@sema-agent/server 7.147.0 → 7.149.0

package/deploy/sema-up/preflight.sh

@@ -4,7 +4,7 @@
 # (sema cloud deploy 渲染用,同一交互协议的 infeasible:{reason,suggestion} 字段)。
 # 只读探测,零改动,幂等。退出码:0=可部署(可能有 WARN),1=存在 BLOCK 项。
 set -u
-# >>> 自身目录(五个入口逐字同一段)
+# [[[ 自身目录(五个入口逐字同一段)
 # HERE = 本脚本**真实文件**所在目录。经 npm bin 软链(node_modules/.bin/sema-up)调用时 $0 是软链路径,
 # 按它的目录找 lib/ 会落进 .bin/ ⇒ 逐跳解软链。只用不带参数的 readlink(macOS 自带 bash 3.2 / BSD readlink 没有 -f)。
 # 库要在知道 HERE 之后才找得到,所以这段不能收进库里:五个入口各持同一段,逐字一致由测试判。
@@ -16,11 +16,13 @@ while [ -L "$_self" ]; do
 done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
-# <<< 自身目录
+# ]]] 自身目录
 # 自动数据根的路径形只在 lib/dataroot.sh 定义一次:下面「多盘机」建议句与 sema-up 自动选的根同一条规则。
 . "$HERE/lib/dataroot.sh"
 # 取值旗的形:判据与词表同 sema-up.sh 一处定义。
 . "$HERE/lib/flagshape.sh"
+# 把一段文本按行 / 按词 / 按分隔字符读进变量的三只函数(不用 here-document / here-string)。
+. "$HERE/lib/shell-text.sh"
 log() { printf '[preflight] %s\n' "$*" >&2; }
 
 JSON=false
@@ -111,13 +113,13 @@ else add OK disk "${DISK_GB}G avail /" "" ""; fi
 BEST_MNT="" BEST_GB=0
 if [ "$OS_ID" = "macos" ]; then DF_OUT="$(df -g 2>/dev/null | awk '$1 ~ /^\/dev\// {print $9"\t"$4}')"
 else DF_OUT="$(df -BG --output=source,avail,target 2>/dev/null | awk '$1 ~ /^\/dev\// {gsub(/G/,"",$2); print $3"\t"$2}')"; fi
