@sema-agent/server 7.136.0 → 7.138.0

package/dist/config-catalog.js

@@ -7,6 +7,7 @@ import { WORKSPACE_CACHE_DEFAULT, WORKSPACE_CACHE_MOUNT_DEFAULT, WORKSPACE_CACHE
 import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "./object-store-buckets.js";
 import { WORKSPACE_PERSIST_DEFAULT, WORKSPACE_PERSIST_WORDS, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_RANGE, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE } from "./workspace-space.js";
 import { APPROVAL_ASK_RETENTION_DEFAULT_MS, APPROVAL_ASK_RETENTION_FLOOR_MS } from "./approval-ask-retention.js";
+import { SANDBOX_SECRET_SEAT_VERBS } from "./plugins/k8s-exec-protocol.js";
 import { LIVENESS_MS_DEFAULT } from "./exec-bounds.js";
 import { THINKING_FORMATS } from "./model-compat.js";
 import { AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, CENTER_BASE_URL_RULE, CONFIG_PROVIDER_WORDS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, DEVICE_DELIVERY_TIMEOUT_BOUNDS, DEVICE_EXEC_TIMEOUT_BOUNDS, FIRST_BYTE_TIMEOUT_BOUNDS, FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS } from "./config-types.js";
@@ -125,6 +126,7 @@ export const CONFIG_CATALOG = [
     r("DEVICE_MAX_INFLIGHT_PER_DEVICE", "orchestration", "number", `per-device 在途上限(超额云侧排队;原值进 helloAck.maxInflight;须为 ≥ ${DEVICE_HELLO_ACK_BOUNDS.maxInflight.min} 的规范十进制整数,其余拒启 —— 0 会让每次派发都 device.busy)`, { derivedDefaultNote: "缺席 ⇒ 4(§11-O3 裁定值)" }),
     r("DEVICE_MAX_PREAUTH_PER_REMOTE", "orchestration", "number", "未鉴权握手的 per-remote 并发帽(正整数或字面 off;XFF/NAT 形用 off+全局帽)", { danger: SEC, derivedDefaultNote: "缺席 ⇒ 8" }),
     r("DEVICE_RECONNECT_GRACE_MS", "orchestration", "number", `device 断连后在途不判丢的窗(ms;同 epoch 重连续接;原值进 helloAck.reconnectGraceMs;须为 [${DEVICE_HELLO_ACK_BOUNDS.reconnectGraceMs.min}, ${DEVICE_HELLO_ACK_BOUNDS.reconnectGraceMs.max}] 内规范十进制整数,其余拒启)`, { derivedDefaultNote: "缺席 ⇒ adapter 默认 120s" }),
+    r("DEVICE_RELAY_URL", "orchestration", "url", "设备直达入口:设备连不到本引擎自己的地址(引擎在中继 / 网关之后)时拨的那一个 ws(s) URL,逐字上 /v1/capabilities 的 deviceExecutor.relayUrl;须为无 userinfo / query / fragment、不带凭据形的 ws:// 或 wss:// 绝对地址,其余拒启。不从 FLEET_ADVERTISE_ADDRESS 派生(那是对中心公告的地址,受众不是设备)", { derivedDefaultNote: "缺席 ⇒ 能力面不带 relayUrl,设备按引擎地址 + deviceExecutor.wsPath 拨号" }),
     r("DEVICE_SUPERSEDE", "orchestration", "enum", "同 deviceId 二连的顶替策略", { enumValues: ["stale_only", "deny"], staticDefault: "stale_only", danger: SEC }),
     r("DIRECT_APPROVAL_DOOR", "approval", "boolean", "直连 /decide 门(无 BFF 的桌面/CLI 客户端;开 ⇒ 要求签名 JWT+HMAC 信封,principal 头降级不可信)", { staticDefault: "false", danger: SEC, configKey: "directApprovalDoor" }),
     r("DOCKER_COMMAND_TIMEOUT_MS", "orchestration", "number", "local-docker 车道单命令超时(ms)"),
@@ -163,9 +165,13 @@ export const CONFIG_CATALOG = [
     r("FLEET_GENERATION", "integrations", "string", "fleet 成员的代际(配置渲染器写;引擎回声到心跳与 /health 的 generation)。缺席 ⇔ 非 fleet 成员(不续服务租约、不受围栏);在场必须是规范十进制串(\"0\" / \"7\";空串、前导零、符号、空白拒启)", { danger: SEC, configKey: "fleetGeneration" }),
     r("FLEET_LEASE_FAIL_CLOSED", "integrations", "boolean", "租约连接级失败(中心鉴权拒 / 凭证不可读 / 不可达 / 5xx / 超时 / 坏体)时计费入口拒 503 fleet.lease_unavailable(true)还是放行(false);409 not-lease 与耗尽 429 不受它管;词表外拒启", { danger: SEC, derivedDefaultNote: "缺席 ⇒ 按部署姿态派生:REQUIRE_PRINCIPAL=true ⇒ true(多租:额度是安全轴);单用户 ⇒ false(AP 姿态)。显式值压过派生。生效值见 caps centerWiring.failMode", configKey: "fleetLeaseFailClosed" }),
     r("FLEET_LEASE_OUTAGE_MAX_MS", "integrations", "number", "一台实例「活着而不服务」的最长时长 T_max(ms),两处读它:① 服务租约中心不可达的容忍上限 —— 租约过期满这么久 ⇒ 新计费提交 503 state.lease_expired(取消 / HITL 应答 / 续跑 / 读面照放行,在飞不动,/readyz 不翻),只在 fleet 成员 ∧ 中心宣告 servingLease 能力位时生效;② 排空口 POST /v1/admin/drain 的期限上界 —— deadlineAt 离此刻超过它 ⇒ 400 request.field_invalid,成员与非成员同读;< 60000(租约 TTL 地板)或非整数拒启", { danger: SEC, staticDefault: String(FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS), configKey: "fleetLeaseOutageMaxMs" }),
-    r("FLEET_SCOPE", "integrations", "string", "本引擎所在的租户 scope(配置渲染器为多租引擎写;唯一读者 = 排空口 POST /v1/admin/drain 的身份比对,请求不带 scope 也读成缺省 scope)。在场必须是 scope id 形(小写字母 / 数字 / 内部连字符,1–64;空串拒启);与 FLEET_GENERATION 不联动(成员缺席 ⇒ 缺省 scope)。续租体与心跳不带它(scope 由中心凭证绑定)", { danger: SEC, staticDefault: GLOBAL_SCOPE, configKey: "fleetScope" }),
+    r("FLEET_SCOPE", "integrations", "string", "本引擎所在的租户 scope(配置渲染器对每台受管引擎写,缺省 scope 也写;手接的引擎缺席 = 缺省 scope;唯一读者 = 排空口 POST /v1/admin/drain 的身份比对,请求不带 scope 也读成缺省 scope)。在场必须是 scope id 形(小写字母 / 数字 / 内部连字符,1–64;空串拒启);与 FLEET_GENERATION 不联动(成员缺席 ⇒ 缺省 scope)。续租体与心跳不带它(scope 由中心凭证绑定)", { danger: SEC, staticDefault: GLOBAL_SCOPE, configKey: "fleetScope" }),
     r("FORK_ENABLED", "orchestration", "boolean", "CC /fork(core Fork 工具)装配开关", { derivedDefaultNote: "posture 三态:缺席 = 单用户 ⇒ on / 多租户 ⇒ off(per-principal entitlement 另判)", configKey: "forkEnabled" }),
-    r("GATEWAY_MAX_RETRIES", "modelPlane", "number", "openai 兼容腿每次调用重试上限", { derivedDefaultNote: "缺席 ⇒ 不传引擎,引擎默认当家" }),
+    r("GATEWAY_MAX_RETRIES", "modelPlane", "number", "openai 兼容腿每次调用重试上限", {
+        derivedDefaultNote: "缺席 ⇒ 按外层拓扑分两态(启动日志 `brain` 字段的 `gatewayRetryCap` 回显哪一态):配了备用网关(`MODEL_GATEWAY_FALLBACK_URLS`)/ 开了断路器开关(`MODEL_CIRCUIT_BREAKER`,单路网关上也算)/ 开了反应式降级(配着 `MODEL_DEGRADE_TO` 且 `MODEL_DEGRADE_REACTIVE` 开)" +
+            "⇒ 网关各路 server 传 2(`fast-fail:2`),引擎的 `SEMA_MAX_RETRIES` 被遮蔽(降级兜底腿不吃这条收窄:不设时它不传,引擎默认当家);没有这些快切层 ⇒ 不传(`engine-default`),引擎默认当家(读 `SEMA_MAX_RETRIES`,没设是 10)。" +
+            "设了恒赢(`env:<n>`):原样传给引擎(降级兜底腿也吃显式值)并遮蔽 `SEMA_MAX_RETRIES`",
+    }),
     r("GIT_API_BASEURL", "integrations", "url", "repo 工具的 Git host API base", { configKey: "gitApiBaseUrl" }),
     r("GIT_API_KIND", "integrations", "enum", "Git host API 方言", { enumValues: ["gitea", "github"], staticDefault: "gitea", configKey: "gitApiKind" }),
     r("GIT_API_TOKEN", "integrations", "secret", "repo 工具的 Git host 凭据", { danger: SEC }),
@@ -204,7 +210,8 @@ export const CONFIG_CATALOG = [
     r("K8S_MOUNT_PATH", "orchestration", "path", "k8s 工作区挂载路径"),
     r("K8S_NAMESPACE", "orchestration", "string", "沙箱 pod namespace"),
     r("K8S_RUNTIME_CLASS", "orchestration", "string", "沙箱 pod runtimeClass(Kata 等)"),
-    r("K8S_SANDBOX_ENV", "orchestration", "secret", "转发进 k8s 沙箱 pod 容器 env 的本进程 env 点名表(NAME,NAME;点到的键从 worker env 原样取,值只进 pod env —— 不进 spec 的其它位置 / 工作区 / 快照 / center / 事件日志;与 LSP_ENV_ALLOW / E2B_SANDBOX_ENV / DOCKER_SANDBOX_ENV 同一只解析器与「点名放行」谓词:形错 / 点名名单型旋钮拒启且不回显值;本进程环境里没有的名按序号 warn、不转发;与包源派生 env 撞名时显式名单胜;只在本车道被选中时求值;原文按凭据类对待:只回在场位、不进任何子进程)", { danger: SEC }),
+    r("K8S_SANDBOX_BROKER_IMAGE", "orchestration", "string", "成员 git 凭据代理容器的镜像(k8s 沙箱 pod 的 containers[1],只挂在成员 run 的 pod 上;建议填本引擎自身镜像 —— 代理是本包里固定路径的一只程序,命令固定);不设 ⇒ 成员 git 凭据平面关(GET /v1/capabilities 的 credentialPlane.sandboxGit = broker_image_unset),任何 pod 都不挂代理,pod 形逐字节同不设时;只在 REMOTE_EXEC=k8s 被选中时求值"),
+    r("K8S_SANDBOX_ENV", "orchestration", "secret", `转发进 k8s 沙箱 pod 容器 env 的本进程 env 点名表(NAME,NAME;点到的键从 worker env 原样取,值只进该 pod 自己的 Secret —— pod spec 的容器 env 只带 secretKeyRef 引用、不带值,Secret 随 pod 由集群回收;不进工作区 / 快照 / center / 事件日志;沙箱命名空间的 Role 要 secrets ${SANDBOX_SECRET_SEAT_VERBS.env.join(" / ")},起服问不许即拒启;与 LSP_ENV_ALLOW / E2B_SANDBOX_ENV / DOCKER_SANDBOX_ENV 同一只解析器与「点名放行」谓词:形错 / 点名名单型旋钮拒启且不回显值;本进程环境里没有的名按序号 warn、不转发;与包源派生 env 撞名时显式名单胜;只在本车道被选中时求值;原文按凭据类对待:只回在场位、不进任何子进程)`, { danger: SEC }),
     r("K8S_SANDBOX_IMAGE", "orchestration", "string", "k8s 车道沙箱镜像(REMOTE_EXEC=k8s 必需件)"),
     r("K8S_SANDBOX_IPV6", "orchestration", "enum", "k8s 沙箱 pod 的 IPv6:disabled = pod 级 sysctl 关 IPv6(net.ipv6.conf.all / default.disable_ipv6=1;两只都不在 k8s 的 safe sysctl 表里 ⇒ 每个节点 kubelet 要 --allowed-unsafe-sysctls 点名,否则 pod 起不来;沙箱 ns 不能 enforce PodSecurity baseline / restricted);enabled = 不动 pod(pod 保留平台给的 IPv6,只执行 IPv4 的出网策略管不到它,起服自检每次一行 sandbox_egress_policy_gap{kind: ipv6_enabled});词表外拒启", { enumValues: SANDBOX_IPV6_WORDS, staticDefault: SANDBOX_IPV6_DEFAULT, danger: SEC }),
     r("K8S_TIMEOUT_MS", "orchestration", "number", "k8s 沙箱 pod 寿命(activeDeadlineSeconds,ms;整只 pod 的泄漏护栏,后台任务超时也被它钳;各条命令的超时见工具超时)"),
@@ -290,9 +297,9 @@ export const CONFIG_CATALOG = [
     r("MODEL_CHEAP_ID", "modelPlane", "string", "cheap 槽模型 id(subagent/summarize 两 role 走它;未设或与 MODEL_ID 同 id=全落主模型,同 id 不铸 cheap 槽)", { danger: BILL, center: cModels("models[].id") }),
     r("MODEL_CHEAP_MAX_TOKENS", "modelPlane", "number", "cheap 槽输出上限", { derivedDefaultNote: "缺席 ⇒ 继承主模型", center: cModels("models[].maxTokens") }),
     r("MODEL_CHEAP_REASONING", "modelPlane", "boolean", "cheap 槽 reasoning 声明(三态:缺席继承主模型)", { derivedDefaultNote: "缺席 ⇒ 继承主模型" }),
-    r("MODEL_CHEAP_VISION", "modelPlane", "boolean", "cheap 槽 vision 声明(三态:缺席继承主模型;text-only cheap 必设 false 让预检真拦)", { derivedDefaultNote: "缺席 ⇒ 继承主模型" }),
+    r("MODEL_CHEAP_VISION", "modelPlane", "boolean", "cheap 槽 vision 声明(三态:缺席继承主模型;text-only cheap 必设 false,引擎才会在替换图片时于会话流发 `model.capability_downgraded`)", { derivedDefaultNote: "缺席 ⇒ 继承主模型" }),
     r("MODEL_CIRCUIT_BREAKER", "modelPlane", "boolean", "模型腿熔断开关", { staticDefault: String(RESILIENCE_DEFAULTS.circuitBreaker.value) }),
-    r("MODEL_CODE_ROLES", "modelPlane", "csv", "给点名 role 附编码 persona(role 表内名字才生效)"),
+    r("MODEL_CODE_ROLES", "modelPlane", "csv", "给点名 role 按词点名引擎的编码角色基底(`promptRole: \"code\"`;role 表内名字才生效)"),
     r("MODEL_CONTEXT_WINDOW", "modelPlane", "number", "主模型上下文窗声明", { staticDefault: "262144", configKey: "model", resolve: (c) => c.model.contextWindow ?? null, center: cModels("models[].contextWindow") }),
     r("MODEL_COST_CACHE_READ", "modelPlane", "number", "主模型 cache-read 单价(per-1M USD;显式 0=声明免费,不是「没配」)", { derivedDefaultNote: "四键全缺席 ⇒ 未定价(不铸 cost 键,成本读面缺席);任一设 ⇒ 四键在场,未设的按 0 显式", danger: BILL, resolve: (c) => c.model.cost?.cacheRead ?? null, center: cModels("models[].cost.cacheRead") }),
     r("MODEL_COST_CACHE_WRITE", "modelPlane", "number", "主模型 cache-write 单价", { derivedDefaultNote: "四键全缺席 ⇒ 未定价(不铸 cost 键,成本读面缺席);任一设 ⇒ 四键在场,未设的按 0 显式", danger: BILL, resolve: (c) => c.model.cost?.cacheWrite ?? null, center: cModels("models[].cost.cacheWrite") }),
@@ -341,14 +348,16 @@ export const CONFIG_CATALOG = [
         },
     }),
     r("MODEL_VERIFIER", "modelPlane", "string", "verify 门的异构 verifier(须命中目录;typo 回 default 并 boot warn=自评自批)", { derivedDefaultNote: "缺席/不在目录 ⇒ default(=implementer,去相关性失效警告)" }),
-    r("MODEL_VISION", "modelPlane", "boolean", "主模型 vision 声明(三态:true / false / 缺席 = 未声明;false = 明说不收图:带图请求的图被换成占位句交给模型,提交时计数并告警)", {
-        derivedDefaultNote: "缺席 ⇒ 不铸 `Model.input`(没有 true 缺省);引擎与带图预检都按「收」读(图原样交给模型,不出信号);`GET /v1/models` 该行不带 `vision` 键。要让预检对纯文本模型出信号写 MODEL_VISION=false",
+    r("MODEL_VISION", "modelPlane", "boolean", "主模型 vision 声明(三态:true / false / 缺席 = 未声明;false = 明说不收图:带图请求的图被换成占位句交给模型,引擎在替换的那一刻于会话流发 `model.capability_downgraded`,每会话每模型一次)", {
+        derivedDefaultNote: "缺席 ⇒ 不铸 `Model.input`(没有 true 缺省);引擎按「收」读(图原样交给模型,不发 `model.capability_downgraded`);`GET /v1/models` 该行不带 `vision` 键。要让引擎对纯文本模型发该信号写 MODEL_VISION=false",
         resolve: (c) => {
             const v = modelImageInput(c.model);
             return v === "undeclared" ? null : v === "yes";
         },
         center: cModels("models[].vision"),
     }),
+    r("MODS_PACKAGES", "integrations", "opaque", "部署座装载的 mod 包声明(JSON 数组,每项闭集 { name, dir, tier, options? }:name = 包自己的名、逐字同;dir 绝对路径、真实路径须在 MODS_ROOT 之下且是目录;tier ∈ prepend / user / append 宿主必填;options 原样交包的 register)。读包只有引擎的读包者,本服务不读包内文件;形错 / 越根 / 读包者拒 / 名不同 / 引擎准入拒 ⇒ 拒启,一行拒句点名哪一席或哪只包(本服务写的句子不回显声明的值;读包者 / 准入交回的话原样透传、凭据形换记号,可能点名包目录);起服装配一次,改声明或换包要重启;本目录只回在场位与长度(不回显声明);options 不是凭据通道(本服务不替包扣凭据:宿主车道 inheritEnv \"all\" 下子进程照样继承这根旋钮与包自己读的变量)", { danger: SEC, derivedDefaultNote: "缺席 / 空串 = 不声明 ⇒ 部署座只有本服务自铸的注册,/health 与 /v1/capabilities 逐字节同没有这根旋钮的版本" }),
+    r("MODS_ROOT", "integrations", "path", "声明的 mod 包允许所在的根(绝对路径;包的真实路径按路径分量严格落在它的真实路径之下 —— 符号链接出根、前缀相似目录、.. 遍历、根本身都拒启;建议只读物料树)。声明了包而没设它 ⇒ 拒启;单设它而不声明包 = 无事(形照判)", { danger: SEC, configKey: "modsDeclaration", derivedDefaultNote: "缺席 ⇒ 不许声明任何包", resolve: (c) => c.modsDeclaration.root ?? null }),
     r("MYSQL_DATABASE", "store", "string", "MySQL 协议库名(选中该引擎时必填)", { danger: DATA }),
     r("MYSQL_HOST", "store", "string", "MySQL 协议主机(在场即算 SQL 信号,参与 DB_BACKEND 默认推导)", { danger: DATA }),
     r("MYSQL_PASSWORD", "store", "secret", "MySQL 协议口令", { danger: SEC }),

package/dist/config-types.d.ts

@@ -23,6 +23,7 @@ import type { CustomPkgSource } from "./sandbox-pkg-source.js";
 import type { MemoryEngineBackend, StoreBackend as StoreBackendWord } from "@sema-agent/settings-schema/execution-lanes";
 import { DRAIN_GRACE_FLOOR_MS } from "@sema-agent/settings-schema/fleet";
 import type { AtMention } from "@sema-agent/settings-schema";
+import type { ModsDeclaration } from "./mods-declaration.js";
 /** [ref]:记忆向量面的 embedder 坐标(env `MEMORY_EMBEDDER_*` 解析结果;单一属主 = 本类型,
  *  `plugins/memory-embedder.ts` 的工厂直接消费它,不复制形状)。语义与三问见
  *  {@link ServiceConfigFlat.memoryEmbedder}。纯数据 —— 端点原文照存(拼 `/embeddings` 是 transport
@@ -130,7 +131,7 @@ export declare const DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS = 250;
  * 住在本叶(而不在 `fleet/drain-entry.ts`):`config.ts` 读它,而 drain-entry 值引 `plugins/store-contracts.ts`,config 不值引 plugins 层。
  */
 export declare function fleetScopeOf(raw: string | undefined): string;
-/** 中心基址三席(`SEMA_WEB_ADMIN_URL` / `SEMA_WEB_ADMIN_LIVE_URL` / `SEMA_WEB_ADMIN_WEB_URL`)与公告地址的形句 —— 判官 `web-admin-client/center-request.ts` `pathBaseUrlRefusal` 一只(形判 = settings-schema `httpUrlFlaws`),配置目录四行同读这一句。 */
+/** 中心基址三席(`SEMA_WEB_ADMIN_URL` / `SEMA_WEB_ADMIN_LIVE_URL` / `SEMA_WEB_ADMIN_WEB_URL`)与公告地址的形句 —— 判官 `web-admin-client/center-request.ts` `pathBaseUrlRefusal` 一只(形判 = settings-schema `pathBaseUrlFlaws`,14.7.0 起),配置目录四行同读这一句。 */
 export declare const CENTER_BASE_URL_RULE = "\u8BBE\u4E86\u5C31\u5FC5\u987B\u662F\u53EF\u89E3\u6790\u7684 http(s) URL,\u4E14\u4E0D\u5E26\u51ED\u636E / query / fragment(\u57FA\u5740\u540E\u9762\u8981\u62FC\u8DEF\u5F84);\u574F\u5F62\u62D2\u542F(\u6CA1\u63A5\u4E2D\u5FC3\u4E5F\u62D2),\u62D2\u53E5\u53EA\u70B9\u540D\u89C4\u5219,\u4E0D\u56DE\u663E scheme";
 /** 编排器片 2:`FLEET_LEASE_OUTAGE_MAX_MS` 的缺省(24 h)—— 中心 / 库故障、中心降级在今天都靠 LKG 无限期容忍,10 分钟级的窗会把它们变成数据面停服。 */
 export declare const FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS = 86400000;
@@ -266,7 +267,7 @@ export interface MemoryConsolidationDriverConfig {
      *  ①恰好一条时 = 两个 admin 口省略 `scope` 的**唯一**缺省(两条及以上恒不猜——在两个库之间猜一个
      *  去花钱是本设计要消灭的形);②周期腿落地时的 scope 源(设计稿 D2)。
      *  🔴 **不是授权边界**:本仓今天没有任何授权源能对一个 operator 收窄 scope(理由与亲读依据逐字见
-     *  `src/memory-operator-faces.ts` 的 `erasureEnvelopeRefusal` 头注),在本层拿它当白名单就是**发明
+     *  `src/memory-operator-faces.ts` `MemoryComplianceFaces.erase` 的「授权座只有一只」段),在本层拿它当白名单就是**发明
      *  第二套授权语义**。显式传的 scope 照跑,表只管缺省。 */
     scopes: readonly string[];
     /**
@@ -297,7 +298,8 @@ export interface MemoryConsolidationDriverConfig {
      */
     autoRunOnRecommendation?: boolean;
 }
-/** A web-admin MCP server resolved to a core spec (env-NAME refs already → real values) plus the
+/** A web-admin MCP server resolved to a core spec (env-NAME refs already read and registered on the peer desk under the
+ *  roster lease: the spec carries the minted reference, never the values) plus the
  *  scenarios it applies to (empty = all). `resolveSpec` filters by scenario and passes `spec` to core. */
 export interface ScopedMcpServer {
     scenarios: string[];
@@ -312,7 +314,8 @@ export interface CenterMcp {
     servers: ScopedMcpServer[];
     reservedNames: readonly string[];
 }
-/** DESIGN-269 §2.1 —— an A2A PEER resolved to a core spec (header-NAME refs already → real values) plus
+/** DESIGN-269 §2.1 —— an A2A PEER resolved to a core spec (header-NAME refs already read and registered on the peer desk
+ *  under the roster lease: the spec carries the minted reference, never the values) plus
  *  the scenarios it applies to (empty = all). Exact sibling of {@link ScopedMcpServer}: `resolveSpec`
  *  filters by scenario (`a2aForScenario`) and passes `spec` to core as `TaskSpec.a2a`.
  *
@@ -510,8 +513,10 @@ export interface ServiceConfigFlat {
     gatewayFallbackUrls: string[];
     /** `GATEWAY_MAX_RETRIES` —— openai 兼容腿的**每次调用**重试上限。
      *
-     *  🔴 **缺席 = 不传给引擎**(不是"传个默认值"):此前这里是硬编码 `maxRetries: 2`,而显式传参**压过**
-     *  引擎默认 ⇒ core 抬默认对 server 部署一点效果都没有。缺席不传之后,引擎默认当家、core 抬默认自动继承。
+     *  🔴 **配置层缺席 = 本字段 `undefined`**(不是"传个默认值"):此前这里是硬编码 `maxRetries: 2`,而显式传参**压过**
+     *  引擎默认 ⇒ core 抬默认对 server 部署一点效果都没有。缺席之后由 `brain.ts` 按**外层拓扑**分两态(启动日志 `gatewayRetryCap` 回显):
+     *  外层有快切层(备用网关 / 断路器开关 / 反应式降级 —— 后者须配着 `MODEL_DEGRADE_TO`)⇒ 网关各路传 `FAST_FAIL_MAX_RETRIES`(2)并遮蔽引擎的 `SEMA_MAX_RETRIES`;
+     *  没有快切层 ⇒ 不传,引擎默认当家、core 抬默认自动继承。降级兜底腿不吃这条收窄(只吃显式值)。设了恒赢(原样传、同样遮蔽 `SEMA_MAX_RETRIES`)。
      *  (五报清查 R1① 的 server 半场,黑板 [ref]/[ref];anthropic 腿早有 `ANTHROPIC_MAX_RETRIES` 出口,
      *  这条只是把同样的出口补给限流 provider 真正走的那条腿。) */
     gatewayMaxRetries?: number;
@@ -944,6 +949,10 @@ export interface ServiceConfigFlat {
         /** `K8S_SANDBOX_IPV6`(闭集与缺省的属主 `sandbox-egress-policy.ts`):`disabled` ⇒ 沙箱 pod 级 sysctl 关 IPv6;`enabled` ⇒ pod spec 不带 sysctl。
          *  loader 恒铸;可选只为手搓配置。 */
         sandboxIpv6?: import("./sandbox-egress-policy.js").SandboxIpv6;
+        /** `K8S_SANDBOX_BROKER_IMAGE` — the member git-credential broker container's image (`containers[1]` of a member's sandbox pod; this
+         *  engine's own image is the recommended value — the broker is a program of this package at a fixed path, `broker/constants.ts`). Absent /
+         *  empty ⇒ the plane is off (`credentialPlane.sandboxGit` = `broker_image_unset`) and no pod carries a broker. */
+        brokerImage?: string;
         /** `K8S_SANDBOX_ENV=NAME,NAME` 点到、且本进程环境里真有的键 ⇒ 原值(与 e2b 的 `sandboxEnv` 同名同形、同一只解析器、同一只谓词 `allowlistedEnv`,
          *  空串值照带)。只进 pod 容器 env;装配点与包源派生 env 合并一处,显式名单胜。键缺席 = 旋钮未设 / 空串(零转发)。 */
         sandboxEnv?: Record<string, string>;
@@ -1014,6 +1023,11 @@ export interface ServiceConfigFlat {
          *  域 = `[1, 86400]` 的十进制正整数,坏值**拒启**([ref] A 档;解析器 `parseDeviceEnrollTokenTtlEnv`)。
          *  缺席 ⇒ 签发点的属主默认 900(不在 config 层抄第二份默认,与本族其余旋钮同姿势)。 */
         enrollTokenTtlSec?: number;
+        /** `DEVICE_RELAY_URL` = 设备的**直达入口**:设备连不到本引擎自己的地址(引擎在中继 / 网关之后)时该拨的那一个 ws(s) URL,运维声明、**逐字**上能力面
+         *  `deviceExecutor.relayUrl`(唯一消费点 `http/routes/capabilities.ts`)。缺席 ⇒ 键缺席 = 设备按本引擎地址 + `deviceExecutor.wsPath` 拨号(既有形)。
+         *  **不派生**:`FLEET_ADVERTISE_ADDRESS` 是对中心公告的地址(内网 pod IP / 容器别名),受众不是用户机器上的设备;从它拼出来的入口对设备多半不可达。
+         *  形门 = ws / wss 绝对地址,无 userinfo / query / fragment、不带凭据形(值逐字上能力面),坏值**拒启**(解析器 `parseDeviceRelayUrlEnv`)。 */
+        relayUrl?: string;
         /** `DEVICE_SUPERSEDE`(默认 `stale_only`)= 同 deviceId 二连的顶替策略(§5.2)。 */
         supersede?: "stale_only" | "deny";
     } | {
@@ -2196,6 +2210,9 @@ export interface ServiceConfigFlat {
     defaultScenario: string;
     /** Directory of baked-in skill Markdown files, loaded once at startup. */
     skillsDir: string;
+    /** 运维声明的 mod 包(`MODS_ROOT` + `MODS_PACKAGES`;`loadConfig` 读一次,唯一读法 `mods-declaration.ts` 的 `parseModsDeclaration`)。两只起服入口的部署座装配
+     *  (`boot/deployment-mods.ts` 的 `assembleDeploymentMods`)都读这一份;没声明 = 没有 `packages` 这一席(`{}` / 单设根时 `{ root }`;部署座只有本仓自铸的注册)。起服装配一次,配置刷新不重载。 */
+    modsDeclaration: ModsDeclaration;
     /** Central web-admin (web-admin). When set, the service pulls the effective config
      *  on boot (and refreshes) and applies it OVER the env defaults — env is the fallback. Logical config
      *  only (model roster/roles/teams); secrets/gateways stay in this service's env.
@@ -2285,7 +2302,7 @@ export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachme
 /** 组:observability(可观测)。 */
 export type ServiceObservabilityConfig = Pick<ServiceConfigFlat, "metricsToken" | "traceToken" | "toolTrace" | "traceThinking" | "logLevel" | "otel">;
 /** 组:integrations(外部集成)。`mcpServers` / `a2aPeers` 由 web-admin 适配器填(无 env 腿),归本组。 */
-export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "a2aPeers" | "a2aServe" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "centerCredentialRenewLeadMs" | "webAdmin" | "fleetLeaseFailClosed" | "fleetGeneration" | "fleetScope" | "fleetAdvertiseAddress" | "fleetLeaseOutageMaxMs" | "configProvider" | "configLocalDir" | "configLocalOwnerUid">;
+export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "a2aPeers" | "a2aServe" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "modsDeclaration" | "centerCredentialRenewLeadMs" | "webAdmin" | "fleetLeaseFailClosed" | "fleetGeneration" | "fleetScope" | "fleetAdvertiseAddress" | "fleetLeaseOutageMaxMs" | "configProvider" | "configLocalDir" | "configLocalOwnerUid">;
 /** 九个组槽。每组恒在场(`loadConfig` / `attachConfigGroups` 装好才交出配置),故不可选——新代码写
  *  `config.modelPlane.model` 不需要 `?.`(可选组会把 `Model` 污染成 `Model | undefined`)。 */
 export interface ServiceConfigGroups {

package/dist/config.d.ts

@@ -274,7 +274,7 @@ export declare function isRosterGateArmed(webAdmin: ServiceConfig["webAdmin"]):
  * core 的每一只 name-keyed policy(`createAllowDenyPolicy` / `createPermissionRulePolicy` /
  * `createApprovalPolicy`)都解 covering 拼法,而 operator 腿的消费者 `createDurableAskPolicy`
  * (`src/approval.ts`)自 core 5.60.1 的谓词根导出到货后,deny/neverAuto/require 三集合也改成
- * 「精确 ∪ covering」(同一只 `namespacedRuleNameCovers`)。于是本函数放行的
+ * 「精确 ∪ covering」(同一只 `ruleNameCovers`)。于是本函数放行的
  * `<ns>__<server>__*` / `<ns>__<server>__<glob>` 在**每一条**腿上都是**真判**,不再是
  * 「放行进 no-op」—— 而那正是 [ref] 病形(`APPROVAL_DENY=mcp__figma__*` 判 allow)的根。
  *

package/dist/config.js

@@ -3,7 +3,7 @@ import { DEFAULT_AT_MENTION, DEFAULT_MODEL_REF, mintCapabilityKeys } from "./mod
 import { homedir } from "node:os";
 import { isAbsolute, join, posix as posixPath } from "node:path";
 import { fileURLToPath } from "node:url";
-import { compileAllowList, inheritEnvPolicyProblem, BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES, compileReadDeny, resolveReadDenyBuiltins, CODE_AGENT_PROMPT, isModelPriced, PROTOCOL_TABLE, RECOMMENDED_SENSITIVE_PATTERNS, judgeRuleToolName, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules, WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, principalInboxConsumerOf } from "@sema-agent/core";
+import { compileAllowList, inheritEnvPolicyProblem, BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES, compileReadDeny, resolveReadDenyBuiltins, isModelPriced, PROTOCOL_TABLE, RECOMMENDED_SENSITIVE_PATTERNS, judgeRuleToolName, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules, WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, principalInboxConsumerOf } from "@sema-agent/core";
 import { ROSTER_PRIMARY_ROLES, ROSTER_CHEAP_ROLES, WEB_ADMIN_ENV, retiredEnvRefusal, stripControlAndBidi } from "@sema-agent/settings-schema";
 import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
@@ -15,7 +15,7 @@ import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
 import { CONFIG_PROVIDER_WORDS, RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS, MAX_TIMER_DELAY_MS, AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, DRAIN_GRACE_FLOOR_MS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, FIRST_BYTE_TIMEOUT_BOUNDS, FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS, fleetScopeOf, DEVICE_DELIVERY_TIMEOUT_BOUNDS, DEVICE_EXEC_TIMEOUT_BOUNDS, inWholeNumberBounds, wholeNumberBoundsRule } from "./config-types.js";
 import { DEVICE_HELLO_ACK_BOUNDS } from "./device-ws-protocol.js";
-import { FLEET_GENERATION_ENV, FLEET_SCOPE_ENV, SERVING_LEASE_TTL_FLOOR_MS, isCanonicalGeneration } from "@sema-agent/settings-schema/fleet";
+import { FLEET_ADVERTISE_ADDRESS_ENV, FLEET_GENERATION_ENV, FLEET_SCOPE_ENV, SERVING_LEASE_TTL_FLOOR_MS, isCanonicalGeneration } from "@sema-agent/settings-schema/fleet";
 import { ScopeId } from "@sema-agent/settings-schema/api/scopes";
 import { centerLaneConfigured, pathBaseUrlRefusal } from "./web-admin-client/center-request.js";
 import { resolveLocalDataRoot } from "./local-data-root.js";
@@ -45,9 +45,9 @@ import { parseCenterCredentialRenewLeadMs } from "./center-credential-renewer.js
 import { modelProviderRefusal } from "./model-provider.js";
 import { modelRouteUrlRefusal } from "./model-route-url.js";
 import { httpUrlFlaws } from "@sema-agent/settings-schema";
-import { buildHttpUrlRefusal } from "./url-refusal.js";
+import { buildHttpUrlRefusal, buildRefusalShownUrl } from "./url-refusal.js";
 import { customPkgSourceFromEnv } from "./sandbox-pkg-source.js";
-import { anthropicCredentialRefusal, csvOf, envLaneTable, mintedCheapId, readModelRouteEnv } from "./model-route-gap.js";
+import { anthropicCredentialRefusal, csvOf, declaredCredential, envLaneTable, mintedCheapId, readModelRouteEnv } from "./model-route-gap.js";
 import { displayListEntry } from "./list-entry-display.js";
 import { echoCallerText } from "./caller-text-echo.js";
 import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
@@ -55,6 +55,7 @@ import { parseConfigLocalOwnerUid } from "./config-dir-trust.js";
 import { allowlistedEnv } from "./server-secret-env.js";
 import { ENV_NAME_ALLOWLIST_KNOBS, ENV_NAME_ALLOWLIST_KNOB_NAMES, describeAllowlistPostures } from "./env-name-allowlist-knobs.js";
 import { APPROVAL_ASK_RETENTION_DEFAULT_MS, APPROVAL_ASK_RETENTION_FLOOR_MS } from "./approval-ask-retention.js";
+import { parseModsDeclaration } from "./mods-declaration.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
     return csvOf(process.env[name]);
@@ -372,6 +373,30 @@ function parseDeviceEnrollTokenTtlEnv() {
     }
     return Number(raw);
 }
+function credentialLawRewriteOf(href) {
+    const scanned = redactSecrets(href);
+    return scanned === href ? undefined : scanned;
+}
+function parseDeviceRelayUrlEnv() {
+    const raw = process.env.DEVICE_RELAY_URL;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const scheme = /^wss?:\/\//i.exec(raw)?.[0];
+    const asHttp = scheme === undefined ? undefined : `${scheme.length === "wss://".length ? "https" : "http"}://${raw.slice(scheme.length)}`;
+    const flaws = asHttp === undefined ? ["not-ws-url"] : httpUrlFlaws(asHttp, ["userinfo", "query", "fragment"]).map((f) => (f === "not-http-url" ? "not-ws-url" : f));
+    if (flaws.length > 0) {
+        throw new Error(`env DEVICE_RELAY_URL must be an absolute ws:// or wss:// URL with no userinfo, query or fragment (ws(s)://host[:port][/path]) — found: ${flaws.join(", ")}; got ${JSON.stringify(buildRefusalShownUrl(raw))}. ` +
+            `It is published verbatim on GET /v1/capabilities (deviceExecutor.relayUrl) as the address devices dial, so it has no room for credentials (devices authenticate by signature). ` +
+            `Leave it unset when devices reach this engine at its own address — they then dial it at deviceExecutor.wsPath.`);
+    }
+    const href = new URL(raw).href;
+    const credentialScan = credentialLawRewriteOf(href);
+    if (credentialScan !== undefined) {
+        throw new Error(`env DEVICE_RELAY_URL carries something the credential-redaction law recognizes (${credentialScan}) — it is published verbatim on GET /v1/capabilities (deviceExecutor.relayUrl), ` +
+            `so it must not carry a token-shaped path segment; keep it to ws(s)://host[:port][/path] (devices authenticate by signature, not by the URL).`);
+    }
+    return raw;
+}
 function parseDevicePreAuthPerRemoteEnv() {
     const raw = process.env.DEVICE_MAX_PREAUTH_PER_REMOTE;
     if (raw === undefined || raw === "")
@@ -1079,7 +1104,7 @@ function parseModelDomain() {
     }
     const models = envLaneTable(modelId, model, cheapModel);
     const gatewayApiKey = route.gatewayApiKey;
-    if (gatewayBaseUrl === undefined && gatewayApiKey !== undefined && gatewayApiKey !== "") {
+    if (gatewayBaseUrl === undefined && declaredCredential(gatewayApiKey) !== undefined) {
         CONFIG_NOTICES.push({
             level: "warn",
             event: "model_gateway_key_unpaired",
@@ -1090,7 +1115,7 @@ function parseModelDomain() {
     }
     const cheapRef = cheapModel ? cheapModel.id : DEFAULT_MODEL_REF;
     const verifierEnv = process.env.MODEL_VERIFIER;
-    const verifierRef = verifierEnv && models[verifierEnv] ? verifierEnv : DEFAULT_MODEL_REF;
+    const verifierRef = verifierEnv && Object.hasOwn(models, verifierEnv) ? verifierEnv : DEFAULT_MODEL_REF;
     const roles = {
         verifier: verifierRef,
     };
@@ -1105,8 +1130,8 @@ function parseModelDomain() {
             continue;
         roles[role] =
             typeof cur === "string"
-                ? { model: cur, systemPrompt: CODE_AGENT_PROMPT }
-                : { ...cur, systemPrompt: CODE_AGENT_PROMPT };
+                ? { model: cur, promptRole: "code" }
+                : { ...cur, promptRole: "code" };
     }
     const degradeOn = parseDegradeOn(csv("MODEL_DEGRADE_ON"));
     return {
@@ -1942,6 +1967,7 @@ function parseOrchestrationDomain(ctx) {
                         ...(process.env.K8S_MEMORY ? { memory: process.env.K8S_MEMORY } : {}),
                         ...(process.env.K8S_CPU ? { cpu: process.env.K8S_CPU } : {}),
                         sandboxIpv6: enumEnv("K8S_SANDBOX_IPV6", SANDBOX_IPV6_DEFAULT, SANDBOX_IPV6_WORDS),
+                        ...(process.env.K8S_SANDBOX_BROKER_IMAGE ? { brokerImage: process.env.K8S_SANDBOX_BROKER_IMAGE } : {}),
                         ...((names) => (names !== undefined ? { sandboxEnv: allowlistedEnv(names, process.env) } : {}))(parseEnvNameAllowlist("K8S_SANDBOX_ENV", singleUserTurnkey)),
                         ...k8sWorkspaceStore(),
                         ...((c) => (c !== undefined ? { workspaceCache: c } : {}))(k8sWorkspaceCache()),
@@ -2000,6 +2026,7 @@ function parseOrchestrationDomain(ctx) {
                                                                 ...((n) => (n !== undefined ? { maxInflightPerDevice: n } : {}))(parseDeviceBoundedIntEnv("DEVICE_MAX_INFLIGHT_PER_DEVICE", process.env.DEVICE_MAX_INFLIGHT_PER_DEVICE, DEVICE_HELLO_ACK_BOUNDS.maxInflight)),
                                                                 ...((n) => (n !== undefined ? { maxPreAuthPerRemote: n } : {}))(parseDevicePreAuthPerRemoteEnv()),
                                                                 ...((n) => (n !== undefined ? { enrollTokenTtlSec: n } : {}))(parseDeviceEnrollTokenTtlEnv()),
+                                                                ...((n) => (n !== undefined ? { relayUrl: n } : {}))(parseDeviceRelayUrlEnv()),
                                                                 ...(process.env.DEVICE_SUPERSEDE ? { supersede: enumEnv("DEVICE_SUPERSEDE", "stale_only", ["stale_only", "deny"]) } : {}),
                                                             }
                                                             :
@@ -2202,6 +2229,7 @@ function parseIntegrationsDomain(ctx) {
         gitApiKind: parseGitApiKind(process.env.GIT_API_KIND, process.env.GIT_API_BASEURL),
         defaultScenario: env("DEFAULT_SCENARIO", "code"),
         skillsDir: env("SKILLS_DIR", defaultSkillsDir()),
+        modsDeclaration: parseModsDeclaration(process.env.MODS_ROOT, process.env.MODS_PACKAGES),
         centerCredentialRenewLeadMs: parseCenterCredentialRenewLeadMs(process.env.CENTER_CREDENTIAL_RENEW_LEAD_MS),
         webAdmin,
         fleetLeaseFailClosed: parseFleetLeaseFailClosed(process.env.FLEET_LEASE_FAIL_CLOSED, DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds({ requirePrincipal })),
@@ -2241,15 +2269,16 @@ function parseFleetScope(raw) {
     if (raw !== undefined && !ScopeId.safeParse(raw).success) {
         const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
         throw fleetEnvRefusal("scope_invalid", `env ${name}=${JSON.stringify(shown)} is not a scope id: it must be a lowercase slug of letters, digits and inner dashes, 1–64 characters, ` +
-            `not empty. The config renderer sets it on engines that serve a tenant scope; unset it for the default scope ("${fleetScopeOf(undefined)}"). ` +
+            `not empty. The config renderer sets it on every engine it manages (the default scope included); on a hand-wired engine leave it unset for the default scope ("${fleetScopeOf(undefined)}"). ` +
             `Refusing to boot rather than answering drain requests under the wrong identity.`);
     }
     return fleetScopeOf(raw);
 }
 function parseFleetAdvertiseAddress(raw) {
+    const name = "FLEET_ADVERTISE_ADDRESS";
     if (raw === undefined || raw === "")
         return {};
-    const refusal = pathBaseUrlRefusal("env FLEET_ADVERTISE_ADDRESS", raw);
+    const refusal = pathBaseUrlRefusal(`env ${name}`, raw);
     if (refusal !== undefined) {
         throw fleetEnvRefusal("advertise_address_invalid", `${refusal} — it must be an http(s) base URL such as "http://10.0.0.5:8090": the fleet center rejects any other shape on every announce. ` +
             `Unset it if this engine does not announce itself.`);
@@ -2330,8 +2359,8 @@ function parseA2aServe() {
             `inbound authentication on this endpoint is header-shaped (a service credential), not URL-embedded.`);
     }
     const parsed = new URL(rawUrl);
-    const a2aCredentialScan = redactSecrets(parsed.href);
-    if (a2aCredentialScan !== parsed.href) {
+    const a2aCredentialScan = credentialLawRewriteOf(parsed.href);
+    if (a2aCredentialScan !== undefined) {
         throw new Error(`A2A_SERVE_URL carries something the credential-redaction law recognizes (${a2aCredentialScan}) — this address is published VERBATIM on the ANONYMOUSLY readable agent card (the card's url is a functional address: peers fetch it, so it is never rewritten for display), ` +
             `so it must not carry credentials of ANY shape: no userinfo, no credential-named query parameter (api_key/token/…), no token-shaped path segment or parameter value. ` +
             `Keep A2A_SERVE_URL to scheme://host[:port][/path] and move the secret into the caller's headers.`);
@@ -2434,7 +2463,7 @@ const LIMITS_HTTP_GROUP_KEYS = [
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
 const INTEGRATIONS_GROUP_KEYS = [
     "pluginsAllowHosts", "mcpServers", "a2aPeers", "a2aServe", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "gitApiKind", "defaultScenario",
-    "skillsDir", "centerCredentialRenewLeadMs", "webAdmin", "fleetLeaseFailClosed", "fleetGeneration", "fleetScope", "fleetAdvertiseAddress", "fleetLeaseOutageMaxMs", "configProvider", "configLocalDir", "configLocalOwnerUid",
+    "skillsDir", "modsDeclaration", "centerCredentialRenewLeadMs", "webAdmin", "fleetLeaseFailClosed", "fleetGeneration", "fleetScope", "fleetAdvertiseAddress", "fleetLeaseOutageMaxMs", "configProvider", "configLocalDir", "configLocalOwnerUid",
 ];
 export const CONFIG_GROUP_KEYS = {
     store: STORE_GROUP_KEYS,

package/dist/deployment-governance.d.ts

@@ -103,8 +103,8 @@ export interface AbsentApprovalSeat {
  * durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留([ref] 后无活流腿放行执行
  * 也不会产出空答:coordinator 无 ALS ctx ⇒ 冻结 `{kind:"unavailable"}`(src/question.ts),永不悬挂;
  * park 仍是把问题送到人面前的唯一那条腿,正当性不变、只是反事实前提换了)。
- * 工具名取 `approval-content-kind.ts` 的单一属主(它 re-export core 根导出的 `ASK_USER_QUESTION_TOOL_NAME`);
- * server.ts 的 pre-CAS 守卫读同一枚([ref]①:此处旧注称该常量「core 未根导出」= 失实,曾据此手抄 13 处)。
+ * 「是不是引擎的问题工具」不在本层判:core 7.56.0 [ref] 起本门**组合** core 原形的答(它读调用的脸 —— 引擎挂载点 + 目录契约 id,不读名字;
+ * 它答 `ask` ⇒ 是;本层只在那之上按活流分腿)。决断口的 pre-CAS 守卫(「批准问答必须带答」)仍按保留名读(core 同版「Not changed here」那一条)。
  * ⚠️ **单一属主**(复审 A2):AskUserQuestion 的 durable 判决只有这一处。任何需要「同参重建」这条判决的
  * 地方(main.ts 的 parkedReviveInheritedGate 父约束链)必须调本工厂,不得自折 core 原形——两份拷贝里
  * 只改一份正是本条 finding 的成因。**登记豁免一处**:leader worker 腿(src/leader/wire.ts provisionWorker)

package/dist/deployment-governance.js

@@ -1,18 +1,16 @@
 import { join, posix } from "node:path";
 import { FileError, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, createTranscriptIntegrityPolicy, err, isAbsoluteForFamily, isProtectedWrite, ok, pathTargetValue, protectivePathTargetOf, } from "@sema-agent/core";
 import { createDurableAskPolicy, hasApprovalListIntent } from "./approval.js";
-import { ASK_USER_QUESTION_TOOL_NAME } from "./approval-content-kind.js";
-import { heldRuleName } from "./tool-rule-names.js";
 export function createDurableQuestionGate(live) {
+    const durable = createDurableQuestionPolicy();
     if (live === undefined)
-        return createDurableQuestionPolicy();
+        return durable;
     return {
-        check(req) {
-            if (heldRuleName(req, (n) => n === ASK_USER_QUESTION_TOOL_NAME) === undefined)
-                return { action: "allow" };
-            return live.hasLiveContext()
-                ? { action: "allow" }
-                : { action: "ask", message: "AskUserQuestion: awaiting a human answer (durable)" };
+        async check(req) {
+            const answer = await durable.check(req);
+            if (answer.action !== "ask")
+                return answer;
+            return live.hasLiveContext() ? { action: "allow" } : answer;
         },
     };
 }

package/dist/deployment-shape.d.ts

@@ -93,23 +93,23 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      */
     multiTenant: DeploymentShapePredicate<"principal">;
     /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由 `device_session` 绑定验过,不要求单主)。 */
-    callerCwd: DeploymentShapePredicate<"principal" | "lane">;
+    callerCwd: DeploymentShapePredicate<"lane" | "principal">;
     /** 调用方给的宿主绝对路径(附加目录 / 项目上下文 / 本机 SendUserFile / 指令文件探针)只在「手就在本 worker 的盘上 ∧ 单主」时指向调用方自己的东西。 */
-    callerOwnsWorkerDisk: DeploymentShapePredicate<"principal" | "lane">;
+    callerOwnsWorkerDisk: DeploymentShapePredicate<"lane" | "principal">;
     /** wire `executionLane.toolsOnThisHost` 与出厂 / 中心技能的 `baseDir`:只问文件系统同一性,与租户无关(出厂内容每个租户拿到同一份)。 */
     toolsOnThisHost: DeploymentShapePredicate<"lane">;
     /** `REMOTE_EXEC` 未设的进程内形(没有手)且单主:进程级消费者(hooks 命令、项目上下文本机读、卡批规则 root)看到的就是引擎自己的进程 cwd / env。 */
-    inProcessSingleUser: DeploymentShapePredicate<"principal" | "lane">;
+    inProcessSingleUser: DeploymentShapePredicate<"lane" | "principal">;
     /** 任务层替部署声明宿主姿态(bypassPermissions 开写面 / host shell 继承整份环境)的射程:device 车道上跨租户宿主穿越结构性不存在(clay 裁定③)。 */
-    taskHostPostureDeclarations: DeploymentShapePredicate<"principal" | "lane">;
+    taskHostPostureDeclarations: DeploymentShapePredicate<"lane" | "principal">;
     /** 写门走 [ref] 代理裁决(文件平面不在 worker 本机);认不出的词 ⇒ 走代理(代理 slot 空 ⇒ 写门 fail-closed)。 */
     sandboxPathAdjudication: DeploymentShapePredicate<"lane">;
     /** 读能力表 `sandboxSendUserFile` 位(e2b / k8s 每任务一只沙箱 ⇒ 任何租户;ssh 共享一台真机 ⇒ 只单主)。 */
-    sandboxSendUserFile: DeploymentShapePredicate<"principal" | "lane">;
+    sandboxSendUserFile: DeploymentShapePredicate<"lane" | "principal">;
     /** 读能力表 `remoteScratchpad` 位(`/tmp/scratchpad/<sessionId>` 远端约定)。 */
     remoteScratchpad: DeploymentShapePredicate<"lane">;
     /** 读能力表 `tenantSeparation` 位(值来自 settings-schema 车道词表正本);唯一读者 = 跨域不变量 `multi-tenant-shared-lane`。 */
-    laneSeparatesTenants: DeploymentShapePredicate<"principal" | "lane">;
+    laneSeparatesTenants: DeploymentShapePredicate<"lane" | "principal">;
     /**
      * [ref] —— **VM 级**隔离强度(独立内核:e2b 的 Firecracker microVM;k8s 只在 Kata / gVisor 运行时类上)。与能力表 `isolation` 位
      * (OS 级边界,容器即算;wire `executionLane.isolated` 的属主 `laneIsolated`)是两个问题,所以不叫「isolated」。读者:A 值路由。

package/dist/device-ws-protocol.d.ts

@@ -74,6 +74,7 @@ export declare function asInstructionKind(v: string): DeviceInstructionKind | nu
 export declare const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION: {
     readonly 1: readonly ["aborted", "already_exists", "auth_failed", "callback_error", "invalid", "is_directory", "not_directory", "not_found", "not_supported", "outcome_unknown", "permission_denied", "precondition_failed", "shell_unavailable", "spawn_error", "suspended", "target_unavailable", "timeout", "transport_lost", "unknown"];
     readonly 2: readonly ["liveness_no_output"];
+    readonly 3: readonly ["name_too_long"];
 };
 /** 本包认得的协议修订号(= 增量表的行键)。 */
 export type DeviceProtocolRevision = keyof typeof DEVICE_OUTCOME_ERROR_CODES_BY_REVISION;

package/dist/device-ws-protocol.js

@@ -1,7 +1,7 @@
 import { createPublicKey, randomBytes, randomInt, verify as edVerify } from "node:crypto";
 import { MAX_TIMER_DELAY_MS, inWholeNumberBounds, wholeNumberBoundsRule } from "./config-types.js";
 export const DEVICE_WS_PATH = "/v1/device/ws";
-export const DEVICE_PROTOCOL_VERSION = 2;
+export const DEVICE_PROTOCOL_VERSION = 3;
 export const DEVICE_MIN_PROTOCOL_VERSION = 1;
 export const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
 export const DEVICE_WS_LIMITS = {
@@ -66,6 +66,7 @@ export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
         "unknown",
     ],
     2: ["liveness_no_output"],
+    3: ["name_too_long"],
 };
 export function deviceOutcomeErrorCodesAt(revision) {
     if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {

package/dist/file-history-disclosure.d.ts

@@ -25,7 +25,8 @@
  * · **判断面**(同一只函数的 `fault`,core 7.55.0 `FileHistoryError.permanence`):永久码表里的 typed 码 ⇒
  *   `{ permanence: "terminal" }`;**连接类故障**(到库的连接坏了 / 库此刻不接 —— 判官是整仓唯一一只
  *   `plugins/store-fault.ts` 的 `storeFaultClassOf`,识别表在 `plugins/sql-errors.ts`,本文件不再抄第二份)⇒
- *   `{ permanence: "transient" }`;其余 ⇒ `{}`(没判 —— 引擎照旧给重试引导语)。`terminal` 只对永久码。
+ *   `{ permanence: "transient" }`;**部署错配类**(缺表 / 权限拒:连接是好的、重试注定失败,修表 / 授权之前什么都不会变 —— 同一只判官的 `deployment` 一词,表在 `plugins/sql-errors.ts`)⇒
+ *   `{ permanence: "terminal" }`;其余 ⇒ `{}`(没判 —— 引擎照旧给重试引导语)。`terminal` 只对永久码与部署错配类。
  *   折点把它摊进店答的 `FileHistoryError`;引擎的拒句引导语、rewind 披露、`terminal.detail` 都读这一格,**不读散文**。
  * · **机器面**(同一只函数的副作用):码取自 typed 错**对象**、对闭集词表判定,**绝不从散文里抠**。
  *   🔴 这一条是 codex R1-[high] 验真后的定形:文本通道**天然可伪造** —— 一个名叫
@@ -54,7 +55,8 @@ export interface CaughtFailure {
  * `text` = 散文形:带 typed `code` 的前缀一个括号词(`(blob_too_large_for_sql) blob of … exceeds …`),
  * 不带的**逐字**是原 message(transient 失败的文案因此与本批之前一字不差)。
  * `fault` = 判断形(core 7.55.0 `FileHistoryError.permanence`):永久码表里的码 ⇒ `{ permanence: "terminal" }`;连接类故障 ⇒ `{ permanence: "transient" }`
- * (什么都不改稍后再试可能成);其余 ⇒ `{}`(店不知道 —— 认不出的驱动 / 库错是不是会自己好,不归本店判)。永久码先于连接类判(一只错不会两个都是)。
+ * (什么都不改稍后再试可能成);部署错配类故障 ⇒ `{ permanence: "terminal" }`(修表 / 授权之前重试注定失败);其余 ⇒ `{}`(店不知道 —— 认不出的驱动 / 库错是不是会自己好,不归本店判)。
+ * 永久码先于分类判(一只错不会两个都是);分类词只读判官 `storeFaultClassOf`,本文件不写码。
  * 副作用 = 机器形:码取自错误对象,逐次计数 + 每进程每码一条 warn。观测绝不抛。
  */
 export declare function foldCaughtFailure(err: unknown): CaughtFailure;

package/dist/file-history-disclosure.js

@@ -46,6 +46,8 @@ function faultOfClass(cls) {
     switch (cls) {
         case "connection":
             return { permanence: "transient" };
+        case "deployment":
+            return { permanence: "terminal" };
         case "corrupt":
         case "unclassified":
             return {};

package/dist/gate-settlement.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 回决门族 200 体上的**结清证据**(`decisionCommitted` / `checkpointId`)—— 唯一铸点与唯一读法。
+ *
+ * ## 律(一条)
+ * `decisionCommitted: true` = 「本请求点名的那道门,已以本请求的决定被耐久地结清过」的**历史证据**。它只在下面五个执行 / 回放边界之一
+ * 被跨过的那一拍、由 {@link buildSettlementEvidence} 铸(闭集 {@link SettlementCrossing},`switch` 穷尽):
+ *  ① `engine_accepted` —— 引擎续跑腿的受理点(`resumeStream` 解析 = 引擎的 pre-CAS 守卫与 checkpoint resolve CAS 都过了);
+ *  ② `engine_terminal` —— 引擎续跑腿交回结果之后的终局体(同步长调用形 / verify 臂;含「已提交、又重开同一张卡」的 `retriable:true` 那一形);
+ *  ③ `replay_matched`  —— `/decide` 幂等回放比对通过(同一决定早已与 resolve 原子地落在行上;回放不起续跑);
+ *  ④ `agent_revived`   —— 停驻后台子代复活成功(引擎以选中的 token 续跑、attach 之后才交回);
+ *  ⑤ `card_voided`     —— 复活不了的停驻子代被 deny 作废成功(这道门以本 deny **经作废结清**:卡 pending → expired;没有 resolve、没有 deny 结果行)。
+ * 调用方对一条引擎续跑腿的分类({@link GateCommitment})只说「这条腿到边界时能证什么」,**从不单独铸位** —— 位要有边界作证。
+ * 不铸的出口(都在调用点成文):`checkpoint.resume_aborted` 取消(拿不到 resolve 的返回值 ⇒ 证不出)、抛出臂的取消(受理之后也可能走到 ⇒
+ * **刻意不带**证据,fail-closed)、4xx、交给宿主 / 新铸一跑 / 同一决定重投的回执(`delivered`,门由别人结清或仍待决)、停驻子代认领到的
+ * token 不是选中的那一张(⇒ `409 decide.gate_moved`,不复活)。证据只随**同一次决定**的回放走:停驻赎回席的反向重试回放摘掉它
+ * ({@link withoutSettlementEvidence})。
+ *
+ * ## 读法(三句,契约 §4a「结清证据」同句)
+ *  · 位在场 ⇒ 门已以此决定结清过(历史证据;与 `errorCode:"cancelled"` 或 `retriable:true` 并存时同样成立 —— 它不证明卡的**当前**状态、
+ *    不证明批过的动作执行了);
+ *  · 位缺席 ⇒ 证不出或刻意不带,按「没提交」读;
+ *  · `checkpointId` = 执行**前**从选中的那一行捕获、过信任边界(`checkpoint-identity.ts` 的 `durableRowIdentity`,face `decision-receipt`)
+ *    的门身份,只随位出现;缺席 = 身份不可用(老行 / 没过边界)或不适用(回放的投影不带门身份),不推断任何事。
+ *
+ * ## 读者
+ * 本仓两个:`/decide` 的 [ref] 迟到结算留痕与 remember 豁免落店,都经 {@link decisionCommittedOf} 读体上的位(一处读法;不读 `errorCode`)。
+ * 纯数据、零运行时依赖(停驻子代腿与 HTTP 层共用)。
+ */
+import type { GateIdentity } from "./checkpoint-identity.js";
+/**
+ * 一条**引擎续跑腿**到达边界时能证什么(调用方声明;闭集)。`DriveResumeArgs` 的必填位 —— 同一条驱动路径既续本请求点名的门,也替宿主投递。
+ *  · `gate_resolved` —— 这条腿 resolve 的就是本请求点名的那道门(`/decide` 引擎臂、`/resume`、`/plan_review`);`checkpointId` = 执行前捕获的身份片段。
+ *  · `delivered`     —— 这条腿 resolve 的是宿主的门(wake;含 `/decide` workflow 车道的 wake 投递腿):本请求点名的那道门由别人结清或仍待决 ⇒ 到任何边界都不铸。
+ */
+export type GateCommitment = {
+    readonly kind: "gate_resolved";
+    readonly checkpointId?: string;
+} | {
+    readonly kind: "delivered";
+};
+/** 五个边界(铸点穷尽)。引擎两边界按腿的分类铸;回放不带身份;停驻子代两边界的门恒是本请求点名的那道,身份取执行前捕获的那一份。 */
+export type SettlementCrossing = {
+    readonly at: "engine_accepted" | "engine_terminal";
+    readonly commitment: GateCommitment;
+} | {
+    readonly at: "replay_matched";
+} | {
+    readonly at: "agent_revived" | "card_voided";
+    readonly gate: GateIdentity;
+};
+/** 体上的结清证据(两键都可缺席;wire 只加)。由调用方原样展开进它自己的体形(各体形保持各自的键集,不并进一张受理形)。 */
+export interface GateSettlementEvidence {
+    readonly decisionCommitted?: true;
+    readonly checkpointId?: string;
+}
+/** 没有跨过任何边界的回执(`/decide` workflow 车道的宿主新一跑、同一决定重投)带的证据:无。 */
+export declare const NO_SETTLEMENT_EVIDENCE: GateSettlementEvidence;
+/** **唯一铸点**:一次边界跨越 → 体上的证据片段。 */
+export declare function buildSettlementEvidence(crossing: SettlementCrossing): GateSettlementEvidence;
+/**
+ * 一张已带证据的回执被拿去答**另一个**决定(停驻赎回席的反向重试:回放首次受理的那一向、不改判)⇒ 证据两键都摘掉 ——
+ * 证据说的是当初被结清的那次决定,这一次请求的决定从没被结清。同向重试是同一次请求的回放,体原样(证据随它)。
+ * 只摘、不铸:本模块之外没有第二个写这两键的地方。
+ */
+export declare function withoutSettlementEvidence<B extends Record<string, unknown>>(body: B): Omit<B, keyof GateSettlementEvidence>;
+/** **唯一读法**:这张回决应答说「门已以此决定结清过」吗(`200` 且体上的位为真)。两个读者同调这一只。 */
+export declare function decisionCommittedOf(out: {
+    readonly status: number;
+    readonly body: object;
+}): boolean;
+//# sourceMappingURL=gate-settlement.d.ts.map