@thincoder/core 0.10.4 → 0.10.6

package/agent-tools/subagent.mjs

@@ -1,7 +1,10 @@
 /**
- * subagent.mjs — subagent tool（ONE tool, EIGHT actions + spawn 路径驱动器）。
+ * subagent.mjs — subagent tool（ONE tool, NINE actions + spawn 路径驱动器）。
  * 2026-09-07 token 链终消费制：+action: consume-design（ENGINEERING-MODE.md §2.6 F1——
  * 父侧链终核销消费 designId 槽——执行器 executeConsumeDesignAction 在 subagent-spawn.mjs）。
+ * 2026-10-07 批 ledger-tool（#927 并入）：+action: design-slots（只读清点面——
+ * DESIGN-TOKEN-SETTLEMENT.md §10 F-SL1）+ consume-design 选择器扩展（designIds / expired /
+ * olderThanDays）——实现在 `design-slots.mjs`（subagent-spawn.mjs re-export 保 import 面）。
  *
  * 2026-09-03 拆分轮: subagent.mjs 超 500 硬顶——async 常量、共享 post-spawn 管线
  *（runChildPipeline）与队列/注入/并账机械迁至 ./subagent-async.mjs。execute
@@ -31,6 +34,7 @@ import {
 import { buildChildSignal } from "./async-settle.mjs"
 import { executeStatusAction, executeEscalateAction, executePanelAction, executeObserveAction, executeSendAction } from "./subagent-actions.mjs"
 import { prepareScheduling, buildSpawnChild, executeConsumeDesignAction } from "./subagent-spawn.mjs"
+import { executeDesignSlotsAction } from "./design-slots.mjs"
 import { executeAsyncSpawn } from "./subagent-run.mjs"
 import { ROUND_VALUES } from "./spawn-gates.mjs"
 // #15 描述外置：描述文本单点 = tool-docs/subagent.md（DESC 单解析面，缺档抛错语义不变）
@@ -102,14 +106,16 @@ export function buildSyncStoppedReport(role, capturedOutput, designId) {
 }
 
 /**
- * subagent tool — ONE tool, EIGHT actions (AGENT-LOOP-SUBAGENT.md §6.7 +
+ * subagent tool — ONE tool, NINE actions (AGENT-LOOP-SUBAGENT.md §6.7 +
  * SUBAGENT-OBSERVE-SEND): spawn (default) / status (non-blocking pool query) / observe
  * (inspect a running/queued/done async child's recent activity + current tool — docs/cli/design/TUI.md §6.8) /
  * send (inject a direction into a RUNNING async child — consumed at its next turn
  * boundary as an ordinary instruction — §6.8) / escalate (飞刀 — hand implementation to
  * a stronger model) / cancel (stop ONE background subagent — AGENT-LOOP-SUBAGENT.md §6.7.2) / panel (view + fix
  * the live subagent panel — AGENT-LOOP-SUBAGENT.md §6.7.2) / consume-design (parent-side chain-terminal token
- * consumption — ENGINEERING-MODE.md §2.6, 2026-09-07). The check
+ * consumption — ENGINEERING-MODE.md §2.6, 2026-09-07; selectors designId / designIds / expired /
+ * olderThanDays — DESIGN-TOKEN-SETTLEMENT.md §10 F-SL2) / design-slots (read-only slot inventory —
+ * DESIGN-TOKEN-SETTLEMENT.md §10 F-SL1, 2026-10-07). The check
  * action was deleted (AGENT-LOOP-SUBAGENT.md §6.7.5): async results reach the model only via the auto channel.
  * - action:"spawn" roles: "explore" — read-only tools, search/read/analyze
  *   (suitable for codebase exploration); "coder" — full tool set, self-contained
@@ -130,7 +136,7 @@ export const subagentTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send"], description: "Which action — spawn (default) / status / observe / send / escalate / cancel / panel / consume-design; semantics per action in the tool description." },
+      action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send", "design-slots"], description: "Which action — spawn (default) / status / observe / send / escalate / cancel / panel / consume-design / design-slots; semantics per action in the tool description." },
       view: { type: "boolean", description: "action:'panel' only: true (default) = the live panel blocks as the user sees them; false without freeze = error. Mutually exclusive with freeze (freeze wins)." },
       freeze: { type: "string", description: "action:'panel' only: block key of a digested-stuck block — reclaims it into the conversation; refused for running/done/unknown blocks or a still-pending report; works on the CLI TUI panel and on the desktop renderer panel (live readback of the blocks as the user sees them)." },
       task: { type: "string", description: "Required for action:'spawn' (the self-contained task brief) and action:'escalate' (goal, constraints, entry files, acceptance criteria)." },
@@ -138,8 +144,11 @@ export const subagentTool = {
       role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder", "eng-designer"], description: "The sub-agent role — see the role matrix in the tool description. Exact spelling required. action:'spawn' only (escalate spawns its own expert internally)." },
       model: { type: "string", description: "action:'spawn': provider/model override ('provider:model', a provider, or a model name on the parent's provider) — defaults config.agent.subagentModels[role] → config.agent.subagentModel → the parent's provider; \"default\" inherits. action:'escalate': a consult candidate (default = the first)." },
       designToken: { type: "string", description: "Required when role='eng-coder': the token from advisor(type='design') after the review passed — without it, eng-coder cannot modify files." },
-      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the slot to close out (required to pick between several; the gate refuses to guess)." },
-      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (e.g. <repo>/docs/batches/<batch>-<topic>.md; relative paths resolve against the session cwd first, then candidate project roots — or absolute) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated." },
+      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the single-slot selector (required to pick between several; the gate refuses to guess); see designIds / expired / olderThanDays for batch consumption." },
+      designIds: { type: "array", items: { type: "string" }, description: "action:'consume-design' (batch): an explicit non-empty list of design ids to close out — pass exactly ONE selector per call (designId / designIds / expired / olderThanDays)." },
+      expired: { type: "boolean", description: "action:'consume-design' (batch): true = close out every expired slot (exactly ONE selector per call)." },
+      olderThanDays: { type: "number", description: "action:'consume-design' (batch): close out every slot older than N days (age > N; exactly ONE selector per call)." },
+      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (e.g. <repo>/docs/batches/<batch>-<topic>.md; relative paths resolve against the session cwd first, then candidate project roots — or absolute) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated. role='coder' (normal mode): optional — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file." },
       round: { type: "string", enum: ROUND_VALUES, description: "REQUIRED for role='eng-coder'/'eng-designer': initial (first round for this design) or fix (a correction round reusing the same designId+designToken; docs FIRST). No default — missing = refused." },
       async: { type: "boolean", description: "action:'spawn'/'escalate': default at depth 0 = true (async; the report arrives automatically); depth>0 always sync. async:false forces the blocking flight." },
       files: { type: "array", items: { type: "string" }, description: "action:'spawn' only: the file write-domain this task declares — file-level paths only (cwd-relative or absolute; directories rejected — they bypass the conflict detector). Overlapping-file tasks serialize automatically. Omit = no conflict detection." },
@@ -165,7 +174,7 @@ export const subagentTool = {
       // coder+WRITE child (violates explore-only intent) and status/panel/observe/send
       // have no async pool / panel mirror to query in a child context.
       if ((ctx.depth ?? 0) > 0 && (ctx.agent?._role === "eng-coder" || ctx.agent?._role === "eng-designer")) {
-        throw new Error(`only action:'spawn' (sync explore children) is available inside an ${ctx.agent._role} — escalate/status/cancel/panel/consume-design/observe/send are not`)
+        throw new Error(`only action:'spawn' (sync explore children) is available inside an ${ctx.agent._role} — escalate/status/cancel/panel/consume-design/design-slots/observe/send are not`)
       }
       // AGENT-LOOP-ASYNC-POOL.md §6.8 N3/D-S6 spawn gate (manual tier): auto-turn digests may not spawn —
       // async OR blocking — the digest must stay organize-only. The escalate
@@ -183,6 +192,10 @@ export const subagentTool = {
       // 非只读控制动作——depth-0 + 工程模式限定（本分流已过受限变体门；工程模式门在
       // 执行器内）——planMode 拒绝（dispatch 不豁免）——不入批审批分组（dispatch 免审）。
       if (action === "consume-design") return executeConsumeDesignAction(args, ctx)
+      // 2026-10-07 批 ledger-tool（#927 并入——DESIGN-TOKEN-SETTLEMENT.md §10 F-SL1）：design-slots =
+      // 只读清点（工程模式父侧限定——门在执行器内）；dispatch 分类 = readonly（planMode 放行 /
+      // 免审批 / digest 放行——同 status / observe）。
+      if (action === "design-slots") return executeDesignSlotsAction(args, ctx)
       // AGENT-LOOP-SUBAGENT.md §6.7.2 panel 动作：view（readonly 面——digest 内放行——自省类）与 freeze
       // （控制类——同 cancel——digest 内放行）。深度/门控检查在 executePanelAction 内。
       // CLI-ACTIVITY-DEBLOAT F-3（2026-09-10）接线：executePanelAction 经 ctx.state
@@ -195,7 +208,7 @@ export const subagentTool = {
       // send = 控制类豁免（同 cancel——父回合内显式调用即授权）。深度门在各自执行器内。
       if (action === "observe") return executeObserveAction(args, ctx)
       if (action === "send") return executeSendAction(args, ctx)
-      throw new Error(`Unknown subagent action: ${JSON.stringify(action)}. Valid actions: spawn, status, escalate, cancel, panel, consume-design, observe, send.`)
+      throw new Error(`Unknown subagent action: ${JSON.stringify(action)}. Valid actions: spawn, status, escalate, cancel, panel, consume-design, observe, send, design-slots.`)
     }
 
     const parent = ctx.agent

package/agent-tools/timer.mjs

@@ -1,10 +1,90 @@
-import { TIMER_MAX_PENDING } from "../agent/timers.mjs"
+import { TIMER_MAX_PENDING, TIMER_MIN_EVERY_MS, nextFireAt } from "../agent/timers.mjs"
 import { DESC } from "../tools/shared.mjs"
 
 /**
  * timer tool: set a time budget for thinking before the agent insists on action.
- * 描述面 = `tool-docs/timer.md`（DESC() 加载；机制 = AGENT-LOOP-ASYNC-POOL.md §6.30.3 D-TW8）。
+ * 描述面 = `tool-docs/timer.md`（DESC() 加载；机制 = AGENT-LOOP-ASYNC-POOL.md §6.30.3 D-TW8 ∥ §6.30.18
+ * 四式 ＋ `cancel`/`list`）。取时单点 = 时钟缝 `ctx.now ?? Date.now()`（§6.30.18——生产 `toolCtx`
+ * （`agent/dispatch-run.mjs`）不携 `now` ⇒ 缺省回落 = 现行为零变；单元测试档以假 ctx 直驱）。
  */
