@sema-agent/server 7.144.0 → 7.146.0

package/deploy/facts/CHANGES.json

@@ -0,0 +1,25 @@
+{
+  "changes": [
+    {
+      "version": "7.146.0",
+      "file": "lanes",
+      "kind": "introduced",
+      "pointer": "",
+      "why": "首发:每条执行车道的租户档、隔离位与必需键,行集 = 所依 settings-schema 的全部车道词"
+    },
+    {
+      "version": "7.146.0",
+      "file": "sandbox-rbac",
+      "kind": "introduced",
+      "pointer": "",
+      "why": "首发:k8s 沙箱服务账号的 RBAC 规则表(每条规则何时授、引擎真调还是兼容保留)"
+    },
+    {
+      "version": "7.146.0",
+      "file": "sealed-key",
+      "kind": "introduced",
+      "pointer": "",
+      "why": "首发:钥匙保管目录的安装契约(显式绝对 SEALED_KEY_DIR、整个目录跨重启持久且各副本共享、目录与文件的权限位)"
+    }
+  ]
+}

package/deploy/facts/README.md

@@ -0,0 +1,57 @@
+# 引擎部署事实(随包数据)
+
+这个目录是 `@sema-agent/server` 引擎**自己的部署要求**的机器可读形:引擎发出的 API 调用、引擎按名读的键与目录、引擎要求先存在的条件。
+安装器(chart / 清单 / 安装脚本)按这里的数据渲自己的产物,不必逐字节拷 server 的 chart。部署方自己拥有的策略实例(例如沙箱出网的 NetworkPolicy:引擎只读来诊断)不在这里。
+
+## 取用
+
+npm 包内固定路径,子路径 = 文件路径:
+
+- Node:`require.resolve("@sema-agent/server/deploy/facts/lanes.json")`(ESM 用 `import.meta.resolve`);
+- tarball:`package/deploy/facts/lanes.json`。
+
+公开子路径恰是下表的七个 JSON 文件;这个目录里的其他文件(如本 README)不导出。部署 server 的哪一版,就读那一版包里的这份数据 —— 混版不受支持(规则行是数据,新版可能多一行恒授规则)。
+
+| 文件 | 内容 |
+| --- | --- |
+| `lanes.json` / `lanes.schema.json` | 每条执行车道:分不分租户(`tenantSeparation`)、手跑在不在 OS 级隔离边界里(`isolation`)、选它时引擎起服必须读到的键(`requiredEnv` / `requiredSecretEnv`)。行集 = 本包所依 settings-schema 的全部车道词。 |
+| `sandbox-rbac.json` / `sandbox-rbac.schema.json` | k8s 沙箱车道的服务账号要的 RBAC 规则:范围、资源、动词、何时授(`when`)、引擎适配器真调还是兼容保留(`need`)。 |
+| `sealed-key.json` / `sealed-key.schema.json` | 钥匙保管目录的安装契约:给引擎设绝对路径的 `SEALED_KEY_DIR`;整个目录跨重启持久、各副本共享、引擎可写;目录与钥匙文件的权限位。 |
+| `CHANGES.json` | 形变登记:每份数据的形在哪个版本、怎样变过(与下方「变更」节同源)。 |
+
+## 读方义务
+
+1. 用**同一个包里**那份 `*.schema.json` 校验数据(JSON Schema 2020-12 的子集)。`x-uniqueKey` 是自定义注解:列出的属性组合在数组里唯一(成员都是标量或标量数组,按值比较即可)—— 标准校验器忽略它,要判就自己判。
+2. 不认识的 `schemaVersion` 整份拒读。
+3. 同一 `schemaVersion` 内的未知键忽略。
+4. 行是数据,不是形:新版可能多一行(新车道、新的恒授规则)而 `schemaVersion` 不变。按行读的消费方对不认识的行(例如不认识的车道词)按自己的策略跳过或拒绝,不要假设行集封闭;
+   闭集的是每一列的取值(`enum`),闭集加词才抬版。
+
+## 版本与形变
+
+- 加性形变只有一种:新增一个**可选**属性 —— `schemaVersion` 不变,`CHANGES.json` 记一条 `additive`。
+- 其余任何形变(删属性、改类型、可选 ⇄ 必有、新增必有属性、闭集增 / 删词、`const` 变、`minItems` / `uniqueItems` / `x-uniqueKey` 变)都是破坏性:该文件的 `schemaVersion` 加 1,记一条 `breaking`。
+- 值的含义变了而形没变,同样记一条 `breaking` 并抬版。
+- 发版前的门禁对上一个已发版本求差:没登记的形变、没抬版的破坏性形变发不出去。
+
+## `sealed-key.json` 之外的引擎行为
+
+没设 `SEALED_KEY_DIR` 时,引擎回落到数据根下的 `sealed-key/`(数据根自身还有一条回落链)。那是引擎内部行为,安装器不依赖它:安装契约是显式设绝对路径。
+声明的目录建不了保管店 ⇒ 起服拒;回落目录建不了只告警、sealed 模型逐个失败 —— 显式声明响得更早。
+
+## 这份数据还没覆盖的
+
+本版只覆盖车道、沙箱 RBAC、钥匙保管目录三类。全局必填配置(例如多租户部署的 `REQUIRE_PRINCIPAL=true`)、快照桶、SQL 表列形、缓存卷要求的持久店后端、其余配置交叉约束,
+仍以引擎起服时的拒启判据与 server 的部署前置文档为准 —— 失败照样响亮,只是要到起服时才知道,装之前查不出来。
+
+## 变更
+
+<!-- @generated-begin facts-changes -->
+本节由形变登记表生成(与 `CHANGES.json` 同源,仓内门禁保证逐字一致),不要手改。
+
+| 版本 | 文件 | 种类 | 指针 | 为什么 |
+| --- | --- | --- | --- | --- |
+| 7.146.0 | `lanes` | introduced | `""`(整份) | 首发:每条执行车道的租户档、隔离位与必需键,行集 = 所依 settings-schema 的全部车道词 |
+| 7.146.0 | `sandbox-rbac` | introduced | `""`(整份) | 首发:k8s 沙箱服务账号的 RBAC 规则表(每条规则何时授、引擎真调还是兼容保留) |
+| 7.146.0 | `sealed-key` | introduced | `""`(整份) | 首发:钥匙保管目录的安装契约(显式绝对 SEALED_KEY_DIR、整个目录跨重启持久且各副本共享、目录与文件的权限位) |
+<!-- @generated-end facts-changes -->

