thincoder 0.12.58 → 0.12.60

package/src/agent-tools/consult.mjs

@@ -1,19 +1,35 @@
 /**
  * consult.mjs — multi-model consultation ("会诊", docs/design/CONSULTATION.md). CLI port.
  *
- * Three tools: consult_start (non-blocking spawn) / consult_check (read the next
- * reply as it arrives) / consult_stop (abort the rest). The mechanism does ZERO
- * judging — the main agent reads replies and verifies with its own tools.
+ * Two tools (AGENT-LOOP.md §25 D-R17a — R17, 2026-09-06): consult_start
+ * (non-blocking spawn) / consult_stop (cancel a running session). consult_check
+ * was RETIRED with the digest auto-injection: the mechanism does ZERO judging —
+ * when every model of a session settles (pending 0), the session moves to the
+ * pending single container (`_pendingAsyncResults` +role "consult"——
+ * ASYNC-RESULT-CONTAINER.md D2——升格完整 entry) and the NEXT run start (user turn
+ * or digest auto-turn) injects the full verdict text ("[System reminder:
+ * consultation #id finished — N replies …]" — per-model status annotations on
+ * partial/full failures) for the main agent to judge and act on in the digestion
+ * round. A cancelled session (consult_stop) never reaches the stream.
  *
  * CLI adaptation (vs the VS Code plugin): the child runner is CLI's runAgent
  * (runAgent(child, input, callbacks, opts) — an agent object, not provider+cwd);
  * children are built with createAgent({ role: "consult", readonly tools,
  * CONSULT_BASE overlay }); activity streams to the parent TUI via the relay
- * prefix `consult#<id>/` (same channel subagent uses), not onSubagent/onToolPanel.
+ * prefix `consult#<childRelayN>/` (one per consultant child — the shared subagent
+ * relay channel; the child relay number is NOT the session id — sessions key
+ * their own `_consultIdCounter`), not onSubagent/onToolPanel.
+ * Each child settles its own TUI block with a ⟦ev⟧done event at settle (R17 —
+ * the old in-turn check consumption is gone).
  */
 import { createAgent, runAgent, readonlyToolNames } from "../agent.mjs"
 import { resolveChildProvider } from "./subagent.mjs"
+import { pushReal } from "../context.mjs"
+import { offloadToolResult, escapeXml } from "../agent/helpers.mjs"
+import { logEvent, errText } from "../log.mjs"
 import { makeRelay, wrapChildCallbacks, runWithContinue, ensureChildApiKey, clampEffort } from "../agent/spawn-child.mjs"
