@sema-agent/server 7.125.1 → 7.127.0

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

@@ -29,16 +29,16 @@ unset _self _hops _dir
 # <<< 自身目录
 # `.env` 文法(写口 envf_representable + envf_encode / 读口 envf_canonical_line)的唯一定义 —— 写读两半从这一处取判据。
 . "$HERE/lib/envf.sh"
-# 数据根归属(S-851)与「壳怎么接」的渲染(S-850)各一处定义;preflight / kube-up / cluster-up 读同一份。
+# 数据根归属与「壳怎么接」的渲染各一处定义;preflight / kube-up / cluster-up 读同一份。
 . "$HERE/lib/dataroot.sh"
 . "$HERE/lib/shell-access.sh"
-# 取值旗的形(S-621):判据与词表(--profile / --users / --region / --git / --kube)的唯一定义;--help 的词表也从这里渲。
+# 取值旗的形:判据与词表(--profile / --users / --region / --git / --kube)的唯一定义;--help 的词表也从这里渲。
 . "$HERE/lib/flagshape.sh"
 # 对象存储桶的唯一表(kube-up.sh / cluster-up.sh / smoke.sh 同读这一张)。
 . "$HERE/lib/buckets.sh"
 # 日志一律打到 stderr(stdout 留给 --interactive=json 的协议行)。定义在最前面:参数一解析完就要判形,那时下面的函数都还没定义。
 log() { printf '[sema-up] %s\n' "$*" >&2; }
-# 执行车道表的唯一读者(S-599)。定义在**最前面**:`--help` 的词表也从表渲(手抄的词表会在加一条
+# 执行车道表的唯一读者。定义在**最前面**:`--help` 的词表也从表渲(手抄的词表会在加一条
 # 车道时静默分叉),而 `-h` 在参数循环里就被处理,那时后面的函数还没定义。
 lanes() { python3 "$HERE/lib/lanes.py" "$@"; }
 MODE_INTERACTIVE="tty"       # tty | json | none(--yes)
@@ -148,14 +148,14 @@ if [ -n "$CONF" ]; then
   esac
 fi
 
-# ── 取值旗的形(S-621;判据与词表单一属主 lib/flagshape.sh)─────────────────────────────────────────────
+# ── 取值旗的形(判据与词表单一属主 lib/flagshape.sh)─────────────────────────────────────────────
 # 一条规则:每只取值旗都过形判,在建任何目录、写任何文件之前(工作目录 ~/.sema-up/<project> 就建在这一段的下一行)。
 # 判的是**生效值**:命令行旗 ∪ -f 配置(env 形的 -f 在命令行之后 source,同名变量盖过旗 ⇒ 称呼里连变量名一起报)。
 # bool / enum 的空 = 没给(走缺省或询问);命令行上写了 `--旗=` 却没给值 ⇒ 不是没给,照判(空串不在任何闭集里)。
 # 交互答案由 ask() 判(必须是那道题的选项之一)。自由文本旗(URL / 镜像引用 / 路径 / 凭据 / 模型 id)不判,盘点见 README。
 _empty_flags=" "; for a in "$@"; do case "$a" in --*=) _empty_flags="$_empty_flags${a%=} " ;; esac; done
 flag_given() { case "$_empty_flags" in *" $1 "*) return 0 ;; esac; [ -n "$2" ]; }
-# 项目名是 compose 项目名,也是工作目录与自动数据根的一段路径(S-851):`..` / `/` / 空串会把两者指到别处。
+# 项目名是 compose 项目名,也是工作目录与自动数据根的一段路径:`..` / `/` / 空串会把两者指到别处。
 flag_project "--project(PROJECT)" "$PROJECT"
 if flag_given --profile "$PROFILE"; then flag_enum "--profile(PROFILE)" "$PROFILE" $FLAG_WORDS_PROFILE; fi
 if flag_given --users "$USERS"; then flag_enum "--users(USERS)" "$USERS" $FLAG_WORDS_USERS; fi
@@ -182,8 +182,8 @@ flag_bool "--teardown-volumes(TEARDOWN_VOLUMES)" "$TEARDOWN_VOLUMES"
 flag_bool "--skip-preflight(SKIP_PREFLIGHT)" "$SKIP_PREFLIGHT"
 flag_enum "--interactive=json / --yes(MODE_INTERACTIVE)" "$MODE_INTERACTIVE" $FLAG_WORDS_INTERACTIVE
 WORK="$HOME/.sema-up/$PROJECT"; mkdir -p "$WORK"; chmod 700 "$HOME/.sema-up" "$WORK"
-# 凭据/配置文件的坐标(S-599 提到这里:车道决策要在模型面之前读既有 .env)。**读写原语全在 lib/envf.sh**
-# (envf_get / envf_has / envf_load / envf_put / setk / setk_new / resetk,S-618):决策键严格读口、写口序列化、
+# 凭据/配置文件的坐标(提到这里:车道决策要在模型面之前读既有 .env)。**读写原语全在 lib/envf.sh**
+# (envf_get / envf_has / envf_load / envf_put / setk / setk_new / resetk):决策键严格读口、写口序列化、
 # 数据版回读都是那一处的同一套文法;本脚本只调用,不再自带任何一份。物理行假设由 up 之前的
 # `reconcile_render`(`docker compose config` 渲染对账,compose 唯一属主)兜底。
 ENVF="$WORK/.env"
