thincoder 0.12.54 → 0.12.59

package/src/provider/core.mjs

@@ -4,9 +4,11 @@
  * SSE parsing → provider/sse.mjs
  */
 
-import { specForModel, resolveEnableThinking } from "../config.mjs"
+import { providerSpec, resolveEnableThinking } from "../config.mjs"
 import { proxyFetch } from "../proxy.mjs"
-import { escapeMessages } from "../escape.mjs"
+import { escapeMessages, stripLocalMessageFields } from "../escape.mjs"
+import { logEvent, errText, classifyErr, headText } from "../log.mjs"
+import { recordChatTrace } from "../traces/trace-store.mjs"
 import { readSSE } from "./sse.mjs"
 export { readSSE } from "./sse.mjs"
 import {
@@ -15,10 +17,9 @@ import {
   estimateRequestTokens, rateGate, recordRate,
 } from "./rate.mjs"
 
-const FETCH_TIMEOUT_MS = 600_000
+// 2026-09-01：FETCH_TIMEOUT_MS 常量退役（绝对墙钟语义废除）——fetchTimeoutMs 现为每调用从 provider 读（config 归一化），见 effectiveFetchTimeoutMs。
 
-/** 可中断 sleep（2026-08-31 会诊 #5）：退避/Retry-After/overload 等待期间 Ctrl+C 应
- *  立即生效——原来最长睡 60s 无响应。内部走 _rateHooks.sleep（测试替换点）。 */
+/** 可中断 sleep（会诊 #5）：退避/Retry-After/overload 等待期 Ctrl+C 立即生效；内部走 _rateHooks.sleep（测试替换点） */
 function abortDOM(signal) {
   const e = new DOMException("The operation was aborted", "AbortError")
   e.reason = signal.reason
@@ -61,11 +62,71 @@ export function createProvider(config) {
 }
 
 /** Send a streaming chat completion request with automatic continuation on truncation */
-export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules, firedPatterns, toolChoice, parallelToolCalls }) {
+// 2026-09-01 根因修复：600s 绝对墙钟曾腰斩长上下文子代理（eng-coder TTFB>10min 即死）——TTFB 阶段改用
+// fetchTimeoutMs（默认 600s，agent.fetchTimeoutMs 可配），body 阶段 idle 超时（FETCH_BODY_IDLE_MS，无新数据才断）。
+const FETCH_BODY_IDLE_MS = 120_000
+/** §14.2 设计值：prefix 续写只保留最近 8 条非工具文本（截断点语境足够，N 以测试锁定） */
+const PREFIX_CONTINUATION_KEEP = 8
+
+/** 2026-09-01：响应头阶段超时（默认 600s，agent.fetchTimeoutMs 可配）——anthropic/responses transport 共用 */
+export function effectiveFetchTimeoutMs(provider) {
+  return Number.isFinite(provider?.fetchTimeoutMs) && provider.fetchTimeoutMs > 0 ? provider.fetchTimeoutMs : 600_000
+}
+
+export async function chat(provider, opts = {}) {
+  // LOGGING（docs/design/LOGGING.md）：llm:* 事件统一在此落点——所有 chat 调用
+  // （主回合/消化轮/compress/distill/advisor/子代理/auto-think/consult）都经本函数，
+  // 格式分派（anthropic/google/responses）在内部——单点覆盖即 llm:* 全覆盖。
+  // 续写/重试各自为独立 HTTP 请求——续写递归（下方 chatImpl 内）会再包一层（嵌套
+  // llm:start/done 对——每请求一事件）；重试在 requestWithRetry 内部不可见。
+  // §18.6 完整轨迹存档（AGENT-LOOP.md §18.6 N-TR2——权威句 D-TR1）：采集点唯一=
+  // 本函数出口——所有 chat 调用（主回合/消化轮/compress/distill/advisor/子代理/
+  // auto-think/consult）都经本函数；续写/重试在出口已合并——reasoning 全量才完整。
+  const logCtx = opts.logCtx ?? {}
+  const t0 = Date.now()
+  const pname = provider?.name ?? provider?.model ?? "unknown"
+  logEvent("llm:start", { provider: pname, model: provider?.model ?? "", stage: logCtx.stage, turn: logCtx.turn, auto: logCtx.auto === true, child: logCtx.child })
+  try {
+    const result = await chatImpl(provider, opts)
+    logEvent("llm:done", {
+      provider: pname, model: provider?.model ?? "",
+      ms: Date.now() - t0,
+      stage: logCtx.stage, turn: logCtx.turn, auto: logCtx.auto === true, child: logCtx.child,
+      head: headText(result?.content ?? "", 300, { paragraph: true }),
+      len: String(result?.content ?? "").length,
+      finish: result?.finishReason ?? null,
+      tools: Array.isArray(result?.toolCalls) ? result.toolCalls.length : 0,
+    })
+    // §18.6 D-TR1/D-TR5：出口收集——成功路径轨迹（含 content/reasoning 全文/toolCalls）
+    recordChatTrace(provider, opts, result, null)
+    return result
+  } catch (e) {
+    logEvent("llm:error", {
+      provider: pname, model: provider?.model ?? "",
+      ms: Date.now() - t0,
+      stage: logCtx.stage, turn: logCtx.turn, auto: logCtx.auto === true, child: logCtx.child,
+      err: errText(e, 200),
+      kind: classifyErr(e, opts.signal),
+    })
+    // §18.6 D-TR5：失败路径也落盘——error（errText 截断 + 类别）+ finishReason:null
+    recordChatTrace(provider, opts, null, e)
+    throw e
+  }
+}
+
+/** chat 本体（LOG(LLM) 事件包装之外——见上方 chat 包装器）。 */
+async function chatImpl(provider, { messages, tools, onToken, onReasoning, onWait, signal, streamRules, firedPatterns, toolChoice, parallelToolCalls, logCtx }) {
   // Sanitize BEFORE format dispatch — image poisoning bricks anthropic/google sessions
   // the same way it bricks OpenAI-format ones (all raster-only).
-  const spec = specForModel(provider.model)
+  // providerSpec: spec with the provider-level context override (PROVIDER.md §15) — the
+  // window/clamping logic below reads the overridden value where it matters.
+  const spec = providerSpec(provider)
   messages = stripImagesForTextModel(messages, spec)
+  // SESSION.md §9 T-S3: local-only message fields (ts/transient) never reach the wire.
+  // Stripped BEFORE format dispatch — anthropic/responses transports pass whole message
+  // objects through verbatim (only the OpenAI path ran escapeMessages). Copy-on-write:
+  // history keeps the fields, the request never sees them.
+  messages = stripLocalMessageFields(messages)
   const _debugBeforeLen = process.env.THIN_DEBUG_BODY ? JSON.stringify(messages).length : 0
 
   // Format dispatch: delegate to non-OpenAI transports
@@ -190,24 +251,28 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
 
   if (!spec.partialMode && !spec.prefixMode) return result
   for (let n = 0; result.finishReason === "length" && result.content && n < MAX_CONTINUATIONS; n++) {
-    const continued = await chat(spec.prefixMode ? { ...provider, baseURL: betaBaseURL(provider.baseURL) } : provider, {
-      messages: [
-        ...messages,
-        spec.partialMode
-          ? {
-              role: "assistant",
-              content: result.content,
-              partial: true,
-              ...(result.reasoning ? { reasoning_content: result.reasoning } : {}),
-            }
-          : { role: "assistant", content: result.content, prefix: true, ...(result.reasoning ? { reasoning_content: result.reasoning } : {}) },
-      ],
-      tools,
-      onToken,
-      onReasoning,
-      onWait,
-      signal,
-    })
+    let continued
+    try {
+      continued = await chat(spec.prefixMode ? { ...provider, baseURL: betaBaseURL(provider.baseURL) } : provider, {
+        messages: buildContinuationMessages(messages, result, spec),
+        tools,
+        onToken,
+        onReasoning,
+        onWait,
+        signal,
+        // §18.6：续写是同一逻辑调用的子请求——logCtx 原样透传（元数据与门控
+        // traces.enabled 对续写调用同样生效，不在出口静默越过开关）
+        // fix round1（D-TR1）：续写子请求标记 isContinuation:true（T-TR14——true =
+        // 该调用是续写链的一环；外层新调用 false）——分析"纠结"时区分续写/重试链。
+        logCtx: { ...logCtx, isContinuation: true },
+      })
+    } catch (error) {
+      // §14.3 失败可见性：续写失败注入 _warnings（agent 机读线可见）不整轮飞出；AbortError 用户中断透传
+      if (error?.name === "AbortError") throw error
+      result._warnings ??= []
+      result._warnings.push({ name: "continuation-failed", message: `output continuation failed: ${error.message}` })
+      break
+    }
     result.content += continued.content
     result.reasoning += continued.reasoning ?? ""
     mergeRetryToolCalls(result, continued.toolCalls)
@@ -226,6 +291,14 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
   return result
 }
 
+/** 续写消息构造（§14.3）：prefix 精简历史（§14.2——deepseek /beta 网关对含工具链历史必 400，真机矩阵）；partial 保持现状 */
+export function buildContinuationMessages(messages, result, spec) {
+  const tail = (extra) => ({ role: "assistant", content: result.content, ...extra, ...(result.reasoning ? { reasoning_content: result.reasoning } : {}) })
+  if (!spec.prefixMode) return [...messages, tail({ partial: true })]
+  const slim = messages.filter((m) => m.role !== "tool" && !(m.role === "assistant" && m.tool_calls?.length))
+  return [...slim.filter((m) => m.role === "system"), ...slim.filter((m) => m.role !== "system").slice(-PREFIX_CONTINUATION_KEEP), tail({ prefix: true })]
+}
+
 /**
  * Replace image parts with text placeholders when they would 400 the request:
  * - the model has no vision support at all (history may carry image_url parts from a
@@ -347,11 +420,14 @@ async function requestWithRetry(provider, body, signal, onWait) {
           Authorization: `Bearer ${provider.apiKey}`,
         },
         body: JSON.stringify(body),
-        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)]) : AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        // 2026-09-01 根因修复：原 600s 绝对墙钟会腰斩长上下文子代理（TTFB/首 token >10min 即死）。
+        // 拆分语义：响应头阶段仍用 fetchTimeoutMs（600s，覆盖网关排队）；body 阶段由读侧 idle 超时管
+        // （sse.mjs readIdleMs——无新数据才断）。signal 只保留用户取消链，不再叠加绝对墙钟。
+        signal,
         // 2026-08-31 会诊 #4：代理路径响应头超时对齐直连语义（原 15s 与直连 600s 割裂，
         // DeepSeek 排队 TTFB>15s 即误报）— 仅 _ 前缀内部字段，proxyFetch 消费
-        _headerTimeoutMs: FETCH_TIMEOUT_MS,
-        _bodyIdleMs: 120_000,
+        _headerTimeoutMs: effectiveFetchTimeoutMs(provider),
+        _bodyIdleMs: FETCH_BODY_IDLE_MS,
       }
       response = provider.proxyUri
         ? await proxyFetch(url, opts, provider.proxyUri)

package/src/provider/google.mjs

@@ -6,6 +6,7 @@
 
 import { proxyFetch } from "../proxy.mjs"
 import { requestWithRetry } from "./retry.mjs"
+import { effectiveFetchTimeoutMs } from "./core.mjs"
 
 /** OpenAI 语义 tool_choice → Gemini FunctionCallingConfig（2026-08-31 能力层）。 */
 function mapFunctionCallingConfig(choice) {
@@ -100,7 +101,6 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
     body.toolConfig = { functionCallingConfig: mapFunctionCallingConfig(toolChoice) }
   }
 
-  const FETCH_TIMEOUT_MS = 600_000
   // Gemini uses API key as query parameter
   const url = `${provider.baseURL}/models/${provider.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(provider.apiKey)}`
 
@@ -118,10 +118,9 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
-      signal: signal
-        ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
-        : AbortSignal.timeout(FETCH_TIMEOUT_MS),
-      _headerTimeoutMs: FETCH_TIMEOUT_MS,
+      // 2026-09-01：同 core.mjs——绝对墙钟废除；响应头阶段 fetchTimeoutMs（600s 默认），body 阶段读侧 idle 管
+      signal,
+      _headerTimeoutMs: effectiveFetchTimeoutMs(provider),
       _bodyIdleMs: 120_000,
     }, provider.proxyUri),
     { signal, onWait, buildMessage: (status, text) => `Gemini API error ${status}: ${text}` },