+
+/** `at` = 本地刻 `YYYY-MM-DDTHH:MM[:SS]`（严格正则＋日历回读校验——如 `2026-02-30` 拒）。 */
+const AT_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/
+/** `daily` = 本地 `HH:MM`（与核 `DAILY_RE` 同形——工具面 = 唯一生产者，核守卫为防御面）。 */
+const DAILY_RE = /^([01]\d|2[0-3]):([0-5]\d)$/
+
+/** 默认 `message` 槽尾（逐式槽 = §6.30.18 默认表；一次性槽逐字零变）。 */
+const DEFAULT_TAIL = ". Have you tried running the code, adding a console.log, or checking the output? Thinking more without data is guessing."
+
+/** 本地刻 `YYYY-MM-DD HH:MM`（宿主本地时区——回执 ∥ 默认文案槽共用）。 */
+function localText(ms) {
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+/** `at` 解算（宿主本地时区）：形不合 ∥ 日历回读不符（`2026-02-30` ∥ 时位越界等）⇒ `null`。 */
+function atEpochMs(raw) {
+  const m = AT_RE.exec(raw)
+  if (m === null) return null
+  const [y, mo, d, hh, mi, ss] = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6] ?? 0)]
+  const date = new Date(y, mo - 1, d, hh, mi, ss, 0)
+  const back = date.getFullYear() === y && date.getMonth() === mo - 1 && date.getDate() === d
+    && date.getHours() === hh && date.getMinutes() === mi && date.getSeconds() === ss
+  return back ? date.getTime() : null
+}
+
+/** 时长形（§6.30.18）：`<mm:ss>`（< 1h）∥ `<h:mm:ss>`（≥ 1h——h 不补零；与 `/timers` 行同判）。 */
+function durText(ms) {
+  const sec = Math.max(0, Math.ceil(ms / 1000))
+  const h = Math.floor(sec / 3600)
+  const mm = String(Math.floor((sec % 3600) / 60)).padStart(2, "0")
+  const ss = String(sec % 60).padStart(2, "0")
+  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`
+}
+
+/** kind（`list` 行——§6.30.18）：`every <N>s` ∕ `daily <HH:MM>` ∕ `at <刻>`（`at: true` 来源标记位——
+ *  父侧裁定 2026-10-12）；余（一次性）⇒ `one-shot`。 */
+function kindText(t) {
+  const everyMs = t?.everyMs
+  if (typeof everyMs === "number" && Number.isFinite(everyMs) && everyMs > 0) return `every ${everyMs / 1000}s`
+  const daily = t?.daily
+  if (typeof daily === "string" && DAILY_RE.test(daily)) return `daily ${daily}`
+  if (t?.at === true) return `at ${localText(t.expiresAt)}`
+  return "one-shot"
+}
+
+/** `list` 行第三槽：到期未投 ⇒ `due now`；否则 `next <dur>`（剩余现算）。 */
+function nextText(t, now) {
+  const at = Number(t?.expiresAt)
+  return at > now ? `next ${durText(at - now)}` : "due now"
+}
+
+/** `message` 首行（`list` 行第四槽——逐字原样，不截断）。 */
+function firstLine(message) {
+  const text = String(message ?? "")
+  const i = text.indexOf("\n")
+  return i < 0 ? text : text.slice(0, i)
+}
+
+/** `cancel`（§6.30.18）：按 id 移除（`String` 宽松比对）；零匹配 ⇒ 显式抛错（文案含 `list` 指引）。 */
+function cancelAction(agent, wanted) {
+  const pending = agent?._pendingTimers ?? []
+  const idx = pending.findIndex((t) => String(t?.id) === String(wanted))
+  if (idx < 0) {
+    throw new Error(`timer cancel: no pending timer with id ${String(wanted)} — use list: true to see pending timers`)
+  }
+  const [hit] = pending.splice(idx, 1)
+  return `Timer cancelled (id ${String(hit.id)}).`
+}
+
+/** `list`（只读枚举——剩余现算；到期未投 ⇒ `due now` 态照出）。 */
+function listAction(agent, now) {
+  const pending = agent?._pendingTimers ?? []
+  if (pending.length === 0) return "No pending timers."
+  return pending.map((t) => `${String(t.id)} · ${kindText(t)} · ${nextText(t, now)} · ${firstLine(t.message)}`).join("\n")
+}
+
 export const timerTool = {
   name: "timer",
   description: DESC("timer"),
@@ -15,6 +95,26 @@ export const timerTool = {
         type: "number",
         description: "Thinking budget in seconds (default 180). Longer for complex reasoning, shorter for simple tasks.",
       },
+      at: {
+        type: "string",
+        description: 'Fire once at a local clock time, e.g. "2026-10-13T09:00" (YYYY-MM-DDTHH:MM[:SS]). A time already past fires immediately.',
+      },
+      every: {
+        type: "number",
+        description: "Fixed interval in seconds (minimum 60): the first reminder comes N seconds after setting, then every N seconds until cancelled.",
+      },
+      daily: {
+        type: "string",
+        description: 'Local "HH:MM" — repeats every day at that time (a time already past today fires tomorrow), until cancelled.',
+      },
+      cancel: {
+        type: "string",
+        description: "Id of a pending timer to stop (from the set confirmation; see also list).",
+      },
+      list: {
+        type: "boolean",
+        description: "List pending timers with their next due time (read-only).",
+      },
       message: {
         type: "string",
         description: "Custom reminder message to show when time is up. Default: a suggestion to add debug logs or run the code.",
@@ -25,22 +125,96 @@ export const timerTool = {
   readonly: true,
   sideEffectExempt: true,
   execute(args, ctx) {
-    // D15.3#1：默认 180；非法值（非数字/非正数）显式报错——静默 NaN 定时器永不触发的坑
-    const seconds = Number(args.seconds ?? 180)
-    if (!Number.isFinite(seconds) || seconds <= 0) {
-      throw new Error(`timer seconds must be a positive number, got: ${args.seconds}`)
+    const now = ctx.now ?? Date.now() // 时钟缝单点（§6.30.18）：at 过时判定 ∥ every/daily 首投换算 ∥ id 撞号基准
+    const agent = ctx.agent
+
+    // 动作解析 + 互斥（至多一式；cancel ∥ list 与一切设置式互斥、与彼此互斥）——违例显式拒。
+    const hasSeconds = args.seconds !== undefined && args.seconds !== null
+    const hasAt = args.at !== undefined && args.at !== null
+    const hasEvery = args.every !== undefined && args.every !== null
+    const hasDaily = args.daily !== undefined && args.daily !== null
+    const hasCancel = args.cancel !== undefined && args.cancel !== null
+    const wantsList = args.list === true
+    const forms = [hasSeconds && "seconds", hasAt && "at", hasEvery && "every", hasDaily && "daily"].filter((v) => v !== false)
+    if (forms.length > 1 || (forms.length > 0 && (hasCancel || wantsList)) || (hasCancel && wantsList)) {
+      const given = [...forms, hasCancel && "cancel", wantsList && "list"].filter((v) => v !== false).join(" / ")
+      throw new Error(
+        `timer: pass at most one action per call — got ${given}. Forms: { seconds } one-shot ∥ { at: "YYYY-MM-DDTHH:MM[:SS]" } absolute ∥ { every: <seconds ≥ 60> } interval ∥ { daily: "HH:MM" } daily ∥ { cancel: <id> } stop ∥ { list: true } list`,
+      )
+    }
+    if (hasCancel) return cancelAction(agent, args.cancel)
+    if (wantsList) return listAction(agent, now)
+
+    // 逐式解算（校验逐条显式抛错——不静默钳制；拒点时在途表零变动）
+    let form = "seconds"
+    let expiresAt = null
+    let message = null
+    let everySec = null
+    let everyMs = null
+    let oneShotSec = null
+    if (hasAt) {
+      form = "at"
+      const raw = args.at
+      const ts = typeof raw === "string" ? atEpochMs(raw) : null
+      if (ts === null) {
+        throw new Error(`timer at must be a local clock time "YYYY-MM-DDTHH:MM[:SS]" (e.g. "2026-10-13T09:00"), got: ${String(raw)}`)
+      }
+      expiresAt = ts // 过时点 ⇒ 所给刻（delay ≤ 0 ⇒ 即时投递——AC-45① 口径；不重排）
+      message = `⏰ Time's up (at ${localText(ts)})${DEFAULT_TAIL}`
+    } else if (hasEvery) {
+      form = "every"
+      everySec = Number(args.every)
+      if (!Number.isFinite(everySec) || everySec * 1000 < TIMER_MIN_EVERY_MS) {
+        throw new Error(`timer every must be a number of seconds ≥ ${TIMER_MIN_EVERY_MS / 1000} (got: ${String(args.every)})`)
+      }
+      everyMs = everySec * 1000
+      expiresAt = nextFireAt({ everyMs, expiresAt: now }, now) // 首投 = 设时 + N（非立即——防「设置即投」双投感）
+      message = `⏰ Time's up (every ${everySec} seconds)${DEFAULT_TAIL}`
+    } else if (hasDaily) {
+      form = "daily"
+      if (typeof args.daily !== "string" || !DAILY_RE.test(args.daily)) {
+        throw new Error(`timer daily must be a local "HH:MM" time (24-hour, e.g. "09:00"), got: ${String(args.daily)}`)
+      }
+      expiresAt = nextFireAt({ daily: args.daily }, now) // 今日该刻未过 ⇒ 今日；已过 ⇒ 明日（非即时）
+      message = `⏰ Time's up (daily at ${args.daily})${DEFAULT_TAIL}`
+    } else {
+      // D15.3#1：默认 180；非法值（非数字/非正数）显式报错——静默 NaN 定时器永不触发的坑
+      const seconds = Number(args.seconds ?? 180)
+      if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new Error(`timer seconds must be a positive number, got: ${args.seconds}`)
+      }
+      expiresAt = now + seconds * 1000
+      message = `⏰ Time's up (${seconds}s)${DEFAULT_TAIL}`
+      oneShotSec = seconds
     }
