@sema-agent/server 7.148.0 → 7.150.0

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/env-name-allowlist-knobs.d.ts

@@ -6,14 +6,15 @@
  *  · `example` 进拒句;
  *  · `multiTenant` = `REQUIRE_PRINCIPAL=true` 下名单作不作数 —— **只有服务进程读的旋钮有这一列**(姿态是服务进程的概念):
  *    - `LSP_ENV_ALLOW` ⇒ ignored:host 腿语言服务器在多租户姿态下本来就不起,名单无处作数,设了要说出来([ref])。
+ *    - `HOOK_ENV_ALLOW` ⇒ ignored:请求的 `settings.hooks` 在多租户姿态下整只不跑(`task-settings.ts` `taskHooksHonored`,同一只部署形谓词),名单无处作数。
  *    - 三只沙箱名单(e2b / local-docker / k8s 各一只) ⇒ honored:[ref] 照录修前语义(任何姿态下都转发),[ref] 主会话裁定维持 —— 沙箱 env 是部署方为隔离沙箱显式配的
  *      带外凭据(e2b / docker / k8s 车道本来就是多租户 fleet 的主形),与 LSP 那条「本机子进程」的形不同;多租户下起服说一句。
  *  · `BAKE_ENV_ALLOW`([ref] 残余,7.103.0)由 **bake-runner 进程**读(构建宿主守护进程:没有主体、没有租户 ⇒ 没有姿态列,
- *    不进 {@link describeAllowlistPostures} 的姿态句)。它与服务侧四只旋钮同一只解析器、同一只「点名放行」谓词、同一条「原文按凭据类」律。
- *  · `channel` = 这张名单**交给谁、在谁的减法之上**(闭集两词)。它只定拒句里「交到哪里」那半句与出路的主语,**不定拒不拒**:「不许点哪些名」对五只一律
+ *    不进 {@link describeAllowlistPostures} 的姿态句)。它与服务侧五只旋钮同一只解析器、同一只「点名放行」谓词、同一条「原文按凭据类」律。
+ *  · `channel` = 这张名单**交给谁、在谁的减法之上**(闭集两词)。它只定拒句里「交到哪里」那半句与出路的主语,**不定拒不拒**:「不许点哪些名」对六只一律
  *    = 名单型旋钮名 ∪ 本服务自有凭据名(引擎此刻的声明:起服解析时判一次,声明增长时由换代声明对活配置里每只服务侧名单此刻交出去的名重判一次;判官 = 引擎
  *    `inheritEnvPolicyProblem`,与引擎拒嵌入方白名单同句),规则全文在解析器头注 ②。
- *    - `host-put-back`(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)—— 剥后放回形:宿主子进程的 env 先经唯一组合(引擎扣掉本服务自有凭据 + 形状剥),
+ *    - `host-put-back`(`LSP_ENV_ALLOW` / `HOOK_ENV_ALLOW` / `BAKE_ENV_ALLOW`)—— 剥后放回形:宿主子进程的 env 先经唯一组合(引擎扣掉本服务自有凭据 + 形状剥 / 严格名单),
  *      名单点到的键再从本进程环境**原样**取回叠上去;点到本服务自有凭据名 = 把引擎刚扣下的那枚交回那只子进程。
  *    - `sandbox-grant`(三只沙箱名单)—— 沙箱 env 的唯一来源(沙箱不从本进程继承任何东西),部署方显式交出的带外凭据([ref] 照转发);
  *      点到本服务自有凭据名 = 把它装进模型读得到的沙箱 env。沙箱要凭据 ⇒ 部署方给沙箱另铸一把(名与值都不同于本服务的任何凭据)。
@@ -25,7 +26,7 @@
  * 当场撒谎。为什么是纯叶:`config-catalog.ts` 被 `config.ts` 值引,表留在 `config.ts` 会成装载环。
  */
 /** 服务进程(`config.ts` `loadConfig`)读的名单型旋钮 —— 有多租户姿态。 */
-export type ServerEnvNameAllowlistKnob = "LSP_ENV_ALLOW" | "E2B_SANDBOX_ENV" | "DOCKER_SANDBOX_ENV" | "K8S_SANDBOX_ENV";
+export type ServerEnvNameAllowlistKnob = "LSP_ENV_ALLOW" | "HOOK_ENV_ALLOW" | "E2B_SANDBOX_ENV" | "DOCKER_SANDBOX_ENV" | "K8S_SANDBOX_ENV";
 /** bake-runner 进程(`bake-runner/main.ts` `loadEnv`)读的名单型旋钮 —— 构建宿主守护进程没有主体 / 租户,没有姿态。 */
 export type RunnerEnvNameAllowlistKnob = "BAKE_ENV_ALLOW";
 export type EnvNameAllowlistKnob = ServerEnvNameAllowlistKnob | RunnerEnvNameAllowlistKnob;
