@sema-agent/server 7.145.0 → 7.147.0

package/dist/deploy-facts.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 随包的引擎部署事实(npm 包内 `deploy/facts/`)—— 成员集、Schema 方言、形变登记表的**唯一定义处**,以及其中两份成员(车道 / 钥匙保管目录)的投影与 Schema。
+ *
+ * ## 成员律
+ * `deploy/facts/` 只装**引擎自己的部署要求**:引擎发出的 API 调用、引擎按名读的键与目录、引擎要求先存在的条件。每一份都有引擎属主,都是生成物
+ * (唯一生成器 `scripts/gen-deploy-lanes.ts`,`--check` 与 `test/deploy-lane-projections.test.ts` 钉「入库 ≡ 生成物」),从不手写。
+ * 部署方拥有的策略实例(引擎读来诊断、不据以发调用的东西,例如沙箱出网的 NetworkPolicy)不是成员。
+ * 每个成员 `<m>` = 数据 `<m>.json` + 一份机器可读 Schema `<m>.schema.json`;另有一份形变登记 `CHANGES.json`。三类文件都是 npm 子路径
+ * `@sema-agent/server/deploy/facts/<文件>`(子路径 = 包内文件路径)。
+ *  · `lanes`:每条执行车道的租户档、隔离位、必需键 —— 投影自 settings-schema 车道表与执行环境能力块({@link LANE_FACTS_SCHEMA};行由生成器从同一个车道模型渲出,
+ *    安装器那张旧车道表的 `users` / `isolation` 两列也从这些行派生,同源零双写);
+ *  · `sandbox-rbac`:k8s 沙箱服务账号的 RBAC 规则表 —— 表与 Schema 都在 `src/sandbox-rbac-rules.ts`(和表放一起);
+ *  · `sealed-key`:钥匙保管目录的安装契约 —— 投影自 `src/sealed-key-layout.ts` 的布局常量与配置读法「`SEALED_KEY_DIR` 须是绝对路径」({@link SEALED_KEY_FACTS})。
+ *
+ * ## 契约:「未登记的加性形变,或未抬版的破坏性形变 ⇒ 红」
+ * 发车链对**上一个已发 tag** 里的同名 Schema 求差(`scripts/deploy-facts-gate.ts`;CI 浅克隆读不到 tag,这道判据在发车链跑),
+ * 差异逐条分成加性 / 破坏性,与 {@link FACTS_SCHEMA_CHANGES} 里本版新登记的条目对账。**加性只有一种:新增一个可选属性**;其余任何形变
+ * (删属性、改类型、可选 ⇄ 必有、新增必有属性、`items` 形变、闭集增 / 删词、`const` 变、`minItems` / `uniqueItems` / `x-uniqueKey` 变)都是破坏性。
+ * 值的含义变了而 Schema 不变(例如重新定义某个闭集词)门判不出 —— 改动者登记一条 `breaking` 并写明 `why`,复审按这一条问。
+ *
+ * ## 版本
+ * 每个成员的 `schemaVersion` **从登记表派生**({@link factsSchemaVersion}):首发那一版 = 1,此后每个登记了 `breaking` 的版本 +1。不另写常量 ——
+ * 登记一条破坏性形变就抬了版,「改了形忘了抬版」只剩「改了形没登记」一种,门对着已发 tag 抓它。
+ * 读方义务:用**同一个包里**那份 Schema 校验;不认识的 `schemaVersion` 整份拒读;同一版本内的未知键忽略。
+ */
+import { TENANT_SEPARATION_WORDS } from "@sema-agent/settings-schema/execution-lanes";
+/** 包内目录(npm 子路径前缀 `@sema-agent/server/deploy/facts/`)。 */
+export declare const DEPLOY_FACTS_DIR = "deploy/facts";
+/** 成员闭集。加一个成员 = 这里加一个词 + 生成器给它数据与 Schema + 登记表一条 `introduced`(缺任一处 ⇒ 编译错或生成抛)。 */
+export declare const DEPLOY_FACTS_MEMBERS: readonly ["lanes", "sandbox-rbac", "sealed-key"];
+export type DeployFactsMember = (typeof DEPLOY_FACTS_MEMBERS)[number];
+/** 形变登记表的文件名(与成员同目录;不是成员,没有自己的 Schema)。 */
+export declare const DEPLOY_FACTS_CHANGES_FILE = "CHANGES.json";
+/** 方言 = JSON Schema 2020-12 的一个闭子集;根上的 `$schema` 恒为它。 */
+export declare const FACTS_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/**
+ * 方言的节点形(类型就是方言:多写一个关键字 = 编译错;`scripts/deploy-facts-gate.ts` 在 JSON 面再判一次,拿到的是入库文件与已发 tag 上的文件)。
+ *  · 标量:`string`(可带 `enum` 闭集或 `const`)/ `integer`(可带 `const`)/ `boolean`;
+ *  · 对象:`properties` + `required`(⊆ properties)+ `additionalProperties: false`(恒关:未登记的键不许出现);
+ *  · 数组:`items`(必有)+ 可选 `minItems`;标量元素可声明 `uniqueItems: true`,对象元素可声明 `x-uniqueKey`(这几个属性的值组合在数组里唯一;
+ *    成员必须是元素的必有属性、且是标量或标量数组 —— 对象成员里加可选属性按上面的判法是加性,却会让旧读方算出的唯一性失真;
+ *    标准校验器把它当注解忽略,本仓的校验器执行它)。
+ *  · JSON 键一律只认自有的(`toString` / `constructor` / `__proto__` 这类原型链上的名字不算「在」)。
+ *  · `description` 任何节点都可带,差异判法不看它(值含义的变化走人工登记)。
+ */
+export type FactsScalarSchema = {
+    readonly type: "string";
+    readonly enum?: readonly string[];
+    readonly const?: string;
+    readonly description?: string;
+} | {
+    readonly type: "integer";
+    readonly const?: number;
+    readonly description?: string;
+} | {
+    readonly type: "boolean";
+    readonly description?: string;
+};
+export interface FactsObjectSchema {
+    readonly type: "object";
+    readonly properties: {
+        readonly [key: string]: FactsNodeSchema;
+    };
+    readonly required: readonly string[];
+    readonly additionalProperties: false;
+    readonly description?: string;
+}
+export interface FactsArraySchema {
+    readonly type: "array";
+    readonly items: FactsNodeSchema;
+    readonly minItems?: number;
+    readonly uniqueItems?: true;
+    readonly "x-uniqueKey"?: readonly string[];
+    readonly description?: string;
+}
+export type FactsNodeSchema = FactsScalarSchema | FactsObjectSchema | FactsArraySchema;
+/**
+ * 每种节点允许的关键字(运行期闭集;`scripts/deploy-facts-gate.ts` 的方言判读它,对入库文件与已发 tag 上的文件都判)。
+ * `satisfies` 让这张表只列类型里有的键;类型里多出来而表里没列的键,生成器在渲 Schema 时当场抛「方言外的关键字」。根节点另多一个 `$schema`。
+ */
+export declare const FACTS_SCHEMA_KEYWORDS: {
+    readonly string: readonly ["type", "enum", "const", "description"];
+    readonly integer: readonly ["type", "const", "description"];
+    readonly boolean: readonly ["type", "description"];
+    readonly object: readonly ["type", "properties", "required", "additionalProperties", "description"];
+    readonly array: readonly ["type", "items", "minItems", "uniqueItems", "x-uniqueKey", "description"];
+};
+/** 根:一个对象节点 + `$schema`;`schemaVersion` 必有且形恒为 `{ type: "integer", const: <版本> }`(门把这一处当版本通道,不当形变)。 */
+export interface FactsRootSchema extends FactsObjectSchema {
+    readonly $schema: typeof FACTS_SCHEMA_DIALECT;
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly type: "integer";
+            readonly const: number;
+            readonly description?: string;
+        };
+        readonly [key: string]: FactsNodeSchema;
+    };
+}
+export declare const FACTS_SCHEMA_CHANGE_KINDS: readonly ["introduced", "additive", "breaking"];
+export type FactsSchemaChangeKind = (typeof FACTS_SCHEMA_CHANGE_KINDS)[number];
+/**
+ * 一条形变登记。`pointer` = 实例路径:`""` 是整份,`/lanes/[]/isolation` 是 `lanes` 数组每一行的 `isolation`(`[]` = 数组元素)。
+ * `version` = 这条形变随哪个 server 版本发出;已发版本的条目只读(门:基线 tag 上的每一条在本树里原样还在)。
+ */
+export interface FactsSchemaChange {
+    readonly version: string;
+    readonly file: DeployFactsMember;
+    readonly kind: FactsSchemaChangeKind;
+    readonly pointer: string;
+    readonly why: string;
+}
+/**
+ * 形变登记表(只追加;生成器把它写成随包 `CHANGES.json` 与 README 的变更节)。
+ * 新条目的 `version` 写下一个要发的 server 版本;发车链在版本号抬起后核「本版新登记的条目都是这个版本」。
+ */
+export declare const FACTS_SCHEMA_CHANGES: readonly FactsSchemaChange[];
+/**
+ * 成员当前的 `schemaVersion`:登记表里恰一条 `introduced`(那一版 = 1),此后每个登记了 `breaking` 的**不同**版本 +1
+ * (同一版本里登记几条破坏性形变都只抬一次;首发那一版里的 `breaking` 不算 —— 那时还没有发出去的形)。
+ * 登记表不合这个形(零条 / 多条 `introduced`)⇒ 抛:版本号无从派生,不猜。
+ */
+export declare function factsSchemaVersion(member: DeployFactsMember, changes?: readonly FactsSchemaChange[]): number;
+/** 隔离位闭集:手跑在不在 OS 级隔离边界里(执行环境能力块的 `isolation` 位;安装器旧车道表的 `isolation` 列也读这两个词)。 */
+export declare const LANE_ISOLATION_WORDS: readonly ["supported", "unsupported"];
+export type LaneIsolationWord = (typeof LANE_ISOLATION_WORDS)[number];
+/** `lanes.json` 的一行(行序 = settings-schema 车道词序)。 */
+export interface LaneFactsRow {
+    readonly lane: string;
+    readonly tenantSeparation: (typeof TENANT_SEPARATION_WORDS)[number];
+    readonly isolation: LaneIsolationWord;
+    readonly requiredEnv: readonly string[];
+    readonly requiredSecretEnv: readonly string[];
+}
+export declare const LANE_FACTS_SCHEMA: FactsRootSchema;
+/** 钥匙保管目录对安装器的要求(闭集;每个词的意思写在 Schema 的 `description` 里)。 */
+export declare const SEALED_KEY_REQUIREMENTS: readonly ["persist-across-restart", "shared-by-all-replicas", "writable", "whole-directory"];
+export type SealedKeyRequirement = (typeof SEALED_KEY_REQUIREMENTS)[number];
+/** 保管目录路径形的闭集:只收绝对路径(相对路径起服拒)。 */
+export declare const SEALED_KEY_DIR_PATH_FORMS: readonly ["absolute"];
+/**
+ * `sealed-key.json` 的内容:安装契约要求**显式设一个绝对路径的 `SEALED_KEY_DIR`**,安装器据此挂卷。
+ * 没设它时引擎回落到数据根下的 `sealed-key/`(数据根自身还有一条回落链)—— 那是引擎内部行为,安装器不依赖它,所以不在这份事实里。
+ */
+export declare const SEALED_KEY_FACTS: {
+    readonly schemaVersion: number;
+    readonly dirEnv: "SEALED_KEY_DIR";
+    readonly dirPath: "absolute";
+    readonly subdirs: readonly ["checkpoint-ctx-keys"];
+    readonly dirMode: string;
+    readonly fileMode: string;
+    readonly requirements: readonly ["persist-across-restart", "shared-by-all-replicas", "writable", "whole-directory"];
+};
+export declare const SEALED_KEY_FACTS_SCHEMA: FactsRootSchema;
+//# sourceMappingURL=deploy-facts.d.ts.map