-while IFS="$(printf '\t')" read -r mnt avail; do
+df_rest="$DF_OUT"$'\n'
+while text_pop_line df_rest df_line; do
+  IFS=$'\t' text_words "$df_line" mnt avail
   [ -z "$mnt" ] && continue
   case "$mnt" in /boot*|/efi*|/System/*|/private/var/vm) continue ;; esac
   if [ "${avail:-0}" -gt "$BEST_GB" ] 2>/dev/null; then BEST_GB="$avail"; BEST_MNT="$mnt"; fi
-done <<EOF_DF
-$DF_OUT
-EOF_DF
+done
 if [ -n "$BEST_MNT" ] && [ "$BEST_MNT" != "/" ] && [ "$BEST_GB" -gt "${DISK_GB:-0}" ]; then
   add WARN disk-alt "$BEST_MNT ${BEST_GB}G avail" "存在比 / 更大的数据盘(多盘机)" "--data-root=$(dataroot_for_disk "$BEST_MNT" "$PROJECT")(sema-up 未显式指定时会自动选它;数据根按项目分)"
 fi
@@ -172,7 +174,7 @@ if $JSON; then
   printf '{"profile":"%s","findings":[' "$PROFILE"
   first=true
   for f in "${FINDINGS[@]}"; do
-    IFS='|' read -r lv ck rs why fix <<<"$f"
+    text_split '|' "$f" lv ck rs why fix
     [ "$lv" = "BLOCK" ] && BLOCKS=$((BLOCKS+1))
     $first || printf ','
     first=false
@@ -183,7 +185,7 @@ if $JSON; then
 else
   printf '── sema-up preflight(profile=%s)──\n' "$PROFILE"
   for f in "${FINDINGS[@]}"; do
-    IFS='|' read -r lv ck rs why fix <<<"$f"
+    text_split '|' "$f" lv ck rs why fix
     [ "$lv" = "BLOCK" ] && BLOCKS=$((BLOCKS+1))
     printf '[%-5s] %-16s %s' "$lv" "$ck" "$rs"
     [ -n "$why" ] && printf ' — %s' "$why"

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

@@ -14,7 +14,7 @@
 #                本机装 k3s(后两态=kube-up.sh,helm chart 驱动)
 set -euo pipefail
 
-# >>> 自身目录(五个入口逐字同一段)
+# [[[ 自身目录(五个入口逐字同一段)
 # HERE = 本脚本**真实文件**所在目录。经 npm bin 软链(node_modules/.bin/sema-up)调用时 $0 是软链路径,
 # 按它的目录找 lib/ 会落进 .bin/ ⇒ 逐跳解软链。只用不带参数的 readlink(macOS 自带 bash 3.2 / BSD readlink 没有 -f)。
 # 库要在知道 HERE 之后才找得到,所以这段不能收进库里:五个入口各持同一段,逐字一致由测试判。
@@ -26,7 +26,7 @@ while [ -L "$_self" ]; do
 done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
-# <<< 自身目录
+# ]]] 自身目录
 # `.env` 文法(写口 envf_representable + envf_encode / 读口 envf_canonical_line)的唯一定义 —— 写读两半从这一处取判据。
 . "$HERE/lib/envf.sh"
 # 数据根归属与「壳怎么接」的渲染各一处定义;preflight / kube-up / cluster-up 读同一份。
@@ -36,6 +36,8 @@ unset _self _hops _dir
 . "$HERE/lib/flagshape.sh"
 # 对象存储桶的唯一表(kube-up.sh / cluster-up.sh / smoke.sh 同读这一张)。
 . "$HERE/lib/buckets.sh"
+# 把一段文本按行 / 按词 / 按分隔字符读进变量的三只函数(不用 here-document / here-string)。
+. "$HERE/lib/shell-text.sh"
 # 日志一律打到 stderr(stdout 留给 --interactive=json 的协议行)。定义在最前面:参数一解析完就要判形,那时下面的函数都还没定义。
 log() { printf '[sema-up] %s\n' "$*" >&2; }
 # 执行车道表的唯一读者。定义在**最前面**:`--help` 的词表也从表渲(手抄的词表会在加一条
@@ -51,43 +53,16 @@ AGENT_PG_HOST="" AGENT_PG_PASSWORD="" AGENT_MINIO_ENDPOINT="" AGENT_MINIO_PASSWO
 PG_URL="${PG_URL:-}" S3_ENDPOINT="${S3_ENDPOINT:-}" S3_ACCESS_KEY="${S3_ACCESS_KEY:-}" S3_SECRET_KEY="${S3_SECRET_KEY:-}"
 
 usage() {
-  cat <<'EOF'
-用法: sema-up.sh [选项]
-EOF
+  cat "$HERE/lib/usage-head.txt"
   # 闭集词表从 lib/flagshape.sh 渲(单一属主):加 / 删一个词,这几行自己跟着变
   printf '  --profile=P            %s\n' "$(printf '%s' "$FLAG_WORDS_PROFILE" | tr ' ' '|')"
   printf '  --users=U              %s\n' "$(printf '%s' "$FLAG_WORDS_USERS" | tr ' ' '|')"
   printf '  --region=R             %s\n' "$(printf '%s' "$FLAG_WORDS_REGION" | tr ' ' '|')"
-  cat <<'EOF'
-  --interactive=json     机器可读交互协议(sema cloud deploy 渲染用)
-  --yes                  全默认无人值守(与 -f 组合)
-  -f FILE                site 配置(env 形式;machines.yaml=固定形状 mini-parser)
-  --project=NAME         compose project 名(默认 sema;并行试验用)。也是工作目录 ~/.sema-up/<名> 与自动数据根
-                         <盘>/sema-data/<名> 的一段 ⇒ 只收小写字母 / 数字 / - / _,首字符是字母或数字
-  --data-root=DIR        数据卷 bind 到这条目录(缺省:多盘机自动选大盘 <盘>/sema-data/<project>);首装落定不漂移,
-                         一条数据根只归一个项目(根里的 .sema-up-project 标记,别的项目的根一律拒)
-  --dry-run              只打印将执行计划(不写 .env、不起任何容器)
-  --port=N               服务端口(默认 8090);--pg-port/--minio-port/--minio-console-port 同理(端口旗只收 1–65535 的整数)
-  --gateway=URL --model=ID --model-key=K   模型面(带 agent 的档必需)
-EOF
+  cat "$HERE/lib/usage-flags.txt"
   # 词表从 lib/lanes.json 渲(单一属主):加/删一条车道,这行自己跟着变
   printf '  --sandbox=LANE         %s(full-single / local-plus;kube 路径不选词,runtimeClass 自动)\n' \
     "$(lanes choices | tr '\n' '|' | sed 's/|$//')"
-  cat <<'EOF'
-  --registry=true|false  配置中心网站(默认 true;local-plus 默认 false;只收这两个词)
-  --registry-image=REF   sema-registry 镜像(registry=true 必需,可 -f 配置 SEMA_REGISTRY_IMAGE)
-  --git=MODE             none(默认)|provision(一键自建 Gitea)|connect(接已有 git)
-  --git-url=URL --git-token=T   git=connect 的已有服务(Gitea/GitHub/任意三方 git;自动识别,证书不校验)
-  --pg-url=URL           外接第三方 PG(postgres://user:pass@host:port/db;连不上会先检,不部署本地 PG)
-  --s3-endpoint=URL --s3-access-key=K --s3-secret-key=S   外接第三方 S3(兼容协议即可;不部署本地 MinIO)
-  --git-http-port=N --git-ssh-port=N   自建 Gitea 端口(默认 3300/2222)
-  --gitea-image=REF      自建 Gitea 镜像(默认 gitea/gitea:1.24)
-  --pg-host=H --pg-password=P --minio-endpoint=URL --minio-password=P   local-plus 远端数据面
-  --kube=MODE            full-cluster 单机两态:existing(已有 kubeconfig)|k3s(本机装 k3s)
-  --kubeconfig=PATH      --kube=existing 的 kubeconfig(缺省 $KUBECONFIG 或 ~/.kube/config)
-  --teardown             卸载本 project(数据卷保留;--teardown-volumes 连卷删)
-  --skip-preflight       跳过预检(不建议)
-EOF
+  cat "$HERE/lib/usage-tail.txt"
 }
 
 TEARDOWN_VOLUMES=false
@@ -334,7 +309,7 @@ if $TEARDOWN; then
       log "⛔ 卸载未完全成功。下一步:docker ps -a --filter label=com.docker.compose.project=$PROJECT 手查残留"
       exit 1
     fi
-    log "已卸载 project=$PROJECT $($TEARDOWN_VOLUMES && echo '(含数据卷)' || echo '(数据卷保留:pgdata/miniodata/registrydata/gitdata)')"
+    log "已卸载 project=$PROJECT $($TEARDOWN_VOLUMES && echo '(含数据卷)' || echo '(数据卷保留:pgdata/miniodata/registrydata/gitdata/sealedkey)')"
     if $TEARDOWN_VOLUMES && [ -n "$DATA_ROOT" ]; then
       # 删不删盘上文件看这条根归谁(标记是别的项目 / 没有标记 ⇒ 不教 rm -rf)。
       dataroot_teardown_hint "$DATA_ROOT"
@@ -714,11 +689,11 @@ if [ "$PROFILE" = "full-single" ] || [ "$PROFILE" = "local-plus" ]; then
   # **resetk 不是 setk**:`setk` 见键在就不改,而升级路径上最常见的既有值恰是空串 `REMOTE_EXEC=`
   # (旧 compose 的 `${REMOTE_EXEC:-}` 渲出来的)——用 setk 就永远修不好那批无手部署。冲突检测在
   # 上面的车道块里已做过(非空且不同 ⇒ 早已拒),所以这里的重写只会落在「空串 / 同值」两种情形上。
-  while IFS='=' read -r _k _v; do
+  lane_rest="$LANE_ENV"$'\n'
+  while text_pop_line lane_rest lane_line; do
+    text_split = "$lane_line" _k _v
     [ -n "$_k" ] && resetk "$_k" "$_v"
-  done <<EOF_LANE
-$LANE_ENV
-EOF_LANE
+  done
 fi
 if [ "$PROFILE" = "local-plus" ]; then
   setk AGENT_PG_HOST "$AGENT_PG_HOST"
@@ -740,7 +715,7 @@ p=u.urlsplit(os.environ["PG_URL"])
 if p.scheme not in ("postgres","postgresql") or not p.hostname: raise SystemExit("bad")
 print(p.hostname, p.port or 5432, p.username or "postgres", p.password or "", (p.path or "/postgres").lstrip("/"))' 2>/dev/null)" \
     || { log "⛔ --pg-url 解析失败(期望 postgres://user:pass@host:port/db):已按 *** 隐去凭据"; exit 1; }
-  read -r EXT_PG_HOST EXT_PG_PORT EXT_PG_USER EXT_PG_PW EXT_PG_DB <<<"$PGP"
+  text_words "$PGP" EXT_PG_HOST EXT_PG_PORT EXT_PG_USER EXT_PG_PW EXT_PG_DB
   resetk AGENT_PG_HOST "$EXT_PG_HOST"; resetk AGENT_PG_PORT "$EXT_PG_PORT"
   resetk AGENT_PG_USER "$EXT_PG_USER"; resetk AGENT_PG_DATABASE "$EXT_PG_DB"
   resetk PG_PASSWORD "$EXT_PG_PW"
@@ -1106,7 +1081,7 @@ else
       echo " ⚠ 待人工  $n"
     done
     echo " 凭据      $ENVF(0600;全部密码/token 常驻此文件,不进日志)"
-    echo " 数据卷    $(printf ',%s,' "$COMPOSE_PROFILES" | grep -q ',pg,' && printf '%s_pgdata ' "$PROJECT")$(printf ',%s,' "$COMPOSE_PROFILES" | grep -q ',s3,' && printf '%s_miniodata ' "$PROJECT")$([ "$REGISTRY_ENABLED" = "true" ] && printf '%s_registrydata ' "$PROJECT")$([ "$GIT_MODE" = "provision" ] && printf '%s_gitdata' "$PROJECT")$([ -n "$DATA_ROOT" ] && printf '(bind 落 %s)' "$DATA_ROOT")"
+    echo " 数据卷    $(printf ',%s,' "$COMPOSE_PROFILES" | grep -q ',pg,' && printf '%s_pgdata ' "$PROJECT")$(printf ',%s,' "$COMPOSE_PROFILES" | grep -q ',s3,' && printf '%s_miniodata ' "$PROJECT")$([ "$REGISTRY_ENABLED" = "true" ] && printf '%s_registrydata ' "$PROJECT")$([ "$GIT_MODE" = "provision" ] && printf '%s_gitdata ' "$PROJECT")$(printf ',%s,' "$COMPOSE_PROFILES" | grep -q ',agent,' && printf '%s_sealedkey' "$PROJECT")$([ -n "$DATA_ROOT" ] && printf '(bind 落 %s)' "$DATA_ROOT")"
     echo " 重入      再跑同命令=幂等升级(凭据不轮换);验证=smoke.sh --project=$PROJECT"
     echo " 卸载      $0 --project=$PROJECT --teardown(留数据)/--teardown-volumes(连卷删)"
     [ "$PROFILE" = "data-center" ] && echo " 接入      别处 agent 连这个数据面 = sema-up.sh --profile=local-plus --pg-host=$HOSTIP --minio-endpoint=http://$HOSTIP:$MINIO_PORT + 两个密码(本机 .env 里)"

package/deploy/sema-up/smoke.sh

@@ -5,7 +5,7 @@
 #   远程 URL 模式:     smoke.sh --url=http://host:8090 --token=T   (引擎面:health/auth/真任务)
 # 每项 OK/FAIL 一行;FAIL 带原因+建议(§3d-2 报错规范);exit 0=全绿。
 set -u
-# >>> 自身目录(五个入口逐字同一段)
+# [[[ 自身目录(五个入口逐字同一段)
 # HERE = 本脚本**真实文件**所在目录。经 npm bin 软链(node_modules/.bin/sema-up)调用时 $0 是软链路径,
 # 按它的目录找 lib/ 会落进 .bin/ ⇒ 逐跳解软链。只用不带参数的 readlink(macOS 自带 bash 3.2 / BSD readlink 没有 -f)。
 # 库要在知道 HERE 之后才找得到,所以这段不能收进库里:五个入口各持同一段,逐字一致由测试判。
@@ -17,7 +17,7 @@ while [ -L "$_self" ]; do
 done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
-# <<< 自身目录
+# ]]] 自身目录
 # `.env` 的文法与读原语只在 lib/envf.sh 定义:本脚本读 `.env` 只经 envf_load,不 source。
 . "$HERE/lib/envf.sh"
 # 取值旗的形:判据同 sema-up.sh 一处定义。
@@ -105,12 +105,13 @@ except Exception: print("")' 2>/dev/null)
 fi
 
 if [ -n "$URL" ]; then
-  # ④ /health(整体取回:后端位在体的中后段,截断读会丢它)
-  H=$(curl -m5 -s "$URL/health")
+  # ④ /health(整体取回:后端位在体的中后段,截断读会丢它;配了服务凭据的引擎只对出示凭据的读者给后端位 / 持久性,所以带 $TOKEN 读)
+  H=$(health_curl "$TOKEN" -m5 -s "$URL/health")
   case "$H" in *'"status":"ok"'*) ok "/health($URL)" ;; *) fail "/health" "无响应或非 ok:$(printf '%s' "${H:-空}" | head -c 200)" "服务没起/端口不对/防火墙;docker logs 或 systemctl 看进程" ;; esac
-  # ④′ 后端位:/health 200 ≠ 数据落了库 —— 引擎的 sessionBackend 必须是期望的持久后端(durable(pg)),`memory` = 内存里跑、重启即丢
+  # ④′ 后端位:/health 200 ≠ 数据落了库 —— 引擎的 sessionBackend 必须是期望的后端(pg),`memory` = 内存里跑、重启即丢;
+  #     store.durability 必须读得到(不是 durable 时照过,成功行带上读数与指路)
   case "$H" in *'"status":"ok"'*)
-    if BK_WHY=$(health_backend_check "$H"); then ok "引擎后端(sessionBackend=$SEMA_UP_EXPECT_SESSION_BACKEND)"
+    if BK_WHY=$(health_backend_check "$H"); then ok "引擎后端(sessionBackend=$SEMA_UP_EXPECT_SESSION_BACKEND · store.durability=$(health_store_durability "$H"))${BK_WHY:+ — $BK_WHY}"
     else fail "引擎后端" "$BK_WHY" "库没连上时引擎不会再退内存起服(拒启);读到 memory 多半是旧镜像或手工起的引擎 —— 看 docker logs / kubectl logs 的 store_sql_open_wait 与拒启句"; fi ;;
   esac
   if [ -n "$TOKEN" ]; then

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

@@ -14,3 +14,6 @@ volumes:
   gitdata:
     driver: local
     driver_opts: { type: none, o: bind, device: "${DATA_ROOT_DIR:?}/gitdata" }
+  sealedkey:
+    driver: local
+    driver_opts: { type: none, o: bind, device: "${DATA_ROOT_DIR:?}/sealedkey" }

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

@@ -69,7 +69,7 @@ services:
     environment:
       PORT: "8090"
       # 1.123.0 收编:显式 DB_BACKEND=pg 即 durable。SESSION_BACKEND=auto 是旧镜像(<1.123)兜底——
-      # 老版本 pg 不自动强转 durable 会静默 memory(真机验出 session:"memory");auto 新旧版都落 durable(pg)
+      # 老版本 pg 不自动强转 durable 会静默 memory(真机验出 session:"memory");auto 新旧版都落 pg(/health.sessionBackend 读 pg)
       DB_BACKEND: pg
       SESSION_BACKEND: auto
       PG_HOST: ${AGENT_PG_HOST:-pg}
@@ -104,8 +104,19 @@ services:
       REMOTE_EXEC: ${REMOTE_EXEC:-}
       E2B_API_KEY: ${E2B_API_KEY:-}
       # @generated-end lane-env
+      # 钥匙保管目录 = 下面 sealedkey 卷的挂载位(安装契约:显式绝对路径;与 chart / cluster 清单同一个值,只在 scripts/gen-deploy-lanes.ts 定义一次,圈起来的行由生成器渲出)
+      # @generated-begin sealed-key-env
+      SEALED_KEY_DIR: "/root/.ai-agent/sealed-key"
+      # @generated-end sealed-key-env
     ports:
       - "${SERVER_BIND:-0.0.0.0}:${SERVER_PORT:-8090}:8090"
+    # 停驻封签钥匙与模型钥匙的私钥只在钥匙保管目录里(不进库):容器重建不丢钥匙,重建之前停驻、带请求凭据的任务照常续跑。
+    # `--teardown-volumes` 删这只卷对象:docker 管的卷连钥匙一起没(之前停驻的任务续跑 409 key_not_held,web-admin 贴的 sealedApiKey 要对着新公钥重封);
+    # `--data-root` 时卷是 bind,盘上 <数据根>/sealedkey 留着,落回同一条数据根重装即读回原钥匙。
+    volumes:
+      # @generated-begin sealed-key-mount
+      - sealedkey:/root/.ai-agent/sealed-key
+      # @generated-end sealed-key-mount
 
   # sema-registry 配置中心(MCP/skill/模型配置云同步;管人+云同步一环,可选)。
   # 镜像=该仓 CI 产物,现行来源=GHCR/Hub(迁移中,SWR 已弃用 2026-07-13;公开仓匿名可拉,
@@ -168,3 +179,4 @@ volumes:
   miniodata:
   registrydata:
   gitdata:
+  sealedkey:

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

@@ -170,6 +170,17 @@ 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 }]
 ---
+# ── 停驻封签钥匙的持久卷(与 chart 的 sealedKey 块同形、同名 sema-server-sealed-key)──────────────────────
+#    引擎的钥匙保管目录(SEALED_KEY_DIR;模型钥匙 + 子目录 checkpoint-ctx-keys/ 的停驻行封签钥匙)整个挂这一只卷。私钥只在这里(不进库):
+#    不持久 ⇒ 每次重启换钥匙;各副本各一份 ⇒ 换副本就换了钥匙 —— 两种结局都是重启 / 换副本之前停驻、带请求凭据的任务续跑恒 409(key_not_held)。
+#    本清单的副本数恒 > 1(cluster-up 按机器数渲 2 或 3)⇒ ReadWriteMany(与 chart 按共享 pod 数派生的结果相同)。Longhorn 的 RWX 走 NFS 共享管理器:
+#    **每个节点要装 NFS 客户端**(Debian / Ubuntu:nfs-common;RHEL 系:nfs-utils)—— cluster-up 不替你装,机器预检缺它会告警;缺了 server Pod 挂不上卷、
+#    rollout 等不到就绪,cluster-up 在第 7 步响亮失败。PVC 不随 kubectl delete -f 以外的任何动作删除;确认不要了再 kubectl -n sema delete pvc sema-server-sealed-key。
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata: { name: sema-server-sealed-key, namespace: sema }
+spec: { accessModes: [ReadWriteMany], storageClassName: longhorn, resources: { requests: { storage: 64Mi } } }
+---
 # ── 引擎(3 副本跨机打散;镜像=节点预灌 sema-server:local,imagePullPolicy Never
 #    ⚠ k3s-uninstall.sh 会连 containerd 镜像一起清,重装过的节点必须补灌)──────────
 apiVersion: v1
@@ -233,7 +244,17 @@ spec:
             # 默认=公开池 code-node(小巧 git+node+python;clay 拍 2026-07-13,重任务 per-task profile 按需选)——裸 OS 镜像无 pkg-source hook,别退回
             - { name: K8S_SANDBOX_IMAGE, value: "docker.io/claybobby/code-node:20260707-749ab84f5fdd-786f5ef10ffd" }
             - { name: K8S_TOKEN, valueFrom: { secretKeyRef: { name: sema-runner-token-copy, key: token } } }
+            # 钥匙保管目录 = 下面那只卷的挂载位(安装契约:显式绝对路径);值与挂载位只有一处定义(scripts/gen-deploy-lanes.ts),圈起来的行由生成器渲出,不要手改
+            # @generated-begin sealed-key-env
+            - { name: SEALED_KEY_DIR, value: "/root/.ai-agent/sealed-key" }
+            # @generated-end sealed-key-env
           readinessProbe: { httpGet: { path: /readyz, port: 8090 }, initialDelaySeconds: 5, periodSeconds: 5 }  # the only probe path (/health is diagnostic)
+          volumeMounts:
+            # @generated-begin sealed-key-mount
+            - { name: sealed-key, mountPath: "/root/.ai-agent/sealed-key" }
+            # @generated-end sealed-key-mount
+      volumes:
+        - { name: sealed-key, persistentVolumeClaim: { claimName: sema-server-sealed-key } }
 ---
 apiVersion: v1
 kind: Service

package/dist/adoption/plan.d.ts

@@ -56,10 +56,34 @@ export interface BlobRewriteSpec {
      */
     readonly revInPayload?: string;
 }