@@ -52,7 +53,7 @@ export type EnvNameAllowlistKnobTable = {
     readonly [K in EnvNameAllowlistKnob]: K extends ServerEnvNameAllowlistKnob ? ServerEnvNameAllowlistKnobRow : RunnerEnvNameAllowlistKnobRow;
 };
 export declare const ENV_NAME_ALLOWLIST_KNOBS: EnvNameAllowlistKnobTable;
-/** 名单型旋钮的全部名字(五只;表键派生)—— 两处用:解析器的「点名名单型旋钮 = 形错」、剥除的「名单原文按凭据类」臂。 */
+/** 名单型旋钮的全部名字(六只;表键派生)—— 两处用:解析器的「点名名单型旋钮 = 形错」、剥除的「名单原文按凭据类」臂。 */
 export declare const ENV_NAME_ALLOWLIST_KNOB_NAMES: ReadonlySet<string>;
 /**
  * 多租户姿态句 —— **由表派生**,不许在别处手写。形:`under REQUIRE_PRINCIPAL=true: <旋钮> is ignored; <旋钮> / <旋钮> are forwarded as configured`

package/dist/env-name-allowlist-knobs.js

@@ -4,6 +4,11 @@ export const ENV_NAME_ALLOWLIST_KNOBS = {
         channel: "host-put-back",
         multiTenant: { kind: "ignored", why: "the host-lane language server is not started in this posture, and the language-server env keeps the full secret strip" },
     },
+    HOOK_ENV_ALLOW: {
+        example: "HOOK_ENV_ALLOW=HOOK_TOKEN,WEBHOOK_SIGNING_KEY",
+        channel: "host-put-back",
+        multiTenant: { kind: "ignored", why: "request settings hooks are not run in this posture, so no hook environment reads the list" },
+    },
     E2B_SANDBOX_ENV: { example: "E2B_SANDBOX_ENV=GIT_TOKEN,NPM_TOKEN", channel: "sandbox-grant", multiTenant: { kind: "honored" } },
     DOCKER_SANDBOX_ENV: { example: "DOCKER_SANDBOX_ENV=GIT_TOKEN,NPM_TOKEN", channel: "sandbox-grant", multiTenant: { kind: "honored" } },
     K8S_SANDBOX_ENV: { example: "K8S_SANDBOX_ENV=GIT_TOKEN,NPM_TOKEN", channel: "sandbox-grant", multiTenant: { kind: "honored" } },

package/dist/execution-lane-caps.d.ts

@@ -16,9 +16,8 @@ export type ExecutionLane = DeclarableLane;
 export interface ExecutionLaneCaps {
     /** 调用方送来的 `cwd` 是否被尊重。读者:部署形表行 `callerCwd`(本位即判据;改前对账 `task-cwd.ts` 的 `cwdHonored || deviceCwdHonored`)。 */
     readonly callerCwd: LaneCapability;
-    /** core 的后台 shell 面(`run_in_background`/`BashOutput`/`KillShell`)。判别式:各 adapter 的
-     *  `backgroundCapabilities.supported`(`plugins/remote-env-{host,e2b,k8s}.ts`);host 腿的闸在
-     *  `boot/execution-env.ts` 的 `hostCfg.backgroundShell`。 */
+    /** core 的后台 shell 面(`run_in_background`/`BashOutput`/`KillShell`),含把运行中的前台命令领养成后台任务(`supportsDetach`)。读者:部署形表行 `backgroundShell`(本位即判据);
+     *  三只适配器的 `backgroundCapabilities`(`supported` 与 `supportsDetach` 同一个答案)、host 适配器的装配点与事实 `autoBackgroundOnTimeout` 同读这一行,没有第二份判别式。 */
     readonly backgroundShell: LaneCapability;
     /** 自唤醒 scheduler(`CronCreate`/…)。判别式:`boot/execution-env.ts` host 臂的 `hostScheduler`
      *  与 `http/routes/capabilities.ts` 的 `scheduler` 位(两处同判据)。 */
@@ -330,11 +329,27 @@ export declare function buildLaneHomeBootNote(deployment: LaneHomeDeployment): {
     readonly event: string;
     readonly note: string;
 } | undefined;
