@sema-agent/server 7.123.0 → 7.124.1

package/MIGRATION.md

@@ -7,6 +7,144 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## Unreleased
+
+1. **订正 7.124.0 节「升级前必读」一句**(文字订正,行为不变):那句写决断口 409「新增一码」—— 7.124.0 **没有**新增任何决断口 409 码(复审中整退);决断口的变化只有:`field:"answer"` 的 409 由 `approval_binding_mismatch` 挪到 `resume_outcome_invalid`,以及 `409 checkpoint.unsupported_version` 体多出 additive 的 `writerVersion` / `readerVersion` 两键。第 14 条正文是对的,以第 14 条为准。
+2. **订正契约 §0.4 一句**(文字订正,行为不变):扁平布尔对 `draining` / `drainingSince` 在 7.124.0 **仍照发**,删发随提货 settings-schema 12.0.0 的那一版(届时发车帖点名);消费方现在就可改读 `engineSignal.draining`。
+3. **订正 7.124.0 节第 14 条的 `field:"answer"` 一句**(文字订正,行为不变):「`field:"answer"` 改发 `resume_outcome_invalid`」描述的是本服务对 core 闭集词 `answer` 的**映射表项**,不是 7.124.0 决断口上可观察到的行为变化 —— 在 core 7.48.0 下,引擎铸 `field:"answer"` 的三种形(答案不是规范数组 / 答案配在 deny 或非问题卡上 / 批准问题卡却无答案)在 `POST /v1/approvals/:sessionId/decide` 上都先被本服务的请求/状态守卫以 `400 request.field_conflict` 或 `400 request.body_shape` 拒掉,普通停驻卡上**没有**一种请求能拿到那条 409;唯一能让引擎抛出它的是 parked 子代行上「deny 带 answer / 非问题卡带 answer」,而那条腿把它作 `422 parked_resume.startup_failed` 透传(引擎原句,无 `field`)。消费端不需要为这一句改任何码;两腿投影不一致本身已登记为待收口项。
+
+## 7.124.0 —— `@sema-agent/settings-schema` 11.2.0(major):升级序硬约束 · `models.atMention` 取代 `atModelAllowlist` · 盘上 LKG / 本地 `config.d` / 调度店的一次性迁移(升级零动作,回滚有条件)· 缺省模型只有 `roles.default` 一位 · web-admin 连接 env 整组改名(旧名在场即拒启)· web 基址与中心身份起服互证 · 日志键 `sema_registry_*` → `web_admin_*` · 排空口动作号是标识符 · 审批「结局成因」一张闭集(410 `deniedReason` → `cause`,晚答 404 旧词退役,决断口 409 按成因分码;`checkpoint.unsupported_version` 体带写者 / 读者两个版本键)
+
+**升级前必读**:升级序按中心视图分两种(第 1 条)—— 视图里没有退役形(`models.atModelAllowlist` / `models.default` / 带限额的 `runtime` 域)⇒ 先把所有引擎升到本版,再让 web-admin 升到 settings-schema 11.x;视图里有退役形 ⇒ 先把 web-admin 升到 11.x、在中心上把数据改成新形,再滚引擎;两种窗口里都别重启 7.123.0 引擎(重启后 `@` 限制静默放开)。接 web-admin 的部署把全部连接 env 改写成 `SEMA_WEB_ADMIN_*`(第 7 条:旧名在场即拒启;由 web-admin 编排器渲染 env 的车队(web-admin 0.1.x 渲染)只能**停机换代三步**:① 停引擎;② 把中心换到带「按目标引擎版本写名」渲染器的 web-admin 版本(随 settings-schema 11.x 换岛同车到),或由运维手改 env 成 `SEMA_WEB_ADMIN_*` 十键;③ 起新引擎 —— 不存在零停机顺序);设了 web 基址的部署核一眼它与 issuer 是同一台 web-admin(第 11 条);按日志键告警的规则改前缀(第 12 条);有本地 `config.d` 的部署升级前备份它(第 3 条,回滚要还原它);按 `410 gone.ask` 体的 `deniedReason` 键、按晚答 `404` 的 `cause === "voided" | "denied"`、或按 `approval_binding_mismatch` 一码处理所有决断口 409 的壳核第 14 条(键名与旧词退役,`answer` 席改码,新增一码)。
+
+1. **升级序(按中心视图分两种部署;跨仓硬约束)**:11.x 的 web-admin 发给引擎的有效视图恒带 `models.atMention`;内带 10.x 契约的引擎(≤ 7.123.0)刷新时把整份候选当未知键拒、停在上一份好配置
+   (`config_candidate_rejected … unknown keys dropped by domain schema: atMention`,`engineSignal.configTargetVersion ≠ configAppliedVersion` 持续不收敛,`/health` 仍报健康)。web-admin 的 10.x 与 11.x 副本也不要混跑(10.x 副本仍会写出旧形)。
+   - **视图里没有退役形**(没有 `models.atModelAllowlist`、`models.default`、带限额的 `runtime` 域):先把所有引擎升到本版(连接 env 先改成新名,第 7 条),再让 web-admin 升到 11.x。
+     窗口里仍是 7.123.0 的引擎**不要重启**:它起服时对 11.x 视图按起服的容错读法照收、只丢 `atMention`(一行 `config_domain_invalid … unknown keys dropped by domain schema: atMention`),
+     起来后 `configTargetVersion = configAppliedVersion`、`@` 限制静默放开(`only` / `none` 变成全放行)—— 刷新被拒那一形认得出,重启后这一形认不出。
+   - **视图里有退役形**:「引擎先」会让本版引擎起服时 models 域整域落缺省 —— 目录只剩 env 模型(`MODEL_ID`),点名目录模型的请求 400 `request.unknown_reference`;中心可达时起服不读盘上 LKG,
+     7.123.0 写的那份救不回这一形;只有起服一行 `config_domain_invalid`(点名 `SS-M6` / `SS-M9`)与此后每次刷新一行 `config_candidate_rejected`;`engineSignal` 起服那一拍认不出
+     (`configTargetVersion = configAppliedVersion`),从中心发布下一版、刷新首拍被拒起 `configTargetVersion ≠ configAppliedVersion` 认得出(中心版本没前进时被拒的刷新两值仍相等)。
+     带限额的 `runtime` 域起服整包拒(拉取失败 ⇒ LKG / env)、刷新 `502`,`engineSignal` 两拍都是 `0/0`(版本没读到),只能看拉取失败行。**正确顺序**:先把 web-admin 升到 11.x(它起服迁移自己的存量;
+     这段时间 7.123.0 引擎对 11.x 视图整份拒、冻在 LKG —— 窗内不要重启它们,理由同上),在 11.x 中心上确认数据已是新形(`atMention` / `roles.default` / `limits`),再滚引擎到本版。
+   - **逐条丢弃不是域拒**:同设两种钥匙的模型条目、URL 带 `#` 的条目在本版是逐条丢弃 —— 那一条不在、其余照用,候选照常应用(`configAppliedVersion` 前进),`config_entry_dropped` 行点名迁移 id 与命令;不影响升级序。
+2. **`models.atMention`**:「`@` 能点名哪些模型」三态 `{mode:"all"}`(缺省)/ `{mode:"none"}` / `{mode:"only", models:[…]}`,取代数组 `atModelAllowlist`(在场即被契约拒)。
+   语义对应:旧的缺席 / 空数组 = `all`,非空数组 = `only`;`none` 是新的(一个都不许)。`GET /v1/models`:`all` 时行上没有 `atMentionable`(与此前名单缺席逐字同),`none` 时每行 `false`,`only` 时逐行布尔。
+   `request.model_not_allowed` 码不变、句子变(`… is not @-mentionable on this deployment … (models.atMention)`)—— 按码分流,别按句子文本匹配。
+3. **本地 `config.d`(配置源 local)起服一次性迁移**:本地配置源第一次读之前,引擎把本地读腿会读的那几份文档(便携域与 `runtime.json`)交给契约的一次性迁移跑一次:
+   `models.atModelAllowlist` → `atMention`、`models.default` → `roles.default`、`runtime.json` 的治理三闸 → `governance.json` / 限额五键 → `limits.json`(之后删 `runtime.json`)、
+   模型条目同设两种钥匙 ⇒ 去掉 `apiKeyEnv`、URL 带 `#` ⇒ 剥掉。引擎不读的域文件(`hosts.json` / `workers.json` 等)一个字节不动 —— 它们若要迁,手跑下面那条命令。
+   整域判得过才原子写回(已有文件沿用原模式);改写了 ⇒ 日志 `config_dir_migrated` 一行(收据点名迁移 id 与坐标,不带值);再起服零改动。
+   **迁不动的**(例:同一份文档里两种写法并存,迁移不替你挑)⇒ 一字不写、`config_dir_migration_refused` 一行点名;读侧对这些旧形照旧拒(models 域降级 / rosters 整份读不出 / `runtime.json` 带事实 ⇒ 整份读不出),
+   照报告手改后重起,或手跑 `npx @sema-agent/settings-schema migrate <config.d 目录>`。`config.d` 不存在或里面没有域文档 ⇒ 不跑。
+   **回滚到 7.123.0 及以前**:改写过的 `config.d` 是 11 的形;旧引擎照读目录与 `roles.default`,只把 `models.json` 里的 `atMention` 当未知键丢掉(一行 `config_domain_invalid … unknown keys dropped by domain schema: atMention`)⇒ `@` 限制放开(`only` / `none` 变成全放行)—— **升级前备份 `config.d`,回滚时还原**。
+4. **盘上 LKG 信封 formatVersion 3 → 4**:每次读回都过契约的一次性迁移(只认形、幂等),迁过的按 4 写回原位,日志 `config_lkg_migrated` 一行(带收据);有迁不动的坐标 ⇒ 这份 LKG 不读回
+   (`config_lkg_unusable`,拒因点名迁移 id;中心可达照拉、断着则 env 兜底,下一份干净候选重写)。**回滚到 7.123.0 及以前**:那些进程读不懂 4,把这份 LKG 当不可用(中心可达照拉 —— 但第 1 条:
+   10.x 引擎读不进 11.x web-admin 的候选,回滚引擎的同时要么 web-admin 也停在 10.x,要么接受它停在 env)。
+5. **调度店(`scheduled_tasks.json`)**:文件形不变。写者改走契约的唯一写原语(与常驻 daemon 不再丢更新);整份文件不是 JSON 数组 ⇒ 调度 / 取消答 `io` 错误、文件**不被覆盖**
+   (此前读成空店再整份覆盖)—— 修好或删掉那个文件即恢复;读到的坏记录 / 过期会话记录 / 读时改写各进一行日志(不带记录原文)。
+6. **缺省模型只有 `roles.default` 一位**:`models.default` 键退役(读侧拒,第 3 条迁移把它并进 `roles.default`;两位都设且不同时并过去的是 `models.default` —— 此前主任务真跑的那一个)。
+   `roles.default = {select: …}` 的部署:主模型改成引擎按 `default` 角色挑中的那只(此前跑的是档位 / 第一条可用条目);什么都挑不中 ⇒ 模型面这一组被拒 `[config.default_model_missing]`(上一代模型面继续服务)。
+   要固定主模型就写 `roles.default = {model: <名>}`。
+7. **web-admin 连接的 env 名整组换成 `SEMA_WEB_ADMIN_*`(settings-schema `WEB_ADMIN_ENV` 表),旧名在场即拒启**。值与文件内容的形一个字节不变;凭证两键仍二选一、都设拒启。
+   引擎只读新名,旧名零读点;任一旧名设着(非空)⇒ 起服拒,新名同时设着也拒(「两个都留着」正是迁移到一半最常见的形)。对照表(左列括号里是更早一代、同样拒的名):
+
+   | 旧名 | 新名 |
+   |---|---|
+   | `SEMA_REGISTRY_URL`(`CONFIG_CENTER_URL`) | `SEMA_WEB_ADMIN_URL` |
+   | `SEMA_REGISTRY_TOKEN`(`CONFIG_CENTER_TOKEN`) | `SEMA_WEB_ADMIN_TOKEN` |
+   | `SEMA_REGISTRY_TOKEN_FILE` | `SEMA_WEB_ADMIN_TOKEN_FILE` |
+   | `SEMA_REGISTRY_WORKER`(`CONFIG_CENTER_WORKER`) | `SEMA_WEB_ADMIN_WORKER` |
+   | `SEMA_REGISTRY_LIVE_URL` | `SEMA_WEB_ADMIN_LIVE_URL` |
+   | `SEMA_REGISTRY_WEB_URL` | `SEMA_WEB_ADMIN_WEB_URL` |
+   | `SEMA_REGISTRY_DRY_RUN`(`CONFIG_CENTER_DRY_RUN`) | `SEMA_WEB_ADMIN_DRY_RUN` |
+   | `SEMA_REGISTRY_ADMIN_TOKEN`(`REGISTRY_ADMIN_TOKEN`) | `SEMA_WEB_ADMIN_ADMIN_TOKEN` |
+
+   起服拒句样例(stderr 首屏,进程非零退出;只点名键、不回显值):
+   ```
+   retired env name(s) set [config.env_key_retired] — refused while present, whether or not the replacement is also set: SEMA_REGISTRY_URL → use SEMA_WEB_ADMIN_URL; SEMA_REGISTRY_TOKEN_FILE → use SEMA_WEB_ADMIN_TOKEN_FILE — rename the env key(s); the value semantics are unchanged.
+   ```
+   这张墓碑表的属主是 settings-schema(`RETIRED_ENVS`;拒句 `retiredEnvRefusal`):引擎起服、壳起本机引擎之前、web-admin 渲染 worker env 之前读同一张;`GET /v1/config/catalog` 的 `retired[]` 是它的投影
+   (`CONFIG_CENTER_*` / `REGISTRY_ADMIN_TOKEN` 的 `replacement` 现在直指 `SEMA_WEB_ADMIN_*`,并多出上表左列八行)。给引擎渲染 env 的一方(web-admin 编排器、部署脚本、壳)按目标引擎版本写名:本版及以后写新名。
+   本包根不再导出 `RETIRED_ENVS` / `RetiredEnv` / `RetiredEnvKind` / `RetiredEnvWire`(构建期工具改 import `@sema-agent/settings-schema`;tsc 红即通知)。
+8. **`runtime` 域退役**:限额五键只从 `limits` 域读;中心(或更老的存量)仍在 wire 上发带事实的 `runtime` 域 ⇒ 整包拒(拉取失败、回落 LKG / env,拒句点名一次性迁移 `SS-M1`)。把限额写进 `limits`。
+9. **排空口 `POST /v1/admin/drain` 的 `actionId` 是标识符**:1–128 字符,首字母数字,其余字母数字 / `.` / `_` / `:` / `-`;带空格或任意文本 ⇒ `400 request.field_invalid`(零状态变化)。
+   改成 id 形(`manual:<uuid>`、时间戳、序号都合法)。
+10. **诊断文案**(运维日志,零 wire 变化):`config_domain_invalid` / `config_candidate_rejected` 里的整域失效改成逐条 `坐标: 句子`(值的位置写 `«value»`,契约拒句里的迁移 id 原样可见);
+   悬空引用改成契约句式 `<引用者> → unknown <名词> "<指纹>" (at <坐标>)`,每条引用只在引用者的域下报一次;逐条丢弃行与整域行对同一条 issue 读同一句:契约给了整句就读整句(值位 `«value»`),没给就读 issue 自己的规则句(`contextWindow: Invalid input: expected number, received string`;URL 带 `#` 的条目点得出 `SS-M7` 与迁移命令);超过 600 字截断时句尾带 `…(truncated)`。按旧句式解析这些行的脚本要改读法。
+11. **web 基址与中心身份起服互证**:`SEMA_WEB_ADMIN_WEB_URL` 在场时,必须与中心身份 —— `AUTH_BRIDGE_ISSUER`,缺席 = `SEMA_WEB_ADMIN_URL` —— 同主机同端口(http 与 https 同主机算一族;路径不比)—— 即两只 URL 的 `URL.host`(主机 + 非缺省端口)相同,这就是「同 origin 族」的全部定义。
+   不同 ⇒ 起服拒,拒句点名两只旋钮与两个主机;`AUTH_BRIDGE_ISSUER` 不是 http(s) URL ⇒ 证不了同一个中心,同样拒。
+   基址 / 活性基址(`SEMA_WEB_ADMIN_URL` / `SEMA_WEB_ADMIN_LIVE_URL`)是传输地址,不参与 —— 编排器注入集群内地址、`AUTH_BRIDGE_ISSUER` 写对外域名的标准形照常起服。
+   出路:`SEMA_WEB_ADMIN_WEB_URL` 写那台 web-admin 自己的界面地址;或把 `AUTH_BRIDGE_ISSUER` 设成 web-admin 的对外 origin;或不设 `SEMA_WEB_ADMIN_WEB_URL`(`/health.center.webBaseUrl` 缺席,壳不拼深链)。
+12. **日志键 `sema_registry_*` → `web_admin_*`**(后缀逐字不变;字段只有 `web_admin_models` 一处随 `atMention` 换代,见表里那一行;同一行 `defaultSource` 的值 `enabled[0]` 改叫 `fallback`(缺省模型命名链的兜底级,第 6 条))。按日志键告警 / 过滤的规则照下表改:
+
+   | 旧日志键 | 新日志键 |
+   |---|---|
+   | `sema_registry_a2a` | `web_admin_a2a` |
+   | `sema_registry_a2a_env_missing` | `web_admin_a2a_env_missing` |
+   | `sema_registry_a2a_name_unusable` | `web_admin_a2a_name_unusable` |
+   | `sema_registry_approval_require_invalid` | `web_admin_approval_require_invalid` |
+   | `sema_registry_at_mention_dangling` | `web_admin_at_mention_dangling` |
+   | `sema_registry_at_mention_invalid` | `web_admin_at_mention_invalid` |
+   | `sema_registry_collab_notes` | `web_admin_collab_notes` |
+   | `sema_registry_collab_skipped` | `web_admin_collab_skipped` |
+   | `sema_registry_collab_workflows` | `web_admin_collab_workflows` |
+   | `sema_registry_commandpolicy_invalid` | `web_admin_commandpolicy_invalid` |
+   | `sema_registry_default_dangling` | `web_admin_default_dangling` |
+   | `sema_registry_dry_run` | `web_admin_dry_run` |
+   | `sema_registry_limits` | `web_admin_limits` |
+   | `sema_registry_limits_deferred` | `web_admin_limits_deferred` |
+   | `sema_registry_limits_invalid` | `web_admin_limits_invalid` |
+   | `sema_registry_limits_unconsumed_keys` | `web_admin_limits_unconsumed_keys` |
+   | `sema_registry_mcp` | `web_admin_mcp` |
+   | `sema_registry_mcp_content_class_invalid` | `web_admin_mcp_content_class_invalid` |
+   | `sema_registry_mcp_env_missing` | `web_admin_mcp_env_missing` |
+   | `sema_registry_mcp_name_unusable` | `web_admin_mcp_name_unusable` |
+   | `sema_registry_mcp_tool_faces_invalid` | `web_admin_mcp_tool_faces_invalid` |
+   | `sema_registry_model_base_url` | `web_admin_model_base_url` |
+   | `sema_registry_model_entry_invalid` | `web_admin_model_entry_invalid` |
+   | `sema_registry_model_key_env_missing` | `web_admin_model_key_env_missing` |
+   | `sema_registry_model_no_brain` | `web_admin_model_no_brain` |
+   | `sema_registry_model_plane_refused` | `web_admin_model_plane_refused` |
+   | `sema_registry_model_plane_swap_refused` | `web_admin_model_plane_swap_refused` |
+   | `sema_registry_model_sealed_key_no_private_key` | `web_admin_model_sealed_key_no_private_key` |
+   | `sema_registry_model_sealed_key_no_store` | `web_admin_model_sealed_key_no_store` |
+   | `sema_registry_model_sealed_key_open_failed` | `web_admin_model_sealed_key_open_failed` |
+   | `sema_registry_models` | `web_admin_models`(字段 `atModelAllowlist: <个数>` → `atMention: <mode>`,`<mode>` ∈ `all` / `none` / `only`) |
+   | `sema_registry_projects` | `web_admin_projects` |
+   | `sema_registry_read_face` | `web_admin_read_face` |
+   | `sema_registry_read_face_env_wins` | `web_admin_read_face_env_wins` |
+   | `sema_registry_read_face_invalid` | `web_admin_read_face_invalid` |
+   | `sema_registry_refresh_failed` | `web_admin_refresh_failed` |
+   | `sema_registry_refreshed` | `web_admin_refreshed` |
+   | `sema_registry_role_binding_unavailable` | `web_admin_role_binding_unavailable` |
+   | `sema_registry_runtime` | `web_admin_runtime` |
+   | `sema_registry_runtime_hot` | `web_admin_runtime_hot` |
+   | `sema_registry_scenario_invalid` | `web_admin_scenario_invalid` |
+   | `sema_registry_scenarios` | `web_admin_scenarios` |
+   | `sema_registry_skill` | `web_admin_skill` |
+   | `sema_registry_skill_cache_corrupt` | `web_admin_skill_cache_corrupt` |
+   | `sema_registry_skill_cache_write_failed` | `web_admin_skill_cache_write_failed` |
+   | `sema_registry_skill_duplicate_name` | `web_admin_skill_duplicate_name` |
+   | `sema_registry_skill_failed` | `web_admin_skill_failed` |
+   | `sema_registry_stale_generation_refused` | `web_admin_stale_generation_refused` |
+   | `sema_registry_tier_binding_unavailable` | `web_admin_tier_binding_unavailable` |
+   | `sema_registry_unpublished` | `web_admin_unpublished` |
+
+   连带:`POST /v1/admin/config/refresh` 的 502 `internal.config_refresh_failed` 句里点名的日志行改叫 `web_admin_refresh_failed`(码不变)。
+13. **嵌入方类型面改名(零别名)**:`ServiceConfig.configCenter` → `webAdmin`、`ServiceDeps.registryJwtVerifier` → `webAdminJwtVerifier`、`ServiceDeps.configCenterManagedKeys` → `webAdminManagedKeys`(形不变)。
+   只用 `sema-server` 起服的部署零动作;自建 `ServiceDeps` 的嵌入方按名改(tsc 红即通知)。
+14. **审批「结局成因」收成一张闭集(17 词);读面三处同一个词,决断口 409 按成因分码**(硬破坏,零别名):一张卡没被人答就结束了,「为什么」此前在四个读面各说各话(审计 settle 行的 `expired` 一词盖窗到期 / run 取消 / run 退出 / 广播全灭,问账 `denied_reason`、晚答 404 的 `cause`、决断口 409 的码各有各的词表)。现在只有一张表,`cause` 在场 ⇔ 非人结局,人答的结局没有 `cause`。断连强转 park 记 `stream_disconnected`、持久行不可用 / 身份不定的兜底臂记 `undeliverable`,`broadcast_lost` 只留给 emit 零接收这一个事实。
+   - **活卡结局帧 `tool_approval_complete` 多一个 additive 键 `cause`**(非人结局在场、人答缺席,与审计 settle 行同一个词):壳据它把 `outcome:"expired"` 渲成「已取消 / 已到期 / 断连」。旧壳不读这个键,零变化。带系统成因的 `VOID` / `DENIED` 行(例:兄弟被别处撤卡)被 CAS 输家读到时,帧 `outcome` 由 `denied` 变 `expired`(引擎收到的值不变 —— 例外是开卡帧尚未确认送达任何连接的极窄窗:`park` 政策下引擎收到 `unavailable`,此前是拒),按帧上的 `cause` 分辨。
+   - **`POST /v1/tasks/:taskId/asks/:askId/decision` 的 `410 gone.ask` 体:键 `deniedReason` → `cause`**(值域:原有八个词 + `run_exited` / `batch_sibling_withdrawn`;`state:"DENIED"` ⇒ `routing_failure_fail_closed`)。读 `deniedReason` 的消费端改读 `cause`;行上没写成因的存量行(升级前落的 `VOID` 行)体里仍无该键。`crashConverged[].cause` 与它是同一个词。
+   - **`POST /v1/tool-approvals/:id/respond` 的 `404 tool_approval.not_pending` 体的 `cause`:旧词 `voided` / `denied` 退役**,换成行上记的具体成因词(同一张表:`run_cancelled` / `run_exited` / `batch_sibling_withdrawn` / `routing_failure_fail_closed` ……);`unknown_or_other_replica` 保留;行上没写成因 ⇒ 无 `cause`。按 `cause === "voided"` 分支的壳改成「任何成因词 ⇒ 这张卡没有人决过它,消卡」。
+   - **决断口 `POST /v1/approvals/:id/decide` 的 409 不再借名**:`approval_binding_mismatch` 只说「绑定变了」(`retriable:true`,重取坐标再决);**`field:"answer"` 改发 `resume_outcome_invalid`**(`retriable:true`,改答案再决 —— 此前借 `approval_binding_mismatch`,按「`approval_binding_mismatch` + `field`」分支的壳要把 `answer` 挪到 `resume_outcome_invalid` 一臂)。这两个码只按 core 的 `field` 分,与停驻行由哪一版写出无关;没有 `field` 的拒(含 core 的行完整性拒,例 `read_face_damaged`)逐字维持 `approval_binding_mismatch` —— 行损坏对任何版本都是损坏,不是版本不兼容。`retriable` 在决断口只有一个意思:卡仍 pending、run 行重新停回 `suspended`,不是「在本引擎上重试会成功」。
+   - **「停驻行的格式比本引擎新」只有一个来源 = core 的 `409 checkpoint.unsupported_version`**(原因 `version_newer`,`retriable:true`):本版起它的体多两个 additive 键 **`writerVersion`**(停驻那一版服务)/ **`readerVersion`**(本引擎),只在这一码上出现、这一码的每一个铸点同律(含本服务自铸的两只读法记号拒),续跑上下文带写者版本时在场;两值相等也照带(那就不是版本问题,出路照码与报文)。按码分支的壳给这一码读两个版本键:`writerVersion` 比 `readerVersion` 新 ⇒ 回到 `writerVersion` 那一版(或更新的一版)去决,不是在本引擎上重试。
+   - **写者版本**:续跑上下文(`checkpoint_ctx`)多一个服务端写的键 `writerVersion`(写它的服务版本;每次新的持久化写和每条续跑腿的写回都盖本进程的版本),`checkpoint.unsupported_version` 的体据它带两个版本键;它不参与判成因、不改任何码。本版之前停驻的卡没有它 ⇒ 那一码的体不带两键,**如实不猜**;零 DDL、零迁移。
+   - **审计账本** `ledger.jsonl` 的 `settle` 行:非人结局(`outcome:"expired"`)恒带 `cause`(同一张表),人答缺席;本版之前落盘的 `expired` 行没有 `cause`,照读不回填。这一面留盘给取证,不上任何 HTTP 读面。有序关停期间同批两张卡的 settle 行:赢家 `shutdown_before_park`、被撤卡的兄弟 `batch_sibling_withdrawn`(此前兄弟也盖 `shutdown_before_park`)。
+   - **回滚**:老引擎去批新引擎停驻的卡 —— 行格式同代 ⇒ `200`,照常决(例:回滚到 7.123.0,两版内带同一个引擎,停驻行的形读得懂);core 报行格式更新 ⇒ `409 checkpoint.unsupported_version`(`retriable:true`,卡留 pending、命令没有交给 shell;读者 ≥ 7.124.0 时体带 `writerVersion` / `readerVersion`,`writerVersion` 比 `readerVersion` 新 ⇒ 出路 = 回到 `writerVersion` 那一版去决);core 把行读成损坏(无 `field` 的行完整性拒)⇒ `409 approval_binding_mismatch` + `retriable:true`,不论写者版本。订正 7.123.0 节第 9 条的回滚句 —— 回滚到 7.122.0 及以前、旧引擎读不懂**本版停驻**的那一行时,决断口答的是 `409 approval_binding_mismatch` + `retriable:true`(卡留 pending、命令没有交给 shell),不是那一节写的 `checkpoint.invalid_outcome`(原因 `read_face_damaged`)—— 后者只在**续跑那一腿**出现。**出路不变**:回滚前先在本版上续跑完停泊任务,或确认没有这类停泊任务。
+     回滚到 7.123.0 后,本版写下的非人结局 settle 行(成因不是 `shutdown_before_park` 的那些)会被 7.123.0 的审计账本计入坏行(`corruptLines`):这些卡的结清照认,只是启动收敛的探针行会报出坏行数 —— 那是成因词读不懂,不是账本坏了。
+
 ## 7.123.0 —— `GET /v1/models` 自报被读腿丢掉的目录条目(additive)· LKG 信封 formatVersion 2 → 3(升级零动作,回滚有条件)· settings-schema 10.1.1(存量配置里夹私钥 PEM 头的条目升级后被丢) · core 7.48.0(会话规则写口拒空串项 / `mcp__<server>__` 拒码变 / `/` 开头的读拒行根锚定 —— 回滚有条件 / shell 读法收窄与放宽) · `permissionModeAuto.reason` 新词 `operator_floor`
 
 **升级前必读**:`SEMA_CONFIG_DIR` 设成工作目录本身或它的祖先(容器里 `SEMA_CONFIG_DIR=/workspace` 而项目在 `/workspace/proj`、或直接设成 `HOME`)的部署,项目里的写都要过 `write_protection` 一问、allow 规则放不掉 —— 把配置根指到项目之外的目录(第 4 条);依赖「`AUTONOMY=plan` 下人批了一次写就写成」的壳核一遍第 5 条的射程(写面根围栏之内);把订阅流的 `error` 终帧整类当「run 已动过」的消费端核第 6 条。往会话规则里写空串 / 纯空白项、或按 `request.field_invalid` 处理 `mcp__<server>__` 的调用方核第 7、8 条;设了 `CONFIG_LKG_PATH` 或运维读拒行以 `/` 开头的部署核第 9 条 —— **回滚到 7.122.0 及以前前先清空停泊任务**;无人值守腿(leader、无终端的 `run-local`)上跑带流喂 shell 的脚本核第 10 条。

