@sema-agent/server 7.120.0 → 7.121.0

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

package/dist/fleet-client.js

@@ -1,6 +1,7 @@
-import { InstanceAnnouncement, UsageReport, DEFAULT_HEARTBEAT_MS } from "@sema-agent/settings-schema/fleet";
-import { buildDisplaySafeUrl } from "./trace/redact.js";
+import { InstanceAnnouncement, UsageReport, DEFAULT_HEARTBEAT_MS, readCapabilityReading } from "@sema-agent/settings-schema/fleet";
+import { drainingFlag, fleetMembershipKeys } from "./fleet/engine-signal.js";
 import { centerFetch, centerLaneConfigured } from "./config-center/center-request.js";
+import { recordFailOpen } from "./observability/fail-open.js";
 export const FLEET_USAGE_KEY_CAP = 1024;
 export const FLEET_CLIENT_FETCH_TIMEOUT_MS = 5000;
 export class FleetUsageAccumulator {
@@ -74,6 +75,16 @@ async function rejectionSnippet(res) {
         return "";
     }
 }
+async function capabilityReadingOf(res) {
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        return { kind: "unreadable", why: "body", detail: err instanceof Error ? err.message : String(err) };
+    }
+    return readCapabilityReading(body);
+}
 export function startFleetClient(opts) {
     const f = opts.fetchImpl ?? fetch;
     const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
@@ -81,28 +92,55 @@ export function startFleetClient(opts) {
     const send = (route, method, json) => centerFetch(opts.center, { kind: route }, { method, json, timeoutMs: FLEET_CLIENT_FETCH_TIMEOUT_MS, fetchImpl: f });
     let stopped = false;
     let failStreak = 0;
+    let unreadableStreak = 0;
     const address = opts.advertiseAddress;
     const announceOnce = async () => {
         if (stopped || address === undefined)
             return;
         try {
-            const verdict = opts.readiness();
-            const restart = opts.restart();
+            const signal = opts.signal();
             const modelRefusals = opts.modelRefusals();
             const body = {
                 instanceId: opts.instanceId,
                 worker: opts.center.worker,
                 address,
                 version: opts.version,
-                ready: verdict.ready,
-                draining: !verdict.ready && verdict.reasons.includes("draining"),
+                ready: signal.verdict.ready,
+                draining: drainingFlag(signal),
                 heartbeatMs,
-                ...(restart !== undefined ? { restart } : {}),
+                ...(signal.restart !== undefined ? { restart: signal.restart } : {}),
                 ...(modelRefusals !== undefined ? { modelRefusals } : {}),
+                ...fleetMembershipKeys(signal),
             };
             const { res } = await send("fleet-instances", "POST", body);
             if (!res.ok)
                 throw new Error(`announce ${res.status}${await rejectionSnippet(res)}`);
+            if (opts.onCenterCapabilities !== undefined) {
+                const reading = await capabilityReadingOf(res);
+                switch (reading.kind) {
+                    case "declared":
+                    case "undeclared":
+                        unreadableStreak = 0;
+                        opts.onCenterCapabilities(reading.kind === "declared" ? reading.capabilities : undefined);
+                        break;
+                    case "unreadable":
+                        recordFailOpen("server.fleet.announce-reply-unreadable", `why=${reading.why} leaseState=${signal.lease.state}`);
+                        unreadableStreak += 1;
+                        if (unreadableStreak === 1) {
+                            opts.logger?.warn("fleet_announce_reply_unreadable", {
+                                status: res.status,
+                                why: reading.why,
+                                ...(reading.detail !== undefined ? { error: reading.detail } : {}),
+                                note: "the fleet center's heartbeat reply is not a capability reading (unreadable body, not an object, or a malformed capabilities value) — no reading taken; the last one stands (the serving lease keeps its state and outage clock)",
+                            });
+                        }
+                        break;
+                    default: {
+                        const unhandled = reading;
+                        throw new Error(`heartbeat reply: unknown capability reading ${JSON.stringify(unhandled)}`);
+                    }
+                }
+            }
             if (failStreak > 0)
                 opts.logger?.info("fleet_announce_recovered", { after: failStreak });
             failStreak = 0;
@@ -156,7 +194,7 @@ export function startFleetClient(opts) {
     };
     const announcing = address !== undefined;
     if (announcing)
-        void announceNow();
+        queueMicrotask(() => void announceNow());
     const hb = announcing ? setInterval(() => void announceNow(), heartbeatMs) : undefined;
     hb?.unref?.();
     const uw = opts.usage ? setInterval(() => void flushUsage(), usageWindowMs) : undefined;
@@ -190,29 +228,15 @@ export function startFleetClient(opts) {
     };
     return { announceNow, stopRouting, flushFinalUsage };
 }
-export function startFleetClientFromEnv(cfg, opts) {
+export function startFleetClientFromConfig(cfg, opts) {
     const cc = cfg.configCenter;
-    const raw = opts.advertiseAddress ?? process.env.FLEET_ADVERTISE_ADDRESS;
-    const address = raw === undefined || raw === "" ? undefined : raw;
-    if (address !== undefined && cc?.baseUrl && cc.credential.declared) {
-        let parsed;
-        try {
-            parsed = new URL(address);
-        }
-        catch {
-            parsed = undefined;
-        }
-        if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
-            throw new Error(`FLEET_ADVERTISE_ADDRESS must be a parseable http(s) base URL (e.g. "http://10.0.0.5:8090"); got "${buildDisplaySafeUrl(address)}" — the fleet center rejects any other shape on every announce`);
-        }
-    }
+    const address = cfg.fleetAdvertiseAddress;
     if (!centerLaneConfigured(cfg)) {
         if (address !== undefined && cc?.baseUrl && cc.credential.declared) {
             opts.logger?.warn("fleet_client_no_worker_scope", { note: "FLEET_ADVERTISE_ADDRESS set but SEMA_REGISTRY_WORKER missing — announce needs the worker (dispatch key); fleet client not started" });
         }
         return undefined;
     }
-    const lane = cfg.configCenter;
-    return startFleetClient({ ...opts, center: { baseUrl: lane.baseUrl, credential: lane.credential, worker: lane.worker }, advertiseAddress: address });
+    return startFleetClient({ ...opts, center: cfg.configCenter, advertiseAddress: address });
 }
 //# sourceMappingURL=fleet-client.js.map

package/dist/http/approval-sweeps.js

@@ -6,7 +6,7 @@ import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
 import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
 import { hasServiceAuth } from "./dispatch.js";
 import { gatedPrincipal } from "./principal-gate.js";
-import { readinessOf, billableRefusalOf } from "./readiness.js";
+import { admissionRefusalOf, readinessOf } from "./readiness.js";
 import { readResumeCtx } from "./resume-ctx-read.js";
 import { storedBodyReplayRefusal } from "./checkpoint-ctx.js";
 const BLOCKED_SCALAR_KEYS = ["errorCode", "blockedBy", "field", "reason", "count", "cap", "index"];
@@ -107,11 +107,9 @@ export function createApprovalSweeps(ctx) {
         if (!hasServiceAuth(deps.config) && !deps.config.allowUnauthedWrites) {
             return { status: 503, body: { error: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions", errorCode: "auth.service_token_required" } };
         }
-        const readiness = readinessOf(deps);
-        if (!readiness.ready) {
-            const refusal = billableRefusalOf(readiness, deps.drainState?.reason);
+        const refusal = admissionRefusalOf(readinessOf(deps), deps.servingLease?.(), "hitl-answer");
+        if (refusal !== undefined)
             return { status: refusal.status, body: refusal.body };
-        }
         if (deps.costQuota && req.httpReq) {
             const quotaPrincipal = gatedPrincipal(req.httpReq, deps.config);
             if (quotaPrincipal !== undefined) {

package/dist/http/dispatch.js

@@ -3,9 +3,11 @@ import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isDestructiveSessio
 import { publicStoreProbeError } from "../store-live-probe.js";
 import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
 import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
-import { READ_CREDENTIAL_ROUTES, PUBLIC_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath } from "./route-table.js";
+import { READ_CREDENTIAL_ROUTES, PUBLIC_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, billableKindOf, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath } from "./route-table.js";
 import { sendJson, sendError, isSseResponse } from "./send.js";
-import { readinessOf, healthReadinessKeys, sendReadyz, billableRefusalOf, sendBillableRefusal } from "./readiness.js";
+import { admissionRefusalOf, readinessOf, healthReadinessKeys, sendReadyz, sendBillableRefusal } from "./readiness.js";
+import { fleetMembershipKeys, mintEngineSignal, restartActionable } from "../fleet/engine-signal.js";
+import { buildHealthSelfReport } from "./health-self-report.js";
 import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal, sendUnauthorized, verifiedIdentitySource } from "./principal-gate.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function hasServiceAuth(config) {
@@ -113,7 +115,7 @@ export function createDispatch(ctx) {
             return;
         }
         if (req.method === "GET" && url === "/health") {
-            const restart = deps.restartState?.();
+            const signal = mintEngineSignal(deps);
             const configHash = createHash("sha256")
                 .update(JSON.stringify({ model: deps.config.model.id, sessionBackend: deps.config.sessionBackend, dbBackend: deps.config.dbBackend, dataRoot: deps.config.localDataRoot, configProvider: deps.config.configProvider, remoteExec: deps.config.remoteExec?.provider, port: deps.config.port }))
                 .digest("hex")
@@ -121,24 +123,26 @@ export function createDispatch(ctx) {
             sendJson(res, 200, {
                 status: "ok",
                 ...(typeof deps.capabilities?.version === "string" ? { version: deps.capabilities.version } : {}),
-                ...(deps.drainState?.draining ? { draining: true, ...(deps.drainState.since ? { drainingSince: deps.drainState.since } : {}), ...(deps.drainState.reason ? { drainReason: deps.drainState.reason } : {}) } : {}),
+                ...(deps.drainState?.draining ? { draining: true, ...(deps.drainState.since ? { drainingSince: deps.drainState.since } : {}) } : {}),
                 ...(deps.drainState?.inflight ? { inflight: deps.drainState.inflight() } : {}),
                 ...(deps.storePosture?.degradedReason !== undefined ? { durable: false, storeDegraded: true } : {}),
-                ...healthReadinessKeys(readinessOf(deps)),
+                ...healthReadinessKeys(signal.verdict),
                 model: deps.config.model.id,
                 sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend,
                 sessions: deps.runner.sessions.size,
                 ...(deps.instanceId ? { instanceId: deps.instanceId } : {}),
+                ...fleetMembershipKeys(signal),
                 ...(deps.config.localDataRoot ? { dataRoot: deps.config.localDataRoot } : {}),
                 configHash,
                 pid: process.pid,
                 startedAt: PROCESS_STARTED_AT_MS,
                 port: deps.config.port,
                 ...(deps.config.directDoorActive ? { directDoorActive: true } : {}),
-                ...(restart ? { restartRequired: true, restart } : {}),
+                ...buildHealthSelfReport(deps, hasServiceAuth(deps.config)),
+                ...(signal.restart ? { ...(restartActionable(signal) ? { restartRequired: true } : {}), restart: signal.restart } : {}),
                 ...(() => {
-                    const stuck = deps.planeDeferredState?.();
-                    return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
+                    const configHandoff = deps.configHandoffState?.();
+                    return configHandoff ? { configHandoff } : {};
                 })(),
                 ...(() => {
                     const gen = deps.configApplyState?.();
@@ -173,7 +177,7 @@ export function createDispatch(ctx) {
             return;
         }
         if (req.method === "GET" && url === "/readyz") {
-            sendReadyz(res, readinessOf(deps));
+            sendReadyz(res, mintEngineSignal(deps).verdict);
             return;
         }
         if (req.method === "GET" && (url === "/metrics" || url === "/metrics/summary" || url === "/metrics/plan-cache")) {
@@ -244,10 +248,11 @@ export function createDispatch(ctx) {
             sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions");
             return;
         }
-        if (req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
-            const verdict = readinessOf(deps);
-            if (!verdict.ready) {
-                sendBillableRefusal(res, billableRefusalOf(verdict, deps.drainState?.reason));
+        const billableKind = req.method === "POST" && !isMethodDispatchedSubmitPath(url) ? billableKindOf(url) : undefined;
+        if (billableKind !== undefined) {
+            const refusal = admissionRefusalOf(readinessOf(deps), deps.servingLease?.(), billableKind);
+            if (refusal !== undefined) {
+                sendBillableRefusal(res, refusal);
                 return;
             }
         }

package/dist/http/health-self-report.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `GET /health` 的**自报位**(7.121.0)—— `auth` / `operator` / `center` 三键:壳在**带凭据之前**要知道的三件部署事实
+ * (这台引擎要不要凭据、认哪几类、能不能附着身份;有没有运维方可找;接着哪个中心、会话会不会出现在那个中心的 web 面)。
+ *
+ * ## 规则(一条):自报位是**投影**,不是第二份规则
+ * 每一位读的是**门本身读的那只谓词 / 那只取值口**,本模块不判任何东西:
+ *  · `auth.required` = 全局凭据门的武装谓词(`hasServiceAuth`,由 `dispatch.ts` 交进来 —— 门与本位读同一次求值的同一只函数);
+ *  · `auth.kinds` = {@link IDENTITY_SOURCES}(`verifiedIdentitySource` 的回值闭集)里,这台部署的装配**能**回的那几个词:
+ *    `service_token` ⇐ 全局门武装(`systemFor` 只在配了 service token 时回得出值)· `sso` ⇐ 鉴权桥装了(入口预认证只在
+ *    `registryJwtVerifier` 在场时挂身份)· `direct_door_jwt` ⇐ 直连门开着(`verifiedIdentitySource` 那一臂的第一个合取项);
+ *  · `auth.identityAttach` = kinds 里有没有**带调用方身份**的一类({@link carriesCallerIdentity},穷举):`service_token` 认的是系统
+ *    (`systemFor` 回系统名或 null),不是人;
+ *  · `operator` = 能力事实 `operatorLane`(operator 面族的 501 门读的同一只;名单本身不上 wire);
+ *  · `center.issuer` = 鉴权桥 issuer 的唯一取值 `authBridgeIssuerOf`(装配 `boot/stage-09-leader.ts` 与 caps `centerWiring.issuer` 同读);
+ *  · `center.webBaseUrl` = 运维旋钮 `SEMA_REGISTRY_WEB_URL`(`config.configCenter.webBaseUrl`,接了中心才挂;起服时已判成固定基址);
+ *  · `center.sessionsVisible` = 中心的 web 面能不能列出本引擎的会话 —— 四件接线事实全在才可能:中心车道配齐(`centerLaneConfigured`,
+ *    租约 / 用量 / 公告同一只谓词)∧ 公告地址在(配置席 `fleetAdvertiseAddress`:web 面只拨中心登记过的实例地址)∧ 鉴权桥在(web 面带的是
+ *    中心铸的中继令牌,不带 service token)∧ 会话枚举面在(事实 `sessionList`,web 面中继 `GET /v1/sessions`);缺任一 ⇒ `false`。
+ *    四件齐时:多租户(`REQUIRE_PRINCIPAL`)每条会话都落着验过的属主 ⇒ `true`;单用户形下一条会话归谁取决于提交它的那次请求带没带
+ *    身份(web 面只列调用人自己的会话)—— 部署级答不了 ⇒ `"unknown"`。
+ *
+ * ## 无鉴权面
+ * `/health` 排在凭据门之前、缺省全网卡监听:本模块只出闭集词、布尔与运维要发布的 URL。两只 URL 值都过 display-safe 律
+ * (`buildDisplaySafeUrl`,所有展示面 URL 的同一个铸点):userinfo 落地、query 值成记号、尾斜杠折掉 —— issuer 的来源
+ * (`AUTH_BRIDGE_ISSUER` / `SEMA_REGISTRY_URL`)起服时不判凭据形,这一道是它上无鉴权面的唯一闸。令牌、名单、worker 名、凭证一概不上。
+ *
+ * ## 在场律
+ * 三键**恒在场**;缺席 = 老 worker(≤7.120.x)。`center.issuer` / `center.webBaseUrl` 缺席即缺席(没有鉴权桥 / 没配旋钮),不拼不猜。
+ */
+import type { FlatServiceDeps } from "./server.js";
+import { type IdentitySource } from "./principal-gate.js";
+/** `auth.identityAttach` 的词表。 */
+export declare const IDENTITY_ATTACH_WORDS: readonly ["available", "unavailable"];
+export type IdentityAttach = (typeof IDENTITY_ATTACH_WORDS)[number];
+/** `operator` 的词表。 */
+export declare const OPERATOR_PRESENCE_WORDS: readonly ["present", "absent"];
+export type OperatorPresence = (typeof OPERATOR_PRESENCE_WORDS)[number];
+/** `center.sessionsVisible` 的值域(两个布尔 + 一个词;`"unknown"` = 接线齐了,但会话归谁要看提交它的那次请求)。 */
+export declare const SESSIONS_VISIBLE_VALUES: readonly [true, false, "unknown"];
+export type SessionsVisible = (typeof SESSIONS_VISIBLE_VALUES)[number];
+/** 三键的 wire 形(纯数据)。 */
+export interface HealthSelfReport {
+    readonly auth: {
+        readonly required: boolean;
+        readonly kinds: readonly IdentitySource[];
+        readonly identityAttach: IdentityAttach;
+    };
+    readonly operator: OperatorPresence;
+    readonly center: {
+        readonly issuer?: string;
+        readonly webBaseUrl?: string;
+        readonly sessionsVisible: SessionsVisible;
+    };
+}
+/**
+ * 三键的**唯一铸点**(`build*`:纯数据)。`credentialGateArmed` 由 `dispatch.ts` 交进来 —— 它是全局凭据门自己的那一句
+ * (`hasServiceAuth`),本模块不另求一遍(另求就是第二个写者)。
+ */
+export declare function buildHealthSelfReport(deps: Pick<FlatServiceDeps, "config" | "registryJwtVerifier" | "sessionStorage" | "runStore">, credentialGateArmed: boolean): HealthSelfReport;
+//# sourceMappingURL=health-self-report.d.ts.map