package/dist/deploy-facts.js

@@ -0,0 +1,95 @@
+import { TENANT_SEPARATION_WORDS } from "@sema-agent/settings-schema/execution-lanes";
+import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE } from "./sealed-key-layout.js";
+import { OWNER_ONLY_FILE_MODE } from "./plugins/owner-only-file-mode.js";
+export const DEPLOY_FACTS_DIR = "deploy/facts";
+export const DEPLOY_FACTS_MEMBERS = ["lanes", "sandbox-rbac", "sealed-key"];
+export const DEPLOY_FACTS_CHANGES_FILE = "CHANGES.json";
+export const FACTS_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export const FACTS_SCHEMA_KEYWORDS = {
+    string: ["type", "enum", "const", "description"],
+    integer: ["type", "const", "description"],
+    boolean: ["type", "description"],
+    object: ["type", "properties", "required", "additionalProperties", "description"],
+    array: ["type", "items", "minItems", "uniqueItems", "x-uniqueKey", "description"],
+};
+export const FACTS_SCHEMA_CHANGE_KINDS = ["introduced", "additive", "breaking"];
+export const FACTS_SCHEMA_CHANGES = [
+    { version: "7.146.0", file: "lanes", kind: "introduced", pointer: "", why: "首发:每条执行车道的租户档、隔离位与必需键,行集 = 所依 settings-schema 的全部车道词" },
+    { version: "7.146.0", file: "sandbox-rbac", kind: "introduced", pointer: "", why: "首发:k8s 沙箱服务账号的 RBAC 规则表(每条规则何时授、引擎真调还是兼容保留)" },
+    { version: "7.146.0", file: "sealed-key", kind: "introduced", pointer: "", why: "首发:钥匙保管目录的安装契约(显式绝对 SEALED_KEY_DIR、整个目录跨重启持久且各副本共享、目录与文件的权限位)" },
+];
+export function factsSchemaVersion(member, changes = FACTS_SCHEMA_CHANGES) {
+    const own = changes.filter((c) => c.file === member);
+    const intro = own.filter((c) => c.kind === "introduced");
+    const [first] = intro;
+    if (intro.length !== 1 || first === undefined)
+        throw new Error(`deploy-facts: member "${member}" needs exactly one "introduced" entry in FACTS_SCHEMA_CHANGES (found ${intro.length}) — its schemaVersion cannot be derived`);
+    return 1 + new Set(own.filter((c) => c.kind === "breaking" && c.version !== first.version).map((c) => c.version)).size;
+}
+export const LANE_ISOLATION_WORDS = ["supported", "unsupported"];
+const envNames = (description) => ({ type: "array", uniqueItems: true, items: { type: "string" }, description });
+export const LANE_FACTS_SCHEMA = {
+    $schema: FACTS_SCHEMA_DIALECT,
+    description: "引擎的执行车道事实:每条车道分不分租户、手跑在不在 OS 级隔离边界里、选它时引擎起服必须读到的键。行集 = 本包所依 settings-schema 车道表的全部车道词(含没有安装器接线的车道)。",
+    type: "object",
+    additionalProperties: false,
+    required: ["schemaVersion", "lanes"],
+    properties: {
+        schemaVersion: { type: "integer", const: factsSchemaVersion("lanes"), description: "本份数据的形版本;读方不认识的版本整份拒读。" },
+        lanes: {
+            type: "array",
+            minItems: 1,
+            "x-uniqueKey": ["lane"],
+            description: "每条车道一行,行序 = 车道表次序。",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["lane", "tenantSeparation", "isolation", "requiredEnv", "requiredSecretEnv"],
+                properties: {
+                    lane: { type: "string", description: "车道词,即 REMOTE_EXEC 的取值。" },
+                    tenantSeparation: { type: "string", enum: TENANT_SEPARATION_WORDS, description: "supported = 可在多租户部署(REQUIRE_PRINCIPAL=true)上用;single-user-only = 只给单用户部署,多租户部署选它起服即拒。" },
+                    isolation: { type: "string", enum: LANE_ISOLATION_WORDS, description: "supported = 手跑在 OS 级隔离边界里(独立沙箱);unsupported = 手跑在没有 OS 级隔离的地方(服务容器本身、远端主机、设备)。" },
+                    requiredEnv: envNames("选这条车道时引擎起服必须读到的非密键(缺任一 ⇒ 起服拒)。"),
+                    requiredSecretEnv: envNames("选这条车道时引擎起服必须读到的密钥键(缺任一 ⇒ 起服拒;值由运维自备)。"),
+                },
+            },
+        },
+    },
+};
+export const SEALED_KEY_REQUIREMENTS = ["persist-across-restart", "shared-by-all-replicas", "writable", "whole-directory"];
+export const SEALED_KEY_DIR_PATH_FORMS = ["absolute"];
+const octal = (mode) => mode.toString(8).padStart(4, "0");
+const SEALED_KEY_DIR_ENV = "SEALED_KEY_DIR";
+export const SEALED_KEY_FACTS = {
+    schemaVersion: factsSchemaVersion("sealed-key"),
+    dirEnv: SEALED_KEY_DIR_ENV,
+    dirPath: SEALED_KEY_DIR_PATH_FORMS[0],
+    subdirs: [CHECKPOINT_CTX_KEY_SUBDIR],
+    dirMode: octal(SEALED_KEY_DIR_MODE),
+    fileMode: octal(OWNER_ONLY_FILE_MODE),
+    requirements: SEALED_KEY_REQUIREMENTS,
+};
+export const SEALED_KEY_FACTS_SCHEMA = {
+    $schema: FACTS_SCHEMA_DIALECT,
+    description: "引擎钥匙保管目录的安装契约:sealed 形模型钥匙的 X25519 钥匙对与停驻行凭据封签的钥匙都在这个目录里,私钥只存在这里。",
+    type: "object",
+    additionalProperties: false,
+    required: ["schemaVersion", "dirEnv", "dirPath", "subdirs", "dirMode", "fileMode", "requirements"],
+    properties: {
+        schemaVersion: { type: "integer", const: SEALED_KEY_FACTS.schemaVersion, description: "本份数据的形版本;读方不认识的版本整份拒读。" },
+        dirEnv: { type: "string", const: SEALED_KEY_FACTS.dirEnv, description: "安装器必须给引擎设的环境变量:值 = 保管目录的挂载位。" },
+        dirPath: { type: "string", enum: SEALED_KEY_DIR_PATH_FORMS, description: "absolute = 值必须是绝对路径(相对路径起服即拒;设了而目录建不了保管店也起服拒)。" },
+        subdirs: { type: "array", uniqueItems: true, items: { type: "string" }, description: "引擎在保管目录之下自建的子目录(随目录一起持久、一起共享)。" },
+        dirMode: { type: "string", const: SEALED_KEY_FACTS.dirMode, description: "引擎每次起服把保管目录设成的权限位(四位八进制);目录必须允许引擎进程改它的权限。" },
+        fileMode: { type: "string", const: SEALED_KEY_FACTS.fileMode, description: "引擎写钥匙文件时设的权限位(四位八进制)。" },
+        requirements: {
+            type: "array",
+            minItems: 1,
+            uniqueItems: true,
+            items: { type: "string", enum: SEALED_KEY_REQUIREMENTS },
+            description: "persist-across-restart = 目录跨进程重启保留(不然重启后封给旧钥匙的密文与停驻行凭据开不开);shared-by-all-replicas = 同一部署的每个副本挂同一份目录(多副本要支持多处读写的存储;不然 A 副本封的东西 B 副本开不开);" +
+                "writable = 引擎对目录可写(空目录起服时生成一把钥匙;只读挂载 ⇒ 建不了保管店);whole-directory = 持久与共享的单位是整个目录,含 subdirs 列出的子目录。",
+        },
+    },
+};
+//# sourceMappingURL=deploy-facts.js.map

