@sema-agent/server 7.127.1 → 7.128.0

package/MIGRATION.md

@@ -7,6 +7,45 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.128.0 —— 本地 `config.d/skills.json` 生效 · 部署侧 MCP `toolAxes` 进引擎(坏形整条不挂)· 宿主 shell 两行运维行 · 7.127.2 第 1 条两句订正(升级零动作)
+
+1. **本地部署的 `config.d/skills.json` 开始生效(行为修复,零 DDL、无配置变化)**:`CONFIG_PROVIDER=local` 的部署此前只装出厂技能,`config.d/skills.json` 的条目从不进名册(零提示;
+   同一目录的 `mcp.json` 是生效的)。本版起 HTTP 服务起服与 `run-local` 都按名把这些条目盖在出厂技能上,与配了中心的部署同一条路径;`enabled: false` 的不装。
+   - **谁受影响**:写着 `skills.json` 的本地部署 —— 升级后那些技能真进名册,模型看得见的技能清单(从而可用的工具面)可能变化,同名条目盖掉出厂技能。
+   - **做法**:不想要的条目写 `enabled: false` 或删掉文件;起服日志每装上一条一行 `web_admin_skill`(带 `overrodeBuiltin`),拿不到正文的一条一行 `web_admin_skill_failed`(`reason`)。
+     与 MCP 同,改了 `skills.json` 要重启才生效(刷新拍后 `/health` 的 `restart.reasons` 含 `skills`)。技能的来源与覆盖序见 USAGE「技能从哪来」。
+2. **部署侧 MCP 条目的 `toolAxes` 进引擎(新能力,零动作)**:`config.d/mcp.json` 与配置中心的 MCP 条目若写了 `toolAxes`(按工具名声明 `effect` / `egress` / `irreversibility`),本版起进引擎 spec、喂审批门;此前只承载不读。坏形(词外 / `egress` 非布尔 / 未知成员)⇒ **这条 server 整条不挂**,起服一行 `web_admin_mcp_tool_axes_invalid` 点名 server 与工具名、兄弟 server 照挂 —— 此前坏形被静默忽略、server 照挂。
+   - **谁受影响**:条目里早就写着 `toolAxes` 的部署 —— 合法的本版起真生效(调用的审批姿态可能变),坏形的那条 server 本版起不挂(改条目即恢复)。
+3. **宿主车道两行新运维行(零动作)**:`REMOTE_EXEC=host`(含 `run-local`)起服时解析一次本机 shell;Windows 上找不到 Git Bash ⇒ `warn host_shell_unavailable { err, remedy }`,解析到 / 装好后拾起 ⇒ `info host_shell_resolved { shell }`(按状态转换打,每条 Bash 不打);macOS / Linux 不打。找不到不挡起服,Bash / hooks 到 spawn 时以真因拒。
+4. **订正 7.127.2 节第 1 条两句**(已发节正文只读):(a)「账本面不存媒体字节」是**读面与新写行**的律 —— 7.127.0 / 7.127.1 写下的存量行里的字节仍在店里(file 后端 `events.jsonl` 逐位不变),读面隐藏而不改写存量行,回滚到旧版又读得到;要清掉只能走会话删除或留存到期。(b)「整图只在活流与子代 tail 流上」按字面不成立 —— 会话存档 `GET /v1/sessions/:id`(会话树自己的内容,续轮回送模型)的 `messages[].content[].data` 与 `messages[].details.file.base64` 两处都带整图,7.127.x 与本版同;本版只是让后一处的字节座位不再过文本脱敏(此前碰巧成凭据形的子串会被改写成占位、图读坏)。
+
+## 7.127.2 —— 账本行 details 卡的媒体字节不落账(行为修复)· 缺省部署自动整理被引擎拒(披露)· 7.127.0 节三条订正(升级零动作)
+
+升级零动作:无 DDL、无配置变化。本节是对 7.127.0 节的三条订正(已发节正文只读,订正记在此处)。
+
+1. **订正 7.127.0 节第 1 条「账本面只存描述符 … 这类客户端本版拿不到整图」(行为修复,持久数据面,升级零动作)**:7.127.0 / 7.127.1 上只有 `output` 的媒体块在账本面是描述符,
+   同一行里 Read 图像 / PDF 的 details 卡 `structured`(`{ type: "image" | "document", file: { base64?, … } }`)的 `file.base64`(引擎只在 ≤48K 字符时随卡)仍随账本行落库,并在
+   `GET /v1/runs/:id/events`、`GET /v1/tasks/:id/turns`、`GET /v1/tasks/:id/stream` 的回放上出现 —— 描述符想省的那份字节还在行里。本版起一条律:**媒体字节不落账,不论它骑在 `output` 的块上还是 `structured` 卡的字段上**。
+   - **账本面**:卡上去掉 `file.base64` 这一个键(其余成员逐字;与引擎对超 48K 的卡自己略去该键的形一致),存量行在读面上同样不再带;帧级 `truncated` / `totalChars` 仍只说 `output`。
+   - **活面**:`structured` 逐字(`file.base64` 不过文本脱敏,卡上其余成员照常脱敏);连接积压判据把它与 `output` 媒体块的字节同一帧一起计,降级时一并去掉。
+   - **谁需要**:读账本回放面的消费方与存账本的部署;**谁受伤**:从回放面的 `structured.file.base64` 取图的客户端(整图本来只在 `/v1/tasks/stream` 与子代 tail 流上);**补偿**:要图读活流;按「`file.base64` 缺席」渲染(引擎超 48K 的卡本就是这个形)。
+2. **订正 7.127.0 节漏项:k8s 车道沙箱出网策略(安全面,部署;7.127.0 起已生效)**:7.127.0 的 CHANGELOG 段写了这一条,随包的本文件 7.127.0 节漏了。`REMOTE_EXEC=k8s` 的部署读下面几行:
+   - **出网边界**:沙箱 ns 的 egress 白名单对集群外只放行 **IPv4 公网面** —— 私网 / 共享 / 链路本地 / 环回六段(`10/8`、`172.16/12`、`192.168/16`、`100.64/10`、`169.254/16`、`127/8`)整段不放行,
+     公网面上的集群地址按 `clusterCidrs` 与 `nodeCidrs`(`kube-up.sh` 遍历**全部节点**的全部 IPv4 Internal / External 地址自动填;读不出 ⇒ 拒装)再除外。此前是一张点名表,只盖第一只节点的第一只 InternalIP。
+   - **IPv6**:不写放行规则(NetworkPolicy 只有放行规则,写 `::/0` 只会放宽);缺省 `K8S_SANDBOX_IPV6=enabled` **不关** pod 的 IPv6 —— 只执行 IPv4 的策略实现(k3s 单栈缺省即是)管不到 pod 的 IPv6,链路本地 v6 照通,
+     起服自检每次起服一行 `sandbox_egress_policy_gap{kind: "ipv6_enabled"}` 提醒。要在 pod 侧关,设 `K8S_SANDBOX_IPV6=disabled`(chart `sandbox.ipv6: disabled`;前提:**每个节点**的 kubelet 带 `--allowed-unsafe-sysctls` 放行
+     `net.ipv6.conf.all.disable_ipv6` 与 `net.ipv6.conf.default.disable_ipv6`,沙箱 ns 不 enforce PodSecurity `baseline` / `restricted`;没放行的节点上沙箱 pod 起不来)。
+   - **谁受伤**:沙箱要访问集群外**私网地址**上的包源 / 代码托管 / 对象存储的部署(升级后到不了);手写 values 在 `nodeCidrs` / `clusterCidrs` 里写了 IPv6 或不带前缀的项的部署(chart 渲染拒并点名);
+     手写 RBAC 的部署(chart 多两只只读授权:沙箱 ns 的 `networkpolicies` get / list,与集群级 `nodes` get / list —— 没给时起服自检一行 `unreadable`)。
+   - **补偿**:在沙箱 ns 另建一条 NetworkPolicy 放行那个私网地址(或那台主机的 /32)—— 策略按并集叠加,chart 升级不碰它;手写 RBAC 的部署补上面两只只读授权;没有上报进节点对象的公网地址(1:1 NAT 的弹性 IP 一类)要自己写进 `nodeCidrs`。
+     这张策略是收窄、不是边界:所在节点的往来流量由 CNI 的实现决定,宿主上被 DNAT 的发布端口在策略之前改写目的地址,CNI 不执行 NetworkPolicy 时整张不生效(射程见 USAGE §9.3e)。
+3. **订正 7.127.0 节第 4 条「记忆整理按人的路径规则判写」(披露:引擎缺陷,本版行为不变)**:那一条在缺省部署上不成立 —— 只要部署的敏感路径守卫在场(`SENSITIVE_WRITE_PATTERNS` 未设即在场),
+   自动整理**每一次**都被拒(`memory.consolidation_refused`,`detail.refusalCode = memory.consolidation_write_refused`),与有没有点名库路径的规则、权限模式无关:引擎问写判官时递给部署策略的是一只已中止的信号,
+   守卫因此判不了库目录的真实落点、按 `target_unresolved` 拒。通告的人读句只带拒因的前 200 字,`detail` 没有原因成员。修复在引擎,随下一次引擎提货生效。
+   - **谁受影响**:开着自动整理的部署(缺省开)。用户任务不受影响,库不被改写。
+   - **做法**:要整理就用手动阀门 `POST /v1/admin/memory/consolidation/run`(它不问这只判官,与第 4 条所写同);按 `memory.consolidation_refused` 告警的,知道它今天是这个成因。
+     不要为此设 `SENSITIVE_WRITE_PATTERNS=off`(那会撤掉敏感路径的写拦截)。
+
 ## 7.127.1 —— Windows 宿主车道:策略链读 `cdPath` 不再因 shell 未落定而拒每条 Bash(行为修复,升级零动作)
 
 升级零动作:无 DDL、无配置变化、无 wire 变化。**谁受影响**:Windows 宿主部署里 server 进程环境找不到 Git Bash 的(PATH 无 Git、`ProgramFiles` 不对、经 ssh 起服白名单环境等)—— 7.127.0 及之前每条 Bash 都被策略链拒成「policy check threw / aborted」且真因被吞;本版起策略链读 `cdPath` 不再碰 shell,命令真要跑时才以真因拒(装 Git for Windows 或设 `HOST_SHELL_PATH`)。装了 Git Bash 的普通部署行为不变。回滚到 7.127.0 安全。

