@sema-agent/server 7.125.1 → 7.126.0

package/MIGRATION.md

@@ -7,6 +7,201 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.126.0 —— 🔴 会话 id 只收 canonical uuid(提交口 / A2A / run-local;自选名改成自留映射)· 🔴 团队编排面退役(请求键 `council` `debate` / `discuss` 场景 / `councilRuns`,零别名)· 🔴 角色词六个 · 🔴 审批卡词 `contentKind` → `approvalCard` · 🔴 `allowTools` 未知名拒跑 · 存量 SQL 库:`task_run` 加一列(幂等体指纹)+ 新表 `workspace_space_commit`(建表腿自动;期限列随行)· 会话删除 / 留存 sweep 回收空间快照对象(桶生命周期规则只作兜底)· 一次性迁移 M1–M3 退役:从没在 7.125.x 起过服的旧库起服即拒 ⇒ 先过 7.125.x 一次 · `WORKSPACE_PERSIST` 缺省 `off` → `space` · 记忆店根搬家 ⇒ 拒启 · 远端车道相对 `cd` 后删除问人 · 升级序:web-admin 先(council 键退役)、再 server;核心 7.49.5 / settings-schema 12.2.1 两包精确钉
+
+1. **订正 7.125.0 节第 4 条(文字订正,行为不变)**:`PATCH /v1/sessions/:id` 与 2c 导入的 `title` 除 1–120 字符与拒 C0 外,**首尾空白也拒**:400 `request.field_invalid`「title must not start or end with whitespace」(先于 C0 判;服务端不代为 trim)。客户端在送出前自行 trim;7.125.0 节第 4 条与随包 USAGE 漏写了这一句,契约 §20 一直写着。
+
+2. **补写 7.125.0 节第 15 条的消费方读法(文字补充,行为不变)**:`GET /v1/fleet/stream?session=<会话 id>` 自 7.125.0 起同时带回**这条会话发起的顶层 run 行**与它的**前台子代行**(此前键错,顶层 run 行被滤掉)。两种行在同一张表里,靠行上的位区分,不靠「在不在流里」:顶层 run 行 **`parentId` 缺席**;子代行 `parentId` = 父行 id,且带 `agentType` / `agentName`;后台与否看 `status` 与引擎自己的后台登记,**不要把流里每一行都当成活跃后台任务**(一个消费端在引擎换代路径上这样读,把前台这一轮宣告成「被本地引擎重启杀掉」并唤醒模型)。契约 H.3 的行型一直如此,本条只是把读法写到升级面上。
+
+3. **提交口幂等 = 同一调用方、同一键、同一请求:同键换体 ⇒ `409 conflict.idempotency_payload_mismatch`(行为变更 + 存量表要加一列;契约 §0.7 / 附录 A.1)**。
+   `POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs` 带 `Idempotency-Key` 时,账本行同时记下绑定这把键的那次请求的体指纹(收到的 JSON 体按键递归排序、去掉 `taskId`,头不进)。
+   同键同体 ⇒ 与之前逐字同;**同键异体 ⇒ 409 新码**(体 `{ error, errorCode }`,不回显键与那一行),不回放首发、不建新行、那一行不动 —— 此前回的是首发那条 run 的回执。
+   - **谁受伤**:把「同键换体」当重试的客户端 —— 重试时重新序列化把体改了(多 / 少一个键、塞了每次都变的字段、数组换了序)⇒ 409。**做法**:重试原样重发同一份体(键序无所谓);新请求换新键。
+     按 `errorCode` 判:`conflict.idempotency_payload_mismatch` ≠ `conflict.run_exists`(后者是「那一行你读不到 / 钥匙指向别的行」,先于本码判)。
+   - **流式腿**:进门判出 ⇒ JSON 409、不开流;开流之后才撞上 ⇒ 终帧 `done.result = { status: "failed", errorCode: "conflict.idempotency_payload_mismatch", errorMessage }`。
+   - **不变的**:读口 `GET /v1/runs?idempotencyKey=` 不比体;只带 `body.taskId`、不带 `Idempotency-Key` 的提交,或按 `taskId` 命中而带的是另一把键,都不比体(指纹属于绑定那一行的那把键);A2A `message/send`(键里就是消息内容)、`POST /v1/leader`、镜像烘焙。
+   - **存量 `task_run` 表(MySQL 协议 / PostgreSQL)要加一列**:没加就起服 ⇒ **拒启** `config.schema_mismatch`,拒句点名 `task_run` 缺 `idem_body_fingerprint` 并给出那一句。
+     ① **原地加列(推荐,零数据丢失)**:`ALTER TABLE task_run ADD COLUMN idem_body_fingerprint VARCHAR(64) NULL;`(PostgreSQL:`ALTER TABLE task_run ADD COLUMN idem_body_fingerprint VARCHAR(64) COLLATE "C";`),
+     再起本版。**先升库、再升副本**(加了列的库上,旧副本重启会把它看成多出的列而拒启)。② 重建:与 7.125.0 节第 8 条同四步。
+     存量行的指纹为 NULL:同键第一次再投放行并记下这次的体指纹,之后换体才 409(升级窗里对旧键的第一次重投不会被误拒)。
+   - `DB_BACKEND=local` 零动作(指纹随 `run.json` 落盘,旧文件读作「没有」,同上一句);内存形零动作。
+
+4. **`settings.hooks` 工具事件的正则形 matcher:提交时求值超时 ⇒ `400 request.field_invalid`(行为变更;契约附录 B「`settings.hooks` 的工具事件 matcher」一节)**。
+   此前一次提交里所有正则形 matcher 共用一份 `100 ms` 预算,用尽 ⇒ 照旧受理(`202`)—— 同一份设置在忙机上偶尔被收下、闲机上恒 400,结局随机器负载翻转。现在每只 matcher 的每次求值各一份固定的 `1 000 ms`(不共享、不读钟),
+   超时 ⇒ 确定的 `400`,体 `field: "settings.hooks"` + `detail: { reason: "over_budget", event, groupIndex, budgetMs }`,拒句点名事件 / 组下标 / 预算;`over_budget` 的放行臂与它的 fail-open 登记原因词退役
+   (`server.hooks.matcher-unjudged` 的 `reason` 只剩 `oversize`;`invalid_regex` 同批改拒,见第 19 条)。
+   - **谁受伤**:提交里带「灾难回溯」正则形 matcher 的客户端(如 `(.*)*x` 一类嵌套重复)—— 此前被收下(预算用尽 ⇒ 未判受理),现在恒 400。这类 matcher 在运行期每次工具调用都会卡住事件循环,放行本就是把坏配置推迟成运行期卡死。**做法**:改成工具名列表(`A|B`)或去掉嵌套重复。
+   - **体形同批 additive**:`400` 体的 `detail` 按 `detail.reason` 分形 —— 既有的「选中别名而选不中正名」形多一个 `reason: "dead_alias"` 键(其余三键、句子逐字不变),按 `field === "settings.hooks"` 分流的消费方不受影响;要区分两种拒就读 `detail.reason`,不要解析句子。
+   - **不变的**:多租户车道(`settings.hooks` 整只被忽略)零调用方正则执行;超 `8 192` 字符不读;续跑重放不判(编不过的正则见第 19 条)。
+
+5. **dev-open 部署上单会话面不再按自报的主体头答 404(行为变更;契约 §0.5)**。没配 service token、没配只读 trace token、没开 `REQUIRE_PRINCIPAL` 的部署上,
+   `GET /v1/sessions/:id` · `…/head` · `…/events` · `…/memory-status` · `POST …/memory/erase` · `PATCH /v1/sessions/:id` · `GET …/background` · `POST …/background/stop` · `POST …/mcp/reconnect`
+   与会话列表(`GET /v1/sessions`,一向 fleet-wide)同读调用方:不钉任何人 —— 带别人的 `x-agent-principal`、或不带头,都读得到 / 改得到那只会话(此前 404);`GET …/mcp` 面板对这样的调用方也投 `lastLegMcp`。
+   - **谁受影响**:把 dev-open 上的主体头当隔离用的部署。它此前也不是(谁都能自报属主的头,列表也早把全部会话列给任何人)。**做法**:要隔离就设身份边界 ——
+     `SERVICE_AUTH_TOKEN` 加一层写主体头的网关,或 `REQUIRE_PRINCIPAL=true`;有身份边界的部署上各口的属主门不变,外人与「不存在」同码同串 404。
+   - **不变的**:规则口 `GET|PUT …/policy` 与 `POST …/notify`(会话属主在那里同时是存储键,照旧按头比)· run 面 · fork / delete / 同步(本来就与列表同读)。只接了中心登录令牌、上面三者都没配的部署同属 dev-open。
+
+6. **带事实的退役域(`runtime`)改走候选判官:日志与刷新口换形(行为变更;订正 7.124.0 节第 1 / 8 条与 7.125.0 节第 3 条里「`runtime` 域是读腿整包拒、拉取失败」的说法)**。
+   中心视图,或起服迁移够不着的本地 `config.d/runtime.json`(起服之后才出现的、或被起服迁移拒 / 失败而留在盘上的),还带着治理三闸 / 限额键 ⇒ 这份候选被整拒(与坏域同一条回落链:盘上 LKG → env),**不再**按「源不可达」处理;起服前就在盘上的 `runtime.json` 由起服的一次性迁移先搬走(治理三闸 → `governance.json`〔已有该文件则它赢〕、限额键 → `limits.json`〔文件里已有的键赢〕;之后删 `runtime.json`),不经判官。
+   - **日志**:起服不再出 `config_source_unreachable_using_env`、刷新不再出 `web_admin_refresh_failed` —— 换成一行 `config_candidate_rejected`(`domains` 点名 `runtime`,`errors[]` 那条 `reason: "retired_domain"`,
+     拒句点名一次性迁移 `SS-M1`;同一份候选只响一次)。`config_candidate_rejected.errors[]` 每条多一个键 `reason`(`domain_invalid` / `retired_domain`)。按旧事件名告警的规则改按这一行。
+   - **手动刷新口** `POST /v1/admin/config/refresh`:此前 `502 internal.config_refresh_failed`,现在 `200 { triggered:true, targetVersion, appliedVersion }`(被拒是判官的结论,拍跑完了)——看 `targetVersion ≠ appliedVersion` 认出。
+   - **`engineSignal`**:`configTargetVersion` 推进到被拒那一代(此前停在 LKG / env 那一代)⇒ 起服第一拍 `configTargetVersion ≠ configAppliedVersion` 就认得出。
+   - **出路不变**:中心侧把 web-admin 升到 settings-schema 11.x 迁数据;本地 `config.d` 由起服的一次性迁移改写,迁不动时 `npx @sema-agent/settings-schema migrate <config.d 目录>`。
+
+7. **引擎 7.49.5 + settings-schema 12.2.1(两包精确钉)—— 角色词收成引擎认的六个(BREAKING,升级序)**:`default` · `summarize` · `subagent` · `verifier` · `classifier` · `consolidate`。
+   `roles.team` / `roles.synthesize` / `roles.advisor` 三词删除。**先升中心(web-admin 到 settings-schema 12)再升本服务**:存量中心配置里的 `roles.team` / `roles.synthesize`
+   由 settings-schema 的一次性迁移 SS-M8 搬走;混版本窗里中心腿发来表外角色词 ⇒ 本服务丢掉那一条并打一行,句子指「把 web-admin 升到 settings-schema 12」。
+   side query `POST …/side-query` 带 `modelRole` 表外词(含 `advisor`,此前回落主模型)⇒ **400 `request.field_invalid`**,带了 `model` 也一样拒。**做法**:绑 `subagent` / `default`。
+
+8. **团队编排面退役(BREAKING,零别名)**:引擎 7.49.0 删了团队讨论运行时与内建命名 workflow,本服务不留第二份团队编排 —— 消费方的编译错 / 400 / 拒启就是通知。
+   - **场景 `discuss` 删除**:请求体 `scenario:"discuss"` ⇒ 400 `scenario_unknown`;中心把它指派给主体 ⇒ 该主体的 run 503 `state.scenario_assignment_unknown`;
+     `DEFAULT_SCENARIO=discuss` ⇒ **起服拒**。`GET /v1/capabilities` 的场景闭集少 `discuss`(工具名 `run_discussion` 同删)。
+   - **`code-review` 只剩直评一腿**:请求键 `council` / `debate` / `lenses` / `rounds` / `team` / `businessContext` ⇒ 400 未知键(工具 `run_council` 同删)。
+   - **包导出 `createCouncilTool` 删除**;`ScenarioDeps` 少 `handslessSubRunner` / `metrics` 两键(自建 `ScenarioDeps` 的嵌入方删掉这两键即可,tsc 会点名)。
+   - **`GET /metrics/summary` 少 `councilRuns` 键**;Prometheus 的 `council_runs_total` / `council_tokens` 同删 —— 按 v1 形解析这张表的看板先把这一键改成可缺。
+   - **中心的 `collab` 域照收、不执行**:每次应用打一行 `web_admin_collab_not_executed`(点名已发布且启用的模板 id);dry-run 行的 `collab.centerWouldRegister` 改名 `collab.notExecuted`。
+     多成员的活改成 Agent 子代 + 主模型综合,或在部署的 `workflow-scripts` 店里登记 Workflow 脚本(按名调用,`Workflow({ name })`)。
+   - **多租户墙钟只剩一个基值 2400s**(3600s 的「大任务」档只为 council / debate / discuss 而设);运维日志 `orchestration_routed.mode` 只剩 `single` / `supervisor`。
+
+9. **记忆店根搬了家 ⇒ 拒启(file 记忆后端)**:目录被搬走或换成指向别处的链接后,起服拒(码 `memory.target_outside_store`),拒句给出原路径、现路径与两条出路 ——
+   把目录放回原处,或在本服务目录里跑一次 `node --input-type=module -e 'import("@sema-agent/core").then(m => m.reanchorMemoryStoreRoot("<path>", { controlDir: "<controlDir>" }))'`
+   (两个坐标拒句逐字给出)后再起服。`MEMORY_ENGINE=off` / `MEMORY_ENGINE_BACKEND=pg|tidb` 不经这一判。
+
+10. **写目标的真落点读不出 ⇒ 有护行的面拒这次写(引擎一条律,所有权限模式含 bypassPermissions)**:执行环境答不出写目标解析到哪(链接跟不下去、环境报错 / 超时)时,
+   常开写保护表与敏感路径表一律拒(host 车道此前同样拒、只是拒词不同;答不出落点的远端车道此前按拼法判、可能放过)。修法 = 修那只执行环境(或去掉那条链接)。词改名:mandate / 问卡类 `write_protection_unresolved` → `target_unresolved`
+   (本服务 echo 引擎的词,不抄词表);运维通告 `config.write_protection_unresolved` → `config.path_view_unresolved`(`detail` 不变,按码告警的规则改名)。
+   本服务自己的数据根恒为豁免根(`MEMORY_ENGINE=off` 的部署也是),运维零动作。
+
+11. **远端执行车道(e2b / k8s / ssh / local-docker / adb / device)上的相对 `cd` 之后的删除会问人**:这些车道的命令跑在对方的环境里,本服务读不到它的 `CDPATH`,
+   如实报「不知道」⇒ `cd <相对名> && rm -rf …` 一类从放行变成一张审批卡;host 车道读自己组合的子进程环境,不受影响。做法:删除命令里写绝对路径(或接受那张卡)。
+
+12. **allow 名单里的路径形 / 域名形条目从此真授权(放宽)**:请求的 `settings.permissions.allow`、请求技能的 `allowed-tools`、部署的 `APPROVAL_GRANT` 里的
+   `Edit(src/**)` / `Read(//dir/**)` / `WebFetch(domain:example.com)` / `WebFetch(domain:*.example.com)` 现在按引擎的窄读法放行(此前读成空、照问);
+   `permission.allowed_tool_not_granted` 的原因词少 `path_pattern` / `domain` 两个。Bash 审批卡的编辑面仍不许铸出主机 / 子域授权(恒拒)。
+   **谁受伤**:靠「这类条目不生效」兜底的部署 —— 现在它们生效了,审一遍名单。
+
+13. **会话流多两个通告码**(`engine_notice`,受众用户):`route.finish_reason_unknown`(提供方用引擎读不懂的结束原因结束了一轮,回答可能不完整)·
+    `route.stream_end_ignored`(结束之后流又发来东西,之后的一律没进这一轮);运维日志多一码 `route.extra_body_reserved_dropped`(模型目录条目 `extraBody` 里被适配器剥掉的键,只有键名)。
+    按码白名单渲染的壳把两码加进表(契约附录 D.3)。
+
+14. **Agent 名字多三个保留词**:`team-lead` / `user` / `system`(任意大小写拼法)与 agent id 形的名字 ⇒ 拒(`name.reserved`),存量名册行里带这类名字的委派不能再唤醒;改名即可。
+
+15. **会话住客记号只读会话行(记忆引擎与 k8s 工作区空间同一读法)**:运维日志 `session_incarnation_unavailable` / `memory_session_incarnation_unknown` 两行退役
+    (装配期读口与按副本的登记簿一并删除;记忆引擎从 run 取得的会话上读住客)。SQL 会话行的化身格是空的 ⇒ 这只会话的 turn 响亮失败
+    `session.incarnation_missing`(此前按 id 绑定照跑;7.104.0 起的一次性迁移已为存量行补格,空格只可能来自手改库)—— 出路同拒句:重启一台 7.104.0+ 副本让迁移补格,或删这只会话。
+    k8s 车道 `workspace_space_unavailable` 多出 `reason`(只有 `incarnation_unknown` = 没有这只会话,从不带令牌);读住客**失败**不走这一行(见第 27 条);起服门在「会话店答不出住客 **或**没有店后端」时拒 `space`。
+    local 后端:同一只会话的打开在它的写锁里取住客格 —— 与同会话在飞的改名 / 导入 / 删除串行。
+
+16. **提交体新键 `allowTools`(引擎的可用性选择器,原样透传)· `excludeTools` 读同一文法 · 工具名表里的未知名拒跑(BREAKING 行为面)**:
+    这一 run 可用的工具 = 它挂的一切 ∩ `allowTools` − `excludeTools`(deny 赢),引擎开跑前一次算出;本服务不算补集、不过滤。
+    - **谁受伤**:① `excludeTools` 里写着本部署不挂的名字的调用方 —— 此前被忽略,现在开跑前拒 `config.tool_face_control`(同步腿 **400**,零 token);
+      ② 靠「`excludeTools:["Bash"]` 只卸引擎的 shell、保留一只别名也叫 `Bash` 的调用方工具」的写法 —— 别名现在也够得着,一并卸掉;③ `excludeTools` 里写 `*` 的 —— 拒。
+      **做法**:只列这台部署挂得出的名字;要卸引擎工具又留同名调用方工具,改写 `allowTools` 点名调用方工具。
+    - **新用法**:要「只给 `Read`」写 `allowTools:["Read"]`,不必再自己算补集(引擎自己的工具与 MCP 工具都在同一只选择器里);`[]` = 什么都不给。
+
+17. **子代 `agents[].allowTools` / `denyTools` 管子代可挂载的全部工具,未知名拒跑(BREAKING 行为面)**:引擎自己的工具(`Monitor` / `Artifact` / 记忆工具 …)与父的 MCP 挂载
+    都在两张表的管辖里(`denyTools:["Monitor"]` ⇒ 子代没有 `Monitor`;带 `allowTools` 的子代只剩点名的那几只与它这条腿的协议工具);
+    名单里没有任何工具答应的名字从「只告不拒」改「开跑前拒 `config.agent.unknown_tool`」。**做法**:名单里点名子代要用的每一只工具,删掉本部署不挂的名字。
+
+18. **计划审阅决断门受理 `decidedBy`(additive)**:`POST /v1/assistant/tasks/:id/plan_review` 收 `decidedBy`(`person` / `policy`;缺席 = `person`),读法与 `/decide` 同一只;
+    此前同一键 `400 request.body_shape`(`unsupportedKeys`)。直连门上带它 ⇒ `400 decided_by_not_in_proof`(与 `/decide` 同)。零动作。
+
+19. **`settings.hooks` 工具事件 matcher 正则编不过 ⇒ `400 request.field_invalid`(行为变更;契约附录 B)**:`detail: { reason: "invalid_regex", event, groupIndex }`,拒句点名
+    `settings.hooks.<event>[<groupIndex>].matcher`、原文与编译错误句。此前编不过的正则被收下(`202`),运行期那一组从不跑。
+    - **谁受伤**:提交里带编不过的工具事件正则 matcher 的客户端。**做法**:修正则,或改成工具名列表(`A|B`)。按 `detail.reason` 穷举读的消费方放行第三个词 `invalid_regex`。
+    - **不变的**:多租户车道零动作;续跑重放不判;写在非工具事件(StopFailure / PreCompact / PostCompact)上的坏 matcher 仍受理。
+
+20. **http 钩子 header 的 `$VAR` / `${VAR}` 展开改用契约包读法(行为变更;契约附录 B「`settings.hooks` 的 `http` 条目」)**:① `${NAME}` 开始展开;② 名字只认大写,
+    **小写名不再展开**(原样当文字发出);③ **名单(`allowedEnvVars`)外的引用置空**、**凭据名表里的名字一律置空**(此前留字面 / 照常展开);④ 每个 header 值剥 CR / LF / NUL;
+    ⑤ 名单内但钩子环境(净化 allowlist + `settings.env`)里没有值的名字展开成空串(此前留字面)。
+    - **谁受伤**:header 里用小写变量名、引用名单外变量、或点名凭据名表变量的 http 钩子。**做法**:变量改大写名(`settings.env` 与 `allowedEnvVars` 同改),或把名字加进 `allowedEnvVars`;
+      凭据名表里的名字不能经 http 钩子 header 发出,换一个普通名字。置空时日志一行 `hook_http_header_env_blanked`(名字与原因,不带值)。
+
+21. **受守卫表覆盖的写在执行环境答不出落点时被拒(车道披露,接第 10 条)**:执行环境一次瞬时失败(pod exec 超时、设备掉线、写门代理还没绑定本任务的沙箱)就是一次「读不出」,
+    受守的 `Write` / `Edit` / `NotebookEdit` 在每个权限模式都被拒(不出卡);重试那一次写即可。各车道答路径问题的能力见 USAGE「写目标的真落点读不出」一条。
+
+22. **审批卡词 `contentKind` → `approvalCard`(wire BREAKING,零别名)**:`GET /v1/approvals` 的 `pending[]` 行、`/v1/approvals/stream` 的 `pending` 帧、`livePending` 行的 `contentKind` 删;
+    同几处与活 `tool_approval` 帧带引擎铸的卡词 `approvalCard`(闭集八词)。**做法**:把 `row.contentKind === "content_ask"` 换成 `row.approvalCard === "question"`。
+    7.49.0 之前的引擎停驻、升级时还挂着的问答没有卡词:队列行不标问答(`approvalCard` 缺席),审批队列里把它**显示**成通用审批卡 —— 只是显示:决断口仍按工具名认问答,对这类停驻发不带 `body.answer` 的 approve 会被 `400` 拒并点名
+    (任务级决断口 `request.field_conflict`;停驻子代的决断口 `decide.parked_answer_required`)。壳对这类停驻必须按问答作答(`approve` 带 `answer`),拒绝照常(`deny`,不带 `answer`)。无人答、到期时被 SLA 拒扫(模型读到「拒」)而不是作废;
+    介意的话升级前把挂着的问答答完或拒掉(存量行补卡词的一次性迁移另登)。
+
+23. **委派子代的停驻卡按父的 scope 列(行为变更)**:同步子代的卡从 `irreversible` 桶(无 principal 部署)搬到父的 `durableApproval.scope`,与父的卡同列;行的 `sourceTaskId` 指子代。
+    按 `irreversible` 找子代卡的读者改按父的 scope 列。已知余项:同步子代卡经 HTTP 决断口答 `409 conflict.resume_context_unavailable`,待修。
+
+24. **`WORKSPACE_PERSIST` 缺省 `off` → `space`(行为变更)**。7.125.0 关缺省的原因(提交标记写在对象存储里,可能晚于引擎拆环境上界落地 ⇒ 上一条 run 的改动可能被覆盖)已关上(仍余更窄的一条:写者放弃后 `latest` 预签 PUT 在对象存储侧迟到落地 —— 多副本上才构造得出,本版披露、不做条件写;见 USAGE §9.3b):
+   「这个空间有提交在飞」现在是 run 店里的一行,由 run 的终态写入在释放会话占用的**同一个事务**里落下,下一条 run 连沙箱前读它、等上一条存完(最多一个上传时限)。
+   - **谁受影响**:`REMOTE_EXEC=k8s` 且 `MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` 三键齐、没设 `WORKSPACE_PERSIST` 的部署 —— 升级后 `/workspace` 跨轮保留
+     (同一会话的下一条 run 看得到上一条留下的文件;能力位 `workspaceSync.persist` 报 `"space"`)。要保持每轮为空:显式设 `WORKSPACE_PERSIST=off`。
+   - **拒启**:上面这类部署若**没有存储后端**(`DB_BACKEND=memory`〔无持久店〕;配了 SQL 的 `DB_BACKEND` 却显式 `SESSION_BACKEND=memory` 时库不开,同一形;`/health.sessionBackend` 报 `memory`)⇒ 本版起服即拒
+     (拒句一行点名旋钮词、缺的存储后端、会话店种类与出路:设 `WORKSPACE_PERSIST=off`,或改用 `DB_BACKEND=local` / `mysql` / `pg`)。`SESSION_BACKEND=memory` 配 `DB_BACKEND=local` **照起**
+     (被收编成 local 店,`/health.sessionBackend` 报 `durable(local)`;`DB_BACKEND=local` 上 `SESSION_BACKEND` 缺省就是 `memory`)。7.125.0 只在显式设了 `space` 时拒。
+   - **起服行**:k8s 车道没配 `MINIO_*` 三键 ⇒ 起服多一行 `workspace_persist_unavailable`(点名缺的键;行为不变,工作区每轮为空);设 `WORKSPACE_PERSIST=off` 即不出。
+   - **谁受伤(存储面)**:缺省 `space` 后每条 run 末都往桶里写一份快照对象(留 `WORKSPACE_SNAPSHOT_KEEP` 份,缺省 3,外加指针 `latest`)。会话删除(`DELETE /v1/sessions/:id`)与托管留存 sweep 回收空间时**一并删**:
+     该空间 `<前缀>/<化身>/space/` 下的全部对象、该会话停驻车道 `<前缀>/<会话 id>/` 里的 `*.tar.gz`(只删名字带本住客归属记号的 —— 7.126.0 起停驻快照 id 形为 `kata-<归属记号>-<时间>-<随机>`,归属记号是住客化身的不可逆摘要〔化身本身不进名字〕,没有已知住客的 run 记 `none`;会话 id 删后可被别人重新登记,后来的住客的快照带它自己的记号,不碰;升级前写的旧形停驻快照不带记号,留给桶的生命周期规则;升级时还挂着的停驻 run 照常续跑 —— id 对引擎不透明,key 形不变)、构建缓存卷(同一只回收座);删失败 = 一行 `workspace_space_reclaim_failed` + 计数 `server.workspace-space.reclaim-failed`,不挡删除。
+     回收**不在删除应答路径里**:`DELETE /v1/sessions/:id` 摘掉旧订阅后即答,回收座在应答前已起、应答不等它完成,对象存储再慢也不拖删除;回收座**一次调用一份绝对截止**(= 快照时限 `WORKSPACE_SNAPSHOT_TIMEOUT_MS`,不新增旋钮;在入口建一次,**卷回收也在内**):会话删除 = 一个空间的调用;托管留存 sweep 每域每次最多取 500 个到期会话、按域循环,每个域这一拍结束的空间 = 一次调用,所以一拍里回收的上界 = 域数 × 快照时限。截止到点 ⇒ 切断在途请求、停掉余下的列举与删除,一行 `workspace_space_reclaim_failed{stage: "budget"}`;这次调用里还没轮到的空间一个请求都不发、各记一行 `budget`(配了缓存卷的,卷再各一行 `workspace_cache_reclaim_failed{reason: "budget"}`);没删的对象归桶的生命周期规则、卷按标签手清。到期会话已删、不会被重新列出:下一拍照常起、不被这一拍拖住(同一个域内 sweep 的后续步骤 —— 孤儿结果清理 —— 照跑;一拍最长 = 有结束空间的域数 × 快照时限,超过 sweep 间隔时中间的拍被跳过(防重入守卫照旧);**快照时限 ≥ 2 × sweep 间隔(= 租约 TTL)时,一个域内的回收可把本副本的租约耗过期 ⇒ 这一拍余下的域不跑、下一拍再起(一行 `retention_sweep_lease_lost`)—— 配法:快照时限要明显小于租约 TTL,即 `WORKSPACE_SNAPSHOT_TIMEOUT_MS`(毫秒)< 2 × `RETENTION_SWEEP_INTERVAL_SEC` × 1000 再留出该域 SQL 步骤的余量;缺省时限 300 000 ms 对 sweep 间隔 ≥ 300 s 的部署成立,间隔更短的部署调大间隔或调小时限(时限下限 30 000 ms)**)。会话删除路径没有并发上限:每个 `DELETE` 各起一次调用、各自一份截止。
+     桶的生命周期规则只作兜底(回收失败的对象、回收截止到点而没删的对象、回收没跑完进程就退留下的对象、会话删除那一刻上一条 run 的提交恰好才落下的对象、升级前已结束的空间留下的对象、升级前写的不带记号的旧形停驻快照与无住客的 run 写的 `none` 停驻快照,只有它能清)。
+   - **开之前核一件事**(同 7.125.0 第 9 条):这组 MinIO 凭据能读写 `WORKSPACE_SNAPSHOT_BUCKET`(缺省 `workspaces`)桶,且 server 进程够得着 `MINIO_ENDPOINT`。读 `latest` 失败 ⇒ run 连沙箱失败。回收空间用同一组凭据对桶做列举与删除(修剪旧快照早就在用)。
+
+25. **SQL 后端:新表 `workspace_space_commit`(存储面;存量库加一表,零手工动作;列 `space_key` / `task_id` / `state` / `expires_at_ms`)**。起服的建表腿(`CREATE TABLE IF NOT EXISTS`)自动建它 —— 前提与其余表同:库账号有建表权限
+   (没有 ⇒ 先照 `docs/schema/baseline-<mysql|pg>.sql` 里那一段手建)。表在而列不齐 ⇒ 拒启 `config.schema_mismatch`,拒句形与 7.125.0 第 5 / 8 条两列相同(点名缺的列 + 生成的
+   `ALTER TABLE … ADD COLUMN …;`)。旧版副本不认识这张表、也不判它 ⇒ 滚动先后不限。`DB_BACKEND=local`:数据根下多一个目录 `space-commits/`(每个在飞的提交一份记录),零动作。
+
+26. **从显式开了 `space` 的 7.125.0 部署滚动升级**:窗内 7.125.0 副本仍用对象存储里的提交标记 `<前缀>/<化身>/space/committing`、本版副本用新表,两边互相看不见 ⇒ 相邻两条 run 落在不同版本的
+   副本上时,7.125.0 写明的残窗在窗内仍在。要零窗:窗内设 `WORKSPACE_PERSIST=off`,全部换代后再去掉;或停机换代。残留的 `space/committing` 对象本版不读;空间结束时(会话删除 / 托管留存 sweep)回收座把 `space/` 下的对象一并删掉它,仍活着的空间里的由桶生命周期规则清走。
+   本版副本之间滚动改 `WORKSPACE_SNAPSHOT_TIMEOUT_MS` 没有窗:提交的期限随行(写行的副本按自己的数写),等它的副本只读行里的期限 ——
+   所以下一条 run 最多等的是**上一条 run 的写者副本**所配的数(每次写行续一界),不是它自己副本的数;各副本同配时就是同一个数。
+
+27. **日志与失败形(按事件名告警的规则对一下)**:
+   - 退役:`workspace_commit_marker_stuck`(提交标记没了);`workspace_snapshot_failed` 的 `stage` 值 `marker` 退役,新值 `fence`(这条 run 的提交行已过期限 —— 下一条 run 可能已按放弃继续 ——
+     或另一条 run 的提交仍在飞;上传完、写 `latest` 前再认领一次时行已过期限或已归别的 run,也是它 ⇒ 不保存、`latest` 不动、终态帧照旧带 `workspaceSnapshot: "failed"`)。
+     闭集变为 `fence` / `upload` / `pointer`;`pointer` 只剩 `latest` 写失败(7.125.0「从开始保存算起超时限才走到写 `latest`」那一形并进 `fence`)。
+   - `workspace_commit_abandoned`:只在下一条 run 于行锁下真把过期行删掉之后才出(写者恰在那一刻续期 ⇒ 不出、照等);字段 `ageMs` 换成 `remainingMs`(≤ 0:过了写者期限多久 —— 期限写在行里,不再是读者自己的时限),多一个字段 `state`
+     (`pending` = 上一条 run 死在终态与保存之间;`committing` = 死在上传里;`publishing` = 死在写 `latest` 时);期限按存储自己的钟(SQL = 数据库的钟)算。
+   - 新增 `workspace_latest_dangling`(`space` / `key` / `deleted`):`latest` 指向的快照对象不在了(桶生命周期规则只清了 `.tar.gz`,或手删)⇒ 删掉悬空指针、这条 run 从空目录开始,
+     它的 run 末快照成为新的 `latest`。**此前**同一情形是这条 run 连沙箱失败、直到运维删指针。
+   - 读提交行失败(数据库 / 数据根故障)⇒ 这条 run 连沙箱失败(`connect_failed`),与读 `latest` 失败同形。
+   - 读会话住客失败(会话店报错,或答出的不是住客令牌)且跨轮保留或缓存卷开着 ⇒ 同形 `connect_failed`、一只 pod 都不建,新增一行 `workspace_space_unreadable_occupant`(`sessionId` / `code`)。
+     **此前**同一情形是一行 `workspace_space_unavailable{reason: <故障码>}`、这一轮在空工作区里照跑且不存;按 `workspace_space_unavailable` 告警读故障的规则改按新事件名。
+
+28. **委派子代 / 后台代理的 run 不开工作区空间**:它们与父 run 并发,共用一个空间就是两个写者 ⇒ 子代的 `/workspace` 每轮新建、不恢复也不保存,不再逐个打 `workspace_space_unavailable`。
+   父 run 的空间与能力位不受影响;停驻挂起照常。(7.125.0 上子代本就读不出会话住客、既不恢复也不保存,只是每个碰了沙箱的子代各打一行 —— 本条收掉的是那行噪声,行为不变。)
+
+29. **`GET /v1/capabilities.workspaceSync` 成员各自在场(wire 收窄;契约 B.1 / B.1a)**:`persist` / `keep` / `timeoutMs` 只在配了快照存储时在场,`cache` 只在开卷(`WORKSPACE_CACHE=volume`)时在场,整对象在任一成员在时在;7.125.0 的「对象在 ⇒ `persist` 在」不再成立。
+    谁受伤:把 `persist` / `keep` 当必填型或按封闭 schema 解析该对象的消费方(sdk 类型随 21.0.0 改为各自可选);改读 = 按成员各自在场判,读跨轮保留一律读 `persist === "space"`。
+
+30. **一次性迁移 M1–M3 退役:7.126.0 起不再自动迁;从没在 7.125.x 起过服的旧库起服即拒(持久数据面;行为变更)**。7.74.0 引入的三条启动期一次性迁移 ——
+    删退役的整树快照索引表 `snapshot_manifest`;删退役的单座 steering 列 `checkpoint.pending_steer`(列上还有送得出去的指令时拒启);把账本与已决 checkpoint 里的旧判词拼法 `unresolvable` 原地改名 `ancestor_marked` ——
+    窗(发布日 + 30 天)已关,本版删了它们的码,以及起服日志行 `one_time_migrations_applied` 里对应的五个读数字段(`retiredSnapshotTable` / `retiredSnapshotRows` / `retiredSteerSeatColumn` / `retiredSteerSeatStaleRows` / `askOriginRowsMigrated`;
+    同一行里 `removableAfter` 读数的 `M1` / `M2` / `M3` 三键随登记行消失)。按这五个字段做告警或看板的规则要删。
+    - **谁受伤**:从 ≤ 7.73.x 直接跳到本版、中间从没起过 7.74.0–7.125.x 任一版的库(表或列还在)—— 起服**拒启** `config.schema_mismatch`,拒句点名在场的那一件或两件(`snapshot_manifest` / `checkpoint.pending_steer`),并说明旧判词的改写同样没跑过。
+      判据只看这两件退役 schema 在不在;旧拼法不另扫账本(那是一条无索引的整表扫,不能成为每次起服的固定开销,而且这两件在场本来就是「改名没跑过」的标记)。
+    - **做法**:先在 **7.125.x** 上对这只库起服一次,让迁移跑完(它删表、删列、改名;列上还有送得出去的 steering 指令时它自己拒启,拒句给出它的出路),再升到本版。7.74.0–7.125.x 各节的升级动作(例如各版加的列)照常适用。
+      拒启前只会建出本版新表(起服的 `CREATE TABLE IF NOT EXISTS`,幂等;回退到 7.125.x 仍安全 —— 旧版只对账它认识的表),不改任何存量行 —— 回退重来是安全的。
+    - **不受影响**:起过 7.74.0 及以后任一版的库(退役 schema 早已不在,零动作);新建的库;内存形(没有这张表和这一列)。
+    - **`DB_BACKEND=local` 不在「不受影响」之列(如实)**:7.125.x 上 M3 有 local 腿(起服时改写 run 账本里的旧拼法),本版删了它、且没有拒启 —— local 数据根里 ≤ 7.73.x 写下的旧拼法行不再被改写,回放面整条缺席并计数(`server.trace.gate-outcome-defective`,响亮)。
+      要干净:先在 7.125.x 对这个数据根起服一次,再升本版。
+    - **残余(如实)**:① 升级前手工把两件退役 schema 都删掉、却没跑过那条改名的库不会拒启;库里残留的旧判词在回放面上整条缺席并计数(`server.trace.gate-outcome-defective`,响亮,不静默)。
+      ② `DB_BACKEND=local` 的已决 checkpoint 存在引擎自己的 File 店里,按契约物理不可变,迁移从来改不了它们(7.74.0 起即如此),同样由那条读腿整条缺席并计数。
+      这两种情形里 `gate` 缺席是这一格的已知形,不是别的故障。
+    - **类型面(自建 `StoreBackend` 的嵌入方;随包 `dist/plugins/one-time-migrations.d.ts`)**:`OneTimeMigrationReport` 删除上面那五键(`NO_SQL_MIGRATIONS` 同步少五键)—— 自建 `runOneTimeMigrations()` 返回形的 tsc 即通知;
+      `RetiredSteerSeatError`(事件码 `checkpoint.pending_steer_seat_retired`)删除,不再有「列上有送得出去的指令」这一条拒启;新增具名错误 `RetiredSchemaPresentError`(`code: "config.schema_mismatch"`,字段 `found` = 在场的坐标)。
+    - 未到期的 M4–M16 不动。
+
+31. **会话 id 只有一只形律:提交口与 `run-local --session` 也只收 canonical uuid(硬破坏,零别名;契约 §0.8 / 附录 A.1)**。
+    `POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs` 体里的 `sessionId`(A2A `message/send` 的 `params.message.contextId` 同)此前按「任意 ≤ 64 字符串」收;
+    现在与会话口(fork / 抹除 / 会话策略 / 2c 同步)是**同一只**形判 —— 只收 canonical uuid(任意版本,小写;壳预设的 v4、本服务自己铸的 v7 都过)。`run-local --session myproj` 同拒同句。
+    - **改法**:会话 id 一律改用 uuid;想要好记的名字,自己记 name → uuid 的映射(服务端不存、不转换)。
+    - **拒句形**:`400 request.id_invalid`,句子 `invalid session id (must be a canonical uuid); a self-chosen session name is not accepted — use a uuid (any version) and keep your own name-to-uuid mapping`
+      (句首与会话口同句;`run-local`:同一句,用法错,退出码 2)。此前超过 64 字符的拒答是 `400 request.field_invalid` + `sessionId must be at most 64 characters`:这条长度判与那句话**退役**(超长串现在也是 `request.id_invalid`)。按 `errorCode` 分支,句子只作展示。
+    - **没有转换期**:无旋钮、无别名,升级即生效。
+    - **谁受影响**:提交体里带自选 `sessionId` 的调用方(`myproj`、业务键、带空格或超过 36 字符的串、大写 uuid);`run-local --session <自选名>` 的 dev 用法;给 A2A `contextId` 塞自选串的对端;
+      以及发 `"sessionId": ""` 想表达「新会话」的客户端(空串此前被当成没给,现在是非 uuid ⇒ 400 —— 缺省请**省略这个键**;A2A 的 `contextId: ""` 同,此前是 JSON-RPC -32602;`run-local --session ""` 的拒句也换成同一句)。
+    - **存量**:旧自选 id 的会话数据仍在库里,读口仍按原 id 读得到,但提交口不再受理这个 id —— 那些会话**续聊不了**(fork / 抹除本来就只收 uuid)。没有迁移工具:要延续历史,请改用新 uuid 开新会话。
+      形判只看字符串形,不查会话存不存在,带一个不存在的 uuid 的行为不变。已经停驻在审批上的旧 id 会话不受影响:审批口 `POST /v1/approvals/:sessionId/decide` 按路径段兑现,续跑腿不重过提交口的形判。
+    - **不变的**:缺席 `sessionId` ⇒ 服务端现铸 uuidv7;v4 / v7 / 其它版本的 canonical uuid 照常过门;`body.taskId`(uuidv7)与 `GET /v1/sendfile-links?before=` 游标(uuidv7)的形要求不变。
+
 ## 7.125.1 —— 受理门宿主绝对路径形判认三族(posix / Windows 盘符 / UNC;契约包 11.3.1)(行为修复,升级零动作)
 
 0. **行为修复,无升级动作**:Windows 宿主送 `C:\…` / UNC 形的 `cwd` / `additionalDirectories` / `additionalReadDirectories` / `skill.baseDir` 不再被受理门 `400 request.field_invalid`;posix 路径逐字同 7.125.0;拒句与错误码不变。零 DDL、零旋钮、零 wire 形变;细节见 CHANGELOG 7.125.1。