+/**
+ * 一条腿的表由**哪一段装配**建(闭集;消费它的 `switch` 穷尽,表外的词是编译错)。
+ *  · `core` —— 中央 `ensureSchema` 或任一 SQL 后端上无条件的逐店 ensure 建的表:SQL 后端每次起服都建,库上恒在(本表缺 = 库被人动过,不是部署形态),腿恒跑、不探表;
+ *  · `memory-engine` —— 记忆引擎 DB 后端(`MEMORY_ENGINE_BACKEND=pg|mysql` 且引擎开)那一段装配才建的六张 `agent_memory_engine_*` 表
+ *    (`boot/stores.ts` 的记忆 SQL 臂:`ensure*MemoryEngineSchema` / `*MemoryHistorySchema` / `*MemorySyncSchema`);缺省 file 记忆引擎的部署上它们不存在;
+ *  · `task-attachment` —— 附件店只在配了对象存储(`MINIO_*`)时才接线、才 ensure 的 `task_attachment`(无对象存储 ⇒ 整段不接线、表不建)。
+ * 非 `core` 的两面是**可选部署表面**:同一张计划表、同一套腿,只是「本部署有没有这张表」是**部署事实**,不是每条腿各带一个 `optional` 字面量。
+ */
+export type AdoptionTablePlane = "core" | "memory-engine" | "task-attachment";
+/**
+ * 本部署**装配出**了哪些可选表面(boot 的店接线事实,必填、无默认值:忘传 = 编译红;与留存执行器的 `taskAttachmentTable` 同一条理由)。
+ * 只在 runner 的腿集规划(`planLegs`)用来判「库上缺这张表是不是意外」—— 接线了却缺表 = 部署坏了(409 `adoption.table_missing`,点名表);没接线也缺表 = 这个部署本来就没有那个面,
+ * 它的腿不在回执里。**没接线但表在**(例:曾配过对象存储后撤掉配置、表与行都还在)不是「没有那个面」:行在库里就得迁,腿照跑 —— 腿集由库上在场的表定,接线只定缺席算不算错。
+ */
+export interface AdoptionWiring {
+    /** 记忆引擎 DB 后端的那一段装配在 boot 里跑过(= `memoryExportStores` 在场 = DB 记忆平面亮起)。 */
+    readonly memoryEngine: boolean;
+    /** 附件店在 boot 里构造过(= `taskAttachmentStore` 在场;SQL 后端上它只在配了对象存储时才有)。 */
+    readonly taskAttachment: boolean;
+}
+/** 这个可选面在本部署上是不是**该有**(闭集 `switch`:`AdoptionTablePlane` 多一词 ⇒ 这里编译红)。`core` 恒该有。 */
+export declare function planeExpected(plane: AdoptionTablePlane, wiring: AdoptionWiring): boolean;
 export interface RebindLegSpec {
     /** 腿的稳定标识(回执 `legs[].store`)= `<表名>#<身份轴>`。下游按它对账,改名 = wire 破坏。 */
     readonly leg: string;
     readonly table: string;
+    /** 这张表由哪一段装配建({@link AdoptionTablePlane});必填 —— 新腿加进来时必须说出它的表是库上恒在的还是可选面的。 */
+    readonly plane: AdoptionTablePlane;
     readonly kind: LegKind;
     readonly action: AdoptionLegAction;
     /** 携带同一个身份值、必须一起改的列(键列的字节孪生 `*_key` 与可读列并列时两个都在)。 */

package/dist/adoption/plan.js

@@ -1,9 +1,24 @@
 import { formatUserScope, encodeScopeSegment, SCOPE_SEGMENT_MAX_ENCODED } from "@sema-agent/core";
 import { PROJECT_LAYER_KEY_PREFIX } from "../project-layer-key.js";
+export function planeExpected(plane, wiring) {
+    switch (plane) {
+        case "core":
+            return true;
+        case "memory-engine":
+            return wiring.memoryEngine;
+        case "task-attachment":
+            return wiring.taskAttachment;
+        default: {
+            const unhandled = plane;
+            throw new Error(`adoption: unhandled table plane ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
 export const REBIND_LEGS = [
     {
         leg: "session_meta#owner",
         table: "session_meta",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -15,6 +30,7 @@ export const REBIND_LEGS = [
     {
         leg: "session_meta#placement_scope",
         table: "session_meta",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["placement_scope"],
@@ -26,6 +42,7 @@ export const REBIND_LEGS = [
     {
         leg: "task_run#owner",
         table: "task_run",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -37,6 +54,7 @@ export const REBIND_LEGS = [
     {
         leg: "resume_anchor#owner",
         table: "resume_anchor",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -48,6 +66,7 @@ export const REBIND_LEGS = [
     {
         leg: "sendfile_link#scope",
         table: "sendfile_link",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["scope"],
@@ -59,6 +78,7 @@ export const REBIND_LEGS = [
     {
         leg: "task_attachment#owner",
         table: "task_attachment",
+        plane: "task-attachment",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -70,6 +90,7 @@ export const REBIND_LEGS = [
     {
         leg: "approval_ask#owner",
         table: "approval_ask",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -81,6 +102,7 @@ export const REBIND_LEGS = [
     {
         leg: "sandbox_image_index#tenant_id",
         table: "sandbox_image_index",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["tenant_id"],
@@ -92,6 +114,7 @@ export const REBIND_LEGS = [
     {
         leg: "leader_run#owner",
         table: "leader_run",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -103,6 +126,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_completion_inbox#owner",
         table: "workflow_completion_inbox",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -114,6 +138,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_inbox_fence#owner",
         table: "workflow_inbox_fence",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -125,6 +150,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_notify_journal#principal",
         table: "workflow_notify_journal",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["principal"],
@@ -136,6 +162,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_notify_journal#scope",
         table: "workflow_notify_journal",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -147,6 +174,7 @@ export const REBIND_LEGS = [
     {
         leg: "background_agent#record_json",
         table: "background_agent",
+        plane: "core",
         kind: "blob-rewrite",
         action: "row-rewrite",
         columns: ["scope_key"],
@@ -159,6 +187,7 @@ export const REBIND_LEGS = [
     {
         leg: "background_agent#owner",
         table: "background_agent",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["owner"],
@@ -170,6 +199,7 @@ export const REBIND_LEGS = [
     {
         leg: "checkpoint#checkpoint_blob",
         table: "checkpoint",
+        plane: "core",
         kind: "blob-rewrite",
         action: "row-rewrite",
         columns: ["scope"],
@@ -182,6 +212,7 @@ export const REBIND_LEGS = [
     {
         leg: "checkpoint#scope",
         table: "checkpoint",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -193,6 +224,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_run#run_blob",
         table: "workflow_run",
+        plane: "core",
         kind: "blob-rewrite",
         action: "row-rewrite",
         columns: ["scope"],
@@ -205,6 +237,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_run#scope",
         table: "workflow_run",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -216,6 +249,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_journal_owner#scope",
         table: "workflow_journal_owner",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -227,6 +261,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_agent_session#scope",
         table: "workflow_agent_session",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -238,6 +273,7 @@ export const REBIND_LEGS = [
     {
         leg: "workflow_resume_claim#scope",
         table: "workflow_resume_claim",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -249,6 +285,7 @@ export const REBIND_LEGS = [
     {
         leg: "mailbox#scope",
         table: "mailbox",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope_key", "scope"],
@@ -260,6 +297,7 @@ export const REBIND_LEGS = [
     {
         leg: "mailbox_tombstone#scope_key",
         table: "mailbox_tombstone",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope_key"],
@@ -271,6 +309,7 @@ export const REBIND_LEGS = [
     {
         leg: "mailbox_message#scope_key",
         table: "mailbox_message",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope_key"],
@@ -282,6 +321,7 @@ export const REBIND_LEGS = [
     {
         leg: "mailbox_consumed#scope_key",
         table: "mailbox_consumed",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope_key"],
@@ -293,6 +333,7 @@ export const REBIND_LEGS = [
     {
         leg: "background_agent#scope",
         table: "background_agent",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope_key", "scope"],
@@ -304,6 +345,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_roster#owner",
         table: "agent_roster",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["owner_key", "owner"],
@@ -315,6 +357,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_roster#scope",
         table: "agent_roster",
+        plane: "core",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope_key", "scope"],
@@ -326,6 +369,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_memory_engine_entry#scope",
         table: "agent_memory_engine_entry",
+        plane: "memory-engine",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -337,6 +381,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_memory_engine_cursor#scope",
         table: "agent_memory_engine_cursor",
+        plane: "memory-engine",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -348,6 +393,7 @@ export const REBIND_LEGS = [
     {
         leg: "memory_optout_grant#principal",
         table: "memory_optout_grant",
+        plane: "core",
         kind: "bulk-rebind",
         action: "row-rewrite",
         columns: ["principal"],
@@ -359,6 +405,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_memory_engine_sync_cursor#scope",
         table: "agent_memory_engine_sync_cursor",
+        plane: "memory-engine",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -370,6 +417,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_memory_engine_sync_partition#scope",
         table: "agent_memory_engine_sync_partition",
+        plane: "memory-engine",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -381,6 +429,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_memory_engine_push_queue#scope",
         table: "agent_memory_engine_push_queue",
+        plane: "memory-engine",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -392,6 +441,7 @@ export const REBIND_LEGS = [
     {
         leg: "agent_memory_engine_history#scope",
         table: "agent_memory_engine_history",
+        plane: "memory-engine",
         kind: "bulk-rebind",
         action: "bucket-rebind",
         columns: ["scope"],
@@ -403,6 +453,7 @@ export const REBIND_LEGS = [
     {
         leg: "session_policy#principal",
         table: "session_policy",
+        plane: "core",
         kind: "session-policy-rekey",
         action: "row-rewrite",
         columns: ["principal"],
@@ -414,6 +465,7 @@ export const REBIND_LEGS = [
     {
         leg: "permission_rule#owner_key",
         table: "permission_rule",
+        plane: "core",
         kind: "rule-owner-rekey",
         action: "bucket-rebind",
         columns: ["owner_key", "principal"],
@@ -449,7 +501,7 @@ export const AFFECTED_CONFIG_TEMPLATES = [
     { deployment: "cli", key: "~/.sema/cloud/credentials + cloud/profiles.json", requiredValue: "%TO%" },
     { deployment: "cli", key: "SEMA_LIVE_PRINCIPAL", requiredValue: "%TO%" },
     { deployment: "env", key: "REQUIRE_PRINCIPAL", requiredValue: "true (multi-tenant posture must stay on)" },
-    { deployment: "core-decl", key: "localOwnerRules", requiredValue: "(withdraw — the declaration resolves to the adopted principal after adoption)" },
+    { deployment: "core-decl", key: "localOwnerRules", requiredValue: "(withdrawn by REQUIRE_PRINCIPAL=true — this server declares it only on a single-user deployment with a permission-rule store)" },
 ];
 export const IDENTITY_WIDTH_LIMITS = [
     { what: "sandbox_image_index.tenant_id VARCHAR(64)", unit: "chars", max: 64 },