@sema-agent/server 7.138.0 → 7.140.0

package/dist/config.js

@@ -9,6 +9,7 @@ import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
 import { buildRuleListJudgeOptions } from "./permission-rule-list.js";
 import { isV2ScopeKey, memoryReplicationCoverage, replicatesProjectLayersOf } from "./memory-scope.js";
+import { memorySyncPeerOf } from "./memory-sync-client.js";
 import { assertProjectLayerOwnable } from "./project-identity.js";
 import { projectLayerOwnerOf } from "./project-layer-key.js";
 import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
@@ -26,7 +27,7 @@ import { THINKING_LEVELS, THINKING_FORMATS, buildModelCompat, isThinkingFormat,
 import {} from "./posture-source.js";
 import { COST_QUOTA_WINDOW_SEC_RANGE, costQuotaWindowSecInRange } from "./observability/cost-quota.js";
 import { NAME_TABLE_BEHAVIOR, TOOL_NAME_ROSTER, describeUnmatchableRuleName, ruleEntryToolName, unmatchableRuleNameOf } from "./namespaced-rule-name.js";
-import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal, operatorSingleUserRefusal, workflowParkDecisionDomainRefusal } from "./config-invariants.js";
+import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal, operatorSingleUserRefusal, remoteConfigProviderUrlRefusal, retentionLaneRefusal, workflowParkDecisionDomainRefusal } from "./config-invariants.js";
 import { declaredSemaConfigDir } from "./sema-config-dir.js";
 import { lkgPathOverrideOf } from "./config-lkg.js";
 import { K8S_WORKSPACE_MOUNT_DEFAULT, WORKSPACE_PERSIST_DEFAULT, WORKSPACE_PERSIST_WORDS, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_RANGE, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE, parseWorkspaceSnapshotExclude, parseWorkspaceSnapshotPrefix } from "./workspace-space.js";
@@ -35,7 +36,7 @@ import { laneLivenessOf } from "./exec-bounds.js";
 import { SANDBOX_IPV6_DEFAULT, SANDBOX_IPV6_WORDS } from "./sandbox-egress-policy.js";
 import { WORKSPACE_CACHE_DEFAULT, WORKSPACE_CACHE_MOUNT_DEFAULT, WORKSPACE_CACHE_MOUNT_RESERVED, WORKSPACE_CACHE_SIZE_DEFAULT, WORKSPACE_CACHE_WORDS, isK8sQuantity, mountsOverlap, reservedMountCollision } from "./workspace-cache.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
-import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, laneRequiredEnv } from "./execution-lane-caps.js";
+import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, laneMissingEnv } from "./execution-lane-caps.js";
 import { MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "@sema-agent/settings-schema/execution-lanes";
 import { AUTONOMY_MODES } from "./runtime-governance.js";
 import { MAX_NAMED_INERT_ENTRIES, allowLayerEntryCountIssue, describeInertRuleEntries, inertRuleEntriesOf, inertRuleEntryGuidance, ruleEntryListShapeOk } from "./rule-entry-list.js";
@@ -195,7 +196,7 @@ function buildExecLaneNotice(remoteExec) {
     };
 }
 const ENV_VALUE_ECHO_CHARS = 120;