package/USAGE.md

@@ -646,6 +646,13 @@ MODEL_CASCADE_LADDER=deepseek-flash,deepseek-pro   # 目录里的模型名,cheap
   `projectContext` / `callerCwd` 回答(那两位的判据多一条单用户约束;多租户 ∧ host 部署自 7.104.0 起拒启,这一形的分叉不再可达)。
   端点/凭据/镜像/`serial` 一个字都不上这条 wire,那些仍只在 operator 面 `GET /v1/config/catalog`。
 
+**宿主车道的 shell(Windows 宿主;7.128.0 起成文)**
+- 宿主车道(`REMOTE_EXEC=host`,含 `run-local`)的 Bash、后台 shell 与 hooks 的 command 条目都用本机 POSIX shell 起。Windows 上是 Git Bash:`HOST_SHELL_PATH` 显式覆写,否则 Git for Windows 安装目录,
+  再否则 PATH 里的 `bash.exe`;`System32` 下的 `bash.exe` 是 WSL 启动器,刻意不认。**起服时解析一次**,找不到不挡起服。
+- 两行运维行(进程级,**按状态转换打**:同态重复解析、每条 Bash 都不再打):`warn host_shell_unavailable { err, remedy }` —— 找不到可用的 bash;`err` 是脱敏后的原因,`remedy` 是出路句
+  (装 Git for Windows,或把 `HOST_SHELL_PATH` 设到 bash.exe);`info host_shell_resolved { shell }` —— 解析到了(起服成功,或失败之后装好 / 改好被下一次解析拾起),`shell` 是解析到的路径。
+- 找不到时:宿主车道的其它工具照常;要起 shell 的调用到 spawn 时以同一句真因拒(`shell_unavailable` / hook 故障帧),装好后下一次调用自动拾起,不用重启。macOS / Linux 不打这两行。
+
 **workspace 浏览面 —— 已随整树快照纪元退役**
 - 旧四端点(list/tree/file/archive)恒 `501 capability.workspace_retired`,`capabilities.workspace`
   恒 `false`。理由:rewind 换代为 per-file 历史(只备份代理**编辑过**的文件,无树遍历、无体积门),
@@ -1183,6 +1190,38 @@ TASK_WRITE_FACE_ESCALATION=allow     # 词表 allow|refuse;坏词启动期响亮
   配置管道);`GET /v1/sessions/:id/mcp` 面板与执行面同一台账(被撤服务器的工具不再展示)。
   纯 env 配置的 `MCP_SERVERS` 部署无中心撤销语义,行为逐字不变。
 