package/dist/deployment-shape.d.ts

@@ -9,7 +9,7 @@
  * ## 两根轴,每根轴一个读口(原始配置键只在这两个函数里被读)
  *  · `principal` —— 运维的 `REQUIRE_PRINCIPAL` 声明({@link readPrincipalAxis})。
  *  · `lane` —— `REMOTE_EXEC` 的归一车道词(`executionLaneOf`,认不出 ⇒ `undefined`,行必须 fail-closed)+ 那条车道的能力表行 +
- *    这份部署上执行环境的能力块(唯一作者 `capabilitiesFor`;k8s 的快照店是它的输入)+ 车道子旋钮(k8s 运行时类、隐式 host 尾臂记号)({@link readLaneAxis})。
+ *    这份部署上执行环境的能力块(唯一作者 `capabilitiesFor`;k8s 的快照店是它的输入)+ 车道子旋钮(k8s 运行时类)({@link readLaneAxis})。
  *
  * ## 轴列不是注释,是型
  * 每行的判官只收到它**声明**的那几根轴的事实({@link DeploymentShapeFacts}),读不到配置本身 —— 判官碰一根没声明的轴 = 编译红;
@@ -34,14 +34,14 @@ export interface PrincipalAxisFacts {
     /** 运维声明了 `REQUIRE_PRINCIPAL=true`。 */
     readonly declared: boolean;
 }
