@sema-agent/server 7.137.0 → 7.139.0

package/dist/config.js

@@ -9,13 +9,14 @@ 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";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
 import { CONFIG_PROVIDER_WORDS, RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS, MAX_TIMER_DELAY_MS, AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, DRAIN_GRACE_FLOOR_MS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, FIRST_BYTE_TIMEOUT_BOUNDS, FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS, fleetScopeOf, DEVICE_DELIVERY_TIMEOUT_BOUNDS, DEVICE_EXEC_TIMEOUT_BOUNDS, inWholeNumberBounds, wholeNumberBoundsRule } from "./config-types.js";
 import { DEVICE_HELLO_ACK_BOUNDS } from "./device-ws-protocol.js";
-import { FLEET_GENERATION_ENV, FLEET_SCOPE_ENV, SERVING_LEASE_TTL_FLOOR_MS, isCanonicalGeneration } from "@sema-agent/settings-schema/fleet";
+import { FLEET_ADVERTISE_ADDRESS_ENV, FLEET_GENERATION_ENV, FLEET_SCOPE_ENV, SERVING_LEASE_TTL_FLOOR_MS, isCanonicalGeneration } from "@sema-agent/settings-schema/fleet";
 import { ScopeId } from "@sema-agent/settings-schema/api/scopes";
 import { centerLaneConfigured, pathBaseUrlRefusal } from "./web-admin-client/center-request.js";
 import { resolveLocalDataRoot } from "./local-data-root.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";
@@ -47,7 +48,7 @@ import { modelRouteUrlRefusal } from "./model-route-url.js";
 import { httpUrlFlaws } from "@sema-agent/settings-schema";
 import { buildHttpUrlRefusal, buildRefusalShownUrl } from "./url-refusal.js";
 import { customPkgSourceFromEnv } from "./sandbox-pkg-source.js";
-import { anthropicCredentialRefusal, csvOf, envLaneTable, mintedCheapId, readModelRouteEnv } from "./model-route-gap.js";
+import { anthropicCredentialRefusal, csvOf, declaredCredential, envLaneTable, mintedCheapId, readModelRouteEnv } from "./model-route-gap.js";
 import { displayListEntry } from "./list-entry-display.js";
 import { echoCallerText } from "./caller-text-echo.js";
 import { buildDisplaySafeUrl, redactSecrets } from "./trace/redact.js";
@@ -55,6 +56,7 @@ import { parseConfigLocalOwnerUid } from "./config-dir-trust.js";
 import { allowlistedEnv } from "./server-secret-env.js";
 import { ENV_NAME_ALLOWLIST_KNOBS, ENV_NAME_ALLOWLIST_KNOB_NAMES, describeAllowlistPostures } from "./env-name-allowlist-knobs.js";
 import { APPROVAL_ASK_RETENTION_DEFAULT_MS, APPROVAL_ASK_RETENTION_FLOOR_MS } from "./approval-ask-retention.js";
+import { parseModsDeclaration } from "./mods-declaration.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
     return csvOf(process.env[name]);
@@ -194,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;
@@ -508,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];
@@ -527,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}` +
@@ -1103,7 +1124,7 @@ function parseModelDomain() {
     }
     const models = envLaneTable(modelId, model, cheapModel);
     const gatewayApiKey = route.gatewayApiKey;
-    if (gatewayBaseUrl === undefined && gatewayApiKey !== undefined && gatewayApiKey !== "") {
+    if (gatewayBaseUrl === undefined && declaredCredential(gatewayApiKey) !== undefined) {
         CONFIG_NOTICES.push({
             level: "warn",
             event: "model_gateway_key_unpaired",
@@ -1703,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). " +
@@ -1901,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).`);
             }
         }
     }