package/README.md

@@ -185,7 +185,7 @@ The server is configured entirely through environment variables. The most import
 | `PORT` | `8090` | HTTP listen port |
 | `BIND_HOST` (alias `HOST`) | see note | Listen address. An explicit `BIND_HOST` **always wins**. Default: `127.0.0.1` when the write face is unauthenticated (`ALLOW_UNAUTHED_WRITES=true` **and** no service token configured), otherwise all interfaces — deployments with a token are unaffected. Since 3.15.0 the `HOST` alias is **not** fully equivalent: shells commonly set `HOST` to the machine name without the operator knowing, so when the narrowing condition above holds it wins over an inherited `HOST` (logged as `bind_host_from_HOST_env_overridden`). Set `BIND_HOST` explicitly, or configure a service token, to expose the write face. |
 | `MODEL_GATEWAY_BASEURL` | **no default** | OpenAI-compatible gateway base URL (without `/chat/completions`). **No factory default** (S-623): every route that rides the openai-compatible lane must resolve to an explicit endpoint — the model's own catalog `baseUrl`, or this knob — else the server refuses to boot, naming the models and printing the explicit local spelling (`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`). An Anthropic-only deployment may leave it unset. Setting `MODEL_GATEWAY_FALLBACK_URLS` without it is refused too |
