@sema-agent/server 7.120.0 → 7.121.0

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). */
@@ -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, pathBaseUrlFlaw } 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";
@@ -488,7 +491,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) {
@@ -1853,7 +1855,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 +1899,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 +2188,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 +2204,107 @@ 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 why = pathBaseUrlFlaw(raw);
+    if (why !== undefined) {
+        throw fleetEnvRefusal("advertise_address_invalid", `env FLEET_ADVERTISE_ADDRESS ${why} (an http(s) base URL, e.g. "http://10.0.0.5:8090"); got ${JSON.stringify(buildDisplaySafeUrl(raw))} — ` +
+            `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 — "0" and "infinite" are not values (the tolerance must be bounded 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 why = pathBaseUrlFlaw(raw);
+    if (why !== undefined)
+        throw new Error(`env ${name} ${why}; got ${JSON.stringify(buildDisplaySafeUrl(raw))}. ${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,
@@ -2336,7 +2428,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 +2440,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,87 @@
+/**
+ * 排空的**一只入口**(编排器长远稿片 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`)不动在跑的期限 —— 排空驱动读的是期限,不是窗。
+ *  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)。 */
+export interface DrainEntry {
+    readonly actionId: string;
+    readonly deadlineAt: number;
+}
+/**
+ * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
+ *  · `draining` / `since` / `actionId` / `deadlineAt` —— **只由** {@link enter} 整组写入(排空事实 = 契约 `EngineDraining`);
+ *  · `enter` —— 唯一入口(收尾链装;缺席 = 这个进程没有收尾链,如嵌入宿主 / 测试夹具);
+ *  · `yieldInflight` —— 让出本副本在飞的可抢占腿(`createHttpServer` 装);
+ *  · 其余四只是既有的读口(在飞数 / 活性时钟 / 附着流),语义见 `http/server.ts`。
+ */
+export interface DrainState {
+    draining: boolean;
+    since?: number;
+    actionId?: string;
+    deadlineAt?: number;
+    enter?: (entry: DrainEntry) => DrainReceipt;
+    yieldInflight?: () => void;
+    inflight?: () => number;
+    lastActivityAt?: () => number;
+    attachedStreams?: () => number;
+    lastAttachEndedAt?: () => number;
+}
+/** 排空盒子里的排空事实(三键齐才是;入口整组写,所以「缺一」只出现在手搭的夹具上)。 */
+export declare function drainingFactOf(s: Pick<DrainState, "draining" | "since" | "actionId" | "deadlineAt">): EngineDraining | undefined;
+/** 本进程的身份。`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,35 @@
+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 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

package/dist/fleet/engine-signal.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 引擎信号的**一只铸点**(编排器长远稿片 2 件 1;契约型 = settings-schema `./fleet` 的 `EngineSignal` / `RestartSignal.withheld` / `LeaseState` / `InstanceAnnouncement`)。
+ *
+ * ## 规则(先写规则,再写码)
+ *
+ *  1. **一只铸点,三个出口**:{@link mintEngineSignal} 是「引擎此刻自己说自己什么」的唯一来源。`GET /health`(诊断面)、
+ *     `GET /readyz`(就绪探针)与 fleet 心跳(`fleet-client.ts`)各读它**一次**,再按各自的出口形投影;没有出口另算一遍
+ *     就绪 / 重启 / 代际 / 租约。
+ *  2. **就绪**仍只有一只谓词(`http/readiness.ts` 的 `readinessOf`),铸点把它的判决原样带上(`verdict`)。`/readyz` 200 ⇔
+ *     `ready ∧ ¬draining ∧ leaseState ≠ denied` —— 后两项不是新判据:`draining` 本来就是就绪原因,而租约被拒**同一拍**经
+ *     唯一的排空入口进入排空(`fleet/serving-lease.ts`),所以「被拒 ⇒ 排空 ⇒ 不就绪」是构造出来的,不靠第二只谓词。
+ *     `leaseState = expired` **不**进就绪(中心不可达不是本实例的病,见租约模块头注)。
+ *  3. **重启**:`restart` = 已发布的重启信号;没有已发布信号而有一只**扣着**的候选(config-center 的保留候选状态机)且它确有被扣的片时,
+ *     铸 `{reasons: 被扣的片, version, since, withheld: true}`(「要重启,但此刻换掉本实例会丢它手里的候选」)。已发布的信号恒胜(那几片
+ *     是安全可重启的,扣着的片不阻止它们);被扣的片为空(只差发布重试)⇒ 不是重启事实,不铸(契约 `RestartSignal.reasons` 至少一词;
+ *     那一形的面只有每拍一行运维 warn + 计数)。「扣着」在两出口上只有这一种读法(7.120.x 的 `/health.modelPlaneDeferred` 本版删除)。
+ *     合成只在 {@link buildRestartSignal} 一处,`restartState()` 是它唯一的调用方 —— 两个出口读的是同一只取值口。
+ *  4. **代际与实例**:`generation` = env `FLEET_GENERATION` 的回声(规范十进制串;非规范在 boot 拒启,见 `config.ts`);
+ *     缺席 ⇔ 非 fleet 成员。`instanceId` = 本进程起步自铸的那一只(`boot/stage-03` 的 uuidv7),不读 env。
+ *  5. **出口方言**(契约 `EngineSignal` 与今天两出口的既有形两处不同:`draining` 是布尔、`/health` 就绪时不带 `ready` —— 契约包
+ *     自己的 `EngineSignal` 头注写明了这两处;世代账两键 settings-schema 9.0.0 起契约也是数,与引擎同形)—— 两出口**照旧**用 8.0 方言。心跳体的类型
+ *     **就是**契约 `InstanceAnnouncement`(中心按它 `safeParse`;8.2.0 起它类型化 `generation` / `leaseState` / `leaseUntil`),没有
+ *     契约外的键:世代账(`configTargetVersion` / `configAppliedVersion`)契约心跳形没有座位,只上 `/health`。新增的键
+ *     (`generation` / `leaseState` / `leaseUntil`、`restart.withheld`)只在 fleet 成员 / 扣着的候选在场时出现 ⇒ 非 fleet 部署的
+ *     两出口逐字节同 7.120.0。方言收口归契约包下一个 major(布尔 `draining` 对退役、两出口整只承载 `EngineSignal`)与中心提货之后,
+ *     由引擎同版翻转 —— 不在本层另造第二方言。
+ *  6. **租约四态的词表属主是契约包**(`LeaseState`):本模块的读数型 {@link ServingLeaseView} 按它逐词对齐(下面的编译期断言两向钉),
+ *     契约加一个词 ⇒ 本仓编译红,不会悄悄多出一个本仓读不出的态。
+ *
+ * 模块形:纯函数(只值 import 契约包与 `http/readiness.ts`)—— `http/` 与 `fleet-client.ts` 都读它,不许长出回环。
+ */
+import type { EngineDraining, InstanceAnnouncement, LeaseState, RestartSignal } from "@sema-agent/settings-schema/fleet";
+import { type ReadinessInputs, type ReadinessVerdict } from "../http/readiness.js";
+/**
+ * 租约此刻的读数(租约客户端交出;纯数据)。态的词表 = 契约 `LeaseState`(四词的语义在契约注里:`none` 不生效 / `granted` 持有 /
+ * `expired` 生效而此刻无有效授予 / `denied` 正面证据拒,黏性)。`pastOutageMax` = 已过期且不可达满 `T_max` ⇒ 新提交 503 `state.lease_expired`。
+ */
+export type ServingLeaseView = {
+    readonly state: Extract<LeaseState, "none">;
+} | {
+    readonly state: Extract<LeaseState, "granted">;
+    readonly leaseUntil: number;
+} | {
+    readonly state: Extract<LeaseState, "expired">;
+    readonly pastOutageMax: boolean;
+} | {
+    readonly state: Extract<LeaseState, "denied">;
+};
+/** 心跳体上的 fleet 成员三键 —— 类型取自契约心跳形(拼法与值域只有契约一个写者)。 */
+export type FleetMembershipKeys = Pick<InstanceAnnouncement, "generation" | "leaseState" | "leaseUntil">;
+/** 非 fleet 成员 / 没装租约客户端时的读数(唯一拼法)。 */
+export declare const LEASE_NONE: ServingLeaseView;
+/** 扣着的候选(config-center 的 `planeDeferredNoHandoff` 投影):版本、起扣时刻、被扣的重启片。 */
+export interface RetainedCandidate {
+    readonly version: number;
+    readonly since: number;
+    readonly blocked?: readonly string[];
+}
+/**
+ * 重启事实的**唯一**合成点(规则 3):已发布信号恒胜;否则扣着的候选有被扣的片 ⇒ `withheld:true` 的信号;否则缺席。
+ * `build*` = 纯数据。泛型让 config-center 交进来的窄型(`EngineRestartSignal`,`reasons` 是片闭集)原样回来。
+ */
+export declare function buildRestartSignal<R extends RestartSignal>(published: R | undefined, retained: (RetainedCandidate & {
+    readonly blocked?: readonly R["reasons"][number][];
+}) | undefined): R | undefined;
+/** `/health.configHandoff` 的状态词(闭集;今天只有一词 —— 在场即信号,缺席 = 有接力或无从谈起)。 */
+export declare const CONFIG_HANDOFF_STATES: readonly ["missing"];
+export type ConfigHandoffState = (typeof CONFIG_HANDOFF_STATES)[number];
+/**
+ * `/health.configHandoff`(只在 `/health`,不上心跳)—— 一件**事故**:**在场 ⇔ 部署声明了耐久接力 ∧ 应用着的那一代没在下一次起服将用的身份的桶里确认耐久落盘**
+ * (config-center 的接力账 {@link ConfigHandoffLedger}:最后确认耐久的那一代 + 写进的那只身份桶,对比应用着的那一代 + 此刻的凭证身份 —— 离线起服按此刻
+ * 的身份选桶;部署形门在 config-center 的取值口,读判「handoff confirmed」的同一只谓词)。凭证换了人(换了身份)而新身份的桶里没有这一代 ⇒ 在场。覆盖 LKG 发布失败(含保留候选、启动期技能债)与部分应用(某组被整拒、其余组已热应用,LKG 停在上一个完整世代)两形。**部署形**不在这里报:
+ * 没有耐久声明(`CONFIG_LKG_DURABLE` 不真 / LKG 关)的部署「重启靠中心重拉」是配置时声明的事实 ⇒ 恒缺席;本地腿 / 没有配置管道 ⇒ 缺席。
+ * 与 `restart.withheld` 两个事实两张脸(可同在):要不要重启归 `restart`,声明了的接力缺不缺归本键。
+ * `version` = 应用着的那一代;`since` = 这一代开始没有确认接力的时刻(持续缺着时不刷新,确认即清)。
+ */
+export interface ConfigHandoff {
+    readonly state: ConfigHandoffState;
+    readonly version: number;
+    readonly since: number;
+}
+/** 配置接力账(config-center 持有,`/health.configHandoff` 的唯一来源):应用着的那一代、最后一次确认耐久接力的那一代与它写进的身份桶、
+ *  下一次起服将用的身份(此刻的凭证身份 —— 离线起服选桶读的同一只)。 */
+export interface ConfigHandoffLedger {
+    readonly applied?: number;
+    readonly durable?: {
+        readonly version: number;
+        readonly identity: string;
+    };
+    readonly bootIdentity?: string;
+}
+/** 「接力缺着」的**唯一**判据(纯):应用过一代 ∧ 最后确认耐久的不是「这一代 ∧ 下一次起服将用的身份桶」。 */
+export declare function configHandoffMissing(ledger: ConfigHandoffLedger): boolean;
+/** `configHandoff` 的**唯一**合成点(纯):缺着 ⇒ `{ state: "missing", version: 应用着的那一代, since }`;否则缺席。`since` 由持账方锁存(发现缺着的那一拍)。
+ *  `build*` = 纯数据;config-center 的 `configHandoffState()` 是唯一调用方。 */
+export declare function buildConfigHandoff(ledger: ConfigHandoffLedger, since: number | undefined): ConfigHandoff | undefined;
+/** 铸点读的输入 —— `ServiceDeps` 上的同名键(HTTP 面与心跳读的是**同一个**对象)。 */
+export interface EngineSignalInputs extends ReadinessInputs {
+    readonly instanceId?: string;
+    /** `config.fleetGeneration` = env `FLEET_GENERATION` 的回声(boot 已判规范;缺席 ⇔ 非 fleet 成员)。 */
+    readonly config?: {
+        readonly fleetGeneration?: string;
+    };
+    readonly drainState?: ReadinessInputs["drainState"] & {
+        readonly since?: number;
+        readonly actionId?: string;
+        readonly deadlineAt?: number;
+    };
+    readonly restartState?: () => RestartSignal | undefined;
+    readonly servingLease?: () => ServingLeaseView;
+    readonly configApplyState?: () => {
+        readonly configTargetVersion: number;
+        readonly configAppliedVersion: number;
+    } | undefined;
+}
+/** 铸出的信号(纯数据)。 */
+export interface EngineSignalFacts {
+    /** 就绪判(`readinessOf` 原样)。 */
+    readonly verdict: ReadinessVerdict;
+    /** 在场 ⇔ 排空中(契约 `EngineDraining`:动作 / 起点 / 期限)。 */
+    readonly draining?: EngineDraining;
+    readonly restart?: RestartSignal;
+    readonly generation?: string;
+    readonly instanceId?: string;
+    readonly lease: ServingLeaseView;
+    readonly configTargetVersion?: number;
+    readonly configAppliedVersion?: number;
+}
+/** **唯一**铸点(活判,每次调用现读输入)。 */
+export declare function mintEngineSignal(deps: EngineSignalInputs): EngineSignalFacts;
+/**
+ * fleet 成员身份三键的**唯一**投影(两出口同调,同值同序):`generation` / `leaseState` / `leaseUntil`。
+ * 在场律:非 fleet 成员(无 `generation`)⇒ 空对象(两出口逐字节同 7.120.0);成员 ⇒ `generation` + `leaseState` 恒在,
+ * `leaseUntil` 只在 `granted`。
+ */
+export declare function fleetMembershipKeys(s: EngineSignalFacts): FleetMembershipKeys;
+/** 出口的 8.0 方言布尔 `draining`(心跳 `InstanceAnnouncement.draining` / `/health.draining`):就绪原因含排空。 */
+export declare function drainingFlag(s: EngineSignalFacts): boolean;
+/**
+ * `/health.restartRequired`(冗余顶层布尔,壳读它决定要不要问用户重启)的投影:在场 ⇔ 有**可执行**的重启信号
+ * (`restart` 在场且未被扣)—— 与 7.120.0 的读数逐字同(那时被扣的候选根本不出 `restart`)。
+ */
+export declare function restartActionable(s: EngineSignalFacts): boolean;
+//# sourceMappingURL=engine-signal.d.ts.map

package/dist/fleet/engine-signal.js

@@ -0,0 +1,60 @@
+import { readinessOf } from "../http/readiness.js";
+import { drainingFactOf } from "./drain-entry.js";
+export const LEASE_NONE = Object.freeze({ state: "none" });
+export function buildRestartSignal(published, retained) {
+    if (published !== undefined)
+        return published;
+    if (retained === undefined)
+        return undefined;
+    const reasons = [...new Set(retained.blocked ?? [])];
+    if (reasons.length === 0)
+        return undefined;
+    return { reasons, version: retained.version, since: retained.since, withheld: true };
+}
+export const CONFIG_HANDOFF_STATES = ["missing"];
+export function configHandoffMissing(ledger) {
+    return ledger.applied !== undefined && !(ledger.durable !== undefined && ledger.durable.version === ledger.applied && ledger.durable.identity === ledger.bootIdentity);
+}
+export function buildConfigHandoff(ledger, since) {
+    return configHandoffMissing(ledger) && ledger.applied !== undefined && since !== undefined ? { state: "missing", version: ledger.applied, since } : undefined;
+}
+export function mintEngineSignal(deps) {
+    const verdict = readinessOf(deps);
+    const ds = deps.drainState;
+    const draining = ds === undefined ? undefined : drainingFactOf(ds);
+    const restart = deps.restartState?.();
+    const gen = deps.configApplyState?.();
+    return {
+        verdict,
+        ...(draining !== undefined ? { draining } : {}),
+        ...(restart !== undefined ? { restart } : {}),
+        ...(deps.config?.fleetGeneration !== undefined ? { generation: deps.config.fleetGeneration } : {}),
+        ...(deps.instanceId !== undefined ? { instanceId: deps.instanceId } : {}),
+        lease: deps.servingLease?.() ?? LEASE_NONE,
+        ...(gen !== undefined ? { configTargetVersion: gen.configTargetVersion, configAppliedVersion: gen.configAppliedVersion } : {}),
+    };
+}
+export function fleetMembershipKeys(s) {
+    if (s.generation === undefined)
+        return {};
+    const lease = s.lease;
+    switch (lease.state) {
+        case "granted":
+            return { generation: s.generation, leaseState: lease.state, leaseUntil: lease.leaseUntil };
+        case "none":
+        case "expired":
+        case "denied":
+            return { generation: s.generation, leaseState: lease.state };
+        default: {
+            const unhandled = lease;
+            throw new Error(`engine signal: unknown lease state ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+export function drainingFlag(s) {
+    return !s.verdict.ready && s.verdict.reasons.includes("draining");
+}
+export function restartActionable(s) {
+    return s.restart !== undefined && s.restart.withheld !== true;
+}
+//# sourceMappingURL=engine-signal.js.map

package/dist/fleet/serving-lease.d.ts

@@ -0,0 +1,47 @@
+import { type CenterCapabilities } from "@sema-agent/settings-schema/fleet";
+import { type CenterEndpoint } from "../config-center/center-request.js";
+import { type DrainEntry } from "./drain-entry.js";
+import type { ServingLeaseView } from "./engine-signal.js";
+/** 续租请求的上界(ms)—— 与 fleet 心跳同量级(不在提交热路径上)。 */
+export declare const SERVING_LEASE_FETCH_TIMEOUT_MS = 5000;
+/** 黏性拒在数据根下的文件名。 */
+export declare const SERVING_LEASE_DENIED_FILE = "fleet-serving-lease-denied.json";
+export interface ServingLeaseClientOpts {
+    readonly center: CenterEndpoint & {
+        readonly worker: string;
+    };
+    readonly generation: string;
+    readonly instanceId: string;
+    /** 黏性拒落盘处(缺席 ⇒ 只在进程内黏,且按「位没落下」响亮,规则 3 末段)。 */
+    readonly dataRoot: string | undefined;
+    /** `T_max`(ms,`config.fleetLeaseOutageMaxMs`)。 */
+    readonly outageMaxMs: number;
+    /** 唯一排空入口(装配层接 `drainState.enter`)。 */
+    readonly drain: (entry: DrainEntry) => void;
+    /** 被拒那一拍的排空窗(装配层接 `config.drainGraceMs` —— 期限在进入排空那一拍定死)。 */
+    readonly drainWindowMs: () => number;
+    readonly fetchImpl?: typeof fetch;
+    readonly logger?: {
+        info: (m: string, d?: Record<string, unknown>) => void;
+        warn: (m: string, d?: Record<string, unknown>) => void;
+        error: (m: string, d?: Record<string, unknown>) => void;
+    };
+    /** 测试注入:单调钟 / 挂钟(缺省 `performance.now` / `Date.now`)。 */
+    readonly clock?: {
+        readonly mono: () => number;
+        readonly epoch: () => number;
+    };
+}
+export interface ServingLeaseClient {
+    /** 一次中心能力读数(`undefined` = `undeclared`,中心没宣告 = 不支持)。每一次读数调一次;`unreadable` 不是读数,不调(`fleet-client.ts` `capabilityReadingOf`)。 */
+    noteCenterCapabilities(caps: CenterCapabilities | undefined): void;
+    /** 此刻的租约读数(铸点与准入判读它)。 */
+    view(): ServingLeaseView;
+    /** 起步读黏性拒(装配层在唯一排空入口装好之后调一次)。 */
+    resumeStickyDenial(): void;
+    /** 立刻续一次(测试 / 能力位刚出现时用;单飞)。 */
+    renewNow(): Promise<void>;
+    stop(): void;
+}
+export declare function createServingLeaseClient(o: ServingLeaseClientOpts): ServingLeaseClient;
+//# sourceMappingURL=serving-lease.d.ts.map