@sema-agent/server 7.135.0 → 7.137.0

package/MIGRATION.md

@@ -7,6 +7,241 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.137.0 —— 对 web-admin 中心的请求不再跟随重定向(安全收紧;行为面;反代会回 3xx 的部署升级前把两席写成最终地址) · k8s 车道 `K8S_SANDBOX_ENV` 的值改经每只 pod 自己的 Secret(部署面 BREAKING;沙箱 Role 要 secrets 的 `create`,名单非空而 Role 不许 ⇒ 起服拒;共用沙箱命名空间的两套部署升级前各给一个命名空间) · SQL 后端 `task_run` 表加三列 `identity_source` / `identity_scope` / `identity_principal_inc`(🔴 升级前先 `ALTER TABLE` 加列;持久数据,不能删表重建;嵌入方 `RunRecord` 多必填键 `identity`〔BREAKING,类型面〕) · 请求键 `promptProfile` 退役、换成布尔 `promptLean`(BREAKING,wire;零别名;升级前停驻的任务存体起服原地改写〔一次性迁移 M30,窗 30 天〕,没改写到的续跑 409) · 模型目录条目带 `promptGuidance` 的不服务、fable 系模型 id 不再带 fable 提示段(行为变更) · 带图预检的计量 `images_omitted_total` 与日志行 `images_omitted_no_vision_model` 退役(运维面;行为变更;看板 / 告警改读会话流的 `model.capability_downgraded`) · 引擎 7.56.0 的部署序:先升全部读者、回滚前先决完停驻行(三处:停驻审批行 `mount_site`、技能座 `skill_scopes`、会话规则文法 5) · 规则名里的 `*`:限制侧整名 glob、授予侧一条孤 `*` 不再让整张放行表作废(行为变更;升级前先审放行表) · 规则名外缘的空白被拒(行为变更;人敲的规则编辑文本修剪后再提交) · 嵌入方 hook / mod 的 handler 答案按数据收、非普通记录一律拒(行为变更,fail-closed) · 不是名字的主体在鉴权边界被拒:`400 principal_not_a_name`(行为变更;反代把 UTF-8 用户名原样塞进主体头的部署升级前核) · 计划审阅的决断体可带 `checkpointId`:门换了 ⇒ `409 approval_stale`、不落决断(wire additive;决断方先读能力位 `planReviewCheckpointId` 再带键) · `delegation.ask_unresolvable` 通告的 `detail` 多可选键 `remedies`(wire 加性;宿主按 `kind` 渲染出路,闭集外的 `kind` 忽略) · 引擎 7.56.0 的五个新键本版刻意不投(`requestedBy`、`answeredBy`、`hostFloor`;登记披露,无消费方动作) · 本版其余 wire 面变化的消费方动作逐面表态(多数零动作;设备执行器的修订 3、`attachments.mcpUnavailable`、`resultEntryIds` 各有一句真动作) · 7.136.x 停下、技能请求项带 `mods` 的任务续跑失败(行为变更;新提交早已 400) · 订正 7.136.0 节第 4 条:没有返回任务目标全文的读口(`GET /v1/runs/:id` 不带目标)
+
+1. **对 web-admin 中心的请求不再跟随重定向(安全收紧;行为面)**:此前只有令牌续签不跟重定向,其余对中心的请求(拉配置、principal 视图、skill 正文、prompt 产物、配额租约、
+   fleet 公告 / 用量 / 注销、服务租约、执行公钥上报)被传输层静默跟随 —— POST 307 / 308 把请求体带去 `Location`,同 origin 的跟随连 `Authorization` 一起带走。本版起每条都不跟:
+   中心回重定向(任何 3xx,304 除外)⇒ 该条请求被拒,拒句 `web-admin center request: endpoint answered with a redirect (HTTP <n>); it was not followed and no credential was sent anywhere else — …`
+   点名这条请求打的那一席。**只伤一类部署**:`SEMA_WEB_ADMIN_URL`(或 `SEMA_WEB_ADMIN_LIVE_URL`)指的不是中心的最终地址,而是会 301 / 302 / 307 / 308 的反代(`http` → `https` 跳转、主机名规范化、尾斜杠重定向)。
+   **升级前做**:二选一 —— 让反代直接回答,或把这两席写成最终地址;用文件形用户会话凭证(`SEMA_WEB_ADMIN_TOKEN_FILE` 里的信封)的部署,还要用新地址重新登录一次,使信封里的 `issuer` 也是最终地址
+   (续签遇重定向落终态「被拒」:`center_credential_renew_failed`,`reason: "rejected"`,直到凭证文件变化)。**升级后看**:起服那一行 `config_source_unreachable_using_env`(起服拉配置撞上重定向时拒句落在这一行,多数部署第一眼看到的是它)
+   与 `web_admin_refresh_failed` / `fleet_announce_failed` / `fleet_usage_report_failed`、鉴权桥的 `auth_bridge_jwks_fetch_failed` 这几条 warn 的错误字段里是否出现
+   `answered with a redirect`;出现 = 还有一席没写成最终地址(JWKS 那一行点名 `AUTH_BRIDGE_JWKS_URL` 或它派生自的签发方地址)。其余部署零动作。
+
+2. **k8s 车道:`K8S_SANDBOX_ENV` 的值改经每只 pod 自己的 Secret ⇒ 沙箱 Role 要 secrets 的 `create`(部署面 BREAKING;名单非空而 Role 不许 ⇒ 起服拒)**:本版起名单点到的值不再写进 pod spec,
+   只进该 pod 的一只 Secret(pod 的容器 env 带 `secretKeyRef`;Secret 属于 pod,随 pod 由集群回收)。**升级前做**:设了 `K8S_SANDBOX_ENV` 的部署,给服务账号在沙箱命名空间的 Role 加一条
+   `- apiGroups: [""] resources: [secrets] verbs: [create]`(随包 `deploy/sema-up/chart/templates/sandbox-rbac.yaml` 与 `deploy/sema-up/stack/sema-stack-cluster.yaml` 已带)。
+   动词恰是服务为这只 Secret 真发的调用:`create`(建每只 pod 的 Secret,之后不再碰);**不要**给 `get`(服务从不读回 Secret,给了就让服务账号读得到沙箱命名空间里的每一只 Secret)
+   与 `delete`(Secret 属于它的 pod,由集群的垃圾回收随 pod 删,不经服务账号)。
+   缺了 ⇒ 起服拒,拒句带 `[sandbox-secret-rbac]`、点名缺的动词;起服问不到(API 连不上 / 服务账号建不了 SelfSubjectAccessReview)⇒ 照起,但第一个转发的 run 连接即拒(`auth_failed`)、它的 pod 被删 —— 值不会回落进 pod spec。
+   没设 `K8S_SANDBOX_ENV`(或点到的键在服务进程环境里都没有值)的部署零动作。建议同时给集群开 Secret 静态加密(值现在在 etcd 的 Secret 里)。
+   成员 git 凭据代理的租约 Secret 另要 `patch`(改写租约用 merge-patch;**不需要** `update`)—— 本版该平面恒关、没有代理会被挂上,起服门也不问它,**现在不用给**;
+   平面打开的那一版再加(那时平面判官问的是 `create` / `patch`,不许 ⇒ 平面熄、读数 `secret_seat_denied`)。
+   另一条行为变更不需要动手:服务会删已结束的沙箱 pod(容器全部结束,或它的 run 已终且过了 `max(6 分钟, WORKSPACE_SNAPSHOT_TIMEOUT_MS + 15 秒)`)—— 事后 `kubectl logs` 看不到了,要留现场在 run 结束前取。
+   这里的 `WORKSPACE_SNAPSHOT_TIMEOUT_MS` 是**建这只 pod 的副本**的值:建 pod 时算一次、写进 pod 注解 `sema.io/run-end-hold-ms`,回收器只读这一格、不读自己副本的配置 ——
+   滚动升级或改 `WORKSPACE_SNAPSHOT_TIMEOUT_MS` 时每只 pod 按建它的副本的时限,时限短的副本不会提前删时限长的副本还在存快照的 pod;不带这条注解的 pod(本版之前建的)不按 run 终态删,容器结束后照删。
+   给沙箱命名空间配了限制 pod 注解的准入策略的部署,升级前放行注解键 `sema.io/run-end-hold-ms`(否则建 pod 被拒)。
+   **两套部署共用一个沙箱命名空间**(缺省都是 `sandboxes`)时,回收器按身份标签列 pod、标签里没有部署身份 ⇒ 一套部署会删另一套**容器已结束**的 pod:
+   升级前用 `K8S_NAMESPACE` 给每套部署各一个沙箱命名空间(本版没有关掉回收器的旋钮)。
+
+3. **SQL 后端:`task_run` 表加三列 `identity_source` / `identity_scope` / `identity_principal_inc`(🔴 升级前先加列;持久数据,不能删表重建;嵌入方 BREAKING,类型面)**:
+   本服务受理一条 run 时,把这次请求在凭据门上验过的身份来源(`service_token` / `sso` / `direct_door_jwt`)连同登录令牌的 scope 写进 run 行(化身号一列先恒空,
+   契约包给出那一位之后才有值),之后只读 —— 续跑、挂起、终局、重启都不改。本服务不发 `ALTER`:存量库缺这三列 ⇒ 起服列册对账拒启(`config.schema_mismatch`),拒句带可直接粘贴执行的语句。
+   **升级前做**(MySQL 协议,三句):
+   `ALTER TABLE task_run ADD COLUMN identity_source VARCHAR(32) NULL;`
+   `ALTER TABLE task_run ADD COLUMN identity_scope VARCHAR(190) NULL;`
+   `ALTER TABLE task_run ADD COLUMN identity_principal_inc VARCHAR(64) NULL;`
+   (PostgreSQL,三句)
+   `ALTER TABLE task_run ADD COLUMN identity_source VARCHAR(32) COLLATE "C";`
+   `ALTER TABLE task_run ADD COLUMN identity_scope VARCHAR(190) COLLATE "C";`
+   `ALTER TABLE task_run ADD COLUMN identity_principal_inc VARCHAR(64) COLLATE "C";`
+   存量行三列是 NULL,不回填(没有事实可回填):读法是「这一行没有属主在受理时验过的凭据的记录」,与无鉴权写面(`ALLOW_UNAUTHED_WRITES`)受理的 run、
+   别人替属主按下唤醒 / 决定投递铸的新一跑同读,一律不合格。行上的 `source` 列(系统名,登录令牌直连写 `sso`)只作归因,不被读成认证来源。
+   **顺序**:先升库(加列)、再升副本 —— 加完列之后,仍是 7.136.x 的副本**再启动**会把三列看成幽灵列而拒启(只挡重启;已在跑的旧副本建行时带列名清单、不写这三列,
+   它们受理的 run 三列为 NULL,同上读法)。**不要**删表重建 `task_run`:表里是 run 账本(在飞 / 停驻的 run 与提交幂等键)。`DB_BACKEND=local` 与内存后端零动作
+   (文件后端的 `run.json` 多三键,升级前写下的文件读成 NULL)。
+   **回滚到 7.136.x:只回退二进制不可行**(MySQL 协议与 PG 皆然)—— 加过列的库上,7.136.x 的起服列册对账把多出的三列读成幽灵列、起服拒(拒句点名 `UNKNOWN column(s) identity_source, identity_scope, identity_principal_inc`、不给 ALTER)。
+   回滚 = ① 先停光全部本版副本;② 手工 `ALTER TABLE task_run DROP COLUMN identity_source;`、`ALTER TABLE task_run DROP COLUMN identity_scope;`、`ALTER TABLE task_run DROP COLUMN identity_principal_inc;`(两方言同三句);③ 再起 7.136.x。
+   DROP 只丢本版受理的 run 的身份记录:再升回本版、照上面加列之后,这些行读成 NULL(不合格),run 的其余读写不受影响。
+   **嵌入方(类型面,BREAKING)**:包根导出的 `RunRecord` 多一个必填键 `identity` —— 三形之一:`{ source: "sso", scope, principalInc }`(`principalInc` 可为 `null`)、
+   `{ source: "service_token" 或 "direct_door_jwt", scope: null, principalInc: null }`、`null`。只读它的代码零动作;手写的 `RunRecord` 字面量(测试夹具、自造的 run 读者)tsc 红 —— 补 `identity: null`。
+
+4. **请求键 `promptProfile` 退役,换成布尔 `promptLean`(BREAKING,wire;零别名;引擎 7.56.0)**:新提交三腿(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)上带 `promptProfile` ⇒
+   `400 request.body_shape`(`unknownKeys` 点名它)。**调用方改法**:`promptProfile: "classic"` ⇒ `promptLean: false`;`promptProfile: "simple"` ⇒ 不带键(或 `promptLean: true`)。
+   `promptLean` 不是布尔 ⇒ `400 request.field_invalid`。
+   **停驻中的任务**:7.136.x 及以前停驻、请求体里带 `promptProfile` 的任务,本版**起服时**把存下的请求体原地改写(同一张映射:`"classic"` ⇒ `promptLean: false`,长形照旧;
+   `"simple"` / 词表外 ⇒ 删键,缺省形;体里已有布尔 `promptLean` ⇒ 它说了算、只删旧键;续跑时钟不动),起服一行运维日志 `checkpoint_ctx_prompt_profile_rewritten`(扫了几行、改了几行,不带值)。
+   这是**一次性迁移,窗 = 本版发布日起 30 天**,窗内每次起服都扫;改写过的任务此后续跑几次、窗关之后再续跑,形都不变 —— 零动作。
+   **升级序(与第 7 条同向,且更严)**:**先停光 7.136.x 副本,再起第一个本版副本**(它起服即改写)。改写过的体 7.136.x 读不懂 —— 它只认 `promptProfile`,读到改写后的体回到缺省形
+   (`"classic"` 的长形静默丢),所以本版副本起过服之后,不能再有 7.136.x 副本续跑这些任务;反过来,本版起服之后才由 7.136.x 副本停下的任务存体里仍是旧键。
+   **升级前先缩光副本,按安装路径分三种**(滚动更新做不到「先停光 7.136.x、再起第一个本版副本」;下面三段各管一种安装路径,照你的那一种做):
+   **Helm 形安装**(`kube-up.sh` 的 `--kube=existing` / `--kube=k3s`;`--kube=machines` 下设了 `STACK_ENGINE=helm`):图表只在钥匙卷是 `ReadWriteOnce` 时给 Deployment 写 `Recreate`;缺省的多副本(`server.replicas: 3`、`ReadWriteMany`)不写更新策略,`helm upgrade` 走 Kubernetes 缺省的滚动更新 —— 第一只本版 pod 起服改写存体时 7.136.x 副本还在跑。所以升级前先 `kubectl -n <命名空间> scale deploy/sema-server --replicas=0`(启用 `serverV4pro` 时同样缩 `deploy/sema-server-v4pro`),等旧 pod 退光,再 `helm upgrade`(重跑 `sema-up` / `kube-up.sh` 在这些安装形上走的就是这条),升完核副本数回到 `server.replicas`。
+   **`--kube=machines` 缺省形**(不设 `STACK_ENGINE` = `render`;`cluster-up.sh` 渲染清单后 `kubectl apply`,不是 Helm):清单里 `sema-server` 的副本数按机器数取 2(少于 3 台)或 3(3 台及以上),没有 `strategy` 键 = Kubernetes 缺省的滚动更新,也没有 `serverV4pro`。所以升级前先 `kubectl -n sema scale deploy/sema-server --replicas=0`(第一台机器上写 `k3s kubectl`),等旧 pod 退光,再 `kubectl apply`(重跑 `sema-up` 做的就是这一步;清单里的 `replicas` 把副本数写回 2 或 3),升完核副本数。
+   **compose 两档**(`--profile=full-single` / `local-plus`):`server` 服务只有一只容器、没有副本数键 —— 没有第二只旧副本在滚动更新里陪跑,零动作。
+   **没改写到的**任务(窗内从没起过本版的部署;违反上面的升级序、在本版副本起服之后由 7.136.x 副本停下的任务)续跑答 `409 checkpoint.unsupported_version`(`retriable: true`,卡仍待决;
+   句子点名 `promptProfile`,不回显值),不按旧键读、也不静默丢键:窗内在最后一只 7.136.x 副本停下之后重启一只本版副本,它起服即改写这些任务(重启用的配置里须 `DURABLE_APPROVAL=true` —— 多租户部署缺省关,要显式写,且多租户还需 `OPERATOR_PRINCIPALS` 非空,否则起服拒(拒句点名出路);起服日志里 `checkpoint_ctx_prompt_profile_rewritten`(M30)与 `checkpoint_ctx_credentials_sealed`(M28)两行都出现、且 M30 那一行是 `"window":"open"`,才说明守卫过了、改写跑过 —— M28 的窗先关,窗关后它那一行 `"window":"closed"` 属正常);
+   窗关之后仍带旧键的任务只能取消后作为新任务重提(`promptLean` 代替 `promptProfile`)。跳过本版、直接升到更晚版本的部署,先在本版上起一次服。
+   **库形嵌入方**(包根的 `createHttpServer` + 自建 `StoreBackend`,不经 `@sema-agent/server/main` 这个服务进程入口):本条的起服改写(M30;`checkpoint` 存体里请求凭据的封签 M28 同形同处)只在服务进程的起服第 6 段(`src/boot/stage-06-runners.ts`)里跑 ——
+   包根没有导出它,公开的迁移序列(`createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`)也不含它(它要等 checkpoint 店建成之后才能跑)。所以库形嵌入方自己的装配不会改写存体:7.136.x 停驻、体里带 `promptProfile` 的任务续跑一律答 `409 checkpoint.unsupported_version`,
+   上面「窗内重启一只本版副本即改写」的出路对它不成立。窗内的出路:用本包的服务进程入口(`import "@sema-agent/server/main"` 或 `node dist/main.js`,指向同一份库 / 数据根)起一次服 —— 那一次起服即改写,但有两个前提并列,缺哪个都不行:① `DURABLE_APPROVAL=true`(多租户部署缺省关,要显式写,且多租户还需 `OPERATOR_PRINCIPALS` 非空,否则这一次起服拒(拒句点名出路:设 `OPERATOR_PRINCIPALS`,或单租户部署去掉 `REQUIRE_PRINCIPAL`);两只迁移只在 checkpoint 店存在时跑,店只在这个开关为真时建,开关为假 ⇒ 这一次起服静默不跑它们;这道守卫早于本版,本版只补了这句说明);② 只对 M28 的窗内(UTC 日历日,含 2026-11-20 当天)有意义:服务进程入口读到的保管目录里要有嵌入方封签用的那对钥匙 —— 做法是 `SEALED_KEY_DIR` 指向嵌入方自己 `ensureCheckpointCtxSealing(sealedKeyDir)` 用的那个目录(服务进程入口缺省读 `<数据根>/sealed-key`;读到的目录里没有可用的钥匙文件 ⇒ 服务进程新建一对钥匙去封剩余的明文行,嵌入方不持有这对钥匙,这些行的续跑答 `409 conflict.checkpoint_ctx_unsealable` `reason:"key_not_held"`,嵌入方要先持有那对钥匙〔保管目录只在起服时读〕才读得开,否则取消后作为新任务重提)。两只迁移的窗不同:M28(封签剩余明文凭据行)的窗到 2026-11-20,M30(改写 `promptProfile`)的窗到 2026-11-24 —— 2026-11-21 至 2026-11-24 之间的那一次起服只改写 `promptProfile`、不再封签明文凭据行(前提 ② 在那几天不相干;仍是明文的行续跑答 `409 conflict.checkpoint_ctx_unsealable` `reason:"plaintext"`,取消后作为新任务重提),两行日志名都会出现(M28 那一行是 `"window":"closed"`、`rowsScanned` 为 0)。起服后核日志行 `checkpoint_ctx_credentials_sealed`(M28)与 `checkpoint_ctx_prompt_profile_rewritten`(M30)都出现 —— 没出现 = 守卫挡了、迁移没跑;出现了还要看字段,不只看行名:`"window":"open"` 且 `rowsScanned` 是你预期的行数,才说明那一只迁移真扫过(`"window":"closed"` ⇒ 一行没读)。M30 的窗关之后(2026-11-24 之后)与其余部署同,取消后作为新任务重提。
+   **回滚到 7.136.x**:被改写过的停驻任务在 7.136.x 上续跑回到缺省形(长形丢,零通告)—— 回滚前先决完或取消停驻的任务(与第 7 条「回滚前先决完停驻行」同一个动作)。
+
+5. **模型目录条目带 `promptGuidance` 的不服务;fable 系模型 id 的 fable 提示段(行为变更;引擎 7.56.0)**:目录条目(中心配置 / `config.d` / 部署 env 条目)写了非空 `promptGuidance` ⇒
+    那一条不服务(与别的坏条目同一个拒因 `config.model_entry_invalid`,`fields: ["promptGuidance"]`,起服 / 刷新时运维日志点名)。**做法**:删掉条目里的 `promptGuidance`;引导句的去处是
+    模型声明的提示特征 `promptTraits` —— 契约包的模型条目还没有这个座,在它到之前本服务不透传。经本服务目录跑 fable 系模型 id 的部署:引擎不再按模型 id 认 fable 系,
+    这些 run 本版起不带 fable 提示段、取模型缺省的短形;要那几段的部署在契约包加座之前留在 7.136.x。
+
+6. **带图预检的计量与日志行退役(运维面;行为变更)**:计量 `images_omitted_total{model}` 与运维日志行 `images_omitted_no_vision_model` 本版起不再出现 —— 带图请求遇不收图的模型,
+    由引擎在真替换图片的那一刻在会话流 / 账本里发 `engine_notice` `model.capability_downgraded`(`detail: { model, capability: "image", status, sessionId, runId }`)。
+    **做法**:引用这两者的看板 / 告警改读那条通告(按 `code` 计数);不改的看板会静默少一条线。
+
+7. **引擎 7.56.0 的部署序:先升全部读者,回滚前先决完停驻行(三处)**:
+    - **停驻审批行的 `mount_site`**:本版停下的、引擎挂载的工具(每一只内置工具,问答工具在内)的审批行多一个成员与一个要求词;7.136.x 及以前的副本读到它在认领之前拒
+      (`checkpoint.unsupported_version`,`version_newer`,行留 pending)。⇒ 多副本滚动升级:先把会续跑的每只副本都升到本版,再放新的停驻;**回滚到 7.136.x 之前**先把本版停下的审批决完或取消。
+    - **技能座的 `skill_scopes`**:引擎给「带 hooks 的技能在场时停下的 run」写这个要求词;本服务不编技能 hooks(能力位 `mods.skill_seat` 恒 false、请求面拒 `skills[].mods`),
+      本服务写下的停驻行不会带它 ⇒ 零动作。
+    - **会话规则文法 5**:本版的写口给会话规则行盖文法 5 的戳,7.136.x 及以前的副本读不了这种行(那条会话的每一跑开跑即失败,见下面「回滚」);持久规则桶同理(SQL 后端 `permission_rule` 的 `grammar` 列:
+      本版写过的桶旧副本整桶拒)。⇒ 先把读同一只会话规则店 / 规则桶的每只副本都升到本版,再放会话规则与「始终允许」的写;
+      **回滚**:本版写下的行旧版读不了,旧版的写口也改不了它(写前读那一行即拒)。实测(同一 local 数据根,本版写过会话规则 —— 连只写一条 `Write` 也盖文法 5 —— 再起 7.136.0):
+      这些会话的**每一跑开跑即 `failed`**、终局码 `corrupt`(一次工具调用都没有),`GET /v1/sessions/:id/policy` 答 `500 corrupt`;没写过会话规则的会话照常。
+      回滚后这些会话的出路只有删会话(或再升回本版)。
+      **不要**在库里把戳改小:同一条 `toolDeny` 的 `*` 在文法 4 里什么也不拒(改戳 = 静默放宽)。
+
+8. **规则名里的 `*`:限制侧是整名 glob、授予侧的孤 `*` 不再让整张放行表作废(行为变更;引擎 7.56.0)**:
+    - **限制侧**(请求 `settings.permissions.deny` / `ask`、运维 `APPROVAL_REQUIRE` / `APPROVAL_DENY` / `APPROVAL_NEVER_AUTO` 与中心下发的同名表、`excludeTools`、会话规则 `toolDeny`、技能 `disallowedTools` / 子代 `denyTools`):
+      名字里的 `*` 读成整名 glob,孤 `*` = 每一只工具。7.136.x 上这些写法在受理口一律被拒,所以没有存量部署受伤;**变的是调用方的读法**:此前
+      `deny:["*"]` ⇒ 422 `invalid.tool_name`、`excludeTools:["*"]` ⇒ 400 `config.tool_face_control`、技能 `disallowedTools:["*"]` ⇒ 400 `request.field_invalid`、子代 `denyTools:["*"]` ⇒ 400 `config.agent.unknown_tool` 这几条拒不再出现 ——
+      它们现在 200 / 受理,而且**真的**全拒 / 全问(`deny:["*"]` 的 run 里每一只工具都被拒)。拿那几条 4xx 当信号的调用方:改按 200 与实际策略读。
+    - **授予侧**(请求 `settings.permissions.allow`、技能 `allowedTools`、运维放行席):一条孤 `*` 什么也不授(照旧被通告,`wildcard_all`),但**同表别的条目照常放行** ——
+      此前整张表读空、一条也不放。**升级前做**:靠授予侧一条 `*` 把整张放行表作废的,把表里不该放行的条目删掉(放宽方向,先审已有的表)。
+    **回滚到 7.136.x**:限制侧受理过的 `*` 条目(尤其会话规则行,见第 7 条)旧版读不了或读成什么也不拒 —— 回滚前先清掉本版写下的这类条目。
+
+9. **规则名外缘的空白从 7.137.0 起被拒:卡上人敲的规则编辑文本带前导 / 尾随空白或工具名后空格 ⇒ 裁决之前 `400`(行为变更;引擎 7.56.0;消费者动作 = 去掉空白)**:
+    `persistRule: { rule, edited: true }` 的文本,**前导空白**(含制表符)、**尾随空白**、**工具名与 `(` 之间的空格**(`" Bash(adb *)"`、`"Bash(adb *) "`、`"Bash (adb *)"`)不再被收下 ——
+    裁决之前 `400 request.body_shape`,体带 `ruleRejectCode: "invalid.grammar"`,`error` 句点名去掉空白后的写法(`Bash(adb *)`);这只 ask 未结算、卡还在、店里零落地。7.136.x 上**前导空白**与**工具名后空格**的文本被收下并落成一行规则(尾随空白那时就已拒,不是本版新拒)。
+    **做法**:界面 / 壳把人敲的文本**修剪后再提交**(引擎的解析器不修剪,修剪是编辑器表面的事);文本**内部**的多余空白不在本条之内(`Bash(adb  *)` 仍落 `Bash(adb:*)`)。无存量数据要迁移。
+
+10. **嵌入方:hook / mod 的 handler 答案按数据收,非普通记录的答案一律拒(行为变更,fail-closed;引擎 7.56.0「答案是数据」)**:handler(`PreToolUse` 钩子答案、`prompt.compose` 的 overlay 答案等)返回的值只收原始值或普通记录 / 数组(整只拷贝并冻结);
+    **类实例、`Map`、函数、symbol、bigint、环、原型上带契约成员的对象、不可枚举成员的载体**是站点违约 —— 该次判决被拒(`PreToolUse` 上读数 `ran=0 denied=1`),此前原型载体与类实例被照常接受。
+    本服务自己铸的 handler 答案逐点核过:答案铸点(带 `action` / `block` / `additionalContext` / `overlays` 键的对象字面量)共 20 处 —— `settings.hooks` 注册 19 处、部署座品牌行 1 处 —— 全是普通对象字面量:`settings.hooks` 的成员只有闭集词串(`action`)、截断后的文本串与钩子 stdout 经 `JSON.parse` 得到的 `updatedInput`;
+    品牌行的成员是引擎交回的上一手答案原样接上本服务的一条 overlay 常量;部署座的拒绝计量与工具追踪两只观察者、`StopFailure` / `PostCompact` 的翻译恒答 `undefined`。
+    服务部署零动作;只有**自己往引擎里挂 handler 的嵌入方**要核:把答案改成普通对象字面量。
+
+11. **不是名字的主体在鉴权边界被拒:`400 principal_not_a_name`(行为变更;引擎 7.56.0 的主体名判官)**:主体头(去掉首尾空白之后)、SSO 令牌的 sub、直连门 JWT 的 sub
+    带控制、行段分隔或不可见格式字符(引擎 `principalNameOf` 的判据),或 sub 只有空白 ⇒ 本版起 400 带码,7.136.x 收下;空的 / 只有空白的主体头照旧读作「没有主体」。
+    **最常见的来源**:反代把 UTF-8 用户名原样塞进主体头 —— 本服务按 latin1 一字节一字符读头,UTF-8 字节里的 0x80–0x9F 读成 C1 控制字符、0xAD 读成软连字符(格式字符),
+    于是「张三」(E4 B8 **89**)、`Martín`(C3 **AD**)都被读成「不是名字」的乱码。
+    **怎么核**:升级前在反代上看主体头的字节 —— 有 0x80–0x9F 或 0xAD 的字节 ⇒ 本版起被拒,必须改;其余非 ASCII 字节照收(但同一个人在签名令牌的门上解出的是 UTF-8 原文、
+    在主体头上是 latin1 乱码,两个串,建议一并改);或在 7.136.x 的会话列表 / 审批队列里找属主带乱码的行。升级后看 `400 principal_not_a_name` 的计数。
+    **怎么改**:反代把主体头编成 ASCII 或其它不含控制字符的规范形(用户 id、百分号编码等)再发 —— 同一个人在每条门上要是同一个串。
+    **存量行**:7.136.x 按乱码串记下属主的会话、停驻审批、规则桶,本版上没有主体够得着(那串不再是谁的名字)。本版**没有通用的迁移口**,如实说清能做到哪一步:
+    SQL 后端的多租部署,运维可以试收编口 `POST /v1/adoption`(operator 面)把一位用户的行迁到新名字下 —— `fromPrincipal` 写 7.136.x **真存下的**那一串:
+    用户名的 UTF-8 字节按 latin1 逐字节读出、再去掉首尾空白(边界读头时剥过;0xA0 在 latin1 是 NBSP,串尾的会被剥掉),JSON 里用 `\u00XX` 转义写;
+    `toPrincipal` 写改编码之后的新串(收编口不判它是不是一位主体的名字,由运维保证;同一个 `fromPrincipal` 只能收编一次)。**限制**:收编口要求旧串编码成记忆作用域段后
+    不超过 64 个字符(非 ASCII 每个字节约占 6 个字符)⇒ 大约三个汉字以内的名字迁得动,更长的会被拒(`400 request.field_invalid`)。迁不动的、以及文件后端
+    (`DB_BACKEND=local`,没有收编口)上的旧行,留在旧串名下:只能回滚到 7.136.x 继续用,或删掉。`MEMORY_ORG_DIRECTORY_JSON` 的主体键同判:有这类键 ⇒ 起服拒
+    (拒句按键在 JSON 文本里的出现序点名:`principal key #N (in text order)`),改成新串。
+    **回滚到 7.136.x**:同一份乱码串照旧被收下,存量行照旧够得着;本版下以新串写下的行归新串。
+
+12. **计划审阅的决断体可带 `checkpointId`(决断方看到的那道门):门换了 ⇒ `409 approval_stale`、不落决断(wire additive;服务部署零动作,消费方动作见下)**:
+    `POST /v1/assistant/tasks/:id/plan_review` 认可选键 `checkpointId`;带了而它不是该会话此刻待决的那道 plan 门 ⇒ `409 approval_stale`(与 `/decide` 同码同句),计划未批、卡仍待决,
+    体带当前门 `currentPending: { checkpointId }`(当前门没有可信身份 / 恰被并发消费时缺席);不带键照旧受理。
+    陈旧判过了之后、认领之前门再换(窄窗)⇒ `409 conflict.not_resumable`(认领输家那一码,决断同样不落;直连门上这一份证明的 nonce 已用掉,重签再决)。
+    · **决断方(client-core `decidePlanReview` 等)**:透传人看到的那道门的 `checkpointId` —— 取 park 结果的 `terminal.checkpointId`(`GET /v1/runs/:id` 的 `result`、同步提交体、流的 `done.result`),
+      或运维队列 / 收件行上的 `checkpointId`、`GET /v1/runs/:id/events` 的 `needs_review` 账本行 `data.checkpointId`(同一个值)。值形:非空串、≤ 128 字符,否则 `400 request.field_invalid`。
+      **先读能力位再带键**:`GET /v1/capabilities` 的 `planReviewCheckpointId === true` 才带(位缺席 = 老 server,带了那一次决断整个失败)—— 别按版本号嗅探。
+    · **壳 / cli**:读 `409 approval_stale` 体的 `currentPending.checkpointId`,重取**那道门的计划**给人看,人认可后带新身份再决 —— 别拿它直接重发(那是在批一份没人看过的计划);
+      体里没有 `currentPending` ⇒ 重拉队列或 run 再决。
+    · **直连门签名器**:送这个键就要把它签进 HMAC 信封第 6 位的扩展对象(闭集字典序 `answer` / `checkpointId` / `permissionModeAfter`,例:`["s1","nonce-1",null,"approve",null,{"checkpointId":"cp_…"}]`);
+      不送它的签名器零改动(缺席时字节逐字不变);带了不签 ⇒ `401 approval_mac_invalid`。
+    · **跨版本**(读上一条的能力位就不会撞上):7.86.0–7.136.x 的 server 收到这个键答 `400 request.body_shape`(`unknownKeys` 含 `checkpointId`)—— 位缺席时不带键(= 回到没有陈旧保护的旧行为);
+      7.86.0 之前的 server 没有键闭集门,键被**静默丢**(200 照收、陈旧保护不在)—— 对那么老的 server 别指望这一位。
+    · **重拉还是同一个身份**:体里没有 `currentPending`、重拉 run 结果拿到的身份与你送的一样仍 409(队列 / 收件行上这一道门不带 `checkpointId`)⇒ 这道门的身份没过服务端的信任边界(坏行),带它永远对不上;
+      人看过**当前**计划之后不带这个键再决(这一次没有陈旧保护,告知运维查那一行)。
+    · 连带:`/decide` 收到 `checkpointId` 仍是 400,桶由 `unknownKeys` 换成 `unsupportedKeys`(指路计划审阅那道门);按桶分支的客户端核一下。
+
+13. **`delegation.ask_unresolvable` 通告的 `detail` 多可选键 `remedies`(wire 加性;消费方动作 = 读它、按 `kind` 渲染出路;引擎 7.56.0)**:用户读的 `detail.remedy` / `message` 两句自引擎 7.56.0 起不再教 `bypassPermissions`(模式放行那条出路只在运维放开该模式时才可提);这条出路改作数据:`detail.remedies` = 闭集 `approver` / `permission_mode` 上的非空表,恰在 `detail.remedy` 在场时带 —— `{ kind: "approver" }` 与 `{ kind: "permission_mode", value: "bypassPermissions", disclosedOn: "gate.disposition.released" }`(放行披露在那只调用的 `tool_end.gate.disposition.released`)。本服务只透传:不渲染、不改写、不补句。
+    **消费方动作**:渲染这条通告的宿主(client-core / cli / web-admin)读 `detail.remedies`、按 `kind` 渲染出路,闭集外的 `kind` 忽略;`remedies` 缺席 = 无出路可渲染。只读 `remedy` 句的消费者看不到 `permission_mode` 那条出路(此前句子里有,现在只在数据里)。服务部署零动作。
+
+14. **引擎 7.56.0 的五个新键本版刻意不投:`tool_start.requestedBy`、`tool_end.requestedBy`、`tool_end.answeredBy`、两个出口的 `hostFloor`(登记披露;无消费方动作)**:无消费方动作。这五位是引擎新增、本服务的帧投影登记簿表态「不投」的键(扩展自己发起调用的归因三位:本部署挂的每张注册都声明 `uses.calls: []`,零到达;主机底线姿态两位:本服务不声明 `RunnerDeps.hostFloor`,恒不会被铸出)。它们在 7.136.0 的 wire 上从未出现过,所以不是面丢失;翻转条件与理由见 CHANGELOG 7.137.0 节同名条。
+
+15. **本版其余 wire 面变化的消费方动作逐面表态(多数零动作;设备执行器的修订 3、`attachments.mcpUnavailable`、`resultEntryIds` 各有一句真动作)**:CHANGELOG 7.137.0 节里下列 wire 面的变化,逐面写消费方要做什么:
+    - **会话同步拉取口**(`GET /v1/sessions/:id/sync/manifest` · `…/entries` · `…/history/blobs/:hash`):库断连(含排在最前的会话门那一读)与部署错配(缺表 / 权限拒)由 `500 internal.error` 改答 `503 state.file_history_unreadable`,
+      体带 `permanence`(连接类 `transient` / 部署错配 `terminal`)。**消费方动作**:按 `permanence` 分支 —— `transient` 稍后重发同一请求;`terminal` 不重试、报运维(运维建表 / 授权之后同一请求可再发);
+      别再拿这三口的 `500` 当这两类故障的信号。文件历史店的故障答(`422 adopt_failed` / `restore_failed` 等)对缺表 / 权限拒同样带 `permanence: "terminal"`,同一读法。
+    - **`invalid_session`**:已存日志父链断裂的会话,`POST /v1/tasks` 同步腿由 `200` + failed 体改 `500 invalid_session`;`GET /v1/sessions/:id` / `…/memory-status` 的码由 `internal.error` 改 `invalid_session`。
+      **消费方动作**:当确定性失败处理(重试改不了判 —— 对 5xx 自动重试的端对这个码别重试),出路是换新会话或从断点之上的条目分叉。
+    - **`inheritEnv` 的三只 `400 request.field_invalid`**:拒体多 `field: "inheritEnv"` 与 `reason`(`unknown_word` · `not_a_string` · `lane_not_host` · `no_authorizer_session`)。**无动作**(加性;严格校验拒体键集的客户端放行这两键)。
+    - **`409 resume.constraint_rejected` 体的 `acceptableForm`**:**消费方动作**(批准界面):在场就把那一形呈给批准人、照它再批(读法与审批卡上的 `args` 同一种:已脱敏,超帽 ⇒ 缺席);缺席照旧。
+    - **`wiring_manifest.skills`**:**无动作**(加性;对 `wiring_manifest` 键集做严格校验的消费方放行它)。名册列的是这条 run **交给**引擎的技能;引擎对单只技能有大小上限,超过的那一只名册里有、引擎不装(CHANGELOG 同条的已知残余)。
+    - **`deviceExecutor.relayUrl`**:**消费方动作**(设备拨号方):在场就拨它、不再自己拼引擎地址 + `wsPath`;缺席照旧拼。
+    - **`inherit_env.names_withheld`(会话流通告)**:**无动作**(加性;渲染通告的宿主可按 `code` 显示「这些变量没给工具 shell」—— 只有名字没有值,执行环境说不出时 `state: "unknown"`;闭集外的码照旧忽略)。
+    - **设备协议修订 3 与结局码 `name_too_long`**(执行器实现者):能力位 `deviceExecutor.protocolVersion` 与 challenge 帧报 `3`。**动作**:要报「路径里有一段超过文件系统名字上限」的执行器,按随包 `docs/DEVICE-EXECUTOR-PROTOCOL.md` §1.2
+      声明修订 3(取 challenge 的与自己实现的较小者)再发 `name_too_long`(只用于文件指令);仍声明 1 / 2 的执行器不受影响,别发这个词。读文件失败码的调用方:`name_too_long` 与 `not_found` 同读(文件不在)。
+    - **`attachments.mcpUnavailable`**(请求键,布尔):**消费方动作**:要关掉引擎的「这一回合有 MCP 服务器挂不上」附件帧的调用方发 `attachments.mcpUnavailable: false`(缺省 = 开);非布尔 ⇒ `400 request.field_invalid`。
+      7.136.x 上这个键被静默丢(压回缺省开),所以别按版本号嗅探 —— 对 7.136.x 发它是无害的无效动作。
+    - **`result.resultEntryIds`**(引擎的结果键,随整只结果过境):**消费方动作**(可选):要「这段答复对应会话里哪几条消息」的读它(会话条目 id,会话序;空表 = 没读自任何已提交消息,缺席 = 出处不明,两者不同读);不读的忽略未知键即可。
+
+16. **7.136.x 停下、技能请求项带 `mods` 的任务续跑失败(行为变更;新提交早已 400)**:7.136.x 的受理门容技能项的未知键,引擎 7.55.x 忽略 `skills[].mods`,带它的请求照常成功;本版起新提交带它 ⇒ `400 request.field_invalid`。
+    7.136.x 上停下、存下的请求体里技能项带 `mods` 的任务,本版续跑时这一项原样交给引擎 7.56.0,引擎把它当一张技能扩展注册读、形不对即拒 —— 那一次续跑失败(7.136.x 上它被忽略)。
+    **怎么核**:只有手写过 `skills[].mods` 的调用方会有这种停驻任务。**做法**:升级前在 7.136.x 上决完或取消它们;升级后撞上的,取消后去掉 `mods` 重提。
+
+17. **订正 7.136.0 节第 4 条:没有返回任务目标全文的读口(`GET /v1/runs/:id` 不带目标)**:7.136.0 节第 4 条让「把 inbox `objective` 当完整目标用的」消费方「改读 run 详情面」—— 这句不真:
+    `GET /v1/runs/:id` 不带任务目标(没有 `objective`,也没有 `objectivePreview`)。本服务**没有返回任务目标全文的读口**:inbox 行的 `objective` 与 `GET /v1/assistant/tasks` 的 `objectivePreview`(写入时已脱敏、约 120 字符)是目标唯一的读数。
+    **消费方动作**:要全文展示 / 按全文匹配的,在提交时自己留存目标(提交方本来就持有它);会话历史里那一轮的用户消息是引擎处理过的输入(部署的钩子可能在前面加了文字),不保证与提交的目标逐字相同,别把它当目标原文。
+
+## 7.136.0 —— 中心登录令牌必须带 `scope`,不带的令牌验证不过(安全;行为面收紧,BREAKING;另含嵌入方 `webAdminJwtVerifier` 类型面) · anthropic 车道两把凭据同设起服拒(`ANTHROPIC_API_KEY` 与 `ANTHROPIC_AUTH_TOKEN`;行为收紧) · 一次性迁移 M5 退役(持久数据面;行为变更;嵌入方 `OneTimeMigrationReport` 去两键〔BREAKING,类型面〕;跳过 7.104.0–7.135.x 直升的库补列与铸令牌要自己做) · `GET /v1/assistant/inbox` 行的 `objective` 改成 run 行的目标预览(wire 值变更) · 审批卡信封多一个键 `approvalCard`(整队一次滚完;回滚到 7.135.x 时待决卡按 fail-safe 出口收场) · k8s 工作区快照桶起服时核存在性:没建桶的部署起服拒(行为收紧;升级前确认桶在) · `WORKSPACE_SNAPSHOT_PREFIX` 成为 `/` 分隔的闭集路径:不合形起服拒、未配快照存储也核(行为收紧;同时放宽到多段) · 子进程的命令行停驻时只以封签落盘(安全;零动作,升级序与回滚要留意:先停光 7.135.x 副本再起第一个 7.136.0 副本)
+
+1. **中心登录令牌必须带 `scope` —— 不带的令牌自本版起验证不过(安全;行为面收紧,BREAKING;另含嵌入方类型面)**:鉴权桥(`SEMA_WEB_ADMIN_URL` 在位默认开,或 `AUTH_BRIDGE_ISSUER`)
+   验过签名之后按 settings-schema 的唯一读法 `readTokenScope` 读令牌的 `scope`:缺、空串、不是字符串 ⇒ 拒,拒因 `scope_claim_missing`(日志 `auth_bridge_rejected` 的 `error`、
+   计数 `auth_bridge_verify_total` 的 `outcome`),处置与验签不过同一条 —— 不设任何身份,配了 service 凭据的部署答 `401 auth.unauthorized`(通用体,不说拒因)。不读成缺省 scope `global`。
+   此前这类令牌被当作已验证身份受理、角色照读。
+   **升级序**:先把全部签发点(web-admin 各副本;split 部署里 `AUTH_BRIDGE_ISSUER` 指向的签发方)升到每一枚访问令牌都带 `scope` 的版本,**再过 ≥ 1 小时**
+   (访问令牌寿命上限 3600 秒,存量的无 `scope` 令牌到期自愈),然后升本服务。做不到就接受:窗口里拿着旧令牌的调用方验证不过,刷新或重登即恢复(刷新换出的访问令牌恒带 `scope`)。
+   没有过渡旋钮。升级后看 `auth_bridge_verify_total{outcome="scope_claim_missing"}`:非零 = 仍有签发点不打 `scope`,或调用方拿着旧令牌没刷新。
+   **嵌入方**(只影响自己给 `ServiceDeps.webAdminJwtVerifier` 写验证器的;部署零动作):`verify` 成功返回的 `identity.scope` 必填(非空串),失败返回的 `error` 多一个词
+   `scope_claim_missing` —— 你的验证器读不出 scope 就答失败;tsc 红即是提示,零别名。交出 `scope` 为空串(JS 侧:缺省 / 非串)的成功身份
+   在装身份之前同样被 `readTokenScope` 拒,与验证失败同答。
+
+2. **anthropic 车道两把凭据同设 ⇒ 起服拒(行为收紧;另含子路径端口的行为)**:`ANTHROPIC_API_KEY` 与 `ANTHROPIC_AUTH_TOKEN` 都非空的部署(7.135.x 照起、只发 `Authorization: Bearer`,
+   `x-api-key` 被丢弃)升级后起服拒,拒句带 `[config.anthropic_credential_conflict]`、点名两键、不回显值。**升级前做**:二选一 —— 端点要 Bearer 就只留 `ANTHROPIC_AUTH_TOKEN`
+   (与 7.135.x 实际发出的头相同,线上字节不变),原生 Anthropic API 只留 `ANTHROPIC_API_KEY`;空串仍算未设(compose 透传的 `${VAR:-}` 不算同设)。
+   自拼 `ServiceConfig` 的嵌入方:`anthropic` 同时带非空 `apiKey` 与 `authToken` ⇒ `createBrain` 构造即抛同一句(此前 Bearer 胜出)。读子路径 `@sema-agent/server/model-route-env` 的
+   `laneAndEndpointFor`:两把同设的 env 上抛同一句(此前答 `apiKeyEnvName: "ANTHROPIC_AUTH_TOKEN"`)—— 在引擎起之前调它的壳先按上面二选一收好 env,或接住这一抛。
+
+3. **一次性迁移 M5 退役:会话表的化身列不再由起服补加、空化身的行不再由起服铸令牌(持久数据面;行为变更;嵌入方 BREAKING,类型面)**:7.104.0 引入的启动期迁移 ——
+   给 `session_meta` 补 `incarnation` 列、给每一行空化身(`''`)铸一只互不相同的随机令牌 —— 窗(发布日 + 30 天)于 2026-10-28 关,本版提前于窗关删了它的码(窗内从 ≤ 7.103.x 直跳的库起服拒:先升到 7.104.0–7.135.x 任一版补列、起服一次,再升本版;「谁受伤」与「做法」写了顺序),
+   以及起服日志行 `one_time_migrations_applied` 里的两个读数字段 `sessionIncarnationColumn` / `sessionIncarnationsBackfilled`(同一行里 `removableAfter` 读数的 `M5` 键随登记行消失,`note` 不再叙述它)。
+   按这两个字段做告警或看板的规则要删。新库照旧由建表语句建出这一列,`DB_BACKEND=local` 的令牌在数据根边档里,这条迁移从来不碰。
+   - **嵌入方(类型面)**:`StoreBackend.runOneTimeMigrations()` 的返回型 `OneTimeMigrationReport`(经包根导出的 `StoreBackend` 可达,本身不在包根导出名里)去掉 `sessionIncarnationColumn` 与 `sessionIncarnationsBackfilled`;
+     读它们的代码、把值标成 `OneTimeMigrationReport` 再写这两键的对象字面量 tsc 红;自实现该方法、未标注类型就直接返回含这两键的字面量的代码 tsc 不报(多出的键没有人读),也请一并删掉。
+   - **谁受伤**:从 ≤ 7.103.x 直接跳到本版、中间没在 7.104.0–7.135.x 任一版起过服的 SQL 库(含升级后仍有 ≤ 7.103.x 旧副本混跑、写下空化身行的库)。两种形,都是响亮的,没有静默错答:
+     ① `session_meta` 没有 `incarnation` 列 ⇒ 起服列册对账拒启 `config.schema_mismatch`,拒句里的 `ALTER TABLE session_meta ADD COLUMN incarnation …` 由建表语句生成,照句补列即可起服 ——
+     **补列之后立刻会落进第 ② 种**(新列对每个存量行都是缺省空串);② 列在、行上是空化身 ⇒ 那条会话取不出来(`acquire` 响亮拒 `session.incarnation_missing`),要一位活住客的读者(parked 决定腿)同拒,记忆座退回按 id 绑定并 warn;
+     `session.incarnation_missing` 是内部错误码,日志可见,wire 上是通用 500。起过 7.104.0–7.135.x 任一版的库、新库、`DB_BACKEND=local` 与内存形零影响。
+   - **做法**(只在受伤时,二选一):**先在 7.104.0–7.135.x 任一版上对这只库起服一次**(那几版的起服迁移补列并逐行铸令牌),再升到本版;
+     或在本版上按 ① 的拒句补列后,给每个空化身的行填一只互不相同的随机令牌(不透明串,至多 64 个字符,UUID 即可;只改 `incarnation = ''` 的行,已有令牌的行一个字节不动),或删掉那些会话。
+     令牌不上 wire、不进模型上下文、日志只打前 8 位。
+
+4. **`GET /v1/assistant/inbox` 行的 `objective` 改成 run 行的目标预览(wire 值变更;键名与可空性不变)**:此前是停驻上下文里存着的任务目标**原文**(不截断、不脱敏),
+   本版起是门所属 run 的 `objectivePreview`(写入时已脱敏、约 120 字符,与 `GET /v1/assistant/tasks` 同一列;委派子代的门读派它的那条 run);没有 run 账本的部署 ⇒ `null`。
+   **消费方动作**:把 inbox `objective` 当完整目标用的(全文展示、按全文匹配),改读 run 详情面;盯运维计数 `server.assistant-inbox.objective-ctx-corrupt` 的看板改盯
+   `server.assistant-inbox.objective-preview-unreadable`(旧 tag 退役,不再计数)。
+5. **审批卡信封多一个键 `approvalCard`(滚动升级 / 回滚)**:本版写下的待决审批卡(`approval_ask.card_json`)带卡词,7.135.x 及更早的二进制读不动这类行
+   ⇒ 那张卡在旧副本上开流重放时跳过、同一只问幂等重入改走耐久停驻(人仍可经耐久决断口补批;不会被当成拒绝)。**动作**:整队一次滚完,不留长期混版窗;
+   回滚到 7.135.x 时,7.136.0 写下的待决卡按上面那条 fail-safe 出口收场,升回即自愈。
+
+6. **k8s 工作区快照桶起服时核存在性 —— 没建桶的部署起服拒(行为收紧;运维前置)**:`REMOTE_EXEC=k8s` 且配了对象存储(`MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`)的部署,
+   起服时 server 对 `WORKSPACE_SNAPSHOT_BUCKET`(缺省 `workspaces`)指的桶做一次列举探针 —— 与会话快照桶(`SESSION_SNAPSHOT_BUCKET`)同一只探针、同一条规则:`404 + NoSuchBucket` ⇒ 在 `STORE_LOCK_WAIT_MS` 窗内重试、
+   到窗**起服拒**,拒句点名桶名、`WORKSPACE_SNAPSHOT_BUCKET` 与 `MINIO_ENDPOINT` 的显示安全形(不带密钥)。**server 不建桶**。7.135.x 上这种部署照起,之后每条 run 读 `latest` 得 404,
+   被当成「空间第一条 run」从空目录起,run 末保存失败(`workspace_snapshot_failed`)。连不上 / 403 / 5xx 这类证明不了缺桶的答复**不**拒启,走已登记的 fail-open 兜底口 `server.snapshot-bucket.presence-unproven`。
+   起服之后桶才没的(被删):读 `latest` 得 `404 NoSuchBucket` ⇒ 该 run 以 `connect_failed` 拒,句子与运维日志行 `workspace_snapshot_bucket_missing` 的 `code` 都是 `snapshot_bucket_missing`,不再读成新空间。
+   **升级前做**:确认 `workspaces` 桶(或你的 `WORKSPACE_SNAPSHOT_BUCKET`)存在 —— `mc mb <别名>/workspaces`,或把 `WORKSPACE_SNAPSHOT_BUCKET` 指向已有的桶。sema-up 的三条路径一直建 `workspaces`,不在受伤面。
+   不用工作区快照的 k8s 部署也在此列:对象存储三键一配,这只桶就是停驻挂起与跨轮保留共用的店,拒启的出路只有建桶 / 改指,没有关掉这次探针的旋钮。建桶晚于 server 起的编排:`STORE_LOCK_WAIT_MS` 窗内会重试。
+
+7. **`WORKSPACE_SNAPSHOT_PREFIX` 成为 `/` 分隔的闭集路径 —— 不合形起服拒(行为收紧;同时放宽到多段)**:前缀是一段或多段普通 key 段(`kata`、`libA/ws`),每段以字母或数字开头,其后字母、数字、`.` `_` `-`;
+   空段(前导 / 尾随 / 连续的 `/`)、`.` / `..`、其它字符 ⇒ **起服拒**,码 `config.workspace_snapshot_prefix_invalid`,句子点名第几段。🔴 **未配快照存储(`MINIO_*` 缺)也核**:此前这个值没有存储时根本不读,
+   拼错的值一直潜伏;现在 `REMOTE_EXEC=k8s` 的部署不论配没配存储,起服即核(别的车道不读这个值,杂散的值不拒)。配了存储的部署:7.135.x 对不合形的值在第一次连沙箱时才以
+   `unsafe snapshot key segment (keyPrefix)` 拒(只落在那一条 run 上),现在起服就拒;多段值(`libA/ws`)是新放宽,7.135.x 上同样在运行期被拒。合法的单段旧值行为不变。
+   **升级前做**:核 `WORKSPACE_SNAPSHOT_PREFIX` 的值,不合形的改成合形的;改前缀 = 换了一个 key 空间,旧前缀下的存量快照与 `latest` 不再被读 —— 要保留已有的快照就别改合形的旧值。
+8. **子进程的命令行停驻时只以封签落盘(安全;零动作,升级序与回滚要留意)**:stdio MCP 传输与 command hook 条目的 `command` / `args`(`args` 整只数组一个值)进凭据位,
+   与 env 同一条判据;续跑开封后逐字交执行器,调用方零改动。升级前停驻过的这类任务,命令行明文已经在库 / 盘(及其备份)里 —— 起服的一次性迁移在窗内(至 2026-11-20)把仍在的行原地封好,
+   已落过盘的字节改不回来:**轮换**这些命令行里出现过的密钥。
+   **多副本升级**:会停驻带 stdio MCP 或 command hook 任务的部署,先停光 7.135.x 副本再起第一个 7.136.0 副本(两版混跑时:7.135.x 副本续跑 7.136.0 停驻的这类任务 ⇒
+   整行 `409 conflict.checkpoint_ctx_unsealable`(`reason:"unrecognized_seal"`,`field:"credentialSlotGeneration"`);7.135.x 副本新写的这类行在 7.136.0 上续跑 ⇒ `409`(`reason:"plaintext"`),
+   直到下一次 7.136.0 起服的一次性迁移把它封好 —— 只在窗内)。**回滚到 7.135.x 之前**:用随包排空检查的 `sealed-credentials-rollback` 判据把带封签的停驻任务决掉或取消(这一类在候选里)。
+   三只拒句(`conflict.checkpoint_ctx_unsealable` 两句与装配期拒启)改成规则形,按句子字面匹配的脚本改按 `errorCode` / `field` / `reason` 读。
+
 ## 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 参数
@@ -115,7 +350,7 @@
    **升级前做**:`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 拒扫(引擎拒收,行停到绝对兜底)而不是作废。
+   已在跑的 7.134.x 副本写下的问答停驻行不带这一列,在下一次本版起服之前到期会进 SLA 拒扫(引擎拒收,行停到绝对兜底)而不是作废;7.136.0 起这些行在拒扫选行里排在带卡词的审批行之后,不再挤占后者的取行窗(卡列同为空的审批行之间仍按到期序,先停光旧副本再起新仍是规避)。
    **不要**删表重建 `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` 都执行)再起旧版。
@@ -156,7 +391,7 @@
    - **升级序: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 副本新写的)会把凭据位当空值 ——
+     同时起多个副本可能各建一把:钥匙创建是先读目录、没读到可用的钥匙文件才生成并写入,没有互斥 —— 只有两个副本在同一个目录上同时首启、都没读到可用的钥匙文件时才各建一把;各建了就互相答 `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` 判据列出它们: