@sema-agent/server 7.149.0 → 7.150.0

package/dist/deployment-governance.js

@@ -1,19 +1,6 @@
 import { join, posix } from "node:path";
 import { FileError, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, createTranscriptIntegrityPolicy, err, isAbsoluteForFamily, isProtectedWrite, ok, pathTargetValue, protectivePathTargetOf, } from "@sema-agent/core";
 import { createDurableAskPolicy, hasApprovalListIntent } from "./approval.js";
-export function createDurableQuestionGate(live) {
-    const durable = createDurableQuestionPolicy();
-    if (live === undefined)
-        return durable;
-    return {
-        async check(req) {
-            const answer = await durable.check(req);
-            if (answer.action !== "ask")
-                return answer;
-            return live.hasLiveContext() ? { action: "allow" } : answer;
-        },
-    };
-}
 export const SANDBOX_TREE_FAMILY = "posix";
 function writeTargetFormOf(req) {
     if (!isProtectedWrite(req))
@@ -125,7 +112,7 @@ export function buildApprovalGrantNotice(config) {
 export function createApprovalBaselinePolicy(config, seat) {
     switch (seat.kind) {
         case "durable":
-            return combinePolicies(createDurableQuestionGate(seat.question), createApprovalListPolicy(config, seat.exemption));
+            return combinePolicies(createDurableQuestionPolicy(), createApprovalListPolicy(config, seat.exemption));
         case "live":
             return createApprovalListPolicy(config, undefined);
         case "absent":

package/dist/device-ws-hub.d.ts

@@ -209,6 +209,7 @@ export interface DeviceWsHub {
     declaredSupports(deviceId: string): ReadonlySet<DeviceInstructionKind> | undefined;
     close(): Promise<void>;
 }
+export declare const DEVICE_MAX_PAYLOAD_PART_BYTES: number;
 /** per-remote 帽键的来源(闭集;指标 `device_preauth_key_total{source}` 与 cap-hit 行 `keySource` 同一张表)。 */
 export declare const DEVICE_PREAUTH_KEY_SOURCES: readonly ["socket", "xff", "fallback"];
 export type DevicePreAuthKeySource = (typeof DEVICE_PREAUTH_KEY_SOURCES)[number];

package/dist/device-ws-hub.js

@@ -5,7 +5,7 @@ import { WebSocketServer } from "ws";
 import { DEVICE_DRAINING_CODE, DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, assertDeviceIdShape, } from "./device-store.js";
 import { MAX_TIMER_DELAY_MS } from "./config-types.js";
 import { canonicalAddress, createTrustedProxySet } from "./net-address.js";
-import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
+import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, deviceProtocolRevisionRefusal, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
 const OUTCOME_UNKNOWN_SENTENCE = "outcome unknown — the command may have already executed on the device; verify its effect before re-running";
 const SETTLED_MEMO_MAX = 512;
 const DRAIN_RETRY_AFTER_SEC = 15;
@@ -27,6 +27,25 @@ function outcomeUnknown(why) {
     return { ok: false, errorCode: "outcome_unknown", message: `${why} — ${OUTCOME_UNKNOWN_SENTENCE}` };
 }
 const WRITE_PAYLOAD_KINDS = new Set(["writeFile", "writeFileExclusive", "writeFileGuarded", "appendFile"]);
+const PAYLOAD_CHUNK_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ t: "payload", gen: String(Number.MAX_SAFE_INTEGER), instructionId: mintInstructionId(), part: "chunk", offset: Number.MAX_SAFE_INTEGER, dataB64: "" }), "utf8");
+export const DEVICE_MAX_PAYLOAD_PART_BYTES = Math.floor((DEVICE_WS_LIMITS.maxFrameBytes - PAYLOAD_CHUNK_ENVELOPE_BYTES) / 4) * 3;
+const FRAME_TOO_LARGE = "frame_too_large";
+function encodeServerFrame(frame) {
+    const text = JSON.stringify(frame);
+    const bytes = Buffer.byteLength(text, "utf8");
+    return bytes <= DEVICE_WS_LIMITS.maxFrameBytes ? { ok: true, text } : { ok: false, bytes };
+}
+function frameTooLargeResult(kind, bytes) {
+    return {
+        kind: "never_started",
+        outcome: {
+            ok: false,
+            errorCode: "not_supported",
+            message: `[${FRAME_TOO_LARGE}] the ${kind} instruction frame would be ${bytes} bytes, over the device protocol's ${DEVICE_WS_LIMITS.maxFrameBytes}-byte frame cap — ` +
+                "it was never sent (the device transport drops a connection that carries a frame that size); keep a command and its arguments under the cap, and move large content into a file write (it travels in slices)",
+        },
+    };
+}
 const ALLOWED_SUCCESS_OUTCOME_KINDS = {
     exec: ["exec"],
     execStream: ["exec"],
@@ -145,14 +164,22 @@ export function createDeviceWsHub(options) {
             .catch((err) => logger?.error("device_audit_write_failed", { event, err: err instanceof Error ? err.message : String(err) }));
     }
     function sendServerFrame(conn, frame) {
+        const encoded = encodeServerFrame(frame);
+        if (!encoded.ok) {
+            logger?.error("device_ws_frame_over_cap", { deviceId: conn.deviceId, t: frame.t, bytes: encoded.bytes, cap: DEVICE_WS_LIMITS.maxFrameBytes });
+            return false;
+        }
+        return writeServerText(conn, frame.t, encoded.text);
+    }
+    function writeServerText(conn, t, text) {
         if (conn.ws.readyState !== conn.ws.OPEN)
             return false;
         try {
-            conn.ws.send(JSON.stringify(frame));
+            conn.ws.send(text);
             return true;
         }
         catch (err) {
-            logger?.warn("device_ws_send_failed", { deviceId: conn.deviceId, t: frame.t, err: err instanceof Error ? err.message : String(err) });
+            logger?.warn("device_ws_send_failed", { deviceId: conn.deviceId, t, err: err instanceof Error ? err.message : String(err) });
             return false;
         }
     }
@@ -301,11 +328,11 @@ export function createDeviceWsHub(options) {
         }, reconnectGraceMs);
         reconnectTimers.set(deviceId, timer);
     }