@@ -194,32 +193,66 @@ async function parseGeminiStream(response, { onToken, onReasoning, signal }) {
   }
 
   if (!response.body) throw new Error("No stream response body")
-  for await (const chunk of response.body) {
-    if (signal?.aborted) {
-      const e = new DOMException("Aborted", "AbortError")
-      e.reason = signal.reason
-      throw e
-    }
-    buffer += decoder.decode(chunk, { stream: true })
-    // BOM 剥除（会诊 #12）：首个 chunk 可能带 \uFEFF，否则首个 data 事件静默丢失
-    if (buffer.charCodeAt(0) === 0xfeff) buffer = buffer.slice(1)
-    const lines = buffer.split("\n")
-    buffer = lines.pop()
+  // 2026-09-01 读侧 idle 超时（同 sse.mjs）：body 有数据流动即不超时；连续 120s 无新 chunk 判死
+  const READ_IDLE_MS = 120_000
+  let idleTimer = null
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer)
+    idleTimer = setTimeout(() => {
+      try { response.body?.destroy(new Error(`SSE idle timeout: no data for ${READ_IDLE_MS / 1000}s`)) } catch { /* already gone */ }
+    }, READ_IDLE_MS)
+    idleTimer.unref?.()
+  }
+  armIdle()
+  try {
+    for await (const chunk of response.body) {
+      armIdle()
+      if (signal?.aborted) {
+        const e = new DOMException("Aborted", "AbortError")
+        e.reason = signal.reason
+        throw e
+      }
+      buffer += decoder.decode(chunk, { stream: true })
+      // BOM 剥除（会诊 #12）：首个 chunk 可能带 \uFEFF，否则首个 data 事件静默丢失
+      if (buffer.charCodeAt(0) === 0xfeff) buffer = buffer.slice(1)
+      const lines = buffer.split("\n")
+      buffer = lines.pop()
 
-    for (const line of lines) {
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue
+        const data = line.slice(5).trim()
+        if (!data || data === "[DONE]") continue
+        processData(data)
+      }
+    }
+    buffer += decoder.decode()
+    for (const line of buffer.split("\n")) {
       if (!line.startsWith("data:")) continue
       const data = line.slice(5).trim()
       if (!data || data === "[DONE]") continue
       processData(data)
     }
-  }
-  buffer += decoder.decode()
-  for (const line of buffer.split("\n")) {
-    if (!line.startsWith("data:")) continue
-    const data = line.slice(5).trim()
-    if (!data || data === "[DONE]") continue
-    processData(data)
+  } catch (e) {
+    if (idleTimer) clearTimeout(idleTimer)
+    if (e.name === "AbortError" && signal?.reason?.interrupt) {
+      result.interrupted = true
+      result.interruptMessage = signal.reason.message
+      return result
+    }
+    if (hasPartial(e)) {
+      result.partial = true
+      result.networkError = e.message ?? String(e)
+      return result
+    }
+    throw e
+  } finally {
+    if (idleTimer) clearTimeout(idleTimer)
   }
 
   return result
 }