-| `MODEL_ID` | **required unless a catalog supplies the default** | Default model id — **no factory default since 3.0.0**. Since 7.101.0 (S-705) the check runs **after** the catalog is applied: `MODEL_ID` **or** a usable catalog default (`config.d/models.json` / the config center) is enough; with neither the server refuses to boot (`config.default_model_missing`, naming both ways out). The old baked-in default was an internal-only model name, so every external deployment failed later and further from the cause: a gateway `400` plus a cascade of title-hook warnings |
+| `MODEL_ID` | **required unless a catalog supplies the default** | Default model id — **no factory default since 3.0.0**. Since 7.101.0 (S-705) the check runs **after** the catalog is applied: `MODEL_ID` **or** a usable catalog default (`config.d/models.json` / the web-admin) is enough; with neither the server refuses to boot (`config.default_model_missing`, naming both ways out). The old baked-in default was an internal-only model name, so every external deployment failed later and further from the cause: a gateway `400` plus a cascade of title-hook warnings |
 | `MODEL_API_KEY` | — | Gateway API key (optional). Pairs only with `MODEL_GATEWAY_BASEURL`: with no gateway it is not loaded and sent nowhere |
 | `SERVICE_AUTH_TOKEN` | — | Callers must send `Authorization: Bearer <token>` |
 | `DB_BACKEND` | `local`* | `mysql` (any MySQL-protocol DB: MySQL/TiDB/MariaDB) / `pg` (PostgreSQL) / `local` (file-backed, no DB) / `memory` (explicit in-memory: nothing survives a restart, durable-runs faces 501). *Bare boot (no DB env at all) defaults to `local` so a single-user machine keeps its runs across restarts; any SQL signal (`SESSION_BACKEND` or `MYSQL_/PG_HOST`) keeps the `mysql` engine default, and `REQUIRE_PRINCIPAL=true` bare boots stay `memory`. (`TIDB_HOST`/`_PORT`/`_USER`/`_PASSWORD`/`_DATABASE`/`_POOL_SIZE` are retired names, not an alias — since 5.0.0 setting any of them refuses to boot, pointing at the `MYSQL_*` replacement; TiDB itself connects fine through `MYSQL_*`, since it speaks the MySQL protocol.) (the local file store has no tenant isolation — a warning says so). A DEFAULT-derived `local` that cannot create its data root degrades to memory with a warning + the `store_backend_degraded` gauge; an EXPLICIT `DB_BACKEND=local` fails loud instead. Setting `mysql`/`pg` explicitly also switches sessions to durable |