-/** `lane` 轴读的配置键:已装配的 `remoteExec` 里本表用得到的那几键(`ServiceConfig` 的判别联合每一臂结构上都满足)。 */
+/** `lane` 轴读的配置键:**已合成**的 `remoteExec` 里本表用得到的那几键(`ServiceConfig` 的判别联合每一臂结构上都满足;车道必在 ——
+ *  没有声明的部署在执行车道合成步拒启)。`provider` 收开放串:手搓的部署形 / 外部输入上认不出的词 ⇒ 行在 `lane` 那一格 fail-closed。 */
 export interface LaneAxisInput {
-    readonly remoteExec?: {
-        readonly provider?: string | undefined;
+    readonly remoteExec: {
+        readonly provider: string;
         readonly runtimeClass?: string | undefined;
         readonly s3Snapshot?: unknown;
-        readonly singleMachineDefault?: boolean | undefined;
-    } | undefined;
+    };
 }
 /** `lane` 轴的事实。 */
 export interface LaneAxisFacts {
@@ -53,8 +53,6 @@ export interface LaneAxisFacts {
     readonly block: ExecutionEnvCapabilities | undefined;
     /** k8s 的 `runtimeClass`(别的车道 `undefined`)。 */
     readonly k8sRuntimeClass: string | undefined;
-    /** host 车道值上带「单机形缺省」记号(唯一写者 = `config.ts` 三元链的隐式 host 尾臂;显式 `REMOTE_EXEC=host` 与文件覆写都不带)。 */
-    readonly singleMachineDefault: boolean;
 }
 /** 轴全集(闭集)→ 读入形与事实型。加一根轴 = 在这里加一键 + {@link readAxis} 的穷举 switch 加一臂(漏一处即编译红)。 */
 interface AxisShapes {
@@ -99,8 +97,8 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
     callerOwnsWorkerDisk: DeploymentShapePredicate<"lane" | "principal">;
     /** wire `executionLane.toolsOnThisHost` 与出厂 / 中心技能的 `baseDir`:只问文件系统同一性,与租户无关(出厂内容每个租户拿到同一份)。 */
     toolsOnThisHost: DeploymentShapePredicate<"lane">;
-    /** `REMOTE_EXEC` 未设的进程内形(没有手)且单主:进程级消费者(hooks 命令、项目上下文本机读、卡批规则 root)看到的就是引擎自己的进程 cwd / env。 */
-    inProcessSingleUser: DeploymentShapePredicate<"lane" | "principal">;
+    /** 无手形(声明 `none`;判据读执行环境块 `io`,不点名车道词)且单主:进程级消费者(hooks 命令、项目上下文本机读、卡批规则 root)看到的就是引擎自己的进程 cwd / env。 */
+    noHandsSingleUser: DeploymentShapePredicate<"lane" | "principal">;
     /** 任务层替部署声明宿主姿态(bypassPermissions 开写面 / host shell 继承整份环境)的射程:device 车道上跨租户宿主穿越结构性不存在(clay 裁定③)。 */
     taskHostPostureDeclarations: DeploymentShapePredicate<"lane" | "principal">;
     /** 写门走代理裁决(执行环境块 `hostLocalPaths` 为假:路径不是本 worker 盘上的文件);认不出的词 ⇒ 走代理(代理 slot 空 ⇒ 写门 fail-closed)。 */
@@ -121,8 +119,19 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      * 读者:boot `remote_exec_enabled.suspendable`。
      */
     suspendableHands: DeploymentShapePredicate<"lane">;
-    /** 读者两处:`config.ts` 车道落点一行的 `source`(覆写之前)与 `boot/execution-env.ts` 的 `remote_exec_real_system.note`(覆写之后)—— 同一个记号、两个时刻。 */
-    singleMachineDefaultLane: DeploymentShapePredicate<"lane">;
+    /**
+     * 即时回退的工作区是否活过一次执行 —— run 外回退口(`POST /v1/sessions/:id/rewind-files`)写下的文件要落在一棵下一次执行就从它开始的工作区里;
+     * 工作区随执行结束一起没了(或下一次执行从别处重建它)的部署上,引擎照样恢复、台账照样报「恢复了」,结果却到不了任何人手里(静默的写面 fail-open)。
+     * 按车道穷举(新车道 = 编译红;认不出的车道 ⇒ 不成立):
+     *  · `host`:调用方声明的项目目录 ⇔ 车道能力 `callerCwd` 在这台部署上成立(单主;多租形上每个任务一只用完即删的目录)。单只会话还要本进程登记过它的 cwd、且那只目录实在 —— 那一半是口的 409,不是部署形;
+     *  · `device` / `ssh` / `adb`:一台常驻的真机器,环境拆毁 = 断连,不删文件;
+     *  · `local-docker`(拆毁 = `docker rm -f`)/ `e2b`(拆毁 = 杀 VM):每个任务一只新环境;
+     *  · `k8s`:不开工作区持久化 ⇒ 一次性 pod;开了 ⇒ 下一次执行从快照店恢复工作区,而工作区填充链(恢复后的附件填充)与拆毁时的快照持久化都还没纳入回退用途
+     *    (回退那一次取环境照样填充附件、存新快照,存失败也进不了回退的应答)⇒ 本版不成立,重开另票(用途感知的填充 + 持久化结果进回退应答);
+     *  · `none`:没有执行环境(能力事实先判无手车道,这里照样表态)。
+     * 读者:能力事实 `sessionRewindFiles`(能力位与该口的 501 同读这一行)。
+     */
+    rewindableWorkspace: DeploymentShapePredicate<"lane" | "principal">;
 }>;
 export {};
 //# sourceMappingURL=deployment-shape.d.ts.map

package/dist/deployment-shape.js

@@ -1,16 +1,15 @@
-import { capabilitiesFor, executionLaneCaps, executionLaneOf, handsOnWorkerFilePlane } from "./execution-lane-caps.js";
+import { capabilitiesFor, executionLaneCaps, executionLaneOf, handsOnWorkerFilePlane, laneWiresExecutionEnv } from "./execution-lane-caps.js";
 function readPrincipalAxis(deployment) {
     return { declared: deployment.requirePrincipal === true };
 }
 function readLaneAxis(deployment) {
     const declaration = deployment.remoteExec;
-    const lane = executionLaneOf(declaration?.provider);
+    const lane = executionLaneOf(declaration.provider);
     return {
         lane,
         caps: lane === undefined ? undefined : executionLaneCaps(lane),
         block: capabilitiesFor(deployment),
-        k8sRuntimeClass: lane === "k8s" ? declaration?.runtimeClass : undefined,
-        singleMachineDefault: lane === "host" && declaration?.singleMachineDefault === true,
+        k8sRuntimeClass: lane === "k8s" ? declaration.runtimeClass : undefined,
     };
 }
 function readAxis(axis, deployment) {
@@ -52,7 +51,7 @@ export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
     callerCwd: createPredicate(["lane", "principal"], "车道 × 租户 / 设备归属:调用方送来的 cwd(与 settings.env)被尊重 —— host 车道且单主,或 device 车道。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.callerCwd, principal)),
     callerOwnsWorkerDisk: createPredicate(["lane", "principal"], "车道 × 租户:手就在本 worker 的盘上且部署只有一个主人 —— 这块盘上的路径就是调用方自己的。", ({ lane, principal }) => lane.lane !== undefined && handsOnWorkerFilePlane(lane.lane) && !principal.declared),
     toolsOnThisHost: createPredicate(["lane"], "车道:工具跑的那台机器就是本进程这台(手挂上了且文件平面在本 worker 盘上;车道列 handsOnWorkerFilePlane)。", ({ lane }) => lane.lane !== undefined && handsOnWorkerFilePlane(lane.lane)),
-    inProcessSingleUser: createPredicate(["lane", "principal"], "车道 × 租户:进程内车道(REMOTE_EXEC 未设)且部署只有一个主人。", ({ lane, principal }) => lane.lane === "in-process" && !principal.declared),
+    noHandsSingleUser: createPredicate(["lane", "principal"], "车道 × 租户:无手车道(声明 none;车道列 laneWiresExecutionEnv 为假)且部署只有一个主人。", ({ lane, principal }) => lane.lane !== undefined && !laneWiresExecutionEnv(lane.lane) && !principal.declared),
     taskHostPostureDeclarations: createPredicate(["lane", "principal"], "车道 × 租户 / 设备归属:任务层可以替部署声明宿主姿态 —— device 车道(发起者自己的设备),或单主部署。", ({ lane, principal }) => lane.lane === "device" || !principal.declared),
     sandboxPathAdjudication: createPredicate(["lane"], "车道:写门的路径事实要经代理到执行环境里取(文件平面不在本 worker 盘上;认不出的车道也走代理)。", ({ lane }) => lane.block === undefined || !lane.block.hostLocalPaths),
     sandboxSendUserFile: createPredicate(["lane", "principal"], "车道 × 租户:SendUserFile 的沙箱直传腿可以挂(沙箱盘 = 租户自己的任务工作区,或共享真机上的单主部署)。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.sandboxSendUserFile, principal)),
@@ -67,6 +66,25 @@ export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
         return runtimeClass.startsWith("kata") || VM_ISOLATION_RUNTIME_CLASSES.has(runtimeClass);
     }),
     suspendableHands: createPredicate(["lane"], "车道:执行环境可挂起(e2b;k8s 以配了 S3 工作区快照店为前提)。", ({ lane }) => lane.block?.suspendable === true),
-    singleMachineDefaultLane: createPredicate(["lane"], "车道:host 车道是单机形缺省落点(REMOTE_EXEC 未设 ∧ CONFIG_PROVIDER=local,没人点名)。", ({ lane }) => lane.singleMachineDefault),
+    rewindableWorkspace: createPredicate(["lane", "principal"], "车道 × 租户:即时回退的工作区活过一次执行 —— 单主 host、device、ssh、adb 成立;多租 host、local-docker、e2b 每个任务重建工作区;k8s 的工作区填充与快照持久化尚未纳入回退。", ({ lane, principal }) => {
+        switch (lane.lane) {
+            case "host":
+                return lane.caps !== undefined && capabilityHolds(lane.caps.callerCwd, principal);
+            case "device":
+            case "ssh":
+            case "adb":
+                return true;
+            case "k8s":
+            case "local-docker":
+            case "e2b":
+            case "none":
+            case undefined:
+                return false;
+            default: {
+                const unhandled = lane.lane;
+                throw new Error(`rewindableWorkspace: no ruling for lane ${String(unhandled)}`);
+            }
+        }
+    }),
 });
 //# sourceMappingURL=deployment-shape.js.map

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