+
+/** google.mjs 无 hasChoices 追踪——只有流中途死且已有内容才标 partial（同 sse.mjs 语义的简化版） */
+function hasPartial(e) {
+  return /ECONNRESET|terminated|idle timeout|network/i.test(e?.message ?? "")
+}

package/src/provider/normalize.mjs

@@ -5,8 +5,8 @@
  * pure functions sanitize the message array right before it hits the wire;
  * no dependency on chat()/retry logic. core.mjs re-exports them so
  * provider/index.mjs and tool-pairing.test.mjs keep their import paths.
+ * The caller passes the spec (providerSpec from core.mjs — provider-aware).
  */
-import { specForModel } from "../config.mjs"
 
 const RASTER_IMAGE_URL = /^data:image\/(png|jpe?g|gif|webp);base64,/
 

package/src/provider/rate.mjs

@@ -3,8 +3,6 @@
  * Sliding-window accounting; pre-check budget before sending requests; sleep until window frees space when over budget.
  */
 
-import { specForModel } from "../config.mjs"
-
 export const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504])
 export const MAX_RETRIES = 3
 export const MAX_CONTINUATIONS = 3

package/src/provider/responses.mjs

@@ -12,11 +12,12 @@
  * 没有 "data: [DONE]"。
  */
 import { specForModel, isBailianHost } from "../config.mjs"
