@sema-agent/server 7.133.0 → 7.135.0

package/MIGRATION.md

@@ -7,6 +7,227 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.135.0 —— 请求自带 MCP 的 `transport.url` 不得带凭据(新提交 400;安全) · `SANDBOX_PKG_SOURCE=custom` 的地址带凭据名参数起服拒(安全) · 嵌入方:技能的来处必填(`loadSkills` 第二参 `{ source }` 与 `LoadedSkill.source`;BREAKING,类型面) · 引擎 7.55.0:会话规则行的升级序(先升全部读者再放写) · 整协议名 `mcp__*` 在限制表上读成全部工具 · 属主收回自己加的会话规则条目 · 订正 7.134.0 节第 4 条:审批 `feedback` 拒改答 `resume_outcome_invalid`(原 `approval_binding_mismatch`) · 会话店接口只剩头读 `headOf`(嵌入方 BREAKING) · 文件历史读不全 ⇒ `503 state.file_history_unreadable` · journal 坏行 ⇒ `500 workflow.journal_incompatible` · MCP 工具结果两只新码 · `WebFetch(domain:<host>)` 的 deny / ask 按主机生效、参数不属于该工具的 deny / ask 规则受理口 422 / 续跑 409(安全;行为收窄) · `settings.hooks` 组 / 条目上读者不读的键新提交 `400 request.body_shape` · command hook 条目的 `plugin.options` 停驻时只以封签落盘(安全;回滚到 7.134.x 前先结掉带选项的停驻任务) · 耐久事件流开流不再读续跑输入判审批帧族(7.133.x 写下的在飞待决卡照重放;从 7.133.x 直升先停光旧副本) · SQL 后端 `permission_rule` 加一列 `grammar`(🔴 升级前先 `ALTER TABLE` 加列;持久数据,不能删表重建) · 会话 fork 不带在飞的 assistant 轮 · 技能条目自带的 `allowedTools` / `disallowedTools` 开始生效(升级序:先升全部读者,再在管理面写名单;放行免问是放宽方向,先审已有条目) · 请求自带的 `a2aPeers` 对端 / http 钩子 / 搜索后端地址带凭据(新提交 400;安全) · 设备车道有效工作目录非绝对路径的拒带终局码 `config.device_cwd_invalid`(续跑失败终局码多一词) · SQL 后端 `checkpoint` 加一列 `approval_card`(🔴 升级前先 `ALTER TABLE` 加列;表里是在飞的停驻,不能删表重建;嵌入方 `OneTimeMigrationReport` 多三键〔BREAKING,类型面〕) · 一次性迁移 M4 退役(行为变更;起服日志行 `one_time_migrations_applied` 少一个读数字段;嵌入方 `OneTimeMigrationReport` 去一键〔BREAKING,类型面〕;跳版升级的库含旧审计字节的那一页读不出,手工语句见第 22 条) · 嵌入方:审批决议的店接口 `ApprovalAskStore.decideAsk` 第三位插入必填 `owner`(BREAKING,类型面;部署零动作)
+
+1. **`mcpServers[i].transport.url` 带凭据 ⇒ 新提交 `400 request.field_invalid`**(安全;行为面收紧):url 带 userinfo,或带名字在凭据名表里的 query / fragment 参数
+   (`?api_key=` · `?key=` · `?token=` · `?access_token=` · `#access_token=` …;全表与读法见契约附录 A `request.field_invalid` 行)⇒ 新提交三腿与探测口 400,体带
+   `field: "mcpServers[i].transport.url"` 与 `reason`(`url_userinfo` | `url_credential_param`)。**升级前做**:调用方把这类凭据改写进 `transport.headers`
+   (如 `"Authorization": "Bearer …"`);只认 query 鉴权的服务端改在部署面(中心 / `config.d`)声明那台 MCP。按 `reason` 穷举分支的消费方多两个词。
+   升级前已停驻的任务照常续跑(重放存量请求不判),它们续跑上下文里那条 url 仍是原字节 —— 介意的部署把它们结掉后轮换那几枚凭据。
+2. **`SANDBOX_PKG_SOURCE=custom` 的六只地址带凭据名参数 ⇒ 起服拒**(安全):`SEMA_APT_MIRROR` / `SEMA_PIP_INDEX` / `SEMA_UV_INDEX` / `SEMA_UV_PY_MIRROR` / `SEMA_NPM_REGISTRY` /
+   `SEMA_NODE_MIRROR` 里有 `?token=` 一类参数的部署(7.134.x 照起、参数进沙箱环境)。**升级前做**:同 7.133.0 第 1 条 userinfo 的出路 —— 地址改成不带凭据的形,凭据走包管理器自己的通道;
+   源不需要认证就去掉那个参数。拒句点名 env 名与参数名,只回显 `scheme://host[:port]`。
+3. **嵌入方:技能的来处必填**(BREAKING,类型面;只影响自己装配 `ScenarioDeps.skills` 的嵌入方,部署零动作):场景卡新带技能清单 `skills[].source`(`"factory"` | `"center"`),
+   来处由铸技能的那条装载腿写下 ⇒ 包根导出的 `loadSkills(dir, opts)` 第二参必填且带 `source`,`LoadedSkill` 多一个必填成员 `source`。**升级时做**:
+   `loadSkills(dir)` 改成 `loadSkills(dir, { source: "factory" })`(读的是你自己的技能目录;读配置源 / 插件交来的技能写 `"center"`);手写 `LoadedSkill` 字面量的补上 `source`。tsc 红即是提示,零别名。
+4. **引擎 7.55.0:会话规则行的升级序 —— 先升全部读者,再放写(零 DDL)**:本版写下的每一行会话规则带文法戳 `4`(7.134.x 写的是 `2`)与一格 operator 部分 `operatorRules`。
+   7.134.x 及更早的副本读不了这样的行:整行拒(`500 corrupt` / 读不出),那条会话上的每一次工具调用都拒,直到该副本升级或排空 —— 它不把新行读成「更少的规则」。
+   **升级序**:先把读同一只会话规则店的**全部**副本升到本版,再放会话规则的写(`PUT /v1/sessions/:id/policy`、2c 同步导入);做不到就先排空旧副本。单进程部署零动作。
+   **回滚**:本版写下的行旧版读不了(同上的整行拒),而且在本版上重写一遍没有用 —— 本版的写口判官照样盖戳 `4`;旧版的 `PUT` 也改不了它(写前先读那一行,读不出 ⇒ `500 corrupt`)。
+   要回滚,这些会话在旧版上只有两种结局:每一次工具调用都拒(失效关闭),或删会话(规则随之删)。**不要**在库里把戳改回 `2`:同一条目在文法 2 里意思不同
+   (`toolDeny` 的 `mcp__*` 在文法 2 里什么也不拒),改戳 = 静默放宽。混版实测读数与部署前置写在仓库的部署前置清单(不随包)7.135.0 节。
+   **人的持久规则(同一件事的另一只店)**:引擎 7.55.0 起持久规则桶带文法戳,新文法写下的 deny(Bash 中段 `*` 的模式形、`Agent(<类型>)`)在 7.54.x 上**什么也不拒**
+   (旧引擎不读戳,把模式形读成「无形」)—— 同一份规则目录(`DB_BACKEND=local`)或同一只库不要混跑两版,先升全部进程;**降级到 7.55.0 之前**:先把这类 deny 改写成覆盖它的前缀 deny
+   或整工具 deny,或不降。SQL 持久规则店自本版起也写 / 读这只戳(`permission_rule` 加一列,见第 16 条),且**戳算进桶的完整性指纹**:本版副本读到更晚文法写下的桶整桶拒、每次调用问人;7.134.x 副本(引擎 7.54.1)不读戳,
+   但读到带戳的桶时指纹对不上、同样整桶拒(响亮),不会把新文法的 deny 读成「无形」而放行 —— 这扇窗在 SQL 后端上已关。同一只库仍不要混跑两版、先升全部进程(旧副本在被本版写过的桶上整桶拒,直到升级或排空)。人的持久规则店读不出(损坏,或由更新的引擎写下)时,
+   除引擎自己的问答 / 结构化输出 / 阻塞报告之外每一次工具调用都要问人,无人值守的运行拒 —— 修店或升级即恢复。
+5. **整个协议的名字 `mcp__*` / `mcp__*__*`(与 `a2a__*`)在限制表上是这一协议的每一只工具(行为变化,收紧方向)**:会话规则的 `toolDeny`、请求的 `settings.permissions.deny` / `ask`、
+   `excludeTools` / 子代 `denyTools`、运维 `APPROVAL_DENY` / `APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` 与中心下发的 `approvalRequire` 都按「这一协议的全部工具」读它
+   (此前:会话规则与请求的两桶、三张运维名表拒写,存量行里的 `mcp__*` 什么也不拒)。**升级前核**:存量会话规则行里写着 `toolDeny: ["mcp__*"]` 的会话,升级后拒每一只 MCP 工具,
+   而升级前存下的行整行都是 operator 的(见第 6 条),会话属主自己删不掉,只有 operator 重写。放行表(`APPROVAL_GRANT`、请求的 `settings.permissions.allow`、`allowTools`)照旧不收它。
+6. **会话规则:属主收得回自己加的条目;收不回 operator 写下的(行为变化;wire 加性键 `operatorRules`)**:行记下自己的 operator 部分(`GET` / `PUT` 回包与同步导出的 `rules.operatorRules`;
+   缺席 = 整行归 operator,含升级前存下的每一行 —— 存量行的读法不变)。非 operator 的写只能收回非 operator 写加上去的条目;动到 operator 部分 ⇒ `403 loosen_forbidden`,
+   句子换成 `a non-operator session-rule write may not loosen what an operator wrote; refused: …`(此前 `… may only tighten …`)—— 按句子匹配的脚本改读码。
+   客户端改规则时不要回传 `operatorRules`(与 `rev` / `gen` / `grammar` 同)。
+7. **订正 7.134.0 节第 4 条「话里带 `<system-reminder>` 标签 ⇒ `409 approval_binding_mismatch`」(引擎 7.55.0 起不再成立)**:这条拒现在带判别位,本服务答
+   **`409 resume_outcome_invalid` + `field: "feedback"`**(`retriable: true`,卡留 pending;出路 = 改那段话或去掉再决)。按 `errorCode` / `field` 分支的消费方加一臂;
+   7.134.x 的 worker 仍答旧码(混合舰队期间两形并存)。
+8. **会话店接口只剩头读 `headOf`(嵌入方 BREAKING,类型面)**:自建装配里实现 `OwnerAwareSessionStore`(或交给 `CachingSessionStore` 当内层店)的会话店,
+   按 id 读一行改实现 **`headOf(id)`** —— 一次读答 `{ owner, incarnation, leafId }`(属主 `null` = 匿名;没有这一行 = `undefined`;读故障就抛,不答「没有」)。
+   头答自会话**行**:只是会话条目(内容)读不出时,照答属主与住客 —— 本服务的授权门与各路由的属主门只读这两格,内容的故障留给门放行之后读内容的那一位
+   (头整只抛 = 谁来问都答 `500`,连门拒的调用方也读得出「这个 id 在、而且坏了」)。
+   `ownerOf` / `incarnationOf` / `sessionFaceOf` / `getHead` / `getLeafId` 五只读口不再被读(删掉;引擎 7.55.0 的会话店接口也不再有前两只)。
+   缺 `headOf` 的店:会话授权器在多租户部署答 `403`(不带码;单用户部署不设这道门),后台任务 / 唤醒通知 / MCP 重连三口答 `501 capability.session_ownership_required`(句子点名 `sessionStorage.headOf`),会话事件订阅 / 回卷 / 会话同步等能力位答 `false`。
+   用本服务自带会话店(SQL 两只、local、内存)的部署零动作。
+9. **会话同步拉取口新码 `503 state.file_history_unreadable`**:`GET /v1/sessions/:id/sync/manifest` / `…/sync/history/blobs/:hash` 遇到文件历史读不全(撕裂 / 读不出的边界)⇒ 503 +
+   `permanence`(`transient` 稍后重拉;`terminal` 先修店),此前当成「没有历史」答 200(同步零条 rewind 历史)。按状态码分支的同步脚本加一臂。
+   推送侧(同一条文件历史店契约):对 `capabilities.sessionSyncFileHistory` 为 `false` 的端点(`DB_BACKEND=local`)推引用 blob 的 `fileHistory` ⇒ 第一阶段 `422 missing_blob`(零暂存、零提交;7.134.x 先 `200`、对话提交后才 `422`),按能力位办事(`false` 的端点不带 `fileHistory`)的客户端不受影响;
+   `422` 重放臂的 `adopt_failed` 体多一个键 `permanence`(`transient` 稍后重试同一形;`terminal` 不重试、查 / 修云端文件历史店;没有该键稍后再推一次,仍红查店),预检后取不到的 blob 同样答 `missing_blob`。
+10. **`GET /v1/workflows/:id/journal` 坏行 ⇒ `500 workflow.journal_incompatible` + `ordinal`**:此前这几类行照常读回 200(文件后端跳过读不出的行、SQL 把读不出的行画成「超尺寸」存根)。
+   三个后端判的范围同一个:这条 journal 里任何一行(不论落在哪一页、不论多大;超 64 KiB 的行页里仍只出尺寸存根,但照样被判)被引擎的判官判坏 ⇒ 每一页都答本码,`ordinal` 点名按序数升序的第一条坏行 —— 与续跑的整次拒同判。
+   SQL 后端因此每次读面请求都分块读整份 journal(内存按块有界,量级不超过一次续跑的 `load`):对大 journal 反复轮询的脚本,看进度改用 `GET /v1/workflows/:id`(状态)或 `…/stream`,journal 读面留给翻历史。
+   local 车道的运维计数 tag `server.workflow-journal.corrupt-record-skipped` 撤线(文件 journal 店对坏行改整只拒,不再跳过),按它告警的改看逐命中 warn `workflow_journal_refused`。
+11. **MCP 工具结果多两只码 + 丢会话的读法**:`tool_end.errorCode` 可能是 `mcp.tool_declaration_changed` / `mcp.tool_listing_unreached`(引擎重拨后这只工具的声明变了 / 没被列到,
+   发出之前拒;出路 = `POST /v1/sessions/:id/mcp/reconnect`)。按封闭表穷举工具结果码的消费方加两词。服务器丢了会话(404)的那一次失败仍是 `http_status` + `delivered: "unknown"`
+   —— **不是**「可安全重试」(引擎已自己重拨并重发一次)。
+12. **`WebFetch(domain:<host>)` 的 deny / ask 按主机生效;参数不属于该工具的 deny / ask 规则被拒**(安全;行为收窄;随引擎 `@sema-agent/core` 7.55.0):
+    - 请求 `settings.permissions.deny` / `.ask` 里的 `WebFetch(domain:<host>)` / `WebFetch(domain:*.<域>)` 从「受理但从没生效」变成按调用实际到达的主机拒 / 问。
+      **升级前做**:过一遍写着主机形 deny / ask 的请求模板、壳设置与技能,确认这些拒 / 问仍是想要的(升级后它们开始拦);要整只拒取数写 `WebFetch`(不带括号)。
+      会话规则 `toolDeny`、技能 `disallowedTools`、`POST /v1/rules` 的 deny / ask 此前对主机形答 400,现在受理并生效 —— 无需动手。
+    - 同两桶里参数不属于该工具的 deny / ask(`WebFetch(foo:…)`、`WebSearch(domain:…)`、`TodoWrite(foo:…)`;判据是引擎目录里该工具能按规则读的参数)此前受理、永不命中,
+      现在新提交 `422 request.unprocessable`(句子带 `unsupported.param_unknown` 与该工具能写的参数),停驻任务的存量体带它们续跑 `409 resume_blocked_by_policy`(任务仍停着)。
+      **升级前做**:按句子删掉或改写这些条目(改成该工具自己的参数,或写整只工具);升级前停驻、存量体里带着它们的任务,升级后取消,按改好的设置重提。
+      自挂了与引擎内建同名的工具、在它多出的参数上写 deny / ask 的部署:给那只工具换一个引擎目录里没有的名字。
+13. **`settings.hooks` 的匹配组 / 条目上带 hooks 读者不读的键 ⇒ 新提交 `400 request.body_shape`**(行为面收紧;此前静默剥掉):体带 `unknownKeys`(全坐标,如
+   `settings.hooks.PreToolUse.0.hooks.0.onFailure`)。读者读的键:组上 `matcher` / `hooks` / `source`;command 条目上契约字段加 `plugin` / `args`;其余条目类型上各自的契约字段。
+   **升级前做**:原样投影宿主设置文件的调用方,投影前剥掉读者不读的键(参照实现 2.1.296 的 `onFailure` 等;用同一只契约分类器比对它携带的键即可),并告诉用户这个键不跑;
+   或升级后按拒体 `unknownKeys` 删键重提。续跑重放存量请求不判(这些键照旧剥掉)。
+14. **command hook 条目的 `plugin.options` 停驻时只以封签落盘**(安全;零动作):与 `settings.env` 同属凭据位,可以放敏感值(7.133.0 第 19 条「只放非敏感值」的约束随之退役)。
+   **回滚到 7.134.x 之前**:先把带插件选项的停驻任务决掉或取消 —— 7.134.x 不认这一位上的封签,续跑时那份 hooks 整只不采纳;随包排空检查的 `sealed-credentials-rollback` 判据把它们列为候选(超集)。
+   **多副本升级**:会停驻带插件选项的任务的部署,先停光 7.134.x 副本再起第一个 7.135.0 副本(两版混跑时:7.134.x 副本续跑 7.135.0 停驻的这类任务 ⇒ hooks 整只不采纳;
+   7.134.x 副本新写的这类行在 7.135.0 上续跑 ⇒ `409 conflict.checkpoint_ctx_unsealable`(`reason:"plaintext"`),直到下一次 7.135.0 起服的一次性迁移把它封好 —— 这只迁移只在 M28 窗内(至 2026-11-20)跑,窗外这类行停在 `409` 不再补封)。不带插件选项的任务不受影响。
+15. **耐久事件流开流不再读续跑输入判审批帧族;7.133.x 写下、仍在飞的待决卡照重放**(行为变化;升级序):本版起开流只按本 worker 的呈卡族重放(卡的存在本身证明这条 run 声明过该族,「卡作证」),7.134.0 那一读专为升级窗口里 7.133.x 在飞卡而设的过渡判退役。只影响从 7.133.x **直升**本版、且客户端渲染不了 `approval_request` 的部署:升级序 = 先停掉全部 7.133.x 副本(含它们宿主 run 名下仍在跑的后台子代),等它们写下的待决卡按各自的窗 / 悬挂窗到期并被对账收场,再放新客户端开流;经 7.134.x 中途升级的部署零动作。
+16. **SQL 后端:`permission_rule` 表加一列 `grammar`(🔴 升级前先加列;持久数据,不能删表重建)**:引擎 7.55.0 起人的持久规则桶带规则文法戳,SQL 两方言的店把它存在 `permission_rule.grammar`
+   (TiDB `INT NULL` / PG `INTEGER`)。本服务不发 `ALTER`:存量库缺这一列 ⇒ 起服列册对账拒启(`config.schema_mismatch`),拒句带可直接粘贴执行的语句。
+   **升级前做**:`ALTER TABLE permission_rule ADD COLUMN grammar INT NULL;`(PostgreSQL 写 `grammar INTEGER`)。已有的桶列读 NULL = 戳存在之前写下的桶,照读,下一次写盖戳。
+   **顺序**:先升库(加列)、再升副本 —— 加完列之后,仍是 7.134.x 副本(引擎 7.54.1)**再启动**会对多出的列拒启(只挡重启;已在跑的副本继续运行,它们不选这一列:本版写过(盖了戳)的桶它们读到指纹不符、整桶拒(响亮),
+   仍无戳的桶两版都照读照写,它们的写不盖戳、下一次本版的整桶回写盖章)。戳列与指纹同一条语句写;存量无戳行的指纹与升级前逐字节相同,升级不重写任何存量桶。**不要**手改 `grammar` 列(指纹对不上,桶整桶拒)。
+   **不要**删表重建 `permission_rule`:桶里是人的持久规则。`DB_BACKEND=local` 与内存后端零动作(文件后端的桶由引擎自己盖戳)。本版 SQL 副本读到晚于自己的戳整桶拒(码 `permission_rules.later_grammar`),
+   将来某一版文法再修订后,把库回滚到本版的运维会撞见这一拒:升级引擎即恢复。
+   **回滚到 7.134.x:只回退二进制不可行**(MySQL 协议与 PG 皆然)—— 加过列的库上,7.134.x 的起服列册对账把多出的 `grammar` 读成幽灵列、起服拒(`config.schema_mismatch`,拒句点名 `UNKNOWN column(s) grammar`、不给 ALTER),
+   失败发生在起服期,还没到下面「带戳桶整桶拒」那一步。回滚 = ① 先停光全部 7.135.0 副本(它们的 SQL 读写点名这一列,列没了而它们还在跑会在规则读写上报错);② 手工 `ALTER TABLE permission_rule DROP COLUMN grammar;`(两方言同一句);③ 再起 7.134.x —— **本版还加了 `checkpoint.approval_card`(第 21 条)这第二枚幽灵列**:只摘这一枚,7.134.x 仍被另一枚拒启;两条回滚段的 ①② 合起来做一遍(停光副本一次、两句 `DROP COLUMN` 都执行)再起旧版。
+   **DROP 会丢掉列里的戳**:戳在桶的指纹里,丢了之后带戳的桶在任何版本上指纹都对不上 —— 想保住日后升回本版的可能,在**停光全部 7.135.0 副本之后、DROP 之前**把戳存进一张表(停光之前存的不算:存完之后仍在跑的 7.135.0 副本再盖的戳会随 DROP 永久丢失,那只桶在任何版本上都整桶拒):
+   `CREATE TABLE permission_rule_grammar_stash (owner_key VARCHAR(190) NOT NULL PRIMARY KEY, grammar INT NOT NULL);`(PostgreSQL:`owner_key VARCHAR(190) COLLATE "C" NOT NULL PRIMARY KEY, grammar INTEGER NOT NULL`),
+   再 `INSERT INTO permission_rule_grammar_stash SELECT owner_key, grammar FROM permission_rule WHERE grammar IS NOT NULL;`。升回时先照「升级前做」加列,**写回放在加列之后、起第一个 7.135.0 副本之前**(这时没有写者):
+   MySQL 协议 `UPDATE permission_rule p JOIN permission_rule_grammar_stash s ON s.owner_key = p.owner_key SET p.grammar = s.grammar WHERE p.grammar IS NULL;`,
+   PostgreSQL `UPDATE permission_rule p SET grammar = s.grammar FROM permission_rule_grammar_stash s WHERE s.owner_key = p.owner_key AND p.grammar IS NULL;`;
+   `grammar IS NULL` 只补还没有戳的行(这些桶在 7.134.x 上整桶拒;桶体与指纹没有写者改过〔取 dot 的计数器可能前移,它不在指纹里〕)。写回之前起的 7.135.0 副本对这些桶整桶拒(指纹对不上;响亮、无害),写回后恢复;核对无误后 `DROP TABLE permission_rule_grammar_stash;`。
+   DROP 之后:本版写过的桶(带戳)7.134.x 读不了、整桶拒(它不读戳,指纹对不上;响亮)—— 留在本版或更新;没被本版写过的桶(列 NULL)两版照读照写。
+17. **会话 fork 只拷已提交的叶(行为修正)**:`POST /v1/sessions/:id/fork` 与 Fork 工具经宿主会话店铸的孩子会话不再带源会话在飞的 assistant 轮(带一个还没有结果的工具调用的那一轮)—— 孩子从它的父开始;
+   已结的轮整份拷。此前三只会话店拷整份日志,孩子唤醒时被补一条 `[INTERRUPTED]` 结果。零动作;按「fork 一定含在飞轮」写脚本的(未见)改读孩子的实际条目。
+18. **技能条目自带的两只工具名单 `allowedTools` / `disallowedTools` 开始生效(行为变化;升级序;零 DDL)**:配置源 —— 中心的技能域或 `CONFIG_PROVIDER=local` 的 `config.d/skills.json` —— 里技能条目写着这两个键的,
+   此前本服务的 worker 不把它们交给引擎(静默无效),本版起交:`allowedTools` 是该技能被激活的那一 run 的 allow 规则来源(免问;deny / ask、plan 模式、组织上限与强制提问照旧站着),
+   `disallowedTools` 是 deny 规则来源,拒侧引擎读成空的条目(例:`*`)⇒ 那次激活不发生(`userInvokedSkills` 按名点用的:终局 `failed`、码 `config.skill_deny_unreadable`;模型自己调 `Skill` 工具的:那一次调用被拒、错误结果回给模型)。缺席 ⇒ 没有;在场 ⇒ 整只原样(`[]` 引擎读作未声明)。
+   **升级前做**:① 过一遍已经写着这两个键的技能条目,确认它们现在生效是想要的(放行免问是放宽方向,先审);② **升级序**:先把读这条链的每一跳都升上来(本服务各副本,以及其它读 `/effective` 技能域的读者,例如 client-core 的云端腿),再在管理面给技能写名单 ——
+   没升的读者静默丢这两位,丢 `disallowedTools` 就是比作者所写更松。不想让某条技能带名单就删掉这两个键。
+19. **`a2aPeers[i].url` / `.cardUrl`、`settings.hooks` 的 http 钩子 `url`、`settings.webSearch.endpoint` 带凭据 ⇒ 新提交 `400 request.field_invalid`**(安全;行为面收紧;第 1 条同一条规则的另三座):
+   URL 带 userinfo,或带名字在凭据名表里的 query / fragment 参数(全表与读法见契约附录 A `request.field_invalid` 行)⇒ 新提交三腿 400,体带 `field`
+   (`a2aPeers[i].url` | `a2aPeers[i].cardUrl` | `settings.hooks.<事件>[g].hooks[h].url` | `settings.webSearch.endpoint`)与 `reason`(`url_userinfo` | `url_credential_param`)。
+   **升级前做**:调用方把凭据挪进同一条目的已封签位 —— 对端 / 钩子条目的 `headers`(`"Authorization": "Bearer …"`;钩子的 `headers` 可用 `$NAME` + `allowedEnvVars` 让配置本身不带密钥值),搜索后端的 `apiKey`;
+   只认 query 鉴权、不收请求头的服务端(含 searxng 实例:searxng 腿不发鉴权头)改在部署面声明。搜索后端地址的 userinfo 形此前已是 400,句子不变,体多 `field` / `reason`。
+   续跑重放存量请求不判(升级前停驻的任务照常续跑,续跑上下文里的 URL 仍是原字节 —— 介意的部署把它们结掉后轮换那几枚凭据);部署面声明的地址(中心 / `config.d` / 部署 env)不判。按 `field` 坐标或 `reason` 穷举分支的消费方多认这四个坐标。
+   **同批的行为变化**:一次提交的 `a2aPeers` 超过 32 条(读器的挂载上限)⇒ 新提交 `400 request.field_invalid`,`field:"a2aPeers"` · `reason:"over_cap"` · `count` · `cap`(此前 200,第 33 条起丢弃、只在运维 warn 里点名):界外的尾项从不挂载,但提交体整份落盘,上面那条判官要么看过每一条对端的 `url` / `cardUrl`、要么这份体不收。升级前把一次提交的对端数压到 32 以内。
+20. **设备车道:有效工作目录不是绝对路径的拒带终局码 `config.device_cwd_invalid`**(7.134.0 节第 8 条「工厂的其余几只拒同样带机读码」漏了这一只,本版补齐):会话 cwd / 委派链父 cwd / 入籍时落库的 `workspaceRoot` 任一来源不是绝对路径
+   (入籍口收紧之前落库的相对根,或引擎交来的相对父 cwd)⇒ 续跑失败的终局码 `config.device_cwd_invalid`(修前这一形抛裸错误,终局码不带它;句子不变,多一段 `[config.device_cwd_invalid]`)。
+   按终局码匹配续跑失败的读者(运维看板 / 重试规则)把它与 7.134.0 节列的四个词一并认进去;它是装配 / 数据错误,重试无益 —— 出路是修有效工作目录的来源(重新入籍给绝对路径)。
+21. **SQL 后端:`checkpoint` 表加一列 `approval_card`(🔴 升级前先加列;持久数据,不能删表重建;嵌入方 BREAKING,类型面)**:检查点店写行时把门上的审批卡词照存进这一列(引擎 7.55.0 的行事实派生),
+   到期两条腿(收割作废 / SLA 拒扫)与运维待批队列行的卡读它。本服务不发 `ALTER`:存量库缺这一列 ⇒ 起服列册对账拒启(`config.schema_mismatch`),拒句带可直接粘贴执行的语句。
+   **升级前做**:`ALTER TABLE checkpoint ADD COLUMN approval_card TEXT NULL;`(PostgreSQL 写 `ALTER TABLE checkpoint ADD COLUMN approval_card TEXT COLLATE "C";`)。
+   升级前停驻、升级时还挂着的行由起服的一次性迁移按同一只派生补上这一列(待决的审批门行;文档读不出的行留空,起服日志 `one_time_migrations_applied` 的 `parkedApprovalCardsBackfilled` /
+   `parkedApprovalCardRowsUnreadable`(条数),并一行 warn `parked_approval_card_row_unreadable` 点名会话;卡词超过列容量 —— MySQL 协议 `TEXT` 65,535 **字节**、PG 无上限 —— 的行同一个报法:留空、计数在 `parkedApprovalCardRowsTooLong`,并一行 warn `parked_approval_card_row_too_long` 点名会话(另带字节数),起服不挡:引擎铸的卡词是短词,超长只会是手改的行)。**顺序**:先升库(加列)、再升副本 —— 加完列之后,仍是 7.134.x 的副本**再启动**会对多出的列拒启;同一只库不混跑两版(与第 4 / 16 条同一升级序):
+   已在跑的 7.134.x 副本写下的问答停驻行不带这一列,在下一次本版起服之前到期会进 SLA 拒扫(引擎拒收,行停到绝对兜底)而不是作废。
+   **不要**删表重建 `checkpoint`:表里是在飞的停驻(待批的卡、待审的计划)。`DB_BACKEND=local` 与内存后端零动作(停驻行在引擎自己的文件店里,卡从文档读)。
+   **回滚到 7.134.x:只回退二进制不可行**(MySQL 协议与 PG 皆然)—— 加过列的库上,7.134.x 的起服列册对账把多出的 `approval_card` 读成幽灵列、起服拒(`config.schema_mismatch`,拒句点名 `UNKNOWN column(s) approval_card`、不给 ALTER)。
+   回滚 = ① 先停光全部 7.135.0 副本(它们的停驻写与待批队列读点名这一列,列没了而它们还在跑会报错);② 手工 `ALTER TABLE checkpoint DROP COLUMN approval_card;`(两方言同一句);③ 再起 7.134.x —— **本版还加了 `permission_rule.grammar`(第 16 条)这第二枚幽灵列**:只摘这一枚,7.134.x 仍被另一枚拒启;两条回滚段的 ①② 合起来做一遍(停光副本一次、两句 `DROP COLUMN` 都执行)再起旧版。
+   DROP 只丢这一列(派生数据):停驻行自己的文档(卡词在门上)一个字节没动,7.134.x 照旧从文档读卡;再升回本版时先照本条加列,窗内 M29 把待决的审批门行重新回填。
+   **嵌入方(类型面,BREAKING)**:`StoreBackend.runOneTimeMigrations()` 的返回型 `OneTimeMigrationReport` 多三个必填键 `parkedApprovalCardsBackfilled`(条数)/ `parkedApprovalCardRowsUnreadable` /
+   `parkedApprovalCardRowsTooLong`(后两者是点名行的数组),`NO_SQL_MIGRATIONS` 同步多三键(local 车道恒 `0` / `[]` / `[]`)。自实现 `runOneTimeMigrations()` 的代码(实现 `StoreBackend` 的店,或标了这只返回型的函数)tsc 红 —— 补上三键;
+   只读这份报告的代码不受影响(多出的键没有人读)。部署零动作。
+22. **一次性迁移 M4 退役:审计明细里的 JSON 文本 `null` 不再由起服改写(持久数据面;行为变更;嵌入方 BREAKING,类型面)**:7.93.5 引入的启动期迁移 ——
+   把设备审计表 `device_audit` 的 `detail` 列里 JSON 文本 `null`(7.93.4 及更早的写腿对显式 `detail: null` 落下的旧字节)改成 SQL NULL —— 窗(发布日 + 30 天)已关,本版删了它的码,
+   以及起服日志行 `one_time_migrations_applied` 里的读数字段 `auditDetailJsonNullRows`(同一行里 `removableAfter` 读数的 `M4` 键随登记行消失,`note` 不再叙述它)。按这个字段做告警或看板的规则要删。
+   - **嵌入方(类型面)**:`StoreBackend.runOneTimeMigrations()` 的返回型 `OneTimeMigrationReport`(经包根导出的 `StoreBackend` 可达,本身不在包根导出名里)去掉 `auditDetailJsonNullRows`;读它的代码、把值标成 `OneTimeMigrationReport` 再写这一键的对象字面量 tsc 红;自实现该方法、未标注类型就直接返回含这一键的字面量的代码 tsc 不报(多出的键没有人读),也请一并删掉。
+   - **谁受伤**:从 ≤ 7.93.4 直接跳到本版、中间没在 7.93.5–7.134.x 任一版起过服的库(含升级后仍有 ≤ 7.93.4 旧副本混跑写入的库)—— 设备审计表里留着 `detail` 为 JSON 文本 `null` 的行时,
+     含这种行的那一页 `DeviceStore.listAudit()` 读不出来(整页拒,拒句点名行 id;刻意不逐行跳过 —— 跳过会把「这一页少了一条」与「本来就没有」变成同形)。本服务自带的 HTTP 面没有路由读这张表,读它的是嵌入方与运维脚本。
+     起过 7.93.5 及以后任一版的库、新库、`DB_BACKEND=local` 与内存形(没有设备审计表)零影响。
+   - **做法**(只在受伤时):要么先在 7.93.5–7.134.x 任一版上对这只库起服一次(迁移跑完)再升;要么在本版上手工跑下面一句(幂等,可重复跑;只碰 JSON 文本 `null` 的行,真有明细的行与本来就是 SQL NULL 的行一个字节不动):
+     - TiDB / MySQL 协议:`UPDATE device_audit SET detail = NULL WHERE detail IS NOT NULL AND CAST(detail AS CHAR) = 'null';`
+     - PostgreSQL:`UPDATE device_audit SET detail = NULL WHERE detail IS NOT NULL AND detail::text = 'null';`
+23. **嵌入方:审批决议的店接口 `ApprovalAskStore.decideAsk` 第三位插入必填 `owner`**(BREAKING,类型面;部署零动作):经包根导出型 `StoreBackend` 的 `approvalAsk()` 成员可达的问答账本店,
+   人答臂的签名由 `decideAsk(askId, batchId, decision)`(7.134.0)改成 **`decideAsk(askId, batchId, owner, decision)`** —— `owner: string | null` 必填、无缺省,是这次决议的门**判过的**那位属主
+   (门读到的行上 `owner` 列;不是调用方的主体:运维代决别人的问,传的是那个别人;`null` 只等于属主为 `null` 的行)。tsc 红即是提示,零别名。
+   **升级时做**:① 调用 `decideAsk` 的嵌入方代码补上第三参;② 自实现该店(自建 `StoreBackend`,`approvalAsk()` 返回你自己的店)的嵌入方,把「行上的属主列逐字等于 `owner`」并进单赢者 CAS 的谓词
+   (与问 / 批 / 仍待决并列;MySQL 协议侧按字节比,尾空白不算同一位属主):行此刻不带这位属主(门读行之后被 `POST /v1/adoption` 改写)⇒ 不决、零写,答
+   `{ ok: false, reason: "ask_not_pending", row: null }` —— 输者读数里该行读作缺席(不交出别人的行),这一判排在幂等键唯一性之前(出域的那一笔不碰键)。两扇决议门把它读成缺席,与「不存在 / 不是你的」同体同码:
+   耐久回决口 `404 not_found.ask`、live 应答口 `404`(`cause: unknown_or_other_replica`)。本服务自带三店(SQL 两方言、local、内存)已是这个读法,用它们的部署零动作。
+
+## 7.134.0 —— 停驻任务续跑上下文里的请求凭据只以封签落盘(安全;BREAKING,嵌入方自建 ServiceDeps 带 checkpointStore 必须带 checkpointCtxSealing,否则 createHttpServer 拒启;保管目录建不了的耐久审批部署起服拒;保管目录跨重启持久、多副本共享;先停光 7.133.x 再起 7.134.0,两版不能混跑;一次性迁移 M28) · 引擎 7.53.0 → 7.54.1 提货:先升所有会续跑的 worker(停驻行多两只要求词) · 设备车道发射闸的三条部署前置 · 决定体 `feedback`(人的放行带的话;拒决 / 策略上 400、直连门 400) · `APPROVAL_AUTO_BUDGET` 的放行改记成策略答的放行 · `mcpServers[].toolFaces` / `startupTimeoutMs` 坏形新提交 400 · 请求侧 `toolAxes` 写 `boundaryFlow` 被拒 · 设备车道文件失败码 `target_unavailable` 与换绑后的续跑拒 · placed 会话准入拒句换成引擎的句子 · 带主体头的 service 凭据请求在 fleet 面上就是那位主体(安全;BREAKING:行为面收窄(多租前端带主体头的运维脚本不再看全舰队,升级前核)+ 类型面(嵌入方自实现的会话店暂存导入)) · 审批卡只发给声明认得这一族的客户端(请求面 `settings.approvalFrameFamilies`;没声明的任务遇审批当场停驻 / 拒;BREAKING,wire;客户端先升,见位才发)
+
+1. **停驻任务续跑上下文里的请求凭据只以封签落盘**(安全;BREAKING,嵌入方自建 ServiceDeps 带 checkpointStore 必须带 checkpointCtxSealing,否则 createHttpServer 拒启):开了耐久审批的部署(`DURABLE_APPROVAL`;单用户 + 有耐久店时缺省开,含 `DB_BACKEND=local`),任务提交体里 `mcpServers[].transport.headers` / `transport.env` 的值、
+   `a2aPeers[].headers` 的值、`settings.env` 的值、`settings.webSearch.apiKey`、http hook 条目的静态头 `settings.hooks.<事件>[].hooks[].headers` 的值在续跑上下文
+   (SQL `checkpoint_ctx.ctx` / local `<数据根>/checkpoint-ctx/`)里改存封签(对着这一域自己的保管钥匙 `<数据根>/sealed-key/checkpoint-ctx-keys/` 最新那把公钥封,绑着这一行的会话;
+   与模型钥匙 `sealedApiKey` 那对钥匙不共用);续跑时开封,任务照原值重建。开不开 ⇒ `409 conflict.checkpoint_ctx_unsealable`(`field` + `reason`)。**升级前做**:
+   - **保管目录可建**:服务要能建并 `chmod 0700` `<数据根>/sealed-key/` 与其下的 `checkpoint-ctx-keys/`(只读挂载 / 权限不够 ⇒ 7.133.x 只是一行 warn `sealed_key_store_unavailable`,
+     7.134.0 起耐久审批在场的部署先 warn `checkpoint_ctx_sealing_unavailable` 再起服拒,拒句点名 `checkpointCtxSealing`;确实不要停驻就显式 `DURABLE_APPROVAL=false`)。
+   - **保管目录跨重启持久**(SQL 后端也一样:钥匙不进库):`<数据根>/sealed-key/` 在一个跨重启留存的卷上。目录空 ⇒ 起服生成新钥匙 ⇒ 重启之前停驻、带上述凭据的任务续跑恒答 409
+     `reason:"key_not_held"`(旧钥匙已不在任何副本上,恢复不了,只能作为新任务重提)。容器部署给数据根(或至少 `sealed-key/`)挂持久卷。
+   - **多副本共享钥匙**:SQL 后端的多副本,每个副本的 `<数据根>/sealed-key/` 必须是同一份(整个目录,含子目录 `checkpoint-ctx-keys/`;先起一个副本让它生成,再把那份目录放进每个副本 —— 与 USAGE §9.10 ⑦
+     模型钥匙的多副本要求同一件事)。不共享 ⇒ A 副本封的行在 B 副本上续跑答 409 `reason:"key_not_held"`;把钥匙文件补齐、重启那个副本(钥匙只在起服时读)之后,同一个决定原样重发即可。
+   - **升级序:7.133.x 与 7.134.0 不能混跑**。**先停掉全部 7.133.x 副本,再起第一个 7.134.0 副本**(一次性迁移 M28 在它起服时跑,把升级前停驻行里的明文原地封好:不删行、不动续跑时钟;
+     起服 info 一行 `checkpoint_ctx_credentials_sealed`;M28 的窗 = 发布日 + 30 天,窗外不扫)。多副本:先起一个 7.134.0 副本、等它起好再起其余副本(耐久审批开着时它起好即打出上面那一行)——
+     停驻封签的钥匙在新子目录 `sealed-key/checkpoint-ctx-keys/` 里,升级后第一个起服的 7.134.0 副本生成它(`sealed-key/` 早已共享好也一样:那是模型钥匙的那一层);
+     同时起多个副本会各建一把,互相答 `key_not_held`,直到各自重启一次(钥匙只在起服时读目录里的全部文件)。混跑时 7.133.x 副本续跑一条已封签的行(M28 封过的,或 7.134.0 副本新写的)会把凭据位当空值 ——
+     MCP 的 `headers` / `env` 整键不交(server 照挂)、A2A 对端不挂、`settings.env` 不采纳、WebSearch 不挂、`settings.hooks` 整份不采纳(同一份里的 command hook 一起)—— 任务无凭据照跑、不报错
+     (只有运维日志各一行 warn);7.133.x 的续跑读者没有对封签值的拒臂,新版本改不到它。反过来,7.133.x 副本新写的明文行在 7.134.0 副本上续跑答 409 `reason:"plaintext"`。
+   - **回滚**:降级到 7.133.x 之前先把带凭据的停驻行结掉(决定或取消);已封签的行在 7.133.x 上同样是无凭据续跑、不报错。随包排空检查的 `sealed-credentials-rollback` 判据列出它们:
+     `DB_BACKEND=local` 跑 `node node_modules/@sema-agent/server/scripts/drain-check-local.mjs [<数据根>]`(末行 `SEALED-CREDENTIALS-ROLLBACK rows=0` 才算结完,命中行 `field=` 点名哪一个凭据位;workflow 子代卡续跑读的是发起会话那一份,自己那一份不带封签时脚本按候选列出、点名 `runId=`);
+     SQL 后端跑随包 `scripts/drain-check.{mysql,pg}.sql` 里同名那一段(`hit_rows` 为 0;它数的是候选超集)。与第 2 条(`approval_targets` / `cross_boundary` 两类停驻行)同一个动作。
+   - **嵌入方**(自建 `ServiceDeps`,带 `checkpointStore`;BREAKING —— tsc 照绿、起服拒就是通知):新可选位 `checkpointCtxSealing`,带店就必须带它,否则 `createHttpServer` 拒启;
+     铸法 `await ensureCheckpointCtxSealing(sealedKeyDir)`(在 `sealedKeyDir` 之下建 `checkpoint-ctx-keys/`),工厂与型 `CheckpointCtxSealing` 从包根导出。
+   - **读拒体的消费方**:`conflict.checkpoint_ctx_unsealable` 是新码(409,确定性 —— 原样重试同答;`reason` 是 `key_not_held` 时等运维补齐钥匙、重启那个副本(钥匙只在起服时读)再重发,其余作为新任务重提、
+     仍停驻的先取消)。
+2. **升级序:先把所有会续跑的 worker 升到 7.134.0,再让新 worker 停行**。7.134.0(引擎 7.54.1)停下的审批行可能带两只新要求词:`approval_targets`(批准对象多一位 `pendingAction.targets`,`rosterDigest` 停铸)
+   与 `cross_boundary`(执行在目标设备上的树)。7.133.x 及以前的 worker 在认领前拒这类行(`checkpoint.unsupported_version`,`version_newer`,`requires` 点名该词),行留 pending,
+   换到新 worker 上照常赎回。SQL 后端把检查点存成 JSON 文档 —— **零 DDL**。回滚到 7.133.x 之前先把这两类停驻行结掉(决定或取消)。
+3. **设备车道发射闸的三条部署前置**:① 带 `cross_boundary` 的行只在 ≥ 7.134.0 的 worker 上赎回(同第 2 条);
+   ② 设备会话的新一轮没有版本闸 —— 整个舰队都 ≥ 7.134.0 之前不要开 `multi_tenant` 的设备车道;③ 姿态 `RunnerDeps.crossBoundaryPosture` 每台 worker 显式同值,本服务由 `REQUIRE_PRINCIPAL` 派生
+   (`true` ⇒ `multi_tenant`,否则 `single_user`;不是新旋钮)。没声明姿态的 worker(嵌入方自建 Runner、不经本服务的部署姿态座席族)对宿主父腿不启站,并按每条武装腿铸一条 operator 通告
+   `config.cross_boundary_posture_undeclared`。`REQUIRE_PRINCIPAL=true` 且跑设备车道的部署:写到设备之外、离目标读之后回到设备的调用从此停下等人(bypass、策略答、无人值守的整批放行都不放)。
+   新的事件出现在设备车道的 run 上(宿主车道永不出现):`GET /v1/runs/:id/events` 上是 `cross_boundary_taint`,`GET /v1/tasks/:id/stream` 上是 `cross-boundary-taint`;按事件名精确分派的消费方多认一种。
+4. **耐久决定口的决定体多一只键 `feedback`**(人写在审批卡上给代理的话):只在人的放行上收;拒决或 `decidedBy: "policy"` 上带它 ⇒ `400 request.field_conflict`(`detail.kind: "approval_feedback"`),
+   非字符串 ⇒ `400 request.field_invalid`,直连门 worker 上 ⇒ `400 feedback_not_in_proof`;话里带 `<system-reminder>` 标签 ⇒ `409 approval_binding_mismatch`(引擎原句,卡留 pending,改那段话再决)。
+   7.133.x 对这只键答 `400 request.body_shape`(`unknownKeys:["feedback"]`)。混合舰队里引擎 < 7.54.0 的 worker 静默忽略它 —— 同第 2 条,先升会续跑的 worker。
+   按 `detail.kind` 穷举分支的消费方多一个词 `approval_feedback`。
+5. **`APPROVAL_AUTO_BUDGET` 的放行改记成策略答的放行**:额度内放行的那次调用,结算记录是 `policy_allowed`、审批人 `auto_approve_budget`(此前是名单表态的放行)。
+   引擎 7.54.0 起名单表态不再替 MCP / A2A 工具答掉「没人表态」那一问,不改就会每次出卡;现在额度在这两类工具上恢复生效。没有人可问的探针请求、参数绑不住批准的调用不扣额度。
+   按结算记录审计的规则跟着改。
+6. **`mcpServers[].toolFaces` 与 `startupTimeoutMs` 的坏形新提交 400**(判官换成引擎包根的 `readToolFaces` / `mcpStartupTimeoutMs`):`toolFaces` 上空工具名、保留审批卡、
+   `pathTarget.access` 不在 `read` / `create` / `edit`(`"write"` 拒)、`pathTarget.base: "root"` 而 `access` 不是 `read`、单独的 `patternParam`、未知成员、安全轴写成面成员、非布尔旗 ⇒ 整条 400
+   (续跑重放整条 server 不进;中心 / `config.d` 腿跳过该 server 并点名 warn;绕过本服务直接到引擎的部署声明整任务拒 `config.tool_face_invalid`)。`startupTimeoutMs` 坏值 ⇒ `400 request.field_invalid`
+   (7.133.x 照常 200、引擎拨号时只拒这一只 server)。改对那一格,见 USAGE 9.5e。
+7. **请求侧 `toolAxes` 写 `boundaryFlow` 被拒**:`mcpServers[i].toolAxes.<tool>.boundaryFlow` ⇒ 新提交 `400 request.field_invalid`;`a2aPeers[i].toolAxes.<skill>.boundaryFlow` ⇒ 那条对端不挂、warn 点名。
+   续跑重放同 `toolAxes` 判不过的既有处置:一次性迁移 M19 的窗内按升级前读法重读(`boundaryFlow` 作未知成员剔掉、条目照挂、一行运维 warn),窗关后整条不进。
+   声明引擎专用工具只有部署声明(`config.d` / 配置中心)能写:`boundaryFlow: "engine"` 且同条 `egress: false`。
+8. **设备车道:文件失败码 `target_unavailable`;续跑腿的拒带机读终局码**:文件操作的失败码,目标在提交前拒(不在线 / 忙 / 未绑 / 别处挂着 / 认领冲突 / 换绑冲突 / 限流 / 排空)与设备结局 `target_unavailable` 从 `transport_lost` 改为 `target_unavailable`
+   (从未开始、零效果、目标回来后重试安全)—— 按 `transport_lost` 匹配设备文件失败的规则跟着改。停驻行记下的设备与 placement 根此刻绑的不是同一台(换绑过)⇒ 续跑失败终局码 `device.identity_mismatch`
+   (不连另一台、不改道):先把停驻的任务结掉或取消,再在新绑的设备上重新起。工厂的其余几只拒同样带机读码,续跑失败的终局码随工厂抛的 `.code` 变(修前码只在句子里,终局码不带它):
+   placement 根没有设备绑定 ⇒ `device.not_bound`;绑定的设备已不存在或不归该绑定的主体 ⇒ `not_found.device`;设备已吊销 ⇒ `device.revoked`;placement 根为空(装配错误)⇒ `config.placement_root_invalid`。
+   按终局码匹配续跑失败的读者(运维看板 / 重试规则)把这四个词与 `device.identity_mismatch` 一并认进去;前三形的出路同换绑(结掉停驻的任务,绑上可用的设备 —— 吊销是终态,重新入籍得到的是新设备 —— 再重新起),`config.placement_root_invalid` 是装配错误、重试无益。
+9. **placed 会话准入的拒句换成引擎的句子**:判据改问引擎(`admitSessionPlacement`),码不变(`placement_refused`);缺元组那一形的句尾从 `written away out of band` 变成 `or the repo dropped the tuple` ——
+   按原句匹配告警的运维规则跟着改。
+10. **「service 凭据 + 验过的主体」= 那位主体,不再是全舰队**(安全,BREAKING:行为面收窄(多租前端带主体头的运维脚本不再看全舰队,升级前核)+ 类型面(嵌入方自实现的会话店暂存导入);主体按部署的身份读法 —— 前端设的主体头,直连门上是签名的 principal 令牌,那里自报的头不算):舰队流 `GET /v1/fleet/stream`、会话列表 `GET /v1/sessions`、发件链接列表 `GET /v1/sendfile-links`、
+   后台名册 `GET /v1/agents/roster`、trace 读口 `GET /v1/tasks*`、用量 `GET /v1/usage/*`、`GET /v1/tasks/source-summary`、`/metrics*`、`DELETE /v1/sessions/:id`、`POST /v1/sessions/:id/fork`、
+   同步族 `/v1/sessions/:id/sync/*` 上,带 `x-agent-principal` 的 service 凭据请求按那位主体钉住(行只列它的;他人会话 404 / `{deleted:false}`;运维聚合两口 `401 auth.unauthorized`)。
+   全舰队视图 = **不带主体头**的 service 凭据(读写两档),或只读令牌(只读面 `TRACE_TOKEN`;指标族 `METRICS_TOKEN`)。dev-open 部署、只读 `TRACE_TOKEN`、不带主体头的 service 凭据的读数不变;
+   运维名册(`OPERATOR_PRINCIPALS` / `OPERATOR_SINGLE_USER`)不给 fleet 面开全舰队,运维口照旧读它。
+   - **升级前核**:多租部署(`REQUIRE_PRINCIPAL=true`)上用「service 凭据 + 某个主体头」拉全舰队视图的运维脚本 / 看板 / 中继 —— 去掉主体头,或改用只读令牌;单用户部署同理(壳不设 `SEMA_LIVE_PRINCIPAL` 时发 `default`,
+     它的舰队流 / 会话列表 / trace / 用量按 `default` 收窄,两只运维口对它 401)。
+   - **存量**:此前经「service 凭据 + 主体头」同步推上来的新会话是无主行,在同步族上对那位主体是 404,fork 同样 404(单用户部署的 `default` 主除外:存量无主会话互认臂照旧放它 fork / 删除 / 同步;会话视图照旧开放);
+     要交回那位主体 ⇒ 不带主体头拉下来,再以那位主体推成一只新 id。存量无主会话的同步族在单用户形下照旧可用(与 fork / 删除同一只互认臂:单用户形 ∧ 行无主且非 placed ∧ 调用方恰为 `default`);多租形、别的主体、无主的 placed 行仍 404。
+     `default` 推进一只无主会话时,只有真提交(`fresh` / `fast_forward` / `fork` / `stale`)把这行的属主落成推送方,`identical` 捷径不提交、不换属主(行照旧无主,附随物照常重放)。
+   - **暂存句柄**:同步导入第一阶段由 fleet 调用方(不带主体头的 service 凭据)开的暂存,第二阶段也只认 fleet 调用方 —— 两阶段请同一把凭据、同一个主体头。
+   - **导入第二阶段与第一阶段同一只属主门**:第二阶段在流读完之后、提交前按会话此刻的面再判同一只门 —— 流期间别的副本删建 / 认领 / 新建了这只会话、这位调用方此刻不过门 ⇒
+     `404 not_found.session`(与门同体);提交只落在开暂存时门判过的那一格属主上 —— 属主格变了而调用方仍过门(fleet 调用方,或那一行此刻归它)⇒ `409 conflict`,
+     固定句 `session owner changed while the import streamed; nothing was imported — start the sync again`,事务回滚、目标会话一个字节没动。两答的出路相同:从第一阶段重来(重新过门)。
+     ≤7.133.x 第二阶段只核暂存开启者,照覆盖、并把目标行的属主改成导入方。嵌入方自实现会话店的暂存导入(`OwnerAwareSessionStore.beginImportStaging` 交出的句柄):
+     `commit(owner, opts)` 的 `opts` 必传、带 `expectedOwner`(按 `ownerOf` 的读法:`undefined` = 无此会话,`null` = 无主),提交事务里属主格不等就回滚、抛码为 `conflict` 的 `SessionError`(类型面 BREAKING,tsc 红即通知)。
+   - 7.133.0 节第 10 条最后一句说的「`/sync/*` 把带凭据的调用方读成 fleet-wide」自本版起不成立:`/sync/*` 与会话视图读同一只判据。
+
+11. **审批卡只发给声明认得这一族的客户端(请求面声明 `settings.approvalFrameFamilies`;BREAKING,wire)**:一条任务只在提交体的 `settings.approvalFrameFamilies` 含本服务呈卡用的那一个族
+   (`GET /v1/capabilities` 顶层 `approvalFrameFamilies` 的那个词)时收到活卡;缺席 / 不含 ⇒ 这条任务遇审批当场收场,不呈卡、不换族、不双发,也不再挂到窗口过期。结局看这台 worker 有没有耐久店(checkpoint 店;`DURABLE_APPROVAL` 开着):**在场** ⇒ 按 `UNATTENDED_APPROVAL_POLICY`
+   (`park` ⇒ 任务停驻、`/v1/approvals/:sessionId/decide` 作答;`deny` ⇒ 当场拒,拒因句点名缺的族);**不在场**(`DURABLE_APPROVAL=false`,含 helm 图表关持久的形)⇒ 没有地方停驻,受门工具当场拒(缺省 `park` 政策下是引擎按 `approver_unavailable` 拒,结算当事方是「无人」,不是 `deny` 政策的结算,拒因句不点名缺的族与声明键;`deny` 政策下是部署政策拒),run 照常收尾,无卡、无 `/decide`。**升级前做**:
+   - **会渲染审批卡的客户端(壳 / SDK 审批循环 / 自写客户端)**:见能力位 `taskSettings.approvalFrameFamilies: true` 才带键(7.133.x 及以前对这个键答 `400 request.body_shape`),
+     在 `POST /v1/tasks/stream` · `POST /v1/runs` 的提交体里声明你渲染得了的**每一个**族(两族都渲染就写两个;只写最新那一个,到了呈 `tool_approval` 的服务上就没有活卡)。
+   - **升级序**:发版时还没有主线客户端发 `settings.approvalFrameFamilies` —— 声明随 cli / client-core 的后续版本到货(以各自的发布说明为准)。到货前:耐久 worker 上 park 等 /decide,非耐久 worker 上(缺省 `park` 政策下)引擎按 `approver_unavailable` 拒(fail-closed;`deny` 政策下是部署政策拒);
+     运维要保旧壳体验,只能先不升 server。到货后:客户端先升到会声明的版本,再升服务端;反过来的窗口里,不声明的客户端遇审批当场停驻 / 拒(不再挂住)。
+   - **没有耐久店的 worker**(`DURABLE_APPROVAL=false`,含 helm 图表关持久的形):没有地方停驻 —— 未声明的客户端遇受门工具当场拒,run 照常收尾,无卡、无 `/decide`。对 7.133.x 这是有意的行为收窄
+     (那类 worker 在 7.133.x 上对这类客户端出活的 `tool_approval` 卡):硬破坏,不发旧族、不双发、不留回退;客户端先声明,或先不升服务端。
+   - **关了流内审批的部署**(`STREAM_APPROVAL_ENABLED=false`,本服务呈 `tool_approval`):判据对两个族同一条 —— 为老客户端专门关掉它的部署,升到本版后老客户端同样当场停驻 / 拒,
+     要客户端声明 `"tool_approval"` 才有活卡。
+   - **升级前停驻的任务**:续跑读持久化的提交体,里面没有声明 ⇒ 续跑那一段遇审批同样当场收场(停驻的卡照旧经 `/decide` 作答)。
+   - **坏声明**:非数组 / 词表外 / 重复 ⇒ `400 request.field_invalid`(`field: "settings.approvalFrameFamilies"` · `reason: "bad_entry"` · 坏项的 `index`);`[]` 合法(与缺席同读)。
+   - **按运维日志分账的**:`approver_unavailable` 多一个 `arm` 词 `frame_family_undeclared`。
+
 ## 7.133.0 —— `SANDBOX_PKG_SOURCE=custom` 的包源 / 镜像地址带 userinfo 起服拒启(安全) · 删包根导出 `judgeModelRouteGap`(BREAKING;壳 / 包改读 `GET /v1/models` 的 `modelPlane`) · 审批帧一条腿一个帧族(BREAKING,wire;消费方按 `approvalFrameFamilies` 分派) · 坏 JSON 体统一答 `400 request.invalid_json`、读体超限统一答 `413`(BREAKING,wire 码 / 状态码变更;此前多数口答 `request.rejected`,一批口把超限折成 `400 request.invalid_json`) · device 车道四根数值旋钮越界起服拒启、协议修订号抬到 2(结局码集随修订号) · acceptEdits 的免问写域改为引擎的写根(行为变更;沙箱车道上不再等同 `default`) · 审批列表面同族、`approvalId` = 行的键、已决卡再应答回放首决(BREAKING,wire 值变更) · 委派子代会话的属主随委派树写入、无主的委派子代行不对具名主体放行、SQL 后端存量子代行每次起服回填(安全) · 嵌入方 `ServiceKnobDeps.snapshotBlobSqlCap` 读口退役(BREAKING;零别名;要固定帽设 `SNAPSHOT_BLOB_SQL_MAX_BYTES`) · 子代转录读法 = 同一会话读面 + 终态帧 `transcriptId`、会话视图体顶层加性键 `agent`(消费方读法) · 没声明 `REMOTE_EXEC_HOME_DIR` 的 k8s / local-docker / ssh / adb 车道自己实测执行环境的家目录(行为变更;声明仍胜;起服 warn `execution_lane_home_undeclared` 只留给 device) · SQL 后端 workflow 续跑日志的属主 scope 搬进新表 `workflow_journal_owner`、`workflow_journal` 起服一次性按新主键重建(持久数据;🔴 先停旧副本再起新;收编回执腿名随表改) · workflow 子代的审批决定落盘:宿主会话的每一跑都带着它、同一决定重投回同一张回执(行为变更;SQL 后端起服多建一张表、整队一次切;SQL 后端配 `WORKFLOW_RUN_STORE=file|memory` 且开自编排起服拒) · 审批账本有了保留窗:结了且挂靠的东西都已终局的问安静超过 30 天就整问删掉(行为变更;要永久保留设 `APPROVAL_ASK_RETENTION_MS=0`,且要在升级后的第一次清扫之前) · 多租部署上请求 `settings.permissions.allow` 与按名点用的自带技能 `allowedTools` 按调用方信任档受理(安全,行为变更;低角色 / 不带角色的登录令牌带非空的 ⇒ `400`,能力位 `settings.permissions.callerTrust`) · 本地配置源 `config.d` 读之前判目录信任:别人改得动就拒启(安全;升级前自查权限;新旋钮 `CONFIG_LOCAL_OWNER_UID`) · 单用户记忆项目层换键形 `userrepo:<属主>/<档>.<摘要>`(带主体、跨设备;开记忆同步的部署项目层也同步;先升中心;存量项目层第一次在该项目跑任务时自动折进新键) · SQL 后端断路器键换成路由身份摘要、写新表 `breaker_state`,退役表 `circuit_breaker` 起服删掉(持久数据;无需动手) · `settings.hooks` 的 `source` / `plugin` / `args` 被读(不带且不引用插件变量零动作;托管组独立车道、跑不成即折 ask;exec 形不再被剥参数;引用不在场的插件变量的命令起不来) · 名单为空的单用户部署:审批队列不再把每个调用方当运维,要当自己的运维写一行 `OPERATOR_SINGLE_USER=true`(行为变更) · 隔离型车道(e2b / k8s / local-docker)的读面缺省 `READ_FACE` 缺席时从 `roots` 变 `open`(行为变更;把宿主目录或共享卷挂进沙箱的部署升级前写 `READ_FACE=roots`) · center 的 `allowBypassPermissions` / `allowAutoMode` 两键开始生效:组织关掉的模式由引擎折回 `default`(安全;行为变更) · 模式缺席的请求也问 `Workflow`(行为变更;要清掉这一问用 `settings.permissions.allow:["Workflow"]`) · 中心凭证换人:server 自己降到「无中心配置」档、当场拉取,`/health` 多一键 `centerIdentityNotice`(行为变更;没有 env 模型的部署在换人窗口里没有可派发模型) · 嵌入方:`StoreBackend.orgDeliveryQuota()` / `StoreBackend.checkpointReadView()` 必选(BREAKING,类型面;`orgDeliveryQuota()` 的返回型从包根导出,读口按 `StoreBackend` 成员型读) · SQL 后端收件箱里身份键过不了判官的存量行起服删掉(持久数据;无需动手)
 
 1. **`SANDBOX_PKG_SOURCE=custom` 的六只显式地址不得带 userinfo,带的起服拒**(安全):`SEMA_APT_MIRROR` / `SEMA_PIP_INDEX` / `SEMA_UV_INDEX` / `SEMA_UV_PY_MIRROR` /