-function parseConfigProvider() {
+export function parseConfigProvider() {
     const raw = process.env.CONFIG_PROVIDER;
     if (raw === undefined || raw === "")
         return undefined;
@@ -509,11 +510,32 @@ function parseNameListEnv(name, raw, opts) {
 }
 const ENV_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ENV_NAME_ALLOWLIST_WITHHELD = "<withheld: entries are not echoed — a value pasted in place of a name can pass the name check>";
-function ownCredentialPutBackProblem(name) {
+const OWN_CREDENTIAL_HANDOFF = {
+    "host-put-back": { where: "a put-back list hands the named variable back, as written, to the child the engine withheld it from", whom: "that child" },
+    "sandbox-grant": { where: "a sandbox list puts the named variable, as written, into a sandbox the model can read", whom: "the sandbox" },
+};
+function ownCredentialNameProblem(name, channel) {
     const engine = inheritEnvPolicyProblem([name]);
-    return engine === undefined
-        ? undefined
-        : `this deployment's own credential — a put-back list hands the named variable back, as written, to the child the engine withheld it from (the engine refuses it on any allow list: ${engine})`;
+    if (engine === undefined)
+        return undefined;
+    const { where, whom } = OWN_CREDENTIAL_HANDOFF[channel];
+    return `this deployment's own credential — ${where}; give ${whom} a credential of its own (another name and another value) and list that name instead (the engine refuses it on any allow list: ${engine})`;
+}
+const NAMES_IN_FORCE = {
+    LSP_ENV_ALLOW: (c) => c.lspEnvAllow,
+    E2B_SANDBOX_ENV: (c) => (c.remoteExec?.provider === "e2b" ? Object.keys(c.remoteExec.sandboxEnv ?? {}) : []),
+    K8S_SANDBOX_ENV: (c) => (c.remoteExec?.provider === "k8s" ? Object.keys(c.remoteExec.sandboxEnv ?? {}) : []),
+    DOCKER_SANDBOX_ENV: (c) => (c.remoteExec?.provider === "local-docker" ? Object.keys(c.remoteExec.env ?? {}) : []),
+};
+const SERVER_ENV_NAME_ALLOWLIST_KNOBS = Object.keys(NAMES_IN_FORCE);
+export function sandboxEnvNamesInForce(seats) {
+    return SERVER_ENV_NAME_ALLOWLIST_KNOBS.filter((knob) => ENV_NAME_ALLOWLIST_KNOBS[knob].channel === "sandbox-grant").flatMap((knob) => NAMES_IN_FORCE[knob](seats));
+}
+export function ownCredentialHitsInForce(seats) {
+    return SERVER_ENV_NAME_ALLOWLIST_KNOBS.flatMap((knob) => NAMES_IN_FORCE[knob](seats).flatMap((name) => {
+        const problem = ownCredentialNameProblem(name, ENV_NAME_ALLOWLIST_KNOBS[knob].channel);
+        return problem === undefined ? [] : [{ knob, name, problem }];
+    }));
 }
 export function parseEnvNameAllowlist(knob, singleUserTurnkey) {
     const raw = process.env[knob];
@@ -528,9 +550,7 @@ export function parseEnvNameAllowlist(knob, singleUserTurnkey) {
                 ? 'not an environment-variable name (letters, digits and "_", not starting with a digit)'
                 : ENV_NAME_ALLOWLIST_KNOB_NAMES.has(seg.toUpperCase())
                     ? `the name of a name-list knob (${[...ENV_NAME_ALLOWLIST_KNOB_NAMES].join(" / ")}: their raw text is withheld from every child process and sandbox; naming one would put that text back)`
-                    : spec.channel === "host-put-back"
-                        ? ownCredentialPutBackProblem(seg)
-                        : undefined;
+                    : ownCredentialNameProblem(seg, spec.channel);
         if (problem === undefined)
             return;
         throw new Error(`env ${knob}: entry #${i + 1} of ${segments.length} is ${problem}` +
@@ -1704,6 +1724,7 @@ function parseMemoryDomain(ctx) {
         if (memorySyncToken === undefined) {
             throw new Error("MEMORY_SYNC_URL is set but MEMORY_SYNC_TOKEN is not — refusing to start half-configured (the central sync face requires a bearer token)");
         }
+        memorySyncPeerOf(memorySyncUrl);
         if (memorySyncScopeRaw === undefined && memoryScope !== undefined && !isV2ScopeKey(memoryScope)) {
             throw new Error(`MEMORY_SYNC_URL is set but MEMORY_SYNC_SCOPE is not set and MEMORY_SCOPE (${JSON.stringify(memoryScope)}) is not a typed scope key — the sync leg replicates exactly ONE scope by name ` +
                 "(core syncMemoryScope takes the entries whose scope === the sync scope and POSTs them under that same name), so deriving `user:<MEMORY_SCOPE>` would name a scope this deployment never writes and nothing would ever be synced (S-964). " +
@@ -1902,10 +1923,10 @@ function parseOrchestrationDomain(ctx) {
                 throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: ${REMOTE_EXEC_PROVIDER_WORDS.join(" | ")}. ` +
                     `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`);
             }
-            const missing = laneRequiredEnv(word).filter((name) => !process.env[name]);
+            const missing = laneMissingEnv(word, process.env);
             if (missing.length > 0) {
-                throw new Error(`REMOTE_EXEC=${lane} but required env ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} missing/empty — ` +
-                    `refusing to start rather than silently downgrading to the host/in-process lane (#157; unset REMOTE_EXEC if you meant no sandbox lane).`);
+                throw new Error(`REMOTE_EXEC=${lane} but required env ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} unset, empty or whitespace-only — it counts as absent: ` +
+                    `refusing to start rather than silently downgrading to the host/in-process lane (#157; set ${missing.length === 1 ? "it" : "them"}, or unset REMOTE_EXEC if you meant no sandbox lane).`);
             }
         }
     }
@@ -1923,6 +1944,7 @@ function parseOrchestrationDomain(ctx) {
             assertReadDenyBuiltinsResolvable(tiers, exclude);
             return { ...(tiers !== undefined ? { readDenyBuiltinTiers: tiers } : {}), ...(exclude !== undefined ? { readDenyBuiltinExclude: exclude } : {}) };
         })(),
+        readDenyFloorRequired: boolEnv("READ_DENY_FLOOR_REQUIRED", false),
         ...((dir) => (dir !== undefined ? { agentConfigDir: dir } : {}))(declaredSemaConfigDir()),
         ...((p) => (p !== undefined ? { configLkgPath: p } : {}))(lkgPathOverrideOf(process.env.CONFIG_LKG_PATH)),
         configLkgEnabled: boolEnv("CONFIG_LKG_ENABLED", true),
@@ -1951,7 +1973,7 @@ function parseOrchestrationDomain(ctx) {
                 orphanReclaim: boolEnv("E2B_ORPHAN_RECLAIM", true),
             }
             :
-                process.env.REMOTE_EXEC === "k8s" && process.env.K8S_SANDBOX_IMAGE
+                process.env.REMOTE_EXEC === "k8s" && process.env.K8S_SANDBOX_IMAGE && process.env.K8S_NAMESPACE
                     ? {
                         provider: "k8s",
                         image: process.env.K8S_SANDBOX_IMAGE,
@@ -1959,7 +1981,7 @@ function parseOrchestrationDomain(ctx) {
                         ...(process.env.K8S_TOKEN ? { token: process.env.K8S_TOKEN } : {}),
                         ...(process.env.K8S_CA_CERT_B64 ? { caCert: Buffer.from(process.env.K8S_CA_CERT_B64, "base64").toString("utf8") } : {}),
                         ...(boolEnv("K8S_INSECURE_TLS", false) ? { insecureTls: true } : {}),
-                        ...(process.env.K8S_NAMESPACE ? { namespace: process.env.K8S_NAMESPACE } : {}),
+                        namespace: process.env.K8S_NAMESPACE,
                         ...(process.env.K8S_RUNTIME_CLASS != null ? { runtimeClass: process.env.K8S_RUNTIME_CLASS } : {}),
                         ...(process.env.K8S_MOUNT_PATH ? { mountPath: process.env.K8S_MOUNT_PATH } : {}),
                         ...((n) => (n !== undefined ? { timeoutMs: n } : {}))(optNumEnvStrict("K8S_TIMEOUT_MS")),
@@ -2450,7 +2472,7 @@ const ORCHESTRATION_GROUP_KEYS = [
     "workflowSizeGuideline", "backgroundAgentRetentionMs", "backgroundAgentStaleRunningMs",
     "backgroundAgentParkClaimStaleMs", "delegationEntryCaps", "rosterRetentionMs", "leaderRunStaleMs", "scratchpadSweepTtlMs", "sandboxPkgSource", "sandboxPkgSourceCustom",
     "sessionAutoTitle", "sessionAutoTitleSource", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspEnabled", "lspHostEnabled", "lspEnvAllow",
-    "imageBakes", "readFace", "readFaceSource", "taskWriteFaceEscalation", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude",
+    "imageBakes", "readFace", "readFaceSource", "taskWriteFaceEscalation", "readDenyPatterns", "readDenyBuiltinTiers", "readDenyBuiltinExclude", "readDenyFloorRequired",
     "agentConfigDir", "configLkgPath", "configLkgEnabled",
 ];
 const LIMITS_HTTP_GROUP_KEYS = [
@@ -2602,6 +2624,14 @@ export function loadConfig() {
     if (centerIdentity !== undefined) {
         throw new Error(centerIdentity);
     }
+    const remoteSourceRefusal = remoteConfigProviderUrlRefusal({ configProvider: integrations.configProvider, webAdmin: integrations.webAdmin });
+    if (remoteSourceRefusal !== undefined) {
+        throw new Error(remoteSourceRefusal);
+    }
+    const retentionRefusal = retentionLaneRefusal({ retentionPolicy: auth.retentionPolicy, retentionSweep: auth.retentionSweep });
+    if (retentionRefusal !== undefined) {
+        throw new Error(retentionRefusal);
+    }
     const { directApprovalDoor, durableApproval: dgDurable, approvalHmacKeys: dgHmacKeys } = approval;
     const { principalJwtPubkeys, principalJwtIss, principalJwtAud, operatorPrincipals: dgOperators, operatorSingleUser, authTokens } = auth;
     const directDoorActive = directApprovalDoor && dgDurable && dgHmacKeys.length > 0 && principalJwtPubkeys.length > 0 && !!principalJwtIss && !!principalJwtAud;

package/dist/delegated-session-owner.d.ts

@@ -38,7 +38,7 @@
  *    M23 回填了无主的父)⇒ 写下的仍是判断时的读数 —— 按律如此;那一行若因此无主,照上一节处置。
  *  · **停驻挂点**(`plugins/session-store.ts` 的 `ensureChildSessionDurableWithPromotion`;快路 + 晋升):来源 = **调用方交出的委派树根,只有这一只**,连同
  *    调用方判断那一刻读到的根行住客({@link DelegationRootWitness};见证值,判断用,不进 CAS):请求腿 = 本请求经鉴权解析的会话,住客 = 受理时那一读
- *    (`boot/resolve-spec.ts`);`/decide` 的赎回腿 = 行上的 `rootSessionId`,住客 = 赎回腿 claim 前后两读的那一位(`parked-revive-surface.ts`,每一行都交)。
+ *    (`boot/resolve-spec.ts`);`/decide` 的赎回腿 = 行上的 `rootSessionId`,住客 = 赎回腿写口放行的那一位(认领之前解析器那一读;`parked-revive-surface.ts`,每一行都交)。
  *    挂点先读一次根行:它在而住客不是见证的那一位 ⇒ 根被删、同 id 换了住客 ⇒ **拒**(不按新住客晋升 / 认领,{@link assertRootStillWitnessed});它不在 ⇒ 律给哨兵
  *    (根真没了)。不回落父:core 的挂点 `ensureChildSessionDurable(sessionId)` 只交子代 id,父 id 在这一写点拿不到;两条候选读法都读不到东西 ——
  *    ① 读 `session_meta(子代).placement_parent_session_id`:晋升的拷贝分支恰恰只在子代**没有** placed 行时才走(有 placed 行 ⇒ 快路),这一列按构造为空;
@@ -52,6 +52,7 @@
  */
 import type { SessionPlacement } from "@sema-agent/core";
 import { type HeadRead, type SessionFace } from "./session-incarnation.js";
+import type { SqlDialect } from "./plugins/sql-driver.js";
 /** 孤行哨兵属主的前缀(保留主体前缀:`security.ts` 的 `RESERVED_PRINCIPAL_PREFIXES` 登记它,任何身份来源报出带它的主体都在鉴权边界被拒)。 */
 export declare const ORPHAN_SESSION_OWNER_PREFIX = "_orphan:";
 /** 一只推不出属主的子代会话的哨兵属主(每只会话一个值:即便哪天有谁误配出这个串,也只够得着这一只)。 */
@@ -112,7 +113,7 @@ export declare function reportWrittenOwner(log: OrphanOwnerLog, site: DelegatedO
  * 不改变写进去的值(律:属主 = 判断时见证到的,本文件头注)。两方言只差占位符。
  * MySQL 协议下 mysql2 缺省带 FOUND_ROWS,但条件里有 `owner IS NULL` ⇒ 匹配行数 = 改写行数。
  */
-export declare const CLAIM_OWNERLESS_PLACED_SQL: Readonly<Record<"tidb" | "pg", string>>;
+export declare const CLAIM_OWNERLESS_PLACED_SQL: Readonly<Record<SqlDialect, string>>;
 /** 认领句的绑参(两方言同序;店与 M23 都经它,不各排一份):`incarnation` = 判断时读到的子行化身。 */
 export declare function claimOwnerlessParams(sessionId: string, incarnation: string, owner: string): readonly [string, string, string];
 /** 店的认领口(SQL 两店 + 缓存包装层同一个签名):这只会话的那一位住客(`incarnation`)仍是无主的 placed 行 ⇒ 写 `owner`,返回是否写成。 */
@@ -134,7 +135,7 @@ export interface PlacedRowWriter {
 export declare function createPlacedSessionRow(sessionId: string, placement: PlacementSources, io: PlacedRowWriter, log: OrphanOwnerLog): Promise<void>;
 /**
  * 停驻挂点的**见证**:调用方交出的委派树根 + 调用方判断那一刻读到的根行住客(化身;`null` = 那一读里根行不在)。请求腿 = 鉴权解析的会话与受理时那一读;
- * 赎回腿 = 行上的根与 claim 前后两读的那一位住客。
+ * 赎回腿 = 行上的根与写口放行的那一位住客(认领之前解析器那一读)。
  */
 export interface DelegationRootWitness {
     readonly sessionId: string;

package/dist/delegated-session-owner.js

@@ -47,7 +47,7 @@ export function reportWrittenOwner(log, site, childId, judged) {
     });
 }
 export const CLAIM_OWNERLESS_PLACED_SQL = {
-    tidb: "UPDATE session_meta SET owner = ? WHERE session_id = ? AND incarnation = ? AND owner IS NULL AND placement_kind IS NOT NULL",
+    mysql: "UPDATE session_meta SET owner = ? WHERE session_id = ? AND incarnation = ? AND owner IS NULL AND placement_kind IS NOT NULL",
     pg: "UPDATE session_meta SET owner = $1 WHERE session_id = $2 AND incarnation = $3 AND owner IS NULL AND placement_kind IS NOT NULL",
 };
 export function claimOwnerlessParams(sessionId, incarnation, owner) {

package/dist/deployment-shape.d.ts

@@ -9,7 +9,7 @@
  * ## 两根轴,每根轴一个读口(原始配置键只在这两个函数里被读)
  *  · `principal` —— 运维的 `REQUIRE_PRINCIPAL` 声明({@link readPrincipalAxis})。
  *  · `lane` —— `REMOTE_EXEC` 的归一车道词(`executionLaneOf`,认不出 ⇒ `undefined`,行必须 fail-closed)+ 那条车道的能力表行 +
- *    车道子旋钮(k8s 运行时类 / 快照店、隐式 host 尾臂记号)({@link readLaneAxis})。
+ *    这份部署上执行环境的能力块(唯一作者 `capabilitiesFor`;k8s 的快照店是它的输入)+ 车道子旋钮(k8s 运行时类、隐式 host 尾臂记号)({@link readLaneAxis})。
  *
  * ## 轴列不是注释,是型
  * 每行的判官只收到它**声明**的那几根轴的事实({@link DeploymentShapeFacts}),读不到配置本身 —— 判官碰一根没声明的轴 = 编译红;
@@ -21,8 +21,9 @@
  * (`mcpInjectionHonored` = 锁 ∧ 合规 ∧ `!multiTenant`;`taskHooksHonored`;身份门 …),读行、不读原始键。
  * 车道表(`execution-lane-caps.ts`)按车道词键控的布尔列(`laneIsolated` 等)是车道轴自己的事实表,不是「部署」的谓词;行读它们。
  *
- * 依赖纪律:叶模块 —— 值导入只有 `execution-lane-caps.ts`(它本身是叶),零运行期环。
+ * 依赖纪律:叶模块 —— 值导入只有 `execution-lane-caps.ts`(它本身是叶),零运行期环(引擎只 type-import)。
  */
+import type { ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type ExecutionLane, type ExecutionLaneCaps } from "./execution-lane-caps.js";
 /** `principal` 轴读的配置键(`ServiceConfig` 结构上满足)。 */
 export interface PrincipalAxisInput {
@@ -48,10 +49,10 @@ export interface LaneAxisFacts {
     readonly lane: ExecutionLane | undefined;
     /** 那条车道的能力表行(认不出 ⇒ `undefined`)。 */
     readonly caps: ExecutionLaneCaps | undefined;
+    /** 这份部署上执行环境的能力块(`capabilitiesFor`;认不出 ⇒ `undefined`)。 */
+    readonly block: ExecutionEnvCapabilities | undefined;
     /** k8s 的 `runtimeClass`(别的车道 `undefined`)。 */
     readonly k8sRuntimeClass: string | undefined;
-    /** k8s 配了 S3 工作区快照店(别的车道 `false`)。 */
-    readonly k8sSnapshotStore: boolean;
     /** host 车道值上带「单机形缺省」记号(唯一写者 = `config.ts` 三元链的隐式 host 尾臂;显式 `REMOTE_EXEC=host` 与文件覆写都不带)。 */
     readonly singleMachineDefault: boolean;
 }
@@ -92,7 +93,7 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      * 签发方配置是身份验签轴、不算租户证据)—— 两个问题、一根轴、一个读口;「鉴权必需」与「多租形」拆成两个声明时只改这一行的判官。
      */
     multiTenant: DeploymentShapePredicate<"principal">;
-    /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由 `device_session` 绑定验过,不要求单主)。 */
+    /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由根会话行执行格上的设备绑定验过,不要求单主)。 */
     callerCwd: DeploymentShapePredicate<"lane" | "principal">;
     /** 调用方给的宿主绝对路径(附加目录 / 项目上下文 / 本机 SendUserFile / 指令文件探针)只在「手就在本 worker 的盘上 ∧ 单主」时指向调用方自己的东西。 */
     callerOwnsWorkerDisk: DeploymentShapePredicate<"lane" | "principal">;
@@ -102,7 +103,7 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
     inProcessSingleUser: DeploymentShapePredicate<"lane" | "principal">;
     /** 任务层替部署声明宿主姿态(bypassPermissions 开写面 / host shell 继承整份环境)的射程:device 车道上跨租户宿主穿越结构性不存在(clay 裁定③)。 */
     taskHostPostureDeclarations: DeploymentShapePredicate<"lane" | "principal">;
-    /** 写门走 [ref] 代理裁决(文件平面不在 worker 本机);认不出的词 ⇒ 走代理(代理 slot 空 ⇒ 写门 fail-closed)。 */
+    /** 写门走代理裁决(执行环境块 `hostLocalPaths` 为假:路径不是本 worker 盘上的文件);认不出的词 ⇒ 走代理(代理 slot 空 ⇒ 写门 fail-closed)。 */
     sandboxPathAdjudication: DeploymentShapePredicate<"lane">;
     /** 读能力表 `sandboxSendUserFile` 位(e2b / k8s 每任务一只沙箱 ⇒ 任何租户;ssh 共享一台真机 ⇒ 只单主)。 */
     sandboxSendUserFile: DeploymentShapePredicate<"lane" | "principal">;
@@ -111,13 +112,13 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
     /** 读能力表 `tenantSeparation` 位(值来自 settings-schema 车道词表正本);唯一读者 = 跨域不变量 `multi-tenant-shared-lane`。 */
     laneSeparatesTenants: DeploymentShapePredicate<"lane" | "principal">;
     /**
-     * [ref] —— **VM 级**隔离强度(独立内核:e2b 的 Firecracker microVM;k8s 只在 Kata / gVisor 运行时类上)。与能力表 `isolation` 位
+     * [ref] —— **VM 级**隔离强度(独立内核:e2b 的 Firecracker microVM;k8s 只在 Kata / gVisor 运行时类上)。与执行环境块 `isolation` 键
      * (OS 级边界,容器即算;wire `executionLane.isolated` 的属主 `laneIsolated`)是两个问题,所以不叫「isolated」。读者:A 值路由。
      */
     vmIsolatedHands: DeploymentShapePredicate<"lane">;
     /**
-     * [ref] —— 执行环境可挂起:能力表 `suspendable` 位(「结构上能不能」)∧ k8s 的前提旋钮(配了 S3 快照店)。真作者是各适配器对 core 的
-     * `capabilities.suspendable` 声明(对账:`test/execution-lane-caps.test.ts` 拿真适配器实例逐车道核)。读者:boot `remote_exec_enabled.suspendable`。
+     * 执行环境可挂起 = 这份部署上执行环境块的 `suspendable`(唯一作者 `capabilitiesFor`,k8s 的快照店是它的输入;适配器的块是同一只函数铸的)。
+     * 读者:boot `remote_exec_enabled.suspendable`。
      */
     suspendableHands: DeploymentShapePredicate<"lane">;
     /** 读者两处:`config.ts` 车道落点一行的 `source`(覆写之前)与 `boot/execution-env.ts` 的 `remote_exec_real_system.note`(覆写之后)—— 同一个记号、两个时刻。 */

package/dist/deployment-shape.js

@@ -1,4 +1,4 @@
-import { executionLaneCaps, executionLaneOf, handsOnWorkerFilePlane } from "./execution-lane-caps.js";
+import { capabilitiesFor, executionLaneCaps, executionLaneOf, handsOnWorkerFilePlane } from "./execution-lane-caps.js";
 function readPrincipalAxis(deployment) {
     return { declared: deployment.requirePrincipal === true };
 }
@@ -8,8 +8,8 @@ function readLaneAxis(deployment) {
     return {
         lane,
         caps: lane === undefined ? undefined : executionLaneCaps(lane),
+        block: capabilitiesFor(deployment),
         k8sRuntimeClass: lane === "k8s" ? declaration?.runtimeClass : undefined,
-        k8sSnapshotStore: lane === "k8s" && Boolean(declaration?.s3Snapshot),
         singleMachineDefault: lane === "host" && declaration?.singleMachineDefault === true,
     };
 }
@@ -54,7 +54,7 @@ export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
     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),
     taskHostPostureDeclarations: createPredicate(["lane", "principal"], "车道 × 租户 / 设备归属:任务层可以替部署声明宿主姿态 —— device 车道(发起者自己的设备),或单主部署。", ({ lane, principal }) => lane.lane === "device" || !principal.declared),
-    sandboxPathAdjudication: createPredicate(["lane"], "车道:写门的路径事实要经代理到执行环境里取(文件平面不在本 worker 盘上;认不出的车道也走代理)。", ({ lane }) => lane.caps === undefined || lane.caps.hostFilePlane !== "supported"),
+    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)),
     remoteScratchpad: createPredicate(["lane"], "车道:执行环境里按会话分的远端 scratchpad 约定适用。", ({ lane }) => lane.caps !== undefined && lane.caps.remoteScratchpad === "supported"),
     laneSeparatesTenants: createPredicate(["lane", "principal"], "车道 × 租户:这条车道在这台部署上不让两个租户的命令落在同一个共享目标上(单主部署恒成立;认不出的车道不成立)。", ({ lane, principal }) => lane.caps !== undefined && capabilityHolds(lane.caps.tenantSeparation, principal)),
@@ -66,7 +66,7 @@ export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
         const runtimeClass = (lane.k8sRuntimeClass ?? "").trim().toLowerCase();
         return runtimeClass.startsWith("kata") || VM_ISOLATION_RUNTIME_CLASSES.has(runtimeClass);
     }),
-    suspendableHands: createPredicate(["lane"], "车道:执行环境可挂起(e2b;k8s 以配了 S3 工作区快照店为前提)。", ({ lane }) => lane.caps !== undefined && lane.caps.suspendable === "supported" && (lane.lane !== "k8s" || lane.k8sSnapshotStore)),
+    suspendableHands: createPredicate(["lane"], "车道:执行环境可挂起(e2b;k8s 以配了 S3 工作区快照店为前提)。", ({ lane }) => lane.block?.suspendable === true),
     singleMachineDefaultLane: createPredicate(["lane"], "车道:host 车道是单机形缺省落点(REMOTE_EXEC 未设 ∧ CONFIG_PROVIDER=local,没人点名)。", ({ lane }) => lane.singleMachineDefault),
 });
 //# sourceMappingURL=deployment-shape.js.map

package/dist/device-enrollment.d.ts

@@ -18,12 +18,21 @@
  * 上是**同一个** `device.enrollment_invalid`;设备读面的「不存在」与「不是你的」是同一个
  * `not_found.device`。细分只进审计。
  *
+ * ── 绑定从哪读(一只读)─────────────────────────────────────────────────────────────────────────────
+ * 根会话 ↔ 设备的绑定是根会话行上这一位住客的执行格 writer(device, D)(`execution-placement.ts` 头注)。准入链**不另读**:
+ * 读只有会话店的执行席 `seat.read(root)` 一只({@link DeviceEnrollment.readPlacement},装配点把会话店的执行席交进来 ——
+ * device 车道只在 SQL 后端 ⇒ 席恒在,缺 ⇒ 装配期响亮抛);{@link DeviceEnrollment.admitSession} 判的是调用方交进来的**那一读**,
+ * 于是提交意图「判已绑 / 未绑」与它记下的住客出自同一次行读。「这一格放在哪台设备上」只有一种读法 `boundDeviceOf`。
+ *
  * ── 吊销在途语义(§8-R4)──────────────────────────────────────────────────────────────────────────
  * `revoked` 是终态:①绑定的 session 后续提交 = `device.revoked`(admitSession 步 2,**先于** presence
  * 判定);②吊销同事务把连接租约作废并把 `conn_generation` 推进一格 ⇒ 在途连接的每一次带世代谓词的写
  * 都会影响 0 行,设备侧因此立刻失权(§4.6 步 2);③重新 enrollment = 新 deviceId,不复活旧行。
  */
-import { type DeviceErrorCode, type DeviceOwner, type DeviceRejectCode, type DeviceEnrollTokenRow, type DeviceRow, type DeviceSessionRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+import { type DeviceErrorCode, type DeviceOwner, type DeviceRejectCode, type DeviceEnrollTokenRow, type DeviceRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+import { type ExecutionDeviceCell, type ExecutionPlacementReading, type ExecutionPlacementSeat } from "./execution-placement.js";
+import type { ExecutionLane } from "./execution-lane-caps.js";
+import type { SessionFace } from "./session-incarnation.js";
 /** typed 拒绝 —— 端点层只负责把它翻成 HTTP(status 已在体内,不许调用方另算)。 */
 export interface DeviceRejection {
     /** [ref]:含两个借用位(`limit.rate_exceeded` 429 / `draining` 503);enrollment 本文件只铸前者,
@@ -68,10 +77,34 @@ export interface EnrollDeviceValue {
 }
 export interface AdmitSessionInput {
     rootSessionId: string;
+    /** 调用方读的**那一读**(会话店执行席 `seat.read(rootSessionId)` 的答案,经 {@link DeviceEnrollment.readPlacement})—— 准入链只判它,不另读。 */
+    placement: ExecutionPlacementReading | undefined;
     requester: DeviceOwner;
     /** 提交体携带的 deviceId(§4.3.2:仅根任务携;缺席 = 沿用绑定)。 */
     requestedDeviceId?: string;
 }
+/**
+ * 首绑({@link DeviceEnrollment.bindPlacement})的结果:成立(`device` = 落下的格)、设备闭集的 typed 拒(异设备 `device.claim_conflict` /
+ * 设备 404 / 已吊销),或会话行那一侧的三种结局 —— 住客不是判过的那一位 / 行不在(`gone`)、写者在别处(`mirror`)、格在别的车道上(`tree_bound`)。
+ * 后三者不在设备闭集里(它们说的是会话,不是设备),由提交点(`http/execution-context.ts` 的 `commitExecutionContext`)各答各的码。
+ */
+export type BindPlacementOutcome = {
+    readonly ok: true;
+    readonly device: ExecutionDeviceCell;
+} | {
+    readonly ok: false;
+    readonly reject: DeviceRejection;
+} | {
+    readonly ok: false;
+    readonly placement: "gone";
+} | {
+    readonly ok: false;
+    readonly placement: "mirror";
+} | {
+    readonly ok: false;
+    readonly placement: "tree_bound";
+    readonly boundLane: ExecutionLane;
+};
 export interface AdmitSessionValue {
     deviceId: string;
     device: DeviceRow;
@@ -110,11 +143,15 @@ export interface DeviceEnrollment {
     /** §7-T5 五件的第 ①②③ 件的**写入侧**:绑定复合身份 + TTL + 一次性摘要落库(明文一现)。 */
     issueEnrollToken(input: IssueEnrollTokenRequest): Promise<DeviceOutcome<IssuedEnrollToken>>;
     enroll(input: EnrollDeviceInput): Promise<DeviceOutcome<EnrollDeviceValue>>;
+    /** 绑定的唯一读:会话店执行席的 `read(root)`(一次行读:住客 + 格;行不在 ⇒ `undefined`;读故障抛,不吞成「未绑」)。 */
+    readPlacement(rootSessionId: string): Promise<ExecutionPlacementReading | undefined>;
+    /** 首绑(认领之后的初始放置写):按意图那一读的住客定址,设备店一只事务。 */
     bindPlacement(input: {
         rootSessionId: string;
+        occupant: SessionFace;
         deviceId: string;
         requester: DeviceOwner;
-    }): Promise<DeviceOutcome<DeviceSessionRow>>;
+    }): Promise<BindPlacementOutcome>;
     admitSession(input: AdmitSessionInput): Promise<DeviceOutcome<AdmitSessionValue>>;
     revoke(input: {
         deviceId: string;
@@ -125,6 +162,8 @@ export interface DeviceEnrollment {
 }
 export interface DeviceEnrollmentDeps {
     store: DeviceStore;
+    /** 会话店的执行席(绑定的唯一载体与唯一读;装配点交会话店的 `executionPlacement`)。 */
+    seat: ExecutionPlacementSeat;
     /** 缺席 = 不限速(端点车必须传;见文件头注 ⑤)。 */
     rateLimiter?: DeviceEnrollRateLimiter;
     /** 测试可注入确定性铸造;默认 `mintDeviceId()`。 */

package/dist/device-enrollment.js

@@ -1,4 +1,5 @@
 import { DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, DEVICE_RATE_LIMIT_CODE, assertDeviceIdShape, assertDeviceOwnerShape, assertDevicePubkeyShape, assertEnrollTokenHashShape, assertRootSessionIdShape, hashEnrollToken, mintDeviceId, mintEnrollToken, } from "./device-store.js";
+import { boundDeviceOf } from "./execution-placement.js";
 export const DEFAULT_ENROLL_TOKEN_TTL_SEC = 900;
 export function buildDeviceRejection(errorCode, message) {
     return { code: errorCode, status: DEVICE_ERROR_STATUS[errorCode], message };
@@ -13,7 +14,7 @@ function rejectNotFound() {
     return reject(DEVICE_ERROR_CODES.NOT_FOUND, "device not found");
 }
 export function createDeviceEnrollment(deps) {
-    const { store } = deps;
+    const { store, seat } = deps;
     const mintId = deps.mintId ?? mintDeviceId;
     async function rateGate(key) {
         if (!deps.rateLimiter)
@@ -87,21 +88,35 @@ export function createDeviceEnrollment(deps) {
                 return rejectEnrollment();
         }
     }
+    async function readPlacement(rootSessionId) {
+        assertRootSessionIdShape(rootSessionId);
+        return seat.read(rootSessionId);
+    }
     async function bindPlacement(input) {
         assertRootSessionIdShape(input.rootSessionId);
         assertDeviceIdShape(input.deviceId);
         assertDeviceOwnerShape(input.requester);
-        const result = await store.bindSession({ rootSessionId: input.rootSessionId, deviceId: input.deviceId, owner: input.requester });
+        const result = await store.placeDeviceExecution({ root: input.rootSessionId, occupant: input.occupant, deviceId: input.deviceId, owner: input.requester });
         switch (result.outcome) {
             case "bound":
-            case "idempotent":
-                return { ok: true, value: result.row };
-            case "conflict":
+            case "same":
+                return { ok: true, device: result.device };
+            case "device_conflict":
                 return reject(DEVICE_ERROR_CODES.CLAIM_CONFLICT, "this session is already bound to a different device");
             case "device_not_found":
                 return rejectNotFound();
             case "device_revoked":
                 return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+            case "gone":
+                return { ok: false, placement: "gone" };
+            case "mirror":
+                return { ok: false, placement: "mirror" };
+            case "tree_bound":
+                return { ok: false, placement: "tree_bound", boundLane: result.boundLane };
+            default: {
+                const unhandled = result;
+                throw new Error(`bindPlacement: unknown store outcome ${JSON.stringify(unhandled)}`);
+            }
         }
     }
     async function admitSession(input) {
@@ -109,22 +124,22 @@ export function createDeviceEnrollment(deps) {
         assertDeviceOwnerShape(input.requester);
         if (input.requestedDeviceId !== undefined)
             assertDeviceIdShape(input.requestedDeviceId);
-        const binding = await store.getSessionBinding(input.rootSessionId);
-        if (!binding)
+        const bound = input.placement === undefined ? undefined : boundDeviceOf(input.placement.cell);
+        if (!bound)
             return reject(DEVICE_ERROR_CODES.NOT_BOUND, "this session has no device binding");
-        if (binding.owner.tenant !== input.requester.tenant || binding.owner.subject !== input.requester.subject)
+        if (bound.owner.tenant !== input.requester.tenant || bound.owner.subject !== input.requester.subject)
             return rejectNotFound();
-        if (input.requestedDeviceId !== undefined && input.requestedDeviceId !== binding.deviceId) {
+        if (input.requestedDeviceId !== undefined && input.requestedDeviceId !== bound.id) {
             return reject(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, "the requested device is not the one bound to this session");
         }
-        const view = await store.readDeviceForAdmission(binding.deviceId, input.requester);
+        const view = await store.readDeviceForAdmission(bound.id, input.requester);
         if (!view)
             return rejectNotFound();
         if (view.row.status === "revoked")
             return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
         if (!view.online)
             return reject(DEVICE_ERROR_CODES.OFFLINE, "device is not connected");
-        return { ok: true, value: { deviceId: binding.deviceId, device: view.row, connGeneration: view.row.connGeneration } };
+        return { ok: true, value: { deviceId: bound.id, device: view.row, connGeneration: view.row.connGeneration } };
     }
     async function revoke(input) {
         assertDeviceIdShape(input.deviceId);
@@ -138,7 +153,7 @@ export function createDeviceEnrollment(deps) {
                 return rejectNotFound();
         }
     }
-    return { issueEnrollToken, enroll, bindPlacement, admitSession, revoke };
+    return { issueEnrollToken, enroll, readPlacement, bindPlacement, admitSession, revoke };
 }
 export function createFixedWindowRateLimiter(opts) {
     const now = opts.now ?? (() => Date.now());