package/deploy/facts/lanes.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "lanes": [
+    {
+      "lane": "host",
+      "tenantSeparation": "single-user-only",
+      "isolation": "unsupported",
+      "requiredEnv": [],
+      "requiredSecretEnv": []
+    },
+    {
+      "lane": "e2b",
+      "tenantSeparation": "supported",
+      "isolation": "supported",
+      "requiredEnv": [],
+      "requiredSecretEnv": ["E2B_API_KEY"]
+    },
+    {
+      "lane": "k8s",
+      "tenantSeparation": "supported",
+      "isolation": "supported",
+      "requiredEnv": ["K8S_SANDBOX_IMAGE", "K8S_NAMESPACE"],
+      "requiredSecretEnv": []
+    },
+    {
+      "lane": "ssh",
+      "tenantSeparation": "single-user-only",
+      "isolation": "unsupported",
+      "requiredEnv": ["SSH_HOST", "SSH_USER"],
+      "requiredSecretEnv": ["SSH_PRIVATE_KEY"]
+    },
+    {
+      "lane": "adb",
+      "tenantSeparation": "single-user-only",
+      "isolation": "unsupported",
+      "requiredEnv": ["ADB_SERIAL"],
+      "requiredSecretEnv": []
+    },
+    {
+      "lane": "local-docker",
+      "tenantSeparation": "supported",
+      "isolation": "supported",
+      "requiredEnv": ["DOCKER_IMAGE"],
+      "requiredSecretEnv": []
+    },
+    {
+      "lane": "device",
+      "tenantSeparation": "supported",
+      "isolation": "unsupported",
+      "requiredEnv": ["DEVICE_RELAY_URL"],
+      "requiredSecretEnv": []
+    }
+  ]
+}

