@sema-agent/server 7.120.0 → 7.122.0

package/dist/config-types.d.ts

@@ -121,6 +121,16 @@ export declare const DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS: {
     readonly maxMs: 10000;
 };
 export declare const DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS = 250;
+/**
+ * 本仓读一个租户 scope 的**唯一**读法:给了就是它,缺席 = settings-schema 的缺省 scope(`GLOBAL_SCOPE`;缺省值只在契约包里写一处)。
+ * 引擎自己的 scope(`config.ts` 解析 env `FLEET_SCOPE`)与排空请求的 `scope`(`fleet/drain-entry.ts`)走同一只 —— 两侧缺席的读法不会分家。
+ * 住在本叶(而不在 `fleet/drain-entry.ts`):`config.ts` 读它,而 drain-entry 值引 `plugins/store-contracts.ts`,config 不值引 plugins 层。
+ */
+export declare function fleetScopeOf(raw: string | undefined): string;
+/** 中心基址三席(`SEMA_REGISTRY_URL` / `SEMA_REGISTRY_LIVE_URL` / `SEMA_REGISTRY_WEB_URL`)与公告地址的形句 —— 判官 `config-center/center-request.ts` `pathBaseUrlRefusal` 一只(形判 = `url-shape.ts`),配置目录四行同读这一句。 */
+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;
 /**
  * S-753(core 7.33.0 #1121)—— `MODEL_FIRST_BYTE_TIMEOUT_MS`(→ core `BrainTimeoutConfig.firstByteTimeoutMs`,`fetch()` → 响应头
  * 的等待)的**合法域**,闭区间、整数 ms。解析器(`config.ts`)与目录行(`config-catalog.ts`)共读这一处。
@@ -1469,8 +1479,9 @@ export interface ServiceConfigFlat {
      *  `TaskSpec.enablePlanMode:true` but NOT `handsReadOnly` (writable-start) → core auto-mounts `enter_plan_mode`
      *  (+ `present_plan`) so the model can self-call `enter_plan_mode` at ANY time it judges a task needs planning
      *  (CC EnterPlanMode parity). 🆕 DEFAULT ON (clay: model-driven plan is resident — the model decides when to plan);
-     *  set `PLAN_MODE_ENABLED=false` to opt out. USER-driven plan (`body.permissionMode=plan` → enablePlanMode +
-     *  handsReadOnly, read-only from start) is unaffected/independent. */
+     *  set `PLAN_MODE_ENABLED=false` to opt out. A USER-driven plan (`body.permissionMode=plan`, bundle `defaultMode`, or
+     *  `AUTONOMY=plan`) is the same engine mode word, independent of this knob: the engine's mode table mounts the plan
+     *  tools for a declared `plan` itself, and no plan entry clamps the hands (only `AUTONOMY=read-only` does). */
     planModeEnabled: boolean;
     /**
      * [ref]⑥(core 5.56 `Hooks.timeoutMs` 座)—— **每一只 hook 席位单次调用的时间上限**(ms)。
@@ -2001,6 +2012,9 @@ export interface ServiceConfigFlat {
     /** LKG 落盘路径的覆写(`CONFIG_LKG_PATH`,绝对路径;单一读法 `config-lkg.ts` `lkgPathOverrideOf`)。缺席 = LKG 落在配置根下按箱派生。
      *  读者:LKG 的落盘 / 读回(`boot/config-center.ts`)与读拒行(部署姿态座席族 —— LKG 在哪,读拒就守哪,`lkgReadDenyRows`)。 */
     configLkgPath?: string;
+    /** 远程配置的 LKG(last-known-good)盘缓存读写开关(`CONFIG_LKG_ENABLED`,缺省开;只对远程 provider 有意义)。单一读法:`loadConfig` 铸这一席
+     *  (同时登记极性行),`boot/config-center.ts` 的两个读点(boot 的 LKG 来源判定、skill 正文缓存目录)只读它 —— 起服之后改环境变量不影响。 */
+    configLkgEnabled: boolean;
     /** Structured log level. */
     logLevel: "debug" | "info" | "warn" | "error";
     /** Per-principal request cap per minute on task/run endpoints. 0 disables. */