@@ -38,6 +38,7 @@
 import http from "node:http";
 import { type DeviceOwner, type DeviceStore } from "./device-store.js";
 import type { DeviceEnrollment, DeviceRejection } from "./device-enrollment.js";
+import { type CidrSet } from "./net-address.js";
 import { type DeviceChunkKind, type DeviceInstructionArgsByKind, type DeviceInstructionKind, type DeviceInstructionOutcome } from "./device-ws-protocol.js";
 /** 交给调用方的一片上行流(`data` 已从 base64 解回字节)。 */
 export interface DeviceChunkDelivery {
@@ -159,10 +160,14 @@ export interface DeviceWsHubOptions {
     chunkBufferMaxBytes?: number;
     /** codex R1-F3:本副本**未鉴权**连接的并发帽(超额在 upgrade 阶段就 503 拒)。 */
     maxPreAuthConnections?: number;
-    /** codex R1-F3:单来源地址的未鉴权连接并发帽。[ref]([ref]):字面 `off` = 显式停用该层——
-     *  帽键是裸 remoteAddress,XFF 反代 / 公司 NAT 部署形把全员折叠成单键,这层从公平层退化成
-     *  「全员共享一份预算」;停层后全局帽(`maxPreAuthConnections`)照常兜底。 */
+    /** codex R1-F3:单来源地址的未鉴权连接并发帽。[ref]([ref]):字面 `off` = 显式停用该层;停层后全局帽
+     *  (`maxPreAuthConnections`)照常兜底。帽键 = 真实对端的规范形({@link readPreAuthRemoteKey}):名单
+     *  {@link trustedProxyCidrs} 空时就是 socket 对端 —— 反代 / 公司 NAT 后全员同一 socket 对端,这层是「全员共享一份预算」;
+     *  把自己的反代写进名单,这层就按反代转来的真实来源计。 */
     maxPreAuthConnectionsPerRemote?: number | "off";
+    /** [ref]:可信代理名单(CIDR 闭集;env `DEVICE_TRUSTED_PROXY_CIDRS`,配置层逐项校验)。缺省空 = 不读任何代理头(帽键 =
+     *  socket 对端,今日行为)。socket 对端落在名单内才读 `X-Forwarded-For`。坏项构造时抛(装配缝,与 helloAck 界同姿势)。 */
+    trustedProxyCidrs?: readonly string[];
 }
 export interface DeviceWsHub {
     /** 把 `GET /v1/device/ws` 的 upgrade 处理器挂到裸 `http.Server` 上。 */
@@ -204,5 +209,45 @@ export interface DeviceWsHub {
     declaredSupports(deviceId: string): ReadonlySet<DeviceInstructionKind> | undefined;
     close(): Promise<void>;
 }
+/** 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];
+/** 对端是可信代理而转发头展不开的缘由(闭集;warn `device_preauth_forwarded_unusable{reason}`)。 */
+export declare const DEVICE_FORWARDED_UNUSABLE_REASONS: readonly ["absent", "malformed", "all_trusted", "too_many_headers"];
+export type DeviceForwardedUnusableReason = (typeof DEVICE_FORWARDED_UNUSABLE_REASONS)[number];
+export type DevicePreAuthKey = {
+    readonly key: string;
+    readonly source: "socket" | "xff";
+} | {
+    readonly key: string;
+    readonly source: "fallback";
+    readonly reason: DeviceForwardedUnusableReason;
+};
+/**
+ * 可信对端的升级请求最多带几行头,汇聚端还认它的 `X-Forwarded-For`。node 对头行数超过它的上限(`server.maxHeadersCount`,缺省约 1000 行)
+ * 的请求要么**静默**丢掉多余的头、要么直接答 431(版本行为)。丢头那一形里,反代追加在末尾的那一行 XFF 正在尾部,丢了它,剩下的就只有
+ * 客户端自己垫在前面的那一行 —— 所以行数到这个数(或运维给 server 设的更低上限)⇒ 不采 XFF(回落 `too_many_headers`);答 431 那一形里
+ * 请求到不了这里。两形下垫在前面的 XFF 都不会成为帽键。一次设备握手连同反代自己加的头远不到 100 行;这个数刻意远低于 node 的缺省上限,
+ * 不随 node 版本漂。
+ */
+export declare const DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX = 100;
+/** 转发头的一次读数(只在对端可信时取):`header` = node 合并后的 `X-Forwarded-For`;`complete` = 请求头行数低于可信读数上限。 */
+export interface ForwardedForReading {
+    readonly header: string | readonly string[] | undefined;
+    readonly complete: boolean;
+}
+/**
+ * [ref]:per-remote 帽键 = **本连接真实对端的规范形**(`canonicalAddress`;IPv4-mapped 折成点分 IPv4 —— 同一台主机直连与经代理
+ * 是同一个键,不是两份名额)。
+ *
+ * 真实对端只有一个来源 = socket 对端;唯一的展开:socket 对端落在可信代理名单内 ⇒ 读 `X-Forwarded-For`(node 把重复头按到达序
+ * 以 `, ` 合并 = 同一张列表),**自右向左**逐项:名单内 = 又一层自己的代理,继续左移;第一个名单外的地址 = 键。选中项**以左**是
+ * 客户端自己写的段,不解析 —— 往那里塞什么都改不了键,也逼不出回落。
+ *
+ * 展不开(头行数到顶 / 头缺席 / 某项不是地址 / 全在名单内)⇒ 键 = socket 对端,`source=fallback`。🔴 这不是 fail-open,**不走 `recordFailOpen`**:
+ * 回落键把整只代理折成一个键,比展开更严(收紧方向),与名单空的今日行为同键;调用方另打一行带 reason 的 warn 指路。
+ * 名单外的对端:转发头读口一次都不调用(惰性 `readForwardedFor`;伪造 XFF 零效果)。不读 `Forwarded` / `X-Real-IP` / PROXY protocol —— 对端只有这一种展开。
+ */
+export declare function readPreAuthRemoteKey(peer: string | undefined, readForwardedFor: () => ForwardedForReading, trusted: CidrSet): DevicePreAuthKey;
 export declare function createDeviceWsHub(options: DeviceWsHubOptions): DeviceWsHub;
 //# sourceMappingURL=device-ws-hub.d.ts.map

package/dist/device-ws-hub.js

@@ -1,8 +1,10 @@
 import http from "node:http";
 import { createHash } from "node:crypto";
+import { isIP } from "node:net";
 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";
 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;
@@ -63,6 +65,41 @@ function assertHelloAckNumbersInBounds(values) {
         }
     }
 }