+import { effectiveFetchTimeoutMs } from "./core.mjs"
 import { proxyFetch } from "../proxy.mjs"
 import { requestWithRetry } from "./retry.mjs"
 import { rateGate, recordRate, estimateRequestTokens } from "./rate.mjs"
 
-const FETCH_TIMEOUT_MS = 600_000
+// 2026-09-01：FETCH_TIMEOUT_MS 常量退役（绝对墙钟废除）——经 core.mjs effectiveFetchTimeoutMs 共用
 
 /** 白名单：已实证 previous_response_id 的官方端（2026-08-31 真机验证：
  *  百炼 store:true 全链路 ✅；GLM（open.bigmodel.cn/api/v1）store:true 全链路 ✅）。 */
@@ -430,10 +431,8 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` },
         body: JSON.stringify(body),
-        signal: signal
-          ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
-          : AbortSignal.timeout(FETCH_TIMEOUT_MS),
-        _headerTimeoutMs: FETCH_TIMEOUT_MS,
+        signal,
+          _headerTimeoutMs: effectiveFetchTimeoutMs(provider),
         _bodyIdleMs: 120_000,
       }, provider.proxyUri),
       { signal, onWait, buildMessage: (status, text) => `Responses API error ${status}: ${text}` },
@@ -451,10 +450,8 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` },
         body: JSON.stringify(fullBody),