@@ -1275,7 +1470,6 @@
 - **wire 值(S-922):`POST /v1/side-query` 200 体 `errorMessage` 过 `redactErrorMessage`**(键不变;服务商错误体里的密钥形换 `«redacted»`)。**迁移**:按原样错误体做字符串匹配的调用方改比错误码。
 - **零动作(S-921 / S-920)**:披露改真与明拒行保鲜钉,无行为变化。
 
-
 ## 7.107.0(车SE,S-907 / S-890;车SF)—— `@sema-agent/core` 7.36.0:post 钩子收 wire 名 · 双引擎名声明拒 · 工具调用 id 越界折叠(服务商拿回原串)· 两只恒真能力位删
 
 - **🔴 hooks:PostToolUse / PostToolUseFailure 的 matcher 与 payload `tool_name` 改为调用派发到的工具的 wire 名**(此前是模型拼写;PreToolUse 本来就是 wire 名)。
@@ -1926,7 +2120,6 @@ wire 面(同步提交撞 park 的 200 体、`GET /v1/runs/:id` 行形、同一
 - **`WEB_SEARCH_ENDPOINT` 带 userinfo ⇒ 拒启(S-716,行为面)**:`WEB_SEARCH_PROVIDER` 点名了后端、`WEB_SEARCH_ENDPOINT` 形如 `https://user:pw@host/…`(或只带 `user@`)的部署升级后拒启(`config.web_search_invalid`);每请求 `settings.webSearch.endpoint` 带这一形从 202 变 `400 request.field_invalid`(修前这一形本来就用不了:fetch 每次都抛,错误文本还带出口令)。**迁移**:brave / tavily 的凭据走 `WEB_SEARCH_API_KEY`(或 `settings.webSearch.apiKey`);带 basic-auth 的 SearXNG 在前面放一层注入鉴权的反代。
 - **配置目录两行 `csv` → `secret`(S-713,wire 形变)**:`GET /v1/config/catalog` 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` 两行 `type` `csv` → `secret`、`valueClass` `plain` → `secret`、`effectiveValue` 从名字数组变 `{ present }`,`summary.secret` 计数 +2。读这两行名单内容的消费方改读起服行 `remote_exec_enabled.sandboxEnvKeys`(只键名);这两只旋钮的原文从此也不进 host shell / git 子进程 / 语言服务器(在这些子进程里读它们的脚本收不到了)。
 
-
 ## 7.100.0 —— 十条 BREAKING(部署面 `CROSS_SESSION_INBOUND=accept` 拒启 / 类型面 `MailboxStore.ack` / WebSearch 配置形错响亮 / 请求面 `settings.webSearch` / WebSearch 报错句换形 / deny 部署的「无人可答」记部署政策 / 记忆抹除面新 409 / 审批名单热应用 / 子进程剥名 / local 车道回滚前收敛 ask 账本)
 
 - **`CROSS_SESSION_INBOUND=accept` ⇒ 拒启**(core 7.30.0 把 `accept` 从 `crossSessionInbound` 闭集删掉,拆成 `wake`(立刻唤醒收件方)/ `next-turn`(排到收件方下一轮 = 旧 `accept` 的那一档);本仓词表直接取 core 常量,零别名 —— 拒启句列出新词表)。**迁移**:env 写 `next-turn`(原义)或 `wake`;`settings.json` 里的 `accept` 由引擎自己读成 `next-turn` 并通告一次,但 `@sema-agent/settings-schema` 6.0.0 的文件层对 `accept` 响亮拒 ⇒ 一并改写。本版精确钉 core 7.30.1 + settings-schema 6.0.0(锁步序:core → settings-schema → server → 宿主才可写 `wake`)。

package/README.md

@@ -184,8 +184,8 @@ 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 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_GATEWAY_BASEURL` | **no default** | OpenAI-compatible gateway base URL (without `/chat/completions`). **No factory default**: 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 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 |

package/README.zh-CN.md

@@ -155,8 +155,8 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 |------|------|------|
 | `PORT` | `8090` | HTTP 监听端口 |
 | `BIND_HOST`(别名 `HOST`) | 见说明 | 监听地址。显式 `BIND_HOST` **恒生效**。缺省:写面无鉴权时(`ALLOW_UNAUTHED_WRITES=true` **且**未配任何 service token)= `127.0.0.1`,否则全接口——配了 token 的部署不受影响。自 3.15.0 起 `HOST` 别名**不再完全等效**:shell 常把 `HOST` 设成机器名而 operator 并不知情,于是上述收窄条件成立时,收窄压过继承来的 `HOST`(告警事件 `bind_host_from_HOST_env_overridden`)。要暴露写面,显式设 `BIND_HOST`,或配一个 service token。 |
-| `MODEL_GATEWAY_BASEURL` | **无缺省** | OpenAI 兼容网关地址(不带 `/chat/completions`)。**无出厂缺省**(S-623):每一条落 openai 兼容腿的路由都必须解析到显式端点 —— 目录条目自己的 `baseUrl`,或本键 —— 否则拒启,拒因点名模型并给出本机写法(`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`)。anthropic 单路由部署可不设。只设 `MODEL_GATEWAY_FALLBACK_URLS` 不设本键同拒 |
-| `MODEL_ID` | **必填(目录给出缺省时可省)** | 缺省模型 id ——**3.0.0 起无出厂缺省**。7.101.0 起(S-705)判据挪到目录应用**之后**:`MODEL_ID` **或**目录里一条可用的缺省(`config.d/models.json` / 配置控制面)任一在场即可;两者皆无 = 拒启(码 `config.default_model_missing`,指路二选一)。旧的烤死缺省是内网模型名,外部部署必炸且炸在离根因最远处:网关 `400` + 标题 hook 连环告警 |
+| `MODEL_GATEWAY_BASEURL` | **无缺省** | OpenAI 兼容网关地址(不带 `/chat/completions`)。**无出厂缺省**:每一条落 openai 兼容腿的路由都必须解析到显式端点 —— 目录条目自己的 `baseUrl`,或本键 —— 否则拒启,拒因点名模型并给出本机写法(`MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1`)。anthropic 单路由部署可不设。只设 `MODEL_GATEWAY_FALLBACK_URLS` 不设本键同拒 |
+| `MODEL_ID` | **必填(目录给出缺省时可省)** | 缺省模型 id ——**3.0.0 起无出厂缺省**。7.101.0 起判据挪到目录应用**之后**:`MODEL_ID` **或**目录里一条可用的缺省(`config.d/models.json` / 配置控制面)任一在场即可;两者皆无 = 拒启(码 `config.default_model_missing`,指路二选一)。旧的烤死缺省是内网模型名,外部部署必炸且炸在离根因最远处:网关 `400` + 标题 hook 连环告警 |
 | `MODEL_API_KEY` | — | 网关 key(可选)。只与 `MODEL_GATEWAY_BASEURL` 配对:没设网关时不装载、不发往任何路由 |
 | `SERVICE_AUTH_TOKEN` | — | 调用方需带 `Authorization: Bearer <token>` |
 | `DB_BACKEND` | `local`* | SQL 引擎:`mysql`(任何 MySQL 协议库:MySQL/TiDB/MariaDB —— TiDB 走这个值,**没有** `tidb` 别名,写它启动即拒)/ `pg`(PostgreSQL)/ `local`(免 DB 文件持久化)/ `memory`(显式纯内存)。显式设置 `mysql`/`pg` 时 session 自动转 durable。*单租户裸 boot 缺省 `local`;`REQUIRE_PRINCIPAL=true` 的多租户裸 boot 缺省 `memory`(local 与多租户互斥) |