-    const expiresAt = Date.now() + seconds * 1000
-    const message = args.message || `⏰ Time's up (${seconds}s). Have you tried running the code, adding a console.log, or checking the output? Thinking more without data is guessing.`
 
     // §6.30.3 门三件②（D-TW6）：在途帽 8——超限显式拒（不静默丢 / 不静默清；形态先例 = 队满
-    // 「拒 + 提示 + 保留」）。拒点时在途表零变动（本次不推入）。
-    const pending = (ctx.agent._pendingTimers = ctx.agent._pendingTimers ?? [])
+    // 「拒 + 提示 + 保留」）。周期项同占坑（1 条 1 坑——§6.30.18 D-TW15；重排净零不触帽）。
+    const pending = (agent._pendingTimers = agent._pendingTimers ?? [])
     if (pending.length >= TIMER_MAX_PENDING) {
       throw new Error(`timer: ${pending.length} timers already pending (max ${TIMER_MAX_PENDING}) — wait for one to fire before setting another`)
     }
-    pending.push({ id: Date.now(), expiresAt, message })
+    // id 唯一化（取消可寻址·§6.30.18）：基准读时钟缝单点，与在途撞号 ⇒ `+1` 递增至空闲（零新载体字段）。
+    let id = now
+    while (pending.some((t) => String(t?.id) === String(id))) id += 1
+    const entry = { id, expiresAt, message: args.message || message }
+    if (everyMs !== null) entry.everyMs = everyMs
+    if (form === "daily") entry.daily = args.daily
+    if (form === "at") entry.at = true // 来源标记位（非载重——时刻单源 = `expiresAt`；父侧裁定 2026-10-12）
+    pending.push(entry)
 
