@sema-agent/server 7.137.0 → 7.139.0

package/dist/brain.js

@@ -6,7 +6,7 @@ import { createHash } from "node:crypto";
 import { isModelKeyPoison, modelKeyPoisonIdentity } from "./key-resolver.js";
 import { anthropicRouteRoot, brainLaneFor, mountRoutes, routeTableOf } from "./model-provider.js";
 import { openaiRouteBaseUrl } from "./model-route-endpoint.js";
-import { anthropicLaneCredentialOf } from "./model-route-gap.js";
+import { anthropicLaneCredentialOf, declaredCredential } from "./model-route-gap.js";
 import { catalogEntryFingerprint } from "./web-admin-client/restart-signal.js";
 import { buildDisplaySafeRefusal, buildDisplaySafeUrl } from "./trace/redact.js";
 import { createModelReachBrain } from "./model-unreachable-notice.js";
@@ -26,10 +26,10 @@ function breakerRoutesOf(config, r) {
     return r.circuitBreaker ? deploymentGatewayRoots(config).slice(0, -1) : [];
 }
 function deploymentGatewayKey(config) {
-    return config.gatewayBaseUrl !== undefined ? config.gatewayApiKey : undefined;
+    return config.gatewayBaseUrl !== undefined ? declaredCredential(config.gatewayApiKey) : undefined;
 }
 function degradeDeclaredRoot(fallbackBaseUrl, config) {
-    const armed = Boolean(deploymentGatewayKey(config)) && isOffDeploymentRoot(fallbackBaseUrl, config);
+    const armed = deploymentGatewayKey(config) !== undefined && isOffDeploymentRoot(fallbackBaseUrl, config);
     return armed ? config.gatewayBaseUrl : openaiRouteBaseUrl(fallbackBaseUrl, config.gatewayBaseUrl);
 }
 export const FAST_FAIL_MAX_RETRIES = 2;