@@ -1950,7 +1972,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,
@@ -1958,7 +1980,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")),
@@ -2228,6 +2250,7 @@ function parseIntegrationsDomain(ctx) {
         gitApiKind: parseGitApiKind(process.env.GIT_API_KIND, process.env.GIT_API_BASEURL),
         defaultScenario: env("DEFAULT_SCENARIO", "code"),
         skillsDir: env("SKILLS_DIR", defaultSkillsDir()),
+        modsDeclaration: parseModsDeclaration(process.env.MODS_ROOT, process.env.MODS_PACKAGES),
         centerCredentialRenewLeadMs: parseCenterCredentialRenewLeadMs(process.env.CENTER_CREDENTIAL_RENEW_LEAD_MS),
         webAdmin,
         fleetLeaseFailClosed: parseFleetLeaseFailClosed(process.env.FLEET_LEASE_FAIL_CLOSED, DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds({ requirePrincipal })),
@@ -2273,9 +2296,10 @@ function parseFleetScope(raw) {
     return fleetScopeOf(raw);
 }
 function parseFleetAdvertiseAddress(raw) {
+    const name = "FLEET_ADVERTISE_ADDRESS";
     if (raw === undefined || raw === "")
         return {};
-    const refusal = pathBaseUrlRefusal("env FLEET_ADVERTISE_ADDRESS", raw);
+    const refusal = pathBaseUrlRefusal(`env ${name}`, raw);
     if (refusal !== undefined) {
         throw fleetEnvRefusal("advertise_address_invalid", `${refusal} — it must be an http(s) base URL such as "http://10.0.0.5:8090": the fleet center rejects any other shape on every announce. ` +
             `Unset it if this engine does not announce itself.`);
@@ -2460,7 +2484,7 @@ const LIMITS_HTTP_GROUP_KEYS = [
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
 const INTEGRATIONS_GROUP_KEYS = [
     "pluginsAllowHosts", "mcpServers", "a2aPeers", "a2aServe", "configBootFetchBudgetMs", "gitApiBaseUrl", "gitApiToken", "gitApiKind", "defaultScenario",
-    "skillsDir", "centerCredentialRenewLeadMs", "webAdmin", "fleetLeaseFailClosed", "fleetGeneration", "fleetScope", "fleetAdvertiseAddress", "fleetLeaseOutageMaxMs", "configProvider", "configLocalDir", "configLocalOwnerUid",
+    "skillsDir", "modsDeclaration", "centerCredentialRenewLeadMs", "webAdmin", "fleetLeaseFailClosed", "fleetGeneration", "fleetScope", "fleetAdvertiseAddress", "fleetLeaseOutageMaxMs", "configProvider", "configLocalDir", "configLocalOwnerUid",
 ];
 export const CONFIG_GROUP_KEYS = {
     store: STORE_GROUP_KEYS,
@@ -2599,6 +2623,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 行 ⇒ 快路),这一列按构造为空;
@@ -134,7 +134,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/deployment-shape.d.ts

@@ -92,24 +92,24 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      * 签发方配置是身份验签轴、不算租户证据)—— 两个问题、一根轴、一个读口;「鉴权必需」与「多租形」拆成两个声明时只改这一行的判官。
      */
     multiTenant: DeploymentShapePredicate<"principal">;
-    /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由 `device_session` 绑定验过,不要求单主)。 */
-    callerCwd: DeploymentShapePredicate<"principal" | "lane">;
+    /** 读能力表 `callerCwd` 位(host = 单主才开;device = 路径落在发起者自己的设备上,归属由根会话行执行格上的设备绑定验过,不要求单主)。 */
+    callerCwd: DeploymentShapePredicate<"lane" | "principal">;
     /** 调用方给的宿主绝对路径(附加目录 / 项目上下文 / 本机 SendUserFile / 指令文件探针)只在「手就在本 worker 的盘上 ∧ 单主」时指向调用方自己的东西。 */
-    callerOwnsWorkerDisk: DeploymentShapePredicate<"principal" | "lane">;
+    callerOwnsWorkerDisk: DeploymentShapePredicate<"lane" | "principal">;
     /** wire `executionLane.toolsOnThisHost` 与出厂 / 中心技能的 `baseDir`:只问文件系统同一性,与租户无关(出厂内容每个租户拿到同一份)。 */
     toolsOnThisHost: DeploymentShapePredicate<"lane">;
     /** `REMOTE_EXEC` 未设的进程内形(没有手)且单主:进程级消费者(hooks 命令、项目上下文本机读、卡批规则 root)看到的就是引擎自己的进程 cwd / env。 */
-    inProcessSingleUser: DeploymentShapePredicate<"principal" | "lane">;
+    inProcessSingleUser: DeploymentShapePredicate<"lane" | "principal">;
     /** 任务层替部署声明宿主姿态(bypassPermissions 开写面 / host shell 继承整份环境)的射程:device 车道上跨租户宿主穿越结构性不存在(clay 裁定③)。 */
-    taskHostPostureDeclarations: DeploymentShapePredicate<"principal" | "lane">;
+    taskHostPostureDeclarations: DeploymentShapePredicate<"lane" | "principal">;
     /** 写门走 [ref] 代理裁决(文件平面不在 worker 本机);认不出的词 ⇒ 走代理(代理 slot 空 ⇒ 写门 fail-closed)。 */
     sandboxPathAdjudication: DeploymentShapePredicate<"lane">;
     /** 读能力表 `sandboxSendUserFile` 位(e2b / k8s 每任务一只沙箱 ⇒ 任何租户;ssh 共享一台真机 ⇒ 只单主)。 */
-    sandboxSendUserFile: DeploymentShapePredicate<"principal" | "lane">;
+    sandboxSendUserFile: DeploymentShapePredicate<"lane" | "principal">;
     /** 读能力表 `remoteScratchpad` 位(`/tmp/scratchpad/<sessionId>` 远端约定)。 */
     remoteScratchpad: DeploymentShapePredicate<"lane">;
     /** 读能力表 `tenantSeparation` 位(值来自 settings-schema 车道词表正本);唯一读者 = 跨域不变量 `multi-tenant-shared-lane`。 */
-    laneSeparatesTenants: DeploymentShapePredicate<"principal" | "lane">;
+    laneSeparatesTenants: DeploymentShapePredicate<"lane" | "principal">;
     /**
      * [ref] —— **VM 级**隔离强度(独立内核:e2b 的 Firecracker microVM;k8s 只在 Kata / gVisor 运行时类上)。与能力表 `isolation` 位
      * (OS 级边界,容器即算;wire `executionLane.isolated` 的属主 `laneIsolated`)是两个问题,所以不叫「isolated」。读者:A 值路由。

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());