@sema-agent/server 7.146.0 → 7.148.0

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"
@@ -705,17 +680,20 @@ if [ "$PROFILE" = "full-single" ] || [ "$PROFILE" = "local-plus" ]; then
   setk MODEL_ID "$MODEL"
   [ -n "$MODEL_KEY" ] && setk MODEL_API_KEY "$MODEL_KEY"
   setk REQUIRE_PRINCIPAL "$REQUIRE_PRINCIPAL_WANT"
+  # 单用户运维声明:由租户词派生(lib/flagshape.sh 唯一定义),每次重写 —— 它不是第二个部署事实,是 REQUIRE_PRINCIPAL 那一个事实的另一根键。
+  # 不写 ⇒ 单用户 server 起服拒(没人能当运维);升级路径上旧 .env 没有这一行,resetk 补上。
+  resetk OPERATOR_SINGLE_USER "$(operator_single_user_of_users "$USERS")"
   setk SANDBOX_PKG_SOURCE "$([ "$REGION" = "global" ] && echo global || echo '')"
   [ -n "${SEMA_SERVER_IMAGE:-}" ] && setk SEMA_SERVER_IMAGE "$SEMA_SERVER_IMAGE"
   # 执行车道落 .env(从上面 `lanes resolve` 的结果渲,脚本里零车道词)。
   # **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"
@@ -737,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"
@@ -800,10 +778,11 @@ shq() { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"; }
 # ── 渲染对账(生成 .env 之后、compose up 之前)──────────────────────────────────
 # .env 的写口 / 读口都按物理行判,认不出 compose dotenv 的跨行引号值等边角;唯一能确知「容器真正拿到
 # 什么」的是 compose 自己。所以在 up 之前跑一次 `compose config`——与 up **同一组 -f / profile / 同一 shell
-# 环境**(于是运维导出的空串等也算进来)——从渲染结果取 agent 服务的 REQUIRE_PRINCIPAL / REMOTE_EXEC /
-# REQUIRE_EXECUTION_LANE,与本次决策逐值对比,不一致 ⇒ 拒并点名渲染值与决策值。**以 compose 为唯一属主**。
+# 环境**(于是运维导出的空串等也算进来)——从渲染结果取 agent 服务的 REQUIRE_PRINCIPAL / REMOTE_EXEC,
+# 与本次决策逐值对比,不一致 ⇒ 拒并点名渲染值与决策值。**以 compose 为唯一属主**。
 # docker 不可达在上面 `command -v docker` 那道已 fail-loud 拦下;config 本身失败(YAML/插值坏)也拒,
-# 不新铸降级臂:未经对账就不 up。只有 agent 面有这三个决策键,别的档跳过。
+# 不新铸降级臂:未经对账就不 up。只有 agent 面有这两个决策键,别的档跳过。
+# (REQUIRE_EXECUTION_LANE 是退役 env —— 设了即起服拒 —— 产物不再渲它,也不再对账它。)
 #
 # 拒因分两种、各给各的出路(7.98.0 曾把 stderr 并进 stdout 当 JSON 解析 ⇒ compose 的任何警告都让它 traceback,
 # 拒因还冒充「不一致」):
@@ -813,7 +792,7 @@ shq() { printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"; }
 # 插值警告里的变量名也可能是凭据的一段)。
 RECON_PY='
 import json, sys
-want = {"REQUIRE_PRINCIPAL": sys.argv[1], "REMOTE_EXEC": sys.argv[2], "REQUIRE_EXECUTION_LANE": sys.argv[3]}
+want = {"REQUIRE_PRINCIPAL": sys.argv[1], "REMOTE_EXEC": sys.argv[2]}
 try:
     d = json.loads(sys.stdin.read())
     env = d["services"]["server"].get("environment") or {}
@@ -833,8 +812,7 @@ if bad:
 '
 reconcile_render() {
   case ",$COMPOSE_PROFILES," in *,agent,*) : ;; *) return 0 ;; esac
-  local exp_rp="$REQUIRE_PRINCIPAL_WANT" exp_re="$LANE_REMOTE_EXEC" exp_rl rendered errf nerr rc=0 prc=0 repro a
-  exp_rl="$(printf '%s\n' "$LANE_ENV" | sed -n 's/^REQUIRE_EXECUTION_LANE=//p')"
+  local exp_rp="$REQUIRE_PRINCIPAL_WANT" exp_re="$LANE_REMOTE_EXEC" rendered errf nerr rc=0 prc=0 repro a
   # 复现命令:与这次 config 同一个 compose 入口、同一张全局参数表、同一组 profile(从源渲,不手抄)。
   dc_argv; compose_globals
   repro="(cd $(shq "$HERE/stack") && COMPOSE_PROFILES=$(shq "$COMPOSE_PROFILES") ${DC_ARGV[*]}"
@@ -848,12 +826,12 @@ reconcile_render() {
     log "   ↳ 下一步:在本机亲跑 $repro 看 compose 的报文(本脚本不转印它:.env 解析失败的报文会原样引用那一行,可能带凭据);常见成因是手改过的 .env 行"
     exit 1
   fi
-  printf '%s' "$rendered" | python3 -c "$RECON_PY" "$exp_rp" "$exp_re" "$exp_rl" || prc=$?
+  printf '%s' "$rendered" | python3 -c "$RECON_PY" "$exp_rp" "$exp_re" || prc=$?
   case "$prc" in
     0) : ;;
     3)
       log "⛔ 渲染对账:渲染值与决策值不一致 —— compose 渲染出的容器决策值与本次决策对不上;以 compose 为唯一属主,拒绝 up"
