@sema-agent/server 7.122.0 → 7.124.0

package/MIGRATION.md

@@ -7,6 +7,192 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 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 条。
+
+1. **`GET /v1/models` 顶层新键 `droppedEntries`**(additive,恒在场;零条 = `[]`,键缺席 = 更早的 server):升级零动作。把未知顶层键当错误的严格解析器要放行该键。
+2. **LKG 信封 `formatVersion` 2 → 3**(被丢目录条目的记录随 effective 一起落盘,墓碑与 `droppedEntries` 读同一份)。**升级**:启动时读回 7.122.0 及以前写的文件(2)一次性迁移,运维日志 `config_lkg_migrated` 一行;迁移来的文件 **ETag 不复用** ⇒ 中心可达后第一拍是整拉(不是 304),记录随即补全;中心断着的那段时间 `droppedEntries` 只列旧文件记下的那几行。**回滚到 7.122.0 及以前**:那些进程读不懂 3,把这份 LKG 当不可用(运维日志 `config_lkg_unusable` 一行)—— 中心可达则照常拉取、断着则 env 兜底,下一份干净候选按旧格式重写;回滚前确认中心可达,或删掉 LKG 文件让下一次拉取重写。迁移臂在本版发布 30 天后的版本删除。
+3. **`@sema-agent/settings-schema` 9.0.0 → 10.1.1**:写入校验在串中**任意位置**认私钥 PEM 头(此前只认串首),读侧同一套 schema ⇒ **存量**配置里自由文本位(目录条目的 `extraBody` / `compat` / `headers` / `baseUrl`、mcp 的 `url` / `command` / `args` 等)夹着私钥 PEM 头的:可降级域(`models` / `mcp` / `plugins` …)那一条在读腿被逐条丢掉(目录条目出现在 `GET /v1/models.droppedEntries`,原因 `entry-schema-invalid`;其余域的被丢条目只进 `config_entry_dropped` 日志行);gate 域(`workers` / `entitlement` …)整域读拒 —— 读拒发生在拉取段(读候选即拒),与「源不可达」走同一臂、同一事件名(与 7.122.0 及以前任何 gate 域坏形同一行):**起服**时运维行 `config_source_unreachable_using_env { source:"remote", err:<schema 诊断,带字段路径> }`,随后按 LKG → env 兜底(盘上有干净 LKG 就从它起服,运维行 `config_loaded_lkg`,`/v1/models` 与 `droppedEntries` 是 LKG 那一代;没有才走 env,此时 `droppedEntries:[]`);**运行中刷新**时运维行 `sema_registry_refresh_failed`,ETag 不前进、正在服务的那一代保持不变,下一拍重拉同一份候选。两行都不点名出错的域,`err` 里的字段路径是唯一线索。升级前把私钥移出配置串(引用 env 名或密封托管)并轮换那把密钥。
+4. **`SEMA_CONFIG_DIR` 不要设成工作目录本身或它的祖先**(引擎 7.46.0 起一直如此,7.120.0 节第 3 条的另一面;本版零代码改动,补记一条此前没写的事实):引擎内建写保护表里的 `.sema` 行不只守家目录下的 `~/.sema`,
+   也被放在声明的配置根下 —— 根**之内任何路径**(不止配置文件)的写都要过 `write_protection` 一问。所以配置根是项目的祖先时(容器里 `SEMA_CONFIG_DIR=/workspace` 而项目在 `/workspace/proj`、直接设成 `HOME`、或设成项目目录本身),
+   项目里的每一次写(`Write` / `Edit` / `NotebookEdit`)都出这一张卡:allow 规则清不掉它(请求 `settings.permissions.allow`、`APPROVAL_GRANT`、持久规则同),`acceptEdits` 不放,`dontAsk` 拒;无人值守腿(leader、无终端的 `run-local`)的作答集只有 `ordinary` 类、这一类不在其中 ⇒ 拒(leader 配了耐久审批的部署上改为停驻,等人经 `/decide` 答);
+   只有 `bypassPermissions` 放行(托管部署上请求这一档另受 `TASK_WRITE_FACE_ESCALATION` 约束)。**起服不报、首条任务也不报**:本服务不拿配置根与工作目录比,引擎只验它是已存在的绝对目录 —— 第一次知道是第一次写。
+   **出路**:把配置根指到项目之外的专用目录(不设即缺省 `~/.sema`;`/workspace/.cfg` 一类不含项目的目录也行)。LKG(`config-lkg-*.json`)、skill 缓存(`skill-cache/`)、scheduler 共享店(`scheduled_tasks.json`)的缺省位置随配置根走,
+   改根不会替你搬旧文件 —— 要保留 scheduler 共享店就手动把 `scheduled_tasks.json` 搬过去。确实要保留祖先形配置根的:`WRITE_PROTECTED_TABLE_REPLACE` 给一张不含 `.sema` 行的表可去掉这一问,代价是 `~/.sema` 下的这一问一并没了。
+5. **勘误(7.122.0 节第 7 条;已发节不改字节):`AUTONOMY=plan` 下「一次写在有人可答时出一张卡(人批了就写)」的射程是写面根围栏之内,不是任意路径**。批准只清模式门(plan 门那一问);
+   引擎文件工具(`Write` / `Edit` / `NotebookEdit`)自己的根围栏不受批准影响,围栏 = 任务 `cwd` + 引擎宣告的可写目录(记忆目录、会话 scratchpad)+ 请求的 `additionalDirectories`。
+   围栏外的路径,卡批了也不写:工具答错误,`tool_end.errorCode` = `path_not_in_root`,拒句 `… resolves outside the allowed root(s) (<根清单>); access denied.` 点名这些根。
+   把 7.122.0 那句读成「批了就写,不论路径」的壳 —— 例如计划文件的路径在工作目录与上述目录之外的(默认配置根 `~/.sema` 之下就是一例)—— 要么让路径落进围栏(会话 scratchpad 或请求的 `additionalDirectories`),要么别指望那次写成功。
+   写面声明为 open 的任务不受这道围栏约束(`bypassPermissions` 派生的开放写面;`GET /v1/capabilities` 的 `taskWriteFaceOpen` 披露本部署认不认)。本版零行为变化,这一条只改文字。
+6. **补记(7.122.0 节第 6 条):订阅流的排空终帧 `error{ errorCode:"draining" }` 是连接面的信号,不是 run 状态信号**(零行为变化,只补文字)。排空进入那一拍,服务端对**每一条**打开着的只读订阅流发这一帧
+   (`/v1/approvals/stream`、`/v1/fleet/stream`、`/v1/sessions/:id/events`、`/v1/runs/:id/events`、`/v1/tasks/:id/stream`、`/v1/runs/:id/subagents/:sub/stream`、`/v1/workflows/:id/stream`、`/v1/images/bakes/:id/events`),
+   与流所观察的 run / 审批此刻在什么状态无关 —— 在跑的、停在一张审批卡上的、已终局的收到同一帧,帧里只有 `type` / `errorCode` / `message`,不带任何 run 或审批的状态。消费端:收到它 ⇒ 重连到替换实例;
+   **不要**据此判「run 已续跑 / 已动过 / 卡已决」,不要因此收掉在等的审批卡、也不要把重连前持住的停驻标当已决丢弃;按 `errorCode` 分支,别把 `error` 帧型整类当作 run 状态的信号。
+   要知道 run 或审批此刻的状态,重连之后读 `GET /v1/runs/:id` / `GET /v1/approvals`。
+7. **会话规则写口对「不是一列非空字符串」的桶答 400**(`PUT /v1/sessions/:id/policy`、`POST /v1/sessions/:id/sync/import` 的 `policy` 面;引擎 7.48.0 的规则表判官):
+   空串 / 纯空白项(`toolDeny: [""]`、`commandDeny: ["  "]`、`toolAllow: ["Read", ""]`、`allowDirs: ["/work", "\t"]`)此前存得进(一条什么都不匹配的规则),现在
+   `400 request.field_invalid`,店里零字节;句子是引擎的,点名桶与值类型(`session rules <桶> must be an array of strings, got … — a rule list is written as a list of names (["rm"], not "rm")`)。
+   修前就是 400 的裸字符串 / `null` / 混入非字符串三形码不变、句子换成同一句(按码匹配的不受影响)。**存量**:旧版写下的空串项行照常读出、照常执行;
+   非 operator 想删掉空串 **deny** 项会被收紧门判成放宽(403 `loosen_forbidden`)—— 由运营方(operator)`PUT` 一份干净的规则体,或删会话。
+   2c 推送遇到云端那一把键上是这种存量行 ⇒ 照常写:operator 推送照写(干净规则替换存量行,清它的另一条路);非 operator 推送若去掉了空串 **deny** 项 ⇒ 403 `loosen_forbidden`
+   (与 7.122.0 同答;装上引擎 7.48.0 而不改本服务时这里是 500)。推送体自己的记录里带空串项 ⇒ Phase A 400(先在源端清掉那一项再推)。
+8. **工具段为空的协议名(`mcp__<server>__` / `a2a__<peer>__`)由引擎判官判**(判词 `unmintable_segment`,与对端段铸不出的名字同一判):
+   会话规则两写口的拒码 **`400 request.field_invalid` → `400 rules.legacy_tool_name`**(体带 `field` / `name` / `verdict: "unmintable_segment"` / `guidance`);
+   请求 `settings.permissions.allow` 与技能 `allowedTools` 里它**由拒(422 / 400)变收**,引擎在开跑时读成 `tool_name` 并通告(`permission.allowed_tool_not_granted`);
+   技能 `disallowedTools` 里它仍 400 `request.field_invalid`(句子换成引擎条目读法的那一句);运维 `APPROVAL_*` 四表、中心下发名表、请求 deny / ask 桶照拒,指引换成引擎的句子。
+   **存量**:7.115.x 及以前写进会话规则的这种名字,本版起每一跑在准备阶段拒(`config.legacy_tool_name`,一个 turn 不跑;同步提交腿 200 + failed 体)——
+   7.122.0 及以前那条规则什么都不守、run 照跑。属主自己删得掉(删一条非现行 deny 不算放宽)。**出路**:写 `mcp__<server>`(整台服务器)或 `mcp__<server>__<tool>`(一只工具)。
+9. **`/` 开头的读拒行根锚定**(引擎 7.48.0):只守那一个绝对位置,不再按尾段在任意深度匹配;路径经符号链接的目录时,引擎在每次准备时把这一行沿链放置到字面头真正通向的地方
+   (链接目标同样被拒)。`CONFIG_LKG_PATH` 派生的读拒行收成一条 = 覆写的绝对路径(此前两条:写下的路径 + 本服务解出的落点);用户仓里同尾的路径读得到、Grep 也找得到;
+   `permission.read_deny_unapplied` 的 `detail.rows` 里部署 LKG 路径由两行变一行。运维 `READ_DENY_PATTERNS` 里 `/` 开头的行同此 —— **要任意深度就去掉前导 `/`**。
+   **回滚到 7.122.0 及以前**:本版(引擎 7.48.0)写出的检查点带 `/` 开头的读拒行时,7.47.x 引擎的工作者恢复它即拒(`checkpoint.invalid_outcome`,原因 `read_face_damaged`),
+   检查点停泊不动 —— 回滚前先在本版上续跑完、或确认没有这类停泊任务(部署设了 `CONFIG_LKG_PATH`、或运维读拒行以 `/` 开头,就有这类行)。
+10. **shell 读法:收窄五条、放宽四条**(引擎 7.48.0 披露为可否决;本服务零改码,三种放行形 —— 无 allow 的 `default`、请求 `settings.permissions.allow: ["Bash"]`、
+   `bypassPermissions` —— 原样过境)。**多问**:`P=rm; $P -rf <根>` 这类经变量拼出的危险删除在 allow 与 bypass 下也是一张 `dangerous_delete` 卡;
+   **流喂 / 进程替换的 shell 一律 `dangerous_delete`,无害文本也是**(`ls | xargs -I{} sh -c 'echo {}'`、`bash <(printf 'echo hi')`,三种放行形各一张卡)。
+   无人值守腿(leader 各条腿、无终端的 `run-local`)的作答集只有 `ordinary` ⇒ 这些卡没人答 ⇒ 拒(leader 配了耐久审批则停驻等 `/decide`)—— 跑在这些腿上的脚本里用
+   `xargs … sh -c` / `bash <(…)` 驱动 shell 循环的,先改成不经流喂 shell 的写法。**少问**(只在请求 allow `Bash` 与 `bypassPermissions` 下;`default` 照问):
+   未加引号的多词值(`X='a b'; cat $X`)、名字取多个值后经 `su -c "$X"`、嵌套循环、带通配符的未引号值不再各出一张卡。
+
+11. **`GET /v1/capabilities` 的 `permissionModeAuto.reason` 闭集加一词 `operator_floor`**(additive;改正 7.122.0 节第 7 条「能力面答 `reason:"mode_not_auto"`」那半句,已发节不改字节)。
+   `AUTONOMY=plan` 的部署上,意图(查询串 `?permissionMode=`,缺席按 auto)被入口地板改成了别的词 ⇒ `reason:"operator_floor"`(此前 `mode_not_auto`):意图缺席、`auto`,以及任何比 `plan` 松的词
+   (`default` / `acceptEdits` / `bypassPermissions` / `dontAsk`)都是这一词;意图本身是 `plan` ⇒ 仍是 `mode_not_auto`。没有地板的部署读数不变。`armed` 不变。
+   消费端:按 `reason` 指路的壳(`sema doctor permissions` 一类)给 `operator_floor` 一条「运维的 `AUTONOMY=plan` 让每个任务从 plan 起步,改请求的词到不了 auto;找运维换档」的出路;
+   对 `reason` 写穷尽 switch 的类型面加这一臂,未知词照旧按「未武装」兜底。
+
 ## 7.122.0 —— 配置型 URL 拒句零回显(两种模型路由形改拒启)· 排空口的期限有上界(`FLEET_LEASE_OUTAGE_MAX_MS`)· 服务租约能力位撤掉再宣告不重置失联钟 · 改路停驻的审批在停驻当拍收口(迟到作答的 202 写真)· 排空不被只读订阅流挂住 · plan 模式一只判官(运维 `AUTONOMY=plan` = 提交入口的模式词地板)
 
 **升级前必读**:按拒句文字匹配配置拒启的脚本改按拒启码匹配(第 1 条);模型路由三键里没有 `ftp://` 一类非 http(s) 根(被消费的根修前已拒启,不被消费的那一根升级后也拒启)、没有以空 `#` 结尾的根(第 2 条,升级后拒启);