-    return `Timer set for ${seconds} seconds. A reminder will appear when time is up.`
+    if (form === "at") {
+      const when = localText(expiresAt)
+      return expiresAt > now
+        ? `Timer set (id ${id}) for ${when} local. Stop it with cancel id ${id}.`
+        : `Timer set (id ${id}) for ${when} local — that time has passed, so the reminder appears immediately.`
+    }
+    if (form === "every") {
+      return `Repeating timer set (id ${id}): first reminder in ${everySec} seconds, then every ${everySec} seconds. Stop it with cancel id ${id}.`
+    }
+    if (form === "daily") {
+      return `Daily timer set (id ${id}): next reminder ${localText(expiresAt)} local, then every day at ${args.daily}. Stop it with cancel id ${id}.`
+    }
+    return `Timer set for ${oneShotSec} seconds. A reminder will appear when time is up.`
   },
 }

package/agent-tools/zero-write-watch.mjs

@@ -36,7 +36,7 @@ export function advisorAlertText(from, rounds) {
  * 命中 ⇒ `pushChildUpstream({parent, from: _upstream.label, kind: "note", message})` + 置闩。
  * **恒零抛**（兜底捕获兑现——自动源无模型可报错；失败面静默跳过）。
  * @param {object} child 子 agent（eng-coder / eng-designer 形态；`_upstream` 由 spawn 站点装配）。
- * @returns {boolean} 是否命中推送（测试面）。
+ * @returns {boolean} 是否命中推送（测试）。
  */
 export function maybeZeroWriteAlert(child) {
   try {
@@ -65,7 +65,7 @@ export function maybeZeroWriteAlert(child) {
  * @param {object} parent 父 agent（接收方——`pushChildUpstream` 载体吸收同款）。
  * @param {string} from 来源标签（`advisor#<entry id>`）。
  * @param {number} rounds 连续无产出轮数。
- * @returns {boolean} 是否推送成功（测试面）。
+ * @returns {boolean} 是否推送成功（测试）。
  */
 export function pushAdvisorAlert(parent, from, rounds) {
   try {

package/agent-tools.mjs

@@ -13,13 +13,14 @@ export { recentChangesTool } from "./agent-tools/recent-changes.mjs"
 export { timerTool } from "./agent-tools/timer.mjs"
 export { advisorTool } from "./agent-tools/advisor.mjs"
 export { engTool } from "./agent-tools/eng.mjs"
+export { manifestTool } from "./agent-tools/manifest.mjs"
 export { readHistoryTool } from "./agent-tools/read-history.mjs"
 // 模型主动整理上下文（CONTEXT-COMPACTION.md §6.16 · F-CC5）：单工具三操作 stats / prune / compact
 // ——depth-0 段挂载（子代理面裁见 §6.16.6 `family-tools.mjs` `depthOnly`）。
 export { contextTool } from "./agent-tools/context.mjs"
 export { batchTool } from "./agent-tools/batch.mjs"
 // 批次档生命周期工具（BATCH-RECORD §4.3 挂载表——主名 `batch` 单工具四 action：depth-0 主 agent
-// create/close + append §1/§4/§6 + status §1（轮 2 裁定②：§4/§6 状态面走普通文档写）（D-BR18）；
+// create/close + append/status 域随模式（工程面 = append §1/§4/§6 ∥ status §1；普通面 = append §1/§2/§4/§5/§6 ∥ status §1/§2/§5）（轮 2 裁定②：§4/§6 状态面走普通文档写）（D-BR18）；
 // eng 子代理 eng 分支绑定段写入；评审 §3。
 // CORE-UNIFICATION TOOLS #83（统一登记册——VSC `agent-tools/index.mjs:15` 含 consult 家族；
 // CLI 原把 consult 另挂 `agent/setup.mjs:173` ⇒ 归位：登记册即单一来源，装配方只读本档）。

package/agent.mjs

@@ -91,7 +91,7 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
   try {
     return await runTurnLoop(agent, {
       maxTurns, threshold, toolSchemas, toolByName, systemPrompt,
-      depth, signal, autoTurn, streamOutput, consumeInjected, consumeQueuedInput, callbacks, distillSignal,
+      depth, signal, autoTurn, suspDriven, streamOutput, consumeInjected, consumeQueuedInput, callbacks, distillSignal,
     })
   } catch (e) {
     thrownError = e

package/attachments.mjs

@@ -64,7 +64,7 @@ export function isNonVisionModel(model) {
  */
 export function savePastedImages(dataUrls, cwd, { fs } = {}) {
   const list = Array.isArray(dataUrls) ? dataUrls : []
-  if (list.length === 0) return { paths: [], dropped: 0 } // 空表先于缝校验早退（零判据面 —— 缝不检）
+  if (list.length === 0) return { paths: [], dropped: 0 } // 空表先于缝校验早退（零判据 —— 缝不检）
   if (typeof fs?.mkdirSync !== "function" || typeof fs?.writeFileSync !== "function") {
     throw new TypeError("savePastedImages: fs seam missing — inject { mkdirSync, writeFileSync } (the write face must not silently drop every image)")
   }

package/browser/actions.mjs

@@ -0,0 +1,163 @@
+/**
+ * browser/actions.mjs — 基线八动作实现（navigate / snapshot / click / type / evaluate / wait / screenshot / close）
+ * （BROWSER-TOOL.md §2.2 ∥ §2.4；KD-10：click / type 内部选型**不迁** Input 域——对外语义零回归）。
+ *
+ * 会话能力一律经句柄取（`h.call` / `h.evalRaw` / `h.takeSnapshot` / `h.ensureSession` / `h.pageError` /
+ * `h.step` / `h.sleep` …）——本档不 import `session.mjs`（DAG 单向，§5 拆分决定）。
+ * 硬超时（§2.9）：wait 的谓词帽（`timeoutMs`：缺省 30s · 上限 120s）语义零变——动作预算 = 谓词帽 + 15s
+ * 余量（`queue.mjs` 预算表）；轮询循环标 `wait poll` 步名（卡点可诊断——N-BT10）。
+ */
+import { DEFAULT_MAX, clickExpression, typeExpression, truncateText, waitExpression } from "./snapshot.mjs"
+
+export const WAIT_TIMEOUT_DEFAULT = 30_000
+export const WAIT_TIMEOUT_MAX = 120_000
+export const WAIT_POLL_MS = 150
+export const NETWORK_QUIET_MS = 500
+export const MAX_EVAL_CHARS = 8_000
+
+function normalizeHttpUrl(value) {
+  const raw = String(value ?? "")
+  let url
+  try { url = new URL(raw) } catch { url = null }
+  if (!url || (url.protocol !== "http:" && url.protocol !== "https:")) {
+    throw new Error(`navigate requires an http/https url — got "${raw}"`)
+  }
+  return url.toString()
+}
+
+function jsonOf(value) {
+  if (value === undefined) return "undefined"
+  try { return JSON.stringify(value) ?? String(value) }
+  catch { return String(value) }
+}
+
+/** navigate（§2.2）：http/https 限；回执 = `[navigate] <final-url>` + 内联新页快照（省一轮 snapshot）。 */
+async function actNavigate(args, ctx, h) {
+  const url = normalizeHttpUrl(args.url)
+  h.assertHostAllowed(url, ctx) // 静态参数面先检——被拦的 host 不得起浏览器（§3.2「不执行」）
+  await h.ensureSession(args)
+  await h.call("Page.navigate", { url })
+  await h.waitForReady()
+  const snap = await h.takeSnapshot({ max: DEFAULT_MAX })
+  return `[navigate] ${snap.url}\n${snap.text}`
+}
+
+/** snapshot（§2.2）：引用清单（生成 / 复用 / 标记——§2.3）。 */
+async function actSnapshot(args, ctx, h) {
+  await h.ensureSession(args)
+  const snap = await h.takeSnapshot({ selector: args.selector ?? null, max: args.max ?? DEFAULT_MAX })
+  return snap.text
+}
+
+/** click（§2.2）：DOM 级语义激活（`el.click()`——KD-10）；导航判据 = URL 变化 ⇒ `[navigated]` / `[no navigation]`。 */
+async function actClick(args, ctx, h) {
+  await h.ensureSession(args)
+  const info = await h.pageInfo()
+  h.assertHostAllowed(info.url, ctx)
+  const entry = h.resolveRef(args.ref)
+  const res = await h.evalRaw(clickExpression(entry.selector, entry.tag))
+  if (!res?.found || res.tag) throw h.pageError(`ref ${args.ref} is stale (was "${entry.name}") — run snapshot again`)
+  if (res.disabled) throw h.pageError(`ref ${args.ref} is disabled ("${entry.name}")`)
+  const out = [`[click] ${args.ref} "${entry.name}"`]
+  const landed = await h.waitForUrlChange(info.url)
+  if (landed) {
+    await h.waitForReady()
+    const snap = await h.takeSnapshot({ max: DEFAULT_MAX })
+    out.push(`[navigated] ${snap.url}`, snap.text)
+  } else {
+    out.push("[no navigation]")
+  }
+  return out.join("\n")
+}
+
+/** type（§2.2）：写值（原生 value setter + input/change）；password 目标 ⇒ 值不回显（N-BT4）。 */
+async function actType(args, ctx, h) {
+  await h.ensureSession(args)
+  const info = await h.pageInfo()
+  h.assertHostAllowed(info.url, ctx)
+  const entry = h.resolveRef(args.ref)
+  const text = String(args.text)
+  const res = await h.evalRaw(typeExpression(entry.selector, entry.tag, text, args.clear === true))
+  if (!res?.found || res.tag) throw h.pageError(`ref ${args.ref} is stale (was "${entry.name}") — run snapshot again`)
+  if (res.fillable === false) {
+    throw h.pageError(`ref ${args.ref} is not a fillable field ("${entry.name}", <${entry.tag}>) — use snapshot to pick an input/textarea`)
+  }
+  if (res.disabled) throw h.pageError(`ref ${args.ref} is disabled ("${entry.name}")`)
+  return `[type] ${args.ref} "${entry.name}" ← ${text.length} chars${res.password ? " (hidden)" : ""}`
+}
+
+/** evaluate（§2.2）：页面上下文 JS；异常 ⇒ `Error: evaluate failed: <message>`；回执受 8000 字符上限（N-BT3）。 */
+async function actEvaluate(args, ctx, h) {
+  await h.ensureSession(args)
+  const info = await h.pageInfo()
+  h.assertHostAllowed(info.url, ctx)
+  let value
+  try {
+    value = await h.evalRaw(String(args.expression))
+  } catch (e) {
+    if (e?.browserAbort || e?.sessionLost) throw e // 预算中止 / 外部关闭 ⇒ 原样上报（不裹进页面异常句）
+    throw h.pageError(`evaluate failed: ${e?.message ?? e}`)
+  }
+  return `[evaluate @ ${info.url}] ${truncateText(jsonOf(value), MAX_EVAL_CHARS, "narrow the expression")}`
+}
+
+function waitPredicate(args) {
+  if (args.networkIdle === true) return { kind: "networkIdle", value: null, label: "networkIdle" }
+  for (const kind of ["selector", "text", "url"]) {
+    const value = args[kind]
+    if (typeof value === "string" && value !== "") return { kind, value, label: `${kind} ${JSON.stringify(value)}` }
+  }
+  // 工具层已校验互斥（§2.2）——此处兜底（直调会话面时同样不悬挂）
+  throw new Error("wait requires exactly one of selector|text|url|networkIdle")
+}
+
+/** wait（§2.2）：四选一谓词 + 150ms 轮询；networkIdle = 事件在飞归零后静默 500ms。 */
+async function actWait(args, ctx, h) {
+  await h.ensureSession(args)
+  const pred = waitPredicate(args)
+  const wanted = Number(args.timeoutMs)
+  const timeoutMs = Math.max(1, Math.min(Number.isFinite(wanted) && wanted > 0 ? wanted : WAIT_TIMEOUT_DEFAULT, WAIT_TIMEOUT_MAX))
+  const started = Date.now()
+  return h.step("wait poll", async () => {
+    for (;;) {
+      if (pred.kind === "networkIdle") {
+        const net = h.networkState()
+        if (net.inflight.size === 0 && Date.now() - net.lastEventAt >= NETWORK_QUIET_MS) break
+      } else if (await h.evalRaw(waitExpression(pred.kind, pred.value)) === true) break
+      if (Date.now() - started >= timeoutMs) throw h.pageError(`wait timed out after ${timeoutMs}ms (${pred.label})`)
+      await h.sleep(WAIT_POLL_MS)
+    }
+    return `[wait] ${pred.label} — ok after ${Date.now() - started}ms`
+  })
+}
+
+/** screenshot（§2.2）：PNG 落盘返路径（KD-6——模型经 read_image 查看）。 */
+async function actScreenshot(args, ctx, h) {
+  await h.ensureSession(args)
+  const shot = await h.call("Page.captureScreenshot", {
+    format: "png",
+    ...(args.fullPage === true ? { captureBeyondViewport: true } : {}),
+  })
+  if (typeof shot?.data !== "string") throw new Error("screenshot failed: the browser returned no image data")
+  const saved = await h.saveShot(Buffer.from(shot.data, "base64"))
+  return `[screenshot] ${saved.path} (${saved.bytes} bytes)`
+}
+
+/** close（§2.2）：幂等——无会话 ⇒ `[close] no browser session`（成功态）。 */
+async function actClose(args, ctx, h) {
+  if (!h.connection()) return "[close] no browser session"
+  await h.closeSession()
+  return "[close] browser session closed"
+}
+
+/** 基线八动作分发表（会话档并入总表——§5）。 */
+export const ACTIONS = {
+  navigate: actNavigate,
+  snapshot: actSnapshot,
+  click: actClick,
+  type: actType,
+  evaluate: actEvaluate,
+  wait: actWait,
+  screenshot: actScreenshot,
+  close: actClose,
+}