@@ -2090,9 +2104,15 @@ export interface ServiceConfigFlat {
      *  `credential`(S-651,BREAKING:取代 7.98.0 及以前的 `token: string` 启动快照):凭证来源活对象
      *  (`center-credential.ts`),每条出站请求经它取一次值 —— `SEMA_REGISTRY_TOKEN`(值)或
      *  `SEMA_REGISTRY_TOKEN_FILE`(每次读文件,轮换 / 换账号不重启)二选一(两键名与判官的属主 = settings-schema
-     *  `CENTER_CREDENTIAL_ENV` / `judgeCenterCredentialDeclaration`,S-742)。 */
+     *  `CENTER_CREDENTIAL_ENV` / `judgeCenterCredentialDeclaration`,S-742)。
+     *  `liveBaseUrl`(编排器片 2,env `SEMA_REGISTRY_LIVE_URL`):fleet 活性组(心跳 / 注销、服务租约 —— settings-schema `FLEET_LIVE_PATHS`)的基址,
+     *  给「管理面在就绪门后、活性面另走一条不看就绪的入口」的部署;缺席 ⇒ 活性组也打 `baseUrl`(这条缺省只在 `centerFetch` 读)。
+     *  `webBaseUrl`(7.121.0,env `SEMA_REGISTRY_WEB_URL`):这个中心的 **web 面固定基址**,运维声明、引擎原样转述到 `/health.center.webBaseUrl`
+     *  (壳按它拼会话深链;路径怎么拼归壳)。起服时判成「可拼路径的基址」:http(s)、不带凭据 / query / fragment,否则拒启;缺席即缺席,引擎不拼不猜。 */
     configCenter?: {
         baseUrl: string;
+        liveBaseUrl?: string;
+        webBaseUrl?: string;
         credential: CenterCredentialSource;
         dryRun: boolean;
         worker?: string;
@@ -2103,6 +2123,25 @@ export interface ServiceConfigFlat {
      *  显式值压过派生(部署级旋钮无条件,与 `READ_FACE` 缺省按 posture 派生 S-167 同形)。只在装了租约管理器的部署上有意义
      *  (`lease:"absent"` 的部署不参与);生效值上 caps `centerWiring.failMode`。 */
     fleetLeaseFailClosed: boolean;
+    /** 编排器片 2:fleet 成员的**代际**(env `FLEET_GENERATION`,settings-schema `FLEET_GENERATION_ENV`;配置渲染器是唯一写手)。
+     *  缺席 ⇔ 非 fleet 成员(单机形:不续服务租约、不受围栏)。在场则必须是规范十进制串(`"0"`、`"7"`;不许前导零 / 符号 / 空白 / 空串),
+     *  否则拒启 —— 「设了但读不成代际」是渲染器或手配的事故,不是「非成员」。引擎把它原样回声到心跳与 `/health`(`generation`)。 */
+    fleetGeneration?: string;
+    /** 编排器片 2:本引擎所在的**租户 scope**(env `FLEET_SCOPE`,配置渲染器写)。`loadConfig` 解析一次:缺席 ⇒ 缺省 scope(settings-schema
+     *  `GLOBAL_SCOPE`,经本文件的 `fleetScopeOf` —— 本仓唯一读法);在场必须是 settings-schema `ScopeId` 形,否则拒启。
+     *  唯一读者 = 排空口 `POST /v1/admin/drain` 的身份比对;续租体与心跳不带它(那两处的 scope 由中心凭证绑定)。 */
+    fleetScope: string;
+    /** `FLEET_ADVERTISE_ADDRESS`:本实例对中心公告的可达地址(运维声明;k8s pod IP / docker alias / 127.0.0.1:port 只有部署环境自己知道)。
+     *  `loadConfig` **无条件**解析一次:未设 / 空串 ⇒ 缺席(公告环不装);在场必须是可解析的 http(s) URL,否则拒启。读者:fleet 公告环、
+     *  围栏判官 `fleetFenceLaneOf`、`/health.center.sessionsVisible`、启动日志 —— 都读这一席,不读 env。 */
+    fleetAdvertiseAddress?: string;
+    /** 编排器片 2:一台实例「活着而不服务」的最长时长 `T_max`(ms;env `FLEET_LEASE_OUTAGE_MAX_MS`)。缺省 86 400 000(24 h);地板 = 服务租约
+     *  TTL 地板(settings-schema `SERVING_LEASE_TTL_FLOOR_MS`,60 s);不许 0 / 无穷,坏值拒启。`loadConfig` 无条件解析(成员与非成员同读)。两个读者:
+     *  ① 服务租约**中心不可达的容忍上限**(`fleet/serving-lease.ts`;只在 fleet 成员 ∧ 中心宣告了 `servingLease` 能力位时生效):租约过期(中心
+     *  不可达 / 答 unknown)之后照常服务,直到过期满这么久 ⇒ 新计费提交 503 `state.lease_expired`(取消 / HITL 应答 / 续跑 / 读面照放行),在飞不动、
+     *  不自停;中心恢复授予即恢复。② 排空口 `POST /v1/admin/drain` 的**期限准入上界**(`fleet/drain-entry.ts` 规则 2):`deadlineAt` 离此刻超过它 ⇒
+     *  400 `request.field_invalid`。 */
+    fleetLeaseOutageMaxMs: number;
     /** S-698(design-325 §2):中心凭证**续签提前量**(ms)—— `SEMA_REGISTRY_TOKEN_FILE` 指向人的登录会话信封
      *  (`kind:"user-session"`)时,访问令牌离到期 ≤ 本值即由引擎续签并原子改写同一文件(`center-credential-renewer.ts`)。
      *  缺省 5 min;`0` = 关续签、只读信封(壳负责续);其余必须是整数毫秒且落在 `CENTER_CREDENTIAL_RENEW_LEAD_MIN_MS`(一次续签请求的
@@ -2134,13 +2173,13 @@ export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled"
  *  config 这一层它只是一句声明。 */
 export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "configCatalogEnabled" | "retentionPolicy" | "retentionSweep" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "authBridgeIssuer" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
-export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "remoteExecHomeDir" | "requireExecutionLane" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "hooksTimeoutMs" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "sessionAutoTitleSource" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "lspEnvAllow" | "imageBakes" | "readFace" | "readFaceSource" | "taskWriteFaceEscalation" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "agentConfigDir" | "configLkgPath">;
+export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "remoteExecHomeDir" | "requireExecutionLane" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "hooksTimeoutMs" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "sessionAutoTitleSource" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "lspEnvAllow" | "imageBakes" | "readFace" | "readFaceSource" | "taskWriteFaceEscalation" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "agentConfigDir" | "configLkgPath" | "configLkgEnabled">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */
 export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "drainSecondSignalMinGapMs" | "sighupIdleGraceMs" | "parentPid" | "engineAutoExit" | "engineLingerMs" | "engineOrphanLingerMs" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
 /** 组:observability(可观测)。 */
 export type ServiceObservabilityConfig = Pick<ServiceConfigFlat, "metricsToken" | "traceToken" | "toolTrace" | "traceThinking" | "logLevel" | "otel">;
 /** 组:integrations(外部集成)。`mcpServers` / `a2aPeers` 由 sema-registry 适配器填(无 env 腿),归本组。 */
-export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "a2aPeers" | "a2aServe" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "centerCredentialRenewLeadMs" | "configCenter" | "fleetLeaseFailClosed" | "configProvider" | "configLocalDir">;
+export type ServiceIntegrationsConfig = Pick<ServiceConfigFlat, "pluginsAllowHosts" | "mcpServers" | "a2aPeers" | "a2aServe" | "configBootFetchBudgetMs" | "gitApiBaseUrl" | "gitApiToken" | "gitApiKind" | "defaultScenario" | "skillsDir" | "centerCredentialRenewLeadMs" | "configCenter" | "fleetLeaseFailClosed" | "fleetGeneration" | "fleetScope" | "fleetAdvertiseAddress" | "fleetLeaseOutageMaxMs" | "configProvider" | "configLocalDir">;
 /** 九个组槽。每组恒在场(`loadConfig` / `attachConfigGroups` 装好才交出配置),故不可选——新代码写
  *  `config.modelPlane.model` 不需要 `?.`(可选组会把 `Model` 污染成 `Model | undefined`)。 */
 export interface ServiceConfigGroups {

package/dist/config-types.js

@@ -1,4 +1,5 @@
 import { DRAIN_GRACE_FLOOR_MS } from "@sema-agent/settings-schema/fleet";
+import { GLOBAL_SCOPE } from "@sema-agent/settings-schema/api/scopes";
 export const TASK_WRITE_FACE_ESCALATIONS = ["allow", "refuse"];
 export const RETENTION_MODES = ["audit-only", "enforce"];
 export const CONFIG_PROVIDER_WORDS = ["local", "remote"];
@@ -8,6 +9,11 @@ export const AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS = { minMs: 1_000, maxMs: MAX_TI
 export { DRAIN_GRACE_FLOOR_MS };
 export const DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS = { minMs: 0, maxMs: DRAIN_GRACE_FLOOR_MS };
 export const DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS = 250;
+export function fleetScopeOf(raw) {
+    return raw ?? GLOBAL_SCOPE;
+}
+export const CENTER_BASE_URL_RULE = "设了就必须是可解析的 http(s) URL,且不带凭据 / query / fragment(基址后面要拼路径);坏形拒启(没接中心也拒),拒句只点名规则,不回显 scheme";
+export const FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS = 86_400_000;
 export const FIRST_BYTE_TIMEOUT_BOUNDS = { minMs: 0, maxMs: MAX_TIMER_DELAY_MS };
 export const RESILIENCE_DEFAULTS = {
     firstTokenTimeoutMs: { env: "MODEL_FIRST_TOKEN_TIMEOUT_MS", value: 600_000 },

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { type Model, type PathRuleBases, type PermissionRule } from "@sema-agent/core";
+import { type CenterEndpoint } from "./config-center/center-request.js";
 import { type Autonomy } from "./runtime-governance.js";
 import { type RunnerEnvNameAllowlistKnob, type ServerEnvNameAllowlistKnob } from "./env-name-allowlist-knobs.js";
 import type { ServiceConfig, ServiceConfigFlat, ServiceConfigGroups } from "./config-types.js";
@@ -243,10 +244,7 @@ export declare function configKnobTable(): ConfigKnobRecord[];
 /** [ref] B4 ②:D 族四枚(`PROJECT_MEMORY` / `CONFIG_LKG` / `HOST_BG` / `HOST_EXEC_SPOOL`)的正名 —— 缺省开,读点只读正名。
  *  3.0.0 之前它们叫 `X_DISABLED`(读点上的双重否定);那四个旧负名是墓碑,在 `RETIRED_ENVS` 里(S-588 起在场即拒启,不论正名在不在)。
  *
- *  LKG (last-known-good) persistence of the remote effective-config fetch. Read LAZILY at both main.ts sites
- *  rather than lifted onto `ServiceConfig`, so this stays a pure env knob; `loadConfig` pre-registers it (below)
- *  so its polarity row appears at boot with everything else. */
-export declare const configLkgEnabled: () => boolean;
+ *  其中 `CONFIG_LKG_ENABLED`(远程配置的 LKG 盘缓存)已升成配置席 `configLkgEnabled`,由 `loadConfig` 一次铸出;这里只剩另外两个懒读孪生。 */
 /** The `host` exec lane's background-shell capability kill switch (read per capability probe in remote-env-host.ts). */
 export declare const hostBackgroundShellEnabled: () => boolean;
 /** The `host` exec lane's spool-file stdio form; false ⇒ the pre-1.226 pipe fallback (read per exec). */
@@ -302,8 +300,8 @@ export declare function isRosterGateArmed(configCenter: ServiceConfig["configCen
  *     的判词 `unmintable_segment`,句子带它的 guidance 与 1:1 现名);本仓 7.116.0–7.117.x 那只自比 `mintNamespacePrefix` 的对照随之退役。
  *     引擎判官放行、却一只工具都够不着的一形 —— **工具段为空**(`mcp__srv__`)—— 由本仓判(`namespaced-rule-name.ts`,会话规则写口两腿与 SQL 店写口同调)。
  *     ⚠️ 两段覆盖形 `mcp__<server>`(服务器段是自铸形)够得着(S-1047 收掉的分叉,见下)。
- *   - **core 的文法编不出来的串**(名字里带反斜杠、单条 >512 字符、空串):判词取自 core 自己的
- *     `validatePermissionRules`,见 {@link uncompilableRuleGuidance}。[ref]①([ref])补齐 ——
+ *   - **core 的文法编不出来的串**:判词取自 core 自己的 `validatePermissionRules`,射程与指引见 {@link uncompilableRuleGuidance}
+ *     (名表消费者只递得来名字里带反斜杠、单条 >512 字符、空串三种;规则编译器消费者递来的每一条内容形都走这里)。[ref]①([ref])补齐 ——
  *     此前只有 `ask` 腿(经 `createPermissionRulePolicy` 的 throw)拒得出这一族,`deny` 静默 no-op。
  *
  * 已接受的权衡(与退役表墓碑同一条):部署自有工具真叫 `figma__x` 的极端形会被误拒——boot 期无 roster 可
@@ -402,6 +400,37 @@ export declare const LIMITS_HTTP_FLOORS: {
     readonly attachmentUnboundTtlMs: 60000;
     readonly drainGraceMs: 10000;
 };
+/**
+ * 编排器片 2 —— fleet 成员面 env 的拒启码(拼法随 `config.*` 家族,按**规则**命名)。拒启异常把码挂在 `code` 上(`boot/fatal-exit.ts` 按
+ * `<name> [<code>]: <message>` 印进 fatal 标题),句子本身不再重复方括号。闭集:加一种 = 加一个键。
+ */
+export declare const FLEET_ENV_REFUSAL_CODES: {
+    readonly generation_invalid: "config.fleet_generation_invalid";
+    readonly scope_invalid: "config.fleet_scope_invalid";
+    readonly advertise_address_invalid: "config.fleet_advertise_address_invalid";
+    readonly member_unfenced: "config.fleet_member_unfenced";
+};
+export type FleetEnvRefusalCode = (typeof FLEET_ENV_REFUSAL_CODES)[keyof typeof FLEET_ENV_REFUSAL_CODES];
+/** 一只 fleet 成员的围栏车道:续租打的中心端点(车道对象原样,含活性基址)+ 代际。 */
+export interface FleetFenceLane {
+    readonly center: CenterEndpoint & {
+        readonly worker: string;
+    };
+    readonly generation: string;
+}
+/**
+ * 编排器片 2 规则 0(成员 ⇒ 围栏车道必须齐)的**唯一**判官:非成员(`fleetGeneration` 缺席)⇒ `undefined`;成员 ∧ 中心车道齐
+ * (`centerLaneConfigured`)∧ 公告地址在 ⇒ 车道;成员而缺任一件 ⇒ 拒启(点名缺的键)。`loadConfig` 在 integrations 域里调一次(拒启早于
+ * 任何装配);装配层(第 10 段)对同一份配置再调一次取车道值 —— 同一只判官,过了 `loadConfig` 的配置在那里不会再拒。
+ * 读成「非成员」或「装不上就算了」会让一只本该受围栏的实例悄悄脱离围栏:能力位只在心跳答复里,不公告就永远听不到。
+ */
+export declare function fleetFenceLaneOf(cfg: {
+    readonly fleetGeneration?: string | undefined;
+    readonly configCenter?: (CenterEndpoint & {
+        readonly worker?: string | undefined;
+    }) | undefined;
+    readonly fleetAdvertiseAddress?: string | undefined;
+}): FleetFenceLane | undefined;
 /** 组名 → 该组取景的平铺键(introspection 面:测试用它钉「每个平铺键恰好被一组取景」)。 */
 export declare const CONFIG_GROUP_KEYS: {
     readonly [G in keyof ServiceConfigGroups]: readonly (keyof ServiceConfigFlat)[];

package/dist/config.js

@@ -10,7 +10,10 @@ import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 import { isV2ScopeKey, memoryReplicationCoverage, replicationCovers } from "./memory-scope.js";
 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 } from "./config-types.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 } from "./config-types.js";
+import { 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 "./config-center/center-request.js";
 import { resolveLocalDataRoot } from "./local-data-root.js";
 import { buildWriteProtectionPosture } from "./write-protection.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
@@ -30,6 +33,7 @@ import { createCenterCredentialSource, readCenterCredentialDeclaration } from ".
 import { parseCenterCredentialRenewLeadMs } from "./center-credential-renewer.js";
 import { modelProviderRefusal } from "./model-provider.js";
 import { modelRouteUrlRefusal } from "./model-route-url.js";
+import { buildHttpUrlRefusal, httpUrlFlaws } from "./url-shape.js";
 import { modelRouteEndpointRefusal } from "./model-route-endpoint.js";
 import { displayListEntry } from "./list-entry-display.js";
 import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
@@ -488,7 +492,6 @@ function boolEnv(name, def) {
     registerKnob({ name, polarity: def ? "opt-out" : "opt-in", value, source });
     return value;
 }
-export const configLkgEnabled = () => boolEnv("CONFIG_LKG_ENABLED", true);
 export const hostBackgroundShellEnabled = () => boolEnv("HOST_BG_ENABLED", true);
 export const hostExecSpoolEnabled = () => boolEnv("HOST_EXEC_SPOOL_ENABLED", true);
 function parseReadDenyPatternsEnv(raw) {
@@ -1225,9 +1228,7 @@ function uncompilableRuleGuidance(name, behavior, pathBases) {
     const issue = issues[0];
     if (issue === undefined)
         return undefined;
-    return (`${issue.code} — core's rule grammar cannot compile this name (${issue.message}), so a table keyed by it matches nothing. ` +
-        `Tool names carry no backslashes and are far shorter than the 512-character rule cap; check the spelling, and use ` +
-        `mcp__<server>__* / a2a__<peer>__* for "every tool on that peer"`);
+    return `${issue.code} — core's rule grammar cannot compile this entry: ${issue.message}`;
 }
 function findUnmatchableToolNames(names, opts) {
     const out = [];
@@ -1562,16 +1563,11 @@ function parseMemoryEmbedder(ctx) {
     if (endpoint === undefined || model === undefined || dimRaw === undefined) {
         throw new Error(`MEMORY_EMBEDDER_* is half-configured — missing ${missing.join(", ")}. The memory vector plane needs all three of MEMORY_EMBEDDER_ENDPOINT, MEMORY_EMBEDDER_MODEL, MEMORY_EMBEDDER_DIM; refusing to start rather than silently running lexical-only retrieval while the deployment believes vectors are on (#228).`);
     }
-    if (!URL.canParse(endpoint)) {
-        throw new Error(`MEMORY_EMBEDDER_ENDPOINT="${buildDisplaySafeUrl(endpoint)}" is not a valid URL (expected e.g. https://embeddings.example.com/v1 — the OpenAI-compatible base, or the full .../embeddings endpoint)`);
-    }
-    const parsedEndpoint = new URL(endpoint);
-    const proto = parsedEndpoint.protocol;
-    if (proto !== "http:" && proto !== "https:") {
-        throw new Error(`MEMORY_EMBEDDER_ENDPOINT="${buildDisplaySafeUrl(endpoint)}" must be http(s) (got "${proto}") — the embedder leg is an HTTP POST to an OpenAI-compatible /embeddings face`);
-    }
-    if (parsedEndpoint.username !== "" || parsedEndpoint.password !== "") {
-        throw new Error("MEMORY_EMBEDDER_ENDPOINT must not carry credentials in the URL (user:password@host) — URL userinfo leaks into transport errors, logs and memory conflict reports. Use MEMORY_EMBEDDER_API_KEY (sent as a Bearer header) instead.");
+    const endpointFlaws = httpUrlFlaws(endpoint, ["userinfo"]);
+    if (endpointFlaws.length > 0) {
+        throw new Error(`${buildHttpUrlRefusal("MEMORY_EMBEDDER_ENDPOINT", endpoint, endpointFlaws)} — the embedder leg is an HTTP POST to an OpenAI-compatible /embeddings face ` +
+            `(expected e.g. https://embeddings.example.com/v1 — the OpenAI-compatible base, or the full .../embeddings endpoint); ` +
+            `credentials in the URL leak into transport errors, logs and memory conflict reports, so use MEMORY_EMBEDDER_API_KEY (sent as a Bearer header) instead.`);
     }
     const dimensions = Number(dimRaw);
     if (!Number.isSafeInteger(dimensions) || dimensions < 1) {
@@ -1853,7 +1849,6 @@ function parseOrchestrationDomain(ctx) {
     const workflowSizeGuideline = workflowSizeGuidelineRaw;
     const usageWindows = parseUsageWindows(process.env.USAGE_WINDOWS);
     const bakeRunnerPrincipal = env("BAKE_RUNNER_PRINCIPAL", "system:bake-runner");
-    configLkgEnabled();
     hostBackgroundShellEnabled();
     hostExecSpoolEnabled();
     const lspHostEnabled = (() => {
@@ -1898,6 +1893,7 @@ function parseOrchestrationDomain(ctx) {
         })(),
         ...((dir) => (dir !== undefined ? { agentConfigDir: dir } : {}))(declaredSemaConfigDir()),
         ...((p) => (p !== undefined ? { configLkgPath: p } : {}))(lkgPathOverrideOf(process.env.CONFIG_LKG_PATH)),
+        configLkgEnabled: boolEnv("CONFIG_LKG_ENABLED", true),
         ...((h) => (h !== undefined ? { remoteExecHomeDir: h } : {}))((() => {
             const raw = process.env.REMOTE_EXEC_HOME_DIR;
             if (raw === undefined || raw === "")
@@ -2186,6 +2182,13 @@ function parseGitApiKind(raw, baseUrl) {
 }
 function parseIntegrationsDomain(ctx) {
     const { requirePrincipal, configProvider } = ctx;
+    const registryUrl = parseCenterBaseUrl("SEMA_REGISTRY_URL", process.env.SEMA_REGISTRY_URL, `It is the center base every config pull, fleet and lease request is sent to; setting it selects the center as the config source.`);
+    const registryLiveUrl = parseCenterBaseUrl("SEMA_REGISTRY_LIVE_URL", process.env.SEMA_REGISTRY_LIVE_URL, `It is the center base the fleet liveness endpoints (heartbeat, serving lease) are sent to; unset it to send them to SEMA_REGISTRY_URL.`);
+    const registryWebUrl = parseCenterBaseUrl("SEMA_REGISTRY_WEB_URL", process.env.SEMA_REGISTRY_WEB_URL, `It is the center's web console base this engine reports on GET /health (center.webBaseUrl); unset it if the center has no web console to link to.`);
+    const configCenter = registryUrl !== undefined ? parseConfigCenter(registryUrl, requirePrincipal, registryLiveUrl, registryWebUrl) : undefined;
+    const fleetGeneration = parseFleetGeneration(process.env.FLEET_GENERATION);
+    const fleetAdvertiseAddress = parseFleetAdvertiseAddress(process.env.FLEET_ADVERTISE_ADDRESS);
+    fleetFenceLaneOf({ ...fleetGeneration, configCenter, ...fleetAdvertiseAddress });
     return {
         pluginsAllowHosts: (process.env.PLUGINS_ALLOW_HOSTS ?? "github.com").split(",").map((h) => h.trim()).filter(Boolean),
         configBootFetchBudgetMs: clampEnvWithWarn("CONFIG_BOOT_FETCH_BUDGET_MS", "1500", 0),
@@ -2195,24 +2198,108 @@ function parseIntegrationsDomain(ctx) {
         defaultScenario: env("DEFAULT_SCENARIO", "code"),
         skillsDir: env("SKILLS_DIR", defaultSkillsDir()),
         centerCredentialRenewLeadMs: parseCenterCredentialRenewLeadMs(process.env.CENTER_CREDENTIAL_RENEW_LEAD_MS),
-        configCenter: process.env.SEMA_REGISTRY_URL ? parseConfigCenter(env("SEMA_REGISTRY_URL"), requirePrincipal) : undefined,
+        configCenter,
         fleetLeaseFailClosed: parseFleetLeaseFailClosed(process.env.FLEET_LEASE_FAIL_CLOSED, requirePrincipal),
+        ...fleetGeneration,
+        fleetScope: parseFleetScope(process.env.FLEET_SCOPE),
+        ...fleetAdvertiseAddress,
+        fleetLeaseOutageMaxMs: parseFleetLeaseOutageMaxMs(process.env.FLEET_LEASE_OUTAGE_MAX_MS),
         ...(configProvider !== undefined ? { configProvider } : {}),
         configLocalDir: process.env.CONFIG_LOCAL_DIR || undefined,
         a2aServe: parseA2aServe(),
     };
 }
+function parseFleetGeneration(raw) {
+    const name = "FLEET_GENERATION";
+    if (raw === undefined)
+        return {};
+    const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
+    if (!isCanonicalGeneration(raw)) {
+        throw fleetEnvRefusal("generation_invalid", `env ${name}=${JSON.stringify(shown)} is not a generation: it must be a canonical non-negative decimal string ("0", "7", "10" — no leading zero, ` +
+            `sign, whitespace or fraction, and not empty). The config renderer sets it on fleet members; unset it entirely for a standalone engine. ` +
+            `Refusing to boot rather than running outside the serving-lease fence.`);
+    }
+    return { fleetGeneration: raw };
+}
+export const FLEET_ENV_REFUSAL_CODES = {
+    generation_invalid: "config.fleet_generation_invalid",
+    scope_invalid: "config.fleet_scope_invalid",
+    advertise_address_invalid: "config.fleet_advertise_address_invalid",
+    member_unfenced: "config.fleet_member_unfenced",
+};
+function fleetEnvRefusal(rule, message) {
+    return Object.assign(new Error(message), { code: FLEET_ENV_REFUSAL_CODES[rule] });
+}
+function parseFleetScope(raw) {
+    const name = "FLEET_SCOPE";
+    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)}"). ` +
+            `Refusing to boot rather than answering drain requests under the wrong identity.`);
+    }
+    return fleetScopeOf(raw);
+}
+function parseFleetAdvertiseAddress(raw) {
+    if (raw === undefined || raw === "")
+        return {};
+    const refusal = pathBaseUrlRefusal("env FLEET_ADVERTISE_ADDRESS", 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.`);
+    }
+    return { fleetAdvertiseAddress: raw };
+}
+export function fleetFenceLaneOf(cfg) {
+    const generation = cfg.fleetGeneration;
+    if (generation === undefined)
+        return undefined;
+    const laneConfigured = centerLaneConfigured(cfg);
+    if (laneConfigured && cfg.fleetAdvertiseAddress !== undefined)
+        return { center: cfg.configCenter, generation };
+    const missing = [
+        ...(laneConfigured ? [] : [`the center lane (SEMA_REGISTRY_URL + ${CENTER_CREDENTIAL_ENV.token} or ${CENTER_CREDENTIAL_ENV.tokenFile} + SEMA_REGISTRY_WORKER)`]),
+        ...(cfg.fleetAdvertiseAddress === undefined ? ["the announce address (FLEET_ADVERTISE_ADDRESS)"] : []),
+    ];
+    throw fleetEnvRefusal("member_unfenced", `fleet member cannot be fenced — env FLEET_GENERATION=${JSON.stringify(generation)} makes this engine a fleet member, ` +
+        `but ${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} not configured. A member renews its serving lease with the center and hears whether ` +
+        `the center enforces the lease only in the heartbeat reply (the heartbeat needs the announce address); without them it would serve outside the fence. ` +
+        `Configure them, or unset FLEET_GENERATION for a standalone engine.`);
+}
+function parseFleetLeaseOutageMaxMs(raw) {
+    if (raw === undefined || raw === "")
+        return FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS;
+    const n = /^(0|[1-9]\d*)$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(n) || n < SERVING_LEASE_TTL_FLOOR_MS) {
+        const shown = raw.length > 40 ? `${raw.slice(0, 40)}…(${raw.length} chars)` : raw;
+        throw new Error(`env FLEET_LEASE_OUTAGE_MAX_MS=${JSON.stringify(shown)} must be a whole number of milliseconds ≥ ${SERVING_LEASE_TTL_FLOOR_MS} (the serving-lease TTL floor; ` +
+            `decimal digits only; unset = ${FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS}, 24 h). It bounds how long this engine keeps taking new submissions after its serving ` +
+            `lease expired with the center unreachable, and how far from now a drain request's deadlineAt may be — "0" and "infinite" are not values ` +
+            `(the bound must be finite and non-trivial). Refusing to boot.`);
+    }
+    return n;
+}
 function parseFleetLeaseFailClosed(raw, requirePrincipal) {
     const explicit = parseBoolWord("FLEET_LEASE_FAIL_CLOSED", raw);
     const value = explicit ?? requirePrincipal;
     registerKnob({ name: "FLEET_LEASE_FAIL_CLOSED", polarity: "posture", value, source: explicit !== undefined ? "env" : requirePrincipal ? "posture" : "default" });
     return value;
 }
-function parseConfigCenter(baseUrl, requirePrincipal) {
+function parseCenterBaseUrl(name, raw, role) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    const refusal = pathBaseUrlRefusal(`env ${name}`, raw);
+    if (refusal !== undefined)
+        throw new Error(`${refusal}. ${role}`);
+    return raw;
+}
+function parseConfigCenter(baseUrl, requirePrincipal, liveBaseUrl, webBaseUrl) {
     const worker = process.env.SEMA_REGISTRY_WORKER || undefined;
     const declared = readCenterCredentialDeclaration();
     return {
         baseUrl,
+        ...(liveBaseUrl !== undefined ? { liveBaseUrl } : {}),
+        ...(webBaseUrl !== undefined ? { webBaseUrl } : {}),
         credential: createCenterCredentialSource(declared.from === "file" ? { ...declared, multiTenant: requirePrincipal } : declared, worker),
         dryRun: boolEnv("SEMA_REGISTRY_DRY_RUN", false),
         worker,
@@ -2230,20 +2317,13 @@ function parseA2aServe() {
             `and that address is the operator's to declare (it is NOT derived from the request Host header: an anonymous discovery caller must not decide what our public card advertises). ` +
             `Set A2A_SERVE_URL to this deployment's externally reachable /v1/a2a URL (e.g. "https://agent.example.com/v1/a2a").`);
     }
-    let parsed;
-    try {
-        parsed = new URL(rawUrl);
-    }
-    catch {
-        parsed = undefined;
-    }
-    if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
-        throw new Error(`A2A_SERVE_URL must be a parseable http(s) URL (e.g. "https://agent.example.com/v1/a2a"); got ${JSON.stringify(buildDisplaySafeUrl(rawUrl))}`);
-    }
-    if (parsed.username !== "" || parsed.password !== "") {
-        throw new Error(`A2A_SERVE_URL must not carry userinfo (credentials before "@") — it is published verbatim on the ANONYMOUSLY readable agent card, so those credentials would be handed to every discovery caller. ` +
-            `Inbound authentication on this endpoint is header-shaped (a service credential), not URL-embedded; strip the userinfo and keep the secret in the caller's headers.`);
+    const urlFlaws = httpUrlFlaws(rawUrl, ["userinfo"]);
+    if (urlFlaws.length > 0) {
+        throw new Error(`${buildHttpUrlRefusal("A2A_SERVE_URL", rawUrl, urlFlaws)} — it is published verbatim on the ANONYMOUSLY readable agent card as this deployment's JSON-RPC endpoint ` +
+            `(e.g. "https://agent.example.com/v1/a2a"), so it must be a plain http(s) address and must not hand credentials to every discovery caller: ` +
+            `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) {
         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), ` +
@@ -2336,7 +2416,7 @@ const ORCHESTRATION_GROUP_KEYS = [
     "backgroundAgentParkClaimStaleMs", "delegationEntryCaps", "rosterRetentionMs", "leaderRunStaleMs", "scratchpadSweepTtlMs", "sandboxPkgSource",
     "sessionAutoTitle", "sessionAutoTitleSource", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspEnabled", "lspHostEnabled", "lspEnvAllow",
     "imageBakes", "readFace", "readFaceSource", "taskWriteFaceEscalation", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude",
-    "agentConfigDir", "configLkgPath",
+    "agentConfigDir", "configLkgPath", "configLkgEnabled",
 ];
 const LIMITS_HTTP_GROUP_KEYS = [
     "port", "attachmentOrphanGraceMs", "workspaceFileMaxBytes", "attachmentMaxBytes", "attachmentMimeAllowlist",
@@ -2348,7 +2428,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", "configCenter", "fleetLeaseFailClosed", "configProvider", "configLocalDir",
+    "skillsDir", "centerCredentialRenewLeadMs", "configCenter", "fleetLeaseFailClosed", "fleetGeneration", "fleetScope", "fleetAdvertiseAddress", "fleetLeaseOutageMaxMs", "configProvider", "configLocalDir",
 ];
 export const CONFIG_GROUP_KEYS = {
     store: STORE_GROUP_KEYS,

package/dist/fleet/drain-entry.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 排空的**一只入口**(编排器长远稿片 2 件 2;契约型 = settings-schema 8.1.0 `DrainRequest` / `DrainReceipt` / `EngineDraining`)。
+ *
+ * ## 规则
+ *
+ *  1. **一只入口,两条车道**:进入排空只有 `boot/shutdown.ts` 的 `enterDrain`(装在 {@link DrainState.enter} 上)一处。Docker 车道 / 中心直调
+ *     经 `POST /v1/admin/drain`(体 = `DrainRequest`);Kubernetes 车道经服务租约被拒(`fleet/serving-lease.ts`,`actionId = lease:<代际>`);
+ *     非编排路径 = 停止信号(SIGTERM)/ SIGHUP 升级 / 附着租约自退,动作号由引擎自铸({@link ENGINE_DRAIN_CAUSES})。全部汇到同一只入口。
+ *  2. **期限在进入那一拍定死**:请求带的 `deadlineAt` 原样;引擎自起的排空 = 起点 + 此刻的排空窗(`drainGraceMs`)。之后改窗(中心热改
+ *     `limits.drainGraceMs`)不动在跑的期限 —— 排空驱动读的是期限,不是窗。
+ *     请求带的期限有**准入上界** = 进入那一拍 + `config.fleetLeaseOutageMaxMs`(`T_max`,env `FLEET_LEASE_OUTAGE_MAX_MS`,`loadConfig` 无条件
+ *     解析、缺省 24 h,成员与非成员同读):一台实例「活着而不服务」最长多久本就由这一席定义(服务租约失联后最多再接单多久,
+ *     `fleet/serving-lease.ts`),排空口不另立第二个数。上界由调用方随入参声明({@link DrainEntry.deadlineBoundMs};排空口声明它,引擎自起的
+ *     排空不声明 —— 那些期限由引擎自己的窗定,拒了就是不排空),**由入口判**:只有这一发会进入排空时才判(已在排空 / 硬停已在进行 ⇒ 期限
+ *     不会被采用,照规则 3 回执);越界 ⇒ 零状态变化,入口答 {@link DrainDeadlineRefusal}(排空口 400 `request.field_invalid`)。「会不会
+ *     采用这只期限」只有入口一处判 —— 调用方不另读 `draining` 去猜。已过的期限不越界(进入即到期:在飞为零当拍硬停,否则下一拍)。
+ *  3. **幂等**:已在排空 ⇒ 不重置,回执 `already_draining` 带**第一次**的动作 / 起点 / 期限(不论这次的动作号是否相同)。
+ *  4. **身份**:逐字段比,任一不符 ⇒ 409 `conflict.fleet_identity`,零状态变化。
+ *     · `scope`:两侧都经 {@link fleetScopeOf} 读成值(缺席 = settings-schema 的缺省 scope,线上任何一处缺席的 scope 都读成它)再严格相等。
+ *       引擎这一侧的唯一来源 = env `FLEET_SCOPE`(`config.fleetScope`,`config.ts` 解析一次);请求不带 `scope` = 点名缺省 scope。
+ *     · `worker` / `expectedGeneration`:缺席对缺席(非 fleet 成员没有代际,不带 `expectedGeneration` 的请求是单机形,不是通配)。
+ *     · `instanceId`:请求带了才比(它是引擎每进程自铸的身份,`/health` 上可读);「点名的是不是别的进程」与 run 行同一只判据
+ *       `runProvenElsewhere`。
+ *     引擎自己的 worker / instanceId 读不出 ⇒ 带了这一项的请求不符(认不出自己就不认任何点名;没配 `SEMA_REGISTRY_WORKER` 的引擎因此
+ *     只能用停止信号排空)。
+ *  5. **进入那一拍让出在飞**:本副本可抢占的在飞腿经 core `TaskSpec.preemptSignal` 让出(在下一个干净的回合边界耐久停驻,
+ *     `resource_limit` / `preempt`;不合格的腿上 core 静默不动,等到期限硬停 —— 既有 `crashed` 臂);活的审批卡按断连同路改路耐久停驻
+ *     (协调器 `beginDrain`,core `onAsk` 答 `"unavailable"` 的合同);排空期间新登记的可抢占腿在登记那一拍让出(同一条规则)。
+ *
+ * 纯类型 + 纯函数叶(值 import 只有 scope 读法叶与 run 行判词叶)。
+ */
+import type { DrainReceipt, DrainRequest, EngineDraining } from "@sema-agent/settings-schema/fleet";
+/**
+ * 引擎自铸的动作号 —— **一张表**(排空事实与回执里不来自请求体的全部拼法;请求体的 `actionId` 由调用方自取):
+ *  · {@link ENGINE_DRAIN_CAUSES}:没有请求承载的排空成因(停止信号 / SIGHUP 升级 / 附着租约自退);
+ *  · {@link HARD_STOP_ACTION_ID}:硬停(未经排空)已在进行时排空口回执里的动作号 —— 不是一种排空成因,只说「这只进程已经在停,而且比你要的更快」;
+ *  · `lease:<代际>`:服务租约被拒的排空({@link leaseDrainActionId},每代一只:同一代被拒两次是同一个动作)。
+ * 按成因穷举的地方({@link DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL})加一种成因不补格 = 编译红。
+ */
+export declare const ENGINE_DRAIN_CAUSES: readonly ["signal:SIGTERM", "signal:SIGHUP", "self-exit:attachment"];
+export type EngineDrainCause = (typeof ENGINE_DRAIN_CAUSES)[number];
+export declare const HARD_STOP_ACTION_ID = "hard-stop";
+export type LeaseDrainActionId = `lease:${string}`;
+/** 服务租约被拒时的动作号(每代一只)。 */
+export declare function leaseDrainActionId(generation: string): LeaseDrainActionId;
+/**
+ * 每种排空成因的**入口那一拍算不算本次排空的第一发停止信号**(`boot/shutdown.ts` 的「第二发 = 硬停」读它;它答的不是「这是不是 `StopSignal`」——
+ * `shutdown.ts` 的 `StopSignal` 闭集只有 SIGTERM / SIGINT,那是「哪些信号走停止处理器」)。算 ⇒ 之后隔 ≥ 最小间隔的一发即硬停;不算 ⇒ 期限由入口定死,
+ * 之后到达的第一发停止信号只被吸收(不缩短期限)。SIGHUP 算:SIGHUP 升级成排空要的就是**第二发** SIGHUP(第一发只开空闲窗),那是人 / 宿主又发了一次
+ * 停的意图,与 SIGTERM 进的排空同一个读法(7.120.0 起的行为)。闭集 Record。
+ */
+export declare const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL: {
+    readonly [C in EngineDrainCause]: boolean;
+};
+/** 入口的入参:动作号 + 期限(epoch ms)+ 调用方声明的期限准入上界(规则 2)。 */
+export interface DrainEntry {
+    readonly actionId: string;
+    readonly deadlineAt: number;
+    /** 期限的准入上界(ms):这一发会进入排空而 `deadlineAt − 进入那一拍 > 它` ⇒ 入口零状态变化,答 {@link DrainDeadlineRefusal}。
+     *  排空口传 `config.fleetLeaseOutageMaxMs`;引擎自起的排空(停止信号 / 租约被拒 / 附着租约自退)不传。 */
+    readonly deadlineBoundMs?: number;
+}
+/** 入口拒了这只期限(规则 2):越过调用方声明的上界,什么都没变。 */
+export interface DrainDeadlineRefusal {
+    readonly state: "deadline_beyond_bound";
+    readonly boundMs: number;
+}
+/** 入口的答:契约回执(进入 / 已在排空),或期限越界的拒(只在调用方声明了上界时出现)。按 `state` 穷举。 */
+export type DrainEntryAnswer = DrainReceipt | DrainDeadlineRefusal;
+/**
+ * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
+ *  · `draining` / `since` / `actionId` / `deadlineAt` —— **只由** {@link enter} 整组写入(排空事实 = 契约 `EngineDraining`);
+ *  · `enter` —— 唯一入口(收尾链装;缺席 = 这个进程没有收尾链,如嵌入宿主 / 测试夹具);
+ *  · `yieldInflight` —— 让出本副本在飞的可抢占腿(`createHttpServer` 装);
+ *  · `endSubscriptions` —— 关掉本副本打开着的只读订阅流(发一帧 `draining` 终帧再关;`createHttpServer` 装,S-1281)。订阅流不是在飞的工作
+ *    (不进 `inflight`),排空不等它;收尾链在排空进入那一拍与硬停起点各调一次(排空期间新开的订阅在硬停那一拍收);
+ *  · 其余四只是既有的读口(在飞数 / 活性时钟 / 附着流),语义见 `http/server.ts`。`inflight` 只数**工作**(run 腿 / 计费提交 / HITL 应答 /
+ *    admission 期的普通请求),只读订阅只进 `attachedStreams`(S-1281)。
+ */
+export interface DrainState {
+    draining: boolean;
+    since?: number;
+    actionId?: string;
+    deadlineAt?: number;
+    enter?: (entry: DrainEntry) => DrainEntryAnswer;
+    yieldInflight?: () => void;
+    endSubscriptions?: () => void;
+    inflight?: () => number;
+    lastActivityAt?: () => number;
+    attachedStreams?: () => number;
+    lastAttachEndedAt?: () => number;
+}
+/** 排空盒子里的排空事实(三键齐才是;入口整组写,所以「缺一」只出现在手搭的夹具上)。 */
+export declare function drainingFactOf(s: Pick<DrainState, "draining" | "since" | "actionId" | "deadlineAt">): EngineDraining | undefined;
+/**
+ * 规则 2 的准入上界:期限离进入那一拍(本引擎的挂钟)超过 `boundMs` ⇔ 越界。恰好等于上界不越界;已过的期限不越界。入口判它
+ * (`boot/shutdown.ts` 的 enterDrain,在「已在排空 / 硬停已在进行」两臂之后)。
+ */
+export declare function drainDeadlineBeyondBound(deadlineAt: number, now: number, boundMs: number): boolean;
+/** 本进程的身份。`scope` 已读成值(`config.fleetScope`);其余三项与 `/health` 上读到的同一份。 */
+export interface EngineIdentity {
+    readonly scope: string;
+    readonly worker?: string;
+    readonly generation?: string;
+    readonly instanceId?: string;
+}
+/** 身份四元的字段名(请求侧拼法;409 拒句按它点名,不回显值)。 */
+export declare const DRAIN_IDENTITY_FIELDS: readonly ["scope", "worker", "expectedGeneration", "instanceId"];
+export type DrainIdentityField = (typeof DRAIN_IDENTITY_FIELDS)[number];
+/** 规则 4:不符的字段(按 {@link DRAIN_IDENTITY_FIELDS} 序;空 ⇔ 认得)。 */
+export declare function drainIdentityMismatches(req: Pick<DrainRequest, "scope" | "worker" | "expectedGeneration" | "instanceId">, self: EngineIdentity): DrainIdentityField[];
+//# sourceMappingURL=drain-entry.d.ts.map

package/dist/fleet/drain-entry.js

@@ -0,0 +1,38 @@
+import { fleetScopeOf } from "../config-types.js";
+import { runProvenElsewhere } from "../plugins/store-contracts.js";
+export const ENGINE_DRAIN_CAUSES = ["signal:SIGTERM", "signal:SIGHUP", "self-exit:attachment"];
+export const HARD_STOP_ACTION_ID = "hard-stop";
+export function leaseDrainActionId(generation) {
+    return `lease:${generation}`;
+}
+export const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL = {
+    "signal:SIGTERM": true,
+    "signal:SIGHUP": true,
+    "self-exit:attachment": false,
+};
+export function drainingFactOf(s) {
+    return s.draining && s.actionId !== undefined && s.since !== undefined && s.deadlineAt !== undefined ? { actionId: s.actionId, since: s.since, deadlineAt: s.deadlineAt } : undefined;
+}
+export function drainDeadlineBeyondBound(deadlineAt, now, boundMs) {
+    return deadlineAt - now > boundMs;
+}
+export const DRAIN_IDENTITY_FIELDS = ["scope", "worker", "expectedGeneration", "instanceId"];
+export function drainIdentityMismatches(req, self) {
+    return DRAIN_IDENTITY_FIELDS.filter((f) => {
+        switch (f) {
+            case "scope":
+                return fleetScopeOf(req.scope) !== self.scope;
+            case "worker":
+                return self.worker === undefined || req.worker !== self.worker;
+            case "expectedGeneration":
+                return req.expectedGeneration !== self.generation;
+            case "instanceId":
+                return req.instanceId !== undefined && (self.instanceId === undefined || runProvenElsewhere({ instanceId: req.instanceId }, self.instanceId));
+            default: {
+                const unhandled = f;
+                throw new Error(`drain identity: unknown field ${String(unhandled)}`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=drain-entry.js.map