-    function rejectHello(conn, code, minProtocolVersion) {
+    function rejectHello(conn, code, version) {
         if (conn.handshakeTimer)
             clearTimeout(conn.handshakeTimer);
         conn.handshakeTimer = null;
-        sendServerFrame(conn, { t: "helloReject", code, ...(minProtocolVersion === undefined ? {} : { minProtocolVersion }) });
+        sendServerFrame(conn, { t: "helloReject", code, ...version });
         closeConn(conn, { releaseLease: false });
     }
     async function fenceConnection(conn) {
@@ -367,7 +394,10 @@ export function createDeviceWsHub(options) {
         if (draining || closed)
             return rejectHello(conn, "draining");
         if (frame.protocolVersion < DEVICE_MIN_PROTOCOL_VERSION || frame.protocolVersion > DEVICE_PROTOCOL_VERSION) {
-            return rejectHello(conn, "protocol_version_unsupported", DEVICE_MIN_PROTOCOL_VERSION);
+            const message = deviceProtocolRevisionRefusal(frame.protocolVersion);
+            logger?.warn("device_hello_version_rejected", { declared: frame.protocolVersion, minProtocolVersion: DEVICE_MIN_PROTOCOL_VERSION, protocolVersion: DEVICE_PROTOCOL_VERSION, message });
+            metrics?.inc("device_hello_rejected_total", { code: "protocol_version_unsupported" });
+            return rejectHello(conn, "protocol_version_unsupported", { minProtocolVersion: DEVICE_MIN_PROTOCOL_VERSION, message });
         }
         let idShapeOk = true;
         try {
@@ -860,8 +890,8 @@ export function createDeviceWsHub(options) {
     async function dispatch(input) {
         if (input.payloadPartBytes !== undefined) {
             const n = input.payloadPartBytes;
-            if (!Number.isSafeInteger(n) || n <= 0 || n > DEVICE_WS_LIMITS.maxFrameBytes) {
-                throw new Error(`device-ws: payloadPartBytes must be a positive safe integer ≤ ${DEVICE_WS_LIMITS.maxFrameBytes} (got ${String(n)})`);
+            if (!Number.isSafeInteger(n) || n <= 0 || n > DEVICE_MAX_PAYLOAD_PART_BYTES) {
+                throw new Error(`device-ws: payloadPartBytes must be a positive safe integer ≤ ${DEVICE_MAX_PAYLOAD_PART_BYTES} (the ${DEVICE_WS_LIMITS.maxFrameBytes}-byte frame cap after base64 and the chunk envelope; got ${String(n)})`);
             }
         }
         if (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs <= 0) {
@@ -963,7 +993,32 @@ export function createDeviceWsHub(options) {
             releaseSlot(deviceId);
             return abortedBeforeCommit();
         }
+        let args = input.args;
+        let body = null;
+        let sha = "";
+        if (input.payload !== undefined && WRITE_PAYLOAD_KINDS.has(input.kind)) {
+            body = Buffer.from(input.payload);
+            sha = createHash("sha256").update(body).digest("hex");
+            args = { ...input.args, contentLen: body.length, sha256: sha };
+        }
         const instructionId = mintInstructionId();
+        const instructionFrame = encodeServerFrame({
+            t: "instruction",
+            gen: conn.genStr,
+            instructionId,
+            rootSessionId: input.rootSessionId,
+            issuedSeq: conn.issuedSeq + 1,
+            kind: input.kind,
+            args,
+            ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+            ...(input.shellEnv === undefined ? {} : { shellEnv: input.shellEnv }),
+            timeoutMs: input.timeoutMs,
+        });
+        if (!instructionFrame.ok) {
+            releaseSlot(deviceId);
+            logger?.warn("device_instruction_frame_over_cap", { deviceId, kind: input.kind, bytes: instructionFrame.bytes, cap: DEVICE_WS_LIMITS.maxFrameBytes });
+            return frameTooLargeResult(input.kind, instructionFrame.bytes);
+        }
         conn.issuedSeq += 1;
         let resolve;
         const settled = new Promise((r) => {
@@ -996,26 +1051,7 @@ export function createDeviceWsHub(options) {
             resolve,
         };
         pending.set(instructionId, p);
-        let args = input.args;
-        let body = null;
-        let sha = "";
-        if (input.payload !== undefined && WRITE_PAYLOAD_KINDS.has(input.kind)) {
-            body = Buffer.from(input.payload);
-            sha = createHash("sha256").update(body).digest("hex");
-            args = { ...input.args, contentLen: body.length, sha256: sha };
-        }
-        const wrote = sendServerFrame(conn, {
-            t: "instruction",
-            gen: conn.genStr,
-            instructionId,
-            rootSessionId: input.rootSessionId,
-            issuedSeq: conn.issuedSeq,
-            kind: input.kind,
-            args,
-            ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
-            ...(input.shellEnv === undefined ? {} : { shellEnv: input.shellEnv }),
-            timeoutMs: input.timeoutMs,
-        });
+        const wrote = writeServerText(conn, "instruction", instructionFrame.text);
         if (body !== null)
             sendPayloadSequence(conn, instructionId, body, input.payloadPartBytes ?? DEVICE_WS_LIMITS.defaultPayloadPartBytes, sha);
         metrics?.inc("device_instruction_dispatched_total", { kind: input.kind });

package/dist/device-ws-protocol.d.ts

@@ -4,14 +4,25 @@ export declare const DEVICE_WS_PATH = "/v1/device/ws";
 /**
  * 本 server 铸/认的协议**修订号**(wire 上的 `protocolVersion`)。
  *
- * 规则(§5.6):加帧 / 加字段 = additive 不升号;改语义 = 升号;**executor → server 方向的闭集加词也升号** —— 修订号是 executor 在发 hello 之前
- * 唯一能读到的「这台 server 受理什么」的事实(challenge 帧带它),所以 server 受理的词集必须是修订号的函数
- * ({@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION},协议文档同名表),不另发第二份列表。闭集变了而修订号没变 = 同一个修订号两种受理集
- * (7.132.0 给结局码加 `liveness_no_output` 时没抬号,本版补到 2)。类型锁:抬了号而表没有这一行 ⇒ 编译红。
+ * 规则(真源 = 协议文档 `docs/DEVICE-EXECUTOR-PROTOCOL.md` §2.1「Protocol revisions」段,此处只转述):加帧 / 加字段 = additive 不升号;
+ * 其余变更一律升号并在增量表加一行,已发布的行不改 —— **server 受理的闭集(executor → server 方向,今天 = 结局 `errorCode` 词集)加词 = 升号**,
+ * **语义变更(server 下发的帧意思变了)= 升号**。修订号是 executor 在发 hello 之前唯一能读到的「这台 server 受理什么、发来的帧是什么意思」的事实
+ * (challenge 帧带它),所以 server 受理的词集必须是修订号的函数({@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION},协议文档同名表),不另发第二份列表;
+ * 闭集变了而修订号没变 = 同一个修订号两种受理集(7.132.0 给结局码加 `liveness_no_output` 时没抬号,7.136.0 补到 2)。类型锁:抬了号而表没有这一行 ⇒ 编译红。
  */
 export declare const DEVICE_PROTOCOL_VERSION: DeviceProtocolRevision;
-/** 低于此版本 ⇒ `helloReject: protocol_version_unsupported`(响亮拒,不静默降级,[ref])。兼容窗 = [MIN, 当前]。 */
-export declare const DEVICE_MIN_PROTOCOL_VERSION = 1;
+/**
+ * 受理下沿:低于它 ⇒ `helloReject: protocol_version_unsupported`(带 `minProtocolVersion` 与一句 {@link deviceProtocolRevisionRefusal},响亮拒,不静默降级,[ref])。
+ * 兼容窗 = [MIN, 当前]。律(协议文档 §2.1 规则句):升号的变更旧修订的 executor 守不住 ⇒ 同一版把下沿抬到那一修订号 —— 旧 executor 在 hello 被拒一次,
+ * 而不是逐调用失败。今天 = 5:修订号 5 起路径只锚不折(下沿理由见 {@link DEVICE_FLOOR_CHANGE}),写给修订号 ≤ 4 的 executor 认的是折过的路径。
+ * 这是**本 server** 的受理下沿,不是 executor 协商时的下界(executor 一侧修订号是累积的:实现了 5 的照样能按 4 服务老 server)。
+ */
+export declare const DEVICE_MIN_PROTOCOL_VERSION: DeviceProtocolRevision;
+/**
+ * `protocol_version_unsupported` 的那一句 `message`(帧上与服务端 warn 行同一句;executor 可原样示人)。声明值在窗外只有两种:低于下沿 / 高于上沿。
+ * 握手之前的帧,任何能开 socket 的对端都读得到 ⇒ 句里只有修订号与下沿引入的版本,不带本进程的服务版本号。
+ */
+export declare function deviceProtocolRevisionRefusal(declared: number): string;
 /** 签名的 domain tag —— 换域即换 tag,防止别处的 Ed25519 签名被拿来当握手用。 */
 export declare const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
 /**
@@ -76,6 +87,7 @@ export declare const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION: {
     readonly 2: readonly ["liveness_no_output"];
     readonly 3: readonly ["name_too_long"];
     readonly 4: readonly ["symlink_loop"];
+    readonly 5: readonly [];
 };
 /** 本包认得的协议修订号(= 增量表的行键)。 */
 export type DeviceProtocolRevision = keyof typeof DEVICE_OUTCOME_ERROR_CODES_BY_REVISION;
@@ -275,10 +287,12 @@ export type DeviceHelloAckFrame = {
     chunkGapTimeoutMs?: number;
     executionCeilingGraceMs?: number;
 };
+/** `minProtocolVersion` 与 `message` 只出现在 `protocol_version_unsupported` 上(加字段 = additive,不升号;协议文档 §1.4 / §2.3)。 */
 export type DeviceHelloRejectFrame = {
     t: "helloReject";
     code: DeviceHelloRejectCode;
     minProtocolVersion?: number;
+    message?: string;
 };
 /**
  * helloAck 六个数值位的**合法域**(闭区间、整数)—— 一处成文:汇聚端创建时按它校验(越界 ⇒ 响亮拒启,不夹取、不换成缺省),

package/dist/device-ws-protocol.js

@@ -1,8 +1,14 @@
 import { createPublicKey, randomBytes, randomInt, verify as edVerify } from "node:crypto";
 import { MAX_TIMER_DELAY_MS, inWholeNumberBounds, wholeNumberBoundsRule } from "./config-types.js";
 export const DEVICE_WS_PATH = "/v1/device/ws";
-export const DEVICE_PROTOCOL_VERSION = 4;
-export const DEVICE_MIN_PROTOCOL_VERSION = 1;
+export const DEVICE_PROTOCOL_VERSION = 5;
+export const DEVICE_MIN_PROTOCOL_VERSION = 5;
+const DEVICE_FLOOR_CHANGE = 'since server 7.150.0 every path an instruction carries (args.path, args.paths, cwd) arrives unfolded, with "." / ".." / empty segments kept for the device\'s filesystem to resolve';
+export function deviceProtocolRevisionRefusal(declared) {
+    return declared < DEVICE_MIN_PROTOCOL_VERSION
+        ? `device protocol revision ${declared} is below the lowest revision this server accepts (${DEVICE_MIN_PROTOCOL_VERSION}): ${DEVICE_FLOOR_CHANGE}; upgrade the executor to one that declares revision ${DEVICE_MIN_PROTOCOL_VERSION} or above`
+        : `device protocol revision ${declared} is above the highest revision this server speaks (${DEVICE_PROTOCOL_VERSION}): declare the highest revision you implement that is not above challenge.protocolVersion`;
+}
 export const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
 export const DEVICE_WS_LIMITS = {
     maxFrameBytes: 1024 * 1024,
@@ -68,6 +74,7 @@ export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
     2: ["liveness_no_output"],
     3: ["name_too_long"],
     4: ["symlink_loop"],
+    5: [],
 };
 export function deviceOutcomeErrorCodesAt(revision) {
     if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {

package/dist/engine-identity.d.ts

@@ -9,7 +9,7 @@
  * 落点之前引擎自己按 `spec.principal` 分的那几面按人分(同一个人的各场景在那几面互见)—— 本仓镜像这几面的读口(工作流读面、后台登记簿的停止标记、
  * leader 子任务的 spec)同读 {@link taskSpecIdentityOf},读到的就是引擎写下的那一个值,不各写一份。
  */
-import type { Person, Subject, SubjectParts } from "./owner-brands.js";
+import { type Person, type Subject, type SubjectParts } from "./owner-brands.js";
 /** 引擎交界的身份(本仓的类型;二元)。 */
 export interface EngineIdentity {
     readonly principal: Person | undefined;
@@ -25,4 +25,10 @@ export declare function specIdentityOf(parts: SubjectParts | undefined): EngineI
 export declare function taskSpecIdentityOf(parts: SubjectParts | undefined): {
     readonly principal?: string;
 };
+/**
+ * 引擎按身份分的那几面落下的 **scope**(core 写侧 `spec.principal ?? "default"` 的同一条读法;工作流行的 `scope` 列就是它):一只主体 ⇒ 落点 {@link taskSpecIdentityOf}
+ * 写下的人;匿名 ⇒ 单机形的租户键 `"default"`(`owner-faces.ts` 的 `LEGACY_UNOWNED_AMNESTY_TENANT`)。读者只在属主存取器(`http/owner-access.ts`):工作流按 id 的门
+ * (调用方一侧按它换成引擎身份再与行的 scope 比)与工作流列表的属主过滤同读这一只;承认之后 journal / 流按承认的那一行的 scope 读。
+ */
+export declare function engineScopeOf(subject: Subject | undefined): string;
 //# sourceMappingURL=engine-identity.d.ts.map

package/dist/engine-identity.js

@@ -1,3 +1,5 @@
+import { partsOf } from "./owner-brands.js";
+import { LEGACY_UNOWNED_AMNESTY_TENANT } from "./owner-faces.js";
 export function specIdentityOf(parts) {
     if (parts === undefined)
         return { principal: undefined };
@@ -7,4 +9,7 @@ export function taskSpecIdentityOf(parts) {
     const { principal } = specIdentityOf(parts);
     return principal === undefined ? {} : { principal };
 }
+export function engineScopeOf(subject) {
+    return taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)).principal ?? LEGACY_UNOWNED_AMNESTY_TENANT;
+}
 //# sourceMappingURL=engine-identity.js.map

package/dist/field-conflict.d.ts

@@ -10,12 +10,12 @@ export interface FieldConflictCoordinates {
     readonly cascade_verify: "verify" | "cascade" | "sandboxImageProfile" | "resumeAt" | "suggestNextPrompts";
     readonly image_profile: "capabilitiesNeeded" | "sandboxImageProfile";
     readonly resume_anchor: "resumeAtMode" | "resumeAt";
-    readonly system_prompt_fold: "appendSystemPrompt" | "settings.outputStyle";
+    readonly system_prompt_fold: "appendSystemPrompt" | "projectId" | "settings.outputStyle";
     readonly file_history_restore: "fileHistory" | "restoreFiles" | "rewindFilesTo";
     readonly skills_disabled: "disableSkills" | "skills" | `agents[${number}].skills`;
     readonly existing_session: "requireExistingSession" | "sessionId";
     readonly fork_target: "forkId" | "forkNonce";
-    readonly scratchpad_root: "cwd" | "scratchpadDir";
+    readonly scratchpad_root: "cwd" | "projectId" | "scratchpadDir";
     readonly ask_answer: "decision" | "answer";
     readonly policy_person_ask: "decision" | "decidedBy";
     readonly plan_edit: "decision" | "editedPlan";

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

@@ -16,6 +16,8 @@
  *     那一形的面只有每拍一行运维 warn + 计数)。「扣着」在两出口上只有这一种读法(7.120.x 的 `/health.modelPlaneDeferred` 本版删除)。
  *     合成只在 {@link buildRestartSignal} 一处,`restartState()` 是它唯一的调用方 —— 两个出口读的是同一只取值口。
  *  4. **代际**:`generation` = env `FLEET_GENERATION` 的回声(规范十进制串;非规范在 boot 拒启,见 `config.ts`);缺席 ⇔ 非 fleet 成员。
+ *     **围栏只有成员身份一个开关**:租约读数只有一只读者 {@link memberLeaseOf}(铸点与准入三处同读)—— 非成员恒 {@link LEASE_NONE},
+ *     注入了读数也不读;所以「`/health` 不报 `leaseState` 而准入照按租约拒」这一形构造不出来。
  *     **身份不是引擎态**:`instanceId`(本进程起步自铸的那一只,`boot/stage-03` 的 uuidv7)是体的身份,只在两出口体的**顶层**说一次,
  *     铸点不读它、契约形里不重复它。
  *  5. **两形一读(展开 / 收缩)**:两出口今天各发两形 —— 嵌套键 {@link ENGINE_SIGNAL_KEY}(契约 `EngineSignal` 整只,{@link buildEngineSignal}),
@@ -52,8 +54,19 @@ export type ServingLeaseView = {
 };
 /** 心跳体上的 fleet 成员三键 —— 类型取自契约心跳形(拼法与值域只有契约一个写者)。 */
 export type FleetMembershipKeys = Pick<InstanceAnnouncement, "generation" | "leaseState" | "leaseUntil">;
-/** 非 fleet 成员 / 没装租约客户端时的读数(唯一拼法)。 */
+/** 非 fleet 成员 / 没装租约客户端时的读数(唯一拼法)。成员的推定围栏只住在租约客户端里,不进这只缺省值。 */
 export declare const LEASE_NONE: ServingLeaseView;
+/**
+ * 租约读数的**唯一读者**(规则 4;铸点 {@link mintEngineSignal} 与准入三处 —— 计费门 / a2a `message/send` / PARKED 赎回席 —— 都经它,不直读
+ * `deps.servingLease`):成员身份 = `config.fleetGeneration` 在场 ⇒ 租约客户端此刻的读数(没装 ⇒ {@link LEASE_NONE});非成员 ⇒ {@link LEASE_NONE}。
+ */
+export declare function memberLeaseOf(deps: Pick<EngineSignalInputs, "config" | "servingLease">): ServingLeaseView;
+/**
+ * 装配判的拒句(`createHttpServer` 构造期,fail-closed):租约读数只属于 fleet 成员,而成员身份只有 `config.fleetGeneration` 一个开关 ——
+ * 注入了 `servingLease` 却没设代际,读数永远不会被 {@link memberLeaseOf} 读到、准入永远不按租约拒。两键都是可选的,所以这是一份能编译的
+ * 自相矛盾的装配:响亮拒,不静默丢掉读数(本服务自己的组合根只给成员装租约客户端,走不到这里)。
+ */
+export declare const SERVING_LEASE_MEMBERSHIP_REQUIRED = "servingLease is wired but config.fleetGeneration is not: a serving-lease reading belongs to a fleet member, and membership is config.fleetGeneration (FLEET_GENERATION) alone \u2014 without it the reading is never read and admission never refuses on the lease; set config.fleetGeneration to this instance's generation, or do not pass servingLease; refusing to start rather than ignore the lease reading";
 /** 扣着的候选(web-admin 的 `planeDeferredNoHandoff` 投影):版本、起扣时刻、被扣的重启片。 */
 export interface RetainedCandidate {
     readonly version: number;

package/dist/fleet/engine-signal.js

@@ -1,6 +1,10 @@
 import { readinessOf } from "../http/readiness.js";
 import { drainingFactOf } from "./drain-entry.js";
 export const LEASE_NONE = Object.freeze({ state: "none" });
+export function memberLeaseOf(deps) {
+    return deps.config?.fleetGeneration === undefined ? LEASE_NONE : (deps.servingLease?.() ?? LEASE_NONE);
+}
+export const SERVING_LEASE_MEMBERSHIP_REQUIRED = "servingLease is wired but config.fleetGeneration is not: a serving-lease reading belongs to a fleet member, and membership is config.fleetGeneration (FLEET_GENERATION) alone — without it the reading is never read and admission never refuses on the lease; set config.fleetGeneration to this instance's generation, or do not pass servingLease; refusing to start rather than ignore the lease reading";
 export function buildRestartSignal(published, retained) {
     if (published !== undefined)
         return published;
@@ -29,7 +33,7 @@ export function mintEngineSignal(deps) {
         ...(draining !== undefined ? { draining } : {}),
         ...(restart !== undefined ? { restart } : {}),
         ...(deps.config?.fleetGeneration !== undefined ? { generation: deps.config.fleetGeneration } : {}),
-        lease: deps.servingLease?.() ?? LEASE_NONE,
+        lease: memberLeaseOf(deps),
         ...(configApply !== undefined ? { configApply } : {}),
     };
 }

package/dist/fleet/fleet-reconciler.d.ts

@@ -1,5 +1,5 @@
 /**
- * [ref](docs/DESIGN-261-fleet-liveness-reconcile.md v1.2,四方零驳定稿)—— fleet 总线**存活对账腿**。
+ * [ref](docs/[ref]-fleet-liveness-reconcile.md v1.2,四方零驳定稿)—— fleet 总线**存活对账腿**。
  *
  * ## 它修什么(§0 病灶机制链)
  * fleet 总线是进程内纯内存聚合(`fleet-bus.ts` 头注自陈 NOT durable / NOT cross-replica),行的**唯一**

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

@@ -32,11 +32,26 @@ export interface ServingLeaseClientOpts {
         readonly epoch: () => number;
     };
 }
+/**
+ * 一拍心跳听到了什么(`fleet-client.ts` 每一次公告尝试恰好交一只;读者在本模块)。
+ *  · `reading` —— 中心的显式能力声明(契约 `declared`;位缺席 = 中心说不执行围栏);
+ *  · `silent` —— 没有读数。`why` 的形是闭集:`HTTP <状态>`(非 2xx,不带中心体片段)/ 请求抛出的那句(不可达 / 超时 / 凭证读不出)/
+ *    `reply-unreadable:<因>`(2xx 而不是声明,因 = `fleet-client.ts` `AnnounceReplyFlaw`)/ `not-sent:<那句>`(这一拍的引擎信号铸不出,没发)。
+ */
+export type HeartbeatHearing = {
+    readonly kind: "reading";
+    readonly capabilities: WebAdminCapabilities;
+} | {
+    readonly kind: "silent";
+    readonly why: string;
+};
 export interface ServingLeaseClient {
-    /** 一次中心能力读数(`undefined` = `undeclared`,中心没宣告 = 不支持)。每一次读数调一次;`unreadable` 不是读数,不调(`fleet-client.ts` `capabilityReadingOf`)。 */
-    noteCenterCapabilities(caps: WebAdminCapabilities | undefined): void;
-    /** 此刻的租约读数(铸点与准入判读它)。 */
+    /** 一拍心跳听到的东西(规则 1;每一次公告尝试恰好一次)。 */
+    noteHeartbeat(hearing: HeartbeatHearing): void;
+    /** 此刻的租约读数(铸点与准入判读它 —— 经 `engine-signal.ts` 的唯一读者 `memberLeaseOf`)。 */
     view(): ServingLeaseView;
+    /** 订阅「租约态由事件翻转」(规则 2′;一只订阅者 = 装配层的 `announceNow`,晚绑:fleet 客户端在本客户端之后造)。 */
+    onViewChange(listener: () => void): void;
     /** 起步读黏性拒(装配层在唯一排空入口装好之后调一次)。 */
     resumeStickyDenial(): void;
     /** 立刻续一次(测试 / 能力位刚出现时用;单飞)。 */

package/dist/fleet/serving-lease.js

@@ -40,8 +40,9 @@ export function createServingLeaseClient(o) {
     const mono = o.clock?.mono ?? (() => performance.now());
     const epoch = o.clock?.epoch ?? Date.now;
     const stickyPath = o.dataRoot === undefined ? undefined : join(o.dataRoot, SERVING_LEASE_DENIED_FILE);
-    let capability;
-    const enabled = () => capability?.announced === true;
+    let fence = { kind: "presumed", since: mono() };
+    const enabled = () => fence.kind === "on";
+    let viewListener;
     let denied = false;
     let stopped = false;
     let lease;
@@ -49,6 +50,37 @@ export function createServingLeaseClient(o) {
     let timer;
     let inFlight;
     let failStreak = 0;
+    const view = () => {
+        if (denied)
+            return { state: "denied" };
+        if (fence.kind === "off")
+            return { state: "none" };
+        const now = mono();
+        if (lease !== undefined && now < lease.expiresAtMono)
+            return { state: "granted", leaseUntil: lease.leaseUntil };
+        return { state: "expired", pastOutageMax: now - (lease?.expiresAtMono ?? fence.since) >= o.outageMaxMs };
+    };
+    const changing = (change) => {
+        const before = view().state;
+        change();
+        if (view().state !== before)
+            viewListener?.();
+    };
+    const unconfirmed = (why) => {
+        recordFailOpen("server.fleet.serving-lease-unconfirmed", `worker=${o.center.worker} generation=${o.generation} why=${why}`);
+        failStreak += 1;
+        if (failStreak === 1) {
+            o.logger?.warn("fleet_serving_lease_unconfirmed", {
+                error: why,
+                note: "the fleet center has not confirmed this instance's serving lease (heartbeat or renewal unanswered, refused or unreadable, or the verdict was unknown) — this instance keeps serving until its last grant, or with no grant yet the moment the fence took effect (this process's start, for a member that has not heard the center), is FLEET_LEASE_OUTAGE_MAX_MS behind, then refuses new work (unconfirmed is never a denial)",
+            });
+        }
+    };
+    const confirmed = (by) => {
+        if (failStreak > 0)
+            o.logger?.info("fleet_serving_lease_recovered", { after: failStreak, by });
+        failStreak = 0;
+    };
     const clear = () => {
         if (timer !== undefined)
             clearTimeout(timer);
@@ -79,6 +111,9 @@ export function createServingLeaseClient(o) {
     const enterDenied = (denial) => {
         if (denied)
             return;
+        changing(() => enterDeniedNow(denial));
+    };
+    const enterDeniedNow = (denial) => {
         denied = true;
         lease = undefined;
         clear();
@@ -118,25 +153,22 @@ export function createServingLeaseClient(o) {
             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)" });
+            if (fence.kind === "on")
+                unconfirmed(reading === undefined ? why : "verdict=unknown (the center holds no lifecycle object for this instance right now)");
             schedule(nextInMs);
             return;
         }
-        if (failStreak > 0)
-            o.logger?.info("fleet_serving_lease_recovered", { after: failStreak });
-        failStreak = 0;
+        confirmed("verdict");
         switch (reading.verdict) {
-            case "granted":
+            case "granted": {
                 if (denied)
                     return;
-                lease = { expiresAtMono: sendMono + reading.ttlMs, leaseUntil: sendEpoch + reading.ttlMs };
+                const granted = { expiresAtMono: sendMono + reading.ttlMs, leaseUntil: sendEpoch + reading.ttlMs };
+                changing(() => (lease = granted));
                 nextInMs = reading.ttlMs / 3;
                 schedule(nextInMs);
                 return;
+            }
             case "denied":
                 enterDenied({ from: "center", reason: reading.reason });
                 return;
@@ -154,34 +186,48 @@ export function createServingLeaseClient(o) {
         });
         return inFlight;
     };
+    const noteDeclaration = (caps) => {
+        const on = caps.servingLease === true;
+        if (!on)
+            recordFailOpen("server.fleet.serving-lease-capability-absent", `worker=${o.center.worker} generation=${o.generation} was=${fence.kind}`);
+        if (on && fence.kind !== "on") {
+            fence = { kind: "on", since: fence.since ?? mono() };
+            o.logger?.info("fleet_serving_lease_enabled", { generation: o.generation, worker: o.center.worker });
+            void renewNow();
+        }
+        else if (!on && fence.kind !== "off") {
+            const was = fence.kind;
+            fence = { kind: "off", since: was === "on" ? fence.since : undefined };
+            clear();
+            confirmed("not-enforced");
+            if (was === "on")
+                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; its outage clock is not reset (when the capability returns, the last grant and the moment the fence first took effect in this process still count)" });
+        }
+    };
     return {
-        noteCenterCapabilities(caps) {
+        noteHeartbeat(hearing) {
             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()) {
-                capability = { announced: true, firstSeenAtMono: capability?.firstSeenAtMono ?? mono() };
-                o.logger?.info("fleet_serving_lease_enabled", { generation: o.generation, worker: o.center.worker });
-                void renewNow();
-            }
-            else if (!on && capability?.announced === true) {
-                capability = { announced: false, firstSeenAtMono: capability.firstSeenAtMono };
-                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; its outage clock is not reset (when the capability returns, the last grant and this process's first sighting of the capability still count)" });
+            switch (hearing.kind) {
+                case "silent":
+                    if (fence.kind === "presumed")
+                        unconfirmed(`heartbeat:${hearing.why}`);
+                    return;
+                case "reading":
+                    if (fence.kind === "presumed")
+                        changing(() => noteDeclaration(hearing.capabilities));
+                    else
+                        noteDeclaration(hearing.capabilities);
+                    return;
+                default: {
+                    const unhandled = hearing;
+                    throw new Error(`serving lease: unknown heartbeat hearing ${JSON.stringify(unhandled)}`);
+                }
             }
         },
-        view() {
-            if (denied)
-                return { state: "denied" };
-            if (capability === undefined || !capability.announced)
-                return { state: "none" };
-            const now = mono();
-            if (lease !== undefined && now < lease.expiresAtMono)
-                return { state: "granted", leaseUntil: lease.leaseUntil };
-            const expiredAt = lease?.expiresAtMono ?? capability.firstSeenAtMono;
-            return { state: "expired", pastOutageMax: now - expiredAt >= o.outageMaxMs };
+        view,
+        onViewChange(listener) {
+            viewListener = listener;
         },
         resumeStickyDenial() {
             if (stickyPath === undefined || denied)