@sema-agent/server 7.68.0 → 7.70.0

package/README.md

@@ -191,6 +191,9 @@ stop different things at different moments (per-task ceiling / per-principal ADM
 not interrupt a run already executing / deployment usage window that does stop one at a turn
 boundary) — the side-by-side table is in `USAGE.md`, worth reading before picking one.
 
+Web search (deployment `WEB_SEARCH_*` env, per-request `settings.webSearch`, the two-lane precedence
+and the tool-level error forms) is documented in `USAGE.md` §9.5.
+
 ## HTTP API overview
 
 One row per endpoint family (not exhaustive):

package/README.zh-CN.md

@@ -170,6 +170,9 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 (单任务硬闸 / per-principal **进场门**——不打断已在跑的 run / 部署级治理窗——会在 turn 边界停住它);
 选之前请先读 `USAGE.md` 里的「三道 $ 闸的分工」对照表。
 
+Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`、两车道优先级、工具层错误形)
+见 `USAGE.md` §9.5。
+
 ## HTTP API 概览
 
 一行一个端点族(非全量):

package/USAGE.md

@@ -75,14 +75,34 @@ ANTHROPIC_MAX_RETRIES=10             # 云 Anthropic 腿
 - **重试上限**(2026-07-31):两个键**不设就不传给引擎** —— 引擎默认当家。以前这里是 server 侧硬编码 `2`(openai 腿甚至零配置出口),而**显式传参压过引擎默认**,于是引擎抬默认对 server 部署毫无效果;第三方限流 provider 下"重试两次就放弃"正是由此而来。现在:不设=继承引擎默认(抬默认那天自动跟上),设了=按设的走。钉在 `test/brain.test.ts` 的「网关腿重试次数」两条上。
 - 断路器状态:配了 `SESSION_BACKEND=mysql` 时自动用**跨副本共享态**(SQL `circuit_breaker` 表,写穿+刷新最终一致),否则进程内 Map。启动日志 `breakerState` 字段回显 `shared(mysql)`/`in-process`/`off`。
 
-**可选 — WebSearch 后端(core 只留注入口,不自带任何 provider)**
+**可选 — WebSearch 后端(core 只留注入口,不自带任何 provider;部署 env 七键)**
 ```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                # 单次搜索墙钟
+WEB_SEARCH_PROVIDER=brave|tavily|searxng   # 唯一的"装配开关":合法词才挂 WebSearch 工具;缺席/非法词 = 不装配(不是挂了报错)
+WEB_SEARCH_API_KEY=…                       # brave/tavily 必需(searxng 不读这一键);只进 backend 闭包,永不进模型 prompt 或工具参数
+WEB_SEARCH_ENDPOINT=https://searx.example  # searxng 必需(实例地址);brave/tavily 下是可选的 base-URL 覆盖(代理/测试)
+WEB_SEARCH_MAX_RESULTS=10                  # 1..20(夹逼);缺席/非正数/非数字 → 用 backend 默认 10;小数向下取整
+WEB_SEARCH_TIMEOUT_MS=10000                # 单次搜索墙钟(ms),下限 1000;缺席/非正数/非数字 → 用 backend 默认 10000
+WEB_SEARCH_SEARXNG_PARAMS="engines=bing,duckduckgo;language=zh-CN"  # 仅 searxng 腿消费;`;` 分隔 k=v 对;一个都解析不出 → 键整个不铸(不产出空对象)
+WEB_SEARCH_PROBE_ON_BOOT=true              # boot 期一次性真出网探活,默认 OFF;只认 "true"/"1"(trim+小写后比较),含糊值当没开
 ```
+
+七键逐一(`src/plugins/web-search.ts` `webSearchConfigFromEnv` §294-309;类型/默认/坏值登记见
+`src/config-catalog.ts:654-662`):
+
+| env 键 | 类型 | 默认 | 缺席行为 | 坏值行为 |
+|---|---|---|---|---|
+| `WEB_SEARCH_PROVIDER` | 闭集(`brave`\|`tavily`\|`searxng`) | 无 | WebSearch 工具整体不装配(功能缺席,无 warn) | 三词之外的任何值 = 同缺席处理,不装配、不 warn(`:296-297`) |
+| `WEB_SEARCH_API_KEY` | secret string | 无 | brave/tavily:后端仍会装配(装配只看 `PROVIDER`),**首次真实工具调用**时抛 `WEB_SEARCH_API_KEY is required for the <provider> provider`(`:152`/`:164`);searxng:本键无消费点 | 空字符串同缺席(`env.WEB_SEARCH_API_KEY ?` 只认真值,`:303`) |
+| `WEB_SEARCH_ENDPOINT` | url string | brave/tavily → 各自官方 API;searxng → 无默认 | brave/tavily:落官方 endpoint;searxng:**首次真实工具调用**时抛 `WEB_SEARCH_ENDPOINT (the SearXNG instance URL) is required for the searxng provider`(`:193`) | 不做 URL 形校验——写不成 URL 由 `new URL()` 抛出,同样落到"首次调用才现形"那条路径,不拒启 |
+| `WEB_SEARCH_MAX_RESULTS` | number | `10` | 用默认 10 | 非数字/≤0 → 回落默认 10;是数字则向下取整;最终值再夹在 `[1,20]`(设 999 也被 clamp 到 20,`:227`) |
+| `WEB_SEARCH_TIMEOUT_MS` | number(ms) | `10000` | 用默认 10000 | 非数字/≤0 → 回落默认;最终值下限夹到 1000ms(`Math.max(1000,…)`,`:228`) |
+| `WEB_SEARCH_SEARXNG_PARAMS` | string(`k=v;k=v`) | 无(不铸键 = 不传 `extraParams`,交给 core adapter 自己的缺省) | 键整个不铸 | 一个 `k=v` 对都解析不出(没有 `=`,或 `k`/`v` 任一为空)→ 同缺席,整串忽略,不拒启不 warn(`:260-277`);env 侧值恒为字符串,不会触发下面 per-request 那个"数组被误当对象吸收"的边角(见 §9.5) |
+| `WEB_SEARCH_PROBE_ON_BOOT` | boolean(仅认 `"true"`/`"1"`) | `false`(OFF) | 不探活 | trim+小写后不等于 `"true"`/`"1"` 的任何拼法(含 `"yes"`/`"on"`)一律当 `false`;探活失败(网络不通/后端拒绝)只 `warn`(`web_search_probe_failed`),**不拒启**——功能型能力缺席走降级,不是保护型旋钮(`main.ts:1028-1034`) |
+
+**结论:七键无一在 boot 期拒启。** 与本仓其它安全轴旋钮(`MODEL_DEGRADE_ON`、思考档三键等,拼错即拒启)
+姿势不同——WebSearch 挂不挂是**功能面**取舍,不是安全边界,七键统一走"回落/降级",不是"fail-closed 拒启"。
+真正的配置错误(缺 key / endpoint 错)只在**首次真实工具调用**时才现形,以 tool_result 错误文本形式回给
+模型,不是 HTTP 层错误、不影响 boot、也不使任务整体 `failed`(细节见 §9.5)。
 - 结果是**不可信输入**:core 会 `delimitUntrusted` 围栏并**重新施加** `allowed_domains`/`blocked_domains`
   地板,所以 backend 遵不遵守 `opts` 是优化不是正确性要求 —— 换 provider(包括换成自建 SearXNG)
   不会削弱域名地板。
@@ -91,6 +111,7 @@ WEB_SEARCH_TIMEOUT_MS=10000                # 单次搜索墙钟
   笔记本上起的 localhost SearXNG,云端 worker 够不着 —— 所以「本地 SearXNG 兜底」这一档**只适用
   壳自 spawn 本地引擎的同机形**;壳连接远程引擎时该档整级跳过,由运维在**引擎侧**配 `WEB_SEARCH_*`。
   用户手填一个集中式 SearXNG 地址是合法形,照常放行。
+- **per-request 覆盖 + 两车道优先级 + 错误形全表**:见 §9.5。
 
 - **大工具结果落盘**(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`。
 