package/deploy/facts/lanes.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "引擎的执行车道事实:每条车道分不分租户、手跑在不在 OS 级隔离边界里、选它时引擎起服必须读到的键。行集 = 本包所依 settings-schema 车道表的全部车道词(含没有安装器接线的车道)。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "lanes"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "本份数据的形版本;读方不认识的版本整份拒读。"
+    },
+    "lanes": {
+      "type": "array",
+      "minItems": 1,
+      "x-uniqueKey": ["lane"],
+      "description": "每条车道一行,行序 = 车道表次序。",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["lane", "tenantSeparation", "isolation", "requiredEnv", "requiredSecretEnv"],
+        "properties": {
+          "lane": {
+            "type": "string",
+            "description": "车道词,即 REMOTE_EXEC 的取值。"
+          },
+          "tenantSeparation": {
+            "type": "string",
+            "enum": ["supported", "single-user-only"],
+            "description": "supported = 可在多租户部署(REQUIRE_PRINCIPAL=true)上用;single-user-only = 只给单用户部署,多租户部署选它起服即拒。"
+          },
+          "isolation": {
+            "type": "string",
+            "enum": ["supported", "unsupported"],
+            "description": "supported = 手跑在 OS 级隔离边界里(独立沙箱);unsupported = 手跑在没有 OS 级隔离的地方(服务容器本身、远端主机、设备)。"
+          },
+          "requiredEnv": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string"
+            },
+            "description": "选这条车道时引擎起服必须读到的非密键(缺任一 ⇒ 起服拒)。"
+          },
+          "requiredSecretEnv": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string"
+            },
+            "description": "选这条车道时引擎起服必须读到的密钥键(缺任一 ⇒ 起服拒;值由运维自备)。"
+          }
+        }
+      }
+    }
+  }
+}

package/deploy/facts/sandbox-rbac.json

@@ -0,0 +1,113 @@
+{
+  "schemaVersion": 1,
+  "rules": [
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["pods"],
+      "verbs": ["get", "list", "create", "delete"],
+      "when": "always",
+      "need": "called",
+      "why": "沙箱 pod 的生命周期:remote-env-k8s.ts#createPod 建(POST pods)并读就绪(GET pods/<名>)· remote-env-k8s.ts#listSandboxPods 按标签列(GET pods?labelSelector)· remote-env-k8s.ts#reconnect 读存活(GET pods/<名>)· remote-env-k8s.ts#deletePod 删(DELETE pods/<名>)"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["pods"],
+      "verbs": ["watch"],
+      "when": "always",
+      "need": "retained",
+      "why": "兼容保留:chart 一直授着,适配器没有 watch 调用"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["pods/exec"],
+      "verbs": ["create", "get"],
+      "when": "always",
+      "need": "called",
+      "why": "在沙箱 pod 里执行命令:remote-env-k8s.ts#execUrl 拼 pods/<名>/exec 的连接地址"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["pods/attach"],
+      "verbs": ["create", "get"],
+      "when": "always",
+      "need": "retained",
+      "why": "兼容保留:chart 一直授着,适配器没有 attach 调用"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["pods/log"],
+      "verbs": ["get"],
+      "when": "always",
+      "need": "retained",
+      "why": "兼容保留:chart 一直授着,适配器没有读日志的调用"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["persistentvolumeclaims"],
+      "verbs": ["get", "create", "deletecollection"],
+      "when": "WORKSPACE_CACHE=volume",
+      "need": "called",
+      "why": "按工作区空间的构建缓存卷:remote-env-k8s.ts#ensureCacheClaim 按名读、没有就建(GET / POST persistentvolumeclaims)· remote-env-k8s.ts#cacheClaimBound 按名读 · remote-env-k8s.ts#reclaimSpaceCache 空间结束按标签回收(DELETE persistentvolumeclaims?labelSelector = deletecollection);缺它 ⇒ 缓存卷拿不到,适配器按 fail-open 照起、不挂卷(计数 server.workspace-cache.unavailable)"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["persistentvolumeclaims"],
+      "verbs": ["delete"],
+      "when": "WORKSPACE_CACHE=volume",
+      "need": "retained",
+      "why": "兼容保留:chart 一直授着,适配器回收只发按标签的 deletecollection,没有按名 delete 的调用"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": [""],
+      "resources": ["secrets"],
+      "verbs": ["create"],
+      "when": "K8S_SANDBOX_ENV",
+      "need": "called",
+      "why": "沙箱秘密座:动词取自 SANDBOX_SECRET_SEAT_VERBS.env —— 起服门(boot/execution-env.ts ensureSandboxSecretSeat)问的与 remote-env-k8s.ts#createOwnedSecret 为 env Secret 真发的(POST secrets)是同一行;起服门只在有效转发集合非空(名单点到的键在服务进程环境里有值)时问:答 denied ⇒ server 起服拒,问不到 ⇒ 告警 sandbox_secret_seat_unverified 照起;名单非空而有效集合为空时本行是保守多授(安装器看不到服务进程的运行时环境,引擎此时既不问也不调)"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": ["networking.k8s.io"],
+      "resources": ["networkpolicies"],
+      "verbs": ["list"],
+      "when": "always",
+      "need": "called",
+      "why": "起服的出网自检读本 ns 的 NetworkPolicy 集合:remote-env-k8s.ts#egressPolicyGaps(GET .../networkpolicies)"
+    },
+    {
+      "scope": "Role",
+      "apiGroups": ["networking.k8s.io"],
+      "resources": ["networkpolicies"],
+      "verbs": ["get"],
+      "when": "always",
+      "need": "retained",
+      "why": "兼容保留:chart 一直授着,适配器只读集合(list),没有按名 get"
+    },
+    {
+      "scope": "ClusterRole",
+      "apiGroups": [""],
+      "resources": ["nodes"],
+      "verbs": ["list"],
+      "when": "always",
+      "need": "called",
+      "why": "出网自检读节点表(节点是集群级对象 ⇒ ClusterRole + Binding 给同一只服务账号):remote-env-k8s.ts#egressPolicyGaps(GET /api/v1/nodes)"
+    },
+    {
+      "scope": "ClusterRole",
+      "apiGroups": [""],
+      "resources": ["nodes"],
+      "verbs": ["get"],
+      "when": "always",
+      "need": "retained",
+      "why": "兼容保留:chart 一直授着,适配器只读集合(list),没有按名 get"
+    }
+  ]
+}