@@ -110,7 +110,7 @@ export function createBrainAssembly(config, deps = {}) {
                     brainRoutes.anthropic
                 : constructRouteBrain(`degrade target "${degradeTo}"`, [fallbackModel.baseUrl, config.gatewayBaseUrl], () => createOpenAIBrain({
                     ...(fbDeclaredRoot !== undefined ? { baseUrl: fbDeclaredRoot } : {}),
-                    ...(fbDeploymentKey ? { apiKey: fbDeploymentKey } : {}),
+                    ...(fbDeploymentKey !== undefined ? { apiKey: fbDeploymentKey } : {}),
                     ...(config.gatewayMaxRetries !== undefined ? { maxRetries: config.gatewayMaxRetries } : {}),
                     fetchImpl,
                     ...timeouts,
@@ -240,7 +240,7 @@ export function brainSummary(config) {
             if (declaresOwnCredential) {
                 return { reactiveDegradeRoutePairing: "per-model-declared", reactiveDegradeRouteRefusal: null };
             }
-            const verdict = adjudicateModelRoute({ id: target.id, baseUrl: target.baseUrl }, resolveRouteCredential(((key) => (key ? { configApiKey: key } : {}))(deploymentGatewayKey(config))), { baseUrl: degradeDeclaredRoot(target.baseUrl, config) });
+            const verdict = adjudicateModelRoute({ id: target.id, baseUrl: target.baseUrl }, resolveRouteCredential(((key) => (key !== undefined ? { configApiKey: key } : {}))(deploymentGatewayKey(config))), { baseUrl: degradeDeclaredRoot(target.baseUrl, config) });
             return verdict.ok
                 ? { reactiveDegradeRoutePairing: `ok:${verdict.posture}`, reactiveDegradeRouteRefusal: null }
                 : {

package/dist/budget.d.ts

@@ -5,7 +5,7 @@
  *   ④ createTracer    — core's content-free TraceEvents → /metrics (spend, first-token, tool calls).
  *   ⑤ cappedCeiling  — clamp a caller's requested per-task budget DOWN to the operator ceiling.
  */
-import { type Model, type ModelPricing, type TracerHook } from "@sema-agent/core";
+import { type AccountRow, type Model, type ModelPricing, type TracerHook } from "@sema-agent/core";
 import type { Metrics } from "./observability/metrics.js";
 import type { QuotaTracker } from "./observability/cost-quota.js";
 import type { FleetUsageBins } from "./fleet-client.js";
@@ -116,23 +116,25 @@ export declare function createTracer(metrics: Pick<Metrics, "inc" | "observe">,
  * (tokens×quotaWeight,weight-at-burn 固化)、micro-USD 同轴。装配点与 createTracer 同一处(main.ts),
  * 传同一组实例——两臂永不分家。
  *
- * 已知残差(codex R3 medium,记档):cost 源=core SideQueryResult.usage.cost.total(brain 层计价),
- * OpenAI cache-heavy 输入按全价入账(tracer 的 e.costMicroUsd 是 cache-family-aware 价)——方向=多收
- * (保守,绝不少收);根修=core 在 SideQueryResult 上回权威 costMicroUsd(已提货 core)。model 标签/
+ * 金额源 = 引擎定价的账行 `SideQueryResult.account.costMicroUsd`(core 7.59.0:与 run 的旁路调用同一只定价函数、
+ * 按部署价表、按实际作答的模型)—— 与 tracer 的 `e.costMicroUsd` 同一口径;缺席 = 那只模型没有价表 = **未知**(不编 0)。
+ * 适配器自报的 `usage.cost.total`(cache 命中按全价)不是金额源(7.58.x 及更早读它,cache-heavy 时多收)。model 标签 /
  * weight 键用**路由身份 r.model**(池配置有界)非 servedModel(provider 上报,无界)。
  */
-export declare function createSideQueryAccountant(metrics: Pick<Metrics, "inc">, costQuota?: QuotaTracker, fleetUsage?: Pick<FleetUsageBins, "record">, fleetLease?: Pick<FleetLeaseManager, "recordSpend">, quotaWeightFor?: (model: string) => number): (principal: string | undefined, r: {
-    model: string;
-    usage?: {
-        input?: number;
-        output?: number;
-        cacheRead?: number;
-        cacheWrite?: number;
-        cost?: {
-            total?: number;
-        };
+export interface SideQueryAccountingInput {
+    readonly model: string;
+    /** 引擎归一的计数(`input` 已是 uncached 量,见函数体 [ref] 注)。 */
+    readonly usage?: {
+        readonly input?: number;
+        readonly output?: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
     };
-}) => void;
+    /** 引擎定价的账行(`origin: "side_query"`);只读它的 `costMicroUsd`。 */
+    readonly account?: AccountRow;
+}
+export type SideQueryAccounting = (principal: string | undefined, r: SideQueryAccountingInput) => void;
+export declare function createSideQueryAccountant(metrics: Pick<Metrics, "inc">, costQuota?: QuotaTracker, fleetUsage?: Pick<FleetUsageBins, "record">, fleetLease?: Pick<FleetLeaseManager, "recordSpend">, quotaWeightFor?: (model: string) => number): SideQueryAccounting;
 /**
  * ⑤ Resolve a per-task budget: honor the caller's requested value but never let it EXCEED the operator
  * ceiling. `0`/unset ceiling = no limit (returns the caller's value, or undefined). A non-positive /

package/dist/budget.js

@@ -144,8 +144,8 @@ export function createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetL
         const cacheRead = typeof r.usage?.cacheRead === "number" ? r.usage.cacheRead : 0;
         const cacheWrite = typeof r.usage?.cacheWrite === "number" ? r.usage.cacheWrite : 0;
         const promptTokens = input + cacheRead + cacheWrite;
-        const costTotal = typeof r.usage?.cost?.total === "number" ? r.usage.cost.total : undefined;
-        const micro = costTotal !== undefined ? Math.round(costTotal * 1_000_000) : undefined;
+        const costMicro = r.account?.costMicroUsd;
+        const micro = typeof costMicro === "number" && Number.isFinite(costMicro) ? Math.round(costMicro) : undefined;
         if (micro !== undefined && micro > 0) {
             metrics.inc("model_cost_micro_usd_total", { model: r.model }, micro);
             if (principal)

package/dist/capabilities/mcp-probe.d.ts

@@ -34,6 +34,7 @@
  */
 import { type McpServerSpec } from "@sema-agent/core";
 import type { DeclarationRefusal } from "../request-declaration-refusal.js";
+import { type McpDraft, type PeerDesk } from "../peer-seat.js";
 /**
  * 本面的**拒码闭集**(设计稿 §2 的四枚)。闭集写成型,是为了让 {@link MCP_PROBE_HTTP_STATUS} 那张表
  * 「漏一枚 = 编译红」—— [ref] 的安全轴纪律:词表是闭集,未处置的成员必须是编译错误而不是运行期惊喜。
@@ -163,25 +164,29 @@ export interface McpProbeRefusal {
     readonly facts?: DeclarationRefusal["facts"];
 }
 /**
- * `POST …/probe` 的体读器:闭形、逐条点名、零静默丢。成功 ⇒ 交给 core 的 `specs`(**原样**转发被读出来的
- * 条目,`McpServerSpec` 的可选键一个都不重写 —— 重写就是在 core 的型上做第二次投影)。
+ * `POST …/probe` 的体读器:闭形、逐条点名、零静默丢。成功 ⇒ 每条申报的**草稿**(被读出来的条目经 `toMcpDraft` 拆成声明 + 件,
+ * 声明里 `McpServerSpec` 的可选键一个都不重写 —— 重写就是在 core 的型上做第二次投影)。
  *
  * ## 申报「能不能原样用」:问提交腿 fresh 门**同一只**回答者,不另判
  * 本面只判自己那一层(体是对象、顶层只受理 `mcpServers`、这个键必填);`mcpServers` 本身 —— 列表的形、上限、每条的键名与键值 —— 全部交给
  * `task-mcp.ts` 的 `requestMcpDeclarationRefusal`,拒(码 + 句 + `unknownKeys` + 撞帽 / url 带凭据两形的机读位)原样转述:同一份申报在两扇门上只有一个答案,零拨号之前就给。
- * 回答者受理的申报由**同一只**读器(`validateRequestMcp`)交回,读器的产物就是申报本身(只差判官自己的合法归一),经 `toCoreMcpServerSpec`
- * 得到的就是一条任务提交会交给引擎的那一份 —— 本面拨的正是它。读器只在回答者受理之后才跑,所以它对重放存量 body 才有的降级留痕
- * (`source` 写坏的 F 类丢弃)不会在一次被拒的探测上虚记。
+ * 回答者受理的申报由**同一只**读器(`validateRequestMcp`)交回,读器的产物就是申报本身(只差判官自己的合法归一),经 `toMcpDraft`
+ * 拆出的草稿就是一条任务提交会交给铸点的那一份 —— 走查在自己的租约下铸它(见 {@link createMcpProbeWalk}),本面拨的正是铸出的声明。读器只在回答者受理之后才跑,
+ * 所以它对重放存量 body 才有的降级留痕(`source` 写坏的 F 类丢弃)不会在一次被拒的探测上虚记。
  *
- * ## 唯一一处按门分的后果:声明了 `assertionHeader`(引擎尚无断言头座)
+ * ## 唯一一处按门分的后果:声明了 `assertionHeader`(本部署的对端座对断言一种引用恒拒、没有断言来源)
  * 事实只有一个、读它的谓词只有一只(`specWithholdsMcpAssertionHeader`,读发送开关 `MCP_ASSERTION_HEADER_SENT`):这台 server 声明的断言头本版**承载、不发送**,交给引擎的规格里没有它。
  * 新提交照挂并给运维一行 info(`mcp_assertion_header_not_sent`;settings 面同读法);本面**整条拒** —— 拨出去的不是申报的那一份,一台握手放行、
  * 调用才要断言的对端会被答成 connected,而它的调用会被拒。判据同一只、后果按门分(与重放腿对同一组身份头「降级到升级前读法」同一个姿势);
- * 引擎长出同名座的那天,开关翻真,`toCoreMcpServerSpec` 的剥键与这一拒一起退役(`mcp-assertion-header.ts` 的退役门编译红)。
+ * 开关与它的退役门在 `mcp-assertion-header.ts`(押在对端座上)。
+ *
+ * ## 带件的申报(`transport.headers` / `transport.env`):与任务提交同一条路
+ * 件进草稿、不进声明;走查在自己的宿主租约下把件登记进部署的对端座,交给引擎的声明只带一只引用,引擎在起子进程 / 发请求时向同一只座要 ——
+ * 拨出去的就是申报的那一份,件形的判(多行值、协议自有头名 …)也是任务那一份判。
  */
 export declare function readMcpProbeBody(raw: unknown): {
     ok: true;
-    specs: McpServerSpec[];
+    drafts: McpDraft[];
 } | {
     ok: false;
     refusal: McpProbeRefusal;
@@ -194,8 +199,28 @@ export declare function readMcpProbeBody(raw: unknown): {
  * 无 principal(单用户部署上恒如此)折成 `local`:那台机器上只有一个人。
  */
 export declare function buildMcpProbeIdentity(principal: string | undefined): string;
-/** 缓存键 = `(身份, sha256(规范化 specs))`。**纯数据** ⇒ `build*`。 */
-export declare function buildMcpProbeCacheKey(principal: string | undefined, specs: readonly McpServerSpec[]): string;
+/**
+ * 一次探测问的是什么 —— 两条口各一臂,**谁写的申报**就是判别位:
+ *  · `deployment`(`GET /v1/capabilities/mcp`)= 本部署名册里这个场景挂的声明。它们起服时已在名册租约下铸过(件在对端座里、声明只带引用),
+ *    走查直接拨、不开租约、不再登记;
+ *  · `caller`(`POST …/probe`)= 调用方自带申报的草稿(声明 + 件)。走查在自己的宿主租约下经唯一铸点登记件,见 {@link createMcpProbeWalk}。
+ * 两臂的声明都由同一只座作答。缓存键、走查、失败归属(谁写的申报谁的错)都读这一只输入。
+ */
+export type McpProbeInput = {
+    readonly declaredBy: "deployment";
+    readonly specs: readonly McpServerSpec[];
+} | {
+    readonly declaredBy: "caller";
+    readonly drafts: readonly McpDraft[];
+};
+/** 这次探测申报了几台(零台 ⇒ 诚实空面,不进缓存、不占限速、不开租约)。 */
+export declare function countMcpProbeDeclarations(input: McpProbeInput): number;
+/**
+ * 缓存键 = `(身份, sha256(规范化的整份输入))`。**对输入算**:键在缓存命中 / 在途帽 / 限速三道前置拒里就要用,那时还没有登记任何件(登记在走查里),
+ * 所以只能对问的那一份算 —— 调用方臂的件在键内(只差凭据的两份申报是两次走查,与件写在声明里时同义),申报方也在键内(同一份声明在两臂上是两件事)。
+ * 部署臂的声明带的是引用,同一进程同内容同 id,换了名册的件就换了 id。键只在进程内的表里用,不出门。**纯数据** ⇒ `build*`。
+ */
+export declare function buildMcpProbeCacheKey(principal: string | undefined, input: McpProbeInput): string;
 /** 限速键(设计稿 §3:`mcp-probe:<身份>`)。**纯数据** ⇒ `build*`。 */
 export declare function buildMcpProbeRateKey(principal: string | undefined): string;
 /** 本域独占的运行期状态(每 server 实例一份 —— 模块级会把缓存与限速窗跨实例串味)。 */
@@ -281,7 +306,7 @@ export interface McpProbeWalk {
     readonly answer: Promise<McpProbeFaceBody>;
     readonly dials: Promise<unknown>;
 }
-export declare function createMcpProbeWalk(specs: readonly McpServerSpec[], principal: string | undefined, now?: () => number): McpProbeWalk;
+export declare function createMcpProbeWalk(input: McpProbeInput, principal: string | undefined, desk: PeerDesk, now?: () => number): McpProbeWalk;
 /**
  * 下标对齐的**内部断言**没过(行数 ≠ 申报数,或读数条数 ≠ 行数):core 的 `@contract mcp.probe.index_aligned` 在今天结构上保证它不发生,
  * 所以它一旦发生,是**这台服务内部的读数违约**,不是调用方的申报写错 —— 修申报修不好它。**具名型**而不是按文案或按「非 Incomplete 的 reject」分诊:

package/dist/capabilities/mcp-probe.js

@@ -4,7 +4,8 @@ import { createFixedWindowRateLimiter } from "../device-enrollment.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { keyClosureClause, scanKeyClosure } from "../request-key-closure.js";
 import { requestMcpDeclarationRefusal, validateRequestMcp } from "../task-mcp.js";
-import { specWithholdsMcpAssertionHeader, toCoreMcpServerSpec } from "../mcp-assertion-header.js";
+import { specWithholdsMcpAssertionHeader, toMcpDraft } from "../mcp-assertion-header.js";
+import { mintDeclaration } from "../peer-seat.js";
 import { projectWiringManifestMcpRows } from "../trace/project.js";
 import { buildBoundedToolNames } from "../panel-tool-names.js";
 export const MCP_PROBE_REFUSAL_CODES = [
@@ -80,13 +81,26 @@ export function readMcpProbeBody(raw) {
                 "Probe the entry without the key to see how the server answers without it"),
         };
     }
-    return { ok: true, specs: validated.ok.map(toCoreMcpServerSpec) };
+    return { ok: true, drafts: validated.ok.map(toMcpDraft) };
 }
 export function buildMcpProbeIdentity(principal) {
     return principal !== undefined && principal.length > 0 ? principal : "local";
 }
-export function buildMcpProbeCacheKey(principal, specs) {
-    return `${buildMcpProbeIdentity(principal)}::${createHash("sha256").update(canonicalJsonStringify(specs), "utf8").digest("hex")}`;
+export function countMcpProbeDeclarations(input) {
+    switch (input.declaredBy) {
+        case "deployment":
+            return input.specs.length;
+        case "caller":
+            return input.drafts.length;
+        default: {
+            const unknownArm = input;
+            void unknownArm;
+            throw new Error("mcp probe: an input arm this module does not know (the arm set is closed: deployment / caller)");
+        }
+    }
+}
+export function buildMcpProbeCacheKey(principal, input) {
+    return `${buildMcpProbeIdentity(principal)}::${createHash("sha256").update(canonicalJsonStringify(input), "utf8").digest("hex")}`;
 }
 export function buildMcpProbeRateKey(principal) {
     return `mcp-probe:${buildMcpProbeIdentity(principal)}`;
@@ -155,7 +169,8 @@ export function buildMcpProbeFaceRows(rows, readings) {
 function isStringList(v) {
     return Array.isArray(v) && Array.from(v).every((t) => typeof t === "string");
 }
-export function createMcpProbeWalk(specs, principal, now = Date.now) {
+export function createMcpProbeWalk(input, principal, desk, now = Date.now) {
+    const { specs, lease } = probeDeclarations(input, desk);
     const bound = buildMcpProbeWalkTimeoutMs(specs.length);
     const controller = new AbortController();
     const dials = probeMcpServers(specs, {
@@ -163,7 +178,10 @@ export function createMcpProbeWalk(specs, principal, now = Date.now) {
         timeoutMs: MCP_PROBE_VERDICT_TIMEOUT_MS,
         concurrency: MCP_PROBE_CONCURRENCY,
         signal: controller.signal,
+        peerSeat: desk.seat,
     });
+    if (lease !== undefined)
+        void dials.then(() => lease.release(), () => lease.release());
     dials.catch(() => undefined);
     let timer;
     const deadline = new Promise((_resolve, reject) => {
@@ -189,6 +207,27 @@ export function createMcpProbeWalk(specs, principal, now = Date.now) {
     answer.catch(() => undefined);
     return { answer, dials };
 }
+function probeDeclarations(input, desk) {
+    switch (input.declaredBy) {
+        case "deployment":
+            return { specs: input.specs };
+        case "caller": {
+            const lease = desk.lease("probe");
+            try {
+                return { specs: input.drafts.map((draft) => mintDeclaration(desk, draft, lease)), lease };
+            }
+            catch (err) {
+                lease.release();
+                throw err;
+            }
+        }
+        default: {
+            const unknownArm = input;
+            void unknownArm;
+            throw new Error("mcp probe: an input arm this module does not know (the arm set is closed: deployment / caller)");
+        }
+    }
+}
 export class McpProbeMisaligned extends Error {
     constructor(message) {
         super(message);

package/dist/capabilities/scenarios.d.ts

@@ -85,7 +85,7 @@ export interface ScenarioContext {
     /**
      * [ref] / [ref]:**委派树根的见证**(停驻挂点的属主来源)—— 根会话 id + 调用方判断那一刻读到的根行住客(`delegated-session-owner.ts` 的 `DelegationRootWitness`)。
      * 由**每一个**接了停驻挂点的取用方显式交出(一条读法,没有回落):请求腿 = 本请求经鉴权解析的会话与受理时那一读(`boot/resolve-spec.ts`);`/decide` 赎回面 = 行上的
-     * `rootSessionId` 与赎回腿 claim 前后两读的那一位住客(`parked-revive-surface.ts`,交不交座都交)。它**只**喂停驻挂点,不挂任何会话级设施(那是 {@link sessionId} 的事,
+     * `rootSessionId` 与赎回腿写口放行的那一位住客(`parked-revive-surface.ts`,交不交座都交)。它**只**喂停驻挂点,不挂任何会话级设施(那是 {@link sessionId} 的事,
      * 判据是「这只 bundle 是不是在那只会话上取用的」,与属主来源是两个独立判据)。缺席 = 没有根可交(boot 期探针、run-local、行上没有根)⇒ 律给哨兵。
      * 挂点在停驻那一刻再读一次根行:住客不是见证的那一位(删了、同 id 被重新登记)⇒ 停驻否决 —— 不按新住客晋升或认领。
      */

package/dist/capability-facts.d.ts

@@ -33,12 +33,13 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly subagent_output_face_absent: "the background sub-agent output face is not wired";
     readonly task_handle_faces_absent: "the background task-handle output/stop faces are not wired";
     readonly session_head_face_absent: "the session store has no by-id head read (sessionStorage.headOf — owner, occupant and leaf of a session row in one read)";
+    readonly execution_placement_seat_absent: "the session store has no execution placement seat (sessionStorage.executionPlacement — the occupant and the execution placement cell of a root session row in one read)";
     readonly checkpoint_store_absent: "no durable checkpoint store is wired (DURABLE_APPROVAL)";
     readonly session_audit_absent: "no session audit view is wired (needs a durable session store)";
     readonly session_watch_absent: "the session watch registry is not wired";
     readonly session_lister_absent: "no session enumerator is wired (session store or run store listSessions)";
     readonly session_fork_face_absent: "the session store has no fork face";
-    readonly session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / patchSessionMeta)";
+    readonly session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / writeSessionRowCells)";
     readonly session_purge_absent: "no session purge coordinator is wired";
     readonly session_policy_store_absent: "no session policy store is wired";
     readonly store_backend_absent: "no store backend is wired (DB_BACKEND=memory, multi-tenant bare boot, or half-configured SQL)";
@@ -87,6 +88,7 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly not_k8s_lane: "the execution lane is not the k8s pod sandbox (REMOTE_EXEC=k8s)";
     readonly workspace_snapshot_store_absent: "no workspace snapshot store is configured (MINIO_ENDPOINT / MINIO_ACCESS_KEY / MINIO_SECRET_KEY)";
     readonly workspace_cache_off: "the build-cache volume per workspace space is off (WORKSPACE_CACHE=off, the default)";
+    readonly deployment_mod_packages_absent: "no operator-declared mod package was loaded at boot (MODS_ROOT / MODS_PACKAGES)";
 };
 export type CapabilityFactWhy = keyof typeof CAPABILITY_FACT_WHY;
 /** 不可用臂。 */
@@ -127,6 +129,13 @@ type HeadReadingSessionStore = WithMethods<OwnerAwareSessionStore, "headOf">;
 export declare function sessionOwnership(d: Pick<Deps, "sessionStorage">): Fact<"session_head_face_absent", {
     sessionStorage: HeadReadingSessionStore;
 }>;
+/**
+ * 执行放置读面在场:会话店带执行席(`executionPlacement`:一次行读 = 住客 + 执行放置格;SQL 两孪生与 local 恒带,引擎缺省的内存会话店没有)。
+ * 见证 = 那只席 —— `GET /v1/sessions/:id/execution-placement` 读它,且只读它(属主门判这一读的住客)。
+ */
+export declare function executionPlacementRead(d: Pick<Deps, "sessionStorage">): Fact<"execution_placement_seat_absent", {
+    seat: NonNullable<OwnerAwareSessionStore["executionPlacement"]>;
+}>;
 export declare function mcpReconnect(d: Pick<Deps, "runStore" | "sessionStorage">): Fact<"run_store_absent" | "session_head_face_absent", {
     runStore: Store<"runStore">;
     sessionStorage: HeadReadingSessionStore;
@@ -147,11 +156,11 @@ export declare function sessionList(d: Pick<Deps, "sessionStorage" | "runStore">
 export declare function sessionFork(d: Pick<Deps, "sessionStorage">): Fact<"session_fork_face_absent" | "session_head_face_absent", {
     sessionStorage: WithMethods<OwnerAwareSessionStore, "headOf" | "fork">;
 }>;
-/** 会话行可写位(`PATCH /v1/sessions/:id`):会话店的头读(属主 + 化身一次读 —— 门判属主、写与读回按化身条件)∧ 行写口(写后按同一住客读回)。
+/** 会话行可写位(`PATCH /v1/sessions/:id`):会话店的头读(属主 + 化身一次读 —— 门判属主,那一读就是写原语的行期望)∧ 行格写原语(锁内判、提交后另读应答行)。
  *  三只 durable 店(SQL 双生 / local)都带;内存 dev 店没有行写口 ⇒ 501。
- *  本面**没有**独立能力位(契约附录 B.2c 登记):老 worker 对这一动词答 405,本事实为假的部署答 501。 */
+ *  本面**没有**独立能力位(契约附录 B.2c 登记):老 worker 对这一动词答 405,本事实为假的部署答 501;条件写也没有 —— 列表行上有 `rowTag` 即支持。 */
 export declare function sessionPatch(d: Pick<Deps, "sessionStorage">): Fact<"session_row_faces_absent", {
-    sessionStorage: WithMethods<OwnerAwareSessionStore, "headOf" | "patchSessionMeta">;
+    sessionStorage: WithMethods<OwnerAwareSessionStore, "headOf" | "writeSessionRowCells">;
 }>;
 export declare function sessionDelete(d: Pick<Deps, "purgeSession" | "sessionStorage">): Fact<"session_purge_absent" | "session_head_face_absent", {
     purge: Store<"purgeSession">;
@@ -161,11 +170,11 @@ export declare function sessionPolicy(d: Pick<Deps, "sessionPolicyStore" | "sess
     policyStore: Store<"sessionPolicyStore">;
     sessionStorage: HeadReadingSessionStore;
 }>;
-type SyncSessionStore = WithMethods<OwnerAwareSessionStore, "exportEntries" | "exportEntriesStream" | "beginImportStaging" | "headOf" | "sessionSummaryOf" | "patchSessionMeta">;
+type SyncSessionStore = WithMethods<OwnerAwareSessionStore, "exportEntries" | "exportEntriesStream" | "beginImportStaging" | "headOf" | "sessionSummaryOf" | "writeSessionRowCells">;
 type SessionSyncWhy = "store_backend_absent" | "file_history_store_absent" | "session_export_absent" | "session_import_staging_absent" | "session_row_faces_absent" | "policy_purge_absent";
 /** 会话对等同步的**对话半族**(manifest / entries / plan / import 两相):后端 ∧ 文件历史店 ∧ 导出两面 ∧ staged 导入面 ∧
- *  会话行三口(门读头 `headOf` —— 属主 + 化身一次读,属主判门、化身给 identical 短路腿;manifest 带 `title` / `pinned`;导入经唯一写口按导入落定的
- *  那一位住客重放它们)∧ policy 店能清(overwrite-dst 的 commit 要擦目的端旧 policy 行)。
+ *  会话行三口(门读头 `headOf` —— 属主 + 化身一次读,属主判门、化身给 identical 短路腿;manifest 带 `title` / `pinned`;导入经行格写原语以 `replay` 写者
+ *  按导入落定的那一位住客重放它们)∧ policy 店能清(overwrite-dst 的 commit 要擦目的端旧 policy 行)。
  *  文件历史的 blob 搬运是另一只事实。 */
 export declare function sessionSync(d: Pick<Deps, "backend" | "sessionStorage" | "fileHistoryStore" | "sessionPolicyStore">): Fact<SessionSyncWhy, {
     backend: Store<"backend">;
@@ -355,6 +364,11 @@ export declare function workspaceSpace(c: Pick<ServiceConfig, "remoteExec">): Fa
 export declare function workspaceCache(c: Pick<ServiceConfig, "remoteExec">): Fact<"not_k8s_lane" | "workspace_cache_off", {
     cache: WorkspaceCacheCapability;
 }>;
+/** 运维声明的 mod 包:本进程起服装上了几只(部署座装配口 `assembleDeploymentMods` 的读数;本服务自铸的部署注册不算)。
+ *  `/health.mods.deploymentPackages`(投 `count`)与 caps `modsDeploymentPackages`(投 `.available`,false ⇒ 键缺席)同调这一只。 */
+export declare function deploymentModPackages(d: Pick<Deps, "deploymentModPackages">): Fact<"deployment_mod_packages_absent", {
+    count: number;
+}>;
 /** 自唤醒调度器挂在宿主 env 上:`SCHEDULER_ENABLED` ∧ 单用户 ∧ host 车道。装配(`boot/execution-env.ts`)与能力位同调。 */
 export declare function hostScheduler(c: Pick<ServiceConfig, "schedulerEnabled" | "requirePrincipal" | "remoteExec">): Fact<"scheduler_disabled" | "multi_tenant_deployment" | "not_host_lane">;
 /** 引擎能力词的事实(core `ENGINE_CAPABILITIES` 每词一只谓词,值 = 本进程的事实;`/v1/capabilities` 以顶层布尔键展开它们)—— 住在

package/dist/capability-facts.js

@@ -13,12 +13,13 @@ export const CAPABILITY_FACT_WHY = {
     subagent_output_face_absent: "the background sub-agent output face is not wired",
     task_handle_faces_absent: "the background task-handle output/stop faces are not wired",
     session_head_face_absent: "the session store has no by-id head read (sessionStorage.headOf — owner, occupant and leaf of a session row in one read)",
+    execution_placement_seat_absent: "the session store has no execution placement seat (sessionStorage.executionPlacement — the occupant and the execution placement cell of a root session row in one read)",
     checkpoint_store_absent: "no durable checkpoint store is wired (DURABLE_APPROVAL)",
     session_audit_absent: "no session audit view is wired (needs a durable session store)",
     session_watch_absent: "the session watch registry is not wired",
     session_lister_absent: "no session enumerator is wired (session store or run store listSessions)",
     session_fork_face_absent: "the session store has no fork face",
-    session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / patchSessionMeta)",
+    session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / writeSessionRowCells)",
     session_purge_absent: "no session purge coordinator is wired",
     session_policy_store_absent: "no session policy store is wired",
     store_backend_absent: "no store backend is wired (DB_BACKEND=memory, multi-tenant bare boot, or half-configured SQL)",
@@ -67,6 +68,7 @@ export const CAPABILITY_FACT_WHY = {
     not_k8s_lane: "the execution lane is not the k8s pod sandbox (REMOTE_EXEC=k8s)",
     workspace_snapshot_store_absent: "no workspace snapshot store is configured (MINIO_ENDPOINT / MINIO_ACCESS_KEY / MINIO_SECRET_KEY)",
     workspace_cache_off: "the build-cache volume per workspace space is off (WORKSPACE_CACHE=off, the default)",
+    deployment_mod_packages_absent: "no operator-declared mod package was loaded at boot (MODS_ROOT / MODS_PACKAGES)",
 };
 const no = (why) => ({ available: false, why });
 const yes = (w) => ({ available: true, ...w });
@@ -98,6 +100,10 @@ export function sessionOwnership(d) {
     const s = d.sessionStorage;
     return headReadOf(s) !== undefined ? yes({ sessionStorage: s }) : no("session_head_face_absent");
 }
+export function executionPlacementRead(d) {
+    const seat = d.sessionStorage?.executionPlacement;
+    return seat !== undefined ? yes({ seat }) : no("execution_placement_seat_absent");
+}
 export function mcpReconnect(d) {
     const runs = durableRuns(d);
     if (!runs.available)
@@ -132,7 +138,7 @@ export function sessionFork(d) {
 }
 export function sessionPatch(d) {
     const s = d.sessionStorage;
-    if (headReadOf(s) === undefined || s?.patchSessionMeta === undefined)
+    if (headReadOf(s) === undefined || s?.writeSessionRowCells === undefined)
         return no("session_row_faces_absent");
     return yes({ sessionStorage: s });
 }
@@ -162,7 +168,7 @@ export function sessionSync(d) {
         return no("session_export_absent");
     if (s.beginImportStaging === undefined)
         return no("session_import_staging_absent");
-    if (headReadOf(s) === undefined || s.sessionSummaryOf === undefined || s.patchSessionMeta === undefined)
+    if (headReadOf(s) === undefined || s.sessionSummaryOf === undefined || s.writeSessionRowCells === undefined)
         return no("session_row_faces_absent");
     if (overwriteWipeIncapable(d.sessionPolicyStore))
         return no("policy_purge_absent");
@@ -391,6 +397,10 @@ export function workspaceCache(c) {
         return no("workspace_cache_off");
     return yes({ cache: { mount: rx.workspaceCache.mount, size: rx.workspaceCache.size } });
 }
+export function deploymentModPackages(d) {
+    const n = d.deploymentModPackages;
+    return n !== undefined && n > 0 ? yes({ count: n }) : no("deployment_mod_packages_absent");
+}
 export function hostScheduler(c) {
     if (c.schedulerEnabled !== true)
         return no("scheduler_disabled");

package/dist/checkpoint-identity.d.ts

@@ -7,15 +7,22 @@ export declare const MAX_CHECKPOINT_ID_CHARS = 128;
 export declare function withoutCheckpointToken(text: string, token: unknown): string;
 /** 持久层读出的 `checkpointId` 过信任边界:是串、非空、不超长、不含 token(大小写不敏感)⇒ 原值;否则 `undefined`。判据全文见本文件头注。 */
 export declare function trustedCheckpointId(raw: unknown, token: unknown): string | undefined;
-/** 带 `checkpointId` 当 join 键的 durable 面(计数 detail 的 `face`):运维队列行、停驻收件行,与 7.137.0 起的 park 账本行(`GET /v1/runs/:id/events` 的 `suspended` / `needs_review`,写时判一次)。 */
-export type DurableCheckpointFace = "approvals-queue" | "assistant-inbox" | "run-events-park";
+/**
+ * 带 `checkpointId` 当 join 键的面(计数 detail 的 `face`):运维队列行、停驻收件行、park 账本行(`GET /v1/runs/:id/events` 的 `suspended` /
+ * `needs_review`,写时判一次),与回决门族的 200 体(`decision-receipt`:`/decide` / `/resume` / `/plan_review` 执行**前**从选中的那一行捕获一次,
+ * 结清证据带它 —— 语义属主 = `gate-settlement.ts`)。四面同一只读法、同一个计数。
+ */
+export type DurableCheckpointFace = "approvals-queue" | "assistant-inbox" | "run-events-park" | "decision-receipt";
+/** 一行的身份片段:读得出可信值 ⇒ `{ checkpointId }`;读不出 ⇒ `{}`(键缺席)。由调用方原样展开进行投影 / 结清证据。 */
+export type GateIdentity = {
+    readonly checkpointId?: string;
+};
 /**
  * durable 读面的一行 → 它的身份片段,**由调用方原样展开进行投影**(`...durableRowIdentity(face, raw, token)`):读得出可信值 ⇒ `{ checkpointId }`;
  * 读不出 ⇒ `{}`(这一行**照列**,键缺席)+ 计一次(见本文件头注「durable 面的 join 键」)。
  * `raw === undefined` = 行上没有这一格(`why=absent`,老行);在场却没过信任边界(非串 / 空串 / 超长 / 含 token / 读不出)= `why=untrusted`。
- * 三处读面(两只店的 `listPending` + 收件 handler)与 park 账本行的唯一构造器(`trace/project.ts` 的 `parkEventData`)只经这一只 —— 读法、计数、缺席形各只有一份。
+ * 三处读面(两只店的 `listPending` + 收件 handler)、park 账本行的唯一构造器(`trace/project.ts` 的 `parkEventData`)与回决门族三条续跑腿的执行前捕获点
+ * (`http/resume-legs.ts`:`/decide` 在分流之前一次、`/resume`、`/plan_review`)只经这一只 —— 读法、计数、缺席形各只有一份。
  */
-export declare function durableRowIdentity(face: DurableCheckpointFace, raw: unknown, token: unknown): {
-    readonly checkpointId?: string;
-};
+export declare function durableRowIdentity(face: DurableCheckpointFace, raw: unknown, token: unknown): GateIdentity;
 //# sourceMappingURL=checkpoint-identity.d.ts.map

package/dist/config-catalog.js

@@ -109,7 +109,7 @@ export const CONFIG_CATALOG = [
     r("CONFIG_LKG_PATH", "integrations", "path", "LKG 落盘路径(设了 ⇒ 派生一条读拒行 = 这条绝对路径:根锚定,只守这一个文件,经符号链接的目录时引擎沿链连目标一起守;大小写不敏感;用户仓里同尾的路径读得到;空串拒启)", { derivedDefaultNote: "缺席 ⇒ 配置根(SEMA_CONFIG_DIR,缺省 ~/.sema)下按 worker + 凭证身份分箱派生", configKey: "configLkgPath" }),
     r("CONFIG_LOCAL_DIR", "integrations", "path", "本地配置源根(config.d/<domain>.json);兼作数据根回落链一环", { configKey: "configLocalDir", danger: DATA }),
     r("CONFIG_LOCAL_OWNER_UID", "integrations", "number", "本地配置源读之前的目录信任判官多信的那一个属主 uid(本服务用户与 root 之外 —— userns-remap 的 bind-mount、运维用户持有的配置);只放宽属主判据,组 / 他人可写照拒;形错拒启", { configKey: "configLocalOwnerUid", danger: SEC, derivedDefaultNote: "缺席 = config.d 路径上的目录与文档只许属于本服务用户或 root" }),
-    r("CONFIG_PROVIDER", "integrations", "enum", "配置源双模选择(闭集,逐字比较;认不出的词 ⇒ 拒启,S-841)", { enumValues: CONFIG_PROVIDER_WORDS, derivedDefaultNote: `缺席:${WEB_ADMIN_ENV.url} 在场 ⇒ remote,否则纯 env(无管道)`, configKey: "configProvider" }),
+    r("CONFIG_PROVIDER", "integrations", "enum", `配置源双模选择(闭集,逐字比较;认不出的词 ⇒ 拒启;remote 而 ${WEB_ADMIN_ENV.url} 缺席 ⇒ 拒启 —— remote 的配置只来自那只中心)`, { enumValues: CONFIG_PROVIDER_WORDS, derivedDefaultNote: `缺席:${WEB_ADMIN_ENV.url} 在场 ⇒ remote,否则纯 env(无管道)`, configKey: "configProvider" }),
     r("CONFIG_REQUIRE_ROSTER", "integrations", "boolean", "远程 registry 非 dryRun 时布防 ready 门:roster 未落地 ⇒ 计费提交 503 + /health ready:false(严格 'true')", { staticDefault: "false" }),
     r("CORS_ORIGIN", "auth", "csv", "CORS 白名单(单值 v1 兼容回显;多值按请求 Origin 匹配 + Vary;未设=无 CORS 面)", { danger: SEC, configKey: "corsOrigins" }),
     r("COST_QUOTA_WINDOW_SEC", "limitsHttp", "number", "per-principal 成本配额窗长(秒);SQL 腿窗长进桶主键 ⇒ center 腿显式 deferred(重启生效)", { staticDefault: "86400", danger: BILL, configKey: "costQuotaWindowSec", center: cLimits("costQuotaWindowSec", { timing: "restart", restartReason: "cost-quota-window" }) }),
@@ -139,7 +139,7 @@ export const CONFIG_CATALOG = [
     r("DOCKER_NETWORK", "orchestration", "enum", "local-docker 容器网络模式", { enumValues: ["none", "bridge", "host"], staticDefault: "bridge", danger: SEC }),
     r("DOCKER_PATH", "orchestration", "path", "docker 二进制路径"),
     r("DOCKER_PIDS_LIMIT", "orchestration", "number", "local-docker fork-bomb 背栓(--pids-limit;非法值回 adapter 默认 512+warn)", { danger: SEC, derivedDefaultNote: "缺席 ⇒ adapter 默认 512" }),
-    r("DOCKER_SANDBOX_ENV", "orchestration", "secret", "local-docker 车道每条 docker exec 以 -e 注入的本进程 env 点名表(NAME,NAME;点到的键从 worker env 原样取,值不进 spec/center/日志;与 LSP_ENV_ALLOW / E2B_SANDBOX_ENV 同一只解析器与「点名放行」谓词:形错 / 点名名单型旋钮拒启且不回显值;本进程环境里没有的名按序号 warn、不转发;只在本车道被选中时求值;原文按凭据类对待:只回在场位、不进任何子进程)", { danger: SEC }),
+    r("DOCKER_SANDBOX_ENV", "orchestration", "secret", "local-docker 车道每条 docker exec 以 -e 注入的本进程 env 点名表(NAME,NAME;点到的键从 worker env 原样取,值不进 spec/center/日志;与 LSP_ENV_ALLOW / E2B_SANDBOX_ENV 同一只解析器与「点名放行」谓词:形错 / 点名名单型旋钮 / 点名本服务自有凭据名(会把本服务的凭据装进模型读得到的沙箱;判官 = 引擎拒白名单的同一只)拒启且不回显值;本进程环境里没有的名按序号 warn、不转发;只在本车道被选中时求值;原文按凭据类对待:只回在场位、不进任何子进程)", { danger: SEC }),
     r("DRAIN_GRACE_MS", "limitsHttp", "number", "SIGTERM 优雅排空窗(ms;期间新计费提交 503+Retry-After)。出厂默认是**服务器部署**的取值;壳自 spawn 的引擎会被壳注入更短的窗 ⇒ 排壳形关机预算时以本行的 effectiveValue(= 本进程实际生效值)为准,不照抄 staticDefault", { staticDefault: String(10 * 60 * 1000), configKey: "drainGraceMs", center: cLimits("drainGraceMs") }),
     r("DRAIN_SECOND_SIGNAL_MIN_GAP_MS", "limitsHttp", "number", `排空期「第二发信号 = 硬停」的最小间隔(ms;锚 = 本次排空的第一发停止信号 —— SIGTERM / SIGHUP 升级进的排空,入口那一发就是它;排空口 / 租约被拒 / 附着租约自退进的排空,到达的第一发被吸收、不缩短期限。SIGTERM / SIGINT 与锚相隔不足 ⇒ 同一拍的重复投递,一行 drain_duplicate_signal_ignored 后忽略、排空继续;0 = 关,恒按第二发硬停;须为 [${DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS.minMs}, ${DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS.maxMs}] 内十进制整数(上界 = DRAIN_GRACE_MS 地板),小数 / 负数 / 越界拒启)`, { staticDefault: String(DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS), configKey: "drainSecondSignalMinGapMs" }),
     r("DURABLE_APPROVAL", "approval", "boolean", "durable suspend/resume HITL(需 SQL 店;决定 checkpointStore 与 /v1/approvals 面的存在性)", { danger: SEC, derivedDefaultNote: "posture 三态(S-178):显式词恒赢,缺席 = 单用户(REQUIRE_PRINCIPAL≠true)且有耐久店 ⇒ on / 多租户或无耐久店 ⇒ off;生效来源见 GET /v1/diagnostics/wiring 的 serverGates.durableApproval.source", configKey: "durableApproval" }),
@@ -151,7 +151,7 @@ export const CONFIG_CATALOG = [
     r("E2B_LIVENESS_MS", "orchestration", "number", LIVENESS_KNOB_SEMANTICS("e2b"), { derivedDefaultNote: LIVENESS_KNOB_DEFAULT_NOTE }),
     r("E2B_MOUNT_PATH", "orchestration", "path", "e2b 工作区根(resume 用当前值,改前先 drain 挂起任务)"),
     r("E2B_ORPHAN_RECLAIM", "orchestration", "boolean", "崩溃遗留沙盒回收腿(boot 一次+周期;判据保守,拿不准恒不杀)", { staticDefault: "true", danger: BILL }),
-    r("E2B_SANDBOX_ENV", "orchestration", "secret", "转发进 e2b 沙箱的本进程 env 点名表(NAME,NAME;点到的键从 worker env 原样取,值不进 spec/center/事件日志;与 LSP_ENV_ALLOW / DOCKER_SANDBOX_ENV 同一只解析器与「点名放行」谓词:形错 / 点名名单型旋钮拒启且不回显值;本进程环境里没有的名按序号 warn、不转发;只在本车道被选中时求值;原文按凭据类对待:只回在场位、不进任何子进程)", { danger: SEC }),
+    r("E2B_SANDBOX_ENV", "orchestration", "secret", "转发进 e2b 沙箱的本进程 env 点名表(NAME,NAME;点到的键从 worker env 原样取,值不进 spec/center/事件日志;与 LSP_ENV_ALLOW / DOCKER_SANDBOX_ENV 同一只解析器与「点名放行」谓词:形错 / 点名名单型旋钮 / 点名本服务自有凭据名(会把本服务的凭据装进模型读得到的沙箱;判官 = 引擎拒白名单的同一只)拒启且不回显值;本进程环境里没有的名按序号 warn、不转发;只在本车道被选中时求值;原文按凭据类对待:只回在场位、不进任何子进程)", { danger: SEC }),
     r("E2B_SANDBOX_MAX_MS", "orchestration", "number", "e2b 沙箱最长存活(ms)", { staticDefault: "3600000", danger: BILL }),
     r("E2B_TEMPLATE", "orchestration", "string", "e2b 模板名(缺省 adapter 基础模板)"),
     r("E2B_TIMEOUT_MS", "orchestration", "number", "e2b 单命令总超时(ms)"),
@@ -167,7 +167,11 @@ export const CONFIG_CATALOG = [
     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(配置渲染器对每台受管引擎写,缺省 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,10 +208,10 @@ export const CONFIG_CATALOG = [
     r("K8S_LIVENESS_MS", "orchestration", "number", LIVENESS_KNOB_SEMANTICS("k8s"), { derivedDefaultNote: LIVENESS_KNOB_DEFAULT_NOTE }),
     r("K8S_MEMORY", "orchestration", "string", "沙箱 pod 内存限额(2Gi 默认曾被真 OOM)"),
     r("K8S_MOUNT_PATH", "orchestration", "path", "k8s 工作区挂载路径"),
-    r("K8S_NAMESPACE", "orchestration", "string", "沙箱 pod namespace"),
+    r("K8S_NAMESPACE", "orchestration", "string", "沙箱 pod 所在的 namespace(REMOTE_EXEC=k8s 必需件,与 K8S_SANDBOX_IMAGE 同级:缺席、空串或只有空白 ⇒ 起服拒,拒句点名本旋钮;服务不带内置缺省 —— 部署的声明是唯一来源,随包 chart 已显式设为 sandbox.namespace;只在 REMOTE_EXEC=k8s 被选中时求值)"),
     r("K8S_RUNTIME_CLASS", "orchestration", "string", "沙箱 pod runtimeClass(Kata 等)"),
     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_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 的泄漏护栏,后台任务超时也被它钳;各条命令的超时见工具超时)"),
@@ -352,6 +356,8 @@ export const CONFIG_CATALOG = [
         },
         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 }),
@@ -403,8 +409,8 @@ export const CONFIG_CATALOG = [
     r("RESOURCE_SUSPEND_TOTAL_TOKENS", "approval", "number", "跨片 token 总额(0=不设;与 MAX_TASK_TOKENS 的 per-slice 窗是两根轴)", { staticDefault: "0", danger: BILL, configKey: "resourceSuspendTotalTokens" }),
     r("RESOURCE_SUSPEND_TTL_SEC", "approval", "number", "resource/preempt checkpoint 的弃置 GC TTL(秒;0 ⇒ core 默认 30d)", { staticDefault: "0", danger: DATA, configKey: "resourceSuspendTtlSec" }),
     r("RETENTION_MAX_AGE_DAYS", "auth", "number", "托管留存期声明(core 启动期能力校验;真删除归 sweep lane)", { danger: DATA }),
-    r("RETENTION_MODE", "auth", "enum", "留存 sweep 灰度档(拼错拒启 —— audit-only 谎成 enforce 两个方向都致命)", { enumValues: ["audit-only", "enforce"], staticDefault: "audit-only", danger: DATA, resolve: (c) => c.retentionSweep.mode }),
-    r("RETENTION_SWEEP_INTERVAL_SEC", "auth", "number", "留存 sweep 节律(秒;0=lane 关)", { staticDefault: "0", danger: DATA }),
+    r("RETENTION_MODE", "auth", "enum", "留存 sweep 灰度档(拼错拒启 —— audit-only 谎成 enforce 两个方向都致命;enforce 而 RETENTION_MAX_AGE_DAYS 缺、或 RETENTION_SWEEP_INTERVAL_SEC 缺 / 为 0 ⇒ 拒启)", { enumValues: ["audit-only", "enforce"], staticDefault: "audit-only", danger: DATA, resolve: (c) => c.retentionSweep.mode }),
+    r("RETENTION_SWEEP_INTERVAL_SEC", "auth", "number", "留存 sweep 节律(秒;0=lane 关;> 0 而 RETENTION_MAX_AGE_DAYS 缺 ⇒ 拒启)", { staticDefault: "0", danger: DATA }),
     r("REWIND_SNAPSHOT_MAX_MB", "store", "number", "已退役(S-15 整树快照纪元退役):设了只 boot warn 一次,零行为", { envTiming: "inert" }),
     r("ROSTER_RETENTION_MS", "orchestration", "number", "agent_roster 行 TTL(ms;SQL twins 扩展面)", { staticDefault: String(30 * 24 * 60 * 60 * 1000), danger: DATA, configKey: "rosterRetentionMs" }),
     r("ROUTER_ENABLED", "orchestration", "boolean", "A 价值路由(per-task 编排自动决策;ship-dark)", { staticDefault: "false", configKey: "routerEnabled" }),