@sema-agent/server 7.119.0 → 7.121.0

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

package/dist/fleet/serving-lease.js

@@ -0,0 +1,235 @@
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SERVING_LEASE_TTL_DEFAULT_MS, readServingLeaseResponse } from "@sema-agent/settings-schema/fleet";
+import { centerFetch } from "../config-center/center-request.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { leaseDrainActionId } from "./drain-entry.js";
+export const SERVING_LEASE_FETCH_TIMEOUT_MS = 5_000;
+export const SERVING_LEASE_DENIED_FILE = "fleet-serving-lease-denied.json";
+const RENEW_MIN_INTERVAL_MS = 1_000;
+function denialReasonOf(d) {
+    switch (d.from) {
+        case "center":
+        case "data-root":
+            return d.reason;
+        case "data-root-unreadable":
+            return "unreadable_record";
+        default: {
+            const unhandled = d;
+            throw new Error(`serving lease: unknown denial source ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function denialLeadOf(d) {
+    switch (d.from) {
+        case "center":
+            return `the fleet center denied this instance's serving lease (${d.reason})`;
+        case "data-root":
+            return `the fleet center denied this generation's serving lease earlier (${d.reason}) and the data root remembers it`;
+        case "data-root-unreadable":
+            return "the persisted lease record could not be read; treated as denied (fail-closed) — delete the record only if this generation is still meant to serve";
+        default: {
+            const unhandled = d;
+            throw new Error(`serving lease: unknown denial source ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+export function createServingLeaseClient(o) {
+    const mono = o.clock?.mono ?? (() => performance.now());
+    const epoch = o.clock?.epoch ?? Date.now;
+    const f = o.fetchImpl ?? fetch;
+    const stickyPath = o.dataRoot === undefined ? undefined : join(o.dataRoot, SERVING_LEASE_DENIED_FILE);
+    let enabled = false;
+    let enabledAtMono = 0;
+    let denied = false;
+    let stopped = false;
+    let lease;
+    let nextInMs = SERVING_LEASE_TTL_DEFAULT_MS / 3;
+    let timer;
+    let inFlight;
+    let failStreak = 0;
+    const clear = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    };
+    const schedule = (ms) => {
+        clear();
+        if (stopped || denied || !enabled)
+            return;
+        timer = setTimeout(() => void renewNow(), Math.max(RENEW_MIN_INTERVAL_MS, ms));
+        timer.unref?.();
+    };
+    const persistDenial = (reason) => {
+        if (stickyPath === undefined) {
+            o.logger?.error("fleet_serving_lease_denial_not_persisted", { note: "no data root to remember the denial in — it holds in this process only; after a restart this instance serves until its first renewal is answered" });
+            return false;
+        }
+        const record = { worker: o.center.worker, generation: o.generation, reason, at: epoch() };
+        const tmp = `${stickyPath}.tmp-${process.pid}`;
+        try {
+            writeFileSync(tmp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+            renameSync(tmp, stickyPath);
+            return true;
+        }
+        catch (err) {
+            o.logger?.error("fleet_serving_lease_denial_not_persisted", { path: stickyPath, error: err instanceof Error ? err.message : String(err), note: "the denial holds in this process only; after a restart this instance serves until its first renewal is answered (the center denies again then)" });
+            return false;
+        }
+    };
+    const enterDenied = (denial) => {
+        if (denied)
+            return;
+        denied = true;
+        lease = undefined;
+        clear();
+        const reason = denialReasonOf(denial);
+        const sticky = denial.from !== "center" ? "from-data-root" : persistDenial(reason) ? "new" : "process-only";
+        if (sticky === "process-only")
+            recordFailOpen("server.fleet.denied-marker-unpersisted", `worker=${o.center.worker} generation=${o.generation}`);
+        o.logger?.warn("fleet_serving_lease_denied", {
+            generation: o.generation,
+            worker: o.center.worker,
+            reason,
+            sticky,
+            note: `${denialLeadOf(denial)} — draining now and stopping at the drain deadline; ${sticky === "process-only" ? "the denial could NOT be recorded in the data root, so a restart of this generation does not remember it" : "the denial is remembered across restarts of this generation"}`,
+        });
+        o.drain({ actionId: leaseDrainActionId(o.generation), deadlineAt: epoch() + o.drainWindowMs() });
+    };
+    const renewOnce = async () => {
+        if (stopped || denied || !enabled)
+            return;
+        const sendMono = mono();
+        const sendEpoch = epoch();
+        const request = { worker: o.center.worker, generation: o.generation, instanceId: o.instanceId };
+        let reading;
+        let why = "";
+        try {
+            const { res } = await centerFetch(o.center, { kind: "fleet-serving-lease" }, { method: "POST", json: request, timeoutMs: SERVING_LEASE_FETCH_TIMEOUT_MS, fetchImpl: f });
+            if (res.ok) {
+                reading = readServingLeaseResponse(await res.json().catch(() => undefined));
+                if (reading === undefined)
+                    why = "reply is not a serving-lease verdict";
+            }
+            else {
+                why = `HTTP ${res.status}`;
+            }
+        }
+        catch (err) {
+            why = err instanceof Error ? err.message : String(err);
+        }
+        if (reading === undefined || reading.verdict === "unknown") {
+            const unconfirmed = reading === undefined ? why : "verdict=unknown (the center holds no lifecycle object for this instance right now)";
+            recordFailOpen("server.fleet.serving-lease-unconfirmed", `worker=${o.center.worker} generation=${o.generation} why=${unconfirmed}`);
+            failStreak += 1;
+            if (failStreak === 1)
+                o.logger?.warn("fleet_serving_lease_unconfirmed", { error: unconfirmed, note: "the serving lease could not be renewed (the center is unreachable or did not confirm this instance) — this instance keeps serving until the lease expires and then for FLEET_LEASE_OUTAGE_MAX_MS more before it refuses new work (unconfirmed is never a denial)" });
+            schedule(nextInMs);
+            return;
+        }
+        if (failStreak > 0)
+            o.logger?.info("fleet_serving_lease_recovered", { after: failStreak });
+        failStreak = 0;
+        switch (reading.verdict) {
+            case "granted":
+                if (denied || !enabled)
+                    return;
+                lease = { expiresAtMono: sendMono + reading.ttlMs, leaseUntil: sendEpoch + reading.ttlMs };
+                nextInMs = reading.ttlMs / 3;
+                schedule(nextInMs);
+                return;
+            case "denied":
+                enterDenied({ from: "center", reason: reading.reason });
+                return;
+            default: {
+                const unhandled = reading;
+                throw new Error(`serving lease: unknown verdict ${JSON.stringify(unhandled)}`);
+            }
+        }
+    };
+    const renewNow = () => {
+        if (inFlight !== undefined)
+            return inFlight;
+        inFlight = renewOnce().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    return {
+        noteCenterCapabilities(caps) {
+            if (stopped || denied)
+                return;
+            const on = caps?.servingLease === true;
+            if (!on)
+                recordFailOpen("server.fleet.serving-lease-capability-absent", `worker=${o.center.worker} generation=${o.generation} was=${enabled ? "enabled" : "none"}`);
+            if (on && !enabled) {
+                enabled = true;
+                enabledAtMono = mono();
+                o.logger?.info("fleet_serving_lease_enabled", { generation: o.generation, worker: o.center.worker });
+                void renewNow();
+            }
+            else if (!on && enabled) {
+                enabled = false;
+                lease = undefined;
+                clear();
+                o.logger?.warn("fleet_serving_lease_disabled", { note: "the fleet center no longer announces the servingLease capability — the lease is out of effect (leaseState none) until it does again" });
+            }
+        },
+        view() {
+            if (denied)
+                return { state: "denied" };
+            if (!enabled)
+                return { state: "none" };
+            const now = mono();
+            if (lease !== undefined && now < lease.expiresAtMono)
+                return { state: "granted", leaseUntil: lease.leaseUntil };
+            const expiredAt = lease?.expiresAtMono ?? enabledAtMono;
+            return { state: "expired", pastOutageMax: now - expiredAt >= o.outageMaxMs };
+        },
+        resumeStickyDenial() {
+            if (stickyPath === undefined || denied)
+                return;
+            let text;
+            try {
+                text = readFileSync(stickyPath, "utf8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return;
+                o.logger?.error("fleet_serving_lease_denial_unreadable", { path: stickyPath, error: err instanceof Error ? err.message : String(err), note: "a remembered lease denial could not be read — treating this instance as denied (fail-closed); delete the file only if this generation is still meant to serve" });
+                enterDenied({ from: "data-root-unreadable" });
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = undefined;
+            }
+            const record = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+            if (record === undefined || typeof record.generation !== "string" || typeof record.worker !== "string") {
+                o.logger?.error("fleet_serving_lease_denial_unreadable", { path: stickyPath, note: "a remembered lease denial is malformed — treating this instance as denied (fail-closed); delete the file only if this generation is still meant to serve" });
+                enterDenied({ from: "data-root-unreadable" });
+                return;
+            }
+            if (record.worker !== o.center.worker || record.generation !== o.generation) {
+                o.logger?.info("fleet_serving_lease_denial_stale", { path: stickyPath, recorded: { worker: record.worker, generation: record.generation }, current: { worker: o.center.worker, generation: o.generation } });
+                try {
+                    rmSync(stickyPath, { force: true });
+                }
+                catch (err) {
+                    o.logger?.error("fleet_serving_lease_denial_stale_unremovable", { path: stickyPath, error: err instanceof Error ? err.message : String(err), note: "a stale lease denial of another generation could not be removed — it does not bind this generation; remove it by hand" });
+                }
+                return;
+            }
+            enterDenied({ from: "data-root", reason: typeof record.reason === "string" ? record.reason : "unknown_reason" });
+        },
+        renewNow,
+        stop() {
+            stopped = true;
+            clear();
+        },
+    };
+}
+//# sourceMappingURL=serving-lease.js.map

package/dist/fleet-client.d.ts

@@ -3,8 +3,8 @@
  * `/fleet`,center 端点 = sema-registry `/api/fleet/*`)。设计要点:
  *  - **可选分层(D3),两条环各自有门(S-866 ④)**:客户端在中心车道配齐时启动(`centerLaneConfigured` —— baseUrl + 声明了
  *    凭证 + worker,与租约管理器、用量累加器**同一只**谓词);**用量环**只要这三件;**公告环**(announce / 心跳 / 注销)另要
- *    `FLEET_ADVERTISE_ADDRESS` 显式声明(可达性是运维的话,不自猜:k8s pod IP / docker alias / 127.0.0.1:port 只有部署环境自己
- *    知道)。不配中心的部署零行为变化;配了中心而不公告的引擎只报用量、不注册(7.105.0 及以前它连用量都不报)。
+ *    配置席 `fleetAdvertiseAddress`(env `FLEET_ADVERTISE_ADDRESS`,`loadConfig` 解析一次;可达性是运维的话,不自猜:k8s pod IP /
+ *    docker alias / 127.0.0.1:port 只有部署环境自己知道)。不配中心的部署零行为变化;配了中心而不公告的引擎只报用量、不注册(7.105.0 及以前它连用量都不报)。
  *  - **announce=注册=心跳同形状幂等 upsert**:boot 后(listen 之后)POST 一次 + 每 heartbeatMs 续。
  *    `ready` / `draining` 两字段由**同一只**就绪谓词的同一次读铸(S-740:`http/readiness.ts` 的 `readinessOf`,
  *    与 `/health.ready`、`GET /readyz`、计费提交门同源):`ready = verdict.ready`(= roster 已落 ∧ ¬draining),
@@ -25,8 +25,8 @@
  *    向前合并不会双计 —— 只延迟,不丢量)。
  *  - 全部 fire-and-forget + swallow-guarded:fleet 面是运维旁路,绝不影响任务面;网络错误只 warn 一次/连败类。
  */
-import { UsageReport, type ModelRefusalsSignal, type RestartSignal } from "@sema-agent/settings-schema/fleet";
-import type { ReadinessVerdict } from "./http/readiness.js";
+import { UsageReport, type CapabilityReading, type CenterCapabilities, type ModelRefusalsSignal } from "@sema-agent/settings-schema/fleet";
+import { type EngineSignalFacts } from "./fleet/engine-signal.js";
 import { type CenterEndpoint } from "./config-center/center-request.js";
 /** Bound on distinct principal×model keys per window — a runaway/multi-tenant burst collapses into
  *  `__other__` instead of growing unbounded (same posture as budget.ts cardinalityGuard). */
@@ -79,15 +79,17 @@ export interface FleetClientOpts {
      *  S-866 ④:**缺席 = 公告环不装**(不注册、不心跳、不注销;`announceNow` 是空操作),用量环照装。 */
     advertiseAddress?: string | undefined;
     version: string;
-    /** S-740:就绪判(装配层接 `readinessOf(deployment)` —— HTTP 面读的同一个 deps 组)。每条公告现读**一次**,
-     *  `ready` 与 `draining` 两字段都由这一次读铸(不会撕裂成 `ready:true` + `draining:true`)。 */
-    readiness: () => ReadinessVerdict;
-    /** S-741:restart 信号(装配层接 `/health` 同一只取值口 `deployment.restartState`)。每条公告现读一次;`undefined` ⇒ 公告不带
-     *  `restart` 键。必填:心跳面没有「不知道要不要重启」这一形。 */
-    restart: () => RestartSignal | undefined;
+    /** 编排器片 2 件 1:引擎信号的**一只铸点**(装配层接 `mintEngineSignal(deployment)` —— `/health` 与 `/readyz` 读的同一只、同一个 deps 组)。
+     *  每条公告现铸**一次**,`ready` / `draining` / `restart` / 代际与租约三键 / 世代账都取自这一次(不会撕裂成 `ready:true` + `draining:true`,
+     *  也不会出现心跳与 `/health` 各算一份重启或租约)。修前是 `readiness` + `restart` 两只取值口(S-740 / S-741),合进这一只。 */
+    signal: () => EngineSignalFacts;
     /** S-768:模型拒因信号(装配层接 `/health` 同一只取值口 `deployment.modelRefusalsState`)。每条公告现读一次;`undefined` ⇒ 公告不带
      *  `modelRefusals` 键。必填:与 `restart` 同 —— 心跳面没有「不知道有没有拒」这一形(老引擎不发这个键,中心按 `version` 判「不可知」)。 */
     modelRefusals: () => ModelRefusalsSignal | undefined;
+    /** 编排器片 2:每一次**能力读数**交出去一次(装配层接服务租约客户端的 `noteCenterCapabilities`)。规则见 {@link capabilityReadingOf}:
+     *  只有 `declared`(交出宣告的位)与 `undeclared`(交 `undefined` = 老中心没宣告)是读数;`unreadable`(体读不出 / 不是对象 /
+     *  `capabilities` 键在场而形坏)不是读数 ⇒ 不调,上一次读数与它的钟原样。失败的公告同样不调(没听到 ≠ 没有)。 */
+    onCenterCapabilities?: (caps: CenterCapabilities | undefined) => void;
     usage?: FleetUsageAccumulator;
     heartbeatMs?: number;
     usageWindowMs?: number;
@@ -114,25 +116,39 @@ export interface FleetClient {
     flushFinalUsage: () => Promise<void>;
 }
 /**
- * Start the worker-side fleet loops. Caller has already gated on the center lane (startFleetClientFromEnv below).
+ * 心跳 2xx 答复读不成能力读数的原因 —— 一张闭集:`body` = 答复体本身读不出(空体 / 截断 / 非 JSON),其余两词 = 契约读器
+ * `readCapabilityReading` 的 `unreadable` 两因(`not-an-object` / `invalid-capabilities`)。
+ */
+export type AnnounceReplyFlaw = "body" | Extract<CapabilityReading, {
+    kind: "unreadable";
+}>["why"];
+/** 本仓对一次心跳答复的读法:契约三态,`unreadable` 的原因扩成 {@link AnnounceReplyFlaw}(`detail` = 读不出体时的那句错误,当数据交出)。 */
+export type AnnounceReplyReading = Exclude<CapabilityReading, {
+    kind: "unreadable";
+}> | {
+    readonly kind: "unreadable";
+    readonly why: AnnounceReplyFlaw;
+    readonly detail?: string;
+};
+/**
+ * Start the worker-side fleet loops. Caller has already gated on the center lane (startFleetClientFromConfig below).
  * The announce loop runs iff `advertiseAddress` is present; the usage loop iff `usage` is present (S-866 ④: the two
  * loops no longer share one gate).
  */
 export declare function startFleetClient(opts: FleetClientOpts): FleetClient;
 /**
- * Env/config gate (D3 可选分层;S-866 ④ 两条环各自有门): start when the center lane is configured —
+ * Config gate (D3 可选分层;S-866 ④ 两条环各自有门): start when the center lane is configured —
  * {@link centerLaneConfigured}(baseUrl + a DECLARED credential + worker — S-651: declared, not "currently readable": a token
  * file that is unreadable right now still starts the client, every request re-reads it), the SAME predicate the lease
  * manager and the usage accumulator use. The usage loop needs nothing more; the announce loop additionally needs the
- * operator's explicit reachable address (`FLEET_ADVERTISE_ADDRESS`; a malformed one refuses boot). Lane not configured →
- * undefined (zero behavior change for non-fleet deployments); an address set while only the worker is missing is warned
- * (half-configured announce).
+ * operator's explicit reachable address — the config seat `fleetAdvertiseAddress` (env `FLEET_ADVERTISE_ADDRESS`, parsed once by
+ * `loadConfig`: a malformed one refuses boot there). Lane not configured → undefined (zero behavior change for non-fleet
+ * deployments); an address set while only the worker is missing is warned (half-configured announce).
  */
-export declare function startFleetClientFromEnv(cfg: {
+export declare function startFleetClientFromConfig(cfg: {
     configCenter?: (CenterEndpoint & {
         worker?: string;
     }) | undefined;
-}, opts: Omit<FleetClientOpts, "center" | "advertiseAddress"> & {
-    advertiseAddress?: string | undefined;
-}): FleetClient | undefined;
+    fleetAdvertiseAddress?: string | undefined;
+}, opts: Omit<FleetClientOpts, "center" | "advertiseAddress">): FleetClient | undefined;
 //# sourceMappingURL=fleet-client.d.ts.map