@sema-agent/server 7.118.0 → 7.120.0

package/MIGRATION.md

@@ -7,6 +7,145 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.120.0 —— 引擎 7.46.0:子代工具清单回到开跑前拒退役拼法、管到内建工具 · 配置根搬家后同护 · 回显条目一种渲染 · 路径规则锚在装入处
+
+**升级前核查(一句话)**:设了 `SEMA_CONFIG_DIR` 的部署确认那个目录能建出来、不是空串;`CONFIG_LKG_PATH` 不是空串;
+按 `agents[].denyTools` 拼错只告的调用方改正拼写。停驻中的委派子代不必为本版排空(第 5 条)。
+
+1. **勘误(7.119.0 节,已发节不改字节)**:7.119.0 节说 `/health` 多一键 `sessionBackend` —— 「多一键」错:`/health.sessionBackend` 是既有键(≤7.117.0 已在),
+   7.119.0 只把它与 `listening` 日志的读法收成一只、让 sema-up 的冒烟改读这一位。消费方按「已消费 / 不变」读,不要删读点。
+2. **子代 `agents[].denyTools` 的退役拼法(`bash`)与大小写孪生(`BASH`)回到开跑前拒**(`config.agent.unknown_tool`,句子点名现名 `Bash`;7.119.0 上只告不拒、子代照拿 `Bash`):
+   本服务的委派工具现在声明它逐次注入的工具名册,引擎列得出子代工具池。无人挂的名照旧只告不拒(运维日志 `runner_config_advisory`)。
+   `denyTools` / `allowTools` 现在管子代手里的**全部**工具 —— 委派池与内建 hands(`Read` / `Edit` / `Write` / `NotebookEdit` / `Bash` / `Grep` / `Glob` …):
+   `denyTools: ["Write"]` ⇒ 子代没有 `Write`;`allowTools` 只列调用方工具 ⇒ 子代一只内建工具都没有(要什么点名什么);内建只读子代(Explore / Plan)没有 `Edit` / `Write` / `NotebookEdit`。
+   hands 之外的引擎工具(`Monitor` 等)仍不受这两张表管;要按路径 / 命令拦而保留工具,写调用方权限策略的 deny 规则。
+3. **配置根搬家(`SEMA_CONFIG_DIR`)后,根下的配置文件与家目录下同护**:根下的 `settings.json` / `settings.local.json` / `engine-data/.env` / `config-lkg-*.json`
+   模型读不到(家目录 `~/.sema/` 下同名文件照旧读不到,两处都拒),写进根下要问一次。起服时建出那个目录(不在就建,权限 `0700`);建不出来或不是目录 ⇒
+   引擎拒启,拒句带码 `config.agent_config_dir_invalid`(建不出来时本服务先打一行 `sema_config_dir_unprovisioned`,点名旋钮与原因)。
+   **`SEMA_CONFIG_DIR=`(空串)**:≤7.119.x 空串 = 进程工作目录(LKG / skill 缓存 / scheduler 店落在那里);7.120.0 起空串**拒启** —— 去掉变量用 `~/.sema`,
+   或写出要的目录(要保持旧位置就写工作目录的路径)。
+   LKG 覆写到配置根外(`CONFIG_LKG_PATH`)⇒ 派生读拒行:写下的路径与经符号链接目录后真正落的路径各一行(拒句与内建行同一句)。行的射程按路径段串算 ——
+   去掉开头的 `/`、不锚到根:这串段在任意深度出现即拒、大小写不敏感(`CONFIG_LKG_PATH=/app/config-lkg.json` ⇒ 用户仓里的 `…/app/config-lkg.json`、
+   `…/APP/Config-LKG.json` 同样读不到,Grep 的结果里也不出现);引擎提供锚定单文件的读拒行之前如此,要少挡就把覆写路径写得更具体。`CONFIG_LKG_PATH=`(空串)拒启。
+   拒启行的形:带串码的异常印成 `<name> [<code>]: <message>`(按码匹配,不按句子)。
+   `AGENT_DATA_DIR` 搬到配置根之外的部署:引擎数据根下的 `.env` 不在这条规则的射程里 —— 用部署自己的读拒行(`READ_DENY_PATTERNS`)守它。
+4. **回显条目:人读句一种渲染,通告里的规则文本是原值**:拒句、起服拒启行里的工具名 / 规则条目一律是引擎的渲染 —— JSON 串形(带引号),看不见 / 印成空白的字符
+   写成 `\uXXXX`,超长截断;「can never take effect」拒句里的名字与「pre-prefix short form」指引里的建议名从不带引号变成带引号。
+   通告里的规则文本(`permission.allowed_tool_not_granted` 的 `detail.entries[].entry`、`permission.rule_row_dropped` 的 `detail.rows[].rule`)是条目的**脱敏原值**:
+   不加引号、不转义、本服务不另截断;认出的凭据换成脱敏记号,双向控制符 / 零宽字符等格式字符剥掉,C0 控制符保留(JSON 里写成转义)。7.119.0 的 `entry` 剥掉了
+   控制 / 双向符、超过 160 字截断并标原长 —— 把 `entry` 直接打到终端的消费方先自己中和控制符,或显示通告文本 `message`(那是渲染好的句子)。
+5. **停驻中的委派子代:本服务的续跑腿不触发引擎的「装入记录缺席」拒,升级前不必排空**:引擎 7.46.0 对宿主**重供**的父约束链查「每条规则装在哪条腿」的记录,
+   缺了且规则依赖装入腿(相对形、`/x` 形、`~/` 形)⇒ 拒 `resume.parent_constraint_mismatch`(`detail.reason: "installation_record_absent"`)。本服务 `/decide` 一只停驻子代时
+   重供的链只有部署段(审批名单、命令策略、敏感路径守卫集、誊本门、问答门),不带随腿锚定的路径规则,请求的 `settings.permissions` 规则不在链里 ⇒ 没有要拒的条目。
+   实测:7.119.0 停驻(父请求带 deny `Edit(src/**)` / ask `Edit(/src/**)` / deny `Read(~/secret/**)`)→ 7.120.0 `/decide` 三形都照常续跑完。
+   自建续跑腿、自己重供带这几形路径规则的父约束链的嵌入方不在此列(照引擎说明:让旧版 worker 做完,或过期后重提)。
+6. **请求规则的相对 / `/x` 形路径模式在沙箱 / 设备车道(与还没登记工作目录的 host 腿)上照收**(修前 422):引擎把规则锚在装入它的那条腿的真根;
+   相对模式**不随 `cd` 走**(`Read(a/b/**)` 在 `cd sub` 之后不再够到 `sub/a/b/…`;要任意层写 `**/a/b/**`)。
+7. **新通告码 `permission.rule_row_dropped`(上会话流)**:持久规则里有项目行的 scope root 不是完整绝对路径 ⇒ 那几行不参与本 run 的检查;`detail` 点名前八行(`rows[].rule` 与第 4 条同一只写法 = 规则文本的脱敏原值)。
+   这种行是 7.119.0 及更早的本服务入口收下的(`/v1/rules` 写口与两条导入面按「root 非空」收 `project:myproj`,当时引擎也收)。本版:
+   - **入口按引擎同一只谓词拒**(project root 必须是完整绝对路径 `/…`、`X:\…`、`\\host\…`):`POST` / `DELETE /v1/rules` 与 cc-import 预览答 `400 request.body_shape`、
+     `GET /v1/rules?scope=` 答 `400 request.query_invalid`、local-import 预览把那一行判 `scope_unreadable`;修前写口答 `503 state.rule_write_failed`「再发一次」(重试永远不会好)、
+     撤销口答 200 而行留在店里、导入预览收下而兑付时被引擎拒。拒句从「with a non-empty root」改成「with an absolute root」。
+   - **SQL 后端(MySQL-protocol / PostgreSQL)起服时一次性删掉存量的这种行**(规则行与墓碑;一行一条运维 warn `permission_rule_row_removed`,带桶键、态(`kind`)、工具名与 root
+     (root 已脱敏),不带规则正文;启动汇总行 `one_time_migrations_applied` 的 `undurableScopeRuleRowsRemoved`)。只有 `kind: "rule"`(仍生效的那几行)的 warn 劝重写:
+     还要的规则按项目的完整路径重新写。`kind: "revoked-rule"`(早已撤销:它背后的每一次同意都被同桶的撤销记录删掉了)与 `kind: "tombstone"`(撤销记录本身)随之删掉,
+     **不要**重加 —— 撤销照旧成立。
+   - **读路径整桶拒的桶一行不动**(形不合、指纹不符、behavior 不认识、撤销记录的规则文本不规范、规则文本与匹配字段不一致 —— 与读规则时整桶拒的判据是同一只):
+     迁移窗内每次起服逐桶一条运维 warn `permission_rule_bucket_unreadable`(桶键 + 拒因,不带规则正文;汇总行 `undurableScopeRuleBucketsUnreadable` 计数),
+     直到**人工处置** —— 处置 = 修正或删除那一行,并按既有指纹算法(`buildRuleBucketChecksum`,算在规则 / 墓碑 / 隔离三列与观测向量上)重算该桶的 `checksum`。
+     这种桶在升级前后都整桶读不出;迁移不替它删行(从一只整桶拒的桶里删行再重算指纹,等于让原本被拒的规则上线)。
+   - **M11 回写与正常写同形**:被改动的桶里 `rules_json` / `tombstones_json` / `quarantined_json` 的旧行(写于 `behavior` 字段之前)都会补上显式 `behavior`
+     (缺席的本义就是 `allow`,补上的就是 `"allow"`,语义不变);`observed_vector_json` 不动;`checksum` 按回写后的字节重算。
+   - **local 后端删不动**:规则在引擎自己的文件店里,引擎的写面对这种 scope 一律拒 —— 那些行照旧每次 run 被丢并告知;撤销口同样删不动(本版的已知边界,候引擎给删除缝)。
+8. **引擎 7.46.0 的 shell 读法**:喂给 shell 标准输入的脚本(`bash <<'EOF' …`、`curl … | sh`、`cat x.sh | bash`、`bash < x.sh`)按 `-c` 文本判 —— 运行时拼出的一律要人答
+   (`dangerous_delete`,`bypassPermissions` 不免;7.119.0 节第 1 条的已知边界由此收掉);读名单里列了写程序(`cp` / `mv` / `mkdir` / `rm` / `rmdir` / `tee` / `touch` / `flock`)的部署,
+   这些调用现在出卡;开放读面且没有 deny 行时,「说不清读哪」不再出强制卡;经链接 / 别名 / 大小写变体 / `cd` 后相对拼写够到受守路径的调用现在出卡或在闸上拒。
+
+## 7.119.0 —— 场景指派悬空不再静默落 `default`:`DEFAULT_SCENARIO` 不在册 ⇒ 拒启 · 中心指派的场景名本部署没有 ⇒ 该主体的 run 503 · `APPROVAL_REQUIRE` 的「本会话放行」恢复生效
+
+**升级前核查(一句话)**:把 `DEFAULT_SCENARIO`(缺省 `code`)与**中心里每个主体 / 组 / 全局的场景指派**逐名对本部署的在册场景
+(内建 `default` / `code` / `code-review` / `scan` / `discuss` ∪ 配置中心声明的场景;`GET /v1/capabilities` 的 `scenarios` 就是这张表)。
+对不上的名字,7.118.x 上是**静默跑在 `default`**(工具、提示词、skills、MCP 整包跟着换,零日志);本版起:
+
+1. **`DEFAULT_SCENARIO` 不在册 ⇒ 起服拒**,拒句点名那个名字与在册词表。改 env(或把那个场景声明回配置中心)再起。
+   `DEFAULT_SCENARIO` 点名的是**配置中心声明的**场景时,起服要在启动窗内拿到那份声明(中心不可达 / 超窗、且无 last-known-good 缓存 ⇒ 声明缺席 ⇒ 同样拒启,中心恢复后再起)。
+2. **中心指派的场景名不在册 ⇒ 该主体不带 `scenario` 的提交答 `503 state.scenario_assignment_unknown`**,体 `detail: { scenario, source: "ruling" }`,
+   句子点名指派名与在册词表;零 run、零计费、不带 `Retry-After`。出路:在中心把指派改到在册的名字(或把那个场景加回本部署),然后原样重试
+   (本副本读到新指派要等它自己的缓存窗,缺省一分钟)。续跑腿上同一条拒折成 `409 resume_blocked_by_policy`(`blockedBy: "state.scenario_assignment_unknown"`)。
+   **在中心新增场景 X、同一拍把主体指派到 X**:本部署的场景表重启才生效、指派是热读的 ⇒ worker 重启之前那个主体的每一次 run 都是这条 503 —— 先重启 worker 让 X 进表,再指派。
+3. 不变:请求体显式给的未知名仍是 `400 scenario_unknown`;体里显式给在册名照常服务(不受悬空指派影响);在册的指派 / 缺省照常。
+4. 嵌入方自己装配 `resolveSpec`:缺省场景悬空的装配在**提交时**拿到同一条 503(`detail.source: "deployment"`),起服那一拍没人替你拒。
+5. 库面 `selectScenario(scenarios, name)`:`name` 不在册(含 `""`)现在**抛**,不再回落 `default`;不传名(`undefined`)仍取内建 `default`。
+6. `run-local`(单次本地 CLI):`--scenario <不在册的名>` 与 `DEFAULT_SCENARIO` 悬空都退出码 2、点名在册词表(此前静默落 `default`)。
+
+**`SESSION_BACKEND=auto` 收紧(行为破坏性)**:配了坐标(`MYSQL_HOST` / `PG_HOST`)而库起服时连不上,7.118.x 上静默落内存(一行 warn、`/health` 200);本版起在 `STORE_LOCK_WAIT_MS`(缺省 60s)窗内重试、到窗**拒启**,拒句点名后端与 host:port。
+升级前核查:库晚于 server 就绪的编排(k8s 同时起)把窗调大(`STORE_LOCK_WAIT_MS=300000`);要内存就显式写 `DB_BACKEND=memory`。`/health` 的 `sessionBackend` 读到 `memory` ⇒ 这台没落库。能力位 `store.degradedReason` 的词 `db_unreachable` 随之退役(只剩 `local_unwritable`)。
+
+**对象存储桶与 MinIO 镜像(sema-up 部署)**:引擎配了对象存储(`MINIO_*` 三键)而 `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)桶不存在,7.118.x 上起服绿、之后每分钟一条 404;本版起起服核一次、缺则在 `STORE_LOCK_WAIT_MS` 窗内重试后**拒启**。
+升级前:自己建桶的部署确认这只桶在(`mc mb <别名>/session-snapshots`)。sema-up 只有**新装、或重跑本版的 kube-up / cluster-up / sema-up.sh** 才建它;存量 sema-up 部署只做 `helm upgrade`(或只换引擎镜像)的,升级前先重跑本版脚本,或手工 `mc mb <别名>/session-snapshots`。同版 sema-up 的 MinIO 镜像从 `:latest` 钉成 `minio/minio:RELEASE.2025-09-07T16-13-09Z`(`imagePullPolicy: IfNotPresent`):
+存量部署升级前对一下正在跑的镜像(`kubectl -n sema get pod -l app=sema-minio -o jsonpath='{..imageID}'`),不同就 `--set minio.image=<正在跑的那一版>`。
+
+### 审批名单(`APPROVAL_REQUIRE`)的「本会话放行」恢复生效(订正 7.118.0 节第 13 条)
+
+1. **零操作**。7.118.0 节第 13 条说「升级前已落的『本会话放行』对 `APPROVAL_REQUIRE` 的卡失效」—— 本版起**恢复生效**:名单的问是本服务自己的问,
+   它的「本会话放行」记在会话豁免店里,名单门在出问之前读它;同一会话、同一工具命中 ⇒ 名单门不出卡。豁免店的形没有变:7.117.x 及更早落下、
+   7.118.x 期间留在店里的行原样生效,不迁移。不想让哪一行生效:`DELETE /v1/approvals/:sessionId/exemptions/<工具名>` 撤掉,或删会话。
+2. 名单卡上点「本会话放行」(活卡的 `allow_session` / `/decide` 的 `remember: "session"`)⇒ 记下:回执 `rememberApplied: true`,卡面不再带 `rememberRefused`。
+   卡上同时还有别的问(强制、治理、读会话目录外 ……)时照旧只放行这一次。
+3. **不变**:名单的问照样 `permissionMode: "bypassPermissions"` 放不掉、auto 模式的分类器答不了 —— 免问只来自这一会话里人说过的「本会话放行」;
+   `APPROVAL_NEVER_AUTO`、耐久预算耗尽、请求的 `settings.permissions.ask` / 存下的 ask 行铸的卡照旧记不住(`rememberApplied: false`)。
+4. **已知边界**:「本会话放行」只在读得到同一只豁免店的实例上生效(SQL 后端跨副本共享;`DB_BACKEND=local` 只在本机数据根)。
+   续跑落到读不到它的实例上 ⇒ 名单的问再问一次。
+5. **回滚到 7.118.x**:豁免行留在店里、在 7.118.x 上不生效(那一版的读法),零操作。
+
+### local 后端(`DB_BACKEND=local`):会话属主写进会话边档,跨重启保留
+
+1. **零操作**。`<数据根>/session-incarnations.json` 的每一格从「只有化身(一个串)」扩成「化身 + 属主」(`{ "incarnation": …, "owner": … | null }`);
+   本版只在新建 / 登记 / 认领 / 导入时写新形,7.118.x 留下的旧格原样可读(读作「属主没被记下」)。不要手改这只文件:它是严格读的,形不对整只拒。
+2. **升级窗内的认领**:7.118.x 及更早建的会话没有记下属主,读作无主(它的会话规则读不了也改不了:`409 conflict.session_ownerless`)。
+   升级之后在窗内**第一次带 principal 提交任务**到这只会话(壳的 `--resume` 就是),它被认领给那个 principal(日志一行 info `session_owner_claimed`),
+   之后它的规则照常读写。窗的日期见 `plugins/one-time-migrations.ts` 登记表 M10(由本版的发布准备提交回填);窗关之后不再认领,没被认领的存量会话一直读作无主 ——
+   要清它的规则就删会话(`DELETE /v1/sessions/:id`,规则随之删)。
+3. **回滚到 7.118.x**:旧版读不懂新形的格(严格读 ⇒ 会话操作整只拒,拒句点名这只文件)。回滚前先把每一格改回只有化身的串
+   (`{ "<id>": { "incarnation": "T", "owner": … } }` → `{ "<id>": "T" }`;属主随之丢失,即 7.118.x 本来的行为)。
+
+### 引擎 7.45.0(随本版提货):审批与删除的五处行为变化
+
+1. **删除受保护位置一律要人答**:`rm` / `rmdir` 的目标是文件系统根、顶层目录、家目录、任务根 / 工作目录 / 附加工作目录或它们的祖先(含 `rm -rf *` 在任务根、`rm -rf ~/*`),
+   或 shell 拿到的是运行时才拼出的脚本(`bash -c "$CMD"`、`sh -c "$(…)"`、`eval "$(…)"`)—— 任何模式(含 `bypassPermissions`)、任何 allow(请求 `settings.permissions.allow` 的
+   `Bash` / `Bash(rm:*)`、`APPROVAL_GRANT`、存下的 allow 行、技能清单、PreToolUse hook 的 allow)、`auto` 的分类器都清不掉,出一张要人的卡(`askClass: "dangerous_delete"`);
+   没人答就拒(无人值守腿按部署政策拒,`run-local` 无终端时只指终端)。**升级前核查**:靠 `rm -rf *` / `rm -rf <任务根>` 清场、或在 bypass 下跑运行时拼出的 `bash -c` 的脚本化部署,
+   改成按名删(`rm -rf ./build ./dist`)或安排人答卡。没有旋钮放行这一类。已知边界:喂给 shell 标准输入的脚本(`bash <<'EOF' … EOF`、`echo … | bash`)这一版仍按旧判据
+   (`default` 出卡、bypass 放行)。
+2. **`roots` 读面 × `auto`:根外的 shell 读出卡,不再交分类器**。单用户 turnkey 部署缺省 `READ_FACE=open`,不受影响;多租户部署(设了 `REQUIRE_PRINCIPAL`、没设 `READ_FACE`
+   ⇒ 引擎缺省 `roots`)与显式 `READ_FACE=roots` 的部署上,`auto` 档的 `cat <根外文件>`、放不进根的拼法(heredoc 提交说明、变量路径)从分类器自动放行变成一张卡(与 `default`
+   同一张;没人在就拒)。要分类器继续答 ⇒ 显式 `READ_FACE=open`。生效来源见 `GET /v1/diagnostics/wiring` 的 `readFace.source`。
+3. **子代 `agents[].denyTools` 拼错的名字不再让 run 失败**:没有工具叫这个名字(`Bahs`)⇒ 照跑,运维日志一行 `runner_config_advisory`(计数 `runner_config_advisory_total`)
+   点名它 —— 那一条 deny 没生效。`Tool(content)` 形(`Edit(src/**)`)⇒ 整只工具对该子代藏起并同样告一行。仍开跑前拒(`config.agent.unknown_tool`)的:带空白 / 不可见字符的条目、
+   非字符串条目。**退役拼法(`bash`)与大小写孪生(`BASH`)在本服务的部署形上也只告不拒**(7.118.x 上开跑前拒):本服务的委派工具带逐次注入的 extraTools,引擎开跑前列不全子代工具池,
+   不把像 `Bash` 的名字判成拼错;引擎给出宿主声明名册的座后这两形回到开跑前拒。**升级前核查**:把「拼错就失败」当校验的调用方改看那一行告警;靠子代 `denyTools` 藏 shell / 写工具的请求改用会话策略
+   `toolDeny` 或部署 deny 规则 —— `denyTools` / `allowTools` 只约束委派池里的工具,带手的子代自带的 Read / Write / Edit / Bash 不受它约束(写 `"Bash"` 也藏不住;引擎后续版本一张表盖全)。
+4. **沙箱 / 设备车道上的 `//` 绝对形路径规则对相对路径生效**:这些车道上请求规则编译时没有任务根,此前一条 `Read(//w/proj/secrets/**)` 的 deny / ask 对 `secrets/k`、
+   `./secrets/k` 这类相对拼法不生效;现在按引擎在每条调用上带的根 / 工作目录解析(拒就拒、问就问)。调用上也没有根(无文件手的腿)⇒ 一张 `rule_unreadable` 卡
+   (`bypassPermissions` 带理由放行)。相对形的规则模式(`Read(src/**)`)在这些车道上仍 422。
+5. **工具名里带不可见字符(零宽、软连字符、双向控制符 …)的条目读成文法错**:`APPROVAL_GRANT` 里有这种条目 ⇒ 拒启;技能 `disallowedTools` 里有 ⇒ 提交 400、
+   存量停驻体续跑 409(`resume_blocked_by_policy`)—— 升级前照 7.117.0 节跑排空判据 `skill-deny-inert`(它同数这一形);请求 `settings.permissions.allow` 里有 ⇒ 开跑时一帧
+   `permission.allowed_tool_not_granted`(`reason: "grammar"`)。拒句里那个字符看不见,指引句点名「invisible or control character」。
+
+### 接口面
+
+- **`400 rules.legacy_tool_name` 的体顶层多一键 `guidance`**(`PUT /v1/sessions/:id/policy`、同步导入的 `policy` 面):引擎判官对这一条的改法指引原句(退役名 / 对端段铸不出的
+  协议名带;无协议前缀的 `__` 名不带)。句子字节不变。对拒体做精确键集比对的客户端放宽一键。
+- **运维 warn `memory_store_form_refused` 的 `form`** 只取引擎闭集里的词(`symlink` / `file` / `other`);闭集外的值不再写进这一行。409 码与句子不变。
+- **嵌入方直接调引擎的 `steerPriorityOf` / `injectionLaneOf`**:档位不是 `now` / `next` / `later`(`null`、别的词、数字)现在抛 `steering.invalid_content`(此前原样返回,`null` 读作 `next`);
+  只有缺席读作 `next`。本服务的受理口与停驻 steer 列读回都不会把档外值交给它。
+- **嵌入方自装 `Runner` 只给静态 `executionEnv`(没有 `executionEnvFactory`)**:委派的 `isolation: "worktree"` 现在在建任何东西之前拒(`isolation.unavailable`),
+  不再在调用方自己的根里跑子代。本服务的主车道带工厂,不受影响。
+- **`council_done` 事件与 code-review 工具结果 `details.council`**:`lenses` / `perLens` 只含成功的镜头,失败的镜头移到新键 `failedLenses: [{ lens, reason }]`(键恒在,无失败 ⇒ `[]`);
+  对 `perLens` 键集或 `lenses` 计数做精确比对的消费方更新(此前失败镜头在 `perLens` 里是一条 `tokens: 0` 的行)。
+- **请求面 `permissionMode` 多一词 `dontAsk`**(闭集 = 引擎 `PERMISSION_MODES` 全集,受理后原样投引擎);能力位 `permissionModes` 给全集,壳按位发词;词表外拒句的成员表多 `dontAsk`。
+- **退役键 `settledBy` 的 `400 request.body_shape`**(live `/respond`、耐久 ask 账、`/decide` 三条决定口)体顶层多一键 `field: "settledBy"`,三口同一句;壳按码 + `field` 判,不锚文案。
+
 ## 7.118.0 —— 审批决定体的出处位 `decidedBy`(取代 `settledBy`)· 能力位 `approvalDecidedBy` · 有审批名单却无检查点店的装配,任务提交一律 501
 
 **审批决定体用一只键说「谁做的这个决定」**:`decidedBy?: "person" | "policy"`(缺席 = `"person"`)。三条工具审批决定口 ——

package/README.md

@@ -189,7 +189,7 @@ The server is configured entirely through environment variables. The most import
 | `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | unset | **SSH lane host-key verification** (`REMOTE_EXEC=ssh` only). `SSH_HOST_FINGERPRINT` = the host key's SHA256 base64 fingerprint (`SHA256:` prefix and `=` padding both optional); `SSH_KNOWN_HOSTS` = a path to a `known_hosts` file, matched literally on `host` / `[host]:port`. **Either one present ⇒ strict verification, a mismatch REFUSES the connection** (the error carries both fingerprints plus an `ssh-keyscan` line); both set ⇒ both must pass. **Both unset ⇒ a loud per-connection warning (`ssh_host_key_unverified`, man-in-the-middle risk) and the connection proceeds** — the deliberate posture for the batch-deploy lane, registered as a P-DEBT fail-open (`docs/FAIL-OPEN-CENSUS.md`). A malformed fingerprint or an unreadable `known_hosts` path **refuses to start**. Not supported in `known_hosts`, on purpose: hashed (`\|1\|…`) lines, wildcard patterns, `@cert-authority` — all skipped, so a host whose only entries are those is REFUSED (`@revoked` is honored and wins over any plain line, whatever the order) |
 | `HOOKS_TIMEOUT_MS` | unset (engine default 600000) | Per-invocation time bound for every hook seat (core `Hooks.timeoutMs`). Unset = the engine's own default (this server does not copy upstream defaults). `0` is honored as written (every seat expires immediately). A non-integer, negative, or above-`setTimeout`-ceiling (2147483647) value **refuses to start** |
 | `CONFIG_PROVIDER` | unset | Config source: `local` (file-backed `config.d/`, single machine) / `remote` (registry control plane). Closed set, matched exactly (7.104.0+): any other value (wrong case, surrounding spaces) refuses to boot; empty = unset |
-| `DEFAULT_SCENARIO` | `code` | Default scenario when the request body names none |
+| `DEFAULT_SCENARIO` | `code` | Default scenario when the request body names none; must be a scenario this deployment has (boot refuses otherwise) |
 | `SANDBOX_PKG_SOURCE` | `global` | Package sources inside sandboxes: `global` (official upstreams) / `cn` (China mirrors) / `custom` / `none` |
 | `SENSITIVE_WRITE_PATTERNS` | core's recommended set | Sensitive-path write deny list; comma-separated value replaces the set, `off` **or an empty value** disables. Applied unconditionally at the governance layer (independent of client permission mode, lane or settings presence) — including on the `run-local` leg. A value that cannot compile into a guard set (e.g. `/`, a pattern with no path segment) refuses to start |
 | `WRITE_PROTECTED_EXTRA` | unset (engine default table) | **Adds** rows to core's write-protection table (the literal-name table whose hit demotes a surviving `allow` to `ask` on Write/Edit/NotebookEdit). Comma-separated bare names (a bare name matches ANY path segment; a name containing `/` matches a consecutive segment run) or a JSON array of `"name"` strings / `{name, kind}` rows (`kind`: `basename` \| `segment` \| `segment-run`). The value is composed as `[...WRITE_PROTECTED_DEFAULT_TABLE, …]`, so **no default row can be lost**. Unset = no seat is wired = the engine's default table is in force (this server never copies that table). Form discrimination is by content, not by first character: a value containing any JSON structural character (`[ ] { } "`) is parsed as JSON and **must** be a top-level array (a missing pair of brackets refuses to start instead of being split into junk bare names). An empty value, a malformed entry (glob metacharacter, unknown kind, kind/name mismatch) or setting this together with `WRITE_PROTECTED_TABLE_REPLACE` **refuses to start**. Read faces: `GET /v1/capabilities` → `writeProtection.{armed,rows,replaced}`; `GET /v1/diagnostics/wiring` → `writeProtection.{rows,source,droppedDefaultRows}` (operator-only) |

package/README.zh-CN.md

@@ -162,7 +162,7 @@ curl -s localhost:8090/v1/tasks -H "Authorization: Bearer <SERVICE_AUTH_TOKEN>"
 | `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS` | 未设 | **SSH 通道主机密钥校验**(仅 `REMOTE_EXEC=ssh`)。前者 = 主机公钥的 SHA256 base64 指纹(`SHA256:` 前缀与 `=` 填充都可选);后者 = `known_hosts` 文件路径,按 `host` / `[host]:port` **逐字**匹配行。**任一在场 ⇒ 严格校验,不符即拒连**(拒因带两半指纹 + `ssh-keyscan` 取指纹指路一行);两只同时在场 ⇒ 合取(都要过)。**两只全缺席 ⇒ 每连接一条响亮 warn(`ssh_host_key_unverified`,中间人风险)后照常连** —— 批量部署通道的既定姿态,已登记为 P-DEBT fail-open(`docs/FAIL-OPEN-CENSUS.md`)。指纹拼错 / `known_hosts` 路径读不到 ⇒ **启动即拒**。`known_hosts` 里**刻意不支持**:hashed(`\|1\|…`)行、通配符 pattern、`@cert-authority` —— 一律跳过,于是只有这些条目的主机会被**拒连**(`@revoked` 照常生效,且无论写在哪一行都优先于普通匹配行) |
 | `HOOKS_TIMEOUT_MS` | 未设(引擎缺省 600000) | 每一只 hook 席位**单次调用**的时间上限(core `Hooks.timeoutMs`)。未设 = 用引擎自己的缺省(本服务不复制上游默认值)。`0` **按字面生效**(每个席位立即到期)。非整数 / 负数 / 超 `setTimeout` 上限(2147483647)⇒ **启动即拒** |
 | `CONFIG_PROVIDER` | 未设 | 配置来源:`local`(单机文件 `config.d/`)/ `remote`(registry 控制面)。闭集、逐字比较(7.104.0 起):其余任何值(大小写不同、带首尾空白)拒启;空串 = 未设 |
-| `DEFAULT_SCENARIO` | `code` | 请求体未指定场景时的缺省场景 |
+| `DEFAULT_SCENARIO` | `code` | 请求体未指定场景时的缺省场景;必须是本部署在册的场景名,否则拒启 |
 | `SANDBOX_PKG_SOURCE` | `global` | 沙箱内装包源:`global`(官方源)/ `cn`(国内镜像)/ `custom` / `none` |
 | `SENSITIVE_WRITE_PATTERNS` | core 推荐集 | 敏感路径写拒集;逗号分隔值为整体替换,`off` **或留空**关闭。在治理层无条件施加(与客户端权限模式/lane/settings 在场性无关),`run-local` 腿同样生效;编译不出守卫集的值(如 `/`)启动即拒 |
 | `WRITE_PROTECTED_EXTRA` | 未设(引擎缺省表) | 给 core 的**写保护名表**加行(字面名表:命中即把幸存的 `allow` 降级成 `ask`,作用于 Write/Edit/NotebookEdit)。逗号分隔裸名(裸名匹配**任意路径段**,含 `/` 的名匹配连续段)或 JSON 数组(`"name"` 串 / `{name, kind}` 行,`kind`:`basename` \| `segment` \| `segment-run`)。值按 `[...core 缺省表, …]` 组合,**丢不掉任何缺省行**。未设 = 不铸座 = 引擎缺省表在岗(本仓从不复制那张表)。两形按**内容**判而不是猜首字符:值里出现 JSON 结构字符(`[ ] { } "`)即按 JSON 解析,且顶层**必须是数组**(少写一对方括号 ⇒ 拒启,而不是被拆成垃圾裸名静默收下)。空值 / 坏值(通配符、未知 kind、kind 与名字段数矛盾)/ 与 `WRITE_PROTECTED_TABLE_REPLACE` 同时设置 ⇒ **启动即拒**。读面:`GET /v1/capabilities` 的 `writeProtection.{armed,rows,replaced}`;`GET /v1/diagnostics/wiring` 的 `writeProtection.{rows,source,droppedDefaultRows}`(operator-only) |

package/USAGE.md

@@ -51,9 +51,10 @@ docker compose up --build --scale service=4     # 4 个无状态 worker，nginx
 > 而 `DB_BACKEND` 缺省 ⇒ 探的是 mysql)。修前这三形**静默跑内存**(什么都不设是 local 文件持久,加一族坐标反而落到内存)。坐标被用到的存量形
 > (`SESSION_BACKEND=mysql|auto` + MYSQL 坐标、不写 `DB_BACKEND`)照旧起服;「不用坐标」是显式表态的(`DB_BACKEND=memory|local`、
 > `SESSION_BACKEND=memory`)也不拒。拒句点名在场的坐标键、为什么没人用、三条出路:要持久 `DB_BACKEND=pg|mysql`(或 `SESSION_BACKEND=mysql`);
-> 要内存 去掉坐标或 `DB_BACKEND=memory`;要尽力而为 `SESSION_BACKEND=auto` 并把引擎指对(`DB_BACKEND=pg` 配 `PG_HOST`)。本仓两份 compose
-> 显式带 `DB_BACKEND=mysql`。同版:`DB_BACKEND=mysql|pg` 显式而 `SESSION_BACKEND` 不许降级时店打不开,拒句同样点名 `DB_BACKEND=<引擎>` 与
-> `SESSION_BACKEND=auto` 出路(修前只有驱动的一句 `connect ECONNREFUSED …`)。持久化姿态读面:caps `store`(附录 B)。
+> 要内存 去掉坐标或 `DB_BACKEND=memory`。本仓两份 compose
+> 显式带 `DB_BACKEND=mysql`。同版:`DB_BACKEND=mysql|pg` 显式而店打不开,拒句点名 `DB_BACKEND=<引擎>`(修前只有驱动的一句 `connect ECONNREFUSED …`)。
+> 🔴 **7.119.0 起 `SESSION_BACKEND=auto` 配了坐标而库连不上同样拒启,不再有「auto 内存起服」这条出路**:`auto` = 「配了该引擎的坐标就是那只库(boot 期窗内重试、到窗拒启),没配就是内存」,
+> 由配置决定、不由起库成败决定;内存部署写 `DB_BACKEND=memory` 或 `SESSION_BACKEND=memory`。`GET /health` 的 `sessionBackend` 如实说装好的后端(`durable(pg)` / `memory`)。持久化姿态读面:caps `store`(附录 B)。
 
 > 🔴 7.96.0 起根 `docker-compose.yml` 的 `REMOTE_EXEC`(执行车道)是**必填**:不设 ⇒ `docker compose config` 当场失败(此前静默起成一个没有手的 worker)。单人自用 `REMOTE_EXEC=host`(手落在 worker 容器里);多人 / 生产选隔离车道 `e2b`(配 `E2B_API_KEY`)或 `k8s`(配 `K8S_SANDBOX_IMAGE`)。
 
@@ -537,6 +538,8 @@ MODEL_CASCADE_LADDER=deepseek-flash,deepseek-pro   # 目录里的模型名,cheap
   🔴 **两条取数据根的路是同一条腿、同一只旋钮**:HTTP 服务的 local 臂与 `run-local`(一次性 CLI)共用
   同一只等待腿 —— **不为前台形留第二套语义**。前台形要「立刻告诉我谁占着」就设 `STORE_LOCK_WAIT_MS=0`,
   那是文档化的通道,而不是两条路各有一套默认。
+  🔴 **同一只窗 7.119.0 起也管「已配置的 SQL 库此刻连不上」**:`DB_BACKEND=mysql|pg`(含 `SESSION_BACKEND=auto`)boot 期开不了店 ⇒ 窗内每 250ms 重试、到窗拒启(点名后端与 host:port;
+  永久错如凭据 / DDL 权限也拖到窗尾才拒,要当场拒设 `0`)。k8s 清单里库与 server 同时起,所以清单把窗给到 `300000`。
   ⚠️ **裸 boot(没有显式 `DB_BACKEND`)那一形的时序也跟着变**:它的锁冲突走的不是拒启而是既有的
   「退回内存并 warn」降级臂(`store_db_unreachable_fallback_memory`),所以第二只实例此前**当场**降级、
   现在要**等满窗**才降级 —— 方向仍是好的(窗内拿到就用上真数据根,而不是静默丢掉持久面),但它是一次
@@ -859,12 +862,18 @@ UNATTENDED_APPROVAL_POLICY=park
 
 **「本会话不再询问」对引擎的问也生效(7.106.0 起)**
 
-- 审批面 `POST /v1/approvals/:sessionId/decide {decision:"approve", remember:"session"}` 与活卡的 `allow_session` 记下的放行,两处兑现:
-  本服务自己的 `ordinary` 类问(`run_workflow` 问句、acceptEdits 的域外写)在它们自己的层上不再问;**引擎自己的问**(`default`
-  模式下的每一次写、证不了只读的 shell 命令)由服务的**审批席**(工具审批协调器)在下一次到达时代答。后一半要审批席在场:
+- 审批面 `POST /v1/approvals/:sessionId/decide {decision:"approve", remember:"session"}` 与活卡的 `allow_session` 记下的放行,两处兑现 —— **谁问的,谁读它的答案**:
+  本服务自己的问在它们自己的层上、出问之前读,命中就不问:`APPROVAL_REQUIRE` 名单的问(7.119.0 起;卡面带「本会话放行」,回执 `rememberApplied:true`,
+  同一会话下一次调用名单门不出问,引擎看到的只是「这次调用没出问」)、`run_workflow` 问句、acceptEdits 的域外写;**引擎自己的问**(`default`
+  模式下的每一次写、证不了只读的 shell 命令、没人表态的服务器工具)由服务的**审批席**(工具审批协调器)在下一次到达时代答。后一半要审批席在场:
   `TOOL_APPROVAL_ENABLED` 开(多租户缺省关);不想要活卡(纯 park 部署)再配 `STREAM_ASK_WINDOW_MS=0`。
-- 代答不到的:`APPROVAL_DENY` / 敏感路径守卫(是拒,不是问);`APPROVAL_REQUIRE` 名单的问(`ask_rule` 类 —— 引擎的类表说 allow 层清不掉它,站着的答案同读;每次照问,回执 `rememberApplied:false`;要免问就把工具移出名单或开自动批额度);`APPROVAL_NEVER_AUTO` 与耐久预算耗尽的问(「恒问人」,回执 `rememberApplied:false`);
+  名单的问在引擎眼里仍是 `ask_rule`:`permissionMode: "bypassPermissions"` 放不掉、auto 模式的分类器答不了 —— 免问只来自这一会话里人亲口说过的「本会话放行」。
+- 代答不到的:`APPROVAL_DENY` / 敏感路径守卫(是拒,不是问);`APPROVAL_NEVER_AUTO` 与耐久预算耗尽的问(「恒问人」,回执 `rememberApplied:false`);
+  人写的 ask 规则(请求的 `settings.permissions.ask`、存下的 ask 行 —— 引擎的问,类表说站着的答案清不掉,回执 `rememberApplied:false`);
   委派子代经父链继承到祖先席上的引擎问(引擎盖强制位,席依约不代答)。
+- 已知边界:「本会话放行」记在本部署的会话豁免店(SQL 后端跨副本共享;`DB_BACKEND=local` 只在这台机器的数据根里)。续跑落到另一台**读不到这只店**的
+  实例上(local 车道换机 / 换数据根)⇒ 名单的问再问一次 —— 方向是多问一次,不是静默放行。名单靠别名命中的调用(嵌入方给工具挂了 `Bash` 别名)
+  按调用的 wire 名记、按 wire 名读;一张卡上同时有名单的问与别人的问(人写的 ask 规则、强制位、读会话目录外 ……)⇒ 那张卡的「本会话放行」不记。
 
 **无人值守腿:`default` 模式 + 按类作答的审批席(7.109.0 起;S-934 / S-906)—— 没有旋钮**
 
@@ -1392,7 +1401,7 @@ bake-runner 要用 ⇒ `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW` 点名放回。
 | `sessionId` | — | 续聊:带上次返回的 `sessionId`,服务端自动 wake 历史 |
 | `images` | — | 图文输入 `[{data,mimeType}|{url}]`(模型需支持 vision) |
 | `attachmentIds` | — | D-1 通用文件上传(1.289+):先 `POST /v1/attachments?name=…`(raw body,content-type=mime)拿句柄,提交时引用 ≤16 个;文件物化到执行环境工作目录 `attachments/` 下,objective 尾部自动追加文件清单(内容不进会话流)。单文件缺省 ≤32 MiB(`ATTACHMENT_MAX_BYTES`);可配 mime 白名单(`ATTACHMENT_MIME_ALLOWLIST` CSV,缺省不限);上传后未引用的按 `ATTACHMENT_UNBOUND_TTL_MS`(缺省 24h)回收。**云形态(tidb/pg)字节本体存对象存储——MinIO 必配**(`MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY`,与快照 lane 同一组变量),未配则附件面 501;local 形走本地文件店。 |
-| `scenario` | — | 省略时取本部署的 `DEFAULT_SCENARIO`(工厂缺省场景名 = **`code`**——CC 编码 persona 蒸馏版,default 全量工具面,终验旋钮独立;`default` 场景**已非出厂缺省**,要用它须显式传 `scenario:"default"`,或部署方显式设 `DEFAULT_SCENARIO=default`)。可选内建名:`default`(通用/助理场景,域中性 persona,CC agent loop 全量工具面)/ `code-review`(见 §5)/ `scan`(同 §5 的 repo 只读工具但**中性无框架提示词**——objective+中心下发 skill 全权主导输出,OA 扫描类用;与 `code-review`/`discuss` 同属 clone-free 无执行环境场景,见 §5 末)/ **配置控制面可声明任意新场景**(`{name, toolset: none\|repo-readonly, prompt?}`,组合即配置、能力写死在部署;restart-to-apply;center 可覆盖内建名,boot 日志 `config_center_scenarios.shadowsBuiltin` 可审计) |
+| `scenario` | — | 省略时取本部署的 `DEFAULT_SCENARIO`(工厂缺省场景名 = **`code`**——CC 编码 persona 蒸馏版,default 全量工具面,终验旋钮独立;`default` 场景**已非出厂缺省**,要用它须显式传 `scenario:"default"`,或部署方显式设 `DEFAULT_SCENARIO=default`)。可选内建名:`default`(通用/助理场景,域中性 persona,CC agent loop 全量工具面)/ `code-review`(见 §5)/ `scan`(同 §5 的 repo 只读工具但**中性无框架提示词**——objective+中心下发 skill 全权主导输出,OA 扫描类用;与 `code-review`/`discuss` 同属 clone-free 无执行环境场景,见 §5 末)/ **配置控制面可声明任意新场景**(`{name, toolset: none\|repo-readonly, prompt?}`,组合即配置、能力写死在部署;restart-to-apply;center 可覆盖内建名,boot 日志 `config_center_scenarios.shadowsBuiltin` 可审计)。**缺省与指派都必须是本部署在册的场景名,悬空不回落 `default`**:`DEFAULT_SCENARIO` 不在册 ⇒ **起服拒**(拒句点名那个名字与在册词表);中心按主体指派的场景名本部署没有 ⇒ 该主体的 run 答 **503 `state.scenario_assignment_unknown`**(体 `detail: { scenario, source: "ruling" }`,不带 `Retry-After`;修法 = 中心改指派,或把那个场景加回本部署,然后原样重试);请求体显式给的未知名仍是 400 `scenario_unknown` |
 | `repo` / `council` / `debate` | — | `repo` 为 `code-review`/`scan` 必填;`council`/`debate` 仅 `code-review`,见 §5 |
 | `systemPrompt` / `appendSystemPrompt` | — | 调用方自带的系统提示 / 追加段(各 ≤16384 字符,超限 400 `request.field_invalid`;`appendSystemPrompt` 必须非空串)—— 任务自带时优先于角色 / 全局缺省(见 §模型角色) |
 | `model` | — | 本次用哪个模型:只能点服务端**已配置目录**里的名字 / 档位词 / 模型 id(目录见 `GET /v1/models`;请求体带不进新模型)。未知 ⇒ 400 `request.unknown_reference`(带 `available` 列表);目录里有、但本部署服务不了 ⇒ 400 `request.model_unavailable`;空串 / 非字符串 ⇒ 400 `request.field_invalid` |
@@ -1516,7 +1525,7 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 ## 7. 其它接口(按需)
 | 端点 | 用途 |
 |---|---|
-| `GET /v1/sessions/<id>` | 审计回溯:当前上下文 + 摘要(owner 校验) |
+| `GET /v1/sessions/<id>` | 审计回溯:当前上下文 + 摘要(owner 校验);消息里模型 / 工具产出的文本与 live 帧、账本帧同一只脱敏(密钥形换占位,其余字节不变) |
 | `GET /v1/approvals?owner=user:42` | 高危写审批(durable,需 `DURABLE_APPROVAL=true`):**operator** 看待办队列(可按 owner 过滤);非 operator 只看自己的 |
 | `POST /v1/approvals/<sessionId>/decide` `{"decision":"approve"|"deny","reason":"…"}` | 批/否并恢复挂起任务(CAS,重复决议 409);**仅 operator**(非 operator → 403)。5.0.0 起旧轮询腿 `POST /v1/approvals/<id>` 已退役 |
 | `GET /v1/agents/roster` | 后台 agent **名册**(7.29 起,需 durable background-agent store,否则 501 `capability.background_agent_store_required`):调用方自己 scope 的 `a…` 行,新→旧。行只带 `handle`/`name`/`agentType`/`status`/`spawnedAt`/`updatedAt`/`settledAt`(content-free;子代产物正文走 `GET /v1/runs/<id>/subagents/<handle>/output`)。查询:`?limit=`(1..100,默认 20)、`?before=`(上一页的 `nextBefore` 游标)、`?status=`(running\|parked\|completed\|failed\|killed)、`?session=`(按会话树窄化)、`?scope=`(**仅** service-token/单用户形;带 principal 的调用方锁定自己)。回体 `{agents,total,nextBefore?,truncated?}`;`truncated:true` = 租户行数超过名册窗(500),`total` 此时是窗内数。非属主的行**不出现也不计数**(无存在性 oracle) |
@@ -1866,7 +1875,11 @@ tag 词表与每条的最坏后果见 `docs/FAIL-OPEN-CENSUS.md`。引擎装配
 (core 给宿主定级的判别词;词表外原样透传并标 `classificationKnown:false`),指标 `runner_config_advisory_total`
 按 `code` / `classification` / `level` 打标;其中 `shell-gate-off` 在本 session 显式声明 `permissionMode:
 "bypassPermissions"` 时是调用方要的姿态,降为 **info** 并标 `expected`——只有没表态落到引擎默认 off 的无壳直连
-形才 warn。
+形才 warn。子代 `agents[].denyTools` / `allowTools` 的**名字**也归引擎开跑前一只判、同落这一行:无人挂的名只告不拒;退役拼法 / 大小写孪生(`bash` / `BASH`)
+**开跑前拒**(`config.agent.unknown_tool`;委派工具声明了逐次注入工具的名册,引擎列得出子代工具池),名字按工具名原拼写 `Bash`。这两张表管子代手里的**全部**
+工具 —— 委派池与内建 hands(`Read` / `Edit` / `Write` / `NotebookEdit` / `Bash` / `Grep` / `Glob` …):`denyTools:["Write"]` ⇒ 子代没有 `Write`;`allowTools` 只列
+调用方工具 ⇒ 子代一只内建 hands 工具都没有(要什么就点名什么)。内建只读子代(Explore / Plan)没有 `Edit` / `Write` / `NotebookEdit`。hands 之外的引擎工具(`Monitor`
+等)仍不受这两张表管;要按路径 / 命令拦而保留工具,写调用方权限策略的 deny 规则。
 
 🔴 **`shell-gate-off` 这条注的语义自 7.73.0(core 7.15.0)起收窄,文案由引擎改写**:`off` 档**不再**意味着
 「这条会话的 shell 完全没有门」。**读边界**(内建读拒表 + 工作区容纳面)现在**每一档都判**,`shellGate` 只管
@@ -1986,7 +1999,7 @@ GET /v1/capabilities?permissionMode=default
 ```
 
 - `armed`:按上式此刻会不会武装(`?permissionMode=` 折进本次意图;查询串缺席 = 按 auto 意图答「若请求会不会武装」;
-  五词之外 400 `request.field_invalid`)。
+  core 闭集之外 400 `request.field_invalid`)。
 - `reason`(未武装时,闭集**六词**,判序即武装式合取序):`mode_not_auto`(意图不是 auto)/ `deployment_incapable`
   (装配面没挂分类器席位——生产装配恒挂,桩与一次性 CLI 不挂)/ `org_denied`(`caps.autoMode === false`:center 显式 deny、
   center 硬失败 fail-closed 拒项)/ `local_denied`(本地旋钮 `PERMISSIONS_DISABLE_AUTO_MODE=true`,改本机 env)/ `settings_denied`
@@ -2258,10 +2271,10 @@ server 进程(HTTP 服务与 `run-local`)**所有走 undici 的出网跳**都认
   `tag`(本地 tag 在、tag 树的版本对)→ `precheck`(registry 上本版在不在;读不出 ⇒ 红,不盲发)→ `token` → `clone`(干净 tag 树 =
   `git clone --depth 1 --branch v<v> file://<仓>`)→ `npm-ci` → `prepublish`(`npm run prepublishOnly`)→ `pack` → `publish`(**在 tag 树目录里**
   `npm publish --ignore-scripts`)→ `readback-wait`(轮询 registry 至多 20 min)→ `readback-shasum`(dist.shasum = 本地 tarball 的 sha1)→
-  `readback-bytes`(curl 回读 tarball,与本地 `cmp` 逐字节同)→ `githead`(registry 的 gitHead = tag commit)。脚本钉 `umask 022`(文件权限进 tar 头,
+  `readback-bytes`(curl 回读 tarball,与本地 `cmp` 逐字节同;**传输失败**在 `readback-wait` 用的同一只窗里重试、窗满才红,**字节差**不重试、立即红,两种红句分开说)→ `githead`(registry 的 gitHead = tag commit)。脚本钉 `umask 022`(文件权限进 tar 头,
   换 umask 重跑会 pack 出另一份字节);每次 registry 请求有硬上限(60 s),回读等待另有 20 min 墙钟截止,registry 挂住不会挂死链。成功尾行
   `PUBLISH v=<v> shasum=<sha1> gitHead=<sha> bytes=<n> readback=identical`(发车帖 / CHANGELOG 回填 shasum 与 gitHead 从这里取);任一步红 ⇒
-  `PUBLISH-FAIL v=<v> step=<步骤>` + 非零退出 + 一句点名步骤的红因。
+  `PUBLISH-FAIL v=<v> step=<步骤>` + 非零退出 + 一句点名步骤的红因(红因与步骤行同走 stdout,链日志里步骤行之后紧跟)。
   - **幂等**:registry 上已有本版 ⇒ 不重发,只做回读比对 —— 与本地 pack 逐字节同且 gitHead 对 ⇒ 绿并说「已在」;不同 ⇒ 红(别人发的字节,版本不可覆盖)。
     门 3.5 红了(tag 已推):修好后单独重跑 `bash scripts/publish-local.sh <v>`,再前台跑 `bash scripts/post-publish-gates.sh <v>`。
     **手跑的前置**:两只脚本开头都封口,封口要 import `@sema-agent/core`(封口的判据 = core `scrubSecretEnv`)⇒ 在本树装着依赖的前提下跑

package/deploy/sema-up/README.md

@@ -133,6 +133,8 @@ data-center:2c/2G/20G)以下 BLOCK——确实无法稳定部署,提前警告不
 - **registry**:`SEMA_REGISTRY_IMAGE`(GHCR/Hub 的 `sema-registry` 镜像,迁移中,公开仓匿名可拉;
   SWR 已弃用;仅换 private 仓时才需 k8s 路径凭据=env `IMAGE_PULL_USER`/`IMAGE_PULL_TOKEN`)。
 - 公共镜像(postgres/minio/gitea)直接拉;国内网络不通时配 dockerd `registry-mirrors`。
+- **MinIO**:钉死的 tag(`minio/minio:RELEASE.…`,chart / cluster 静态清单 / compose 三份同值;k8s `imagePullPolicy: IfNotPresent`,不再 `:latest` + `Always`)。换源 = 换整条引用:
+  compose 与 kube-up 读环境变量 `MINIO_IMAGE`(kube-up 给了才递给 chart),chart 直接 `--set minio.image=<源>/minio/minio:<tag>`(预灌镜像的节点 `--set minio.pullPolicy=Never`)。
 
 ## 凭据纪律
 

package/deploy/sema-up/chart/templates/minio.yaml

@@ -37,7 +37,8 @@ spec:
     spec:
       containers:
         - name: minio
-          image: {{ .Values.minio.image }}
+          image: {{ .Values.minio.image | quote }}
+          imagePullPolicy: {{ .Values.minio.pullPolicy }}
           args: ["server", "/data", "--console-address", ":9001"]
           env:
             - name: MINIO_ROOT_USER

package/deploy/sema-up/chart/templates/server-v4pro.yaml

@@ -32,6 +32,7 @@ spec:
             - { name: PORT, value: "8090" }
             - { name: DB_BACKEND, value: pg }
             - { name: SESSION_BACKEND, value: auto }
+            - { name: STORE_LOCK_WAIT_MS, value: {{ .Values.server.storeWaitMs | quote }} }
             - { name: PG_HOST, value: sema-pg-rw.{{ .Release.Namespace }}.svc }
             - { name: PG_PORT, value: "5432" }
             - { name: PG_USER, value: sema }

package/deploy/sema-up/chart/templates/server.yaml

@@ -43,6 +43,7 @@ spec:
             - { name: PORT, value: "8090" }
             - { name: DB_BACKEND, value: pg }
             - { name: SESSION_BACKEND, value: auto }
+            - { name: STORE_LOCK_WAIT_MS, value: {{ .Values.server.storeWaitMs | quote }} }
             - { name: PG_HOST, value: sema-pg-rw.{{ .Release.Namespace }}.svc }
             - { name: PG_PORT, value: "5432" }
             - { name: PG_USER, value: sema }

package/deploy/sema-up/chart/values.yaml

@@ -26,7 +26,10 @@ pg:
     bucket: s3://sema-pg-backup/
 
 minio:
-  image: minio/minio:latest
+  # 钉死的 tag(不用 `:latest`:k8s 对它的缺省拉取策略是 Always,每次 Pod 重建都拉「今天恰好是什么」)。换国内源 = 换整条引用
+  # (`--set minio.image=<源>/minio/minio:<tag>`,同 server.image / gitea.image 的形);cluster 静态清单与 compose 默认写同一个 tag(测试咬合)。
+  image: minio/minio:RELEASE.2025-09-07T16-13-09Z
+  pullPolicy: IfNotPresent   # tar 预灌=Never(同 server.pullPolicy)
   storageSize: 200Gi
   storageClass: longhorn
   rootUser: sema
@@ -37,6 +40,9 @@ server:
   pullPolicy: IfNotPresent   # tar 预灌=Never
   replicas: 3
   nodePort: 30890
+  # 引擎 boot 期等库的窗(ms,env STORE_LOCK_WAIT_MS):CNPG 与 server Pod 同时起、库初始化常慢于 server 就绪 ——
+  # 窗内重试、到窗仍连不上才拒启(拒启后 kubelet 重拉;引擎不会再退成内存起服)。0 = 第一次失败就拒。
+  storeWaitMs: 300000
   serviceAuthToken: ""   # REQUIRED
   modelGatewayBaseurl: ""  # REQUIRED
   modelId: ""              # REQUIRED

package/deploy/sema-up/cluster-up.sh

@@ -31,6 +31,10 @@ unset _self _hops _dir
 . "$HERE/lib/shell-access.sh"
 # 取值旗的形(S-621):判据与词表同 sema-up.sh 一处定义。
 . "$HERE/lib/flagshape.sh"
+# 引擎 /health 体里「落在哪个后端」的读法与期望值(smoke.sh / kube-up.sh 同一只)。
+. "$HERE/lib/health.sh"
+# 对象存储桶的唯一表(sema-up.sh / kube-up.sh / smoke.sh 同读这一张)。
+. "$HERE/lib/buckets.sh"
 log() { printf '[cluster-up] %s\n' "$*" >&2; }
 die() { log "⛔ $*"; exit 1; }
 
@@ -419,8 +423,9 @@ PY
 # 凭据清单经 stdin 直接 apply,不落远端盘(落 /tmp 失败时会残留)
 rrun 0 k3s kubectl apply -f - < "$RENDERED" >/dev/null
 fi
-rsudo 0 <<'EOF'
+rsudo 0 $(buckets_prefixed local/ $(buckets_k8s)) <<'EOF'
 set -e
+BUCKETS=("$@")   # 要建的桶(local/<桶>):清单只在 lib/buckets.sh 一处,经位置参数递给远端
 # runner token 跨 ns 复制要赶在 server 起 pod 前(晚了=CreateContainerConfigError 干等——真踩);
 # SA token secret 由控制器异步填充,先等它有值
 TOK=""
@@ -431,6 +436,12 @@ done
 [ -n "$TOK" ] || { echo "sema-runner-token 未被控制器填充" >&2; exit 1; }
 k3s kubectl create secret generic sema-runner-token-copy -n sema --from-literal=token="$(printf '%s' "$TOK" | base64 -d)" \
   --dry-run=client -o yaml | k3s kubectl apply -f - >/dev/null
+# MinIO 建桶(备份桶+引擎桶)—— 排在等 PG healthy 与等 server rollout **之前**:引擎起服会核快照桶在不在,桶缺时 server 不就绪、rollout 永远等不到,而建桶又排在它后面 ⇒ 互等;
+# MinIO 不依赖 PG,建桶也就不必陪着等 PG(冷启拉镜像 + init 可要几分钟,会把引擎的等桶窗耗掉)
+k3s kubectl rollout status deployment/sema-minio -n sema --timeout=300s >/dev/null
+PW=$(k3s kubectl get secret sema-minio -n sema -o jsonpath='{.data.rootPassword}' | base64 -d)
+k3s kubectl exec deploy/sema-minio -n sema -- sh -c \
+  "mc alias set local http://localhost:9000 sema '$PW' >/dev/null && mc mb --ignore-existing ${BUCKETS[*]}" >/dev/null
 # PG healthy(冷启拉镜像+init 可要几分钟)
 for t in $(seq 1 120); do
   s=$(k3s kubectl get cluster sema-pg -n sema -o jsonpath='{.status.phase}' 2>/dev/null || true)
@@ -438,24 +449,25 @@ for t in $(seq 1 120); do
 done
 [ "$s" = "Cluster in healthy state" ] || { k3s kubectl get cluster -n sema; echo "PG 未达 healthy" >&2; exit 1; }
 k3s kubectl rollout status deployment/sema-server -n sema --timeout=300s >/dev/null
-# MinIO 建桶(备份桶+对象桶)
-PW=$(k3s kubectl get secret sema-minio -n sema -o jsonpath='{.data.rootPassword}' | base64 -d)
-k3s kubectl exec deploy/sema-minio -n sema -- sh -c \
-  "mc alias set local http://localhost:9000 sema '$PW' >/dev/null && mc mb --ignore-existing local/sema-pg-backup local/workspaces local/blobs" >/dev/null
 echo STACK_OK
 EOF
 
 # ── 8. smoke(节点内经 NodePort;外网入口=LB 在云商侧配,打印指引)────────────────
 log "8/8 smoke"
 # NodePort 被 nodeport-addresses 钉在节点网段——loopback 不在其内,必须打 node-ip(真踩 curl exit 7)
-SMOKE=$(rsudo 0 <<EOF
-H=\$(curl -m5 -s -o /dev/null -w '%{http_code}' "http://$K3S0_IP:$NODEPORT/health" || echo 000)
+# 第一行 = 两个 HTTP 码,其后 = /health 体(后端位在里面:200 + 401 测不出「服务在内存里跑」,验收必须读那一位)
+SMOKE_OUT=$(rsudo 0 <<EOF
+HB=\$(curl -m5 -s -w '\n%{http_code}' "http://$K3S0_IP:$NODEPORT/health" || printf '\n000')
+H="\${HB##*\$'\n'}"
 A=\$(curl -m5 -s -o /dev/null -w '%{http_code}' "http://$K3S0_IP:$NODEPORT/v1/runs" || echo 000)
 echo "health=\$H auth=\$A"
+printf '%s' "\${HB%\$'\n'*}"
 EOF
 )
+SMOKE="${SMOKE_OUT%%$'\n'*}"
 case "$SMOKE" in *"health=200 auth=401"*) : ;; *) die "smoke 失败:$SMOKE(期望 health=200 auth=401)" ;; esac
-log "smoke ✓ $SMOKE"
+BK_WHY=$(health_backend_check "${SMOKE_OUT#*$'\n'}") || die "smoke 失败:$BK_WHY。下一步:kubectl -n sema logs deploy/sema-server(引擎在库没连上时不会再退内存起服 —— 它会拒启;读到 memory 多半是旧镜像)"
+log "smoke ✓ $SMOKE backend=$SEMA_UP_EXPECT_SESSION_BACKEND"
 cat >&2 <<EOF
 
 ══════════ cluster-up 完成($MACHINE_COUNT 节点)══════════

package/deploy/sema-up/kube-up.sh

@@ -9,7 +9,7 @@
 # 输入(sema-up.sh 注入;也可单独跑):
 #   WORK(状态目录)PROJECT REGION KUBE_MODE [KUBECONFIG_PATH] [DRY_RUN]
 #   USERS REGISTRY_ENABLED GIT_MODE [GIT_URL GIT_TOKEN]
-#   SEMA_SERVER_IMAGE(必需)[SEMA_REGISTRY_IMAGE][GITEA_IMAGE]
+#   SEMA_SERVER_IMAGE(必需)[SEMA_REGISTRY_IMAGE][GITEA_IMAGE][MINIO_IMAGE(整条引用,换国内源用;缺省 = chart 钉死的 tag)]
 #   MODEL_GATEWAY_BASEURL MODEL_ID MODEL_API_KEY
 #   [NAMESPACE=sema][STORAGE_CLASS=集群默认][CNPG_VERSION]
 set -euo pipefail
@@ -33,6 +33,10 @@ unset _self _hops _dir
 . "$HERE/lib/shell-access.sh"
 # 取值旗的形(S-621):判据与词表同 sema-up.sh 一处定义。
 . "$HERE/lib/flagshape.sh"
+# 引擎 /health 体里「落在哪个后端」的读法与期望值(smoke.sh / cluster-up.sh 同一只)。
+. "$HERE/lib/health.sh"
+# 对象存储桶的唯一表(sema-up.sh / cluster-up.sh / smoke.sh 同读这一张)。
+. "$HERE/lib/buckets.sh"
 log() { printf '[kube-up] %s\n' "$*" >&2; }
 die() { log "⛔ $*"; exit 1; }
 
@@ -214,6 +218,7 @@ helm_values() { # helm_values <giteaBaseUrl> <oauthId> <oauthSecret>
   V_REG_PW="${REGISTRY_ADMIN_PASSWORD:-}" V_REG_SS="${REGISTRY_SESSION_SECRET:-}" V_REG_PT="${REGISTRY_PULL_TOKEN:-}" \
   V_GITEA_ENABLED="$([ "$GIT_MODE" = provision ] && echo true || echo false)" \
   V_GITEA_IMAGE="${GITEA_IMAGE:-gitea/gitea:1.24}" V_NODE_IP="$NODE_IP" \
+  V_MINIO_IMAGE="${MINIO_IMAGE:-}" \
   python3 - <<'PY'
 import json, os
 e = os.environ
@@ -244,6 +249,8 @@ v = {
   "gitea": {"enabled": e["V_GITEA_ENABLED"] == "true", "image": e["V_GITEA_IMAGE"],
             "storageClass": e["V_SC"], "domain": e["V_NODE_IP"]},
 }
+# MinIO 镜像:给了才递(默认只在 chart values.yaml 写一处,不在脚本里再抄一份);国内源 = 整条引用
+if e["V_MINIO_IMAGE"]: v["minio"]["image"] = e["V_MINIO_IMAGE"]
 print(json.dumps(v))
 PY
 }
@@ -317,6 +324,12 @@ done
 [ -n "$TOK" ] || die "sema-runner-token 未被控制器填充。下一步:kubectl -n sema-sandbox get secret,sa"
 printf '%s' "$TOK" | base64 -d | $KUBECTL create secret generic sema-runner-token-copy -n "$NAMESPACE" \
   --from-file=token=/dev/stdin --dry-run=client -o yaml | $KUBECTL apply -f - >/dev/null
+$KUBECTL rollout status deployment/sema-minio -n "$NAMESPACE" --timeout=300s >/dev/null
+# MinIO 建桶(幂等;备份桶+引擎桶,清单只在 lib/buckets.sh 一处)。引擎起服会核快照桶在不在,所以建桶排在等 PG healthy 与等 server rollout 之前
+# (MinIO 不依赖 PG;PG 冷启可要几分钟,不该把引擎的等桶窗耗掉)
+$KUBECTL exec deploy/sema-minio -n "$NAMESPACE" -- sh -c \
+  "mc alias set local http://localhost:9000 sema \"\$MINIO_ROOT_PASSWORD\" >/dev/null && mc mb --ignore-existing $(buckets_prefixed local/ $(buckets_k8s))" >/dev/null \
+  || die "MinIO 建桶失败。下一步:kubectl -n $NAMESPACE logs deploy/sema-minio"
 # PG healthy(冷启拉镜像+init 可要几分钟)
 s=""
 for t in $(seq 1 120); do
@@ -324,11 +337,6 @@ for t in $(seq 1 120); do
   [ "$s" = "Cluster in healthy state" ] && break; sleep 5
 done
 [ "$s" = "Cluster in healthy state" ] || { $KUBECTL get cluster -n "$NAMESPACE" >&2 || true; die "PG 未达 healthy。下一步:kubectl -n $NAMESPACE describe cluster sema-pg;PVC Pending 时查 StorageClass"; }
-$KUBECTL rollout status deployment/sema-minio -n "$NAMESPACE" --timeout=300s >/dev/null
-# MinIO 建桶(幂等;备份桶+对象桶)
-$KUBECTL exec deploy/sema-minio -n "$NAMESPACE" -- sh -c \
-  "mc alias set local http://localhost:9000 sema \"\$MINIO_ROOT_PASSWORD\" >/dev/null && mc mb --ignore-existing local/sema-pg-backup local/workspaces local/blobs local/backups" >/dev/null \
-  || die "MinIO 建桶失败。下一步:kubectl -n $NAMESPACE logs deploy/sema-minio"
 $KUBECTL rollout status deployment/sema-server -n "$NAMESPACE" --timeout=600s >/dev/null || die "sema-server 未就绪。下一步:kubectl -n $NAMESPACE logs deploy/sema-server(常见:镜像拉取失败→imagePullSecrets/私仓凭据)"
 
 # ── Gitea 引导(provision:管理员/token/OAuth app;全部 in-pod 动作,不依赖 NodePort 可达)──
@@ -379,30 +387,35 @@ fi
 
 # ── smoke(port-forward 直验——kind/远程 kubeconfig 下 NodePort 对本机不可达,别靠它)──
 log "5/6 smoke"
-smoke_pf() { # smoke_pf <svc> <port> <path> → http code
-  local pf_pid code
+smoke_pf() { # smoke_pf <svc> <port> <path> → 第一行 http code,其后是响应体(调用方按需取)
+  local pf_pid out code body
   $KUBECTL port-forward "svc/$1" -n "$NAMESPACE" "1$2:$2" >/dev/null 2>&1 &
   pf_pid=$!
   sleep 2
-  code=$(curl -m5 -s -o /dev/null -w '%{http_code}' "http://127.0.0.1:1$2$3" || echo 000)
+  out=$(curl -m5 -s -w '\n%{http_code}' "http://127.0.0.1:1$2$3" || printf '\n000')
   kill $pf_pid 2>/dev/null; wait $pf_pid 2>/dev/null || true
-  printf '%s' "$code"
+  code="${out##*$'\n'}"; body="${out%$'\n'*}"
+  [ "$out" = "$code" ] && body=""   # 没有换行 = 只有码(假 curl / 空体)
+  printf '%s\n%s' "$code" "$body"
 }
-H=$(smoke_pf sema-server 8090 /health)
+HR=$(smoke_pf sema-server 8090 /health)
+H="${HR%%$'\n'*}"
 [ "$H" = "200" ] || die "smoke 失败:server /health=$H(期望 200)。下一步:kubectl -n $NAMESPACE logs deploy/sema-server"
-A=$(smoke_pf sema-server 8090 /v1/runs)
+# /health 200 ≠ 数据落了库:后端位必须是期望的持久后端(durable(pg));读到 memory = 服务在内存里跑、重启即丢,不许判绿
+BK_WHY=$(health_backend_check "${HR#*$'\n'}") || die "smoke 失败:$BK_WHY。下一步:kubectl -n $NAMESPACE logs deploy/sema-server(引擎在库没连上时不会再退内存起服 —— 它会拒启;读到 memory 多半是旧镜像)"
+A=$(smoke_pf sema-server 8090 /v1/runs); A="${A%%$'\n'*}"
 [ "$A" = "401" ] || die "smoke 失败:无 token /v1/runs=$A(期望 401=auth 门在)。SERVICE_AUTH_TOKEN 未生效=裸奔,立刻查"
 R="n/a"
 if [ "$REGISTRY_ENABLED" = "true" ]; then
-  R=$(smoke_pf sema-registry 3000 /api/healthz)
+  R=$(smoke_pf sema-registry 3000 /api/healthz); R="${R%%$'\n'*}"
   [ "$R" = "200" ] || die "smoke 失败:registry healthz=$R。下一步:kubectl -n $NAMESPACE logs deploy/sema-registry"
 fi
 G="n/a"
 if [ "$GIT_MODE" = "provision" ]; then
-  G=$(smoke_pf sema-gitea 3000 /api/healthz)
+  G=$(smoke_pf sema-gitea 3000 /api/healthz); G="${G%%$'\n'*}"
   [ "$G" = "200" ] || die "smoke 失败:gitea healthz=$G"
 fi
-log "smoke ✓ health=$H auth=$A registry=$R gitea=$G"
+log "smoke ✓ health=$H backend=$(health_session_backend "${HR#*$'\n'}") auth=$A registry=$R gitea=$G"
 
 # ── summary(一屏;凭据一次性显示)────────────────────────────────────────────────
 log "6/6 完成"
@@ -414,7 +427,7 @@ log "6/6 完成"
   echo "           本机不可达 NodePort 时(kind/远程):kubectl -n $NAMESPACE port-forward svc/sema-server 8090:8090"
   # 壳对 NodePort 的明文 http 按设计拒连(非回环要 https)⇒ 经 port-forward 带到本机回环再 connect。
   shell_access_text "$ENVF" "装了 kubectl、能连这个集群的机器上:" "kubectl -n $NAMESPACE port-forward svc/sema-server 8090:8090" "http://127.0.0.1:8090"
-  echo " 数据      CNPG sema-pg×$PG_INSTANCES($PG_AA)+ MinIO(桶:workspaces/blobs/backups/sema-pg-backup)"
+  echo " 数据      CNPG sema-pg×$PG_INSTANCES($PG_AA)+ MinIO(桶:$(buckets_k8s | tr ' ' '/'))"
   if [ "$REGISTRY_ENABLED" = "true" ]; then
     echo " 配置中心  NodePort 30300 → http://$NODE_IP:30300"
     if $NEW_REG_PW; then echo "           首登:${REGISTRY_ADMIN_USER:-zhaoheran} / ${REGISTRY_ADMIN_PASSWORD}(⚠ 只显示这一次,之后看 .env)"

package/deploy/sema-up/lib/buckets.sh

@@ -0,0 +1,21 @@
+# lib/buckets.sh — 部署侧「要预置哪些对象存储桶」的唯一表。sema-up.sh(compose 建桶 / 外接 S3 建桶 / 汇总)、kube-up.sh、cluster-up.sh(k8s 建桶)与
+# smoke.sh(验桶)都读这一张,不各写一份串:各写一份的下场是清单漏一只桶,而漏桶的症状是起服后每一次对象写 / 每一拍 sweep 都 404。
+#
+# server **不建桶**(docs/DEPLOY-PREREQS.md「对象存储桶」),引擎起服只核一次快照桶在不在、不在就拒启 —— 所以这张表必须包含引擎要用的每一只:
+#  · `session-snapshots` = 引擎的 `SESSION_SNAPSHOT_BUCKET` 缺省名(snapshot-BLOB offload + SendUserFile 私有 presigned 轨 / 沙箱 staging);
+#    由测试把这个名与引擎的缺省逐字咬合(引擎改缺省而这里没跟 ⇒ 红);
+#  · `sema-public`(SendUserFile 永久公链轨)**不在表里**:它要匿名 GetObject-only 策略,是运维另配的桶,脚本不替人开匿名读。
+SEMA_UP_ENGINE_BUCKETS="workspaces blobs backups session-snapshots"
+# CNPG 的 WAL 归档 / 每日基备桶(只有 k8s 两条路径有 PG 备份;名与 chart values 的 `pg.backup.bucket: s3://<名>/` 同名,由测试咬合)。
+SEMA_UP_PG_BACKUP_BUCKET="sema-pg-backup"
+
+# buckets_k8s → 打印 k8s 路径(kube-up / cluster-up)要建的全部桶,空格分隔,每只一次。
+buckets_k8s() { printf '%s %s' "$SEMA_UP_PG_BACKUP_BUCKET" "$SEMA_UP_ENGINE_BUCKETS"; }
+
+# buckets_prefixed <前缀> <桶…> → 每个桶名前加前缀(mc 的 `<别名>/<桶>` 写法),空格分隔。桶名是 S3 闭字符集,不含空白,按空白拆是安全的。
+buckets_prefixed() {
+  local p="$1" b out=""
+  shift
+  for b in "$@"; do out="$out$p$b "; done
+  printf '%s' "${out% }"
+}