+**技能从哪来(来源与覆盖序)**
+
+一个 run 装着的技能按下面的顺序叠出来(每条技能的 `scenarios` 为空 = 进所有场景,写了 = 只进这些场景):
+
+1. **出厂技能 = `SKILLS_DIR` 这一个目录**(缺席 = 包内自带的 `skills/`,按模块位置解析,不是进程 cwd)。目录里每个 `<名>.md`(frontmatter `name` / `description` / `scenarios`)
+   或 `<名>/SKILL.md`(同目录的其余文件作附件)是一条。**设了 `SKILLS_DIR` 就整个替换包内出厂技能,不叠加** —— 想在出厂集上加几条,把包内 `skills/` 拷过去再加;
+   目录不存在 = 零出厂技能(不报错)。
+2. **配置源的技能**:配了中心 = web-admin 的 skills 域;`CONFIG_PROVIDER=local` = `config.d/skills.json`(`{ "skills": [{ "name", "description", "content", "scenarios"?, "enabled"? }] }`,
+   正文写在 `content` 里)。**按名盖在出厂技能上**(同名 ⇒ 配置源这条赢),`enabled: false` 的不装;两种配置源同一条路径(7.128.0 起;此前本地形整域不生效)。
+   起服每装上一条一行 `web_admin_skill`(`overrodeBuiltin` 说盖没盖出厂的);拿不到正文的一条一行 `web_admin_skill_failed`(`reason`:`body_absent` / `read_failed`),
+   这一条不装、同名出厂技能保留、起服照常。重启生效(与 MCP 同:改了之后 `/health` 的 `restart.reasons` 含 `skills`)。
+3. **插件带的技能**(plugins 域):只补**没被占的名字**,撞名让位(起服行 `center_plugins_applied` 的 `letGo`)。
+4. **请求体自带的技能**(`skills[]`):只补这一 run **没被占的名字** —— 与部署的技能同名的那条被丢(一行 `user_skills_dropped`),不覆盖;
+   `disableSkills: true` ⇒ 这一 run 一只技能都不装(部署的、请求的都不装)。
+
+**MCP 条目的工具风险轴(`toolAxes`,7.128.0 起)**
+
+`config.d/mcp.json` 的 `servers[]`(或配置中心下发的同形条目)可带 `toolAxes`,为这台 server 的**每只工具**声明风险轴;声明逐字上引擎的 `McpServerSpec.toolAxes`,喂审批门与计划模式围栏:
+
+```json
+{ "name": "crm", "scenarios": [], "transport": { "kind": "stdio", "command": "crm-mcp" },
+  "toolAxes": { "search_accounts": { "effect": "read" }, "send_mail": { "egress": true, "irreversibility": "always" } } }
+```
+
+- **形**:键 = 该 server 的**原始(未加命名空间)**工具名;值 = `{ effect?, egress?, irreversibility? }` —— `effect` 取引擎的 `ToolEffect` 词(`read` / `write` / `idempotent`)、
+  `egress` 是布尔、`irreversibility` 取 `always` / `never`;词表以引擎为准,本服务不另立一份。成员之间能不能并存(例如 `effect:"read"` 与 `egress:true`)由引擎判,本服务只判形。
+- **坏形整条 server 不挂**:出词表、`egress` 非布尔、未知成员(笔误)、某只工具的值不是对象、整份不是对象、工具名为空 ⇒ 那一台 server 不挂,兄弟 server 照挂,
+  起服日志一行 `web_admin_mcp_tool_axes_invalid { server, problem, note }`(`problem` 指到工具名与成员名,不带值);它的名字仍被部署占着,请求体里的同名条目补不了位。
+  一只工具坏,整条的声明都不收。缺席、`{}`、全空条目 = 没声明。
+- **重启生效**(与 MCP 条目其余部分同:改了之后 `/health` 的 `restart.reasons` 含 `mcp`)。
+- **请求体自带的 `mcpServers[].toolAxes`**(单用户闸:调用方即信任根)不变;这一条只管部署侧声明。
+
 **可选 — MCP 入站表单(elicitation,E23):默认关**
 
 ```bash
@@ -1641,13 +1680,17 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 > - **`tool_end.output` 两形**:串,或块数组。块里可有图像 / 文档 `{ type, data, mimeType }` —— 本流上整块逐字(`data` 是字节编码,不过文本脱敏),
 >   一帧最大约为部署媒体预算的 4/3(缺省约 40 MiB),请按块 `data` 长界帧;读得慢的连接(本帧媒体 + 还没送出去的字节 > 64 MiB)上本帧媒体降成描述符。
 >   媒体块 `data` 的内容由引擎准入负责:引擎本版只对自己产出的块验字节(读图像 / PDF、提交的图像、用户附件),MCP 服务器与宿主自定义工具交回的块不验(引擎下一 minor 收);本服务不在 wire 上对 `data` 做任何改写。
->   账本面只存描述符 —— 账本行与 `GET /v1/runs/:id/events`(断线重连面;对 `POST /v1/runs` 提交的异步 run 它**就是活流**,所以这类客户端本版拿不到整图,整图只在本流与子代 tail 流上)
->   `{ type, mimeType?, bytes, truncated: true }`(帧级 `truncated: true` 与 `totalChars` = 原值真实大小 —— 文本块字符数 + 媒体块 `data` 串长,引擎已截断的帧保留引擎给的值);无 `data` 且 `truncated: true` 的块渲染成「未送达」。
+>   账本面不存媒体字节 —— 账本行与 `GET /v1/runs/:id/events`(断线重连面;对 `POST /v1/runs` 提交的异步 run 它**就是活流**,所以这类客户端拿不到整图,整图只在本流、子代 tail 流与会话存档 `GET /v1/sessions/:id` 上)
+>   里,带 `data` 的媒体块换成 `{ type, mimeType?, bytes, truncated: true }`(帧级 `truncated: true` 与 `totalChars` = 原值真实大小 —— 文本块字符数 + 媒体块 `data` 串长,引擎已截断的帧保留引擎给的值);无 `data` 且 `truncated: true` 的块渲染成「未送达」。
+>   **同一条律也管 `tool_end.structured`**:Read 读图像 / PDF 的卡 `{ type: "image" | "document", file: { base64?, type, originalSize, … } }` 里 `file.base64` 是同一份字节的第二份编码(引擎只在 ≤48K 字符时随卡),
+>   本流上同样逐字(不过文本脱敏,卡上其余成员照常脱敏),积压判据把它与 `output` 块的字节同一帧一起计、降级时一并去掉;账本面(账本行与 `/events`、`GET /v1/tasks/:id/turns`、`GET /v1/tasks/:id/stream` 的回放)里卡上**没有** `file.base64`
+>   (与引擎对超 48K 的卡自己略去该键的形一致,`originalSize` / `type` 仍在)。7.127.0 / 7.127.1 上这份字节(≤48K 字符)仍随账本行落库并回放,7.127.2 起不带。
+>   会话存档读面同律:`GET /v1/sessions/:id` 的 `messages[]` 里,工具结果消息的 `details` 就是这张卡 —— 媒体卡的 `file.base64` 逐字(不去键、不过文本脱敏),卡上其余成员与非媒体卡照常脱敏(7.128.0 起;此前这一位也被文本脱敏改写)。
 
 ## 7. 其它接口(按需)
 | 端点 | 用途 |
 |---|---|
-| `GET /v1/sessions/<id>` | 审计回溯:当前上下文 + 摘要(owner 校验);消息里模型 / 工具产出的文本与 live 帧、账本帧同一只脱敏(密钥形换占位,其余字节不变) |
+| `GET /v1/sessions/<id>` | 审计回溯:当前上下文 + 摘要(owner 校验);消息里模型 / 工具产出的文本与 live 帧、账本帧同一只脱敏(密钥形换占位,其余字节不变);Read 图像 / PDF 的媒体卡(工具结果消息的 `details`)的 `file.base64` 是字节编码,逐字 |
 | `GET /v1/approvals?owner=user:42` | 高危写审批(durable,需 `DURABLE_APPROVAL=true`):**operator** 看待办队列(可按 owner 过滤);非 operator 只看自己的 |
 | `POST /v1/approvals/<sessionId>/decide` `{"decision":"approve"|"deny","reason":"…"}` | 批/否并恢复挂起任务(CAS,重复决议 409);**仅 operator**(非 operator → 403)。5.0.0 起旧轮询腿 `POST /v1/approvals/<id>` 已退役 |
 | `GET /v1/agents/roster` | 后台 agent **名册**(7.29 起,需 durable background-agent store,否则 501 `capability.background_agent_store_required`):调用方自己 scope 的 `a…` 行,新→旧。行只带 `handle`/`name`/`agentType`/`status`/`spawnedAt`/`updatedAt`/`settledAt`(content-free;子代产物正文走 `GET /v1/runs/<id>/subagents/<handle>/output`)。查询:`?limit=`(1..100,默认 20)、`?before=`(上一页的 `nextBefore` 游标)、`?status=`(running\|parked\|completed\|failed\|killed)、`?session=`(按会话树窄化)、`?scope=`(**仅** service-token/单用户形;带 principal 的调用方锁定自己)。回体 `{agents,total,nextBefore?,truncated?}`;`truncated:true` = 租户行数超过名册窗(500),`total` 此时是窗内数。非属主的行**不出现也不计数**(无存在性 oracle) |
@@ -1781,6 +1824,7 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 >   - **自动整理**(任务结束按建议起跑)用这条腿自己的判官 —— 该 run 主体的人的持久路径规则 + 部署的调用方策略,与模型自己的 `Write` 同一套判:
 >     规则点名库目录 ⇒ 在任何占位与模型调用之前拒,运维行 `engine_notice` 一条 `memory.consolidation_refused`(`detail.refusalCode: "memory.consolidation_write_refused"`);
 >     只点名产物文件 ⇒ 应用时拒、什么都不写,一条 `memory.consolidation_incomplete`(`stop: "refused"`);用户任务不受影响。没有主体的 run 读不到任何人的持久规则(只剩部署策略那一层)。
+>     ⚠️ **引擎 7.50.x 上这条腿在缺省部署上每一次都被拒**:只要部署的敏感路径守卫在场(`SENSITIVE_WRITE_PATTERNS` 未设即在场),引擎问写判官时递给部署策略的是一只已中止的信号,守卫判不了库目录的真实落点、按 `target_unresolved` 拒 —— 与规则、权限模式无关(`memory.consolidation_refused`,人读句只带拒因前 200 字)。修复随引擎提货;要整理用手动阀门,不要为此设 `SENSITIVE_WRITE_PATTERNS=off`(见 MIGRATION 7.127.2 第 3 条)。
 >   - **手动阀门**(`POST /v1/admin/memory/consolidation/run`)没有腿,拿不到引擎的那只判官;本服务不另造一只 ⇒ 它的写判官答「无异议」(与 7.126.0 该口行为逐字同),
 >     每次被问记一次 fail-open 计数 `server.memory-consolidation.operator-valve-unjudged`(计数 + 探针行 + 一次性告警)。驱动的每一条通告 —— 非收敛停的 `memory.consolidation_incomplete`、
 >     问判官**之前**推不出库家落点时同码拒的 `memory.consolidation_refused`(生产上可达,与判官答什么无关)—— 都经同一只 `engine_notice` 转发器进运维行;早问拒仍按路由的码臂答 `409 memory.consolidation_refused`。
@@ -2432,6 +2476,12 @@ WebSearch 工具的 `tool_result` 错误文本,回到模型的对话里,**不是
 - 置空(名单外 / 凭据名)时日志一行 `hook_http_header_env_blanked`(名字与原因,不带值)。
 例:`"headers": { "Authorization": "Bearer ${HOOK_TOKEN}" }`、`"allowedEnvVars": ["HOOK_TOKEN"]`,并在请求 `settings.env` 里给 `HOOK_TOKEN`。7.125.x 及更早的读法不同(升级见 MIGRATION)。
 
+### 9.5d MCP 服务器 http 传输的身份头:`principalHeader` 与 `assertionHeader` 二选一(请求体与部署声明同一种读法)
+
+`mcpServers[].transport`(`kind:"http"`)上有两个「用哪个头送身份」的可选键,**只能设一个**:`principalHeader`(runner 把该任务已认证的终端用户 principal 注入这个头)与 `assertionHeader`(托管连接器断言所用的头**名**)。
+- 请求体(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)与部署声明(中心下发 / 本地 `config.d/mcp.json`)判据相同:两键同设 ⇒ 请求体新提交腿 `400 request.body_shape`(拒句点名条目与两键,与契约包解析期的拒句逐字相同);`assertionHeader` 不是字符串 ⇒ `400 request.field_invalid`;部署声明里同设的那一条不进。耐久 resume 腿重放存量请求体时不拒、也不摘 server:server 照挂,`principalHeader` 胜、`assertionHeader` 不生效,一行 warn `mcp_assertion_header_ignored`(`server` / `reason` / `note`)。
+- 本版只承载、不发送断言:声明了 `assertionHeader` 的 server 照常挂载,但不带断言头;每台这样的 server 一行 info `mcp_assertion_header_not_sent`(`server` / `note`)。探测口 `POST /v1/capabilities/mcp/probe` 对声明了该键的条目整条拒 `400 request.field_invalid`(探测不拨一份少了断言头的配置)。
+
 ### 9.6 trace 脱敏的射程:与出站请求体无关
 
 🔴 **脱敏 ≠ 出站控制**:trace 脱敏(账本 / SSE / turns / 审批预览里的 `«redacted»` 标记)只作用于

package/dist/audit.js

@@ -4,6 +4,7 @@ import { PgSessionStorage } from "./plugins/pg-session-storage.js";
 import { createLocalSessionRepo } from "./plugins/local-session-store.js";
 import { redactModelText } from "./observability/run-terminal.js";
 import { redactDeepWith } from "./trace/redact.js";
+import { projectToolStructured } from "./trace/tool-output-media.js";
 import { INJECTED_BLOCK_RE } from "./user-authored-text.js";
 export function buildRewindHandles(anchors, reader) {
     const byEntry = new Map();
@@ -79,10 +80,12 @@ function withRewindHandles(messages, entries, handles) {
 }
 const deepScrub = (v) => redactDeepWith(v, redactModelText);
 const textSlot = (v) => (typeof v === "string" ? redactModelText(v) : deepScrub(v));
+const readToolCard = (v) => projectToolStructured(v, deepScrub);
 function readLeaf(treatment, v) {
     switch (treatment) {
         case "text": return textSlot(v);
         case "structure": return deepScrub(v);
+        case "toolCard": return readToolCard(v);
         case "parts": return readParts(v);
         case "verbatim": return v;
         default: {
@@ -140,7 +143,7 @@ const MESSAGE_READ_TREATMENT = {
         providerCondition: "verbatim", providerConditionSource: "verbatim", providerResetAtMs: "verbatim", apiErrorRoute: "verbatim",
         errorBodyIncomplete: "verbatim", modelOutputInvalid: "verbatim", finishReasonUnknown: "verbatim", streamEndIgnored: "verbatim",
     },
-    toolResult: { role: "verbatim", toolCallId: "verbatim", toolName: "verbatim", content: "parts", details: "structure", isError: "verbatim", timestamp: "verbatim" },
+    toolResult: { role: "verbatim", toolCallId: "verbatim", toolName: "verbatim", content: "parts", details: "toolCard", isError: "verbatim", timestamp: "verbatim" },
     bashExecution: {
         role: "verbatim", command: "text", output: "text", exitCode: "verbatim", cancelled: "verbatim", truncated: "verbatim",
         fullOutputPath: "verbatim", timestamp: "verbatim", excludeFromContext: "verbatim",

package/dist/boot/execution-lane.d.ts

@@ -17,6 +17,17 @@ export interface ExecutionLaneComposeCtx {
 }
 /** 合成 + 判。覆写就地改写 `config.remoteExec`;坏文件 / 不变量不过 ⇒ 抛(拒启)。 */
 export declare function composeExecutionLane(config: ServiceConfig, ctx: ExecutionLaneComposeCtx): Promise<void>;
+/**
+ * **宿主车道的 shell 起服解析**(一次)—— 宿主车道(`provider === "host"`)的命令用本机 shell 起(win32 = Git Bash),起服时把它解析落定,
+ * 找不到就在这里响亮地说一次(`warn host_shell_unavailable { err, remedy }`),而不是等第一个用户的第一条 Bash 撞上。
+ * 一条律:**shell 只属于 spawn,每一处 spawn 都在解析落定之后;解析器的状态转换是唯一的运维信号源** —— 本步只是把观察者装上并让第一次
+ * 转换提前发生,各条 spawn 腿(四条 exec + 两条 hook)自己仍先 await 解析,不依赖本步先跑(细节与行名见 `plugins/host-platform.ts`)。
+ * 失败不挡起服:宿主车道的其它工具照常,Bash 到 spawn 时以真因拒。
+ *
+ * 两个入口调同一只(与 {@link composeExecutionLane} 同形):HTTP 服务在第 5 段(执行环境装配)之后,`run-local` 在宿主车道定下之后。
+ * 非宿主车道零动作 —— 不解析、不装观察者。
+ */
+export declare function settleHostLaneShell(config: Pick<ServiceConfig, "remoteExec">, logger: Pick<Logger, "info" | "warn">): Promise<void>;
 /**
  * 车道合成之后的跨域不变量 —— 表(`config-invariants.ts`)里读 `remoteExec.provider` 的那几条,boot 期 `live === next`。
  * 同步、纯判据:只读 config,不碰文件(测试可以对 `loadConfig()` 的产物直接调它)。

package/dist/boot/execution-lane.js

@@ -1,12 +1,18 @@
 import { loadRemoteExec } from "@sema-agent/settings-schema/node";
 import { crossInvariant } from "../config-invariants.js";
 import { executionLaneOf, laneIsolated } from "../execution-lane-caps.js";
+import { settleHostShellAtBoot } from "../plugins/host-platform.js";
 export const FILE_SOURCED_LANES = ["host", "local-docker"];
 export async function composeExecutionLane(config, ctx) {
     if (ctx.configSource === "local")
         await applyRemoteExecFile(config, ctx);
     assertExecutionLaneInvariants(config);
 }
+export async function settleHostLaneShell(config, logger) {
+    if (config.remoteExec?.provider !== "host")
+        return;
+    await settleHostShellAtBoot(logger);
+}
 export function assertExecutionLaneInvariants(config) {
     const judge = (id) => crossInvariant(id).check({ live: config, next: config });
     const leader = judge("leader-host-lane");

package/dist/boot/resolve-spec.js

@@ -35,7 +35,7 @@ import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, norma
 import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
 import { cwdHonored, deviceCwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
 import { assertRequestA2aUnlocked, resolveRequestA2a } from "../task-a2a.js";
-import { assertRequestMcpContentOrigin, assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
+import { assertRequestMcpContentOrigin, assertRequestMcpIdentityHeaders, assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, taskHooksHonored, providerDropsAppend, settingsPermissionBucketIssue, withPermissionMode } from "../task-settings.js";
 import { skillDenyInertEntryOf } from "../rule-entry-list.js";
 import { TENANCY_WALL_CLOCK_BASE_SEC, enableForkFromBody, normalizeRetainSubagentSessions, selfOrchestrationFromBody } from "../task-workflow.js";
@@ -70,6 +70,8 @@ export function createResolveSpec(ctx) {
         assertRequestMcpUnlocked(body.mcpServers, lockedKeys);
         if (opts?.leg === "fresh")
             assertRequestMcpContentOrigin(body.mcpServers);
+        if (opts?.leg === "fresh")
+            assertRequestMcpIdentityHeaders(body.mcpServers);
         if (opts?.leg === "fresh") {
             const conflict = scratchpadCoveringTaskRoot({
                 cwd: body.cwd,

package/dist/boot/web-admin.js

@@ -19,7 +19,7 @@ import { centerManagedConfigKeys } from "../web-admin-client/apply-effective.js"
 import { createConfigProvider, raceBootFetch, serviceConfigSourceKind, BOOT_FETCH_DEFERRED } from "../config-provider.js";
 import { createKeyResolver } from "../key-resolver.js";
 import { buildSealedKeyPublicFace, ensureSealedKeyStore, reportExecutionPublicKey } from "../sealed-key.js";
-import { applyEffective, applyCenterReadFace, mutateInPlace, logEffectiveDiff, applyCenterSkills, resolveMcpServers, resolveA2aPeers, restartReasons, modelPlaneChanged, withModelPlaneOf, fullyLandedForLkg, fetchPromptArtifact } from "../web-admin-client/facade.js";
+import { applyEffective, applyCenterReadFace, mutateInPlace, logEffectiveDiff, applySkillsManifest, resolveMcpServers, resolveA2aPeers, restartReasons, modelPlaneChanged, withModelPlaneOf, fullyLandedForLkg, fetchPromptArtifact } from "../web-admin-client/facade.js";
 import { buildConfigHandoff, buildRestartSignal, configHandoffMissing } from "../fleet/engine-signal.js";
 import { createMcpRevocationLedger, enabledMcpEntries } from "../web-admin-client/mcp-revocation.js";
 import { buildUnreadConfigFileFields } from "../web-admin-client/read-warnings.js";
@@ -133,6 +133,7 @@ export async function createWebAdminRuntime(ctx) {
             ...(config.configProvider ? { provider: config.configProvider } : {}),
             ...(cc ? { webAdmin: { baseUrl: cc.baseUrl, credential: cc.credential, worker: cc.worker, dryRun: cc.dryRun } } : {}),
             localDir: localRoot,
+            ...(config.configLkgEnabled ? { skillBodyCacheDir: defaultSkillCacheDir(config) } : {}),
         })
         : undefined;
     const localDirField = configProvider?.kind === "local" ? { dir: configProvider.root } : {};
@@ -153,16 +154,16 @@ export async function createWebAdminRuntime(ctx) {
             });
         }
     };
-    const rejectionSource = () => {
+    const candidateSource = () => {
         if (configProvider === undefined)
-            throw new Error("config candidate judged without a config provider (no pipeline ⇒ nothing was pulled)");
-        return configProvider.kind;
+            throw new Error("config candidate handled without a config provider (no pipeline ⇒ nothing was pulled)");
+        return configProvider;
     };
     const announceCandidateRejected = (r, verdict, leg, ordinal) => {
         const domains = verdict.domains.join(",");
         if (candidateRejection?.version === r.effective.version && candidateRejection.domains.join(",") === domains)
             return;
-        noteCandidateVerdict(ordinal, candidateRejectionOf(r, verdict, rejectionSource(), Date.now()));
+        noteCandidateVerdict(ordinal, candidateRejectionOf(r, verdict, candidateSource().kind, Date.now()));
         logger.warn("config_candidate_rejected", buildCandidateRejectedFields(r, verdict, leg, { lkgVersion: latestEffective?.version ?? "(env)", ...localDirField }));
     };
     const selfReportListeners = [];
@@ -372,11 +373,15 @@ export async function createWebAdminRuntime(ctx) {
         }
         const lkgPath = lkgPathFor(identity);
         try {
-            if (effectiveObj.skills && config.webAdmin) {
-                await applyCenterSkills([], effectiveObj.skills, config.webAdmin, logger, undefined, defaultSkillCacheDir(config));
+            const source = candidateSource();
+            const cacheDir = source.skillBodyCacheDir;
+            if (cacheDir === undefined) {
+                logger.warn("config_lkg_save_failed", { err: "the config source declares no skill body cache", note: "LKG NOT written (skill bodies on disk are part of the handoff contract and this source keeps none) — handoff NOT confirmed" });
+                return false;
             }
+            if (effectiveObj.skills)
+                await applySkillsManifest([], effectiveObj.skills, source, logger);
             const enabledSkills = (effectiveObj.skills?.skills ?? []).filter((m) => m.enabled !== false);
-            const cacheDir = defaultSkillCacheDir(config);
             for (const m of enabledSkills) {
                 const hex = m.contentHash.replace(/^sha256:/, "").toLowerCase();
                 if (!SHA256_HEX_RE.test(hex))
@@ -692,9 +697,8 @@ export async function createWebAdminRuntime(ctx) {
             return (await manualRefresh()) === "failed" ? "failed" : "triggered";
         },
         async applyCenterCapabilities(skills) {
-            if (effective?.skills && config.webAdmin) {
-                skills = await applyCenterSkills(skills, effective.skills, config.webAdmin, logger, undefined, config.configLkgEnabled ? defaultSkillCacheDir(config) : undefined);
-            }
+            if (effective?.skills)
+                skills = await applySkillsManifest(skills, effective.skills, candidateSource(), logger);
             if (effective?.plugins !== undefined) {
                 const pluginOut = await applyCenterPlugins(skills, effective, {
                     cacheRoot: join(config.localDataRoot ?? join(homedir(), ".ai-agent"), "plugin-cache"),

package/dist/capabilities/mcp-probe.js

@@ -4,7 +4,8 @@ import { createFixedWindowRateLimiter } from "../device-enrollment.js";
 import { canonicalJson } from "../canonical-json.js";
 import { echoKeyName, keyClosureClause, scanKeyClosure } from "../request-key-closure.js";
 import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "../mcp-content-origin.js";
-import { HTTP_MCP_TRANSPORT_KEYS, MAX_REQUEST_MCP_SERVERS, MCP_ENTRY_EMPTY_ARRAY_KEYS, MCP_ENTRY_EMPTY_RECORD_KEYS, MCP_SERVER_ENTRY_KEYS, MCP_TRANSPORT_EMPTY_ARRAY_KEYS, MCP_TRANSPORT_EMPTY_RECORD_KEYS, STDIO_MCP_TRANSPORT_KEYS, validateRequestMcp, } from "../task-mcp.js";
+import { HTTP_MCP_TRANSPORT_KEYS, MAX_REQUEST_MCP_SERVERS, MCP_ENTRY_EMPTY_ARRAY_KEYS, MCP_ENTRY_EMPTY_RECORD_KEYS, MCP_SERVER_ENTRY_KEYS, MCP_TRANSPORT_EMPTY_ARRAY_KEYS, MCP_TRANSPORT_EMPTY_RECORD_KEYS, STDIO_MCP_TRANSPORT_KEYS, requestEntryIdentityRefusal, validateRequestMcp, } from "../task-mcp.js";
+import { toCoreMcpServerSpec } from "../mcp-assertion-header.js";
 import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { projectWiringManifestMcpRows } from "../trace/project.js";
 export const MCP_PROBE_REFUSAL_CODES = [
@@ -51,8 +52,12 @@ function entryKeyIssue(entry, at) {
         if (keys !== undefined)
             scanKeyClosure(t, `${at}.transport.`, new Set(keys), NO_TOLERATED_KEYS, buckets);
     }
-    if (buckets.unknown.length === 0)
-        return null;
+    if (buckets.unknown.length === 0) {
+        const refusal = requestEntryIdentityRefusal(entry);
+        if (refusal === undefined)
+            return null;
+        return refusal.errorCode === "request.body_shape" ? shapeRefusal(refusal.message) : fieldRefusal(refusal.message);
+    }
     buckets.unknown.sort();
     return shapeRefusal(`body: unrecognized key(s) on an MCP declaration — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
         `${keyClosureClause(buckets.unknown, "unknown (not an mcpServers[] key — check the spelling)")}. ` +
