@sema-agent/server 3.11.0 → 3.13.0

package/USAGE.md

@@ -67,6 +67,24 @@ ANTHROPIC_MAX_RETRIES=10             # 云 Anthropic 腿
 - 断路器**只在配了 `MODEL_GATEWAY_FALLBACK_URLS`(≥2 路)时才有意义**——它的价值是"开路即快速失败 → failover 立刻切备";单网关下它是 no-op(启动日志 `circuitBreakerNoop` 会提示)。只 `network/server/rate_limit` 计入连败,`auth`/`invalid_request` 不计(坏 key 熔断整网关无意义)。备用网关(最后一路)不套断路器。
 - **重试上限**(2026-07-31):两个键**不设就不传给引擎** —— 引擎默认当家。以前这里是 server 侧硬编码 `2`(openai 腿甚至零配置出口),而**显式传参压过引擎默认**,于是引擎抬默认对 server 部署毫无效果;第三方限流 provider 下"重试两次就放弃"正是由此而来。现在:不设=继承引擎默认(抬默认那天自动跟上),设了=按设的走。钉在 `test/brain.test.ts` 的「网关腿重试次数」两条上。
 - 断路器状态:配了 `SESSION_BACKEND=tidb` 时自动用**跨副本共享态**(TiDB `circuit_breaker` 表,写穿+刷新最终一致),否则进程内 Map。启动日志 `breakerState` 字段回显 `shared(tidb)`/`in-process`/`off`。详见 `design/27`。
+
+**可选 — WebSearch 后端(core 只留注入口,不自带任何 provider)**
+```bash
+WEB_SEARCH_PROVIDER=brave|tavily|searxng   # 缺席 = 不装配(WebSearch 工具根本不挂,不是挂了报错)
+WEB_SEARCH_API_KEY=…                       # brave/tavily 必填;只进 backend 闭包,永不进模型 prompt 或工具参数
+WEB_SEARCH_ENDPOINT=https://searx.example  # searxng 必填;brave/tavily 下是可选的 base-URL 覆盖(代理/测试)
+WEB_SEARCH_MAX_RESULTS=10                  # 1..20,返给模型的条数上限
+WEB_SEARCH_TIMEOUT_MS=10000                # 单次搜索墙钟
+```
+- 结果是**不可信输入**:core 会 `delimitUntrusted` 围栏并**重新施加** `allowed_domains`/`blocked_domains`
+  地板,所以 backend 遵不遵守 `opts` 是优化不是正确性要求 —— 换 provider(包括换成自建 SearXNG)
+  不会削弱域名地板。
+- 🔴 **`WEB_SEARCH_ENDPOINT` 的语义是「引擎可达的地址」,不是「用户机器上可达的地址」**
+  (2026-07-31 与 cli 对齐的跨机契约句):壳(TUI/桌面/web)与引擎**可以不在同一台机器**。壳在用户
+  笔记本上起的 localhost SearXNG,云端 worker 够不着 —— 所以「本地 SearXNG 兜底」这一档**只适用
+  壳自 spawn 本地引擎的同机形**;壳连接远程引擎时该档整级跳过,由运维在**引擎侧**配 `WEB_SEARCH_*`。
+  用户手填一个集中式 SearXNG 地址是合法形,照常放行。
+
 - **大工具结果落盘**(core 1.47/1.49):单条工具结果 > ~20000 字符时 core 把全文移出上下文、只留预览+ref,模型用 `read_tool_result` 按需分页回取。配了 TiDB 时自动用**durable `tool_result` 表**(跨副本 wake 仍能取回全文;否则 core 进程内默认 = 跨副本 wake 取不到→降级到预览,不崩)。`TOOL_RESULT_TTL_SEC`(默认 86400)按 TTL 回收(要 ≥ run 可恢复期)。启动日志 `toolResultStore` 回显 `shared(tidb)`/`in-process`。
 
 **可选 — 成本计量 + 预算闸（core 1.37）**

package/dist/approval.d.ts

@@ -9,6 +9,26 @@
  */
 import { type ToolPolicy } from "@sema-agent/core";
 import type { ApprovalStore } from "./plugins/store-backend.js";