package/deploy/facts/sandbox-rbac.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "k8s 沙箱车道(REMOTE_EXEC=k8s)的服务账号在沙箱命名空间 / 集群里需要的 RBAC 规则;每条规则何时授、引擎适配器真调还是兼容保留。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "rules"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "本份数据的形版本;读方不认识的版本整份拒读。"
+    },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "x-uniqueKey": ["scope", "apiGroups", "resources", "need"],
+      "description": "规则行;同一资源的动词按 need 拆成两行,授权时并回一条规则(Kubernetes 对同一资源的多条规则取并集)。",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["scope", "apiGroups", "resources", "verbs", "when", "need", "why"],
+        "properties": {
+          "scope": {
+            "type": "string",
+            "enum": ["Role", "ClusterRole"],
+            "description": "Role = 沙箱命名空间里的 Role;ClusterRole = 集群级对象(节点)要的 ClusterRole,绑给同一只服务账号。"
+          },
+          "apiGroups": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string"
+            },
+            "description": "API 组;核心组写空串。"
+          },
+          "resources": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string"
+            },
+            "description": "资源名(子资源写 pods/exec 这种形)。"
+          },
+          "verbs": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "enum": ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"]
+            },
+            "description": "动词。"
+          },
+          "when": {
+            "type": "string",
+            "enum": ["always", "WORKSPACE_CACHE=volume", "K8S_SANDBOX_ENV"],
+            "description": "always = 恒授;WORKSPACE_CACHE=volume = 引擎开着按工作区空间的缓存卷时授(引擎用到它的条件同一个);K8S_SANDBOX_ENV = 引擎的沙箱 env 名单非空时授 —— 这是保守的授权条件,引擎真正问 / 调用的条件是名单点到的键在服务进程环境里有值,两者之差写在该行 why 里。"
+          },
+          "need": {
+            "type": "string",
+            "enum": ["called", "retained"],
+            "description": "called = 引擎适配器源码真发这些调用;retained = 随包 chart 一直授着、适配器源码里零调用(兼容保留)。"
+          },
+          "why": {
+            "type": "string",
+            "description": "这一行为什么在(called 行写着调用它的适配器方法)。"
+          }
+        }
+      }
+    }
+  }
+}