@@ -124,6 +145,19 @@ MODEL_DEGRADE_ON=rate_limit,breaker_open   # 可选,反应式触发器子集;词
   `med,high` 此前静默窄成只剩 `high` 一档,而这根旋钮的全部用途就是宣告高档可用,静默落空 = 高档
   永远上不去。空串 / 纯分隔(`, `)仍与不设同义(不铸键,行为不变);anthropic 腿刻意不铸 compat
   (那条腿不吃 `reasoning_effort`),`GET /v1/config/catalog` 对它诚实回 `null`。
+- 🔴 **`MODEL_THINKING_FORMAT`(7.69.0 新,同族第三根)**:这台网关按哪种拼法收「开/关思考」——
+  `openai|openrouter|deepseek|together|zai|qwen|qwen-chat-template` 七词闭集(上 core
+  `OpenAICompletionsCompat.thinkingFormat`),未知词同样 **boot 拒启并点名闭集**。缺席 ⇒ 不铸这一键
+  (core 按 baseUrl / 模型 id 自行推断,行为逐字不变)。**真需求**:vLLM / Qwen 类**缺省开思考**的网关,
+  只有 `qwen-chat-template`(`chat_template_kwargs.enable_thinking=false`)关得掉,而 `MODEL_EXTRA_BODY`
+  穿不过引擎的 OpenAI 保留键表 —— 不设它,这类部署每一轮都白烧一段思考且读数上看不出来。它与
+  `MODEL_REASONING_EFFORT_LEVELS` 铸进**同一个** `compat` 对象(两根旋钮同时设两键都在)。
+- 🔴 **逐模型声明(目录腿):`models.models[].compat`**(settings-schema ≥1.10.0;7.69.0 消费)——
+  同一张 `OpenAICompletionsCompat` 五键(`thinkingFormat` / `reasoningEffortLevels` / `maxTokensField` /
+  `requiresReasoningContentOnAssistantMessages` / `supportsReasoningEffort`)可以**按模型**写在
+  `config.d/models.json` 或配置控制面的目录条目上,逐键盖过上面两根 env 缺省(BL-8:没写的键仍继承 env)。
+  **坏形/坏词/未知键 ⇒ 丢掉这条 `compat` 声明、模型本体保留**,并打一条 `model_compat_dropped`
+  点名 warn(引擎回落到自己的推断 = 今天的行为);一条写坏的声明**不会**让这只模型或整套目录消失。
 - 反应式降级 brain 包在**最外层**;fallback brain 用自己的凭据(decorator 清掉主模型的 per-call key 防外泄给别的 provider)。**坑**:`MODEL_DEGRADE_TO` 最好别和被限流的是同一网关/账号,否则反应式切过去照样撞同一个 rate_limit。
 - **定价怎么设**:`model.cost` 来自 `MODEL_COST_INPUT/OUTPUT/CACHE_READ/CACHE_WRITE`(**USD per 1M tokens**,默认 0 = `costUsd` 读 0)。云模型(如 review-gw 的 deepseek-v4-flash)必须设,否则 spend 恒为 $0;本地自托管(qwen)留 0 即对(无 per-token 外部花费)。字段名是 `costUsd`,**非美元计价的网关要先折算**(如 DeepSeek 官方 CNY ÷ 汇率)。配置控制面管的模型走 `CenterModel.cost`(中心存价、不存 secret)。
 - 成本计量**自动开**:从 config 的 `model.cost`(per-1M 绝对 USD)注入 `pricing`,core 算出权威的整数 `costMicroUsd`(避免浮点累计误差)。`/metrics` 新增:`model_cost_micro_usd_total{model}`(覆盖所有 brain 调用=主任务+异步+council 子任务的总花费)、`brain_first_token_ms`(网关 hang 早警)、`brain_call_latency_ms`、`tool_calls_total{name,ok}`、`budget_exceeded_total{code}`、`cost_quota_rejected_total`、`degraded_total{reason}`(1.40 降级)。
@@ -638,8 +672,12 @@ READ_DENY_PATTERNS='[{"pattern":"**/secrets/**"},{"pattern":".ssh","caseSensitiv
   ① **本机 env 显式恒赢**(逐键判)——env 是这台机器的部署主权,下发值不会静默盖掉它,被忽略的键留一条
   `sema_registry_read_face_env_wins` warn;② **坏值整域拒**——任何一个成员过不了引擎自己的校验器就整域不落、
   保留 env 前值 + `sema_registry_read_face_invalid` warn(半应用一份 READ 姿态比不应用更危险);
-  ③ **restart-to-apply**——四键在 boot 期被引擎装配捕获,下发改动经 `/health` 的 `restart.reasons`
-  带 `read-face` 通告,由编排器重启兑现。当前生效档可从 `GET /v1/capabilities` 的 `readFace` 位读
+  ③ **一席热、三席重启**(server 7.69.0 起,引擎侧交付了 read-face 的活体座席):`face` 是**热换席** ——
+  下发或撤回一个档位,下一拍 refresh(≤60s,或手动 `POST /v1/admin/config/refresh`)当场换进全部 Runner,
+  **不重启、也不再签 `read-face` 重启理由**(已在飞的任务保留它准备时的档位,新任务读新档);三个 deny 键
+  (`denyPatterns`/`denyBuiltinTiers`/`denyBuiltinExclude`)**仍是 boot-baked**(core 的可换席闭集只收了
+  `readFace` 一席),下发改动仍经 `/health` 的 `restart.reasons` 带 `read-face` 通告、由编排器重启兑现。
+  当前生效档可从 `GET /v1/capabilities` 的 `readFace` 位读
   (`"open"`/`"roots"`/`null`=本部署未钉,引擎默认当家;deny 表内容属策略内容,**不上**能力面);
   **来源**(env / center / posture / engine-default)在 operator 面 `GET /v1/diagnostics/wiring` 的 `readFace.source`。
   ⚠️ 本地 `config.d/` 车道今天**接不上**这一域(registry-core 的可移植域表里没有它),只有