+/**
+ * 运维**是否表达了门意图** —— boot 的单用户 allow-all 基线只在"零门意图"时才允许铺开,
+ * 所以这个谓词漏一格 = 那一格的意图被 allow-all 静默吞掉。
+ *
+ * 🔴 由来(2026-07-31 缝合审):这判据本来是 `main.ts` 里的一行内联表达式,只枚举了
+ * requireApproval / deny / durableApproval **三格**,漏了 `approvalNeverAuto`。漏的根因不是手滑,
+ * 是 `config-types.ts` 当时把 neverAuto 描述成 "Subset of approvalRequire" —— 若真是子集,
+ * 枚举 requireApproval 就覆盖了它。但本文件 inv#2 的执行面逐字相反(neverAuto ⊄ requireApproval),
+ * 于是「单用户 + 只配 APPROVAL_NEVER_AUTO=Bash」这一**语义完全合理**的形被判成零门意图 ⇒
+ * 落进 `createAllowDenyPolicy({})` 全面放行 ⇒ 那张"永远问人"的表从未进入任何 policy,Bash 直接跑。
+ *
+ * 判定挪到**与 inv#2 同一个文件**就是为了这个:两者再想漂开,得有人同时改这两段。
+ * 新增任何"门意图"配置项时,这里必须同步加一格(下面的表驱动测试会点名漏的那格)。
+ */
+export declare function hasOperatorGateIntent(config: {
+    approvalRequire: readonly string[];
+    approvalDeny: readonly string[];
+    approvalNeverAuto: readonly string[];
+    durableApproval: boolean;
+}): boolean;
 /**
  * Durable approval policy (core 1.67 / design/45): returns three-state **`ask`** for gated tools instead of
  * polling. With `TaskSpec.durableApproval` set + a `checkpointStore` on the Runner, core turns that `ask` into

package/dist/approval.js

@@ -8,6 +8,26 @@
  * dropped at the task deadline instead of holding the worker — design/06 F4 self-protection.
  */
 import { createApprovalPolicy, canonicalToolName, uuidv7 } from "@sema-agent/core";