package/deploy/facts/sealed-key.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "dirEnv": "SEALED_KEY_DIR",
+  "dirPath": "absolute",
+  "subdirs": ["checkpoint-ctx-keys"],
+  "dirMode": "0700",
+  "fileMode": "0600",
+  "requirements": ["persist-across-restart", "shared-by-all-replicas", "writable", "whole-directory"]
+}

package/deploy/facts/sealed-key.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "引擎钥匙保管目录的安装契约:sealed 形模型钥匙的 X25519 钥匙对与停驻行凭据封签的钥匙都在这个目录里,私钥只存在这里。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "dirEnv", "dirPath", "subdirs", "dirMode", "fileMode", "requirements"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "本份数据的形版本;读方不认识的版本整份拒读。"
+    },
+    "dirEnv": {
+      "type": "string",
+      "const": "SEALED_KEY_DIR",
+      "description": "安装器必须给引擎设的环境变量:值 = 保管目录的挂载位。"
+    },
+    "dirPath": {
+      "type": "string",
+      "enum": ["absolute"],
+      "description": "absolute = 值必须是绝对路径(相对路径起服即拒;设了而目录建不了保管店也起服拒)。"
+    },
+    "subdirs": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string"
+      },
+      "description": "引擎在保管目录之下自建的子目录(随目录一起持久、一起共享)。"
+    },
+    "dirMode": {
+      "type": "string",
+      "const": "0700",
+      "description": "引擎每次起服把保管目录设成的权限位(四位八进制);目录必须允许引擎进程改它的权限。"
+    },
+    "fileMode": {
+      "type": "string",
+      "const": "0600",
+      "description": "引擎写钥匙文件时设的权限位(四位八进制)。"
+    },
+    "requirements": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["persist-across-restart", "shared-by-all-replicas", "writable", "whole-directory"]
+      },
+      "description": "persist-across-restart = 目录跨进程重启保留(不然重启后封给旧钥匙的密文与停驻行凭据开不开);shared-by-all-replicas = 同一部署的每个副本挂同一份目录(多副本要支持多处读写的存储;不然 A 副本封的东西 B 副本开不开);writable = 引擎对目录可写(空目录起服时生成一把钥匙;只读挂载 ⇒ 建不了保管店);whole-directory = 持久与共享的单位是整个目录,含 subdirs 列出的子目录。"
+    }
+  }
+}

package/deploy/sema-up/chart/templates/_helpers.tpl

@@ -127,3 +127,22 @@ volumes:
     persistentVolumeClaim: { claimName: {{ include "sema.sealedKey.claimName" . }} }
 {{- end -}}
 {{- end -}}
+
+{{- /*
+  沙箱特性开关(`sandbox.workspaceCacheVolume` ↔ 引擎 WORKSPACE_CACHE=volume;`sandbox.sandboxEnv` ↔ 引擎 K8S_SANDBOX_ENV):
+  同一个 chart 值既决定沙箱 Role 带不带对应规则(`sandbox-rbac.yaml`),又写引擎旋钮(下面的 `sema.sandbox.switchEnv`)—— 两处不再各写一份。
+  判开关的 `sema.sandbox.switchOn` 定义在 `sandbox-rbac.yaml` 里(那份模板整份被取用方拷走,所以它自带自己用到的助手,不依赖本文件);本文件的 `switchEnv` 与它共用同一个定义。
+  「哪条规则由哪个开关决定」与开关的值路径 / 引擎旋钮的书写处只有 server 源码里的规则表 `src/sandbox-rbac-rules.ts`;`switchEnv` 的体与 `sandbox-rbac.yaml` 里的条件由 scripts/gen-deploy-lanes.ts 从它生成。
+*/ -}}
+
+{{- /* worker 容器 env 里的沙箱特性开关旋钮(`indent 12` 之后接在 env 列表里;体由生成器从规则表渲出);两个开关都关 ⇒ 什么都不出。 */ -}}
+{{- define "sema.sandbox.switchEnv" -}}
+{{/* @generated-begin sandbox-switch-env */}}
+{{- if eq (include "sema.sandbox.switchOn" (list . "workspaceCacheVolume" "bool")) "true" }}
+- { name: WORKSPACE_CACHE, value: "volume" }
+{{- end }}
+{{- if eq (include "sema.sandbox.switchOn" (list . "sandboxEnv" "names")) "true" }}
+- { name: K8S_SANDBOX_ENV, value: {{ .Values.sandbox.sandboxEnv | quote }} }
+{{- end }}
+{{/* @generated-end sandbox-switch-env */}}
+{{- end -}}