@@ -269,7 +269,7 @@ One row per endpoint family (not exhaustive):
 | [sema-agent/sema-core](https://github.com/sema-agent/sema-core) | The agent engine, as a library — published as [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core) |
 | [sema-agent/sema-sdk](https://github.com/sema-agent/sema-sdk) | Official TypeScript SDK for this server (`@sema-agent/sdk`) |
 | [sema-agent/sema-deploy](https://github.com/sema-agent/sema-deploy) | One-command deployment — docker compose or k8s (helm), single machine to multi-node HA |
-| [sema-agent/sema-web](https://github.com/sema-agent/sema-web) | Self-hosted web console + registry/config center + orchestrator |
+| [sema-agent/sema-web-admin](https://github.com/sema-agent/sema-web-admin) | web-admin: self-hosted web console, config control plane and orchestrator |
 
 ## Versioning
 

package/README.zh-CN.md

@@ -201,7 +201,7 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 > `/v1/sessions/:id/sync/*`(逐字 durable log 出入)——这两面是**原形**——**发往「该 run 实际选中的模型路由」的请求体是工具结果原文**。
 > 这条路由不止 `MODEL_GATEWAY_BASEURL` 一根:还可能是备用网关列表(`MODEL_GATEWAY_FALLBACK_URLS`)、
 > `provider:"anthropic"` 模型的独立直连路由(缺省根 `https://api.anthropic.com`,除非显式配
-> `ANTHROPIC_BASEURL`)、或配置中心可对单个目录模型下发的 per-model `baseUrl` 覆盖(见
+> `ANTHROPIC_BASEURL`)、或 web-admin 可对单个目录模型下发的 per-model `baseUrl` 覆盖(见
 > `docs/ARCHITECTURE.md` §10)。要让内容不出机器,靠**读侧敏感路径门**,并核对**本部署会被选中的每一条
 > 路由**都指向自己控制的基础设施——只把默认网关 env 指到私有端点是不够的。验法见 `USAGE.md` §9.6。
 
@@ -232,7 +232,7 @@ Web search(部署 env `WEB_SEARCH_*` 七键、per-request `settings.webSearch`
 | [sema-agent/sema-core](https://github.com/sema-agent/sema-core) | 智能体引擎,以库的形式发布 —— [`@sema-agent/core`](https://www.npmjs.com/package/@sema-agent/core) |
 | [sema-agent/sema-sdk](https://github.com/sema-agent/sema-sdk) | 本服务的官方 TypeScript SDK(`@sema-agent/sdk`) |
 | [sema-agent/sema-deploy](https://github.com/sema-agent/sema-deploy) | 一键部署 —— docker compose 或 k8s(helm),单机到多机 HA |
-| [sema-agent/sema-web](https://github.com/sema-agent/sema-web) | 自托管网页控制台 + registry/配置中心 + orchestrator |
+| [sema-agent/sema-web-admin](https://github.com/sema-agent/sema-web-admin) | web-admin:自托管网页控制台、配置控制面与 orchestrator |
 
 ## 版本策略