@@ -1375,5 +1413,80 @@ GET /v1/capabilities?permissionMode=default
 **settings 层 kill-switch(件⑥)**:请求体 `settings.permissions.disableAutoMode` 受理 **`"disable"` / `true` / `false`** 三形(两套已发布契约的拼写:CC 250 的严极词 `"disable"`,与 `@sema-agent/sdk` `SettingsPermissions.disableAutoMode?: boolean`);受理集之外的值 400 `request.field_invalid`。
 `"disable"` 与 `true` **同义**:把该 run 的生效模式由 auto 折成 default(座不写 ⇒ 不武装;tighten-only,只能关不能开);`false` = 显式「不禁」= **合法且无效果**(本键没有放宽臂——它不是 auto 的开关)。`disableBypassPermissionsMode` 本批不落点。
 
-**per-run 面**:本批不在 run 记录上加 per-run `autoMode` 座——引擎侧的武装结果 / 未武装原因(含只有引擎知道的熔断类)
+**per-run 面**:本批不在 run 记录上加 per-run `autoMode` 座——引擎侧的武装结果 / 未武装原因(含只有引擎知道的那些;core 7.12.0 起熔断族已退役)
 将随 core 的状态座到货,届时 server 只投影不自算;此前 `armed` 是 server 侧三项可知判据的裁决。