+// ASYNC-RESULT-CONTAINER.md D2/D3/D6：pending 单容器停靠 + settle 公共收尾 + child signal 单点
+import { buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
 
 // Named consult defaults (consult P2, 2026-08-30).
 const CONSULT_TIMEOUT_MS = 600_000 // default consult lifecycle timeout
@@ -27,7 +43,7 @@ function consultLabel(m) {
 /** Narrow the configured consultModels pool to a requested subset.
  *  Each selector is "provider:model", a bare provider name, or a bare model name
  *  (case-insensitive). A trailing " (effort)" suffix is tolerated (round2 复核
- *  对齐 escalate.mjs：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
+ *  对齐 escalate 动作（subagent action:"escalate"）：withPool 列表会带 " (high)" 后缀，模型照抄应可匹配).
  *  Returns { models, error } — error set when a selector matches
  *  nothing (surface the typo rather than silently dropping it). Absent/empty selectors
  *  → the full pool. */
@@ -111,13 +127,66 @@ export function makeMainHistoryTool(parentAgent) {
   }
 }
 
-/** Wake every parked consult_check waiter. */
-function wakeWaiters(session) {
-  const w = session.waiters.splice(0)
-  for (const resolve of w) { try { resolve(false) } catch { /* noop */ } }
+/**
+ * Full-session settle routing (R17 — AGENT-LOOP.md §25 D-R17a): a session whose
+ * pending count reached 0 has no more replies coming — the session leaves
+ * `_consultSessions` and, unless it was cancelled (consult_stop / turn-end
+ * abort), moves into the pending single container (`_pendingAsyncResults` +role
+ * "consult"——ASYNC-RESULT-CONTAINER.md D2——升格完整 entry：同 subagent/advisor/
+ * escalate 的 `{id, role, report, done, ...}` 形态）whose report carries the full
+ * per-model verdict text (composed here — all settle states are known,
+ * partial/full failures annotated per model). The entry is injected at the next
+ * run start (user turn or digest auto-turn — agent.mjs); the suspension driver
+ * is woken (settle-event parity with the async pools) so an idle settle still
+ * triggers the digestion round (T-R17j).
+ * D3：公共收尾统一走 settleAsyncEntry 共享 helper（四族同机制）——consult 族参数：
+ * 无池（会话池无条目——settle 即出池）、无 ctx（无 TUI 冻结事件——子块各自 settle 时
+ * 已冻结）、无 onAccounting；helper 按 role "consult" 恒停靠 pending（非挂起期也停靠）。
+ * Cancelled sessions produce no digest (T-R17c).
+ */
+function sessionSettled(agent, session) {
+  agent?._consultSessions?.delete(String(session.id))
+  if (session.stopped) return // cancelled — no digest (T-R17c)
+  const entry = {
+    id: String(session.id),
+    role: "consult",
+    report: composeConsultDigest(session),
+    error: null, done: true, status: "done", cancelled: false,
+    relayPrefix: null, startedAt: null, _settle: null, _settleSeq: 0,
+  }
+  settleAsyncEntry(agent, entry, { pool: null, ctx: null })
+}
+
+/** Digest body for a fully-settled session — title + one annotated line per
+ *  reply (failed replies marked per-model — round2 #7; full text is injected
+ *  verbatim and may be >64K → offloaded with a preview at injection). */
+export function composeConsultDigest(session) {
+  const replies = session.replies ?? []
+  const parts = replies.map((r) =>
+    r.failed
+      ? `- [${r.model}] (failed): ${r.reply}`
+      : `- [${r.model}]: ${r.reply}`)
+  const counts = `${replies.length} of ${session.total} models replied (${session.failed} failed)`
+  return `[System reminder: consultation #${session.id} finished — ${counts}]\n${parts.join("\n")}`
 }
 
-function settleChild(session, id, label, ok, payload) {
+/**
+ * Inject one settled consult family entry into the parent history as a
+ * user-role reminder (run-start injection — agent.mjs; same shape rules as
+ * injectAsyncResult: XML-escaped, >64K offloaded with preview + path). Consumed
+ * = the caller splices the entry out of the pending single container
+ * (_pendingAsyncResults——ASYNC-RESULT-CONTAINER.md D2——role 分发注入）。
+ */
+export async function injectConsultResult(agent, entry) {
+  const body = entry?.report ?? "(no consultation result)"
+  const preview = await offloadToolResult(String(body), `consult-${entry.id ?? "session"}`)
+  pushReal(agent, {
+    role: "user",
+    content: escapeXml(preview),
+  })
+}
+
+function settleChild(agent, session, id, label, ok, payload, emitDone) {
   if (ok) {
     session.received++
     session.replies.push({ model: label, reply: payload })
@@ -128,7 +197,8 @@ function settleChild(session, id, label, ok, payload) {
     session.replies.push({ model: label, reply: `(consultation failed: ${payload})`, failed: true })
   }
   session.pending--
-  wakeWaiters(session)
+  emitDone?.() // per-child TUI block freeze at settle (R17 — child's activity card is done)
+  if (session.pending === 0) sessionSettled(agent, session)
 }
 
 async function runConsultChild(ctx, session, id, m, problem, ctrl) {
@@ -145,6 +215,27 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
   }
   let watchdog = armWatchdog()
   const label = consultLabel(m)
+  // LOGGING（LOGGING.md）：child:*（consult）——logSettle 在函数作用域声明（外层 catch
+  // 覆盖 spawn 前失败路径）；spawn 事件在 relay 建立后发射（logArmed 翻转——provider/
+  // 创建失败 = 从未启动，不落子事件、错误仅经 settleChild 进会话）。
+  let childLogId = null
+  let logT0 = 0
+  let logArmed = false
+  let logDone = false
+  const logSettle = (kind, payload) => {
+    if (!logArmed || logDone || !childLogId) return
+    logDone = true
+    const ms = Date.now() - logT0
+    const base = { role: "consult", id: childLogId, ms }
+    if (kind === "ok" || kind === "partial") logEvent("child:done", { ...base, kind })
+    else logEvent("child:error", { ...base, err: errText(payload, 200) })
+  }
+  // R17: relay prefix assigned before the child runner arms — the per-child TUI
+  // block freeze emits only when a block actually exists (relay established).
+  let relayPrefix = null
+  const settle = (ok, payload) => settleChild(agent, session, id, label, ok, payload, relayPrefix
+    ? () => ctx.callbacks?.onToken?.(`${relayPrefix}⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
+    : null)
   try {
     // Provider resolution: consultModels entries are { provider, model, effort? } — resolve
     // via the subagent's provider resolver ("provider:model" handles cross-provider picks).
@@ -156,9 +247,10 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     }
     // Clamp the pool's effort to the model's reasoningEffortEnum — an out-of-enum
     // value makes provider/core throw on EVERY chat call (candidate dies on takeoff).
-    // Symmetric with escalate.mjs; 2026-08-16 a real consult died on qwen3.8-max
-    // effort "high" (enum is xhigh/medium/low). Out-of-enum: DROP the effort entirely
-    // (the provider preset default may ALSO be out-of-enum for this override model).
+    // Symmetric with the escalate action (subagent action:"escalate"); 2026-08-16
+    // a real consult died on qwen3.8-max effort "high" (enum is xhigh/medium/low).
+    // Out-of-enum: DROP the effort entirely (the provider preset default may ALSO be
+    // out-of-enum for this override model).
     clampEffort(provider, m.model, m.effort)
 
     // Read-only consultant: filter the parent tool set down to readonly tools + main_history.
@@ -182,7 +274,13 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
     // Activity relay via the unified spawn-child pipeline (§7.2 D3): `consult#<subId>/`
     // prefix (same channel subagent uses — parallel consultants stay independent) +
     // onToolOutput passthrough so the consultant's tool output lands in its TUI block.
-    const relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
+    relayPrefix = makeRelay(agent, "consult", ctx.callbacks?.onToken, provider.model ?? "")
+    // LOGGING：arm（spawn 事件——relay 建立后；子内事件归属 _logId）
+    childLogId = relayPrefix.slice(0, -1)
+    child._logId = childLogId
+    logT0 = Date.now()
+    logArmed = true
+    logEvent("child:spawn", { role: "consult", id: childLogId, kind: "consult" })
     const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
     let declined = false // review #1: guard against double-settle when onDeclined fired
 
@@ -215,46 +313,50 @@ async function runConsultChild(ctx, session, id, m, problem, ctrl) {
           },
           onDeclined: (e) => {
             declined = true
-            settleChild(session, id, label, false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
+            settle(false, `turn cap reached (${e.turn} turns) — stopped, diagnosis may be partial`)
+            logSettle("partial", null)
             return undefined
           },
         },
       )
       // Review #1 fix: onDeclined already settled this child as a failed reply —
       // settling again here would push a phantom empty success reply and decrement
-      // `pending` twice (negative pending → consult_check's two exits both
-      // unreachable → permanent block until user abort).
-      if (!declined) settleChild(session, id, label, true, String(result ?? ""))
+      // `pending` twice (negative pending would re-enter the settle routing).
+      if (!declined) {
+        settle(true, String(result ?? ""))
+        logSettle("ok", null)
+      }
     } catch (e) {
       // Runner errors (incl. the watchdog's abort) settle as a failed reply — the
       // continue/declined paths are already handled inside runWithContinue.
       const note = timedOut ? `consultation timed out after ${Math.round(timeoutMs / 60000)}min (agent.consultTimeoutMs)` : e?.message ?? String(e)
-      settleChild(session, id, label, false, note)
+      settle(false, note)
+      logSettle("error", note)
     }
   } catch (e) {
     // Errors BEFORE the runner (provider resolution, createAgent) or a throwing
     // continue-prompt settle as failed replies — the runner's own errors are already
-    // handled inside the loop above.
-    settleChild(session, id, label, false, e?.message ?? String(e))
+    // handled inside the loop above. relayPrefix is null on these paths — no TUI
+    // block was ever opened, so no freeze event is emitted.
+    settle(false, e?.message ?? String(e))
+    logSettle("error", e?.message ?? String(e))
   } finally {
     clearTimeout(watchdog)
   }
 }
 
-/** Turn-end cleanup (called from runAgent's finally): abort every leftover
- *  consultation controller, wake parked waiters, clear the session map. */
+/** Turn-end / session-end abort cleanup (R17 — call sites: the Ctrl+C abort
+ *  branches of finalizeAgentTurn and the suspension driver). Consultation
+ *  sessions are now cross-turn background work (like async subagents): a NORMAL
+ *  turn end keeps them alive — this runs only when the user stops everything:
+ *  every leftover session is marked stopped (its settles never reach the digest
+ *  stream — T-R17c) and its controllers aborted. */
 export function cleanupConsultSessions(agent) {
   for (const s of agent._consultSessions?.values() ?? []) {
     s.stopped = true
     for (const c of s.controllers ?? []) { try { c.abort() } catch { /* already settled */ } }
-    for (const w of s.waiters?.splice(0) ?? []) { try { w() } catch { /* noop */ } }
   }
   agent._consultSessions?.clear()
-  // NOTE: deliberately void (consult P3, 2026-08-30). The { stopped: true } marker
-  // only reaches the TUI via the consult_stop TOOL return (onToolResult freezes
-  // blocks on tool calls) — cleanup runs from the turn finally, where the block
-  // freeze is owned by freezeAllSubTasks + sweepToolBlocks, so a return here is
-  // dead weight. Blocks still get frozen on interrupt via that sweep.
 }
 
 export const consultStartTool = {
@@ -265,8 +367,11 @@ export const consultStartTool = {
     "Start a parallel multi-model consultation (会诊) for a hard problem you are stuck on (repeated failures, no headway). " +
     "Call it directly when the user asks for 会诊 / consult — an explicit user request applies even if you are not 'stuck'. " +
     "Several configured models (agent.consultModels) analyze the same problem INDEPENDENTLY and in parallel. " +
-    "Non-blocking: returns immediately with a consult id. Then call consult_check(id) to read each reply as it " +
-    "arrives, judge/verify it yourself with your own tools, and call consult_stop(id) once a reply is good enough.\n" +
+    "Non-blocking: returns immediately with a consult id; the consultants keep running in the background across turns. " +
+    "When EVERY model has replied (or failed), the full verdict text is delivered to you automatically — as a system " +
+    "reminder at the next run start, or digested on its own while the session is idle — judge and adopt each opinion " +
+    "yourself with your own tools (opinions are suggestions, not gates). To stop a session early (user changed their " +
+    "mind / wants the tokens back), call consult_stop(id) — a stopped session delivers no digest.\n" +
     "Parameters:\n" +
     "- problem (required): a brief — the symptom, what you already tried (failure trail), and entry-point files. " +
     "Do NOT paste raw error logs; consultants pull the main session history themselves via their main_history tool.\n" +
@@ -296,7 +401,7 @@ export const consultStartTool = {
     agent._consultSessions ??= new Map()
     const id = String((agent._consultIdCounter = (agent._consultIdCounter ?? 0) + 1))
     const session = {
-      id, controllers: [], replies: [], pending: 0, waiters: [],
+      id, controllers: [], replies: [], pending: 0,
       failed: 0, terminated: 0, stopped: false, received: 0, total: run.length,
       models: run.map(consultLabel),
     }
@@ -306,100 +411,45 @@ export const consultStartTool = {
       session.pending++
       const ctrl = new AbortController()
       session.controllers.push(ctrl)
-      if (ctx.signal) {
-        if (ctx.signal.aborted) ctrl.abort()
-        else ctx.signal.addEventListener("abort", () => ctrl.abort(), { once: true })
+      // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md D5——consult 补 _sessionSignal
+      // 兜底：挂起会话内的 consult children 持会话 signal，digest 自身 Ctrl+C 不误伤）。
+      const baseSignal = buildChildSignal(agent, ctx)
+      if (baseSignal) {
+        if (baseSignal.aborted) ctrl.abort()
+        else baseSignal.addEventListener("abort", () => ctrl.abort(), { once: true })
       }
-      // Fire and forget — each child settles itself into the session queue.
+      // Fire and forget — each child settles itself into the session; the session
+      // routes to the pending single container when every child has settled (R17).
       runConsultChild(ctx, session, id, m, problem, ctrl)
     }
     return JSON.stringify({ id, models: session.models })
   },
 }
 
-export const consultCheckTool = {
-  name: "consult_check",
-  readonly: true,
-  description:
-    "Read the NEXT consultation reply (whichever model answered first). Blocks until a reply arrives or all models " +
-    "have settled. The reply is raw and unjudged — verify/adopt it with your own tools. When done is true, no more " +
-    "replies are coming.\n" +
-    "Call it ALONE in a turn — do NOT batch it with calls that depend on its reply (readonly tools run in parallel).\n" +
-    "Replies arrive in arrival order: call it repeatedly (n = 1, 2, 3, …) until done is true.\n" +
-    "Parameters:\n" +
-    "- id (required): the consult id from consult_start\n" +
-    "- n (required): the 1-based read number for this consult — pass 1 on the first check, 2 on the next, and so on. It exists so consecutive checks are distinct tool calls (loop detectors) and the transcript reads as a sequence.",
-  parameters: {
-    type: "object",
-    properties: {
-      id: { type: "string", description: "Consult id" },
-      n: { type: "number", description: "1-based read number: 1 for the first check, incrementing with each subsequent check of the same consult" },
-    },
-    required: ["id", "n"],
-  },
-  async execute({ id, n: _n }, ctx) {
-    const s = ctx.agent?._consultSessions?.get(String(id))
-    if (!s) return JSON.stringify({ error: "unknown consult id" })
-    const abortAll = () => { for (const c of s.controllers) { try { c.abort() } catch { /* noop */ } } }
-    if (ctx.signal?.aborted) abortAll()
-
-    for (;;) {
-      if (s.replies.length > 0) {
-        const r = s.replies.shift()
-        return JSON.stringify({
-          reply: r.reply, model: r.model, failedReply: r.failed === true,
-          received: s.received,
-          failed: s.failed,
-          terminated: s.terminated ?? 0, total: s.total,
-          done: s.replies.length === 0 && s.pending === 0,
-        })
-      }
-      if (s.pending === 0) {
-        return JSON.stringify({ done: true, received: s.received, failed: s.failed, total: s.total })
-      }
-      const stopped = await new Promise((resolve) => {
-        function cleanup() {
-          const i = s.waiters.indexOf(w)
-          if (i >= 0) s.waiters.splice(i, 1)
-          ctx.signal?.removeEventListener("abort", onAbort)
-        }
-        function w() { cleanup(); resolve(false) }
-        function onAbort() { cleanup(); abortAll(); resolve(true) }
-        s.waiters.push(w)
-        if (ctx.signal) {
-          if (ctx.signal.aborted) { onAbort(); return }
-          ctx.signal.addEventListener("abort", onAbort, { once: true })
-        }
-      })
-      if (stopped) return JSON.stringify({ done: true, stopped: true, received: s.received, failed: s.failed, total: s.total })
-    }
-  },
-}
-
 export const consultStopTool = {
   name: "consult_stop",
   readonly: false,
   sideEffectExempt: true,
   description:
-    "Terminate the still-running consultations of a session once a reply is good enough — saves tokens and time. " +
-    "Already-answered replies stay available for consult_check.\n" +
+    "Cancel a still-running consultation session (会诊) — the user changed their mind, the problem resolved, or you want the tokens back. " +
+    "Aborts every consultant that is still running; a stopped session delivers NO digest (R17 — its already-collected partial replies are dropped). " +
+    "Sessions that finished on their own are no longer cancellable — their verdict text is delivered automatically.\n" +
+    "Returns JSON {abandoned: <pending count>, cancelled: true} — or {error: \"unknown consult id\"} (already finished/cancelled).\n" +
     "Parameters:\n" +
-    "- id (required): the consult id from consult_start\n" +
-    "- n (required): incrementing call number for this consult (next value after the last consult_check/consult_stop) — keeps repeated calls distinct.",
+    "- id (required): the consult id from consult_start",
   parameters: {
     type: "object",
     properties: {
       id: { type: "string", description: "Consult id" },
-      n: { type: "number", description: "Incrementing call number for this consult (see consult_check)" },
     },
-    required: ["id", "n"],
+    required: ["id"],
   },
-  async execute({ id, n }, ctx) {
+  async execute({ id }, ctx) {
     const s = ctx.agent?._consultSessions?.get(String(id))
     if (!s) return JSON.stringify({ error: "unknown consult id" })
     const abandoned = s.pending
     s.stopped = true
     for (const c of s.controllers) { try { c.abort() } catch { /* already settled */ } }
-    return JSON.stringify({ stopped: n, abandoned })
+    return JSON.stringify({ abandoned, cancelled: true })
   },
 }

package/src/agent-tools/design-token.mjs

@@ -0,0 +1,104 @@
+/**
+ * design-token.mjs — design-token utilities（2026-09-08 自 advisor-async.mjs 提取——
+ * advisor-async 随 DESIGN-TOKEN-SETTLEMENT D1 落盘块再越 500 行硬限；本工具组 verbatim
+ * 迁入，零语义变）。
+ *
+ * 沿革：初由 agent-tools/advisor.mjs 迁至 advisor-async.mjs（sync wrapper 与 async
+ * settle 共享一套实现——无 wrapper↔runner 环），再由 advisor-async.mjs 迁入本文件。
+ * 既有 import 面不变：advisor-async.mjs re-export 全部 7 个导出（advisor.mjs 与测试
+ * 的 import 路径原样保留——advisor.mjs 再转发 validateDesignToken 给 spawn 门禁）。
+ */
+
+import { randomUUID } from "node:crypto"
+import { tokenExpiryMs } from "../token-ttl.mjs"
+
+/**
+ * F2c/F2e (§29.1 2026-09-07): the engine-generated Approved suffix — ONE builder
+ * shared by the sync settle and the async settle (and the prior stores, which
+ * strip it with stripApprovedSuffix — exact-suffix truncation, never a regex
+ * guess, zero collateral). The slot count is a point-in-time snapshot taken at
+ * settle time — the situation at spawn time may differ (F2d backs that up).
+ */
+export function buildApprovedSuffix(designToken, designId, slotCount) {
+  return `Approved. Pass this exact token to eng-coder (designToken parameter): ${designToken}\ndesignId: ${designId} (pass as the designId parameter when spawning eng-coder — optional while this session holds a single design; ${slotCount} approved design slot(s) held as of this approval, and the count may have changed since — with several designs the spawn gate refuses a missing designId and lists the held ids)`
+}
+
+/** F2e (§29.1): strip the engine-generated Approved suffix from a report before
+ *  it becomes a prior — the suffix is deterministic (buildApprovedSuffix), so the
+ *  truncation is exact; a text not ending in it passes through untouched. */
+export function stripApprovedSuffix(text, suffix) {
+  if (typeof text !== "string" || !suffix) return text
+  return text.endsWith(suffix) ? text.slice(0, text.length - suffix.length).trim() : text
+}
+
+const TOKEN_TTL_DEFAULT_MS = 7 * 24 * 3600 * 1000 // 7-day ceiling (v2 2026-08-25)
+
+/** Effective token TTL: config override with runtime validation (timeoutMs precedent). */
+export function effectiveTokenTtlMs(agent) {
+  const cfg = agent?.config?.agent?.engTokenTtlMs
+  return (Number.isFinite(cfg) && cfg > 0) ? cfg : TOKEN_TTL_DEFAULT_MS
+}
+
+/** Mint an unsigned design token with expiration (2026-09-06: HMAC layer removed —
+ *  the token is a FLOW credential: uuid:expiresAt, exact slot match + TTL only). */
+export function generateDesignToken(agent) {
+  const uuid = randomUUID()
+  const expiresAt = Math.floor(Date.now() + effectiveTokenTtlMs(agent))
+  return `${uuid}:${expiresAt}`
+}
+
+/** Validate a design token: format + expiration — ALL fail-closed (v2 2026-08-25).
+ *  R16: format/expiry semantics live in token-ttl.mjs (tokenExpiryMs — single source
+ *  shared with restore filtering / enter cleanup / spawn-gate slot deletion — D-R16b). */
+export function validateDesignToken(token) {
+  const expiry = tokenExpiryMs(token)
+  return expiry !== null && expiry >= Date.now()
+}
+
+/** Build a [DESIGN-TOKEN:...] regex matching the FULL token (uuid:expiresAt). */
+export function makeDesignTokenRegex(token, flags = "") {
+  const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return new RegExp(
+    `(?:^|\\s|\`|\\*)\\[DESIGN-TOKEN:\\s*${escaped}\\s*\\](?:\\s|$|\`|\\*)`,
+    flags + "ms"
+  )
+}
+
+/**
+ * Shared design-review settlement (sync wrapper + async settle): the token echo
+ * IS the verdict — the advisor echoes it only on approval. On echo: slot the
+ * token under designId (+ eng-coder gate flag; single-value mirror retired per
+ * DESIGN-TOKEN-SETTLEMENT D3) and return
+ * the clean output with the Approved suffix; the review instance CLOSES (a
+ * later review of the same doc-set starts a fresh full review). On non-echo:
+ * strip every dead token occurrence and return the findings text — slots stay
+ * untouched (方案 ②: a failed re-review revokes nothing).
+ * @returns {{passed: boolean, output: string}}
+ */
+export function settleDesignReview(agent, run, designToken, rawResult) {
+  if (!designToken || typeof rawResult !== "string") {
+    return { passed: false, output: rawResult ?? "" }
+  }
+  const tokenPattern = makeDesignTokenRegex(designToken)
+  if (!tokenPattern.test(rawResult)) {
+    const stripped = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+    return { passed: false, output: stripped || "Advisor: design review did not pass." }
+  }
+  // Echoed the token → review passed. Issue it to the parent for eng-coder.
+  agent._engDesignTokens ??= new Map()
+  agent._engDesignTokens.set(run.designId, designToken)
+  // DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `_engDesignToken` 退役——
+  // 只写多槽 Map（AC3 零镜像写）；settle 落盘由调用方（settleAdvisorRun）当场做。
+  // Unlock the dispatch design gate for eng-coder SELF-review (defense-in-depth —
+  // see the sync wrapper's note: unreachable today, kept for parity).
+  if (agent._role === "eng-coder") agent._engDesignReviewed = true
+  run.open = false // approval closes this doc-set instance — next review is fresh
+  const clean = rawResult.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+  // F2c (§29.1): id echo + omission guidance + point-in-time slot snapshot — the
+  // same suffix the F2e prior stores strip with (stored for the exact truncation).
+  run.approvedSuffix = buildApprovedSuffix(designToken, run.designId, agent._engDesignTokens.size)
+  return {
+    passed: true,
+    output: `${clean}\n\n${run.approvedSuffix}`,
+  }
+}

package/src/agent-tools/eng.mjs

@@ -1,14 +1,24 @@
 /**
  * eng tool: enter/exit engineering mode.
  * In engineering mode the agent follows design-before-code methodology.
- * Toggled here at session level; persisted by /eng.
+ * Toggled here at session level (in-memory flag; the session slot is the sole authority —
+ * saveSession round-trips it at turn end; /eng writes the slot directly). The old ctx
+ * state-persist hook was removed 2026-09-08 (ENG-SESSION-PROVIDER-CLEANUP D1.2): no
+ * provider existed and its legacy payload keys were never read by applySession.
+ * R16 (2026-09-06): design tokens are session-level flow credentials — mode toggles
+ * do NOT clear them (ON→OFF keeps, OFF→ON does not require a fresh review); only TTL
+ * expiry cleans tokens, at three points: restore filtering (session.mjs applySession) /
+ * eng enter expired cleanup (below + cmd-eng ON) / spawn-gate expired rejection
+ * (subagent-spawn.mjs). See docs/design/ENG-TOKEN-BINDING-TUNING.md §5/§5.1 (F-R16).
  */
 import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
+import { purgeExpiredDesignTokens } from "../token-ttl.mjs"
 
 export const engTool = {
   name: "eng",
   description:
-    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents.",
+    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents. " +
+    "Returns the mode state — 'Engineering mode activated/exited' (an already-active state is acknowledged).",
   parameters: {
     type: "object",
     properties: {
@@ -21,50 +31,36 @@ export const engTool = {
     ctx.agent.config.agent ??= {}
     if (args.action === "exit") {
       ctx.agent.config.agent.engineering = false
-      ctx.agent._engDesignToken = null   // stale token from prior design review invalidated
-      ctx.agent._engDesignTokens = new Map() // multi-design slots die with the mode (2026-09-01 fix #2)
-      ctx.agent._engDesignReviewed = false // reset gate state
+      // R16 (F-R16a): OFF 不清 token——有效 token 跨模式存活（设计评审过的产物不因
+      // 开关重复烧）。过期清理跑在另外三处（恢复过滤 / 开模式 / spawn 门禁拒）。
       ctx.agent._advisorRound = 0          // reset convergence budget
+      ctx.agent._advisorRuns = new Map()   // §24 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._touchedFiles = []         // clear mutation tracking
       ctx.agent._lastEngState = false
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_OFF_REMINDER)
-      // 持久化工程模式状态到会话
-      if (ctx.persistState) {
-        await ctx.persistState({
-          engineering: false,
-          engDesignToken: null,
-          engDesignReviewed: false,
-          advisorRound: 0,
-          touchedFiles: []
-        })
-      }
       return "Engineering mode exited. Standard discipline now applies. You may edit files directly."
     }
     if (args.action === "enter") {
-      // Idempotent enter (v2 2026-08-25): already in engineering mode → no-op. The old
-      // unconditional token clear killed standing design tokens on a redundant defensive
-      // eng(enter) — only a real off→on transition requires a fresh design review.
+      // Idempotent enter (v2 2026-08-25): already in engineering mode → pure no-op
+      // (cleanup only runs on a real off→on transition — T-R16c precondition: first
+      // exit/OFF, then enter; an already-on enter must not touch tokens at all).
       if (ctx.agent.config.agent.engineering) {
         return "Engineering mode already active. Existing design tokens stay valid."
       }
       ctx.agent.config.agent.engineering = true
-      ctx.agent._engDesignToken = null   // off→on transition requires a fresh design review
-      ctx.agent._engDesignTokens = new Map() // multi-design slots die with the mode (2026-09-01 fix #2)
+      // R16 (F-R16b ②): off→on 不重评——只清过期 token（用户裁定"打开工程模式时
+      // 应该清理"），有效 token 原样保留——遍历 Map 删过期，返回文案含清理个数。
+      const cleared = purgeExpiredDesignTokens(ctx.agent)
+      ctx.agent._advisorRuns = new Map() // §24 D-24b: per-review instances die with the mode (fresh cycles)
       ctx.agent._lastEngState = true
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
       ctx.agent._pendingReminders.push(ENG_ON_REMINDER)
-      // 持久化工程模式状态到会话
-      if (ctx.persistState) {
-        await ctx.persistState({
-          engineering: true,
-          engDesignToken: null,
-          engDesignReviewed: false,
-          advisorRound: 0,
-          touchedFiles: []
-        })
+      let msg = "Engineering mode activated. Design-before-code enforced: write a design document in docs/, run advisor with type='design', get user approval, then implement via eng-coder subagents."
+      if (cleared > 0) {
+        msg += ` Cleared ${cleared} expired design token${cleared === 1 ? "" : "s"} — 清 ${cleared} 个过期 token，有效 token 保留（TTL 内不重评）。`
       }
-      return "Engineering mode activated. Design-before-code enforced: write a design document in docs/, run advisor with type='design', get user approval, then implement via eng-coder subagents."
+      return msg
     }
     return "Invalid action: expected 'enter' or 'exit'"
   },