package/deploy/sema-up/chart/templates/sandbox-rbac.yaml

@@ -1,4 +1,29 @@
-# ── 沙箱 lane RBAC(k8s+kata;pod 五动词 + 缓存卷四动词 + 沙箱秘密座 create + 出网自检的两只只读:本 ns 的 NetworkPolicy、集群的节点表)────────────────────────────────
+{{- /*
+  沙箱特性开关的判官(本文件的规则条件与 _helpers.tpl 里的 `sema.sandbox.switchEnv` 共用):实参是 `list <根上下文> <sandbox 下的键> <形>`,输出 "true" / "false":
+    · 形 `bool`:**只收布尔**(`--set-string …=false` / 带引号的 "false" 是字符串,模板里字符串恒为真 ⇒ 会静默授出规则,所以非布尔渲染即拒;键缺席也拒 —— 把本模板整份拷进别的 chart 的人要在自己的 values 里补这个键);
+    · 形 `names`:**只收字符串**,去掉首尾空白后非空 = 开(引擎旋钮是 NAME,NAME 名单;形错由引擎起服拒,不在这里重判)。
+  定义放在本文件里而不放 `_helpers.tpl`:本模板整份被取用方原样拷走,它用到的助手必须随它走。
+*/ -}}
+{{- define "sema.sandbox.switchOn" -}}
+{{- $root := index . 0 -}}
+{{- $key := index . 1 -}}
+{{- $kind := index . 2 -}}
+{{- $v := index $root.Values.sandbox $key -}}
+{{- if eq $kind "bool" -}}
+{{- if not (kindIs "bool" $v) -}}
+{{- fail (printf "sandbox.%s must be a boolean (true or false), got %s %q — a string such as \"false\" is truthy in a template and would silently grant the rule" $key (kindOf $v) (toString $v)) -}}
+{{- end -}}
+{{- $v -}}
+{{- else -}}
+{{- if not (kindIs "string" $v) -}}
+{{- fail (printf "sandbox.%s must be a string (a NAME,NAME list; empty = off), got %s %q" $key (kindOf $v) (toString $v)) -}}
+{{- end -}}
+{{- if ne (trim $v) "" -}}true{{- else -}}false{{- end -}}
+{{- end -}}
+{{- end -}}
+# ── 沙箱 lane RBAC(k8s+kata):pod 生命周期 / exec / log、出网自检的两只只读(本 ns 的 NetworkPolicy、集群的节点表)恒授;
+#    缓存卷的 persistentvolumeclaims 与沙箱秘密座的 secrets create 只在对应特性开关开着时授(sandbox.workspaceCacheVolume / sandbox.sandboxEnv)。
+#    「哪条规则由哪个开关决定」只写在 server 源码的规则表 src/sandbox-rbac-rules.ts;下面两个规则区由 scripts/gen-deploy-lanes.ts 从它生成,不要手改。────────────────────────────────
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -20,29 +45,40 @@ metadata:
   name: sema-runner
   namespace: {{ .Values.sandbox.namespace }}
 rules:
+  {{/* @generated-begin sandbox-role-rules */}}
+  # 沙箱 pod 的生命周期:remote-env-k8s.ts#createPod 建(POST pods)并读就绪(GET pods/<名>)· remote-env-k8s.ts#listSandboxPods 按标签列(GET pods?labelSelector)· remote-env-k8s.ts#reconnect 读存活(GET pods/<名>)· remote-env-k8s.ts#deletePod 删(DELETE pods/<名>)
+  # 兼容保留:chart 一直授着,适配器没有 watch 调用
   - apiGroups: [""]
     resources: [pods]
     verbs: [get, list, watch, create, delete]
+  # 在沙箱 pod 里执行命令:remote-env-k8s.ts#execUrl 拼 pods/<名>/exec 的连接地址
+  # 兼容保留:chart 一直授着,适配器没有 attach 调用
   - apiGroups: [""]
     resources: [pods/exec, pods/attach]