+
+### 9.5 Web search:两车道优先级、per-request `settings.webSearch`、错误形
+
+**两车道,整段整取(不是逐键 merge)**:部署 env(`WEB_SEARCH_*`,§0)与 per-request `body.settings.webSearch`
+是唯二两条配置来源。当 per-request 那条腿"生效"(见下面的受理门槛)时,它产出一个**全新、完全独立**的
+`WebSearchBackendConfig`,**整只替换**掉 env 配出来的 backend —— 不是把 per-request 给的字段一个个覆盖到
+env 的 config 上,env 的其余字段(尤其是 `WEB_SEARCH_TIMEOUT_MS`)**不会**被继承到 per-request 那次调用里
+(`src/capabilities/scenarios.ts:264-266`):
+
+```
+const reqWebSearch = deps.requirePrincipal !== true
+  ? webSearchConfigFromSettings(req.settings?.webSearch)
+  : undefined;
+const webSearch = reqWebSearch ? createWebSearchBackend(reqWebSearch) : deps.webSearch;
+```
+
+`reqWebSearch` 非 `undefined`(即 `settings.webSearch.provider` 是合法词**且**本部署是单用户车道)时,
+`deps.webSearch`(env 配的 backend)整个不参与这次请求 —— 谁赢是**二选一**,不是字段级合并。
+
+**受理门槛(单用户车道)**:🔒 per-request `settings.webSearch` 只在 `REQUIRE_PRINCIPAL !== true`(单用户 /
+TOC 本地形)时被读取;`REQUIRE_PRINCIPAL=true`(多租户)上这个键**结构性够不着**——不是被拒、也不留任何
+`warn`/`capabilities` 位说"你发的 webSearch 被忽略了"(对比 `mcpServers` 有 `capabilities.mcpInjection` +
+`mcp_injection_dropped` 日志可读;`settings.webSearch` 没有对应的能力探测位,`src/http/wire-types.ts:320-323`)。
+原因是安全边界(与多租户能力配置隔离规则同源):per-request `endpoint`/`apiKey` 是能力配置,多租户下一个租户把 `searxng`
+指向内网地址就是 SSRF,所以多租户上只认部署 env 配的 backend。
+
+**`settings.webSearch` 键表**(`src/plugins/web-search.ts` `webSearchConfigFromSettings` §318-335;类型契约见
+`@sema-agent/sdk` 9.0.0 `settings.d.ts` `SettingsWebSearch`):
+
+| 键 | 类型 | 必填 | 默认 | 消费点 |
+|---|---|---|---|---|
+| `provider` | `"brave"｜"tavily"｜"searxng"` | 是(缺席/非三词之一 ⇒ 整个 `settings.webSearch` 被丢,回落到 env 的 backend,**不报错**) | 无 | `:321-322` |
+| `apiKey` | string(明文) | brave/tavily 建议带(缺了首次调用才报错,见下表);searxng 不读 | 无(不继承 env 的 `WEB_SEARCH_API_KEY`) | `:326` |
+| `endpoint` | string | searxng 必需(缺了首次调用才报错);brave/tavily 可选覆盖 | 无(不继承 env 的 `WEB_SEARCH_ENDPOINT`) | `:327` |
+| `searxngParams` | `Record<string,string>`(对象)或 `"k=v;k=v"`(字符串) | 否 | 无 | `:330-333`,解析逻辑与 env 腿共用 `parseSearxngParams`(`:260-277`)。⚠️ **未列入已发布的 `@sema-agent/sdk` 8.8.0 `SettingsWebSearch` 类型**(该接口只有 `provider`/`apiKey`/`endpoint`/`maxResults` 四键、无开放下标)——server 侧代码认这个键,但当前发布的 TS 类型接不到它;手写 JSON 请求体仍可以发,server 会照常解析(源码头注自述:字段和消费点先落地,配置录入面尚未跟上,是一笔尚未还清的既有债务) |
+| `maxResults` | number | 否 | 10(与 env 同一 clamp,`[1,20]`,小数向下取整) | `:323` |
+| *(无)* `timeoutMs` | — | — | — | **per-request 车道没有这个字段**——即便部署用 `WEB_SEARCH_TIMEOUT_MS` 配了非默认超时,per-request 生效那次调用永远退回 backend 自己的默认(10000ms,下限 1000ms),因为"整段整取"意味着 env 的 `timeoutMs` 根本不在 `reqWebSearch` 那个新对象里 |
+| *(无)* `fetchImpl` | — | — | — | 同上,仅测试注入用,per-request 车道不可达 |
+
+**门槛以外的键**:`settings.webSearch` 本身是 `TASK_SETTINGS_KEYS` 闭集里的受理顶层键
+(`src/task-settings.ts:309`,集外顶层键 400 `request.body_shape`),但 `webSearch` **自己的子键没有闭集门**
+——不像 `settings.permissions.*` 有 `TASK_SETTINGS_PERMISSION_KEYS` 逐键拒(`src/task-settings.ts:367-403`
+的 `taskSettingsKeyIssue` 只扫 `settings.*` 顶层和 `settings.permissions.*` 两层)。`settings.webSearch` 下
+塞一个上表之外的键(拼错的 `mxResults` 之类)**不会** 400,会被 `webSearchConfigFromSettings` 静默无视
+——门槛之外没有"未知键"这一说。
+
+**错误形**(逐条对应任务书里的四问;全部经**首次真实工具调用**才现形,均为 WebSearch 工具的
+`tool_result` 错误文本,回到模型的对话里,**不是** HTTP 层 `errorCode`,**不会**使 `TaskResult` 整体
+`failed`,也不拒启/不拒收请求本身;core `dist/tools/web.js:840-919` `createWebSearchTool` 统一兜底):
+
+| 触发条件 | 现象 | 是否 retryable(core `classifySearchFailure`) |
+|---|---|---|
+| 坏 `provider`(`settings.webSearch.provider` 非三词之一,或缺席) | **不是错误** —— `webSearchConfigFromSettings` 返回 `undefined`,整段回落到 env 配的 backend(env 也没配 ⇒ WebSearch 工具不装配,模型看不到这个工具);无 warn、无日志 | 不适用 |
+| 缺 `apiKey`(brave/tavily,env 或 per-request 均未给) | 首次调用抛 `WEB_SEARCH_API_KEY is required for the <provider> provider`,core 接住转成 `Error (WebSearch): the search backend failed. …` 文本回模型 | `"unknown"`(消息里没有 HTTP 状态码模式,`classifySearchFailure` 落最后一条默认分支) |
+| `searxngParams` 非对象/非字符串(如数字、布尔、`null`) | 静默丢弃——`parseSearxngParams` 落到"非 object 且非 string"分支,返回 `undefined`,键整个不铸,**不报错、不 warn** | 不适用 |
+| ⚠️ `searxngParams` 是**数组**(如 `["engines=bing"]`) | `typeof [] === "object"` 让它落进对象分支:`Object.entries` 按数组下标产出 `{"0":"engines=bing"}`——**不被拒绝**,但产出的键是数字字符串、值是未拆分的原始 `"k=v"` 串,传给 core adapter 的 `extraParams` 后是一组没有意义的查询参数(不是解析出 `engines=bing`)。这条边角只在 per-request 车道可达(env 值恒为字符串,不会触发);已用与源码逐字一致的独立复现脚本核验(见收车档),未改代码 | 不适用(不是异常路径) |
+| 搜索后端返回**非 2xx HTTP 响应**(鉴权失败/限流/服务端 5xx 等) | 三个 provider 各自的 `!res.ok` 分支抛错,消息形固定为 `"<provider> search failed (<status>): <body首 200 字符>"`(brave/tavily,`:158`/`:174`)或 `"SearXNG <status> <statusText> from <url>"`(searxng,core adapter) | ⚠️ **实测几乎恒为 `"unknown"`,不是按状态码分档**:`classifySearchFailure` 的状态码分支要求 `http`/`status`/`code`/`error` 四词之一紧邻数字前(`\D{0,12}`内),但本仓三个 adapter 的消息把状态码写在 `failed (…)`/`SearXNG …` 之后,不触发该分支;独立复现脚本核验(见收车档)brave/tavily/searxng 的 429/500/403/403 全部落到最后一条默认分支 `retryable:"unknown"`。**真正被分类对的只有两条兜底正则**:上游错误体文本里若真含 `"rate limit"` 才判 429 类 `true`,含 `"timed out"`/`"timeout"` 才判 408 类 `true`——都取决于上游返回的具体措辞,不是本仓能保证的 |
+| `endpoint` **网络层**不可达(连接被拒/DNS 解析失败/fetch 自身抛错,尚未拿到任何 HTTP 响应) | `fetch` 抛出的传输层错误(`ECONNREFUSED`/`ENOTFOUND`/`fetch failed` 等 Node/undici 标准措辞)被同一 `catch` 接住 | `true`——这条路径的错误文本天然含 `econnrefused`/`enotfound`/`fetch failed`/`dns` 等词,`classifySearchFailure` 的网络故障正则能命中(与上一行"已拿到 HTTP 响应但非 2xx"是两条不同的失败路径,别混淆) |
+
+⚠️ **"坏 provider 静默回落"这条对调用方是否可观察,取决于部署 env 有没有配 backend**:上表第一行说
+"env 也没配 ⇒ 工具不装配、模型看不到这个工具"——那只是**部署 env 同样缺席**这一种情形。若部署 env
+**已经**配了合法 backend(例如 `WEB_SEARCH_PROVIDER=brave`),调用方 per-request 传一个拼错的 `provider`
+(如 `"searx"`)、或带着一个本想打到自建 SearXNG 的 `endpoint`,`settings.webSearch` 整段被丢弃、静默回落
+到 env 的 brave backend——**WebSearch 工具照常挂载、照常可用**,查询实际发给了 env 配的 provider,不是
+调用方以为自己指定的那个;工具存在这一事实本身**不能**证明 per-request 的 `provider`/`endpoint` 真的
+生效了,两种情形(per-request 生效 / per-request 被静默丢弃回落 env)在壳侧不可判别(此条经独立复现验证,
+见收车档)。
+
+**`apiKey` 明文与 env 槽边界**:server 收到的 `settings.webSearch.apiKey` 是**明文字符串**,没有任何服务端
+密钥槽位/引用间接——收到什么字符串就直接进 backend 闭包(`:326`,与 `WEB_SEARCH_API_KEY` 同一条消费路径,
+`src/plugins/web-search.ts:63-64`)。**server 本批不改受理面**:明文字段的形状维持原样。调用方(壳)如何在
+自己机器上管理这份明文是调用方的事——例如 cli 壳侧的约定是在**调用方自己的环境**里按
+`SEMA_WEBSEARCH_KEY_<PROVIDER>` 这样的命名空间存放每个 provider 的 key,由壳在本地读出后把明文塞进请求体;
+这纯粹是**客户端约定**,本仓不读取、不校验、也不感知任何这类客户端侧 env 命名(这条命名事实来自任务书,
+本车未读 cli 源码核实,列入收车档「未闭环」)。

package/dist/adoption/plan.js

@@ -223,6 +223,17 @@ export const REBIND_LEGS = [
         residualKey: undefined,
         why: "resume 重放日志的 scope 守卫列 —— 与 run 行**同事务**(错配会让 load 守卫拒掉整条 resume)",
     },