+export const DEVICE_PREAUTH_KEY_SOURCES = ["socket", "xff", "fallback"];
+export const DEVICE_FORWARDED_UNUSABLE_REASONS = ["absent", "malformed", "all_trusted", "too_many_headers"];
+export const DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX = 100;
+export function readPreAuthRemoteKey(peer, readForwardedFor, trusted) {
+    const raw = peer ?? "unknown";
+    const socketKey = canonicalAddress(raw) ?? raw;
+    if (!trusted.has(socketKey))
+        return { key: socketKey, source: "socket" };
+    const reading = readForwardedFor();
+    if (!reading.complete)
+        return { key: socketKey, source: "fallback", reason: "too_many_headers" };
+    const header = typeof reading.header === "string" ? reading.header : reading.header?.join(",");
+    if (header === undefined || header.replace(/[ \t]/g, "") === "")
+        return { key: socketKey, source: "fallback", reason: "absent" };
+    const hops = header.split(",");
+    for (let i = hops.length - 1; i >= 0; i--) {
+        const hop = forwardedHopAddress(hops[i]);
+        if (hop === undefined)
+            return { key: socketKey, source: "fallback", reason: "malformed" };
+        if (!trusted.has(hop))
+            return { key: hop, source: "xff" };
+    }
+    return { key: socketKey, source: "fallback", reason: "all_trusted" };
+}
+function forwardedHopAddress(hop) {
+    const t = hop.replace(/^[ \t]+|[ \t]+$/g, "");
+    if (t.startsWith("[")) {
+        const m = /^\[([^\]]*)\](?::\d{1,5})?$/.exec(t);
+        return m === null || isIP(m[1]) !== 6 ? undefined : canonicalAddress(m[1]);
+    }
+    const withPort = /^([^:]+):\d{1,5}$/.exec(t);
+    if (withPort !== null)
+        return isIP(withPort[1]) === 4 ? withPort[1] : undefined;
+    return canonicalAddress(t);
+}
 export function createDeviceWsHub(options) {
     const { store, enrollment, replicaId, logger, metrics } = options;
     const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15_000;
@@ -81,6 +118,7 @@ export function createDeviceWsHub(options) {
     const chunkBufferMaxBytes = options.chunkBufferMaxBytes ?? 2 * 1024 * 1024;
     const maxPreAuthConnections = options.maxPreAuthConnections ?? 64;
     const maxPreAuthConnectionsPerRemote = options.maxPreAuthConnectionsPerRemote ?? 8;
+    const trustedProxies = createTrustedProxySet(options.trustedProxyCidrs ?? []);
     const wss = new WebSocketServer({ noServer: true, maxPayload: DEVICE_WS_LIMITS.maxFrameBytes });
     const conns = new Map();
     const allConns = new Set();
@@ -757,6 +795,10 @@ export function createDeviceWsHub(options) {
         }, DEVICE_WS_LIMITS.handshakeDeadlineMs);
         sendServerFrame(conn, { t: "challenge", nonce: conn.nonce, protocolVersion: DEVICE_PROTOCOL_VERSION });
     }
