@sema-agent/server 7.37.0 → 7.38.0-rc.2

package/dist/config-invariants.js

@@ -0,0 +1,139 @@
+import { assertGuardPatternsUsable } from "./deployment-governance.js";
+/**
+ * 活体心跳周期(ms)——`runs.ts` 的 `HEARTBEAT_MS` 就是它(那边 re-export,单源在此)。
+ *
+ * 为什么常量住在不变量文件里:它唯一的**判据用途**是「陈旧窗必须大于心跳」这条不变量,而该不变量现在
+ * 有 boot 与 stage 两个消费面。放在这里,两面读的是同一个数,`runs.ts` 的心跳环也读同一个数。
+ */
+export const LIVENESS_HEARTBEAT_MS = 30_000;
+const anyServiceAuth = (v) => Boolean(v.authToken) || Object.keys(v.authTokens ?? {}).length > 0;
+/** 与 `resolveBindHost` 逐字同判:无鉴权写面 + 零凭据 ⇒ boot 期把监听地址收窄到 loopback。 */
+const mustNarrowBind = (v) => Boolean(v.allowUnauthedWrites) && !anyServiceAuth(v);
+/** 直连门的合取项(config.ts:2788 的同一组);任一项翻转 = 门姿态变更。 */
+const directDoorConjuncts = (v) => Boolean(v.directApprovalDoor) && Boolean(v.durableApproval) && v.approvalHmacKeys.length > 0 && v.principalJwtPubkeys.length > 0 && Boolean(v.principalJwtIss) && Boolean(v.principalJwtAud);
+export const CONFIG_CROSS_INVARIANTS = [
+    {
+        id: "run-stale-heartbeat",
+        keys: ["runStaleSec"],
+        restartReason: "run-stale-heartbeat",
+        bootAnchor: { file: "src/main.ts", marker: "CROSS-INVARIANT:run-stale-heartbeat" },
+        check: ({ next }) => next.runStaleSec * 1000 <= LIVENESS_HEARTBEAT_MS
+            ? `runStaleSec (${next.runStaleSec}s) must exceed the ${LIVENESS_HEARTBEAT_MS / 1000}s liveness heartbeat — the reaper would race a run that is still heartbeating normally and reap live work`
+            : undefined,
+    },
+    {
+        // 转换型:boot 期算一次的绑址收窄(resolveBindHost → server.listen)在运行期无法重算,所以任何
+        // **让收窄条件从不成立变成成立**的热切都是谎:写门确实收紧了,监听面却还在原来的接口上。
+        // 反向(窄→宽,例如加了凭据)不拒:那是收紧姿态,已绑的 loopback 只会更严。
+        id: "bind-posture",
+        keys: ["authToken", "authTokens", "allowUnauthedWrites"],
+        restartReason: "bind-posture",
+        check: ({ live, next }) => !mustNarrowBind(live) && mustNarrowBind(next)
+            ? "this candidate would make the unauthenticated-write posture require narrowing the listener to 127.0.0.1, but the listen address is bound once at boot — refusing to hot-apply (restart to re-bind)"
+            : undefined,
+    },
+    {
+        id: "bake-runner-credential",
+        keys: ["imageBakes", "authTokens"],
+        restartReason: "bake-runner-credential",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:bake-runner-credential" },
+        check: ({ next }) => next.imageBakes.enabled && !Object.values(next.authTokens ?? {}).includes(next.imageBakes.runnerPrincipal)
+            ? `IMAGE_BAKES_ENABLED is on but no SERVICE_AUTH_TOKENS entry maps to the runner principal '${next.imageBakes.runnerPrincipal}' — claim/ingest/heartbeat would all 403`
+            : undefined,
+    },
+    {
+        // 状态 + 转换两面都判:半开的直连门(boot 会拒启的那些组合)绝不许经热路径造出来;门**姿态**
+        // (激活/未激活)的翻转同样只许重启 —— 消费面(/health directDoorActive、鉴权腿)在 boot 期定形。
+        id: "direct-door-anchors",
+        keys: ["directApprovalDoor", "durableApproval", "approvalHmacKeys", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud", "requirePrincipal", "operatorPrincipals"],
+        restartReason: "direct-door",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:direct-door-anchors" },
+        check: ({ live, next }) => {
+            if (next.directApprovalDoor) {
+                const missing = [];
+                if (!next.durableApproval)
+                    missing.push("DURABLE_APPROVAL");
+                if (next.approvalHmacKeys.length === 0)
+                    missing.push("APPROVAL_HMAC_KEYS");
+                if (next.principalJwtPubkeys.length === 0)
+                    missing.push("PRINCIPAL_JWT_PUBKEYS");
+                if (!next.principalJwtIss)
+                    missing.push("PRINCIPAL_JWT_ISS");
+                if (!next.principalJwtAud)
+                    missing.push("PRINCIPAL_JWT_AUD");
+                if (next.operatorPrincipals.length === 0)
+                    missing.push("OPERATOR_PRINCIPALS");
+                if (!next.requirePrincipal)
+                    missing.push("REQUIRE_PRINCIPAL");
+                if (missing.length > 0)
+                    return `a half-open direct approval door is refused: missing ${missing.join(", ")}`;
+            }
+            return directDoorConjuncts(live) !== directDoorConjuncts(next)
+                ? "the direct-door posture (its conjunction of approval/JWT anchors) is decided at boot — refusing to hot-flip it (restart to change the door)"
+                : undefined;
+        },
+    },
+    {
+        id: "operator-principals-required",
+        keys: ["durableApproval", "requirePrincipal", "operatorPrincipals"],
+        restartReason: "operator-principals",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:operator-principals-required" },
+        check: ({ next }) => next.durableApproval === true && next.requirePrincipal && next.operatorPrincipals.length === 0
+            ? "DURABLE_APPROVAL + REQUIRE_PRINCIPAL with an EMPTY OPERATOR_PRINCIPALS makes isOperator() true-for-all — every authenticated tenant could read every other tenant's pending-approval queue"
+            : undefined,
+    },
+    {
+        // bake 门是 build-host-RCE 面,空 operator 名单让 isOperator 变 true-for-all = world-writable RCE。
+        // 与上一条同族但**判据不同**(那条判多租户 durable 审批的读面),故各自登记、各自锚。
+        id: "bake-operator-principals",
+        keys: ["imageBakes", "operatorPrincipals"],
+        restartReason: "operator-principals",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:bake-operator-principals" },
+        check: ({ next }) => next.imageBakes.enabled && next.operatorPrincipals.length === 0
+            ? "IMAGE_BAKES_ENABLED with an EMPTY OPERATOR_PRINCIPALS is a world-writable bake door (the runner runs build.sh on the privileged build host)"
+            : undefined,
+    },
+    {
+        id: "sensitive-write-patterns",
+        keys: ["sensitiveWritePatterns"],
+        restartReason: "sensitive-write-patterns",
+        bootAnchor: { file: "src/boot/resolve-spec.ts", marker: "CROSS-INVARIANT:sensitive-write-patterns" },
+        check: ({ next }) => {
+            try {
+                assertGuardPatternsUsable({ sensitiveWritePatterns: next.sensitiveWritePatterns });
+                return undefined;
+            }
+            catch (e) {
+                return e instanceof Error ? e.message : String(e);
+            }
+        },
+    },
+    {
+        id: "leader-host-lane",
+        keys: ["leaderEnabled", "remoteExec"],
+        restartReason: "leader-lane",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:leader-host-lane" },
+        check: ({ next }) => next.leaderEnabled && next.remoteExec?.provider === "host"
+            ? "LEADER_ENABLED with REMOTE_EXEC=host shares ONE absolute workspace across concurrent sub-workers (silent git-state corruption)"
+            : undefined,
+    },
+    {
+        id: "leader-durable-store",
+        keys: ["leaderEnabled", "dbBackend"],
+        restartReason: "leader-lane",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:leader-durable-store" },
+        check: ({ next }) => next.leaderEnabled && next.dbBackend !== "mysql" && next.dbBackend !== "pg"
+            ? `LEADER_ENABLED with DB_BACKEND=${next.dbBackend} (no external SQL store) degrades the leader-run registry to a per-process Map`
+            : undefined,
+    },
+];
+/** 全表校验(**第一条不过即拒**:候选是整批的,报第一个成因足够行动,继续跑其余条目只会淹掉它)。 */
+export function checkCrossInvariants(input) {
+    for (const inv of CONFIG_CROSS_INVARIANTS) {
+        const reason = inv.check(input);
+        if (reason !== undefined)
+            return { ok: false, id: inv.id, reason, restartReason: inv.restartReason };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=config-invariants.js.map

package/dist/config-provider.js

@@ -161,6 +161,14 @@ export class LocalConfigProvider {
                 onWarning: (w) => {
                     if (w.kind === "domain-defaulted")
                         parseWarnings.push({ domain: w.domain, error: w.error instanceof Error ? w.error.message : String(w.error) });
+                    // registry-core 0.19.0 响亮化三 kind(LANDING-7.38 接线件③):dropped/unread=operator 写了但没生效
+                    // (与 defaulted 同级),carried=承运但键表方(stage-limits)才认——都入诊断面,禁静默丢。
+                    else if (w.kind === "unknown-keys-dropped")
+                        parseWarnings.push({ domain: w.domain, error: `unknown keys dropped by domain schema: ${w.keys.join(", ")}` });
+                    else if (w.kind === "unknown-keys-carried")
+                        parseWarnings.push({ domain: w.domain, error: `unknown keys carried to consumer (spelling?): ${w.keys.join(", ")}` });
+                    else if (w.kind === "unread-config-file")
+                        parseWarnings.push({ domain: w.domain ?? "config.d", error: `unread config file ${w.file} (${w.why})` });
                 },
             });
         const { effective: eff, domainErrors } = await store.getEffective({ tolerant: true });
@@ -333,6 +341,9 @@ export function mapToServiceEffective(eff, version) {
             ...(eff.runtime.maxPrincipalCostUsd !== undefined ? { maxPrincipalCostUsd: eff.runtime.maxPrincipalCostUsd } : {}),
             ...(eff.runtime.costQuotaWindowSec !== undefined ? { costQuotaWindowSec: eff.runtime.costQuotaWindowSec } : {}),
         },
+        // #322 批1(registry-core 0.19.0 第 17 域):`limits` 整包透传——本地腿的最后一米在此收口;漏了
+        // 这行,14 键在 local lane 整域消失、继续吃 env 基线(LANDING-7.38 接线件②的事故形)。
+        ...(eff.limits !== undefined ? { limits: eff.limits } : {}),
         // Governance trio (autonomy/commandPolicy/approvalRequire): moved OUT of runtime into the dedicated
         // governance domain (registry-core 0.6, runtime double-write mirror removed in 0.7.1 — buildEffective
         // still READ-lifts legacy raw runtime values into governance, so old on-disk config keeps working).

package/dist/config-types.d.ts

@@ -449,6 +449,15 @@ export interface ServiceConfigFlat {
      *  ⚠️ **不冻进 checkpoint**:resume 的那条腿跟**当前**部署配置走(core 成文)。
      *  运维读面 = `GET /v1/diagnostics/wiring` 的 `memoryPosture.provenance`(`null`=本部署未设)。 */
     memoryProvenance?: "off" | "carry";
+    /** debt #322-B(core 5.48 C18 提货件):委派入口 caps 的部署旋钮 —— env `DELEGATION_MAX_CONCURRENT` /
+     *  `DELEGATION_MAX_PER_SESSION`(整数,numEnvBounded 响亮拒坏值)。**缺席 = 不铸键**(core 自缺省
+     *  CC parity 20/200;`memoryDelegationEvidence` 同姿态);两键各自独立可设,pair 合法性
+     *  (maxConcurrent ≤ maxCumulativePerSession)由 core prepare 的 `config.delegation_entry_caps`
+     *  响亮拒承担,本层不复刻第二判官。部署席 ONLY(TaskSpec 无同名键)。 */
+    delegationEntryCaps?: {
+        maxConcurrent?: number;
+        maxCumulativePerSession?: number;
+    };
     /** 件A 单机形目录:env `MEMORY_ORG_DIRECTORY_JSON` 原文(`Record<principal, Record<org:scope, {write?}>>`)。
      *  config 解析期即整段校验(parseOrgDirectoryStatic,fail-loud);此处存**原文**(config=纯数据,
      *  Map 在装配点重建)。与 config-center 目录腿互斥的裁决在装配点(两者都在=center 腿胜,env 表忽略
@@ -1392,7 +1401,7 @@ export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled"
  *  config 这一层它只是一句声明。 */
 export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "retentionPolicy" | "retentionSweep" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
-export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes" | "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude">;
+export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes" | "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */
 export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "sighupIdleGraceMs" | "parentPid" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
 /** 组:observability(可观测)。 */

package/dist/config.d.ts

@@ -200,6 +200,17 @@ export declare function formatUnmatchableToolNames(source: string, bad: readonly
 /** #270 车2 —— sweep 节律的上界(秒)。`setInterval` 的 delay 是 32 位有符号毫秒(2^31-1);越界会被
  *  Node **重置成 1ms**,理由与拒启判据见调用点。导出供判据与文档单点引用。 */
 export declare const RETENTION_SWEEP_INTERVAL_MAX_SEC: number;
+/** 域:limits+http(限额与 HTTP 面)—— 端口、附件/工作区体积与 TTL、成本与速率天花板、排空窗、回收周期。 */
+/**
+ * #322:limitsHttp 组里**有下限**的三个数值旋钮的下限值 —— env 腿(夹取+点名)与 center 热腿(整批拒)
+ * 共用同一组阈值。判据同源、**处置刻意不同**:env 值是既有部署的存量,夹取不打断服务;center 发布是一次
+ * 显式且可重发的动作,拒绝才是有意义的反馈(#123 响亮拒)。
+ */
+export declare const LIMITS_HTTP_FLOORS: {
+    readonly attachmentMaxBytes: 1024;
+    readonly attachmentUnboundTtlMs: 60000;
+    readonly drainGraceMs: 10000;
+};
 /** 组名 → 该组取景的平铺键(introspection 面:测试用它钉「每个平铺键恰好被一组取景」)。 */
 export declare const CONFIG_GROUP_KEYS: {
     readonly [G in keyof ServiceConfigGroups]: readonly (keyof ServiceConfigFlat)[];

package/dist/config.js

@@ -1639,6 +1639,17 @@ function parseMemoryDomain(ctx) {
         ...(process.env.MEMORY_PROVENANCE !== undefined
             ? { memoryProvenance: enumEnv("MEMORY_PROVENANCE", "carry", ["off", "carry"]) }
             : {}),
+        // debt #322-B(core 5.48 C18):委派入口 caps。两 env 各自独立可设;设了=numEnvBounded 启动期
+        // 响亮拒坏值(#210),缺席=键不铸(core 自缺省 CC parity 20/200,不复制上游缺省)。pair 合法性
+        // (concurrent ≤ cumulative)归 core prepare 的 `config.delegation_entry_caps` 门,单判官不复刻。
+        ...(process.env.DELEGATION_MAX_CONCURRENT !== undefined || process.env.DELEGATION_MAX_PER_SESSION !== undefined
+            ? {
+                delegationEntryCaps: {
+                    ...(process.env.DELEGATION_MAX_CONCURRENT !== undefined ? { maxConcurrent: numEnvBounded("DELEGATION_MAX_CONCURRENT", "20", 1, 10_000) } : {}),
+                    ...(process.env.DELEGATION_MAX_PER_SESSION !== undefined ? { maxCumulativePerSession: numEnvBounded("DELEGATION_MAX_PER_SESSION", "200", 1, 100_000) } : {}),
+                },
+            }
+            : {}),
         ...(memoryOrgDirectoryJson !== undefined ? { memoryOrgDirectoryJson } : {}),
         memoryOrgGrantTtlMs,
         memoryOrgUnavailableBackoffMs,
@@ -2090,6 +2101,16 @@ function parseOrchestrationDomain(ctx) {
     };
 }
 /** 域:limits+http(限额与 HTTP 面)—— 端口、附件/工作区体积与 TTL、成本与速率天花板、排空窗、回收周期。 */
+/**
+ * #322:limitsHttp 组里**有下限**的三个数值旋钮的下限值 —— env 腿(夹取+点名)与 center 热腿(整批拒)
+ * 共用同一组阈值。判据同源、**处置刻意不同**:env 值是既有部署的存量,夹取不打断服务;center 发布是一次
+ * 显式且可重发的动作,拒绝才是有意义的反馈(#123 响亮拒)。
+ */
+export const LIMITS_HTTP_FLOORS = {
+    attachmentMaxBytes: 1024,
+    attachmentUnboundTtlMs: 60_000,
+    drainGraceMs: 10_000,
+};
 function parseLimitsHttpDomain() {
     return {
         // #210 A 档:裸 Number ⇒ NaN 直进 `server.listen(NaN)`(Node 当成 0 = 随机端口),于是服务起来了、
@@ -2115,11 +2136,11 @@ function parseLimitsHttpDomain() {
         })(process.env.ATTACHMENT_ORPHAN_GRACE_MS),
         // workspace 浏览面(#3,[1894]①)单文件读上限。
         workspaceFileMaxBytes: optFinitePositiveEnv("WORKSPACE_FILE_MAX_BYTES") ?? 8 * 1024 * 1024,
-        attachmentMaxBytes: clampEnvWithWarn("ATTACHMENT_MAX_BYTES", String(32 * 1024 * 1024), 1024), // #210 B 档
+        attachmentMaxBytes: clampEnvWithWarn("ATTACHMENT_MAX_BYTES", String(32 * 1024 * 1024), LIMITS_HTTP_FLOORS.attachmentMaxBytes), // #210 B 档
         ...(process.env.ATTACHMENT_MIME_ALLOWLIST
             ? { attachmentMimeAllowlist: process.env.ATTACHMENT_MIME_ALLOWLIST.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean) }
             : {}),
-        attachmentUnboundTtlMs: clampEnvWithWarn("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000), 60_000), // #210 B 档
+        attachmentUnboundTtlMs: clampEnvWithWarn("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000), LIMITS_HTTP_FLOORS.attachmentUnboundTtlMs), // #210 B 档
         infraCostRates: {
             // #210 B 档:负单价夹到 0 是对的(负成本会让账面倒扣),但夹取必须点名——不然 operator 只看到
             // 基建成本恒 0,查不到是自己那个负号被吃掉了。
@@ -2135,7 +2156,7 @@ function parseLimitsHttpDomain() {
                 return v;
             })(),
         },
-        drainGraceMs: clampEnvWithWarn("DRAIN_GRACE_MS", String(10 * 60 * 1000), 10_000), // SIGTERM drain window, default 10min, floor 10s(#210 B 档:把 600 当成"秒"填进来的手滑最常见,夹取后必须点名)
+        drainGraceMs: clampEnvWithWarn("DRAIN_GRACE_MS", String(10 * 60 * 1000), LIMITS_HTTP_FLOORS.drainGraceMs), // SIGTERM drain window, default 10min, floor 10s(#210 B 档:把 600 当成"秒"填进来的手滑最常见,夹取后必须点名)
         sighupIdleGraceMs: clampEnvWithWarn("SIGHUP_IDLE_GRACE_MS", String(120_000), 5_000), // B3: SIGHUP idle-shutdown window, default 2min, floor 5s
         ...parentPidEnv(), // #219:壳 pid 存活监视,缺席 ⇒ 键缺席 ⇒ 整件不装配
         // BL-9: numEnv (not bare Number) — a non-numeric typo FAILS at startup instead of becoming NaN, which would
@@ -2375,7 +2396,7 @@ const ORCHESTRATION_GROUP_KEYS = [
     "schedulerEnabled", "schedulerSessionWakeup", "schedulerSessionLifetime", "schedulerStorePath", "planModeEnabled", "workflowRunStoreBackend",
     "workflowOrphanGraceMs", "workflowJournalRetentionMs", "workflowRunRetentionMs", "usageWindows", "workflowAgentsReadOnly",
     "workflowSizeGuideline", "backgroundAgentRetentionMs", "backgroundAgentStaleRunningMs",
-    "backgroundAgentParkClaimStaleMs", "rosterRetentionMs", "leaderRunStaleMs", "scratchpadSweepTtlMs", "sandboxPkgSource",
+    "backgroundAgentParkClaimStaleMs", "delegationEntryCaps", "rosterRetentionMs", "leaderRunStaleMs", "scratchpadSweepTtlMs", "sandboxPkgSource",
     "sessionAutoTitle", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspEnabled", "lspHostEnabled",
     "imageBakes", "readFace", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude",
 ];
@@ -2482,8 +2503,12 @@ export function loadConfig() {
     const limitsHttp = parseLimitsHttpDomain();
     const observability = parseObservabilityDomain();
     const integrations = parseIntegrationsDomain();
-    // ── 跨域耦合与跨域不变量:两条门(D-G 直连门、bake 门)的判据各自横跨 approval/auth/orchestration 三域,
+    // ── CROSS-INVARIANT-REGION:begin ────────────────────────────────────────────────────────────────
+    // 跨域耦合与跨域不变量:两条门(D-G 直连门、bake 门)的判据各自横跨 approval/auth/orchestration 三域,
     //    任何单域都不足以裁定,故留在装配层(旧名保留,断言与消息逐字不变)。
+    // 🔴 #322:本区内的每一条拒启 throw 必须挂 `CROSS-INVARIANT:<id>` 锚,且 id 在
+    //    `src/config-invariants.ts` 的 CONFIG_CROSS_INVARIANTS 表内 —— 配置改热之后,一条**只活在 boot**
+    //    的不变量就是热路径上的静默漏检。机械门:test/config-hot/batch1-cross-invariants.test.ts(双向)。
     const { directApprovalDoor, durableApproval: dgDurable, approvalHmacKeys: dgHmacKeys } = approval;
     const { principalJwtPubkeys, principalJwtIss, principalJwtAud, operatorPrincipals: dgOperators, authTokens } = auth;
     const { enabled: imageBakesEnabled, runnerPrincipal: bakeRunnerPrincipal } = orchestration.imageBakes;
@@ -2513,6 +2538,7 @@ export function loadConfig() {
         if (!requirePrincipal)
             missing.push("REQUIRE_PRINCIPAL=true (a direct door is multi-tenant; without it an absent principal is anonymous and the spoofable header governs owner/quota checks)");
         if (missing.length) {
+            // CROSS-INVARIANT:direct-door-anchors
             throw new Error(`DIRECT_APPROVAL_DOOR=true but D-G anchors are missing: ${missing.join(", ")} — refusing to start a half-open direct door (design/80 D-G boot invariant)`);
         }
     }
@@ -2526,12 +2552,14 @@ export function loadConfig() {
     // single-tenant legacy semantic (REQUIRE_PRINCIPAL unset — the shared service token IS the operator boundary)
     // is deliberately preserved: only the multi-tenant form is a hole. Refuse to start it.
     if (dgDurable && requirePrincipal && dgOperators.length === 0) {
+        // CROSS-INVARIANT:operator-principals-required
         throw new Error("DURABLE_APPROVAL=true + REQUIRE_PRINCIPAL=true but OPERATOR_PRINCIPALS is empty — on a multi-tenant worker the empty operator set makes isOperator() true-for-all, so every authenticated tenant could read every other tenant's pending-approval queue (GET /v1/approvals & siblings). Set OPERATOR_PRINCIPALS, or unset REQUIRE_PRINCIPAL if this is a single-tenant deployment (#157-① boot invariant)");
     }
     // 🔴 boot invariant (IMAGE-API-DESIGN.md §P2.4a): the bake door is build-host-RCE-capable, and isOperator([],p)
     // is true-for-all — so enabling bakes with an empty OPERATOR_PRINCIPALS = a WORLD-WRITABLE RCE door. Refuse to
     // start (never a half-open bake door). The explicit-operator gate in server.ts is the runtime twin of this.
     if (imageBakesEnabled && dgOperators.length === 0) {
+        // CROSS-INVARIANT:bake-operator-principals
         throw new Error("IMAGE_BAKES_ENABLED=true but OPERATOR_PRINCIPALS is empty — the bake door runs build.sh on the privileged build host; an empty operator set makes isOperator() true-for-all (world-writable RCE). Set OPERATOR_PRINCIPALS or disable bakes (IMAGE-API-DESIGN.md §P2.4a boot invariant)");
     }
     // 🔴 boot invariant (IMAGE-API-DESIGN.md §P2.12 / H1): the bake-runner identity is DERIVED from its bearer
@@ -2539,6 +2567,7 @@ export function loadConfig() {
     // system == BAKE_RUNNER_PRINCIPAL MUST exist, else the runner can never satisfy isRunner and the entire
     // claim/ingest/heartbeat pipeline is silently dead. Refuse to start a bake door with no runner credential.
     if (imageBakesEnabled && !Object.values(authTokens).includes(bakeRunnerPrincipal)) {
+        // CROSS-INVARIANT:bake-runner-credential
         throw new Error(`IMAGE_BAKES_ENABLED=true but no SERVICE_AUTH_TOKENS entry maps to the runner principal '${bakeRunnerPrincipal}' — the bake-runner authenticates by its credential (token-derived source), so a '<BAKE_RUNNER_TOKEN>=${bakeRunnerPrincipal}' SERVICE_AUTH_TOKENS entry is required or claim/ingest/heartbeat all 403 (IMAGE-API-DESIGN.md §P2.12 boot invariant)`);
     }
     // 🔴 boot invariant #193 车4 件2(台账 P1-10 / docs/DESIGN-193-CAR4-leader-failclosed.md 件2):leader
@@ -2552,6 +2581,7 @@ export function loadConfig() {
     // 竞态写 git 状态:不是报错,是**静默数据损坏**。真修(provisionWorker 给每个 worker 传唯一 workspace)
     // 不在本车;门先行,消灭「启用即损坏」的窗口。
     if (orchestration.leaderEnabled && orchestration.remoteExec?.provider === "host") {
+        // CROSS-INVARIANT:leader-host-lane
         throw new Error("LEADER_ENABLED=true + REMOTE_EXEC=host is refused: the leader wire pins ONE absolute workspace path " +
             "(LEADER_WORKSPACE / the /home/user default) for every sub-worker, while the host adapter gives each env a " +
             "DIFFERENT random directory — so N concurrent host workers would share one physical git worktree and " +
@@ -2564,12 +2594,14 @@ export function loadConfig() {
     // 「多副本」这件事在 config 层判不了(副本数不是本进程的知识),可判的**代理**就是 durable 前提本身:
     // 一个没有外部 SQL 店的部署,与 leader run(N worker、最长 24h、真 push)的语义结构性不相容。
     if (orchestration.leaderEnabled && store.dbBackend !== "mysql" && store.dbBackend !== "pg") {
+        // CROSS-INVARIANT:leader-durable-store
         throw new Error(`LEADER_ENABLED=true but DB_BACKEND=${store.dbBackend} (no external SQL store) is refused: a leader run is an ` +
             "N-worker fan-out lasting up to 24h that ends in a REAL git push, and without a durable store its registry is " +
             "a per-process Map — a cross-replica GET 404s, a restart forgets the run, and a retried POST starts a SECOND " +
             "push. Point the service at a durable store (DB_BACKEND=mysql|pg), or turn the leader off (unset LEADER_ENABLED) " +
             "(#193 车4 件2 / staleness ledger P1-9+P1-10 boot invariant)");
     }
+    // ── CROSS-INVARIANT-REGION:end ──────────────────────────────────────────────────────────────────
     // #157 F 类观测:执行车道落点记账放在这里 —— 九域解析与上面全部跨域不变量都过了之后,即「这一轮
     // 确实启得起来」才成立的位置(写在 REMOTE_EXEC 解析途中的话,后置拒启会留下一条没启起来的落点)。
     EXEC_LANE_NOTICE = buildExecLaneNotice(orchestration.remoteExec);

package/dist/http/routes/admin-config-refresh.d.ts

@@ -0,0 +1,20 @@
+/**
+ * #322 批1 追加件(clay 当场裁定,design/322 批1 行):`POST /v1/admin/config/refresh` —— operator 改完
+ * 配置**不等 60s tick**,手动触发一次立即拉取。
+ *
+ * 族属 = `POST /v1/admin/drain` 逐字同族(operator lane:同一条 `explicitOperatorOk` 门、billable=false、
+ * 刻意不吃 drain / roster-pending 两道 503 —— 运维在停机窗里也要打得通自己的口)。门序照那边:
+ * 身份 → 授权 →(本口无 body,无验型步)。
+ *
+ * 🔴 语义 = **触发一次既有的 refresh 拍**,不是「再实现一遍拉取」:实现面是
+ * `configCenter.refreshNow()`,它与 60s cadence 共用同一只 join 形拍(在飞则 join,绝不并发双拍)。
+ * 回执里的两个世代号取自**同一本**世代账(`/health` 的三键同源)—— 两面各算一次迟早会各说各话。
+ *
+ * 🔴 没有配置管道(纯 env 形)⇒ 诚实 409 指路,**不吞成 200**:一个「triggered:true 但什么都没发生」的
+ * 回执会让运维以为配置已经拉过了,那比拒绝糟得多。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare const ADMIN_CONFIG_REFRESH_PATH = "/v1/admin/config/refresh";
+export declare function handleAdminConfigRefresh(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=admin-config-refresh.d.ts.map

package/dist/http/routes/admin-config-refresh.js

@@ -0,0 +1,43 @@
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export const ADMIN_CONFIG_REFRESH_PATH = "/v1/admin/config/refresh";
+const OPERATOR_ONLY_MESSAGE = "config refresh is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable this endpoint)";
+export async function handleAdminConfigRefresh(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleAdminConfigRefreshBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleAdminConfigRefreshBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const path = url.split("?")[0] ?? url;
+    if (req.method !== "POST" || path !== ADMIN_CONFIG_REFRESH_PATH) {
+        miss.fell = true;
+        return;
+    }
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && !principal) {
+        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        return;
+    }
+    if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+        sendError(res, 403, "auth.operator_only", OPERATOR_ONLY_MESSAGE);
+        return;
+    }
+    const trigger = deps.configRefreshNow;
+    const outcome = trigger ? await trigger() : "not-wired";
+    if (outcome === "failed") {
+        // 🔴 codex R2-F3:定时拍吞掉异常是为了保住循环,但**按下刷新的那个人**必须知道这一拍真的失败了
+        // ——「中心超时」与「已刷新」在回执上不可分辨,正是这个口存在的反面。502:失败在依赖侧(配置源)。
+        sendError(res, 502, "internal.config_refresh_failed", "the config refresh tick failed (source unreachable / unreadable / apply error) — the live config is unchanged; see the worker's sema_registry_refresh_failed log line for the cause");
+        return;
+    }
+    if (outcome === "not-wired") {
+        sendError(res, 409, "config.refresh_unavailable", "this deployment has no config pipeline to refresh — set CONFIG_CENTER (remote control plane) or CONFIG_PROVIDER=local (config.d on disk); an env-only worker has nothing to pull");
+        return;
+    }
+    // 世代号取自世代账(与 /health 的 configTargetVersion/configAppliedVersion 同一份读数)。账缺席只发生在
+    // 「触发口在场但世代账没接线」的夹具形 —— 诚实报 0(不编一个看起来像真答案的数)。
+    const gen = deps.configApplyState?.();
+    sendJson(res, 200, { triggered: true, targetVersion: gen?.configTargetVersion ?? 0, appliedVersion: gen?.configAppliedVersion ?? 0 });
+}
+//# sourceMappingURL=admin-config-refresh.js.map

package/dist/http/routes/diagnostics.js

@@ -162,6 +162,10 @@ async function handleDiagnosticsBody(req, res, url, ctx, miss) {
             // 同受众(operator-only,门在上方,本段不自带更松的门)。
             // 缺席 ⇒ 显式 `null`(「这个进程说不出来」),不铸一个看起来像真答案的空壳对象。
             memoryPosture: deps.memoryPosture ?? null,
+            // #322 世代账的 operator 面:按组的 appliedVersion / deferredKeys+铸因 / lastRejected(消毒形——
+            // 只有键名与判据文案,值从不进读面)。/health 那三键是同一份读数的窄投影,两面不可能各说各话。
+            // 缺席 ⇒ 显式 `null`(与 memoryPosture 同姿势:「这个进程说不出来」,不铸空壳)。
+            configApply: deps.configApplyState?.() ?? null,
             serverGates: buildServerWiringGates({
                 toolApprovalEnabled: deps.toolApproval !== undefined,
                 streamApprovalEnabled: deps.config.streamApproval?.enabled === true,

package/dist/http/routes/runs.js

@@ -1396,19 +1396,23 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         // [1596]/[1600] core 1.397 三分:仲裁器**抛错**(店不可达)此前被误吞成 park_resume_won 的假话——
         // 「输给了并发 resume」与「根本问不到仲裁结果」是两种不同的行动建议(前者重查状态,后者原样重试
         // stop),新码 `park_arbiter_unreachable` 让二者不再共用一个 errorCode。
-        const parkArbiterUnreachable = details?.error === "park_arbiter_unreachable";
-        const parkResumeWon = details?.error === "park_resume_won";
-        const stillParked = details?.error === "parked_pending_approval" || details?.status === "parked";
+        // [4797](core 5.50)details.code 孪生对表:stop 族座位今天仍只铸 `error`(族扫未及,已上板点名),
+        // 但 core 契约方向是「code wins when both present」且未承诺新失败座位必带 error ⇒ 判类读
+        // code-优先-error-回落、在场判据双键取并,未来只铸 code 的失败座位不会漏判成 200 成功。
+        const stopCode = typeof details?.code === "string" ? details.code : details?.error;
+        const parkArbiterUnreachable = stopCode === "park_arbiter_unreachable";
+        const parkResumeWon = stopCode === "park_resume_won";
+        const stillParked = stopCode === "parked_pending_approval" || details?.status === "parked";
         // v3.1 批2(统检第二波 high):判别方向翻转——旧形是 (status,error) 的**失败白名单**(status==="running"
         // || 三个具名码),core 新增失败码且行状态不在 {running,parked} 时整个分支被跳过落 200,与上面注释自陈
         // 的不变量(kill 没落地绝不读成功)正相悖(B5 联合非穷尽的 default-放行形;not_local/park 族/arbiter
         // 三次历史新增全靠人追认)。新形:stop 动词的 error **在场即失败**(not_found 已在上方早退),具名臂
         // 保留各自 errorCode,未知码落 stop.not_landed 兜底 409——新失败码默认可见,不默认成功。
-        if (stopVerb && details?.error !== undefined) {
+        if (stopVerb && (details?.error !== undefined || details?.code !== undefined)) {
             // 1.250:durable 回落臂(core stopTask agentStore 分支)对他实例 running 行应答 error="not_local"
             // (没有 kill 被尝试)——与「kill 尝试了没落地」(stop.not_landed)是不同的失败形,各给各的
             // errorCode(同 409 家族,additive)。
-            const notLocal = details.error === "not_local";
+            const notLocal = stopCode === "not_local";
             sendError(res, 409, notLocal
                 ? "stop.not_local"
                 : parkArbiterUnreachable
@@ -1425,7 +1429,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                         ? "the pending tool-approval was resolved (resumed) concurrently with this stop attempt — the resume won the race, so nothing was stopped; re-check the task's current status"
                         : stillParked
                             ? "this task is durably parked awaiting a tool-approval decision, not actively running — there is no live process to interrupt; resolve (or let expire) the pending approval instead"
-                            : `stop did not land (${details.error}) — the process may still be running`, { taskId: runId, target, content: out.content, output: out.details });
+                            : `stop did not land (${stopCode}) — the process may still be running`, { taskId: runId, target, content: out.content, output: out.details });
             return;
         }
         // Registry projection passed through verbatim (status/retrieval_status/cursor flags); `content` is

package/dist/http/server.d.ts

@@ -455,6 +455,14 @@ export interface ServiceDeploymentDeps {
      *  auto rolling-restart the worker. Change-detected (not presence) — absent when nothing baked-at-boot
      *  changed, so polling it never causes a restart loop. */
     restartState?: () => RestartSignal | undefined;
+    /** #322 世代账(design/322 §2):本副本的配置收敛状态 —— `/health` 取三键
+     *  (configTargetVersion / configAppliedVersion / configApplyStaleMs),`GET /v1/diagnostics/wiring` 取整份
+     *  (按组的 appliedVersion / deferredKeys+铸因 / lastRejected 消毒形)。缺席 = 这个进程没有配置管道
+     *  (纯 env 部署 / 测试夹具)⇒ 两个面的形状逐字不变(additive)。 */
+    configApplyState?: () => import("../config-center/apply-ledger.js").ConfigApplyLedgerView | undefined;
+    /** #322 追加件:`POST /v1/admin/config/refresh` 的实现面 —— 触发**一次既有**的 refresh 拍(在飞则 join)。
+     *  缺席 / 回 `"not-wired"` = 本部署没有配置管道 ⇒ 该口诚实 4xx(绝不吞成 200)。 */
+    configRefreshNow?: () => Promise<"triggered" | "not-wired" | "failed">;
     /** codex R18 (models-tiers deferral): the persistent "deferred WITHOUT a next-boot handoff" state — set when a
      *  changed model plane could not hot-apply (tier-frozen Runner / tiered candidate) AND no restart-surviving LKG
      *  exists to justify forcing a restart. Surfaced on /health (`modelPlaneDeferred`) so the stuck-degraded state

package/dist/http/server.js

@@ -44,6 +44,7 @@ import { handleDiagnostics } from "./routes/diagnostics.js";
 import { handleAdoption } from "./routes/adoption.js";
 import { handleRetention } from "./routes/retention-ops.js";
 import { handleAdminDrain } from "./routes/admin-drain.js";
+import { handleAdminConfigRefresh } from "./routes/admin-config-refresh.js"; // #322 批1 追加件:配置手动刷新口(operator lane)
 import { handleMemoryPolicy } from "./routes/memory-policy.js";
 import { handleMemoryBundle } from "./routes/memory-bundle.js";
 import { handleSharedMemory } from "./routes/shared-memory.js";
@@ -218,6 +219,7 @@ const ROUTE_DOMAINS = [
     handleAdoption,
     handleRetention,
     handleAdminDrain,
+    handleAdminConfigRefresh,
     handleMemoryPolicy,
     handleMemoryBundle,
     handleRules,
@@ -494,6 +496,23 @@ export function createHttpServer(rawDeps) {
                     const stuck = deps.planeDeferredState?.();
                     return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
                 })(),
+                // #322 世代账三键(additive;未接线 ⇒ 键全缺席,/health 形状逐字不变)。
+                // 语义:target = 本副本**最后**见到的源版本(身份标);applied = 最后一次真的 commit 的版本;
+                // staleMs = 两者**持续**不等的时长(收敛即缺席)。#325 起 additive 补两 ordinal 键(收货序数,
+                // 进程内单调)——local 腿 version 是内容哈希无序承诺,「见过多少代/停在哪一代」的推进判断
+                // 用 ordinal 键;跨副本「同不同代」的对账仍用 version 身份标。
+                ...(() => {
+                    const gen = deps.configApplyState?.();
+                    if (!gen)
+                        return {};
+                    return {
+                        configTargetVersion: gen.configTargetVersion,
+                        configAppliedVersion: gen.configAppliedVersion,
+                        configTargetOrdinal: gen.configTargetOrdinal,
+                        configAppliedOrdinal: gen.configAppliedOrdinal,
+                        ...(gen.configApplyStaleMs !== undefined ? { configApplyStaleMs: gen.configApplyStaleMs } : {}),
+                    };
+                })(),
                 // B1 活体 store 探测(座注见 storeLiveState 声明;钉 test/health-store-live.test.ts)
                 ...(() => {
                     const probe = deps.storeLiveState?.();
@@ -717,6 +736,10 @@ export function createHttpServer(rawDeps) {
         // 同族(operator 门、billable=false、不吃 drain 503——它正是 drain 前要调的口),位置跟着 retention。
         if (await handleAdminDrain(req, res, url, ctx))
             return;
+        // #322 批1 追加件:配置手动刷新口(routes/admin-config-refresh.ts,operator lane;POST
+        // /v1/admin/config/refresh)。与 drain 同族同门同 billable 姿势,位置紧跟它。
+        if (await handleAdminConfigRefresh(req, res, url, ctx))
+            return;
         // design/158 A9:memory 导出/同步 + /v1/policy 只读面(routes/memory-policy.ts)。
         if (await handleMemoryPolicy(req, res, url, ctx))
             return;
@@ -3496,6 +3519,9 @@ const ROUTE_LABEL_LITERALS = new Set([
     "/v1/adoption",
     // #291:停机因由声明口(operator-only,drain 前一次性动作)。同 adoption 判:低频但只在停机现场被打。
     "/v1/admin/drain",
+    // #322 批1 追加件:配置手动刷新口(operator-only)。同判:低频,但它的 duration 与失败率正是「这次
+    // 配置到底拉没拉下来」的第一手信号,落进 other 桶就看不见了。同族纪律:写**字面量**不引常量。
+    "/v1/admin/config/refresh",
     // #154 车二:CC settings 导入两口。字面量(无 id 段)⇒ 进 LITERALS 表而不是模式表。
     // 🔴 写**字面量**而不是引 `RULES_CC_IMPORT_*_PATH` 常量:名册门与 billable 申明门都是**扫源码文本**
     // 的(它们正则抓本表里的双引号词),引常量会让两条新路由对两道门隐形 —— 那不是「过了门」,是绕过门。