+    {
+        leg: "workflow_agent_session#scope",
+        table: "workflow_agent_session",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined,
+        why: "S-185 workflow 出身 park 的 join 索引行的租户列(值 = 那条 run 的 `scope`,与 workflow_run/journal 同一个字节)——与它们**同族同事务**迁:不迁 ⇒ 索引行留在旧身份名下,而 run 行已迁,一次收编后人对这条 park 的批准结构上投递不出去",
+    },
     {
         leg: "workflow_resume_claim#scope",
         table: "workflow_resume_claim",

package/dist/approval-ask-machine.d.ts

@@ -34,7 +34,7 @@ export declare function canBatchTransition(from: BatchState, to: BatchState): bo
  * ── `legKey`(取代数值 `leg`,一腿一凭据)─────────────────────────────────────────────────────────────
  * = `sha256(resume checkpoint token)` 的 hex,**首腿 = 空串**。一次 park→resume 的 token 就是这条腿的
  * 天然身份:同 token 重投 = 同一腿(幂等,正确);新 park ⇒ 新 token ⇒ 新腿 ⇒ 新 askId。
- * 取摘要而非原始 token 是因为 token 是能力凭据(本仓有 `stripCheckpointToken` 专门把它从可重放账本里
+ * 取摘要而非原始 token 是因为 token 是能力凭据(本仓有 `stripResumeToken` 专门把它从可重放账本里
  * 剥掉),而 `askId` 是 wire 可见值 ⇒ **只存/只喂摘要**。用它当轴顺带消掉了原裁需要的 `task_run` 加列
  * 与 `markResuming` 返回加宽(后者有第二个调用点 `http/routes/runs.ts:463`,加宽会误杀已成功 resume 的
  * running run)。残留边界:同一 run 内**不经 checkpoint token** 的重入形若未来出现会得到同一 legKey ——

package/dist/approval-card.d.ts

@@ -328,6 +328,27 @@ declare const DenialLimitFallbackSchema: z.ZodObject<{
     autoDenyAfterMs: z.ZodNumber;
 }, z.core.$strict>;
 export type DenialLimitFallback = z.infer<typeof DenialLimitFallbackSchema>;
+/** S-185(core 7.10.0 [ref])—— **分类器为什么答不了**。`cause` 是 core 的闭集词
+ *  (`AUTO_MODE_UNAVAILABLE_CAUSES`;core 7.12.0 起 = error | timeout,`breaker_open` 随熔断族退役),
+ *  本仓**刻意不枚举**它:词表的单一
+ *  属主在 core,抄一份的形会在 core 加词那天把新词静默吞成缺席 —— 而丢的正是「这次不可用是新出现的那
+ *  一类」这条信息(与 `AskRequest.origin` 顶注同一条纪律)。判据只到「非空串」这一层形门。
+ *  `.strict()` + 单成员必填:core 将来给这只对象加成员时本读面当场判假、**整键不铸**,新成员必须由人
+ *  处置过才上 wire;而一个**没有 cause** 的空壳等于说「分类器坏了但说不出为什么」,比不说更坏。 */
+declare const ClassifierUnavailableSchema: z.ZodObject<{
+    cause: z.ZodString;
+}, z.core.$strict>;
+export type ClassifierUnavailable = z.infer<typeof ClassifierUnavailableSchema>;
+/**
+ * `AskRequest.classifierUnavailable`(core 7.10.0 [ref])的**边界窄读** —— 活卡帧与 `card_json` 的唯一
+ * 铸造点(与 {@link readDenialLimitFallback} 同款分工),两面结构性同值。
+ *
+ * 🔴 **缺席不是断言**:缺席同时覆盖「分类器答上了」「这只 ask 没资格走分类器」「本部署没接分类器」
+ * 三形(core d.ts 逐字:read presence, never absence),消费端禁读成「分类器好着呢」。
+ * 🔴 **echo-only**:server 不据它做任何裁决 —— 熔断/超时的处置全在 core 的分类器站,据本键在本仓自铸
+ * 第二套回落判据就是同一语义面两个写者(源头修复纪律)。
+ */
+export declare function readClassifierUnavailable(req: unknown): ClassifierUnavailable | undefined;
 /**
  * `AskRequest.denialLimitFallback`(core 7.4.0 [ref])的**边界窄读** —— 活卡帧与 `card_json` 的唯一铸造点
  * (与 {@link readRuleOffersAbsence} / {@link readProbeCause} 同款分工),两面结构性同值。
@@ -422,6 +443,9 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         }>;
         autoDenyAfterMs: z.ZodNumber;
     }, z.core.$strict>>;
+    classifierUnavailable: z.ZodOptional<z.ZodObject<{
+        cause: z.ZodString;
+    }, z.core.$strict>>;
     probeCause: z.ZodOptional<z.ZodObject<{
         code: z.ZodString;
         roots: z.ZodObject<{
@@ -532,6 +556,9 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             }>;
             autoDenyAfterMs: z.ZodNumber;
         }, z.core.$strict>>;
+        classifierUnavailable: z.ZodOptional<z.ZodObject<{
+            cause: z.ZodString;
+        }, z.core.$strict>>;
         probeCause: z.ZodOptional<z.ZodObject<{
             code: z.ZodString;
             roots: z.ZodObject<{

package/dist/approval-card.js

@@ -237,6 +237,14 @@ const DenialLimitFallbackSchema = z
 const _denialLimitFallbackConformance = [true, true];
 void _denialLimitFallbackConformance;
 const DenialLimitFallbackEnvelopeSchema = z.object({ denialLimitFallback: DenialLimitFallbackSchema.optional() });
+const ClassifierUnavailableSchema = z.object({ cause: z.string().min(1).max(MAX_IDENT) }).strict();
+const _classifierUnavailableConformance = [true];
+void _classifierUnavailableConformance;
+const ClassifierUnavailableEnvelopeSchema = z.object({ classifierUnavailable: ClassifierUnavailableSchema.optional() });
+export function readClassifierUnavailable(req) {
+    const parsed = ClassifierUnavailableEnvelopeSchema.safeParse(req);
+    return parsed.success ? parsed.data.classifierUnavailable : undefined;
+}
 export function readDenialLimitFallback(req) {
     const parsed = DenialLimitFallbackEnvelopeSchema.safeParse(req);
     return parsed.success ? parsed.data.denialLimitFallback : undefined;
@@ -261,6 +269,7 @@ export const ApprovalCardSchema = z
     ruleOffers: z.array(RuleOfferSchema).max(MAX_RULE_OFFERS).optional(),
     ruleOffersAbsence: RuleOffersAbsenceSchema.optional(),
     denialLimitFallback: DenialLimitFallbackSchema.optional(),
+    classifierUnavailable: ClassifierUnavailableSchema.optional(),
     probeCause: ProbeCauseSchema.optional(),
     ruleEvidence: RuleEvidenceSchema.optional(),
     fromSubagent: z.literal(true).optional(),
@@ -303,6 +312,7 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
     const ruleEvidence = readRuleEvidence(req);
     const ruleOffersAbsence = readRuleOffersAbsence(req);
     const denialLimitFallback = readDenialLimitFallback(req);
+    const classifierUnavailable = readClassifierUnavailable(req);
     const toolCallId = clip(source.toolCallId, MAX_IDENT);
     const sourceTaskId = clip(source.sourceTaskId, MAX_IDENT);
     const sourceAgentName = clip(source.sourceAgentName, MAX_AGENT_NAME);
@@ -325,6 +335,7 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
         ...(source.ruleOffers !== undefined && source.ruleOffers.length > 0 ? { ruleOffers: source.ruleOffers.map(copyRuleOffer) } : {}),
         ...(ruleOffersAbsence !== undefined ? { ruleOffersAbsence } : {}),
         ...(denialLimitFallback !== undefined ? { denialLimitFallback } : {}),
+        ...(classifierUnavailable !== undefined ? { classifierUnavailable } : {}),
         ...(source.fromSubagent === true ? { fromSubagent: true } : {}),
         ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
         ...(sourceAgentName !== undefined ? { sourceAgentName } : {}),

package/dist/approval-reconciler.d.ts

@@ -1,57 +1,3 @@
-/**
- * 流内审批协议([ref] §3.0)的**对账收敛器** —— [ref] 车5。
- *
- * 职责一句话:把 `PARKING`(窗到期中选、正在转投递面)这个**唯一的非终态中间态**收敛成
- * `PARKED | DENIED | VOID`,并在崩溃后补位那些没人打 expire 的孤儿 `STREAM_PENDING` 行。
- *
- * ── 判据表 v2(设计稿 §9 尾的五臂汇总,逐字落地;每臂注读口)────────────────────────────────────────
- *  ① **身份三元组 ∧ hash 双等** ⇒ `bindBatch`(判别式返回;`ok:false` ⇒ 降级续判)
- *     身份 = `sourceTaskId` 相等 ∧ `toolCallId` 相等 ∧ **因果下界**(不是等式)`cp.createdAtMs ≥
- *     ask.createdAtMs`;再 ∧ `cp.boundInputHash === ask.boundInputHash`。三维里只有前两维是等式,把时间
- *     那一维读成等式会让合法 park 几乎命不中。逐字实现在 {@link classifyGateMatch};判据的**唯一
- *     属主**是那个函数的头注,这里只列纲要,细则(祖先层 fold 否决、多候选取舍)不在此复述。
- *     🔴 两处易错,写在这里免得下一个人照旧口径改码:
- *      · 承重的第一维是 **`sourceTaskId`**([ref] 件1,黑板 [ref]③①)——`sessionId` **不进身份等式**
- *        (委派子代的 ask 落行记的是投递上下文的根会话,park 却发生在子代自己的 sessionId 上,只按
- *        session 等值会张冠李戴),它在这一层只是读口 `findCheckpointCandidatesForAsk` 的入参。
- *        ⚠️ 但别据此把它当无用键:{@link isAncestorFoldMint} 的祖先层否决判的正是
- *        `sourceTaskId !== sessionId` —— 那是内存里的承重用法,只是不属于身份等式;
- *      · hash **任一侧缺席一律不 bind**(硬相等不放宽,理由同下)。缺席的**归因**分两级,别写成一句:
- *        身份先判 —— 同身份候选一条都没有且候选集非空 ⇒ `identity_miss`(有对家但不是这一只,或读不出);
- *        只有在身份这一层没被判掉时,hash 缺席才落 `single_mint` 三形
- *        (`ask_only` / `checkpoint_only` / `neither`)。`single_mint` 是可观测分类、不是放宽的命中;
- *        把「只有一侧铸过」这格结构事实混进 `identity_miss` 的噪声底,运维就读不出两者的区别。
- *     两道等式都不许放宽的原因不变(§9 C2:同 session 内 `toolCallId` 会被网关重用,身份不严会把旧 ask
- *     PARK 到别人的 resume 坐标上,而 `PARKED` 是不可回滚的终态)。读口 = `findCheckpointCandidatesForAsk`
- *     (§9 C4 窄谓词精确查,无分页假阴性);`unparseable` 候选**视同不匹配**(单行读不出不许打断整段
- *     扫描,§8 C-6)。
- *  ② run 终局分臂(读口 `runStore.getRun`):`status ∈ {completed, failed, blocked}`(§8 A-1 词表修正 ——
- *     `cancelled` 不是 run 状态,取消 = `failed` + `errorCode`)——
- *       - `failed ∧ errorCode === "cancelled"`,或批行已 `ABORTED` ⇒ `VOID`(取消不是路由失败,§9 C3);
- *       - 其余终局 ⇒ `DENIED(routing_failure_fail_closed)`。**全仓唯一的 DENIED 写点**(grep 钉)。
- *  ②′ **bind-once 落选者**(codex round2 R2-3 增补,排在 ② 之前判):批已 `ROUTING_BOUND` 且中选者是
- *     兄弟 ⇒ `VOID(batch_bound_elsewhere)` —— 迟到进 PARKING 的行(`bindBatch` 的原子事务连坐不到它)
- *     结构上再也赢不了 bind,当下即可判;不判会让它滞留到 run 终局再被 ② 误报成路由失败。
- *  ③ else(run 还在跑 / suspended / needs_review / 无行且不满足 ④)⇒ **保持 PARKING** + `deferReconcile`
- *     touch(推 `updated_at_ms` 排到队尾,配合 `listByState` 的 `ORDER BY updated_at_ms ASC` 解队头堵塞,
- *     §8 D-4 / §9 C5)。**超时永不产生终态 denial**(约束②)。
- *  ④ adhoc 双谓词(`sessionId === taskId` ∧ `getRun` 无行,§8 C-2)∧ 窗过 + `ADHOC_GRACE` ⇒ `VOID`
- *     (归因 `adhoc_leg_no_durable_domain`)。
- *  ⑤ `createdAtMs` 量的 `ORPHAN_TTL` ⇒ `VOID(orphan_ttl_exceeded)` + warn ——「任何未在 TTL 内收敛的
- *     PARKING」的最后兜底(§8 A-1 放宽形,不限「getRun 无行」),约束①(遗孤最终可判)。
- *     🔴 TTL 一律量 immutable 的 `createdAtMs`/`expiresAtMs`,**绝不量 `updatedAtMs`**(它被 ③ 的队列
- *     轮转每轮刷新,量它的 TTL 永不到期,§9 C5)。
- *
- * ── 三条铁则 ────────────────────────────────────────────────────────────────────────────────────
- *  1. **一经发布的终态不改义**:本模块只从 `PARKING`/`STREAM_PENDING` 出发,`PARKED/DECIDED/DENIED/VOID`
- *     的行永不再被碰(CAS 的 `WHERE state=?` 谓词是机器保证,不靠调用序自觉)。
- *  2. **幂等可重放**:两副本同扫无害——每条转移都是带 `from` 态的 CAS,单赢者;输者本轮什么都不做。
- *  3. **宁可不命中,绝不错配**:判别不出(hash 缺席 / 候选 `unparseable` / 列与 blob 矛盾)一律落 ②③⑤,
- *     绝不发一张别人的 resume 凭据。
- *
- * 命名(CLAUDE.md 工厂命名律):`decideReconcileAction`/`selectGateCandidate` 是纯判定函数;
- * `createApprovalReconciler` 返回带方法的活对象 ⇒ `create*`。
- */
 import type { AskRow, ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
 import type { BatchState } from "./approval-ask-machine.js";
 import type { CheckpointAskCandidate } from "./plugins/checkpoint-store-sql.js";

package/dist/approval-reconciler.js

@@ -1,8 +1,8 @@
+import { CANCELLED_CODE } from "./run-cancel-context.js";
 import { isTerminalRunStatus } from "./plugins/store-contracts.js";
 import { DENY_REASONS, VOID_REASONS } from "./approval-deny-reasons.js";
 import { buildRevokeFrame } from "./approval-card.js";
 import { encodeCheckpointScope } from "./security.js";
-const CANCELLED_ERROR_CODE = "cancelled";
 const RECONCILE_STORE_TIMEOUT_MS = 10_000;
 const RECONCILE_SEGMENT_BUDGET_MS = 30_000;
 function withDeadline(op, label, timeoutMs = RECONCILE_STORE_TIMEOUT_MS) {
@@ -64,7 +64,7 @@ export function decideReconcileAction(input) {
         return { kind: "void", reason: VOID_REASONS.BATCH_BOUND_ELSEWHERE };
     }
     if (run !== null && isTerminalRunStatus(run.status)) {
-        if (run.status === "failed" && run.errorCode === CANCELLED_ERROR_CODE) {
+        if (run.status === "failed" && run.errorCode === CANCELLED_CODE) {
             return { kind: "void", reason: VOID_REASONS.RUN_CANCELLED };
         }
         return { kind: "deny", reason: DENY_REASONS.ROUTING_FAILURE };

package/dist/approval.js

@@ -1,4 +1,5 @@
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "@sema-agent/core";
+import { operatorAsk } from "./operator-ask.js";
 import { isExplicitPosture } from "./posture-source.js";
 export function hasOperatorGateIntent(config) {
     return (config.approvalRequire.length > 0 ||
@@ -51,11 +52,11 @@ export function createDurableAskPolicy(opts) {
             if (deny(toolName))
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             if (neverAuto(toolName))
-                return { action: "ask", message: `human approval required to run "${req.toolName}"` };
+                return operatorAsk(`APPROVAL_NEVER_AUTO(${toolName})`, `human approval required to run "${req.toolName}"`);
             if (require(toolName)) {
                 const remEarly = req.budget?.resourceRemainingMicroUsd;
                 if (remEarly !== undefined && remEarly <= 0) {
-                    return { action: "ask", message: `durable resource budget exhausted — human approval required to run "${req.toolName}"` };
+                    return operatorAsk("RESOURCE_SUSPEND budget exhausted", `durable resource budget exhausted — human approval required to run "${req.toolName}"`);
                 }
                 if (opts.exempt && toolName !== "AskUserQuestion") {
                     return (async () => {
@@ -81,13 +82,13 @@ export function createDurableAskPolicy(opts) {
     function decideRequired(req, toolName) {
         const rem = req.budget?.resourceRemainingMicroUsd;
         if (rem !== undefined && rem <= 0) {
-            return { action: "ask", message: `durable resource budget exhausted — human approval required to run "${req.toolName}"` };
+            return operatorAsk("RESOURCE_SUSPEND budget exhausted", `durable resource budget exhausted — human approval required to run "${req.toolName}"`);
         }
         if (toolName !== "AskUserQuestion" && budget > 0 && autoApproved < budget) {
             autoApproved++;
             return { action: "allow" };
         }
-        return { action: "ask", message: `approval required to run "${req.toolName}"` };
+        return operatorAsk(`APPROVAL_REQUIRE(${toolName})`, `approval required to run "${req.toolName}"`);
     }
 }
 //# sourceMappingURL=approval.js.map

package/dist/boot/config-center.d.ts

@@ -1,4 +1,4 @@
-import { CenterPromptSource, type Model } from "@sema-agent/core";
+import { CenterPromptSource, type SwappableDeps } from "@sema-agent/core";
 import { buildPricing } from "../budget.js";
 import { type PromptsDomainFaces } from "../prompts-domain-validate.js";
 import { type Scenario, type ScenarioDeps, type ScenarioDetail } from "../capabilities/scenarios.js";
@@ -42,16 +42,15 @@ export interface ConfigCenterRuntime {
     /** 60s refresh cadence + boot-deferred 到货续接。
      *  `limitSync`([ref] 批1)= 恒构造的两只限额座的换代口:commit 之后**零 await 内**推一把,与 pricing /
      *  keyResolver 那两件派生重建同族(缺席 = 这条腿本部署没装配,例如 run-local)。
-     *  `swapRunnerModels`(core 5.49,[ref]①)= 模型面永久热的换装口:plane 变更候选在 commit 前喂给
-     *  全部 boot Runner 原子换代;在场 ⇒ models-tiers defer/restart 臂退役,缺席 ⇒ 旧 defer 行为逐字保留。 */
+     *  `swapRunnerDeps`(core 7.10.0 `Runner.swapDeps` 一扇门;5.49 起的 `swapModels` 口在 7.10.0 退役、
+     *  本参数同语义改名)= **可换席**的换装口:模型面 plane 变更候选在 commit 前喂给全部 boot Runner
+     *  原子换代(在场 ⇒ models-tiers defer/restart 臂退役,缺席 ⇒ 旧 defer 行为逐字保留);S-174 起
+     *  read **face** 席也走同一只函数(见 refresh 拍里的 `applyCenterReadFace` 调用点)。 */
     startRefreshLoop(a: {
         runnerTierFrozen: boolean;
         pricing: ReturnType<typeof buildPricing>;
         limitSync?: LimitSync;
-        swapRunnerModels?: (plane: {
-            models: Record<string, Model>;
-            tiers: Record<string, string>;
-        }) => void;
+        swapRunnerDeps?: (next: SwappableDeps) => void;
     }): void;
     /** [ref]-2:停刷新环(hardShutdown 收尾链;幂等,未起环时 no-op)。 */
     stopRefreshLoop(): void;

package/dist/boot/config-center.js

@@ -328,7 +328,8 @@ export async function createConfigCenterRuntime(ctx) {
             }
         }
     }
-    const readFaceEnvHeld = applyCenterReadFace(config, effective ?? { version: 0, updatedAt: "", models: { models: [], roles: {} } }, effective ? logger : undefined);
+    const readFaceBaseline = { ...(config.readFace !== undefined ? { readFace: config.readFace } : {}), readFaceSource: config.readFaceSource };
+    const readFaceEnvHeld = applyCenterReadFace(config, effective ?? { version: 0, updatedAt: "", models: { models: [], roles: {} } }, effective ? logger : undefined).envHeld;
     if (!modelReadyState.ready)
         logger.warn("model_roster_pending", {
             note: "CONFIG_REQUIRE_ROSTER=true and no center roster has landed yet — the env MODEL_ID is treated as a PLACEHOLDER, so billable submissions 503 (and /health reports ready:false) until the first effective pull lands ≥1 enabled model. Unset the knob if this worker's env model is authoritative.",
@@ -341,6 +342,26 @@ export async function createConfigCenterRuntime(ctx) {
         ...(readFaceEnvHeld.length > 0 ? { readFaceEnvHeld } : {}),
         ...(mcpRevocationWired && mcpRevocations.hasBaseline() ? { mcpRevocationLive: true } : {}),
     });
+    const applyLiveReadFace = (eff, swap, phase) => {
+        const before = config.readFace;
+        const beforeSource = config.readFaceSource;
+        const { faceChanged } = applyCenterReadFace(config, eff, logger, { phase: "live", baseline: readFaceBaseline });
+        if (!faceChanged)
+            return;
+        if (swap === undefined) {
+            logger.warn("read_face_swap_unwired", { face: config.readFace ?? null, phase, note: "the center's read FACE changed but no Runner swap door was wired — the value landed in config while the engine keeps the seat it booted with" });
+            return;
+        }
+        try {
+            swap({ readFace: config.readFace });
+            logger.info("read_face_swapped", { from: before ?? null, to: config.readFace ?? null, phase, note: "hot seat (core swapDeps) — legs that already prepared keep the face they prepared under" });
+        }
+        catch (err) {
+            config.readFace = before;
+            config.readFaceSource = beforeSource;
+            throw err;
+        }
+    };
     let ccTimer;
     return {
         providerKind: configProvider?.kind,
@@ -489,7 +510,7 @@ export async function createConfigCenterRuntime(ctx) {
             }
         },
         startRefreshLoop(a) {
-            const { runnerTierFrozen, pricing, limitSync, swapRunnerModels } = a;
+            const { runnerTierFrozen, pricing, limitSync, swapRunnerDeps } = a;
             if (configProvider) {
                 const ccRef = config.configCenter;
                 let refreshInFlight = false;
@@ -555,7 +576,7 @@ export async function createConfigCenterRuntime(ctx) {
                             }
                             else {
                                 const planeChanged = modelPlaneChanged(appliedPlaneEff, r.effective);
-                                const planeDeferred = swapRunnerModels === undefined && (runnerTierFrozen || planeHasActiveTiers(r.effective)) && planeChanged;
+                                const planeDeferred = swapRunnerDeps === undefined && (runnerTierFrozen || planeHasActiveTiers(r.effective)) && planeChanged;
                                 let applyReport;
                                 const committed = applyEffective(config, r.effective, logger, {
                                     teamsOnly: true,
@@ -566,7 +587,7 @@ export async function createConfigCenterRuntime(ctx) {
                                         applyLedger.recordApply(rep);
                                     },
                                     ...(planeDeferred ? { deferModelPlane: true } : {}),
-                                    ...(swapRunnerModels !== undefined && planeChanged ? { swapPlane: swapRunnerModels } : {}),
+                                    ...(swapRunnerDeps !== undefined && planeChanged ? { swapPlane: swapRunnerDeps } : {}),
                                 });
                                 if (!committed)
                                     return "ok";
@@ -574,6 +595,7 @@ export async function createConfigCenterRuntime(ctx) {
                                 keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
                                 limitSync?.sync();
                                 mcpRevocations.applyEnabledEntries(enabledMcpEntries(r.effective.mcp));
+                                applyLiveReadFace(r.effective, swapRunnerDeps, "refresh");
                                 applyLedger.applied(tickGen, r.effective.version);
                                 if (planeDeferred) {
                                     logger.warn("models_tiers_plane_deferred", { version: r.effective.version, note: "tier-frozen Runner: the changed model plane (models/roles/tiers/default) is NOT hot-applied — admission stays on the Runner's generation; restart applies the new plane (models-tiers restart signal rides /health)" });
@@ -596,7 +618,7 @@ export async function createConfigCenterRuntime(ctx) {
                                 }
                                 const lkgPersisted = await persistLkgDurable(r.effective, r.etag);
                                 const reasons = restartReasons(effective, r.effective, restartCtx());
-                                if (swapRunnerModels !== undefined) {
+                                if (swapRunnerDeps !== undefined) {
                                     const mi = reasons.indexOf("models-tiers");
                                     if (mi >= 0)
                                         reasons.splice(mi, 1);
@@ -701,7 +723,7 @@ export async function createConfigCenterRuntime(ctx) {
                         return;
                     }
                     const planeChangedLate = modelPlaneChanged(appliedPlaneEff, r.effective);
-                    const planeDeferredLate = swapRunnerModels === undefined && (runnerTierFrozen || planeHasActiveTiers(r.effective)) && planeChangedLate;
+                    const planeDeferredLate = swapRunnerDeps === undefined && (runnerTierFrozen || planeHasActiveTiers(r.effective)) && planeChangedLate;
                     let applyReportLate;
                     const committedLate = applyEffective(config, r.effective, logger, {
                         teamsOnly: true,
@@ -712,13 +734,14 @@ export async function createConfigCenterRuntime(ctx) {
                             applyLedger.recordApply(rep);
                         },
                         ...(planeDeferredLate ? { deferModelPlane: true } : {}),
-                        ...(swapRunnerModels !== undefined && planeChangedLate ? { swapPlane: swapRunnerModels } : {}),
+                        ...(swapRunnerDeps !== undefined && planeChangedLate ? { swapPlane: swapRunnerDeps } : {}),
                     });
                     if (!committedLate)
                         return;
                     mutateInPlace(pricing, buildPricing(config.models));
                     keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
                     limitSync?.sync();
+                    applyLiveReadFace(r.effective, swapRunnerDeps, "boot-deferred");
                     applyLedger.applied(lateGen, r.effective.version);
                     if (planeDeferredLate)
                         logger.warn("models_tiers_plane_deferred", { version: r.effective.version, note: "tier-frozen Runner (env tiers): the late-boot center model plane is NOT hot-applied — restart applies it" });
@@ -743,7 +766,7 @@ export async function createConfigCenterRuntime(ctx) {
                     ccEtag = r.etag;
                     const lkgPersistedLate = await persistLkgDurable(r.effective, r.etag);
                     const reasons = restartReasons(undefined, r.effective, restartCtx());
-                    if (swapRunnerModels !== undefined) {
+                    if (swapRunnerDeps !== undefined) {
                         const miLate = reasons.indexOf("models-tiers");
                         if (miLate >= 0)
                             reasons.splice(miLate, 1);

package/dist/boot/leader.js

@@ -50,7 +50,7 @@ export function createLeaderFace(ctx) {
                 lockedConfig: governanceSeams.lockedConfig,
                 retentionPolicy: governanceSeams.retentionPolicy,
             },
-            deploymentPosture: buildDeploymentPostureSeats(config),
+            deploymentPosture: () => buildDeploymentPostureSeats(config),
             ...(ctx.tracer ? { tracer: ctx.tracer } : {}),
             ...(config.usageWindows && ctx.usageWindowStore
                 ? { usageWindows: config.usageWindows, usageWindowStore: ctx.usageWindowStore }