-      log "   ↳ 下一步:检查 $ENVF 里 REQUIRE_PRINCIPAL / REMOTE_EXEC / REQUIRE_EXECUTION_LANE,以及 shell / -f 里是否**导出**了同名变量(compose 插值 shell 优先于 --env-file,导出为空会盖掉 .env);亲跑 $repro 可看容器 environment"
+      log "   ↳ 下一步:检查 $ENVF 里 REQUIRE_PRINCIPAL / REMOTE_EXEC,以及 shell / -f 里是否**导出**了同名变量(compose 插值 shell 优先于 --env-file,导出为空会盖掉 .env);亲跑 $repro 可看容器 environment"
       exit 1 ;;
     4)
       log "⛔ 渲染对账:渲染结果解析失败 —— docker compose config 退出 0,但 stdout 不是可解析的 compose JSON(或其中没有 server 服务;compose 另在 stderr 输出了 $nerr 行,本脚本不转印),无法确认容器会拿到什么 —— 拒绝在未对账的情况下 up"
@@ -864,7 +842,7 @@ reconcile_render() {
       log "   ↳ 下一步:确认本机 python3 可用(python3 -c 'import json'),然后重跑"
       exit 1 ;;
   esac
-  log "渲染对账通过:REQUIRE_PRINCIPAL=$exp_rp REMOTE_EXEC=$exp_re REQUIRE_EXECUTION_LANE=$exp_rl(compose 渲染逐值一致)$([ "$nerr" -gt 0 ] && printf ';compose 另在 stderr 输出了 %s 行(多为插值警告;本脚本不转印,up 时 compose 会自己打出来)' "$nerr")"
+  log "渲染对账通过:REQUIRE_PRINCIPAL=$exp_rp REMOTE_EXEC=$exp_re(compose 渲染逐值一致)$([ "$nerr" -gt 0 ] && printf ';compose 另在 stderr 输出了 %s 行(多为插值警告;本脚本不转印,up 时 compose 会自己打出来)' "$nerr")"
 }
 
 # ── 外接端点连接检测(装配前 fail-loud;只验兼容可用,不校验证书——内网自签是常态)────────────
@@ -1103,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}
@@ -93,18 +93,30 @@ services:
       MODEL_ID: ${MODEL_ID:-}
       MODEL_API_KEY: ${MODEL_API_KEY:-}
       REQUIRE_PRINCIPAL: ${REQUIRE_PRINCIPAL:-false}