+    function forwardedHeaderLineCeiling(server) {
+        const cap = server.maxHeadersCount;
+        return typeof cap === "number" && cap > 0 ? Math.min(DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX, cap) : DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX;
+    }
     function attach(server) {
         server.on("upgrade", (req, socket, head) => {
             const path = (req.url ?? "/").split("?")[0];
@@ -764,7 +806,11 @@ export function createDeviceWsHub(options) {
                 return refuseUpgrade(socket, 404);
             if (draining || closed)
                 return refuseUpgrade(socket, 503);
-            const remoteKey = req.socket.remoteAddress ?? "unknown";
+            const keyed = readPreAuthRemoteKey(req.socket.remoteAddress, () => ({ header: req.headers["x-forwarded-for"], complete: req.rawHeaders.length / 2 < forwardedHeaderLineCeiling(server) }), trustedProxies);
+            const remoteKey = keyed.key;
+            metrics?.inc("device_preauth_key_total", { source: keyed.source });
+            if (keyed.source === "fallback")
+                logger?.warn("device_preauth_forwarded_unusable", { reason: keyed.reason });
             const perRemoteCount = preAuthByRemote.get(remoteKey) ?? 0;
             const globalHit = preAuthCount >= maxPreAuthConnections;
             const perRemoteHit = maxPreAuthConnectionsPerRemote !== "off" && perRemoteCount >= maxPreAuthConnectionsPerRemote;
@@ -772,7 +818,7 @@ export function createDeviceWsHub(options) {
                 const arm = globalHit ? (perRemoteHit ? "both" : "global") : "per_remote";
                 metrics?.inc("device_preauth_refused_total", { arm });
                 logger?.warn("device_preauth_cap_hit", {
-                    remoteKey, arm, preAuthCount, cap: maxPreAuthConnections, perRemoteCount, perRemoteCap: maxPreAuthConnectionsPerRemote,
+                    remoteKey, keySource: keyed.source, arm, preAuthCount, cap: maxPreAuthConnections, perRemoteCount, perRemoteCap: maxPreAuthConnectionsPerRemote,
                 });
                 return refuseUpgrade(socket, 503);
             }

package/dist/env-facts.d.ts

@@ -1,5 +1,5 @@
 import type { ImageCapabilities } from "./plugins/store-contracts.js";
-import type { RemoteExecProvider } from "./execution-lane-caps.js";
+import type { ExecutionLane } from "./execution-lane-caps.js";
 export interface SandboxEnvFacts {
     profile?: string;
     capabilities?: string[];
@@ -54,7 +54,7 @@ export declare function buildEnvFacts(opts: {
  *  codex 复审 medium:k8s 必须按**有效快照能力**分叉,不能只看车道名——s3Snapshot 未配=park-only,
  *  resume 是全新 pod 且**工作区不恢复**,「文件已从快照恢复」那句会让模型信赖不存在的文件(比缺席
  *  更糟的谎)。 */
-export declare function resumeFactsForLane(provider: RemoteExecProvider | undefined, // 车道词 = settings-schema 词表正本(经本仓读口取型,不手抄;表加词 ⇒ 下方穷举 switch 编译红)
+export declare function resumeFactsForLane(provider: ExecutionLane, // 车道词 = settings-schema 词表正本(经本仓读口取型,不手抄;表加词 ⇒ 下方穷举 switch 编译红)
 caps?: {
     k8sSnapshot?: boolean;
 }): SandboxEnvFacts["resumeFacts"] | undefined;
@@ -73,6 +73,8 @@ export declare function scratchpadSessionSegment(sessionId: string): string;
  *  intermediate artifacts survive across turns/resume legs). Exported as the single source both the envFacts
  *  composer (below) and the future createFsWriteGatePolicy `exemptDirs` wiring ([ref]①, 1.290) must use. */
 export declare function scratchpadDirFor(localDataRoot: string, sessionId: string): string;
+/** 所有会话段的父目录 `<localDataRoot>/scratchpad`(段路径、过期清扫与一次性迁移 M39 的名册同读这一只)。 */
+export declare function scratchpadRootFor(localDataRoot: string): string;
 /** Resolve + CREATE the session scratchpad dir (mkdir -p, idempotent). Returns the path, or undefined when
  *  creation fails (honest-facts posture: never advertise a directory that does not exist — same class as
  *  egress/pkgSource "don't declare what you don't know"). Lifecycle: the reaper primitives live below —
@@ -149,7 +151,7 @@ export declare function screenShellScratchpadDir(raw: unknown, opts: {
  *    就是凭空多一条 400)。只判其一会留一条**跨请求**的洞:一条请求供一只合法壳 scratchpad 把判据引开、
  *    同时把 cwd 指进自算那只,放行后 cwd 坐进会话表,下一条不带路径字段的请求回落自算形、死在引擎构造期,
  *    而它根本没送过 cwd(codex r2 [medium] 实证);
- *  · **`in-process` 车道(provider 未设)不在射程**:那条腿的门根是**进程自己的 cwd**,与请求字段无关 ——
+ *  · **无手的 `none` 车道不在射程**:那条腿的门根是**进程自己的 cwd**,与请求字段无关 ——
  *    对着一个请求字段拒一件不是它造成的事,是把诊断指向错的地方(如实登记,不假装覆盖)。
  */
 export declare function scratchpadCoveringTaskRoot(args: {
@@ -183,7 +185,7 @@ export declare function sweepStaleScratchpads(localDataRoot: string, opts: {
 }): Promise<number>;
 /** Map the exec-lane posture to the egress fact (the model must know when downloads can't work). */
 export declare function egressForRemoteExec(remoteExec: {
-    provider?: string;
+    provider: string;
     allowInternetAccess?: boolean;
-} | undefined): "none" | "full" | undefined;
+}): "none" | "full" | undefined;
 //# sourceMappingURL=env-facts.d.ts.map