package/README.md

@@ -106,7 +106,7 @@ MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-v4-flash \
   MODEL_API_KEY=<your-key> SERVICE_AUTH_TOKEN=<pick-one> \
   node node_modules/@sema-agent/server/dist/main.js        # → :8090
 
-# B) container (zero local deps, anonymous pull; ⚠ image publishing is paused — see "Image publishing paused" below)
+# B) container (zero local deps; ⚠ images are no longer published — build your own, see "Image publishing discontinued" below and USAGE 9.13)
 docker run -p 8090:8090 \
   -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-v4-flash \
   -e MODEL_API_KEY=<your-key> -e SERVICE_AUTH_TOKEN=<pick-one> \
@@ -127,7 +127,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 - **Distribution coordinates**: npm = [`@sema-agent/server`](https://www.npmjs.com/package/@sema-agent/server)
   (public on npmjs) · images = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
   (both public; `:latest` rolling, `:<sha>` pinned).
-- **Image publishing paused**: Container images have been paused since 7.128.0; the npm package is the only release artifact; resumption will be announced separately.
+- **Image publishing discontinued**: Container images are no longer published since 7.128.0; the npm package is the only release artifact; self-build steps are in USAGE 9.13.
 - **Library embedding** (package root, e.g. `createHttpServer` + your own `StoreBackend`): after
   `loadConfig()`, call `composeExecutionLane(config, ctx)` — the HTTP service and `run-local` both do. Since
   7.104.0 the execution-lane start refusals (`LEADER_ENABLED` on the host lane, a multi-tenant posture on a

package/README.zh-CN.md

@@ -95,7 +95,7 @@ MODEL_GATEWAY_BASEURL=https://api.deepseek.com MODEL_ID=deepseek-v4-flash \
   MODEL_API_KEY=<你的-key> SERVICE_AUTH_TOKEN=<自定> \
   node node_modules/@sema-agent/server/dist/main.js        # → :8090
 
-# B) 容器(零依赖,匿名可拉;⚠️ 镜像已暂停发布,见下方「镜像暂停发布」)
+# B) 容器(零依赖;⚠️ 镜像不再发布,自建见下方「镜像不再发布」与 USAGE 9.13)
 docker run -p 8090:8090 \
   -e MODEL_GATEWAY_BASEURL=https://api.deepseek.com -e MODEL_ID=deepseek-v4-flash \
   -e MODEL_API_KEY=<你的-key> -e SERVICE_AUTH_TOKEN=<自定> \
@@ -110,7 +110,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 - **分发坐标**:npm = [`@sema-agent/server`](https://www.npmjs.com/package/@sema-agent/server)
   (npmjs 公开)· 镜像 = `ghcr.io/sema-agent/sema-server` + `docker.io/claybobby/sema-server`
   (均 public,`:latest` 滚动 / `:<sha>` 钉版)。
-- **镜像暂停发布**:容器镜像自 7.128.0 起暂停发布,npm 包是唯一发布件;恢复另行通告。
+- **镜像不再发布**:容器镜像自 7.128.0 起不再发布,npm 包是唯一发布件;自建镜像步骤见 USAGE 9.13。
 - **作为库嵌入**(包根导出,如 `createHttpServer` + 自建 `StoreBackend`):`loadConfig()` 之后调
   `composeExecutionLane(config, ctx)` —— HTTP 服务与 `run-local` 都这么做。7.104.0 起执行车道的几条拒启(host 车道上开
   `LEADER_ENABLED`、多租户姿态落在共享车道、device 车道缺耐久店)判在这一步,不在 `loadConfig()` 里;