@@ -1442,6 +1628,29 @@ wire 面(同步提交撞 park 的 200 体、`GET /v1/runs/:id` 行形、同一
   另外六名新出现在 `exact-name` 桶。
 - 零 wire 键、零 DDL。
 
+## 7.103.1 —— 补记:ssh / k8s / adb 三条远端车道的工作目录进不去时,命令不再在远端起始目录里照跑(改为不执行 + 一句诊断)
+
+> 这一变化随 7.103.1 发出,当时本文件没有写。7.103.1 的另一块(git 配置组的判定改归引擎)见 7.103.0 的 core 7.33.1 提货一节里标 `⤷ 7.103.1` 的条目。
+
+1. **远端车道(`REMOTE_EXEC=ssh` / `k8s` / `adb`)的命令前面拼着「先进工作目录」;进不去时,命令现在一段也不跑**。
+   · **修前(≤7.103.0)**:交给远端 shell 的是 `cd '<目录>' && export K='v'; <命令>` —— `&&` 只绑住第一只 `export`,目录不存在 / 进不去 / 不是目录时,`;` 之后的命令**照样在远端 shell 的起始目录里跑**
+     (ssh 为目标账户的登录目录),只少了第一只 `export`;引擎的 `Bash` 工具带 `env`(`PWD`)调用,所以模型命令走的就是这一形。没有 `env` 的调用方形是 `cd … && <命令>`,只短路命令的第一段:`a; b`、`a || b`、多行命令的后半同样照跑。
+     结果是命令在**错的目录**里「成功」了(退出码是命令自己的,通常 0),没有任何一行告诉你工作目录没进去。
+   · **现在(7.103.1 起)**:`cd '<目录>' || { echo '<守卫行>' >&2; exit 125; }; …` —— 进不去 ⇒ 命令**不执行**。缓冲执行面(模型的 `Bash`、带工作目录的 git 探针等)把它报成执行层的 `spawn_error`(与 host 车道的 spawn 失败同码同句族),
+     句子 `<ssh|k8s|adb> spawn failed: sema: working directory unavailable: <目录> — the command did not run (<远端 cd 自己的报错>)`。引擎的 `Bash` 工具据此判目录是不是真没了:
+     模型自己 `cd` 进去又删掉的目录 ⇒ 工作目录复位到任务根,答「… The working directory has been reset to <根>; re-run your command (cd first if you need a different directory).」,模型重发即可;
+     任务根本身没了 ⇒ 答「… no longer exist … this task cannot recover its working tree」,无从复位。目录在但**进不去**(权限)时引擎不判死目录、不复位,模型只看到 `command did not run (spawn_error)` 那一句,
+     本轮后续前台 `Bash` 都是它 —— 修目录权限(与 host 车道同形)。
+   · **流式执行与后台任务不走 `spawn_error`**:cd 失败时交出退出码 125 + stderr 一行 `sema: working directory unavailable [<nonce>]: <目录> (cd failed; command not run)`(命令自己退 125 的不会被误认:缓冲面在 cd 成功之后、命令之前会往 stderr 写一行
+     `sema: command started [<同一 nonce>]`,服务在交出之前剥掉它,没见到这一行才算「命令没跑」;文件面探针只用绝对路径、不进工作目录,工作目录进不去不影响它们答真话)。
+   · **谁会看到**:远端工作目录被删 / 挂载没起 / 权限不对的部署 —— 以前这些命令在别的目录里「跑成功」,现在是显式失败。按退出码判成败、或把命令输出当数据的脚本要知道这一点。
+   · **部署前提**:命令串用了 `{ …; }` 组命令,**远端 shell 须兼容 POSIX sh**。ssh 车道走目标账户的**登录 shell**(`-c`):登录 shell 是 csh / tcsh(fish 看版本)的账户整条语法错、命令一条也不跑
+     (修前无 `env` 的 `cd 'X' && cmd` 在 csh 里能跑)—— 给 agent 用的账户把登录 shell 设成 `/bin/sh` / bash / zsh / dash。k8s 走容器里的 `sh -c`,adb 走设备的 `sh`。
+   · **出路**:在远端建好并能进工作目录 —— `K8S_MOUNT_PATH`(缺省 `/workspace`)在容器里存在;`ADB_MOUNT_PATH`(缺省 `/data/local/tmp`)在设备上存在且可进;`SSH_MOUNT_PATH` 在目标机上存在且可进
+     (不设 ⇒ 调用方没给工作目录的那几次不进目录、没有守卫)。
+   · **不在本条范围**:`local-docker` 与 `e2b` 两条车道不经这一组装,它们的死工作目录报法本节未核。
+   · 零 wire 键、零 DDL、零新旋钮。
+
 ## 7.103.0(车OY 部分)—— server 进程出网认 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`(S-776)
 
 - **出网跟着代理变量走**:server 进程(HTTP 服务与 `run-local`)的出网 —— 引擎 → 网关、中心拉取 / 公告 / 凭证续签、WebSearch、对象存储、OTLP … ——

package/README.md

@@ -131,6 +131,11 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   Build-time tools (e.g. a catalog editor) read two allowlists from the package root instead of hand-copying them: `RETIRED_ENVS` (the retired-env
   tombstones) and, since 7.110.0, `CATALOG_ENTRY_HEADER_LANES` / `CATALOG_ENTRY_HEADER_NAMES` (+ type `CatalogEntryHeaderName`) — the closed allowlist of
   model-catalog entry `headers` and the API line that reads each name. Both are frozen, the very objects the server judges with.
+  A shell or package that must know **before the engine starts** whether the model route would stop it imports `judgeModelRouteGap(env)`
+  (pure; takes an env snapshot) from the package root: `{ gap: "endpoint_missing" | "lane_credential_missing" | "none" }`, plus `code` and the
+  refusal sentence `reason` when there is a gap. It is the very function `loadConfig()` judges the model route with — not a copy of it —
+  so its reading and the start-up refusal are the same by construction. `none` says the route gap is absent, not that the engine will start
+  (other invariants refuse with their own codes).
 - **Bundled binaries**: the package ships two `bin` entries — `run-local` (single-machine local
   runner) and `sema-up` (deployment bootstrap script).
   - `run-local` boots the same engine in-process, runs one task from the CLI objective, prints the
@@ -180,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 |
@@ -264,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

@@ -114,6 +114,9 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
   `assertExecutionLaneInvariants(config)` 是同一份判据,不做 `config.d/remote-exec.json` 覆写。
   构建期工具(如目录编辑页)从包根取两张表、不手抄:`RETIRED_ENVS`(退役 env 墓碑)与 7.110.0 起的 `CATALOG_ENTRY_HEADER_LANES` /
   `CATALOG_ENTRY_HEADER_NAMES`(+ 型 `CatalogEntryHeaderName`)—— 模型目录条目 `headers` 的闭集白名单及读每个名字的线路。两者都冻结,就是服务端自己判据用的那一只。
+  壳 / 包要在**引擎起来之前**知道模型路由会不会让它起不来,从包根调 `judgeModelRouteGap(env)`(纯函数,吃一份 env 快照):
+  `{ gap: "endpoint_missing" | "lane_credential_missing" | "none" }`,有缺口时另带 `code` 与拒启句 `reason`。它就是 `loadConfig()` 判模型路由用的那一只函数
+  (不是它的副本),所以读数与起服拒启同源。`none` 只说路由缺口不在,不担保起得来(别的不变量各自带码拒启)。
 - **随包二进制**:包内带两个 `bin` —— `run-local`(单机本地 runner)与
   `sema-up`(部署引导脚本)。
   - `run-local` 在进程内启同一套引擎,把命令行给的目标跑完一次、打印结果、退出——没有 HTTP 服务,
@@ -198,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。
 
@@ -229,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 |
 
 ## 版本策略