-    verbs: [create, get]
+    verbs: [get, create]
+  # 兼容保留:chart 一直授着,适配器没有读日志的调用
   - apiGroups: [""]
     resources: [pods/log]
     verbs: [get]
-  # 按工作区空间的构建缓存卷(WORKSPACE_CACHE=volume):连沙箱时按名读、没有就建;空间结束(会话删除 / 留存 sweep)按标签回收
+  {{- if eq (include "sema.sandbox.switchOn" (list . "workspaceCacheVolume" "bool")) "true" }}
+  # 按工作区空间的构建缓存卷:remote-env-k8s.ts#ensureCacheClaim 按名读、没有就建(GET / POST persistentvolumeclaims)· remote-env-k8s.ts#cacheClaimBound 按名读 · remote-env-k8s.ts#reclaimSpaceCache 空间结束按标签回收(DELETE persistentvolumeclaims?labelSelector = deletecollection);缺它 ⇒ 缓存卷拿不到,适配器按 fail-open 照起、不挂卷(计数 server.workspace-cache.unavailable)
+  # 兼容保留:chart 一直授着,适配器回收只发按标签的 deletecollection,没有按名 delete 的调用
   - apiGroups: [""]
     resources: [persistentvolumeclaims]
     verbs: [get, create, delete, deletecollection]
-  # 沙箱秘密座:K8S_SANDBOX_ENV 点名的值只进每只 pod 自己的 Secret(pod spec 只带 secretKeyRef;Secret 属于 pod,随 pod 由集群回收)
-  # 动词 = 适配器为 env Secret 真发的调用:create;不读回(无 get)、不删(随属主 pod 由集群 GC)。名单非空而缺它 ⇒ server 起服拒(起服 SelfSubjectAccessReview 问的正是它)
-  # 成员 git 凭据平面(本版恒关)打开时,租约 Secret 还要 patch —— 那时再加
+  {{- end }}
+  {{- if eq (include "sema.sandbox.switchOn" (list . "sandboxEnv" "names")) "true" }}
+  # 沙箱秘密座:动词取自 SANDBOX_SECRET_SEAT_VERBS.env —— 起服门(boot/execution-env.ts ensureSandboxSecretSeat)问的与 remote-env-k8s.ts#createOwnedSecret 为 env Secret 真发的(POST secrets)是同一行;起服门只在有效转发集合非空(名单点到的键在服务进程环境里有值)时问:答 denied ⇒ server 起服拒,问不到 ⇒ 告警 sandbox_secret_seat_unverified 照起;名单非空而有效集合为空时本行是保守多授(安装器看不到服务进程的运行时环境,引擎此时既不问也不调)
   - apiGroups: [""]
     resources: [secrets]
     verbs: [create]
-  # 起服的出网自检读本 ns 的 NetworkPolicy(只读)
+  {{- end }}
+  # 起服的出网自检读本 ns 的 NetworkPolicy 集合:remote-env-k8s.ts#egressPolicyGaps(GET .../networkpolicies)
+  # 兼容保留:chart 一直授着,适配器只读集合(list),没有按名 get
   - apiGroups: [networking.k8s.io]
     resources: [networkpolicies]
     verbs: [get, list]
+  {{/* @generated-end sandbox-role-rules */}}
 ---
 apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
@@ -64,9 +100,13 @@ kind: ClusterRole
 metadata:
   name: sema-runner-nodes-{{ .Values.sandbox.namespace }}
 rules:
+  {{/* @generated-begin sandbox-clusterrole-rules */}}
+  # 出网自检读节点表(节点是集群级对象 ⇒ ClusterRole + Binding 给同一只服务账号):remote-env-k8s.ts#egressPolicyGaps(GET /api/v1/nodes)
+  # 兼容保留:chart 一直授着,适配器只读集合(list),没有按名 get
   - apiGroups: [""]
     resources: [nodes]
     verbs: [get, list]
+  {{/* @generated-end sandbox-clusterrole-rules */}}
 ---
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding

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