@@ -71,7 +76,8 @@ function entryValueIssue(entry, at) {
     if (read.badContentOrigin.length > 0) {
         return fieldRefusal(`${at}.contentOrigin must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(entry.contentOrigin)} (omit the key for the default: this server's tools classify as external content)`);
     }
-    return declarationDowngradeIssue(entry, read.ok[0], at);
+    const read0 = read.ok[0];
+    return declarationDowngradeIssue(entry, read0 === undefined ? undefined : toCoreMcpServerSpec(read0), at);
 }
 function declarationDowngradeIssue(entry, spec, at) {
     if (spec === undefined)
@@ -171,7 +177,7 @@ export function readMcpProbeBody(raw) {
                 " so nothing in your body needs changing — if you see it, this deployment has a bug worth reporting"),
         };
     }
-    return { ok: true, specs: validated.ok };
+    return { ok: true, specs: validated.ok.map(toCoreMcpServerSpec) };
 }
 export function buildMcpProbeIdentity(principal) {
     return principal !== undefined && principal.length > 0 ? principal : "local";

package/dist/config-catalog.js

@@ -432,7 +432,7 @@ export const CONFIG_CATALOG = [
     r("SESSION_SNAPSHOT_PREFIX", "store", "string", "快照 blob key 前缀", { derivedDefaultNote: "缺席 ⇒ blobs/(MinioBlobBackend 默认)" }),
     r("SESSION_SNAPSHOT_TTL_SEC", "store", "number", "快照 presign TTL(秒;坏值省略走默认,绝不 NaN 签名)", { derivedDefaultNote: "缺席 ⇒ 3600(MinioBlobBackend 默认)" }),
     r("SIGHUP_IDLE_GRACE_MS", "limitsHttp", "number", "SIGHUP 空闲关停窗(ms;共享引擎形防误杀)", { staticDefault: "120000", configKey: "sighupIdleGraceMs" }),
-    r("SKILLS_DIR", "integrations", "path", "出厂 skill 目录", { derivedDefaultNote: "缺席 ⇒ 包内 skills/(相对模块解析,不是 cwd)", configKey: "skillsDir" }),
+    r("SKILLS_DIR", "integrations", "path", "出厂 skill 目录(设了就整个替换包内 skills/,不叠加;配置源的技能再按名盖上)", { derivedDefaultNote: "缺席 ⇒ 包内 skills/(相对模块解析,不是 cwd)", configKey: "skillsDir" }),
     r("SNAPSHOT_BLOB_ALLOW_SQL_BYTES", "store", "boolean", "云形缺 MinIO 时显式接受 SQL 店放快照字节(严格 'true';安全姿势开关不收宽松真值)", { staticDefault: "false", danger: DATA, configKey: "snapshotBlobAllowSql" }),
     r("SNAPSHOT_BLOB_SQL_MAX_BYTES", "store", "number", "SQL 店单 blob 帽(字节)", { derivedDefaultNote: "缺席:mysql 引擎 ⇒ 内建默认帽;pg ⇒ 不设", configKey: "snapshotBlobSqlMaxBytes" }),
     r("SSH_HOST", "orchestration", "string", "ssh 车道目标主机(必需件)"),

package/dist/config-provider.d.ts

@@ -78,8 +78,9 @@ export declare function raceBootFetch<T>(fetch: Promise<T>, budgetMs: number): P
 /**
  * The two transport calls the service makes to obtain config, behind a backend-selectable seam. Both
  * signatures and return shapes match `facade.fetchEffective` / `facade.fetchSkillContent`
- * EXACTLY so that, ONCE WIRED, the caller (main.ts) could swap remote↔local without touching applyEffective
- * et al. (main.ts does not swap on this seam yet — see the NOT-YET-WIRED note at the top of this module).
+ * EXACTLY, so every consumer (boot / refresh / late boot in `boot/web-admin.ts`, and `run-local`) runs one code
+ * path whichever backend answers: candidates through `fetchEffective`, skill bodies through `fetchSkillContent`
+ * (the skills read port `applySkillsManifest`), the body cache wherever the backend declares it.
  */
 export interface ConfigProvider {
     /** "remote" = web-admin HTTP; "local" = on-disk FileConfigStore. */
@@ -92,11 +93,18 @@ export interface ConfigProvider {
     fetchEffective(etag: string | undefined): Promise<FetchEffectiveResult>;
     /**
      * Fetch one skill body by content hash (`sha256:<hex>`). Remote: GET the content endpoint + verify the
-     * hash. Local: content-addressed lookup over the local skills domain. Returns `undefined` when the hash
+     * hash. Local: content-addressed lookup over the skills of the candidate this provider last served (the
+     * same read that produced the manifest — S-1556). Returns `undefined` when the hash
      * is unknown (remote 404 / local miss) so the caller keeps its baseline; throws only on a hard error
      * (remote non-404 HTTP / hash mismatch).
      */
     fetchSkillContent(contentHash: string): Promise<string | undefined>;
+    /**
+     * S-1556:这只配置源给技能正文留的**盘缓存目录**(content-addressed;`applySkillsManifest` 的读序 内存 → 盘 → 本配置源,读到即回写)。
+     * 远程:开着 LKG(`CONFIG_LKG_ENABLED`)时 = 配置根下的 `skill-cache` —— 中心不可达时的 LKG 起服不卡在正文拉取上,LKG 落盘的正文完整性门
+     * 也验这同一个目录;关着 = 缺席(不落盘)。本地:恒缺席 —— 正文就内联在本机盘上的 config.d 里,再拷一份是第二份真源。
+     */
+    readonly skillBodyCacheDir: string | undefined;
 }
 /** The config-provider knobs read off ServiceConfig (a structural subset — avoids importing the whole
  *  ServiceConfig type and keeps this module testable with a plain object). */
@@ -117,6 +125,8 @@ export interface ConfigProviderInput {
      *  `process.cwd()`,而工厂只在 `CONFIG_PROVIDER === "local"` 字面上递它 ⇒ 另一条走到 local 的路上配置源读 cwd、
      *  合成步读 localRoot,两个根分家。一个远程源也收它:`remote` 而无中心 URL 的形照样落回 local。 */
     localDir: string;
+    /** S-1556:远程配置源的技能正文盘缓存目录(见 {@link ConfigProvider.skillBodyCacheDir});本地配置源不认它(正文本就在盘上)。缺席 = 不落盘。 */
+    skillBodyCacheDir?: string;
 }
 /**
  * RemoteConfigProvider — DELEGATES to the exported web-admin HTTP functions. No HTTP is reimplemented;
@@ -127,13 +137,14 @@ export interface ConfigProviderInput {
 export declare class RemoteConfigProvider implements ConfigProvider {
     private readonly cc;
     private readonly deps;
+    readonly skillBodyCacheDir: string | undefined;
     readonly kind: "remote";
     constructor(cc: CenterEndpoint & {
         worker?: string;
     }, deps?: {
         fetchEffective?: typeof remoteFetchEffective;
         fetchSkillContent?: typeof remoteFetchSkillContent;
-    });
+    }, skillBodyCacheDir?: string | undefined);
     fetchEffective(etag: string | undefined): Promise<FetchEffectiveResult>;
     fetchSkillContent(contentHash: string): Promise<string | undefined>;
 }
@@ -146,6 +157,8 @@ export declare class RemoteConfigProvider implements ConfigProvider {
 export declare class LocalConfigProvider implements ConfigProvider {
     #private;
     readonly kind: "local";
+    /** 本地配置源不留正文盘缓存:正文就内联在 config.d 里(同一块盘),缓存它是第二份真源。 */
+    readonly skillBodyCacheDir: undefined;
     private readonly store;
     /** [ref]b 可观测性:config_loaded 日志要能回答「到底读的哪个目录」——复验实录:只设 LOCAL_DATA_ROOT 时
      *  config.d 静默读不到且 0 模型无告警(CONFIG_LOCAL_DIR 才是本 lane 的选目录旋钮)。 */

package/dist/config-provider.js

@@ -38,10 +38,12 @@ export function raceBootFetch(fetch, budgetMs) {
 export class RemoteConfigProvider {
     cc;
     deps;
+    skillBodyCacheDir;
     kind = "remote";
-    constructor(cc, deps = {}) {
+    constructor(cc, deps = {}, skillBodyCacheDir = undefined) {
         this.cc = cc;
         this.deps = deps;
+        this.skillBodyCacheDir = skillBodyCacheDir;
     }
     async fetchEffective(etag) {
         const fn = this.deps.fetchEffective ?? remoteFetchEffective;
@@ -68,6 +70,8 @@ export class RemoteConfigProvider {
 }
 export class LocalConfigProvider {
     kind = "local";
+    skillBodyCacheDir = undefined;
+    #servedSkills = { skills: [] };
     store;
     root;
     #injectedStore;
@@ -115,6 +119,7 @@ export class LocalConfigProvider {
         const parseErrors = folded.domainErrors.map((w) => ({ domain: w.domain, error: redactConfigError(w.error) }));
         const droppedEntries = folded.droppedEntries.map(redactDroppedEntry);
         const errors = [...domainErrors.map((de) => ({ domain: de.domain, error: redactConfigError(de.error) })), ...parseErrors, ...refErrors];
+        this.#servedSkills = eff.skills;
         return {
             effective: withDroppedCatalogEntries(mapToServiceEffective(eff, eff.version), folded.droppedCatalogEntries),
             etag: tag,
@@ -126,10 +131,7 @@ export class LocalConfigProvider {
         };
     }
     async fetchSkillContent(contentHash) {
-        const skills = await this.store.getDomain("skills");
-        if (!skills)
-            return undefined;
-        return findSkillContent(skills, contentHash);
+        return findSkillContent(this.#servedSkills, contentHash);
     }
 }
 export function mapToServiceEffective(eff, version) {
@@ -234,7 +236,7 @@ export function mapToServiceEffective(eff, version) {
 }
 export function createConfigProvider(input) {
     return configProviderKind(input) === "remote" && input.webAdmin !== undefined
-        ? new RemoteConfigProvider(input.webAdmin)
+        ? new RemoteConfigProvider(input.webAdmin, {}, input.skillBodyCacheDir)
         : new LocalConfigProvider(input.localDir);
 }
 export function configLocalRoot(config) {

package/dist/config-types.d.ts

@@ -274,10 +274,10 @@ export interface ScopedMcpServer {
     spec: McpServerSpec;
 }
 /** The deployment's MCP declaration, resolved (`resolveMcpServers`). `servers` = what actually MOUNTED (env-NAME refs
- *  resolved, `enabled:false` / missing-ref / malformed-`toolFaces` entries skipped, each with its own loud warn);
+ *  resolved, `enabled:false` / missing-ref / malformed-`toolFaces` / malformed-`toolAxes` entries skipped, each with its own loud warn);
  *  `reservedNames` = EVERY name the deployment declared, mounted or not. A name the deployment declared is CLOSED to
  *  request-side injection (`resolveRequestMcp`) whether or not it mounted — otherwise "skipped" would silently mean
- *  "free for the caller to refill without the operator's `toolFaces` / `allowTools`" (车CF codex r2 [high]). */
+ *  "free for the caller to refill without the operator's `toolFaces` / `toolAxes` / `allowTools`" (车CF codex r2 [high]). */
 export interface CenterMcp {
     servers: ScopedMcpServer[];
     reservedNames: readonly string[];

package/dist/hooks/hook-runner.d.ts

@@ -2,6 +2,7 @@ import { HooksConfig, type HookEventName } from "@sema-agent/settings-schema/hoo
 import type { Hooks } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
 import type { HookNoticeObservation } from "../fleet/fleet-bus.js";
+/** 服务侧防线上限(契约本身不设量纲;不设界=单请求可塞任意大配置/任意长命令)。超界=校验错(fail-loud)。 */
 export declare const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export declare const MAX_HOOK_COMMAND_CHARS = 8192;
 /** 单条 hook 超时上限(秒;条目可自设 timeout,但被此值夹住——一个 86400 的 timeout 会挂死工具门)。 */

package/dist/hooks/hook-runner.js

@@ -9,7 +9,6 @@ import { redactSecrets, buildDisplaySafeUrl } from "../trace/redact.js";
 import { ccPromptSystemFor, wrapCondition, parseCcVerdict, CC_EVALUATOR_MAX_OUTPUT_TOKENS } from "./cc-stop-prompt.js";
 import { ccAgentHookSystemFor } from "./cc-agent-hook-prompt.js";
 import { renderBranchTranscript } from "./branch-transcript.js";
-void resolveHostShell().catch(() => undefined);
 export const MAX_HOOK_ENTRIES_PER_EVENT = 32;
 export const MAX_HOOK_COMMAND_CHARS = 8_192;
 export const MAX_HOOK_TIMEOUT_SECONDS = 600;
@@ -391,7 +390,13 @@ function buildHookContextField(parts) {
     const text = buildHookContext(parts);
     return text === undefined ? {} : { additionalContext: text };
 }
-function runCommandHook(entry, payload, ctx) {
+async function runCommandHook(entry, payload, ctx) {
+    try {
+        await resolveHostShell();
+    }
+    catch (e) {
+        return { code: null, stdout: "", stderr: "", timedOut: false, spawnError: String(e) };
+    }
     return new Promise((resolve) => {
         const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
         let child;
@@ -454,10 +459,11 @@ function runCommandHook(entry, payload, ctx) {
         child.stdin?.end(`${JSON.stringify(boundedToolInputPayload(payload))}\n`);
     });
 }
-function fireAsyncCommandHook(entry, payload, ctx, event) {
+async function fireAsyncCommandHook(entry, payload, ctx, event) {
     try {
         const rewake = entry.asyncRewake === true;
         const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
+        await resolveHostShell();
         const sh = hostShell();
         const child = spawn(sh.shell, [...sh.args, entry.command], {
             cwd: ctx.cwd,
@@ -754,7 +760,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
             if (entry.type === "command" && (entry.async || entry.asyncRewake)) {
                 if (entry.once)
                     onceFired.add(onceKey);
-                fireAsyncCommandHook(entry, payload, ctx, event);
+                void fireAsyncCommandHook(entry, payload, ctx, event);
                 continue;
             }
             if (Date.now() > deadlineAt) {

package/dist/http/wire-types.d.ts

@@ -6,7 +6,8 @@
  * cut: ONLY TaskRequestBody (its field types are inline or core imports — no other server.ts-local satellites);
  * sibling request/response shapes can migrate here later on the same pattern.
  */
-import type { A2aServerSpec, AgentDefinition, ApprovalReach, McpServerSpec, PermissionMode, SkillSpec, TaskSpec } from "@sema-agent/core";
+import type { A2aServerSpec, AgentDefinition, ApprovalReach, PermissionMode, SkillSpec, TaskSpec } from "@sema-agent/core";
+import type { RequestMcpServerSpec } from "../mcp-assertion-header.js";
 import type { wiringManifestFaceEventData } from "../trace/project.js";
 import type { buildSyncSubmitBody } from "./sync-submit-body.js";
 export interface TaskRequestBody {
@@ -508,8 +509,15 @@ export interface TaskRequestBody {
      *  保留 —— 丢的只是声明。core 把这个键定性为**部署面**的键,本仓对它的 reject-or-strip 义务由既有的单用户闸
      *  **结构性**兑现:多租户腿整只 `mcpServers` 被忽略 ⇒ 租户够不着;单用户腿 = core 明文豁免的超管面
      *  (完整论证见 `task-mcp.ts` 的 `assertRequestMcpContentOrigin` 顶注)。部署面的正门是 center 下发的
-     *  `CenterMcpServer.contentOrigin`。 */
-    mcpServers?: McpServerSpec[];
+     *  `CenterMcpServer.contentOrigin`。
+     *
+     *  S-1515:`transport.kind:"http"` 的条目可选 `assertionHeader`(托管连接器断言头的**头名**,契约包 settings-schema ≥12.2.0 同键)。
+     *  与 `principalHeader` **互斥**:同设 ⇒ 新提交腿同步 400 `request.body_shape`(拒句与契约包解析期那一句逐字相同);值不是字符串 ⇒ 400
+     *  `request.field_invalid`。耐久 resume 腿不拒(重放存量 body),也**不摘 server**(摘了,park 在它工具审批上的任务批准后撞 `resume.tool_unavailable`
+     *  且每次重试重放同一份 body):降级到升级前的读法 —— server 照挂、`principalHeader` 胜、`assertionHeader` 不生效,一行 warn `mcp_assertion_header_ignored`。
+     *  ⚠️ 本版**只承载、不发送**:引擎的 http 传输尚无断言头座,
+     *  声明被接收、server 照常挂载但不带断言头,并有一行运维 info `mcp_assertion_header_not_sent { server }`;发送随引擎座。 */
+    mcpServers?: RequestMcpServerSpec[];
     /** [DESIGN-269 车1] Caller-supplied per-request A2A peers (remote agents this task may call), aligned to
      *  core `A2aServerSpec`. 🔒 honored on a SINGLE-USER deployment that has neither locked the `a2a` key nor
      *  had `a2a_peers` denied by its compliance posture (task-a2a.ts `a2aInjectionHonored`, the same three-veto

package/dist/main.js

@@ -4,6 +4,7 @@ import { runStage02 } from "./boot/stage-02-web-admin-pull.js";
 import { runStage03 } from "./boot/stage-03-store-backend.js";
 import { runStage04 } from "./boot/stage-04-stores.js";
 import { runStage05 } from "./boot/stage-05-execution-env.js";
+import { settleHostLaneShell } from "./boot/execution-lane.js";
 import { runStage06 } from "./boot/stage-06-runners.js";
 import { runStage07 } from "./boot/stage-07-capability-layer.js";
 import { runStage08 } from "./boot/stage-08-reapers.js";
@@ -15,6 +16,7 @@ async function main() {
     const s03 = await runStage03(s02);
     const s04 = await runStage04(s03);
     const s05 = runStage05(s04);
+    await settleHostLaneShell(s05.config, s05.logger);
     const s06 = runStage06(s05);
     const s07 = await runStage07(s06);
     const s08 = runStage08(s07);