+/**
+ * 读拒表的字节地板不守时一条 run 的**两种结局**(闭集):`ran` = 部署没要求地板,run 照跑(引擎每 run 一条 `config.read_deny_floor_unkept` 通告);
+ * `refused` = 部署要求地板(`READ_DENY_FLOOR_REQUIRED=true`),run 在准备期拒(同码失败终局,同步提交 409)。判官只有引擎一只(`judgeReadFloorKept`),
+ * 结局由旋钮分开 —— 本仓只说话。
+ */
+export type ReadDenyFloorOutcome = "ran" | "refused";
+/**
+ * **读拒字节地板不守的那一句** —— 本仓说这件事的**唯一**组句器(纯字符串 ⇒ `build*`):点名执行环境(`REMOTE_EXEC=<车道>`,运维写的那一格)、
+ * 「不守读拒字节地板」与出路 `READ_DENY_FLOOR_REQUIRED`。读它的面(一个事实一句话,不另写第二句):
+ *  · `ran` —— run 事件流的 `engine_notice` 帧、运维 `engine_notice` 日志行与终局结果的 `readDenyFloor.message`(`read-deny-floor-notice.ts` 的呈现器);
+ *  · `refused` —— 失败终局的句子(同步提交 409 的 `error`、run 行 `error`、`done` 帧 `terminal.message`,`terminal.ts` 的两只出口属主)与起服那一行
+ *    `read_deny_floor_required_unkept` 的 `note`({@link buildReadDenyFloorUnkeptNote})。
+ * 句子不带行数(行数在通告的 `detail.rowCount`):同一条部署上同一种结局逐字同一句,运维能把起服行、409 与日志对上。
+ * 车道名以旋钮形 `REMOTE_EXEC=<词>` 出现 —— 那是调用方 / 运维写得出、查得到的名字,不是本仓对执行车道的自称。
+ */
+export declare function buildReadDenyFloorSentence(lane: string, outcome: ReadDenyFloorOutcome): string;
 /**
  * 「部署要求读拒表的字节地板(`READ_DENY_FLOOR_REQUIRED=true`),而本部署车道的执行环境块不守地板」时起服那一行的 `note`(纯字符串 ⇒ `build*`);否则 `undefined`。
  * 判据只读部署的要求与 {@link capabilitiesFor} 的 `keepsReadFloor`(认不出的车道答不出块 ⇒ 按不守说,不静默)。`none` 的桩块守地板 ⇒ 不出。
- * 句子点名车道与键:这条车道上每个读拒表有行的 run(出厂读拒档在岗时就有行)都在准备期拒,一个命令都不起 —— 起服先把后果与两条出路说出来,
- * 不让运维从第一条 409 才知道。
+ * 句子 = 这条车道上每条被拒的 run 的拒句({@link buildReadDenyFloorSentence} 的 `refused`,一字不差):起服先把后果与两条出路说出来,
+ * 运维不必从第一条 409 才知道,且起服行与 409 是同一句。
  */
 export declare function buildReadDenyFloorUnkeptNote(deployment: CapabilitiesDeployment & {
     readonly readDenyFloorRequired: boolean;

package/dist/execution-lane-caps.js

@@ -327,14 +327,28 @@ export function buildLaneHomeBootNote(deployment) {
         return { event: LANE_HOME_UNDECLARED_EVENT, note: buildHomeAbsentNote(homeLane, "REMOTE_EXEC_HOME_DIR is unset, and this lane cannot read its execution environment's home", DECLARE_HOME_REMEDY) };
     return { event: LANE_HOME_UNMEASURED_EVENT, note: buildHomeUnmeasuredNote(homeLane, home) };
 }
+export function buildReadDenyFloorSentence(lane, outcome) {
+    const env = `the execution environment (REMOTE_EXEC=${lane}) does not keep the read-deny byte floor`;
+    switch (outcome) {
+        case "ran":
+            return (`This run's read-deny rules are not byte-enforced: ${env} — a path a rule refuses is refused when a command names it, ` +
+                `but a program a command runs can still open it (a recursive read under a directory reads the files below it, denied ones included), ` +
+                `and their bytes can reach the conversation. READ_DENY_FLOOR_REQUIRED is not set, so the run went ahead; set READ_DENY_FLOOR_REQUIRED=true to refuse such runs instead.`);
+        case "refused":
+            return (`READ_DENY_FLOOR_REQUIRED=true, and ${env} (a program a command runs could open a path a read-deny rule refuses): ` +
+                `a run with read-deny rules is refused before any command starts (config.read_deny_floor_unkept; a synchronous submit answers 409). ` +
+                `Run on an execution environment that keeps the floor, or unset READ_DENY_FLOOR_REQUIRED to let such runs go ahead with a notice.`);
+        default: {
+            const unhandled = outcome;
+            throw new Error(`unhandled read-deny floor outcome: ${String(unhandled)}`);
+        }
+    }
+}
 export function buildReadDenyFloorUnkeptNote(deployment) {
     if (!deployment.readDenyFloorRequired)
         return undefined;
     if (capabilitiesFor(deployment)?.keepsReadFloor === true)
         return undefined;
-    return (`READ_DENY_FLOOR_REQUIRED=true, but the "${deployment.remoteExec.provider}" execution lane does not keep the read-deny byte floor (a program its commands run can open a path ` +
-        `the read-deny table refuses). Every run whose read-deny table has rows — the shipped default tiers put rows there unless READ_DENY_BUILTIN_TIERS=none — ` +
-        `is refused before any command starts (config.read_deny_floor_unkept; a synchronous submit answers 409). ` +
-        `Either run on a lane that keeps the floor, or unset READ_DENY_FLOOR_REQUIRED to run with one operator notice per run instead.`);
+    return buildReadDenyFloorSentence(deployment.remoteExec.provider, "refused");
 }
 //# sourceMappingURL=execution-lane-caps.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;
     /** 立刻续一次(测试 / 能力位刚出现时用;单飞)。 */