@@ -77,6 +77,10 @@ spec:
             - { name: K8S_RUNTIME_CLASS, value: {{ .Values.sandbox.runtimeClass }} }
             - { name: K8S_SANDBOX_IMAGE, value: {{ .Values.sandbox.image | quote }} }
             - { name: K8S_SANDBOX_IPV6, value: {{ .Values.sandbox.ipv6 | quote }} }
+{{- /* 沙箱特性开关(sandbox.workspaceCacheVolume / sandbox.sandboxEnv)同一个值写引擎旋钮与沙箱 Role 规则,见 _helpers.tpl。 */}}
+{{- with (include "sema.sandbox.switchEnv" . | trim) }}
+{{ . | indent 12 }}
+{{- end }}
             - { name: K8S_TOKEN, valueFrom: { secretKeyRef: { name: sema-runner-token-copy, key: token } } }
 {{- /* 耐久审批的显式表态与停驻封签钥匙卷同源(助手 sema.durableApproval / sema.sealedKey.*,见 _helpers.tpl):关持久 ⇒ 显式 false;留空 ⇒ 不渲。 */}}
 {{- with (include "sema.sealedKey.env" .) }}

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

@@ -90,6 +90,10 @@ spec:
 {{- end }}
             - { name: K8S_SANDBOX_IMAGE, value: {{ .Values.sandbox.image | quote }} }
             - { name: K8S_SANDBOX_IPV6, value: {{ .Values.sandbox.ipv6 | quote }} }
+{{- /* 沙箱特性开关(sandbox.workspaceCacheVolume / sandbox.sandboxEnv)同一个值写引擎旋钮与沙箱 Role 规则,见 _helpers.tpl。 */}}
+{{- with (include "sema.sandbox.switchEnv" . | trim) }}
+{{ . | indent 12 }}
+{{- end }}
             - { name: K8S_TOKEN, valueFrom: { secretKeyRef: { name: sema-runner-token-copy, key: token } } }
 {{- /* 耐久审批的显式表态与停驻封签钥匙卷同源(助手 sema.durableApproval / sema.sealedKey.*,见 _helpers.tpl):关持久 ⇒ 显式 false;留空 ⇒ 不渲。 */}}
 {{- with (include "sema.sealedKey.env" .) }}

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

@@ -149,6 +149,13 @@ sandbox:
   #   每个节点的 kubelet 要 --allowed-unsafe-sysctls 点名它们,否则沙箱 pod 起不来;沙箱 ns 不能 enforce PodSecurity baseline。
   #   enabled = 不动 pod(缺省):只执行 IPv4 的出网策略(k3s 单栈缺省即是)管不到 pod 的 IPv6,server 起服每次一行提醒。
   ipv6: enabled
+  # 沙箱特性开关 —— 同一个值既写引擎旋钮、又决定沙箱 Role 带不带对应规则(「哪条规则由哪个开关决定」只写在 server 源码的规则表 src/sandbox-rbac-rules.ts):
+  #   workspaceCacheVolume(布尔,只收 true / false)= 按工作区空间的构建缓存卷:true ⇒ 引擎 env WORKSPACE_CACHE=volume,Role 加 persistentvolumeclaims 的
+  #     get / create / delete / deletecollection;false(缺省)⇒ 引擎不建卷、Role 不授这四个动词。前提:集群有缺省 StorageClass、引擎有存储后端(本 chart 恒有 PG)。
+  #   sandboxEnv(名单字符串 NAME,NAME)= 沙箱带外 env 名单:非空 ⇒ 引擎 env K8S_SANDBOX_ENV=<名单>,Role 加 secrets 的 create;空(缺省)⇒ 都不加。
+  #     名单点到的键的**值**要在引擎进程的环境里(本 chart 不替部署提供值的来源);点到而环境里没有的键不转发。
+  workspaceCacheVolume: false
+  sandboxEnv: ""
   # 沙箱出网策略(NetworkPolicy,egress 白名单;要集群 CNI 带 NetworkPolicy 控制器 —— k3s 缺省自带):
   #   放行 = DNS(kube-dns)+ 对象存储(chart 自带的 MinIO 9000,加 objectStore 点名的脸)+ IPv4 公网面;
   #   拒   = 私网 / 共享 / 链路本地 / 环回六段(10/8、172.16/12、192.168/16、100.64/10、169.254/16、127/8)整段,