-        signal: signal
-          ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
-          : AbortSignal.timeout(FETCH_TIMEOUT_MS),
-        _headerTimeoutMs: FETCH_TIMEOUT_MS,
+        signal,
+          _headerTimeoutMs: effectiveFetchTimeoutMs(provider),
         _bodyIdleMs: 120_000,
       }, provider.proxyUri),
       { signal, onWait, buildMessage: (status, text) => `Responses API error ${status}: ${text}` },
@@ -471,10 +468,8 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, on
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${provider.apiKey}` },
         body: JSON.stringify(fresh2.body),
-        signal: signal
-          ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
-          : AbortSignal.timeout(FETCH_TIMEOUT_MS),
-        _headerTimeoutMs: FETCH_TIMEOUT_MS,
+        signal,
+          _headerTimeoutMs: effectiveFetchTimeoutMs(provider),
         _bodyIdleMs: 120_000,
       }, provider.proxyUri),
       { signal, onWait, buildMessage: (status, text) => `Responses API error ${status}: ${text}` },

package/src/provider/sse.mjs

@@ -165,8 +165,23 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
   }
 
   if (!response.body) throw new Error("No stream response body")
+  // 2026-09-01 读侧 idle 超时（根因修复）：原实现靠 fetch 层的 600s 绝对墙钟兜底——长上下文子代理
+  // 单次生成（或上游排队）超 10 分钟即被腰斩（"The operation was aborted due to timeout" 直透）。
+  // 现改为：读侧空闲超时——body 只要有数据流动就永不超时，连续 READ_IDLE_MS 无新 chunk 才判死。
+  // 直连 fetch 与 proxyFetch 统一走这里（proxy 的 _bodyIdleMs 语义与之等价，双保险）。
+  const READ_IDLE_MS = 120_000
+  let idleTimer = null
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer)
+    idleTimer = setTimeout(() => {
+      try { response.body?.destroy(new Error(`SSE idle timeout: no data for ${READ_IDLE_MS / 1000}s`)) } catch { /* already gone */ }
+    }, READ_IDLE_MS)
+    idleTimer.unref?.()
+  }
+  armIdle()
   try {
     for await (const chunk of response.body) {
+      armIdle()
       if (signal?.aborted) {
         const e = new DOMException("The operation was aborted", "AbortError")
         e.reason = signal.reason
@@ -189,6 +204,7 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
               result.ruleTriggered = true
               result.ruleMessage = rule.message
               result.ruleName = rule.name
+              if (idleTimer) clearTimeout(idleTimer)
               return result
             }
             const existing = result._warnings ??= []
@@ -202,9 +218,11 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
     buffer += decoder.decode()
     processLines(buffer.split("\n"))
   } catch (e) {
+    if (idleTimer) clearTimeout(idleTimer)
     if (e.name === "AbortError" && signal?.reason?.interrupt) {
       result.interrupted = true
       result.interruptMessage = signal.reason.message
+      if (idleTimer) clearTimeout(idleTimer)
       return result
     }
     // 2026-08-31 会诊 #2（流中断丢全部已收内容）：网络级失败（ECONNRESET / 半截 EOF /
@@ -223,6 +241,8 @@ export async function readSSE(response, { onToken, onReasoning, rules, signal, f
     throw e
   }
 
+  if (idleTimer) clearTimeout(idleTimer)
+
   if (!hasChoices) {
     // Stream started as SSE but no choices were parsed — unusual. Include status for debugging.
     const raw = buffer.trim()

package/src/session.mjs

@@ -116,6 +116,12 @@ export function saveSession(agent) {
     autoApprove: agent.autoApprove ?? false,
     engineering: agent.config?.agent?.engineering ?? false,
     engDesignToken: agent._engDesignToken ?? null,
+    // Multi-design slots ride the same round-trip (2026-09-01 audit #1): Map → {designId: token}
+    // (JSON-safe). Empty/absent Map → undefined → the key is dropped by JSON.stringify, so a
+    // cleared session writes NO field instead of resurrecting slots from the previous save.
+    engDesignTokens: agent._engDesignTokens instanceof Map && agent._engDesignTokens.size > 0
+      ? Object.fromEntries(agent._engDesignTokens)
+      : undefined,
     goal: agent.goal ?? null,
     advisor: agent.config?.advisor ?? null,
     pendingReminders: agent._pendingReminders ?? [],
@@ -315,6 +321,14 @@ export function applySession(agent, data) {
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
   agent._engDesignToken = data.engDesignToken ?? null
+  // Multi-design slots restore from the {designId: token} object (2026-09-01 audit #1). A legacy
+  // slot without the field restores NO Map (fresh state) — never resurrect slots the writer did
+  // not have. Expired tokens are rejected downstream by validateDesignToken (fail-closed, TTL).
+  if (data.engDesignTokens && typeof data.engDesignTokens === "object" && !Array.isArray(data.engDesignTokens)) {
+    agent._engDesignTokens = new Map(Object.entries(data.engDesignTokens))
+  } else {
+    delete agent._engDesignTokens
+  }
   // engineering is session-level (2026-08-29): the slot value is the CLI session's authority
   // — config.json is only the initial default / cross-end mirror. A legacy slot without the
   // field keeps whatever config.json seeded (unchanged behavior).
@@ -429,6 +443,7 @@ export function resetSessionState(agent) {
   agent.tasks = []
   agent._sessionStart = null
   agent._engDesignToken = null
+  agent._engDesignTokens = new Map() // multi-design slots die with the session (2026-09-01 fix #2)
   agent._compressFailures = 0
   agent._verifyRetries = 0
   agent._verifyPassed = undefined

package/src/tools/apply_patch.md

@@ -1,9 +1,13 @@
 Apply a unified diff to one or more files, atomically: if any hunk fails to apply, nothing is written.
 
+**Use it for whole-file and multi-file changes:** creating MULTIPLE new files at once (`--- /dev/null` header per file), whole-file replacement, and cross-file refactors — one unified-diff call covers the whole change. A batched call is one permission ask and one turn instead of N separate calls.
+
 Parameters:
-- patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file.
+- patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file. The `+++ b/path` pair may be omitted for existing files — a lone `--- a/path` (or `--- b/path`) header followed directly by hunks applies to that path (new files still need `--- /dev/null` + `+++ b/path`).
 
 Notes:
+- Hunk header "@@" without coordinates is accepted. Coordinate-less hunks are located by their anchor lines: context lines plus the removed (-) lines, matched as a contiguous sequence — a unique match applies. The anchor-free forms require context: a hunk with no removed (-) lines (pure additions) needs at least 2 context lines for a unique match; a zero/one-context hunk with at least one removed (-) line is located by its anchor sequence (context + removed lines, in order) and applies on a unique match.
+- Returns the applied-file summary (`Applied patch to N file(s)` plus per-file change lines and syntax-check notes for changed .mjs files)
 - Use this for multi-file changes (e.g. rename an interface + update all callers) — one call, all-or-nothing
 - Hunks are located by their context/removed lines, not line numbers — but the context must match the file EXACTLY. Read the files first and generate the patch from actual content
 - If a hunk's context matches multiple locations it is rejected — add more surrounding context lines

package/src/tools/bash.md

@@ -5,7 +5,7 @@ Execute a shell command and return stdout+stderr. Use for running commands, buil
 - `ls` / `dir` → `ls`
 - `find` / glob search → `glob`
 - `grep` / `rg` → `grep`
-- `echo >` / `sed` / `printf >` / `cat << EOF` → `write` / `edit` / `hashline_edit` / `apply_patch` (enforced: redirection is blocked)
+- `echo >` / `sed` / `printf >` / `cat << EOF` → `write` / `edit` / `hashline_edit` / `apply_patch` (preferred: write tools handle encoding/EOL correctly)
 - `git diff` / `git status` / `git log` → `git` tool
 
 Parameters:
@@ -33,5 +33,5 @@ Notes:
 - Never use bash to read, copy, or transmit secret files (.env, keys, tokens)
 - Do NOT run destructive commands (rm -rf, force-push, drop table) without explicit user confirmation
 - After commands that change files (git checkout, npm install, etc.), repo_outline and code_search may be stale — re-run them to get current results.
-- Prefer read/glob/grep/ls for file operations inside the project — bash has no directory confinement.
-- NEVER use bash to write or modify files (echo/sed/printf > file, cat << EOF, etc.). Use write/edit/insert_after/apply_patch instead — they handle encoding, escaping, and directory confinement correctly.
+- Prefer read/glob/grep/ls for file operations inside the project — file tools and bash reach the same paths (no directory restriction).
+- NEVER use bash to write or modify files (echo/sed/printf > file, cat << EOF, etc.). Use write/edit/insert_after/apply_patch instead — they handle encoding, escaping, and EOL conventions correctly.

package/src/tools/delete.md

@@ -10,3 +10,4 @@ Notes:
 - Untracked or non-git files are deleted immediately
 - Tracked files require force=true (user must confirm separately)
 - Directories must be removed with bash (rm -rf)
+- Returns `Deleted <path>` (or `Error: ...` on failure/tracked refusal).

package/src/tools/edit-batch.mjs

@@ -0,0 +1,92 @@
+/**
+ * edit-batch.mjs — edit 工具的数组形态（edits: [...]）：一次多文件原子替换。
+ * （2026-08-31 工具顺手度 §9 ②；2026-09-01 缺陷修复"同文件多条串行累积"；
+ * 2026-09-04 TOOLS.md §15 D15.1——条目级判定+应用迁至 edit-diff.mjs——批量调共用。）
+ *
+ * 语义：同一 path 的多条编辑按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的
+ * 累积内容做匹配与替换；跨 path 条目互不影响（并行原子语义）；任一条失败 →
+ * 全不写（原子性保留）。每条目独立按判定序（§15.2 分支 0 单行替换 / 零重叠→插入 / LCS /
+ * 空 new 显式报错）。顶层 path（args.path）为无自带 path 条目的默认（2026-09-05 用户裁定
+ * ——条目自带 path 优先——见 TOOLS.md D15.3#9 修订注）。
+ */
+import { readFile, writeFile } from "node:fs/promises"
+import { resolveInCwd, normalizeEOL, joinWithEol, gitDiffOne, autoSyntaxCheck } from "./shared.mjs"
+// file.mjs ↔ edit-batch.mjs 循环引用：两侧导入的都是函数声明（提升初始化），
+// 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
+import { recordWrite, appendWriteContext } from "./file.mjs"
+// TOOLS.md §15 D15.1：批量条目判定+应用共用 edit-diff（§15.2 分支 0 单行替换 + 行级 LCS——零重叠→插入）；
+// D15.3#9：edits 互斥错误文本随前置校验分支迁出至 edit-diff.mjs。
+import { assertEditArgsExclusive, validateEditEntry, computeEditEntry } from "./edit-diff.mjs"
+
+/**
+ * Apply the `edits` array form: multi-file atomic replacement. Throws on any
+ * failure (atomic — nothing written). Returns the per-entry result text (joined).
+ */
+export async function applyEditBatch(args, ctx) {
+  if (!Array.isArray(args.edits) || args.edits.length === 0) {
+    throw new Error("edits must be a non-empty array of {path, old_string, new_string}")
+  }
+  assertEditArgsExclusive(args)
+  // 原子：先全量检查（所有文件的替换都可执行）——任一失败全不写。
+  // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑
+  // 按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的累积内容做匹配与替换
+  // （原实现每条都基于盘上原始内容计算、写盘循环后置，同文件后者覆盖前者 →
+  // 除最后一条外全部静默丢失）；跨 path 条目互不影响（并行原子语义不变）。
+  const groups = new Map() // abs → 每文件一条流水线
+  for (const e of args.edits) {
+    // 2026-09-05 用户裁定：顶层 path + edits 并存合法化——`e.path || args.path`（条目优先；
+    // 缺省入口仅在此兜底）；两者皆无 → 原错误文本（措辞补顶层选项）。
+    const p = e.path || args.path
+    if (!p) throw new Error("each edit must have a path — give each entry its own path or pass a top-level path")
+    // 前置校验（空 old / 非字符串 new——文本同 edit-diff 批量形态；读盘前校验）
+    validateEditEntry(e, { label: `edit for ${p}: `, rich: false })
+    const abs = resolveInCwd(ctx, p)
+    let g = groups.get(abs)
+    if (!g) {
+      const raw = await readFile(abs, "utf8")
+      g = { abs, path: p, raw, content: normalizeEOL(raw), edits: [] }
+      groups.set(abs, g)
+    }
+    g.edits.push(e)
+  }
+  const prepared = [] // 每条目一条回显；同文件内按 args 序，跨文件按首次出现分组序（应用/回显语义均正确）
+  for (const g of groups.values()) {
+    g.netShift = 0 // 组内行数差累积（合并快照的 shift = 全组净漂移）
+    for (const e of g.edits) {
+      // 条目级判定+应用（edit-diff——§15.2 分支 0 单行替换 + 判定序 1/2/3 + 空 new 显式报错 + >1000 行报错）
+      const out = computeEditEntry(g.content, e, {
+        path: g.path,
+        absPath: g.abs,
+        abortPrefix: "edit aborted (atomic — no files written): ",
+      })
+      prepared.push({
+        g,
+        editStartLine: out.editStartLine, // 基于累积内容计算——已天然计入前面条目的行偏移，不再累加
+        lineShift: out.lineShift,
+        occurrences: out.occurrences,
+        note: out.note ?? null, // P15.11——空白差异自动落点标记（成功消息追加）
+      })
+      g.content = out.updated // 串行累积：下一条基于本条应用后的内容
+      g.netShift += out.lineShift
+    }
+  }
+  // 全部检查通过——每文件一次写盘（同文件多条：写入串行累积后的最终内容）；
+  // recordWrite 每组一条合并快照：startLine = 组内**所有**编辑受影响行的最小值
+  // （#2，2026-09-01 交付评审尾巴——原实现取首条 = 调用序第一条，逆序条目时
+  // 护栏下界过高、受影响区内的 insert_after 被放行），shift = 全组行数差累积
+  // ——受影响区护栏覆盖组内所有编辑
+  for (const g of groups.values()) {
+    const startLine = Math.min(...prepared.filter((p) => p.g === g).map((p) => p.editStartLine))
+    await writeFile(g.abs, joinWithEol(normalizeEOL(g.content).split("\n"), g.raw), "utf8")
+    recordWrite(g.abs, { type: "edit", startLine, shift: g.netShift })
+  }
+  const results = []
+  for (const p of prepared) {
+    // #4（2026-09-01 交付评审尾巴）：与单文件路径对齐——每条结果附 git diff +
+    // autoSyntaxCheck（同文件多条会重复 diff/检查，换取格式一致、实现零分支）
+    const diff = gitDiffOne(ctx.cwd, p.g.abs)
+    const base = `Edited ${p.g.path}: replaced ${p.occurrences} occurrence(s)${p.note ? ` — ${p.note}` : ""}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(p.g.abs)}`
+    results.push(await appendWriteContext(p.g.abs, p.editStartLine, base))
+  }
+  return results.join("\n")
+}