+      # 单用户运维声明(sema-up 由 --users 渲进 .env:single ⇒ true,multi ⇒ false)。刻意不给缺省:手工起这份 compose 而 .env 里没有它的
+      # 单用户部署,server 起服拒并给出那一行(不在模板里替运维表态「人人是运维」)。
+      OPERATOR_SINGLE_USER: ${OPERATOR_SINGLE_USER:-}
       SANDBOX_PKG_SOURCE: ${SANDBOX_PKG_SOURCE:-}
       # 执行车道:值由 sema-up.sh 从 lib/lanes.json 渲进 .env(resetk,每次重写)。
-      # `REQUIRE_EXECUTION_LANE` 缺省 true —— 手工起这份 compose 而没点名车道时,server 拒启
-      # 并说「没有手」,而不是安静地起成一个什么都干不了的 worker。
-      # 下面圈起来的几行(车道键、缺省、compose 路径上各车道运维自备的键)由车道表生成,不要手改。
+      # 不再渲 `REQUIRE_EXECUTION_LANE`:它是退役 env(设了即起服拒,拒句指向 REMOTE_EXEC);车道只由 REMOTE_EXEC 点名。
+      # 下面圈起来的几行(车道键、compose 路径上各车道运维自备的键)由车道表生成,不要手改。
       # @generated-begin lane-env
       REMOTE_EXEC: ${REMOTE_EXEC:-}
-      REQUIRE_EXECUTION_LANE: ${REQUIRE_EXECUTION_LANE:-true}
       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;公开仓匿名可拉,
@@ -167,3 +179,4 @@ volumes:
   miniodata:
   registrydata:
   gitdata:
+  sealedkey:

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

@@ -1,5 +1,5 @@
 # sema-stack(full-cluster 形态,Phase 1b as-built;cluster-up.sh 渲染 __占位符__ 后 apply)
-# 占位符:__MINIO_PW__ __SVC_TOKEN__ __MODEL_KEY__ __MODEL_GATEWAY__ __MODEL_ID__ __REQUIRE_PRINCIPAL__
+# 占位符:__MINIO_PW__ __SVC_TOKEN__ __MODEL_KEY__ __MODEL_GATEWAY__ __MODEL_ID__ __REQUIRE_PRINCIPAL__ __OPERATOR_SINGLE_USER__
 #         __SERVER_IMAGE__ __SERVER_PULL_POLICY__(tar 预灌=Never / registry 拉取=IfNotPresent)
 # 前置(cluster-up.sh 负责):Longhorn 默认 SC、kata-deploy(runtimeclass kata-qemu)、CNPG operator 1.30、
 #         runner token 跨 ns 复制成 sema/sema-runner-token-copy、MinIO 建桶 sema-pg-backup
@@ -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
@@ -219,11 +230,12 @@ spec:
             - { name: MODEL_VISION, value: "false" }
             # 租户姿态与 chart 主 worker 同值(cluster-up 由 --users 渲:multi ⇒ true,否则 false);修前整块缺席 ⇒ 恒单用户
             - { name: REQUIRE_PRINCIPAL, value: "__REQUIRE_PRINCIPAL__" }
+            # 单用户运维声明与租户姿态同一次翻译(cluster-up 由 --users 渲:single ⇒ true,multi ⇒ false);缺了它单用户 server 起服拒
+            - { name: OPERATOR_SINGLE_USER, value: "__OPERATOR_SINGLE_USER__" }
             - { name: SANDBOX_PKG_SOURCE, value: "__PKG_SOURCE__" }
-            # 显式表态「这台有手」(车道被改没了 ⇒ 拒启,不是安静的无手 worker);下面圈起来的两行取自车道表(lanes.json 的 kube 行),由生成器渲出,不要手改
+            # 车道显式点名(REMOTE_EXEC;REQUIRE_EXECUTION_LANE 是退役 env,设了即起服拒,不再渲);下面圈起来的一行取自车道表(lanes.json 的 kube 行),由生成器渲出,不要手改
             # @generated-begin kube-lane-env
             - { name: REMOTE_EXEC, value: "k8s" }
-            - { name: REQUIRE_EXECUTION_LANE, value: "true" }
             # @generated-end kube-lane-env
             - { name: K8S_API_URL, value: "https://kubernetes.default.svc" }
             - { name: K8S_INSECURE_TLS, value: "true" }
@@ -232,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` 与可读列并列时两个都在)。 */