@sema-agent/server 7.149.0 → 7.151.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, asInstructionKindAt, 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"],
@@ -47,6 +66,7 @@ const ALLOWED_SUCCESS_OUTCOME_KINDS = {
     remove: ["void"],
     createTempDir: ["write"],
     createTempFile: ["write"],
+    openBound: ["stat", "read"],
 };
 const HELLO_ACK_FIELD_SOURCES = {
     heartbeatIntervalMs: "option heartbeatIntervalMs",
@@ -145,14 +165,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 +329,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 +395,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 {
@@ -470,7 +501,7 @@ export function createDeviceWsHub(options) {
         conn.workspaceRoot = frame.workspaceRoot;
         const supported = new Set();
         for (const s of frame.supports) {
-            const k = asInstructionKind(s);
+            const k = asInstructionKindAt(s, frame.protocolVersion);
             if (k !== null)
                 supported.add(k);
         }
@@ -860,8 +891,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 +994,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 +1052,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,29 @@ 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 受理的结局 `errorCode` 词集(executor → server)
+ * 与 server 下发的指令 kind 集(server → executor),各一张按修订号分行的表({@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION} /
+ * {@link DEVICE_INSTRUCTION_KINDS_BY_REVISION},同一组行键;协议文档是同一张修订号表的两栏);**语义变更(server 下发的帧意思变了)= 升号**。
+ * 修订号是 executor 在发 hello 之前唯一能读到的「这台 server 受理什么、会发来什么、发来的帧是什么意思」的事实(challenge 帧带它),所以两个闭集
+ * 都必须是修订号的函数,不另发第二份列表;闭集变了而修订号没变 = 同一个修订号两种集合(7.132.0 给结局码加 `liveness_no_output` 时没抬号,7.136.0 补到 2)。
+ * 下发方向的读法:汇聚端只认**这条连接协商的修订号**那一份 kind 集({@link asInstructionKindAt}),高于它的 kind 与认不出的词同读 —— 恒不下发。
+ * 类型锁:抬了号而任一张表没有这一行 ⇒ 编译红。
  */
 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 认的是折过的路径。
+ * 修订号 6(kind 集加 `openBound`)不抬下沿:那个 kind 只派给协商修订号 ≥ 6 的连接,修订号 5 的 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";
 /**
@@ -60,11 +75,44 @@ export type DeviceCancelState = (typeof DEVICE_CANCEL_STATES)[number];
  */
 export declare const DEVICE_INSTRUCTION_STATES: readonly ["queued", "dispatch_committed", "terminal", "terminal_never_started"];
 export type DeviceInstructionState = (typeof DEVICE_INSTRUCTION_STATES)[number];
-/** 指令 kind ↔ core 的 FileSystem+Shell 面 1:1(§5.1;双端穷举 switch)。 */
-export declare const DEVICE_INSTRUCTION_KINDS: readonly ["exec", "execStream", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "writeFileExclusive", "writeFileGuarded", "appendFile", "fileInfo", "listDir", "canonicalPath", "exists", "readLink", "createDir", "remove", "createTempDir", "createTempFile", "statBatch"];
-export type DeviceInstructionKind = (typeof DEVICE_INSTRUCTION_KINDS)[number];
-/** 认得就收窄,认不出就 null(**不猜**:未知 kind 恒不下发,fail-closed 方向)。 */
-export declare function asInstructionKind(v: string): DeviceInstructionKind | null;
+/**
+ * 指令 kind ↔ core 的 FileSystem+Shell 面 1:1(§5.1;双端穷举 switch)—— **按修订号分行的增量表,是这个闭集唯一的一份来源**(与结局码同一条律):
+ * 修订号 N 的 kind 集 = 行 ≤ N 的并、按行序({@link deviceInstructionKindsAt}),{@link DEVICE_INSTRUCTION_KINDS} 是当前修订号的那一份(派生)。
+ * 汇聚端对一条连接只认它协商的修订号那一份({@link asInstructionKindAt}):executor 在 `hello.supports` 里声明了一个高于自己修订号的 kind,与声明了
+ * 一个认不出的词同读 —— 不进声明集、恒不下发。已发布修订号的行不许改(测试冻结了每个修订号的集合哈希);加 kind = 抬 {@link DEVICE_PROTOCOL_VERSION} + 加一行。
+ * 行键与 {@link DEVICE_OUTCOME_ERROR_CODES_BY_REVISION} 同一组(`satisfies` 锁:少一行 / 多一行 ⇒ 编译红)。
+ */
+export declare const DEVICE_INSTRUCTION_KINDS_BY_REVISION: {
+    readonly 1: readonly ["exec", "execStream", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "writeFileExclusive", "writeFileGuarded", "appendFile", "fileInfo", "listDir", "canonicalPath", "exists", "readLink", "createDir", "remove", "createTempDir", "createTempFile", "statBatch"];
+    readonly 2: readonly [];
+    readonly 3: readonly [];
+    readonly 4: readonly [];
+    readonly 5: readonly [];
+    /**
+     * 7.151.0:绑定读 —— 判过的那只对象就是读到的那只。协议没有跨指令的句柄,所以 `BoundFileObject` 的每一答是一条指令
+     * ({@link DeviceInstructionArgsByKind}`.openBound.op` 四选一):执行器在本机打开这条路径(叶链接不跟)、核对这只打开的对象此刻就在这条路径上
+     * (且 `identity` / `kind` 在场时等于它们)、经这一次打开作答、关掉。executor 必须实现才答得出 ⇒ 加词抬号;只派给协商修订号 ≥ 6 的连接,
+     * 修订号 5 的 executor 收不到它(受理下沿不动)。presence-typed(同 `writeFileGuarded` / `readLink`):执行器在 `hello.supports` 声明才装这一面;
+     * 没声明 ⇒ 这一面缺席(引擎不绑定读,附件不附),**不许**用 `fileInfo` + `readBinaryFile` 仿真。
+     */
+    readonly 6: readonly ["openBound"];
+};
+export type DeviceInstructionKind = (typeof DEVICE_INSTRUCTION_KINDS_BY_REVISION)[DeviceProtocolRevision][number];
+/**
+ * 协议修订号 `revision` 下发的指令 kind 全集(行 ≤ revision 的并,按行序 —— 协议文档 §3.1 的表同序)。executor 按**自己声明的修订号**取这一份,
+ * 决定 `hello.supports` 里能声明哪些 kind。不是本包认得的修订号 ⇒ 抛 `RangeError`(不静默给空集或全集)。
+ */
+export declare function deviceInstructionKindsAt(revision: number): readonly DeviceInstructionKind[];
+/** 当前修订号下发的 kind 全集(派生自增量表;§3.1 的表就是它)。 */
+export declare const DEVICE_INSTRUCTION_KINDS: readonly DeviceInstructionKind[];
+/** `openBound` 指令的四个答(一个 `BoundFileObject` 成员一个;`open` 是开答)。 */
+export declare const DEVICE_BOUND_READ_OPS: readonly ["open", "size", "readBytes", "list"];
+export type DeviceBoundReadOp = (typeof DEVICE_BOUND_READ_OPS)[number];
+/**
+ * 认词 **按协商修订号**:`v` 在修订号 `revision` 的 kind 集里就收窄,不在就 null(**不猜**:高于协商修订号的 kind 与认不出的词同读,恒不下发,fail-closed 方向)。
+ * 不是本包认得的修订号 ⇒ 抛 `RangeError`(汇聚端在 hello 的版本窗之后才调它,窗外到不了这里;到了就是响亮的缺陷,不静默给全集)。
+ */
+export declare function asInstructionKindAt(v: string, revision: number): DeviceInstructionKind | null;
 /**
  * 结果帧的错误码闭集 = core 的 `FileErrorCode ∪ ExecutionErrorCode`(§5.1「error code 全闭集」:
  * 未知值映射为协议错误而非透传 string)—— **按修订号分行的增量表,是这个闭集唯一的一份来源**:
@@ -76,6 +124,8 @@ 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 [];
+    readonly 6: readonly [];
 };
 /** 本包认得的协议修订号(= 增量表的行键)。 */
 export type DeviceProtocolRevision = keyof typeof DEVICE_OUTCOME_ERROR_CODES_BY_REVISION;
@@ -139,7 +189,9 @@ export type DeviceInstructionOutcome = {
 } | {
     ok: true;
     kind: "read";
-} | {
+}
+/** `identity` 是 additive 扩键(`openBound` 开答:被打开对象的 `<dev>:<inode>`,之后每一答的对拍凭据)。 */
+ | {
     ok: true;
     kind: "stat";
     info?: WireFileInfo;
@@ -147,6 +199,7 @@ export type DeviceInstructionOutcome = {
     existsValue?: boolean;
     canonicalPath?: string;
     linkTarget?: string | null;
+    identity?: string;
 }
 /** 写面的**落盘对象收据**(§4.3.1 / core `WriteReceipt`)。`created` 是 additive 扩键(车A-4):
  *  core 的收据形要求它,缺席 = adapter 只能猜「是新建还是覆盖」,而猜出来的收据就是假收据。 */
@@ -243,6 +296,18 @@ export interface DeviceInstructionArgsByKind {
     statBatch: {
         paths: string[];
     };
+    /**
+     * 绑定读的一答。`op`:`open` ⇒ `stat` 结局带 `identity` 与 `info`(`kind` 只许 `file` / `dir`);`size` ⇒ `stat` 带 `info`(`size` = 此刻大小);
+     * `readBytes` ⇒ `read` 结局 + `data` 片(大小 > `max` ⇒ `invalid`,一个字节不读);`list` ⇒ `stat` 带 `entries`(经这只打开的目录列,链接不跟)。
+     * `identity` / `kind` 在场(开答之后的三答)⇒ 这一次打开的对象须与它们都相等,否则 `precondition_failed`;开后不在这条路径上同拒。
+     */
+    openBound: {
+        path: string;
+        op: DeviceBoundReadOp;
+        identity?: string;
+        kind?: "file" | "directory";
+        max?: number;
+    };
 }
 export type DeviceChallengeFrame = {
     t: "challenge";
@@ -275,10 +340,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 = 6;
+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,
@@ -18,30 +24,54 @@ export const DEVICE_GOODBYE_REASONS = ["shutdown", "sleep", "user_stop"];
 export const DEVICE_CHUNK_KINDS = ["stdout", "stderr", "data", "exit"];
 export const DEVICE_CANCEL_STATES = ["not_started", "killed"];
 export const DEVICE_INSTRUCTION_STATES = ["queued", "dispatch_committed", "terminal", "terminal_never_started"];
-export const DEVICE_INSTRUCTION_KINDS = [
-    "exec",
-    "execStream",
-    "readTextFile",
-    "readTextLines",
-    "readBinaryFile",
-    "writeFile",
-    "writeFileExclusive",
-    "writeFileGuarded",
-    "appendFile",
-    "fileInfo",
-    "listDir",
-    "canonicalPath",
-    "exists",
-    "readLink",
-    "createDir",
-    "remove",
-    "createTempDir",
-    "createTempFile",
-    "statBatch",
-];
-const INSTRUCTION_KIND_SET = new Set(DEVICE_INSTRUCTION_KINDS);
-export function asInstructionKind(v) {
-    return INSTRUCTION_KIND_SET.has(v) ? v : null;
+export const DEVICE_INSTRUCTION_KINDS_BY_REVISION = {
+    1: [
+        "exec",
+        "execStream",
+        "readTextFile",
+        "readTextLines",
+        "readBinaryFile",
+        "writeFile",
+        "writeFileExclusive",
+        "writeFileGuarded",
+        "appendFile",
+        "fileInfo",
+        "listDir",
+        "canonicalPath",
+        "exists",
+        "readLink",
+        "createDir",
+        "remove",
+        "createTempDir",
+        "createTempFile",
+        "statBatch",
+    ],
+    2: [],
+    3: [],
+    4: [],
+    5: [],
+    6: ["openBound"],
+};
+export function deviceInstructionKindsAt(revision) {
+    if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {
+        throw new RangeError(`device-ws: no instruction-kind set for protocol revision ${String(revision)} (this package knows revisions 1..${DEVICE_PROTOCOL_VERSION})`);
+    }
+    const out = [];
+    for (const [rev, kinds] of Object.entries(DEVICE_INSTRUCTION_KINDS_BY_REVISION)) {
+        if (Number(rev) <= revision)
+            out.push(...kinds);
+    }
+    return out;
+}
+export const DEVICE_INSTRUCTION_KINDS = deviceInstructionKindsAt(DEVICE_PROTOCOL_VERSION);
+export const DEVICE_BOUND_READ_OPS = ["open", "size", "readBytes", "list"];
+const INSTRUCTION_KIND_SETS = new Map(Object.keys(DEVICE_INSTRUCTION_KINDS_BY_REVISION).map((rev) => [Number(rev), new Set(deviceInstructionKindsAt(Number(rev)))]));
+export function asInstructionKindAt(v, revision) {
+    const kinds = INSTRUCTION_KIND_SETS.get(revision);
+    if (kinds === undefined) {
+        throw new RangeError(`device-ws: no instruction-kind set for protocol revision ${String(revision)} (this package knows revisions 1..${DEVICE_PROTOCOL_VERSION})`);
+    }
+    return kinds.has(v) ? v : null;
 }
 export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
     1: [
@@ -68,6 +98,8 @@ export const DEVICE_OUTCOME_ERROR_CODES_BY_REVISION = {
     2: ["liveness_no_output"],
     3: ["name_too_long"],
     4: ["symlink_loop"],
+    5: [],
+    6: [],
 };
 export function deviceOutcomeErrorCodesAt(revision) {
     if (!Number.isInteger(revision) || revision < 1 || revision > DEVICE_PROTOCOL_VERSION) {
@@ -225,6 +257,12 @@ function parseOutcome(v) {
                     return null;
                 out.linkTarget = v.linkTarget;
             }
+            if (v.identity !== undefined) {
+                const id = str(v.identity);
+                if (id === null)
+                    return null;
+                out.identity = id;
+            }
             return out;
         }
         case "write": {

package/dist/engine-identity.d.ts

@@ -5,11 +5,13 @@
  * 与本仓的人面汇点同轴);`isolationScope` = **带场景的主体**(只在请求带了场景时有;引擎按它分登记域 / offload 租界 / 后台登记 / peer 目录 / 工作流 scope,
  * 引擎的读法是「隔离格缺席 ⇒ 读 `principal`」)。没带场景的请求只有 `principal`,与今天逐字节同。检查点的分区走本仓自己供的 `scope` 格。
  *
- * 今天的引擎还没有隔离格:{@link taskSpecIdentityOf} 是**唯一的落点**,今天只写 `principal`;隔离格到货后改那一行(钉在 `test/scenario-subject.test.ts`)。
- * 落点之前引擎自己按 `spec.principal` 分的那几面按人分(同一个人的各场景在那几面互见)—— 本仓镜像这几面的读口(工作流读面、后台登记簿的停止标记、
- * leader 子任务的 spec)同读 {@link taskSpecIdentityOf},读到的就是引擎写下的那一个值,不各写一份。
+ * 今天的引擎还没有隔离格:{@link taskSpecIdentityOf} 是**唯一的落点**,今天只写 `principal`;隔离格到货后改那一行(钉在 `test/scenario-subject.test.ts`),
+ * {@link engineScopeOf} 同一提交换读(钉在 `test/workflow-scope-core-parity.test.ts`)。
+ * 落点之前引擎自己按 `spec.principal` 分的那几面按人分(同一个人的各场景在那几面互见)。本仓读这几面(工作流行的 `scope` 列、后台登记簿与它的停止标记、
+ * 会话信箱盒与被扣来信的队列、名册)时「一只主体 ⇒ 那一格 scope」只有一只换算 {@link engineScopeOf},读到的就是引擎写下的那一个值,不各写一份;
+ * 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;
@@ -20,9 +22,25 @@ export interface EngineIdentity {
 export declare function specIdentityOf(parts: SubjectParts | undefined): EngineIdentity;
 /**
  * 落进 `TaskSpec` 的身份格(**唯一落点**)。今天的引擎没有隔离格 ⇒ 只写 `principal`,`isolationScope` 在这里不落(引擎按人分它自己的那几面);
- * 引擎的隔离格到货 ⇒ 这里加一格,别处不动。
+ * 引擎的隔离格到货 ⇒ 这里加一格,同一提交里 {@link engineScopeOf} 改读 core 的 `isolationScopeOf`(身份格闭集型在那里编译红,逼读法表态),别处不动。
  */
 export declare function taskSpecIdentityOf(parts: SubjectParts | undefined): {
     readonly principal?: string;
 };
+/**
+ * 🔴 **一只主体在引擎按身份分的那几面上的 scope —— 唯一一只换算**(工作流行的 `scope` 列 / 后台登记簿 / 会话信箱盒与被扣来信的队列 / 停止标记 / 名册:
+ * 引擎写下它们时用的那一个值)。规则 = core 写侧那一条,落在本仓交给引擎的身份格({@link taskSpecIdentityOf})上 ⇒ {@link scopeOfLanded}:
+ *  · core 7.66.0(本仓钉的版本):工作流行 `scope` = `ctx.principal ?? 挂载 scope`(`createRunWorkflowTool` 的 `execute` 里的 `taskScope`;`startWorkflow` 缺席落
+ *    `"default"`)—— `ctx.principal` 是 Runner 填的 `spec.principal`;挂载 scope 与后台登记簿 / 被扣来信队列同一个量,即 Runner 准备任务时算的任务 scope
+ *    `registryScope ?? spec.principal ?? "default"`(同一个值挂进 `run_workflow`、交给信箱排空腿开 held 队列)。本仓不供 `registryScope` ⇒ 各面同值 = 落下的
+ *    `principal`,匿名 = `"default"`。
+ *  · core 的下一形([ref] 隔离格随 7.68.0 到货;[ref] 同版根导出 `callScopeOf` / `isolationScopeOf`):`callScopeOf(ctx, 挂载) = ctx.isolationScope ?? 挂载.scope`,
+ *    Runner 把 `ctx.isolationScope` 填成 `isolationScopeOf(spec) = spec.isolationScope || spec.principal`;落点只写 `principal` 时两形同值。
+ * **随 core [ref] 到货换读、退本读法**:提货车让落点写出隔离格的同一提交里,这里改读 core 根导出的 `isolationScopeOf`(落下的身份格 ⇒ `?? "default"`),
+ * {@link scopeOfLanded} 退役 —— 落点多一格而读法没表态 = 编译红(身份格闭集,见它)。真 core 对拍钉:`test/workflow-scope-core-parity.test.ts`。
+ * 工作流行「归谁」只在属主存取器经它判(`http/owner-access.ts` 的 `workflowScopeOf`:列表 / 按 id / 舰队流同读)。
+ */
+export declare function engineScopeOf(subject: Subject | undefined): string;
+/** 一只**持久的**属主串(会话 / run 行的属主列、续跑腿交来的属主、请求鉴权句柄的纯串主体)在那几面上的 scope:先过内部恢复管线,再经 {@link engineScopeOf};无主 ⇒ 匿名那一格。 */
+export declare function engineScopeOfOwner(owner: string | null | 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, recoveredSubject } from "./owner-faces.js";
 export function specIdentityOf(parts) {
     if (parts === undefined)
         return { principal: undefined };
@@ -7,4 +9,15 @@ export function taskSpecIdentityOf(parts) {
     const { principal } = specIdentityOf(parts);
     return principal === undefined ? {} : { principal };
 }
+export function engineScopeOf(subject) {
+    return scopeOfLanded(taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)));
+}
+export function engineScopeOfOwner(owner) {
+    return engineScopeOf(recoveredSubject(owner));
+}
+function scopeOfLanded(landed) {
+    const { principal, ...unread } = landed;
+    unread;
+    return principal ?? LEGACY_UNOWNED_AMNESTY_TENANT;
+}
 //# sourceMappingURL=engine-identity.js.map

package/dist/entry-mode-clamp-notice.d.ts

@@ -10,7 +10,8 @@
  * ## 铸点(唯一)
  * {@link buildEntryModeClampNotice} 是本码**唯一**的铸点;调用点只有一处:`http/admission.ts` 的 `prepareSpec`(提交入口,盖章之后、装配
  * 之后 —— 那时会话 id 才定)。一次提交一次 ⇒ 一条 run 至多一帧(core 码册的去重单位「once per run」)。读的是盖章那一次求值的读数
- * (`EntryPermissionMode`),不另判一遍「折没折」。续跑腿不铸:它们重放的是已盖过章的存储体,折叠只发生过一次。
+ * (`EntryPermissionMode`),不另判一遍「折没折」。续跑腿不铸:续跑口按**现**地板钳存储体的词时(`permission-mode-admission.ts` `stampReplayEntryMode`),
+ * 那一腿的生效词由它的 `wiring_manifest.permissionMode` 说(引擎收到的就是钳过的词);本码只说受理门那一折(per run 一帧)。
  * 装配期铸、腿开口那一拍投(`PreparedTaskSubmission.engineNotices` → `registerEngineNoticeLeg` 的 `pending`)—— 与请求腿 MCP 丢弃同一条投递路,
  * 白名单 / 归属 / 消毒 / 隔离一个不绕。
  *

package/dist/execution-env-refusal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 本仓自铸的**执行环境拒码**闭集(`env.*` 族)的唯一属主(纯叶:零值依赖)。
+ *
+ * 一族一句:**这只执行环境没开,而且再问也是同一个答** —— 部署状态(或会话数据)与这条 run 冲突,原样重试不改判,出路在部署。两处产出、同一族:
+ *  · host 车道的工厂在铸环境之前拒(读数在构造时就到手:`lane-home-probe.ts` 的 `laneHomeRefusal`),引擎在准备期原样再抛;
+ *  · 远端车道在建连时答的**立定拒**(这只环境此后每一次建连都答同一个拒,适配器记住它):码由 `plugins/remote-env-connect-seat.ts` 的拒因表从事实词拼出
+ *    —— 那张表是远端车道拼本族码的唯一入口,立定 ⇔ 码在引擎可重试表之外 ⇔ 记住。
+ * 同步提交腿按零工作拒落档(`runs.ts` 的 `EXECUTION_ENV_REFUSAL_HTTP_STATUS`,按本闭集键控:加一员而档没跟 ⇒ tsc 红)。
+ *  · `env.home_unconfirmed` —— 家目录主张证不了(`judgeLaneHome` 的三形拒句:读不出 / 不是绝对路径 / 与实测不一致;远端车道只在环境**答了**的两形上记住它)。
+ *    三形一个码:出路都在部署(声明、环境里的 `HOME`,或会话 `settings.env` 里的 `HOME`),消费端不按形分岔;是哪一形、怎么改,句子里说。
+ *  · `env.snapshot_bucket_missing` —— k8s 车道的工作区快照桶不在(对象存储对 `latest` 或归档的读答 `404 NoSuchBucket`):建桶,或把
+ *    `WORKSPACE_SNAPSHOT_BUCKET` 指向已有的桶,或 `WORKSPACE_PERSIST=off`。
+ *  · `env.occupant_missing` —— k8s 车道读这条 run 的会话住客:会话行在、却不带住客令牌(存储数据缺陷,重发不改判):给行补令牌或删会话,或关掉要它的旋钮。
+ *  · `env.sandbox_refused` —— 隔离车道(k8s / e2b / local-docker)替这条 run 建的沙箱被立定地拒:集群在准入时拒了 pod、成员凭据中继建不起来、
+ *    快照归档在桶里却取不回、工作区的填充(会话附件 / 项目包种子)放不进且换一台机器也是同一个答。是哪一件、怎么改,句子里说。
+ *  · `env.host_key_rejected` —— ssh 车道:目标机出示的主机密钥过不了部署钉的判(`SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS`:指纹不符、条目换了钥、被吊销、没有条目)。
+ *    改钉或查明对面为什么换了钥;同一配置同一主机每次同答。
+ */
+export declare const EXECUTION_ENV_REFUSAL_CODES: readonly ["env.home_unconfirmed", "env.snapshot_bucket_missing", "env.occupant_missing", "env.sandbox_refused", "env.host_key_rejected"];
+export type ExecutionEnvRefusalCode = (typeof EXECUTION_ENV_REFUSAL_CODES)[number];
+/** 这个码是不是本族的一员(按闭集,不按前缀:引擎自己的 `env.lifetime_expired` 同前缀而不是本族)。 */
+export declare function isExecutionEnvRefusalCode(code: unknown): code is ExecutionEnvRefusalCode;
+//# sourceMappingURL=execution-env-refusal.d.ts.map

package/dist/execution-env-refusal.js

@@ -0,0 +1,5 @@
+export const EXECUTION_ENV_REFUSAL_CODES = ["env.home_unconfirmed", "env.snapshot_bucket_missing", "env.occupant_missing", "env.sandbox_refused", "env.host_key_rejected"];
+export function isExecutionEnvRefusalCode(code) {
+    return typeof code === "string" && EXECUTION_ENV_REFUSAL_CODES.includes(code);
+}
+//# sourceMappingURL=execution-env-refusal.js.map

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

@@ -184,7 +184,7 @@ export declare function deployedExecutionLanes(config: Pick<ServiceConfigFlat, "
  * 读者问的都是这一句,**同一只函数**,不许各写一份 `=== "host"`:
  *  ① 部署形表行 `toolsOnThisHost`(`deployment-shape.ts`)—— wire `executionLane.toolsOnThisHost` + 出厂自扫技能与中心 plugin 技能的 `baseDir`;
  *  ② 部署形表行 `callerOwnsWorkerDisk`(本列 ∧ 单主)—— SendUserFile 本机腿(「无手不挂」)、调用方宿主路径(附加目录 / 项目上下文)、指令文件探针、
- *     本机语言服务器(`createLspManager`;这类车道的适配器必须绑得住读 `openBound`,对拍钉 `test/host-env-open-bound.test.ts`);
+ *     本机语言服务器(`createLspManager`;「绑得住读」`openBound` 不是本列的事,是每条有手车道的结构前提,见 {@link laneWiresExecutionEnv});
  *  ③ `approval.ts` 的 `buildNoResponderBootWarns` —— 写门的 ask 只在「有手写本机盘」时才会发生(它手里已有车道词,直接读本列)。
  */
 export declare function handsOnWorkerFilePlane(lane: ExecutionLane): boolean;
@@ -230,6 +230,8 @@ export declare function laneIsolated(lane: ExecutionLane): boolean;
  * 这条车道**有没有手**(块 `io`:文件与 shell 两面真到达目标;`none` 的桩块 false)的唯一布尔口。读者四处:路由的「有没有执行环境」(`boot/resolve-spec.ts`)、
  * wire `executionLane.isolated` 的在场判据(`capabilities/execution-lane.ts`)、场景详情的附件供给集(`boot/stage-07-capability-layer.ts` 把它填进
  * `ScenarioDeps.handsLane`:「这一 run 有没有工作区」的车道半场)、起服家目录那一行({@link buildLaneHomeBootNote})—— 同读这一只。
+ * 有手车道的结构前提:适配器有绑定读面(`openBound`;设备的面 presence-typed,执行器声明了才装)—— 「能不能绑定读」的源是适配器对象本身,
+ * 本列不另存一位(对拍钉 `test/host-env-open-bound.test.ts` P3;本版唯一缓装 = ssh,同文件 `HELD_THIS_VERSION`,翻回条件钉在那里)。
  */
 export declare function laneWiresExecutionEnv(lane: ExecutionLane): boolean;
 /** 一条**已登记**的分叉:表写的是目标态,今天的判别式还答别的。 */

package/dist/field-conflict.d.ts

@@ -7,15 +7,15 @@ export type FieldConflictReason = (typeof FIELD_CONFLICT_REASONS)[number];
  * 动态下标的坐标用模板字面量型(`agents[1].skills`)。
  */
 export interface FieldConflictCoordinates {
-    readonly cascade_verify: "verify" | "cascade" | "sandboxImageProfile" | "resumeAt" | "suggestNextPrompts";
+    readonly cascade_verify: "verify" | "cascade" | "sandboxImageProfile" | "resumeAt" | "rewindFilesTo" | "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/file-history-capture.d.ts

@@ -52,21 +52,28 @@ export interface FileHistoryAssembly {
     /** 擦除脸:在场 ⟺ 后端在(与旋钮无关;是 {@link store} 的删除类动词视图)。 */
     readonly erasure: FileHistoryErasureFace | undefined;
 }
-/** 装配:「这台部署有没有文件历史店」的唯一判定。旋钮不在这里 —— 它只关捕获,不摘店([ref])。 */
+/** 「这台部署有没有文件历史店」的唯一判定:店是后端恒交的那一只(`StoreBackend.fileHistory()`,落定席位写的同一只)⇒ 店在 ⟺ 后端在。旋钮不在这里 ——
+ *  它只关捕获,不摘店([ref])。只问「在不在」的读者(能力位)读这一只,不必取店。 */
+export declare function fileHistoryWired(backend: StoreBackend | undefined): backend is StoreBackend;
+/** 装配:取那只店(判定 = {@link fileHistoryWired})。起服装配(引擎的还原族 / 擦除脸)与服务面要店的读者(同步族、rewind 口)都经这里取,手里有后端 ⇒ 型上就有店。 */
+export declare function assembleFileHistory(backend: StoreBackend): {
+    readonly store: ServiceFileHistoryStore;
+    readonly erasure: FileHistoryErasureFace;
+};
 export declare function assembleFileHistory(backend: StoreBackend | undefined): FileHistoryAssembly;
 /**
- * 「捕不捕」的**唯一**判定(纯函数):能力词。`store` = 装配出来的店(在不在),`knob` = 部署旋钮 `FILE_HISTORY_CAPTURE`
+ * 「捕不捕」的**唯一**判定(纯函数):能力词。`wired` = 店在不在({@link fileHistoryWired} 的答 / 装配出来的店在不在),`knob` = 部署旋钮 `FILE_HISTORY_CAPTURE`
  * (`config.fileHistoryCapture`)。从**装配结果**派生,不照旋钮字面回声:后端本来就没有这只店的部署同样是 `off`。
  *
  * 与 `restoreFiles` 分叉([ref] 当时写下的分叉条件,自 [ref] 成真):本词答「这台部署捕不捕、能不能按 run 关掉」,
  * `restoreFiles` 答「这台部署能不能还原」—— 旋钮关的部署本词 `off` 而 `restoreFiles` 仍为真。
  */
-export declare function fileHistoryCaptureOf(store: object | undefined, knob: boolean): FileHistoryCapture;
+export declare function fileHistoryCaptureOf(wired: boolean, knob: boolean): FileHistoryCapture;
 /**
  * core 的部署捕获位 `RunnerDeps.fileHistoryCapture`,由 {@link fileHistoryCaptureOf} 派生(同一组输入、同一只判定)。
  * 形照 `execution-lane-caps.ts` 的穷举 switch(无 default 臂):能力词加一个而这里不加臂 ⇒ 编译红 —— 加臂的那一刻就是
  * 决定「这一词下 core 的捕获位怎么递」的地方。没有店 ⇒ 恒 `undefined`(core 对「off 但没店」拒 prepare)。
  */
-export declare function coreFileHistoryCaptureSeat(store: object | undefined, knob: boolean): RunnerDeps["fileHistoryCapture"];
+export declare function coreFileHistoryCaptureSeat(wired: boolean, knob: boolean): RunnerDeps["fileHistoryCapture"];
 export {};
 //# sourceMappingURL=file-history-capture.d.ts.map