+/**
+ * 运维**是否表达了门意图** —— boot 的单用户 allow-all 基线只在"零门意图"时才允许铺开,
+ * 所以这个谓词漏一格 = 那一格的意图被 allow-all 静默吞掉。
+ *
+ * 🔴 由来(2026-07-31 缝合审):这判据本来是 `main.ts` 里的一行内联表达式,只枚举了
+ * requireApproval / deny / durableApproval **三格**,漏了 `approvalNeverAuto`。漏的根因不是手滑,
+ * 是 `config-types.ts` 当时把 neverAuto 描述成 "Subset of approvalRequire" —— 若真是子集,
+ * 枚举 requireApproval 就覆盖了它。但本文件 inv#2 的执行面逐字相反(neverAuto ⊄ requireApproval),
+ * 于是「单用户 + 只配 APPROVAL_NEVER_AUTO=Bash」这一**语义完全合理**的形被判成零门意图 ⇒
+ * 落进 `createAllowDenyPolicy({})` 全面放行 ⇒ 那张"永远问人"的表从未进入任何 policy,Bash 直接跑。
+ *
+ * 判定挪到**与 inv#2 同一个文件**就是为了这个:两者再想漂开,得有人同时改这两段。
+ * 新增任何"门意图"配置项时,这里必须同步加一格(下面的表驱动测试会点名漏的那格)。
+ */
+export function hasOperatorGateIntent(config) {
+    return (config.approvalRequire.length > 0 ||
+        config.approvalDeny.length > 0 ||
+        config.approvalNeverAuto.length > 0 || // ← 漏了这格,见上面的由来
+        config.durableApproval);
+}
 /**
  * Durable approval policy (core 1.67 / design/45): returns three-state **`ask`** for gated tools instead of
  * polling. With `TaskSpec.durableApproval` set + a `checkpointStore` on the Runner, core turns that `ask` into

package/dist/brain.d.ts

@@ -1,5 +1,13 @@
 import { type Brain, type BreakerState } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+/**
+ * 配了快切层(failover ≥2 路 / 断路器)时,**每路**的重试上限。
+ *
+ * 取 2 的理由:留够吸收一次瞬时抖动(2 次递增退避 ≈ 500ms + 1000ms ≈ 1.5s),同时让外层在秒级而不是
+ * 分钟级拿到错误。断路器阈值 5 在这个值下 ≈ 7.5s 开路 —— 与它"快速失败让 failover 立刻切备"的设计意图
+ * 同量级。详见 createBrain 里 retryCap 那段的由来。
+ */
+export declare const FAST_FAIL_MAX_RETRIES = 2;
 /**
  * Build the external "Brain" (LLM) from config.
  *

package/dist/brain.js

@@ -1,5 +1,13 @@
 import { createAnthropicBrain, createCircuitBreakerBrain, createDegradingBrain, createFailoverBrain, createOpenAIBrain, createRoutingBrain, } from "@sema-agent/core";
 import { resolveModelApiKey } from "./key-resolver.js";
+/**
+ * 配了快切层(failover ≥2 路 / 断路器)时,**每路**的重试上限。
+ *
+ * 取 2 的理由:留够吸收一次瞬时抖动(2 次递增退避 ≈ 500ms + 1000ms ≈ 1.5s),同时让外层在秒级而不是
+ * 分钟级拿到错误。断路器阈值 5 在这个值下 ≈ 7.5s 开路 —— 与它"快速失败让 failover 立刻切备"的设计意图
+ * 同量级。详见 createBrain 里 retryCap 那段的由来。
+ */
+export const FAST_FAIL_MAX_RETRIES = 2;
 const DEFAULT_RESILIENCE = {
     // Watchdog defaults ON — mirrors config.ts env defaults so a config object without a
     // resilience block gets the same posture. connect/firstToken per the [880] fleet audit
@@ -52,7 +60,32 @@ export function createBrain(config, deps = {}) {
     // 压过引擎默认 ⇒ core 把默认抬到 10 对 server 部署零效果。缺席不传之后引擎默认当家、抬默认自动继承。
     // (五报清查 R1① 的 server 半场:限流 provider 走的正是这条 openai 兼容腿,而它此前**零配置出口**——
     // 同文件的 anthropic 腿反倒早有 `ANTHROPIC_MAX_RETRIES`。钉在 test/brain.test.ts 的两条上。)
-    const retryCap = config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {};
+    //
+    // 🔴 **拓扑感知的缺席值**(2026-08-01,core 2.9.0 提货验收当场实测出来的层间相互作用):
+    // core 2.9.0 把每次调用的重试默认抬到 10 且退避改递增形(`min(500·2^(n-1),32000)`),一次失败调用
+    // 要耗尽 **~180s** 才把错误交给外层(实测 179.7s)。而 failover / 断路器 / 反应式降级 **三层全在
+    // 每路 brain 的重试之外** —— 内层不放弃,外层看不见错误 ⇒ 主网关死了要 ~180s 才切备(旧形 ~0.6s)。
+    // 断路器更反讽:它要数失败次数才开路,每笔失败 180s、阈值 5 = 15 分钟,而它的存在理由正是"快速失败
+    // 让 failover 立刻切备"。
+    //
+    // 两边各自都对:core 的 10 次对**单 provider 被限流**是正解;server 的韧性栈对**多网关拓扑**是正解。
+    // **正确的默认取决于拓扑,而引擎不知道拓扑** —— 这条信息只有 server 有。
+    //
+    // ⚠️ 这**不是**又一次"中间层钉死引擎默认"(那正是本文件上一版刚修掉的病),三点区别:
+    //   ① 显式 `GATEWAY_MAX_RETRIES` **恒赢** —— 运维的话压过我们的推断;
+    //   ② 只在**外层真有快切层**时才收窄(≥2 路 failover 或断路器开);单路 = 缺席不传,引擎默认当家
+    //      (那正是限流 provider 的形,10 次是对的);
+    //   ③ 收窄**在启动日志里说出来**(`gatewayRetryCap` 字段),不是静默替换。
+    // 三个快切层,缺一个谓词就漏一族(反应式降级这一格是首版漏掉、被 brain 套件当场咬出来的):
+    //   ① failover(≥2 路)② 断路器 ③ 反应式降级 —— 后者尤其要算:它的触发条件**就是** `rate_limit`,
+    //   而运维开 `MODEL_DEGRADE_REACTIVE` 等于明说"撞限流就换便宜模型,别在原地等"。若这里不收窄,
+    //   主模型会先把 10 次递增退避耗完(~180s)才轮到降级 —— 把运维的选择拖成一句空话。
+    const fastFailTopology = config.gatewayFallbackUrls.length > 0 || r.circuitBreaker || Boolean(config.degrade?.reactive);
+    const retryCap = config.gatewayMaxRetries !== undefined
+        ? { maxRetries: config.gatewayMaxRetries }
+        : fastFailTopology
+            ? { maxRetries: FAST_FAIL_MAX_RETRIES }
+            : {};
     // Local openai-compatible gateway stack: primary + optional same-protocol fallbacks (failover).
     const routes = [config.gatewayBaseUrl, ...config.gatewayFallbackUrls];
     const openaiBrains = routes.map((baseUrl, i) => {
@@ -144,7 +177,9 @@ export function createBrain(config, deps = {}) {
                     get apiKey() {
                         return fbApiKey();
                     },
-                    ...retryCap, // 与主路同源:配了才传,没配让引擎默认当家(见上面 retryCap 的注)
+                    // 🔴 degrade fallback **不吃** fastFail 收窄:它是最外层的兜底,外面**没有**别的切换层了,
+                    // 所以它该按引擎默认那样耐心重试(限流场景正靠它)。显式 env 仍然恒赢。
+                    ...(config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {}),
                     fetchImpl,
                     ...timeouts,
                 });
@@ -170,6 +205,16 @@ export function brainSummary(config) {
         idleTimeoutMs: r.idleTimeoutMs || null,
         circuitBreaker: breakerActive,
         circuitBreakerRequested: r.circuitBreaker,
+        // 🔴 每路重试上限的**来源**必须可见(2026-08-01):收窄是我们按拓扑推断的,不是引擎默认,
+        // 静默替换等于让运维读不出"为什么这台机的失败切换比另一台快"。三态:
+        //   `env:<n>`      = 运维显式配了 GATEWAY_MAX_RETRIES(恒赢)
+        //   `fast-fail:<n>`= 外层有快切层(failover/断路器),我们收窄到 n(见 createBrain 的由来注)
+        //   `engine-default` = 缺席不传,引擎默认当家(单路限流 provider 的正解)
+        gatewayRetryCap: config.gatewayMaxRetries !== undefined
+            ? `env:${config.gatewayMaxRetries}`
+            : hasFailover || r.circuitBreaker || config.degrade?.reactive
+                ? `fast-fail:${FAST_FAIL_MAX_RETRIES}`
+                : "engine-default",
         circuitBreakerNoop: r.circuitBreaker && !hasFailover ? "needs ≥2 gateway routes" : null,
         // reactive degrade is active only if a valid catalog target resolves
         reactiveDegradeTo: config.degrade?.reactive && config.models?.[config.degrade.to] ? config.degrade.to : null,

package/dist/config-types.d.ts

@@ -493,9 +493,17 @@ export interface ServiceConfigFlat {
      *  asks, the human only sees the rest". `APPROVAL_AUTO_BUDGET`. */
     approvalAutoBudget: number;
     /** design/80 D-E (inv#2 — safety asks are never budgetable): gated tools that ALWAYS require a human even when
-     *  the auto-budget is on — the "irreversible / never auto-approve" set. Subset of approvalRequire; empty = the
-     *  budget may auto-approve any required tool. (In-service every gated ask is gate.kind="human", so this set is
-     *  the ONLY way to keep an irreversible tool human-gated under an auto-budget.) `APPROVAL_NEVER_AUTO`. */
+     *  the auto-budget is on — the "irreversible / never auto-approve" set. empty = the budget may auto-approve any
+     *  required tool. (In-service every gated ask is gate.kind="human", so this set is the ONLY way to keep an
+     *  irreversible tool human-gated under an auto-budget.) `APPROVAL_NEVER_AUTO`.
+     *
+     *  🔴 **NOT required to be a subset of `approvalRequire`**(2026-07-31 修口)。这里原来写的是
+     *  "Subset of approvalRequire",而 `approval.ts` 的 inv#2 执行面逐字相反:
+     *  「even if it was not also listed in requireApproval — the footgun: neverAuto ⊄ requireApproval」。
+     *  两处文档互相矛盾**不是文字问题**:`main.ts` 的 `operatorGateIntent` 是照着"子集"那句写的
+     *  ——若真是子集,枚举 `approvalRequire.length > 0` 就覆盖了它,漏掉看着无害。实际不是子集,于是
+     *  「只配 APPROVAL_NEVER_AUTO」这一形被判成"零门意图" ⇒ 落进单用户 allow-all 基线 ⇒ 那张表
+     *  从未进入任何 policy。判定现在单源在 `hasOperatorGateIntent()`(与 inv#2 同文件)。 */
     approvalNeverAuto: string[];
     /** design/80 D-G (HMAC = integrity, not identity; ✅ WIRED — the "SCAFFOLD, not yet wired" note here was STALE,
      *  corrected 2026-07-25: consumed by `verifyDirectDoorProof` → `verifyApprovalHmac`, reached from the live decide

package/dist/http/routes/sessions.js

@@ -220,8 +220,11 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             // codex 一轮生命周期状态机:①连接坑与 close 守卫在任何 await 之前同步建立(读存储期间断连不再
             // 漏清/漏还坑);②每个 await 之后查 closed;③所有拒绝/异常路径经同一 release。
             if (sse.sseConnections >= (deps.sessionEventsMaxConnections ?? 256)) {
-                res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                res.end(JSON.stringify({ error: "session-events connection cap reached — fall back to /head polling" }));
+                // 🔴 机器码而非裸 writeHead(2026-07-31 缝合审):这条 503 与 drain 的 503 走同一条流,
+                // 而 drain 的带 `errorCode:"draining"`(冻结契约)。没有码,消费端只能靠自由文本字面区分
+                // 「连接帽 ⇒ 回落 /head 轮询(自愈,保持连接策略)」与「该重连替换实例」—— 正是本仓要根除的姿势。
+                res.setHeader("retry-after", "5");
+                sendError(res, 503, "state.sse_connection_cap", "session-events connection cap reached — fall back to /head polling");
                 return;
             }
             sse.sseConnections++; // 同步占坑(查+占同拍,慢读并发不再超卖);此后一切路径必经 cleanup 还坑
@@ -247,8 +250,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 const stallBound = deps.sessionEventsStallMs ?? 60_000;
                 if (sse.sseOwnerLookups >= 64) {
                     cleanup();
-                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                    res.end(JSON.stringify({ error: "session-events owner-lookup concurrency cap — retry" }));
+                    res.setHeader("retry-after", "5");
+                    sendError(res, 503, "state.sse_owner_lookup_cap", "session-events owner-lookup concurrency cap — retry");
                     return;
                 }
                 sse.sseOwnerLookups++;
@@ -271,8 +274,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     return; // 读期断连:close 守卫已还坑,别再写已死响应
                 if (owner === "__stall__") {
                     cleanup();
-                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                    res.end(JSON.stringify({ error: "session-events owner lookup stalled — retry" }));
+                    res.setHeader("retry-after", "5");
+                    sendError(res, 503, "state.sse_owner_lookup_stalled", "session-events owner lookup stalled — retry");
                     return;
                 }
                 if (owner === undefined) {
@@ -364,8 +367,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd); // owner 铸入条目(四轮跨副本围栏);已知条目=同步 replay 首帧;新条目=首拍探针 ≤hotMs
                 if (!unsubscribe) {
                     cleanup();
-                    res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
-                    res.end(JSON.stringify({ error: "session-events probe cap reached — fall back to /head polling" }));
+                    res.setHeader("retry-after", "5");
+                    sendError(res, 503, "state.sse_probe_cap", "session-events probe cap reached — fall back to /head polling");
                     return;
                 }
                 res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache, no-transform", connection: "keep-alive", "x-accel-buffering": "no" });

package/dist/main.js

@@ -14,7 +14,7 @@ import { ensureChildSessionDurableWithPromotion } from "./plugins/session-store.
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
 import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadObserver } from "./plugins/web-search.js";
 import { createAuthorizer } from "./security.js";
-import { createDurableAskPolicy } from "./approval.js";
+import { createDurableAskPolicy, hasOperatorGateIntent } from "./approval.js";
 import { loadSkills } from "./capabilities/skills.js";
 import { GiteaClient } from "./capabilities/repo-tools.js";
 import { buildScenarios, builtinScenarioDetails } from "./capabilities/scenarios.js";
@@ -30,6 +30,7 @@ import { performMemorySync } from "./memory-sync.js";
 import { startOtlpExporter } from "./observability/otel-exporter.js";
 import { HEARTBEAT_MS, backgroundAgentOutput, taskHandleOutput, taskHandleStop } from "./runs.js";
 import { SQL_BLOB_DEFAULT_MAX_BYTES } from "./plugins/blob-backend.js";
+import { counterStoreLabel } from "./plugins/store-backend.js";
 import { composeHooks } from "./hooks/hook-runner.js";
 import { createHookLlm } from "./hooks/hook-llm.js";
 import { startFleetClientFromEnv } from "./fleet-client.js";
@@ -367,7 +368,8 @@ async function main() {
     // backing store is wired (e.g. DB_BACKEND=local → no approvalStore/checkpointStore ⇒ approvalEnabled/durableEnabled
     // false), that is a MISCONFIG — do NOT mask it with allow-all; leave toolPolicy undefined so core's UNGATED warning
     // still surfaces it. So the baseline needs single-user turnkey ∧ zero expressed gate intent.
-    const operatorGateIntent = config.approvalRequire.length > 0 || config.approvalDeny.length > 0 || config.durableApproval;
+    // 单源在 approval.ts(与 inv#2 同文件)—— 这里原是内联的三格枚举,漏了 approvalNeverAuto,详见该函数顶注。
+    const operatorGateIntent = hasOperatorGateIntent(config);
     const singleUserAutoAcceptBaseline = config.requirePrincipal !== true && !operatorGateIntent;
     // design/45 durable-checkpoint (core 1.67): opt-in (DURABLE_APPROVAL + a pool). When on, F4 uses durable
     // suspend/resume instead of the poll gate — a gated `ask` suspends the task (status:"suspended" + checkpoint)
@@ -869,9 +871,9 @@ async function main() {
         memory: memoryEngine ? `engine(${memoryEngine.root})` : "off",
         instanceId,
         rateLimitPerMin: config.rateLimitPerMin,
-        rateLimit: config.rateLimitPerMin > 0 ? (backend ? `shared()` : "in-process") : "off",
+        rateLimit: config.rateLimitPerMin > 0 ? counterStoreLabel(backend?.rateLimiter, backend?.kind) : "off",
         maxPrincipalCostUsd: config.maxPrincipalCostUsd || null,
-        costQuota: config.maxPrincipalCostUsd > 0 ? (backend ? `shared()` : "in-process") : "off",
+        costQuota: config.maxPrincipalCostUsd > 0 ? counterStoreLabel(backend?.costQuota, backend?.kind) : "off",
         // durable offload store for large tool results (cross-replica wake); else core's in-process default
         toolResultStore: toolResultStore ? (backend?.kind === "local" ? "file(local)" : "shared(sql)") : "in-process",
         otel: config.otel ? config.otel.endpoint : null,

package/dist/plugins/store-backend.d.ts

@@ -186,6 +186,19 @@ export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "l
  *  field the 20G-workspace case needed; more knobs when a case shows up. Exported for tests
  *  (fractional-MB rounding + partial-merge semantics need a regression lock). */
 export declare function snapshotBoundsFromConfig(config: ServiceConfig): FileSnapshotBounds;
+/**
+ * 启动日志里「跨副本 or 进程内」那一格的标签。
+ *
+ * 🔴 判据必须是**那个 store 本身在不在**,不是「有没有 backend」(2026-07-31 缝合审)。
+ * `LocalBackend` 明确省略 `costQuota`/`rateLimiter`(见它类尾那行 "intentionally absent"),
+ * 而 `DB_BACKEND=local` 是**裸 boot 的默认值** —— 原来 main.ts 那两行用 `backend ? "shared()" : …` 判,
+ * 于是单机默认形配了 `RATE_LIMIT_PER_MIN` 会打出 `shared()`,实际跑的是每副本一份的进程内限流器。
+ * 运维扩到 N 副本时读这行判定"限流是跨副本的",真实额度是 N 倍。
+ * (同一个说谎病族在紧邻的 `breakerState` 上修过一次——"was hard-coded 'shared(tidb)' — lied under
+ * DB_BACKEND=pg"——`session:` 也跟着修了,这两行没跟上。顺带:原来的 `shared()` 括号是空的,
+ * 而兄弟行都写 `shared(${kind})`。)
+ */
+export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
  *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
 export declare function createStoreBackend(config: ServiceConfig): StoreBackend | undefined;

package/dist/plugins/store-backend.js

@@ -276,6 +276,21 @@ class LocalBackend {
     mysqlPool() { return undefined; }
     pgPool() { return undefined; }
 }
+/**
+ * 启动日志里「跨副本 or 进程内」那一格的标签。
+ *
+ * 🔴 判据必须是**那个 store 本身在不在**,不是「有没有 backend」(2026-07-31 缝合审)。
+ * `LocalBackend` 明确省略 `costQuota`/`rateLimiter`(见它类尾那行 "intentionally absent"),
+ * 而 `DB_BACKEND=local` 是**裸 boot 的默认值** —— 原来 main.ts 那两行用 `backend ? "shared()" : …` 判,
+ * 于是单机默认形配了 `RATE_LIMIT_PER_MIN` 会打出 `shared()`,实际跑的是每副本一份的进程内限流器。
+ * 运维扩到 N 副本时读这行判定"限流是跨副本的",真实额度是 N 倍。
+ * (同一个说谎病族在紧邻的 `breakerState` 上修过一次——"was hard-coded 'shared(tidb)' — lied under
+ * DB_BACKEND=pg"——`session:` 也跟着修了,这两行没跟上。顺带:原来的 `shared()` 括号是空的,
+ * 而兄弟行都写 `shared(${kind})`。)
+ */
+export function counterStoreLabel(store, kind) {
+    return store ? `shared(${kind ?? "unknown"})` : "in-process";
+}
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
  *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
 export function createStoreBackend(config) {

package/dist/plugins/tool-result-store-sql.d.ts

@@ -1,40 +1,3 @@
-/**
- * Durable backing store for offloaded large tool results (core 1.47 offload / 1.49 durable contract) —
- * SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical
- * `TiDBToolResultStore` / `PgToolResultStore` class names survive as thin ctor subclasses so every consumer
- * (store-backend.ts, the fake-pool unit suites, the real-DB integration suites) is untouched.
- *
- * Mirrors core's reference `TiDbToolResultStore` adapter. Without this, the Runner defaults to a
- * task-scoped in-memory store: an async run that wakes on ANOTHER replica can't `read_tool_result` an
- * offloaded result (the ref misses → the model is told it's unavailable; the preview still stands, so it
- * degrades, never crashes). A durable store survives wake/resume across the stateless fleet.
- *
- * core namespaces the ref as `tr_<sessionId>_<toolCallId>` (1.49) → globally unique → usable directly as
- * the PRIMARY KEY (no composite key needed). `put` is write-once (idempotent on replay/retry: a retry is
- * a NEW toolCallId → new ref, so a given ref never changes content). Retention is anchored to a run's
- * RECOVERABLE window via TTL (`reapOlderThan`): a resumable run may re-fetch an old ref after wake, but a
- * completed run only needs the preview for audit/replay — so a TTL comfortably exceeding the run lifetime
- * bounds storage without losing recoverable full-text.
- *
- * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
- *   - `?` placeholders vs `$n`
- *   - write-once insert = `INSERT IGNORE` vs `INSERT ... ON CONFLICT (ref) DO NOTHING`
- *   - affectedRows vs rowCount (via SqlDriver)
- *   - `SUBSTRING(content, ?, ?)` (1-indexed, comma form) vs the ANSI `SUBSTRING(content FROM $n::int FOR
- *     $m::int)` positional form WITH explicit `::int` casts — node-pg binds bare params as text, and
- *     `SUBSTRING(s FROM <text>)` is the POSIX-REGEX overload (it would treat $1 as a pattern); the cast
- *     forces the positional integer overload. `CHAR_LENGTH` is ANSI and shared.
- *   - content column: TiDB LONGTEXT vs PG TEXT (PG has no LONGTEXT; TEXT is unbounded), DATETIME(3) vs
- *     TIMESTAMPTZ(3) — schema only (TiDB DDL in tidb-pool.ts; PG DDL self-contained below, exported for the
- *     integration test + pg-pool.ts's central apply).
- *   - `put`'s UTF-16 sanitize is a GENUINE algorithm divergence, not just SQL text — see the dialect branch
- *     inline for why.
- *   - ESCAPE-clause literal: TiDB spells `ESCAPE '\\\\'` (declares the backslash escape char explicitly —
- *     under `sql_mode=NO_BACKSLASH_ESCAPES` `\` is NOT the LIKE escape char by default, so leaving it
- *     implicit would silently stop escaping and let a crafted sessionId's `_`/`%` over-match OTHER
- *     sessions' rows); PG spells `ESCAPE '\'` (its default escape char already, kept for lock-step intent
- *     with the TiDB twin rather than out of necessity).
- */
 import type { ToolResultStore, ToolResultSlice } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
@@ -52,8 +15,13 @@ export declare class SqlToolResultStore implements ToolResultStore {
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** D1(试剂盒揪出,RB-266 语义):ref 是主键且 deleteBySession 靠 `tr_<sid>_%` 前缀清理——不合规
-     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。判定逐字镜像 core assertSafeToolResultRef
-     *  (dist/core/tool-result-store.js:5;core 根不导出,本地镜像,试剂盒契约条目为同源锚)。 */
+     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。
+     *
+     *  🔴 判定**单源**:直调 core 的 `assertSafeToolResultRef`(core 2.8.0 起入公共面)。
+     *  在此之前这里是那 6 个判别条件的**本地镜像** —— 我在 [2159] 主动交出过这条裂缝:镜像是第二真源,
+     *  core 哪天收紧一格(加 Windows 保留名、长度上限……)我方不会跟着动,而**试剂盒会继续绿**
+     *  (它测的是「拒不拒」,不是「按同一张表拒」)。core 按请求追加了导出,镜像随之删除,裂缝闭合。
+     *  抛错文案与 core 逐字相同,所以 wire 与既有钉都不变。 */
     private isUnsafeRef;
     private assertSafeRef;
     put(ref: string, content: string): Promise<void>;

package/dist/plugins/tool-result-store-sql.js

@@ -1,3 +1,41 @@
+/**
+ * Durable backing store for offloaded large tool results (core 1.47 offload / 1.49 durable contract) —
+ * SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical
+ * `TiDBToolResultStore` / `PgToolResultStore` class names survive as thin ctor subclasses so every consumer
+ * (store-backend.ts, the fake-pool unit suites, the real-DB integration suites) is untouched.
+ *
+ * Mirrors core's reference `TiDbToolResultStore` adapter. Without this, the Runner defaults to a
+ * task-scoped in-memory store: an async run that wakes on ANOTHER replica can't `read_tool_result` an
+ * offloaded result (the ref misses → the model is told it's unavailable; the preview still stands, so it
+ * degrades, never crashes). A durable store survives wake/resume across the stateless fleet.
+ *
+ * core namespaces the ref as `tr_<sessionId>_<toolCallId>` (1.49) → globally unique → usable directly as
+ * the PRIMARY KEY (no composite key needed). `put` is write-once (idempotent on replay/retry: a retry is
+ * a NEW toolCallId → new ref, so a given ref never changes content). Retention is anchored to a run's
+ * RECOVERABLE window via TTL (`reapOlderThan`): a resumable run may re-fetch an old ref after wake, but a
+ * completed run only needs the preview for audit/replay — so a TTL comfortably exceeding the run lifetime
+ * bounds storage without losing recoverable full-text.
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - write-once insert = `INSERT IGNORE` vs `INSERT ... ON CONFLICT (ref) DO NOTHING`
+ *   - affectedRows vs rowCount (via SqlDriver)
+ *   - `SUBSTRING(content, ?, ?)` (1-indexed, comma form) vs the ANSI `SUBSTRING(content FROM $n::int FOR
+ *     $m::int)` positional form WITH explicit `::int` casts — node-pg binds bare params as text, and
+ *     `SUBSTRING(s FROM <text>)` is the POSIX-REGEX overload (it would treat $1 as a pattern); the cast
+ *     forces the positional integer overload. `CHAR_LENGTH` is ANSI and shared.
+ *   - content column: TiDB LONGTEXT vs PG TEXT (PG has no LONGTEXT; TEXT is unbounded), DATETIME(3) vs
+ *     TIMESTAMPTZ(3) — schema only (TiDB DDL in tidb-pool.ts; PG DDL self-contained below, exported for the
+ *     integration test + pg-pool.ts's central apply).
+ *   - `put`'s UTF-16 sanitize is a GENUINE algorithm divergence, not just SQL text — see the dialect branch
+ *     inline for why.
+ *   - ESCAPE-clause literal: TiDB spells `ESCAPE '\\\\'` (declares the backslash escape char explicitly —
+ *     under `sql_mode=NO_BACKSLASH_ESCAPES` `\` is NOT the LIKE escape char by default, so leaving it
+ *     implicit would silently stop escaping and let a crafted sessionId's `_`/`%` over-match OTHER
+ *     sessions' rows); PG spells `ESCAPE '\'` (its default escape char already, kept for lock-step intent
+ *     with the TiDB twin rather than out of necessity).
+ */
+import { assertSafeToolResultRef } from "@sema-agent/core";
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
@@ -29,15 +67,25 @@ export class SqlToolResultStore {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
     /** D1(试剂盒揪出,RB-266 语义):ref 是主键且 deleteBySession 靠 `tr_<sid>_%` 前缀清理——不合规
-     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。判定逐字镜像 core assertSafeToolResultRef
-     *  (dist/core/tool-result-store.js:5;core 根不导出,本地镜像,试剂盒契约条目为同源锚)。 */
+     *  ref 的行既躲过 session 删除也只能等 TTL,永远清不掉。
+     *
+     *  🔴 判定**单源**:直调 core 的 `assertSafeToolResultRef`(core 2.8.0 起入公共面)。
+     *  在此之前这里是那 6 个判别条件的**本地镜像** —— 我在 [2159] 主动交出过这条裂缝:镜像是第二真源,
+     *  core 哪天收紧一格(加 Windows 保留名、长度上限……)我方不会跟着动,而**试剂盒会继续绿**
+     *  (它测的是「拒不拒」,不是「按同一张表拒」)。core 按请求追加了导出,镜像随之删除,裂缝闭合。
+     *  抛错文案与 core 逐字相同,所以 wire 与既有钉都不变。 */
     isUnsafeRef(ref) {
-        return ref === "" || ref === "." || ref === ".." || ref.includes("/") || ref.includes("\\") ||
-            [...ref].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+        // core 只给 assert 形(它就是判定本体);读面要的是谓词,由同一个 assert 派生 —— 仍是单源。
+        try {
+            assertSafeToolResultRef(ref);
+            return false;
+        }
+        catch {
+            return true;
+        }
     }
     assertSafeRef(ref) {
-        if (this.isUnsafeRef(ref))
-            throw new Error(`tool-result store: unsafe ref ${JSON.stringify(ref)}`);
+        assertSafeToolResultRef(ref);
     }
     async put(ref, content) {
         this.assertSafeRef(ref);

package/dist/trace/project.d.ts

@@ -248,6 +248,9 @@ export declare function brainStatusEventData(ev: {
     phase: string;
     detail?: string;
     retryInSec?: number;
+    attempt?: number;
+    maxRetries?: number;
+    retryInMs?: number;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;

package/dist/trace/project.js

@@ -289,10 +289,14 @@ export function workspaceChangedEventData(ev) {
  *  SERVICE's own observation record (why a turn stalled: rate_limited/retrying/reconnecting/circuit_open),
  *  not a core event replay. Whitelist: the closed phase union + neutral bounded detail (redacted) + retryInSec. */
 export function brainStatusEventData(ev) {
+    const num = (v) => typeof v === "number" && Number.isFinite(v);
     return {
         phase: String(ev.phase),
         ...(typeof ev.detail === "string" && ev.detail.length > 0 ? { detail: redactSecrets(ev.detail).slice(0, 300) } : {}),
-        ...(typeof ev.retryInSec === "number" && Number.isFinite(ev.retryInSec) ? { retryInSec: ev.retryInSec } : {}),
+        ...(num(ev.retryInSec) ? { retryInSec: ev.retryInSec } : {}),
+        ...(num(ev.attempt) ? { attempt: ev.attempt } : {}),
+        ...(num(ev.maxRetries) ? { maxRetries: ev.maxRetries } : {}),
+        ...(num(ev.retryInMs) ? { retryInMs: ev.retryInMs } : {}),
         ...identityFields(ev),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^2.5.0",
+    "@sema-agent/core": "^2.9.0",
     "@sema-agent/registry-core": "^0.11.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",