@@ -194,7 +194,7 @@ ENVF="$WORK/.env"
 deploy_fact() {
   local k="$1" fenv fsh shsrc shset
   fenv="$(envf_get "$k")" || exit 1
-  # C(S-618):shell **导出为空串** ≠ shell 未设。compose 插值里 shell(即便是空串)优先于 --env-file,
+  # shell **导出为空串** ≠ shell 未设。compose 插值里 shell(即便是空串)优先于 --env-file,
   # 所以导出空会**盖掉** .env 的值 —— 必须按「有值 = 空」参与冲突判定,不许当缺席。`${k+x}` 区分两者。
   if eval "[ \"\${$k+x}\" = x ]"; then shset=1; eval "fsh=\"\${$k}\""; else shset=0; fsh=""; fi
   shsrc="${CONF:+-f $CONF / }shell 环境"
@@ -236,13 +236,13 @@ dc_argv() {
 }
 dc() { dc_argv; "${DC_ARGV[@]}" "$@"; }
 # compose 的全局参数(-p / --env-file / -f)只在这里拼一次(相对 `$HERE/stack`):up / config 走 compose()、teardown 的
-# down、渲染对账给运维的复现命令,都从同一张 COMPOSE_GLOBALS 取(S-646 ④:复现命令曾是手抄的第二份,漏了
+# down、渲染对账给运维的复现命令,都从同一张 COMPOSE_GLOBALS 取(复现命令曾是手抄的第二份,漏了
 # -f compose.dataroot.yaml 与 profile;teardown 是第三份)。数据根由调用方先定好 DATA_ROOT。
 compose_globals() {
   COMPOSE_GLOBALS=(--project-name "$PROJECT" --env-file "$ENVF" -f compose.yaml)
   if [ -n "$DATA_ROOT" ]; then COMPOSE_GLOBALS+=(-f compose.dataroot.yaml); fi
 }
-# compose 路径的「壳接入」(S-850):引擎口在这台机的回环上直连,别的机器 ssh 隧道到它的回环。dry-run 计划与汇总调同一只;
+# compose 路径的「壳接入」:引擎口在这台机的回环上直连,别的机器 ssh 隧道到它的回环。dry-run 计划与汇总调同一只;
 # 文本与 json 两形的接法同源(lib/shell-access.sh 渲)。<端口> = 这台部署真会用的引擎口。
 compose_shell_access_text() {
   shell_access_text "$ENVF" "引擎这台机上:" "" "http://127.0.0.1:$1" \
@@ -304,7 +304,7 @@ ask() {
       log "⛔ 选项 $ans 在本机不可行:${infpart%%|*};建议:${infpart#*|}"; exit 1
     fi
   done
-  # 有选项的题,答案必须是选项之一(S-621,与取值旗同一条规则:不在闭集里的词一律拒,不会落进「别的那一臂」)。
+  # 有选项的题,答案必须是选项之一(与取值旗同一条规则:不在闭集里的词一律拒,不会落进「别的那一臂」)。
   # 没有选项的题(网关 / 模型 id / 地址 / 凭据)是自由文本。
   if [ "$#" -gt 0 ]; then
     local hit=false words=""
@@ -320,7 +320,7 @@ emit() { [ "$MODE_INTERACTIVE" = "json" ] && printf '%s\n' "$1" >&3 || log "$2";
 if $TEARDOWN; then
   cd "$HERE/stack"
   if [ -f "$ENVF" ]; then
-    # 读 .env 一律经 lib 的严格读口(S-618 续):裸 grep|cut 会连编码形的单引号一起读出来。
+    # 读 .env 一律经 lib 的严格读口:裸 grep|cut 会连编码形的单引号一起读出来。
     # 数据根以 .env 登记的为准(卸载的是首装那一份,不看本次 --data-root);全局参数与 up 同一张表(compose_globals)。
     DATA_ROOT="$(envf_get DATA_ROOT_DIR)" || exit 1
     # 全 profile down 会对未启用服务也做 config 校验——.env 缺 SEMA_*_IMAGE(该面没开过)时
@@ -336,7 +336,7 @@ if $TEARDOWN; then
     fi
     log "已卸载 project=$PROJECT $($TEARDOWN_VOLUMES && echo '(含数据卷)' || echo '(数据卷保留:pgdata/miniodata/registrydata/gitdata)')"
     if $TEARDOWN_VOLUMES && [ -n "$DATA_ROOT" ]; then
-      # 删不删盘上文件看这条根归谁(S-851:标记是别的项目 / 没有标记 ⇒ 不教 rm -rf)。
+      # 删不删盘上文件看这条根归谁(标记是别的项目 / 没有标记 ⇒ 不教 rm -rf)。
       dataroot_teardown_hint "$DATA_ROOT"
     fi
   else log "没有找到 $ENVF,无可卸载"; fi
@@ -354,18 +354,18 @@ fi
   "local-plus:本机只跑 agent,连一个已经部署好的 data-center 数据面")
 # ── 两个决策(租户形 / 车道)同一条规则:决策 = 显式旗 ∨ 部署事实 ∨ 表缺省 ─────────────────────
 # 「部署事实」= 同一只 `$WORK/.env`:compose 的 agent 档由本脚本写,full-cluster 由 kube-up / cluster-up 在写凭据的同一处
-# 写(S-600;修前 kube 两条路径不落这条事实 ⇒ 不带旗重跑拿缺省 single 把多租部署降回单用户);data-center 不起 agent。事实 → 决策词只经属主翻译,本脚本不抄第二份:
+# 写(修前 kube 两条路径不落这条事实 ⇒ 不带旗重跑拿缺省 single 把多租部署降回单用户);data-center 不起 agent。事实 → 决策词只经属主翻译,本脚本不抄第二份:
 #   · REQUIRE_PRINCIPAL → --users:只认 sema-up 自己写出的两形 true / false(别的写法 ⇒ 拒;不复刻 server 的布尔词表);
 #   · REMOTE_EXEC → --sandbox:`lanes choice-of`(车道表是唯一属主;表里没有的落盘值 ⇒ 拒并列在役词),见车道块。
 # 不带旗重跑 ⇒ 沿用事实(多租部署重跑不必再带 --users=multi);显式旗与事实不一致 ⇒ fact_conflict 拒并点名两处。
 # 🔴 为什么缺省不能先于事实(合并复审两条真案):把表缺省当成意图去和事实比,合法的无旗重跑就被拒;
 # 反过来若只比不拒,保留的多租 `.env` 在缺省 single 下会被车道表判成 host —— 容器拿到 REQUIRE_PRINCIPAL=true ∧ host。
-# 租户形 ⇒ 容器上 REQUIRE_PRINCIPAL 的值:`principal_of_users`(lib/flagshape.sh,三只脚本共用的唯一定义;S-600 起 kube-up /
+# 租户形 ⇒ 容器上 REQUIRE_PRINCIPAL 的值:`principal_of_users`(lib/flagshape.sh,三只脚本共用的唯一定义;kube-up /
 # cluster-up 也调它)。正向(生成段 setk、事实核对)与反向(事实 → --users 缺省)都经它:反向是拿两个租户词逐个过这只函数去比,
 # 不另写一张反表(与车道的 `lanes choice-of` 同一姿势)。
 USERS_DEF="single" RP_FACT="" RP_FACT_SRC=""
 case "$PROFILE" in
-  # S-600:full-cluster 也读 —— kube-up / cluster-up 在写凭据的同一处把 REQUIRE_PRINCIPAL 落进同一只 .env(它们自己
+  # full-cluster 也读 —— kube-up / cluster-up 在写凭据的同一处把 REQUIRE_PRINCIPAL 落进同一只 .env(它们自己
   # 单独跑时也按同一条规则判,见 lib/flagshape.sh 的 users_decide)。
   full-single|local-plus|full-cluster)
     deploy_fact REQUIRE_PRINCIPAL; RP_FACT="$FACT_VAL" RP_FACT_SRC="$FACT_SRC"
@@ -403,7 +403,7 @@ if [ "$GIT_MODE" = "connect" ]; then
   [ -z "$GIT_TOKEN" ] && { [ "$MODE_INTERACTIVE" = "none" ] && { log "⛔ --git=connect 需要 --git-token(该服务的 access token)"; exit 1; } || GIT_TOKEN=$(ask git_token "该服务的 access token?" "" "验证连通用;Gitea 还会用它自动建 OAuth 登录应用"); }
 fi
 
-# ── 执行车道(S-599;单一属主 = lib/lanes.json,本脚本里零车道词字面量)──────────────────────
+# ── 执行车道(单一属主 = lib/lanes.json,本脚本里零车道词字面量)──────────────────────
 # 病:compose 路径的 `kata` / `runc` 对**执行运行时零接线**(有 KVM 时 kata 还是默认值)⇒ .env 里
 # 压根不出现 `REMOTE_EXEC` ⇒ core 落 StubExecutionEnv ⇒ 起来的 worker 一只手都没有,而三条部署
 # 路径没有任何一处会红。现在:词表 / 默认 / 退役指路 / 落 .env 的键值**全部**从表渲,拒一律非零退出。
@@ -486,7 +486,7 @@ if [ "$PROFILE" = "full-cluster" ]; then
     machines)
       [ "${MACHINE_COUNT:-0}" -ge 1 ] || { log "⛔ --kube=machines 需要 -f machines.yaml(机器清单);模板见 deploy/sema-up/machines.example.yaml"; exit 1; }
       $DRY_RUN && { log "dry-run:将经 cluster-up.sh 对 ${MACHINE_COUNT} 台机器做 k3s HA 装配(ssh)+ helm/render 装栈(users=$USERS);不执行"; exit 0; }
-      # S-600:租户形交给 cluster-up(修前不传 ⇒ 这条路径上的主 worker 恒单用户姿态,--users=multi 被静默丢)。
+      # 租户形交给 cluster-up(修前不传 ⇒ 这条路径上的主 worker 恒单用户姿态,--users=multi 被静默丢)。
       WORK="$WORK" REGION="$REGION" PROJECT="$PROJECT" USERS="$USERS" \
         MODEL_GATEWAY_BASEURL="$GATEWAY" MODEL_ID="$MODEL" MODEL_API_KEY="${MODEL_KEY:-${MODEL_API_KEY:-}}" \
         exec "$HERE/cluster-up.sh"
@@ -565,13 +565,13 @@ if [ "$REGION" = "auto" ]; then
   REGION=$(awk -v a="$t_cn" -v b="$t_gl" 'BEGIN{print (a<b)?"cn":"global"}')
 fi
 HOSTIP=$(host_ip)
-# E(S-618):进度日志只打**已校验的决策词**,不回显未过校验的原始输入(曾把带标记的 --registry 值抢先泄进 stderr,
-# test srv796 实测 NEW-5)。7.104.0 起(S-621)REGISTRY_ENABLED 在建工作目录之前已过形判(只会是 true / false,或空 =
+# 进度日志只打**已校验的决策词**,不回显未过校验的原始输入(曾把带标记的 --registry 值抢先泄进 stderr,
+# test srv796 实测 NEW-5)。7.104.0 起REGISTRY_ENABLED 在建工作目录之前已过形判(只会是 true / false,或空 =
 # 走档位缺省,缺省在上面已落定),registry 仍收成 on/off 决策词。region/profile/users/lane/git 到这里都已定死
 # (形判在参数解析之后、交互答案在 ask() 里、车道在车道块)。
 log "region=$REGION profile=$PROFILE users=$USERS sandbox=${SANDBOX_LANE:-n/a} lane=${LANE_REMOTE_EXEC:-n/a} registry=$([ "$REGISTRY_ENABLED" = "true" ] && echo on || echo off) git=$GIT_MODE"
 
-# ── 数据根(S-851:一条规则 —— 数据根归一个项目所有;判据全在 lib/dataroot.sh)───────────────────────────
+# ── 数据根(一条规则 —— 数据根归一个项目所有;判据全在 lib/dataroot.sh)───────────────────────────
 # 取哪条根:`.env` 首装值(已装的项目不漂移,不搬数据)∨ --data-root / -f 的 DATA_ROOT ∨ 多盘机自动选大容量盘
 # (<盘>/sema-data/<project>;macOS 不自动 —— bind 要经 VM 挂载,显式给了才用)。换盘 = 先 --teardown-volumes 迁数据,
 # 删掉 .env 的 DATA_ROOT_DIR 行,再带新 --data-root 重装。
@@ -707,7 +707,7 @@ if [ "$PROFILE" = "full-single" ] || [ "$PROFILE" = "local-plus" ]; then
   setk REQUIRE_PRINCIPAL "$REQUIRE_PRINCIPAL_WANT"
   setk SANDBOX_PKG_SOURCE "$([ "$REGION" = "global" ] && echo global || echo '')"
   [ -n "${SEMA_SERVER_IMAGE:-}" ] && setk SEMA_SERVER_IMAGE "$SEMA_SERVER_IMAGE"
-  # 执行车道落 .env(S-599:从上面 `lanes resolve` 的结果渲,脚本里零车道词)。
+  # 执行车道落 .env(从上面 `lanes resolve` 的结果渲,脚本里零车道词)。
   # **resetk 不是 setk**:`setk` 见键在就不改,而升级路径上最常见的既有值恰是空串 `REMOTE_EXEC=`
   # (旧 compose 的 `${REMOTE_EXEC:-}` 渲出来的)——用 setk 就永远修不好那批无手部署。冲突检测在
   # 上面的车道块里已做过(非空且不同 ⇒ 早已拒),所以这里的重写只会落在「空串 / 同值」两种情形上。
@@ -781,13 +781,13 @@ elif [ "$GIT_MODE" = "connect" ]; then
 fi
 
 # DATA_ROOT 落定(根在上面「数据根」块里已定、已判归属;首装写 .env 后为准 —— 重跑换值会造出一套空卷,数据看似丢失)。
-# 首装值经严格读口解码回读(S-618 续:路径含空格时写口落整值单引号形)。建根 / 卷目录 / 写项目标记都在 dataroot_settle 里。
+# 首装值经严格读口解码回读(路径含空格时写口落整值单引号形)。建根 / 卷目录 / 写项目标记都在 dataroot_settle 里。
 if [ -n "$DATA_ROOT" ]; then
   [ -n "$_stored" ] || setk DATA_ROOT_DIR "$DATA_ROOT"
   dataroot_settle "$DATA_ROOT"
 fi
 
-# A(S-618):`.env` 生成完毕 —— 把 setk 持久化的**生效端口**回读进 shell 变量(替代旧 source 的这半)。
+# `.env` 生成完毕 —— 把 setk 持久化的**生效端口**回读进 shell 变量(替代旧 source 的这半)。
 # 重跑省略端口旗时,容器绑定的是首装端口(.env),本脚本后续的 API 调用 / 健康检查 / 汇总必须用同一份;
 # 首装(或 .env 无该键)时回读跳过、保留 shell 缺省。凭据在各自用点单独回读(见下 envf_load)。
 envf_load SERVER_PORT PG_PORT MINIO_PORT MINIO_CONSOLE_PORT REGISTRY_PORT GIT_HTTP_PORT GIT_SSH_PORT
@@ -797,7 +797,7 @@ compose() { compose_globals; ( cd "$HERE/stack" && dc "${COMPOSE_GLOBALS[@]}" "$
 # shq —— 单引号引用一个词(复现命令要能原样粘贴:路径里可能有空格)。
 shq() { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"; }
 
-# ── D:渲染对账(S-618 的类闭环;生成 .env 之后、compose up 之前)──────────────────────────────────
+# ── 渲染对账(生成 .env 之后、compose up 之前)──────────────────────────────────
 # .env 的写口 / 读口都按物理行判,认不出 compose dotenv 的跨行引号值等边角;唯一能确知「容器真正拿到
 # 什么」的是 compose 自己。所以在 up 之前跑一次 `compose config`——与 up **同一组 -f / profile / 同一 shell
 # 环境**(于是运维导出的空串等也算进来)——从渲染结果取 agent 服务的 REQUIRE_PRINCIPAL / REMOTE_EXEC /
@@ -805,7 +805,7 @@ shq() { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"; }
 # docker 不可达在上面 `command -v docker` 那道已 fail-loud 拦下;config 本身失败(YAML/插值坏)也拒,
 # 不新铸降级臂:未经对账就不 up。只有 agent 面有这三个决策键,别的档跳过。
 #
-# 拒因分两种、各给各的出路(S-656;7.98.0 曾把 stderr 并进 stdout 当 JSON 解析 ⇒ compose 的任何警告都让它 traceback,
+# 拒因分两种、各给各的出路(7.98.0 曾把 stderr 并进 stdout 当 JSON 解析 ⇒ compose 的任何警告都让它 traceback,
 # 拒因还冒充「不一致」):
 #   · 渲染结果解析失败 —— compose 退出码非零,或退出 0 但 stdout 不是可解析的 compose JSON:没拿到渲染值,谈不上比对;
 #   · 渲染值与决策值不一致 —— 拿到了、逐值比对不上。
@@ -887,7 +887,7 @@ GIT_MANUAL_NOTES=()
 if [ "$GIT_MODE" = "provision" ]; then
   log "git 面:先起 Gitea(引导管理员/token/OAuth 要在 registry 之前)"
   COMPOSE_PROFILES=git compose up -d --wait git || { log "⛔ Gitea 起不来。下一步:docker compose -p $PROJECT logs git;镜像拉不动时 --gitea-image=<可达镜像仓>/gitea:1.24"; exit 1; }
-  # A(S-618):不 source .env —— 回读 sema-up 自己生成、没进 shell 变量的凭据(管理员账号/口令)。
+  # 不 source .env —— 回读 sema-up 自己生成、没进 shell 变量的凭据(管理员账号/口令)。
   envf_load GIT_ADMIN_USER GIT_ADMIN_PASSWORD
   GIT_CTR="${PROJECT}-git-1"
   GIT_API="http://127.0.0.1:${GIT_HTTP_PORT}/api/v1"
@@ -910,7 +910,7 @@ except Exception: print("")')
     [ -n "$TOK" ] || { log "⛔ Gitea access token 生成失败。下一步:curl -u <admin> $GIT_API/users/$GIT_ADMIN_USER/tokens 手查;或看 docker compose -p $PROJECT logs git"; exit 1; }
     setk GIT_ADMIN_TOKEN "$TOK"
   fi
-  envf_load GIT_ADMIN_TOKEN   # A:回读刚生成/已存的 token,不 source .env
+  envf_load GIT_ADMIN_TOKEN   # 回读刚生成/已存的 token,不 source .env
   # OAuth 接线只对它被创建时的 git 目标有效(锚 = REGISTRY_GITEA_BASE_URL):目标变了 ⇒ 上一目标的接线作废、
   # 本次重建(建不成 = registry 走表单登录),不把旧身份源静默带进这一次(车MH codex r2 [high],两条路径同一条规则)。
   envf_invalidate_unless REGISTRY_GITEA_BASE_URL "http://$HOSTIP:$GIT_HTTP_PORT" REGISTRY_GITEA_OAUTH_ID REGISTRY_GITEA_OAUTH_SECRET
@@ -937,7 +937,7 @@ except Exception: print("")')
     fi
   fi
 elif [ "$GIT_MODE" = "connect" ]; then
-  # A(S-618):不 source .env —— GIT_URL / GIT_TOKEN 就是本次命令行/‑f 传进来的 shell 变量,直接用。
+  # 不 source .env —— GIT_URL / GIT_TOKEN 就是本次命令行/‑f 传进来的 shell 变量,直接用。
   # (旧代码 source 是历史遗留:那时 source 会拿 .env 旧值盖掉命令行新值,故先 resetk 再 source 找回;
   #  不 source 之后新值本就在 shell 里,连这道找回都不需要了。)
   # 连通验证(fail-loud:接不上就别继续,别部署完才发现 git 面是死的)。
@@ -1004,12 +1004,12 @@ except Exception: print("")')
 fi
 
 # ── 装配(Layer 1 compose;profiles 映射形态) ────────────────────────────────────────────────
-# D(S-618):up 之前先 `compose config` 渲染对账 —— 容器真正拿到的决策键与本次决策逐值对齐才 up。
+# up 之前先 `compose config` 渲染对账 —— 容器真正拿到的决策键与本次决策逐值对齐才 up。
 reconcile_render
 log "装配:docker compose profiles=$COMPOSE_PROFILES project=$PROJECT"
 # 建桶(幂等,一次性动作归 Layer 0;只对本地 MinIO——外接 S3 已在连接检测时确保)。🔴 排在**全栈 up 之前**:引擎起服会核快照桶在不在
 # (缺则拒启),而 `up --wait` 要等引擎健康 —— 桶建在 up 之后,新数据卷上就是引擎等桶、compose 等引擎的互等。所以先只起 MinIO(`--wait` 等它健康)、建桶,再起全栈。
-envf_load MINIO_PASSWORD   # A:回读生成的 MinIO 口令(建桶用),不 source .env
+envf_load MINIO_PASSWORD   # 回读生成的 MinIO 口令(建桶用),不 source .env
 case ",$COMPOSE_PROFILES," in *,s3,*)
   COMPOSE_PROFILES="$COMPOSE_PROFILES" compose up -d --wait minio \
     || { log "⛔ MinIO 启动失败。下一步:docker compose -p $PROJECT logs minio(常见:镜像拉取失败→检查镜像引用/docker login)"; exit 1; }
@@ -1019,7 +1019,7 @@ COMPOSE_PROFILES="$COMPOSE_PROFILES" compose up -d --wait --remove-orphans \
   || { log "⛔ compose up 失败。下一步:docker compose -p $PROJECT logs(常见:镜像拉取失败→检查镜像引用/docker login;端口占用→--port 换口)"; exit 1; }
 
 # ── 验证(装后即验,§3d smoke 的子集;全量随时可跑 smoke.sh --project=$PROJECT)──────────────
-# A:回读验证 / 汇总要用的凭据与登记值(不 source .env);缺的键回读成空,由下游 :- 缺省处置。
+# 回读验证 / 汇总要用的凭据与登记值(不 source .env);缺的键回读成空,由下游 :- 缺省处置。
 envf_load MINIO_PASSWORD REGISTRY_ADMIN_USER REGISTRY_ADMIN_PASSWORD REGISTRY_GITEA_BASE_URL GIT_ADMIN_USER GIT_ADMIN_PASSWORD
 V_PG="n/a" V_BK="n/a"
 case ",$COMPOSE_PROFILES," in *,pg,*)
@@ -1045,7 +1045,7 @@ fi
 
 # ── 汇总(凭据打印一次;文件 0600 常驻;一屏读完)────────────────────────────────────────────
 if [ "$MODE_INTERACTIVE" = "json" ]; then
-  # 整行经 json.dumps 铸(S-850 同批):此前 printf 拼 JSON —— `health` 塞的是 /health 响应体的前 60 字节(自带双引号)、
+  # 整行经 json.dumps 铸:此前 printf 拼 JSON —— `health` 塞的是 /health 响应体的前 60 字节(自带双引号)、
   # 路径 / URL 里的引号与反斜杠也不转义 ⇒ 带 agent 的档这一行恒不是合法 JSON(本批加 `shellAccess` 时红格读出)。
   # 键名与取值口径逐字不变;`buckets` 是数字时仍是 JSON 数字(没建桶的档是串 "n/a",此前那一形同样不合法);
   # `shellAccess` = 壳接入(没有引擎的档为 null)。

package/deploy/sema-up/smoke.sh

@@ -18,9 +18,9 @@ done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
 # <<< 自身目录
-# `.env` 的文法与读原语只在 lib/envf.sh 定义(S-618 续):本脚本读 `.env` 只经 envf_load,不 source。
+# `.env` 的文法与读原语只在 lib/envf.sh 定义:本脚本读 `.env` 只经 envf_load,不 source。
 . "$HERE/lib/envf.sh"
-# 取值旗的形(S-621):判据同 sema-up.sh 一处定义。
+# 取值旗的形:判据同 sema-up.sh 一处定义。
 . "$HERE/lib/flagshape.sh"
 # 引擎 /health 体里「落在哪个后端」的读法与期望值(kube-up / cluster-up 的验收同一只)。
 . "$HERE/lib/health.sh"
@@ -44,7 +44,7 @@ fail() { printf '[FAIL] %s — %s\n      ↳ 建议:%s\n' "$1" "$2" "$3"; FAILS=
 if [ -n "$PROJECT" ]; then
   ENVF="$HOME/.sema-up/$PROJECT/.env"
   [ -r "$ENVF" ] || { echo "找不到 $ENVF(先跑 sema-up.sh)"; exit 1; }
-  # A(S-618 续):不 source .env(值里的 $() / 反引号 / ; 是数据,不是代码)—— 只经严格读口取本脚本用到的键;
+  # 不 source .env(值里的 $() / 反引号 / ; 是数据,不是代码)—— 只经严格读口取本脚本用到的键;
   # 读到非规范行(比如旧写口留下的裸 `$(…)`)⇒ 响亮拒并点名行号,不猜、不执行。
   envf_load SERVICE_AUTH_TOKEN DEPLOY_PROFILE SERVER_PORT MINIO_PASSWORD \
     AGENT_PG_HOST AGENT_PG_USER PG_PASSWORD AGENT_PG_PORT AGENT_PG_DATABASE AGENT_MINIO_ENDPOINT AGENT_MINIO_USER \

package/deploy/sema-up/stack/compose.yaml

@@ -96,7 +96,7 @@ services:
       SANDBOX_PKG_SOURCE: ${SANDBOX_PKG_SOURCE:-}
       # 执行车道:值由 sema-up.sh 从 lib/lanes.json 渲进 .env(resetk,每次重写)。
       # `REQUIRE_EXECUTION_LANE` 缺省 true —— 手工起这份 compose 而没点名车道时,server 拒启
-      # 并说「没有手」,而不是安静地起成一个什么都干不了的 worker(S-599)。
+      # 并说「没有手」,而不是安静地起成一个什么都干不了的 worker。
       REMOTE_EXEC: ${REMOTE_EXEC:-}
       REQUIRE_EXECUTION_LANE: ${REQUIRE_EXECUTION_LANE:-true}
       E2B_API_KEY: ${E2B_API_KEY:-}

package/deploy/sema-up/stack/sema-stack-cluster.yaml

@@ -92,7 +92,7 @@ kind: Service
 metadata: { name: sema-minio, namespace: sema }
 spec: { selector: { app: sema-minio }, ports: [{ name: s3, port: 9000 }, { name: console, port: 9001 }] }
 ---
-# ── 沙箱 lane RBAC(k8s+kata;测试机同款五动词)────────────────────────────────
+# ── 沙箱 lane RBAC(k8s+kata;测试机同款五动词 + 缓存卷 + 出网自检两只只读)────────────────────────────────
 apiVersion: v1
 kind: ServiceAccount
 metadata: { name: sema-runner, namespace: sema-sandbox }
@@ -118,6 +118,14 @@ rules:
   - apiGroups: [""]
     resources: [pods/log]
     verbs: [get]
+  # 按工作区空间的构建缓存卷(WORKSPACE_CACHE=volume):连沙箱时按名读、没有就建;空间结束(会话删除 / 留存 sweep)按标签回收
+  - apiGroups: [""]
+    resources: [persistentvolumeclaims]
+    verbs: [get, create, delete, deletecollection]
+  # 起服的出网自检读本 ns 的 NetworkPolicy(只读)
+  - apiGroups: [networking.k8s.io]
+    resources: [networkpolicies]
+    verbs: [get, list]
 ---
 apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
@@ -125,6 +133,21 @@ metadata: { name: sema-runner, namespace: sema-sandbox }
 roleRef: { apiGroup: rbac.authorization.k8s.io, kind: Role, name: sema-runner }
 subjects: [{ kind: ServiceAccount, name: sema-runner, namespace: sema-sandbox }]
 ---
+# 出网自检读节点表(集群级对象 ⇒ ClusterRole;只读两动词)。与 chart 的 sandbox-rbac.yaml 同形。
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata: { name: sema-runner-nodes-sema-sandbox }
+rules:
+  - apiGroups: [""]
+    resources: [nodes]
+    verbs: [get, list]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata: { name: sema-runner-nodes-sema-sandbox }
+roleRef: { apiGroup: rbac.authorization.k8s.io, kind: ClusterRole, name: sema-runner-nodes-sema-sandbox }
+subjects: [{ kind: ServiceAccount, name: sema-runner, namespace: sema-sandbox }]
+---
 # ── 引擎(3 副本跨机打散;镜像=节点预灌 sema-server:local,imagePullPolicy Never
 #    ⚠ k3s-uninstall.sh 会连 containerd 镜像一起清,重装过的节点必须补灌)──────────
 apiVersion: v1
@@ -172,11 +195,11 @@ spec:
             - { name: MODEL_ID, value: "__MODEL_ID__" }
             - { name: MODEL_API_KEY, valueFrom: { secretKeyRef: { name: sema-server-env, key: MODEL_API_KEY } } }
             - { name: MODEL_VISION, value: "false" }
-            # S-600:租户姿态与 chart 主 worker 同值(cluster-up 由 --users 渲:multi ⇒ true,否则 false);修前整块缺席 ⇒ 恒单用户
+            # 租户姿态与 chart 主 worker 同值(cluster-up 由 --users 渲:multi ⇒ true,否则 false);修前整块缺席 ⇒ 恒单用户
             - { name: REQUIRE_PRINCIPAL, value: "__REQUIRE_PRINCIPAL__" }
             - { name: SANDBOX_PKG_SOURCE, value: "__PKG_SOURCE__" }
             - { name: REMOTE_EXEC, value: k8s }
-            # S-599:显式表态「这台有手」(车道被改没了 ⇒ 拒启,不是安静的无手 worker)
+            # 显式表态「这台有手」(车道被改没了 ⇒ 拒启,不是安静的无手 worker)
             - { name: REQUIRE_EXECUTION_LANE, value: "true" }
             - { name: K8S_API_URL, value: "https://kubernetes.default.svc" }
             - { name: K8S_INSECURE_TLS, value: "true" }

package/dist/approval-card.d.ts

@@ -83,11 +83,13 @@ export declare const RuleOfferSchema: z.ZodUnion<readonly [z.ZodObject<{
     match: z.ZodEnum<{
         name: "name";
         path: "path";
+        host: "host";
         exact: "exact";
         prefix: "prefix";
         wildcard: "wildcard";
         subpath: "subpath";
         name_prefix: "name_prefix";
+        subdomain: "subdomain";
     }>;
     command: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -98,11 +100,13 @@ export declare const RuleOfferSchema: z.ZodUnion<readonly [z.ZodObject<{
         match: z.ZodEnum<{
             name: "name";
             path: "path";
+            host: "host";
             exact: "exact";
             prefix: "prefix";
             wildcard: "wildcard";
             subpath: "subpath";
             name_prefix: "name_prefix";
+            subdomain: "subdomain";
         }>;
         command: z.ZodString;
         segment: z.ZodString;
@@ -164,11 +168,13 @@ export declare const RuleOfferRawSchema: z.ZodUnion<readonly [z.ZodObject<{
     match: z.ZodEnum<{
         name: "name";
         path: "path";
+        host: "host";
         exact: "exact";
         prefix: "prefix";
         wildcard: "wildcard";
         subpath: "subpath";
         name_prefix: "name_prefix";
+        subdomain: "subdomain";
     }>;
     command: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -179,11 +185,13 @@ export declare const RuleOfferRawSchema: z.ZodUnion<readonly [z.ZodObject<{
         match: z.ZodEnum<{
             name: "name";
             path: "path";
+            host: "host";
             exact: "exact";
             prefix: "prefix";
             wildcard: "wildcard";
             subpath: "subpath";
             name_prefix: "name_prefix";
+            subdomain: "subdomain";
         }>;
         command: z.ZodString;
         segment: z.ZodString;
@@ -617,11 +625,13 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         match: z.ZodEnum<{
             name: "name";
             path: "path";
+            host: "host";
             exact: "exact";
             prefix: "prefix";
             wildcard: "wildcard";
             subpath: "subpath";
             name_prefix: "name_prefix";
+            subdomain: "subdomain";
         }>;
         command: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
@@ -632,11 +642,13 @@ export declare const ApprovalCardSchema: z.ZodObject<{
             match: z.ZodEnum<{
                 name: "name";
                 path: "path";
+                host: "host";
                 exact: "exact";
                 prefix: "prefix";
                 wildcard: "wildcard";
                 subpath: "subpath";
                 name_prefix: "name_prefix";
+                subdomain: "subdomain";
             }>;
             command: z.ZodString;
             segment: z.ZodString;
@@ -695,8 +707,8 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         personalRuleDotsAbsent: z.ZodOptional<z.ZodCustom<AskEvidenceAbsence, AskEvidenceAbsence>>;
     }, z.core.$strict>>;
-    askClass: z.ZodOptional<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>;
-    classes: z.ZodOptional<z.ZodArray<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>>;
+    askClass: z.ZodOptional<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>;
+    classes: z.ZodOptional<z.ZodArray<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>>;
     fromSubagent: z.ZodOptional<z.ZodLiteral<true>>;
     sourceTaskId: z.ZodOptional<z.ZodString>;
     sourceAgentName: z.ZodOptional<z.ZodString>;
@@ -747,11 +759,13 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             match: z.ZodEnum<{
                 name: "name";
                 path: "path";
+                host: "host";
                 exact: "exact";
                 prefix: "prefix";
                 wildcard: "wildcard";
                 subpath: "subpath";
                 name_prefix: "name_prefix";
+                subdomain: "subdomain";
             }>;
             command: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{
@@ -762,11 +776,13 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
                 match: z.ZodEnum<{
                     name: "name";
                     path: "path";
+                    host: "host";
                     exact: "exact";
                     prefix: "prefix";
                     wildcard: "wildcard";
                     subpath: "subpath";
                     name_prefix: "name_prefix";
+                    subdomain: "subdomain";
                 }>;
                 command: z.ZodString;
                 segment: z.ZodString;
@@ -825,8 +841,8 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             }, z.core.$strict>>>;
             personalRuleDotsAbsent: z.ZodOptional<z.ZodCustom<AskEvidenceAbsence, AskEvidenceAbsence>>;
         }, z.core.$strict>>;
-        askClass: z.ZodOptional<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>;
-        classes: z.ZodOptional<z.ZodArray<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "write_protection_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>>;
+        askClass: z.ZodOptional<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>;
+        classes: z.ZodOptional<z.ZodArray<z.ZodCustom<"mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", "mode" | "hook" | "org_rule" | "write_protection" | "target_unresolved" | "content_question" | "ask_rule" | "denial_limit_fallback" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "governance_unavailable" | "rule_unreadable" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary">>>;
         fromSubagent: z.ZodOptional<z.ZodLiteral<true>>;
         sourceTaskId: z.ZodOptional<z.ZodString>;
         sourceAgentName: z.ZodOptional<z.ZodString>;

package/dist/approval-content-kind.d.ts

@@ -1,28 +1,44 @@
 /**
- * [ref]:`contentKind` 投影键的**单一词属主**(server 侧)。
+ * 审批卡的**卡词**读口(server 侧唯一一处)与保留问答工具名的再导出。
  *
- * core 在 `summarizeCheckpoint`(dist/core/checkpoint-store.js)对 tool_approval 门铸
- * `contentKind: "content_ask"`,判据一行:`tool.toolName === ASK_USER_QUESTION_TOOL_NAME`。
- * 该常量 **core 从包根导出**(`@sema-agent/core` 的 `index.d.ts`;声明在 `dist/core/ask-question.d.ts`,
- * 值 `"AskUserQuestion"`)⇒ 本仓 **re-export 那一枚**,一个字节都不自铸。
- * (S-213①:此处旧注曾写「该常量未从 core 包根导出」并据此在全仓手抄了 13 处同字面量 —— 那句前提
- *  失实,而每一份手抄都是一个独立写者:core 哪天改了保留工具名,手抄的那些当场与引擎分岔且全部静默。)
- * 三条 server 投影面(SQL `listPending` 列读 / LOCAL `listPending` blob 读 / live `listLivePending`)
- * 全部经 {@link contentKindOf} 派生,恒与 core 的 summarize 面同词 —— 词漂移由 parity 钉看住
- * (`test/local-checkpoint-store.test.ts` [ref] parity 格:core `summarizeCheckpoint` 对 AskUserQuestion
- * checkpoint 的铸值必须逐字等于本函数的答案;同文件 S-213① 格再普查「src/ 里零第二份手抄字面量」)。
+ * ── 规则(core 7.49.0 #1414 / #1468 A-S4)────────────────────────────────────────────────────────────
+ * 「这一问 / 这一行用哪张卡」只有一个事实源 = **引擎铸的 `approvalCard`**(闭集 core `TOOL_APPROVAL_CARDS`):活 ask 上是
+ * `AskRequest.approvalCard`,停驻行上是门的 `gate.approvalCard`(core `summarizeCheckpoint` 投给 `CheckpointSummary.approvalCard`
+ * 的同一个词)。停驻行到期走哪条路只有一个判官 = core `facetOf(gate)`(问答卡 ⇒ `B`,到期作废;其余审批门 ⇒ `A`,SLA 拒扫腿 deny)。
+ * 本仓**不从工具名回推卡**:此前的 `contentKindOf`(工具名 ⇒ `"content_ask"`)、两只店里按 `tool_name` 判问答的 SQL 字面臂与 LOCAL
+ * 比较,以及 wire 上的第二个卡词 `contentKind`,随 #1414 整删(零别名、零双读)。
  *
- * 🔴 与 `hasBidiControls` 的「server 不重算」纪律**不冲突**:那一位是有界扫描的结果(重算可分家),
- * 而 contentKind 是行上 core 铸的 `toolName` 的**全函数**(一行确定性判)——派生 ≠ 重扫。
- * 🔴 OMIT 契约与同族键一致(`boundCallId`/`gateKind`/`hasBidiControls` 的纪律):
- * `"content_ask"` 或**缺席**,恒不铸 `null`/`false`;缺席 = 不是内容问句门(普通工具门 / 非工具 park /
- * toolName 缺席的存量行)。展示/分诊/渲染分型用,永不参与 resume / gate / CAS。
+ * ── 存量行(7.49.0 之前的引擎停驻、门上没有卡)────────────────────────────────────────────────────────
+ * 按 core 的读法:**无卡 = 不是一问**(core 不从名字回推,本仓也不)。持久数据面不留第二种读法 —— 按工具名回退的臂一旦留下,
+ * 就是与 core `facetOf` 对同一张行答两样的第二个判官(本仓说「问答、作废」,core 收 `sla_timeout` 判 deny)。用户可见后果见
+ * 本仓 CHANGELOG 对应条目:旧问答行在队列上不带卡词;过了 deadline 走 SLA 拒扫腿(模型拿到一次「拒」),不再作废整条 run。
+ *
+ * ── 为什么保留工具名常量 ────────────────────────────────────────────────────────────────────────────
+ * `ASK_USER_QUESTION_TOOL_NAME` 是 core 根导出的那一枚(S-213①:本仓一个字节都不自铸),仍有**决断面**的读者(回决时「批准问答必须
+ * 带答」、问答不可记为会话放行、durable 问答门的政策臂)—— 那几处与 core 自己的答案绑定(`engineCardOf`,按 wire 名)同读法,
+ * 不是卡的渲染读法,不在本模块的规则里。
  */
 export { ASK_USER_QUESTION_TOOL_NAME } from "@sema-agent/core";
-/** 保留工具名的 **SQL 字面量**形(单引号已包)。SQL 里也不许再手抄那个词:片段从同一枚常量派生,
- *  与 `tool-approval.ts` 的 `APPROVAL_GATE_KINDS_SQL_IN`(闭集数组 → IN 片段)同一属主纪律。
- *  值来自 core 的常量(标识符形,无引号/反斜杠),故直接内插不产生注入面。 */
-export declare const ASK_USER_QUESTION_SQL_LITERAL = "'AskUserQuestion'";
-/** 三读面共用的派生:AskUserQuestion 工具门 ⇒ `"content_ask"`;其余(含 null/缺席)⇒ undefined(键缺席)。 */
-export declare function contentKindOf(toolName: string | null | undefined): "content_ask" | undefined;
+import { type ToolApprovalCard } from "@sema-agent/core";
+/**
+ * 一格卡词的**闭集窄读**(三个载体共用这一只:活 ask、LOCAL 店的停驻门、SQL 店读出的门子树)。成员 ⇒ 那个词;缺席 ⇒ `undefined`(不计);
+ * 在场却不是成员(世代差 —— 新引擎加了卡词而本版没跟上 —— 或手改行)⇒ `undefined` + 计一次 `server.approval-card.closed-word-out-of-set`
+ * (detail 前缀 `approvalCard=`;与 core 投影同答:集外词不是卡)。判据 = core 导出的闭集本身,本仓不抄词表。
+ */
+export declare function readApprovalCard(raw: unknown): ToolApprovalCard | undefined;
+/** 停驻行上的门(两只店读出来的形;字段都是 `unknown`,形由下面两只函数判)。 */
+export interface ParkedGateFace {
+    readonly kind?: unknown;
+    readonly approvalCard?: unknown;
+}
+/**
+ * 停驻行的卡 = core `summarizeCheckpoint` 投给 `CheckpointSummary.approvalCard` 的那一个词:只在审批门(门型的寄存臂是
+ * `tool_approval`,读 core `PAUSE_REGISTRY`)上读,词经 {@link readApprovalCard}。非审批门(计划审阅 / 资源 / 收尾)恒无卡。
+ */
+export declare function parkedApprovalCard(gate: ParkedGateFace | undefined): ToolApprovalCard | undefined;
+/**
+ * 停驻行到期的读法 = core `facetOf(gate)`(唯一判官;本仓零自写判据):`A` ⇒ SLA 拒扫腿 deny,`B` / `-` ⇒ 到期作废。
+ * 门型不是 core 登记的门(存量行无门型 / 手改)⇒ `undefined`,调用方按「不是 `A`」处置(与无门型存量行的既有作废路同向)。
+ */
+export declare function parkedFacetOf(gate: ParkedGateFace | undefined): "A" | "B" | "-" | undefined;
 //# sourceMappingURL=approval-content-kind.d.ts.map

package/dist/approval-content-kind.js

@@ -1,7 +1,23 @@
 export { ASK_USER_QUESTION_TOOL_NAME } from "@sema-agent/core";
-import { ASK_USER_QUESTION_TOOL_NAME } from "@sema-agent/core";
-export const ASK_USER_QUESTION_SQL_LITERAL = `'${ASK_USER_QUESTION_TOOL_NAME}'`;
-export function contentKindOf(toolName) {
-    return toolName === ASK_USER_QUESTION_TOOL_NAME ? "content_ask" : undefined;
+import { PAUSE_REGISTRY, TOOL_APPROVAL_CARDS, facetOf, isGateKind } from "@sema-agent/core";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { redactSecrets } from "./trace/redact.js";
+export function readApprovalCard(raw) {
+    if (raw === undefined)
+        return undefined;
+    const cards = TOOL_APPROVAL_CARDS;
+    if (cards.includes(raw))
+        return raw;
+    const shape = typeof raw === "string" ? redactSecrets(raw).slice(0, 40) : `<${raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw}>`;
+    recordFailOpen("server.approval-card.closed-word-out-of-set", `approvalCard=${shape}`);
+    return undefined;
+}
+export function parkedApprovalCard(gate) {
+    if (gate === undefined || !isGateKind(gate.kind) || PAUSE_REGISTRY[gate.kind].pending !== "tool_approval")
+        return undefined;
+    return readApprovalCard(gate.approvalCard);
+}
+export function parkedFacetOf(gate) {
+    return gate !== undefined && isGateKind(gate.kind) ? facetOf({ kind: gate.kind, approvalCard: gate.approvalCard }) : undefined;
 }
 //# sourceMappingURL=approval-content-kind.js.map