@sema-agent/server 7.150.0 → 7.152.0

package/dist/config.js

@@ -32,11 +32,11 @@ import { MODEL_THINKING_LEVELS, THINKING_LEVELS, THINKING_FORMATS, buildModelCom
 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, isRetiredLeftOut, retiredLeftOutEntries, ruleEntryToolName, unmatchableRuleNameOf } from "./namespaced-rule-name.js";
-import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal, operatorSingleUserRefusal, remoteConfigProviderUrlRefusal, retentionLaneRefusal, workflowParkDecisionDomainRefusal } from "./config-invariants.js";
+import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal, operatorSingleUserRefusal, operatorRosterWellFormedRefusal, 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";
-import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "./object-store-buckets.js";
+import { S3_PUBLIC_BUCKET_DEFAULT, SENDFILE_PRIVATE_PREFIX, SESSION_SNAPSHOT_BUCKET_DEFAULT, SIGV4_PRESIGN_MAX_SEC, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT, sessionSnapshotPrefixProblem } from "./object-store-buckets.js";
 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";
@@ -46,10 +46,11 @@ import { sandboxForwardedEnvOf } from "./execution-config-root.js";
 import { SANDBOX_READ_FLOOR_DEFAULT, SANDBOX_READ_FLOOR_WORDS, laneMissingEnv, readDeclaredLaneTable } 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 { CC_RULE_FORM } from "./entry-problems.js";
 import { deploymentRuleRefusal } from "./rule-issue-reading.js";
 import { MAX_NAMED_INERT_ENTRIES, allowLayerEntryCountIssue, describeInertRuleEntries, inertRuleEntriesOf, inertRuleEntryGuidance, ruleEntryListShapeOk } from "./rule-entry-list.js";
 import { readReadDenyEntry } from "./read-deny-entry.js";
-import { createCenterCredentialSource, readCenterCredentialDeclaration } from "./center-credential.js";
+import { createCenterCredentialSource, credentialOriginOf, readWebAdminCredentialDeclaration } from "./center-credential.js";
 import { parseCenterCredentialRenewLeadMs } from "./center-credential-renewer.js";
 import { catalogBrainLane, modelProviderRefusal } from "./model-provider.js";
 import { modelRouteUrlRefusal } from "./model-route-url.js";
@@ -408,15 +409,39 @@ function parseDeviceRelayUrlEnv(raw) {
 export function entryDeclarableRemoteExec(lane) {
     switch (lane) {
         case "host":
-            return {
-                provider: "host",
-                ...(process.env.HOST_WORKSPACE_BASE ? { workspaceBase: process.env.HOST_WORKSPACE_BASE } : {}),
-                ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("HOST_COMMAND_TIMEOUT_MS")),
-            };
+            return { provider: "host", ...parseHostLaneEnv() };
         case "none":
             return { provider: "none" };
     }
 }
+export function parseHostLaneEnv() {
+    return {
+        ...(process.env.HOST_WORKSPACE_BASE ? { workspaceBase: process.env.HOST_WORKSPACE_BASE } : {}),
+        ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("HOST_COMMAND_TIMEOUT_MS")),
+    };
+}
+export function parseLocalDockerLaneEnv(singleUserTurnkey) {
+    return {
+        ...(process.env.DOCKER_IMAGE ? { image: process.env.DOCKER_IMAGE } : {}),
+        ...(process.env.DOCKER_MOUNT_PATH ? { mountPath: process.env.DOCKER_MOUNT_PATH } : {}),
+        ...(process.env.DOCKER_PATH ? { dockerPath: process.env.DOCKER_PATH } : {}),
+        ...(process.env.DOCKER_HOST ? { dockerHost: process.env.DOCKER_HOST } : {}),
+        ...(process.env.DOCKER_MEMORY ? { memory: process.env.DOCKER_MEMORY } : {}),
+        ...((n) => (n !== undefined ? { cpus: n } : {}))(optNumEnvStrict("DOCKER_CPUS")),
+        ...((n) => (n !== undefined ? { pidsLimit: n } : {}))(optFinitePositiveEnv("DOCKER_PIDS_LIMIT")),
+        ...(boolEnv("DOCKER_DROP_CAPS", false) ? { dropAllCaps: true } : {}),
+        ...(process.env.DOCKER_NETWORK
+            ? { network: enumEnv("DOCKER_NETWORK", "bridge", ["none", "bridge", "host"]) }
+            : {}),
+        ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("DOCKER_COMMAND_TIMEOUT_MS")),
+        ...((names) => (names !== undefined ? { env: allowlistedEnv(names, process.env) } : {}))(parseEnvNameAllowlist("DOCKER_SANDBOX_ENV", singleUserTurnkey)),
+        ...((capacity) => (capacity !== undefined ? { capacity } : {}))(parseLocalDockerCapacityEnv()),
+    };
+}
+export const FILE_LANE_CELL_ENV = {
+    host: { workspaceBase: "HOST_WORKSPACE_BASE", commandTimeoutMs: "HOST_COMMAND_TIMEOUT_MS" },
+    "local-docker": { image: "DOCKER_IMAGE", mountPath: "DOCKER_MOUNT_PATH", memory: "DOCKER_MEMORY", cpus: "DOCKER_CPUS", network: "DOCKER_NETWORK" },
+};
 const envNamesNoLane = (raw) => raw === undefined || raw === "";
 function declaredExecutionLane(raw) {
     if (envNamesNoLane(raw))
@@ -470,6 +495,41 @@ function parseDeviceTrustedProxyCidrsEnv(raw) {
             `(e.g. 10.0.0.0/8,fd00::/8); unset it to read no proxy header at all (the cap is then keyed on the socket peer).`);
     });
 }
+function sessionSnapshotPrefixKnob(prefix) {
+    const problem = sessionSnapshotPrefixProblem(prefix);
+    if (problem !== undefined)
+        throw new Error(`SESSION_SNAPSHOT_PREFIX=${JSON.stringify(prefix)} is refused: ${problem} — give each engine on the bucket a prefix that does not end in a domain segment (e.g. "engine-a/")`);
+    return prefix;
+}
+function presignLifetimeKnob(knob, sec, alternative) {
+    if (sec > SIGV4_PRESIGN_MAX_SEC) {
+        throw new Error(`${knob}=${sec} is longer than a presigned URL can live (at most ${SIGV4_PRESIGN_MAX_SEC} s (7 days)) — set ${knob} to at most ${SIGV4_PRESIGN_MAX_SEC}${alternative ? `, ${alternative}` : ""}`);
+    }
+    return sec;
+}
+function presignLifetimeSpelled(knob, raw, legal, alternative) {
+    const spelled = raw?.trim() ?? "";
+    if (spelled === "")
+        return undefined;
+    if (!/^(0|[1-9]\d*)$/.test(spelled)) {
+        const shown = raw.length > 40 ? `${raw.slice(0, 40)}…` : raw;
+        throw new Error(`${knob}=${JSON.stringify(shown)} is not ${legal}`);
+    }
+    return presignLifetimeKnob(knob, Number(spelled), alternative);
+}
+function sendUserFileUrlTtlKnob(raw) {
+    return (presignLifetimeSpelled("SEND_USER_FILE_URL_TTL", raw, `a link lifetime — set 0 (or leave it unset) for a permanent public link, or a whole number of seconds from 1 to ${SIGV4_PRESIGN_MAX_SEC} (7 days) for a private presigned link that expires`, "or 0 for a permanent link") ?? 0);
+}
+function sessionSnapshotTtlKnob(raw) {
+    const sec = presignLifetimeSpelled("SESSION_SNAPSHOT_TTL_SEC", raw, `a presigned-URL lifetime — leave it unset for the default, or set a whole number of seconds from 1 to ${SIGV4_PRESIGN_MAX_SEC} (7 days) in decimal digits`);
+    if (sec !== 0)
+        return sec;
+    CONFIG_WARNINGS.push({ env: "SESSION_SNAPSHOT_TTL_SEC", raw: raw });
+    return undefined;
+}
+function workspaceSnapshotTtlKnob(raw) {
+    return presignLifetimeSpelled("WORKSPACE_SNAPSHOT_TTL_SEC", raw, `a presigned-URL lifetime — leave it unset (or 0) for the default, or set a whole number of seconds from 1 to ${SIGV4_PRESIGN_MAX_SEC} (7 days) in decimal digits`);
+}
 function parseFileHistoryRetention() {
     const raw = process.env.FILE_HISTORY_RETENTION_KEEP;
     if (raw === undefined || raw === "")
@@ -1012,8 +1072,8 @@ function parseStoreDomain(ctx) {
                 accessKey: process.env.MINIO_ACCESS_KEY,
                 secretKey: process.env.MINIO_SECRET_KEY,
                 ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
-                ...(process.env.SESSION_SNAPSHOT_PREFIX ? { keyPrefix: process.env.SESSION_SNAPSHOT_PREFIX } : {}),
-                ...((ttl) => (ttl !== undefined ? { presignTtlSec: ttl } : {}))(optFinitePositiveEnv("SESSION_SNAPSHOT_TTL_SEC")),
+                ...(process.env.SESSION_SNAPSHOT_PREFIX ? { keyPrefix: sessionSnapshotPrefixKnob(process.env.SESSION_SNAPSHOT_PREFIX) } : {}),
+                ...((ttl) => (ttl !== undefined ? { presignTtlSec: ttl } : {}))(sessionSnapshotTtlKnob(process.env.SESSION_SNAPSHOT_TTL_SEC)),
             }
             : undefined,
         snapshotBlobSqlMaxBytes: optFinitePositiveEnv("SNAPSHOT_BLOB_SQL_MAX_BYTES"),
@@ -1026,14 +1086,14 @@ function parseStoreDomain(ctx) {
                 ...(process.env.S3_PUBLIC_ENDPOINT || process.env.S3_ENDPOINT
                     ? { publicEndpoint: (process.env.S3_PUBLIC_ENDPOINT || process.env.S3_ENDPOINT) }
                     : {}),
-                publicBucket: process.env.S3_PUBLIC_BUCKET ?? "sema-public",
+                publicBucket: process.env.S3_PUBLIC_BUCKET ?? S3_PUBLIC_BUCKET_DEFAULT,
                 privateBucket: process.env.SESSION_SNAPSHOT_BUCKET ?? SESSION_SNAPSHOT_BUCKET_DEFAULT,
-                privateKeyPrefix: "sendfile/",
+                privateKeyPrefix: SENDFILE_PRIVATE_PREFIX,
                 ...(process.env.SEND_USER_FILE_SANDBOX_PUT_ENDPOINT ? { sandboxPutEndpoint: process.env.SEND_USER_FILE_SANDBOX_PUT_ENDPOINT } : {}),
                 accessKey: process.env.MINIO_ACCESS_KEY,
                 secretKey: process.env.MINIO_SECRET_KEY,
                 ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
-                defaultTtlSec: ((v) => (v !== undefined && Number.isInteger(v) && v >= 0 ? v : 0))(process.env.SEND_USER_FILE_URL_TTL !== undefined ? Number(process.env.SEND_USER_FILE_URL_TTL) : undefined),
+                defaultTtlSec: sendUserFileUrlTtlKnob(process.env.SEND_USER_FILE_URL_TTL),
             }
             : undefined,
     };
@@ -1339,7 +1399,7 @@ function findUnmatchableToolNames(names, opts) {
         if (opts.consumer === "tool-name-table") {
             const ccGuidance = ccRuleFormGuidance(name);
             if (ccGuidance !== undefined) {
-                out.push({ name, guidance: ccGuidance, reason: "cc_rule_form" });
+                out.push({ name, guidance: ccGuidance, reason: CC_RULE_FORM });
                 continue;
             }
         }
@@ -1395,7 +1455,6 @@ export function approvalGrantRefusal(names) {
 }
 function streamApprovalConfig(gates) {
     const cfg = {
-        enabled: boolEnv("STREAM_APPROVAL_ENABLED", true),
         windowMs: numEnv("STREAM_ASK_WINDOW_MS", gates.windowMsSource === "posture" ? "86400000" : "300000"),
         replayMax: numEnv("STREAM_APPROVAL_REPLAY_MAX", "50"),
         admitMaxPerTask: numEnv("STREAM_APPROVAL_ADMIT_MAX_PER_TASK", "32"),
@@ -1419,7 +1478,7 @@ function streamApprovalConfig(gates) {
     if (cfg.windowMs + cfg.adhocGraceMs >= cfg.orphanTtlMs) {
         throw new Error(`env STREAM_ASK_WINDOW_MS=${cfg.windowMs} + STREAM_APPROVAL_ADHOC_GRACE_MS=${cfg.adhocGraceMs} must be STRICTLY LESS than STREAM_APPROVAL_ORPHAN_TTL_MS=${cfg.orphanTtlMs} — the adhoc arm fires at (createdAt + window + grace) while the orphan backstop fires at (createdAt + ttl); if the backstop wins, every adhoc-leg row is attributed "orphan_ttl_exceeded" instead of "adhoc_leg_no_durable_domain" (attribution honesty, design/172 §6.1)`);
     }
-    const suspendedRowsPossible = cfg.enabled && gates.toolApprovalEnabled && gates.unattendedPolicy !== "deny";
+    const suspendedRowsPossible = gates.toolApprovalEnabled && gates.unattendedPolicy !== "deny";
     if (suspendedRowsPossible && cfg.unreachedTtlMs + cfg.adhocGraceMs >= cfg.orphanTtlMs) {
         throw new Error(`env UNREACHED_ASK_TTL_MS=${cfg.unreachedTtlMs} + STREAM_APPROVAL_ADHOC_GRACE_MS=${cfg.adhocGraceMs} must be STRICTLY LESS than STREAM_APPROVAL_ORPHAN_TTL_MS=${cfg.orphanTtlMs} — an ask minted with NO live stream (case A: a workflow child ask) waits UNREACHED_ASK_TTL_MS, so its row expires at (createdAt + that window); the orphan backstop fires at (createdAt + ttl). If the backstop wins, every suspended row is attributed "orphan_ttl_exceeded" instead of its real cause (attribution honesty, same rule as the STREAM_ASK_WINDOW_MS line above)`);
     }
@@ -1997,7 +2056,6 @@ function parseAuthDomain(ctx) {
     const authTokens = parseServiceAuthTokens(process.env.SERVICE_AUTH_TOKENS);
     return {
         bindHost: process.env.BIND_HOST || undefined,
-        bindHostSource: process.env.BIND_HOST ? "BIND_HOST" : undefined,
         authToken: process.env.SERVICE_AUTH_TOKEN,
         authTokens,
         allowUnauthedWrites: boolEnv("ALLOW_UNAUTHED_WRITES", false),
@@ -2007,6 +2065,7 @@ function parseAuthDomain(ctx) {
         autonomy: parseAutonomy(process.env.AUTONOMY),
         ...parseGovernanceDeclarations(),
         operatorPrincipals: csv("OPERATOR_PRINCIPALS"),
+        operatorDrainPrincipals: csv("OPERATOR_DRAIN_PRINCIPALS"),
         operatorSingleUser: boolEnv("OPERATOR_SINGLE_USER", false),
         serviceTokenActsForDeployment: boolEnv("SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT", true),
         configCatalogEnabled: boolEnv("CONFIG_CATALOG_ENABLED", true),
@@ -2127,23 +2186,8 @@ function parseOrchestrationDomain(ctx) {
                                             ? entryDeclarableRemoteExec(declaredLane)
                                             :
                                                 declaredLane === "local-docker" && process.env.DOCKER_IMAGE
-                                                    ? {
-                                                        provider: "local-docker",
-                                                        image: process.env.DOCKER_IMAGE,
-                                                        ...(process.env.DOCKER_MOUNT_PATH ? { mountPath: process.env.DOCKER_MOUNT_PATH } : {}),
-                                                        ...(process.env.DOCKER_PATH ? { dockerPath: process.env.DOCKER_PATH } : {}),
-                                                        ...(process.env.DOCKER_HOST ? { dockerHost: process.env.DOCKER_HOST } : {}),
-                                                        ...(process.env.DOCKER_MEMORY ? { memory: process.env.DOCKER_MEMORY } : {}),
-                                                        ...((n) => (n !== undefined ? { cpus: n } : {}))(optNumEnvStrict("DOCKER_CPUS")),
-                                                        ...((n) => (n !== undefined ? { pidsLimit: n } : {}))(optFinitePositiveEnv("DOCKER_PIDS_LIMIT")),
-                                                        ...(boolEnv("DOCKER_DROP_CAPS", false) ? { dropAllCaps: true } : {}),
-                                                        ...(process.env.DOCKER_NETWORK
-                                                            ? { network: enumEnv("DOCKER_NETWORK", "bridge", ["none", "bridge", "host"]) }
-                                                            : {}),
-                                                        ...((n) => (n !== undefined ? { commandTimeoutMs: n } : {}))(optNumEnvStrict("DOCKER_COMMAND_TIMEOUT_MS")),
-                                                        ...((names) => (names !== undefined ? { env: allowlistedEnv(names, process.env) } : {}))(parseEnvNameAllowlist("DOCKER_SANDBOX_ENV", singleUserTurnkey)),
-                                                        ...((capacity) => (capacity !== undefined ? { capacity } : {}))(parseLocalDockerCapacityEnv()),
-                                                    }
+                                                    ?
+                                                        { provider: "local-docker", ...parseLocalDockerLaneEnv(singleUserTurnkey), image: process.env.DOCKER_IMAGE }
                                                     :
                                                         declaredLane === "device"
                                                             ? {
@@ -2488,12 +2532,14 @@ function parseCenterBaseUrl(name, raw, role) {
 }
 function parseWebAdmin(baseUrl, requirePrincipal, liveBaseUrl, webBaseUrl) {
     const worker = process.env[WEB_ADMIN_ENV.worker] || undefined;
-    const declared = readCenterCredentialDeclaration();
+    const declared = readWebAdminCredentialDeclaration("access");
+    const assertion = credentialOriginOf(readWebAdminCredentialDeclaration("assertion"));
     return {
         baseUrl,
         ...(liveBaseUrl !== undefined ? { liveBaseUrl } : {}),
         ...(webBaseUrl !== undefined ? { webBaseUrl } : {}),
         credential: createCenterCredentialSource(declared.from === "file" ? { ...declared, multiTenant: requirePrincipal } : declared, worker),
+        ...(assertion.from !== "absent" ? { assertionToken: assertion } : {}),
         dryRun: boolEnv(WEB_ADMIN_ENV.dryRun, false),
         worker,
     };
@@ -2651,8 +2697,8 @@ const MEMORY_GROUP_KEYS = [
 const AUTH_GROUP_KEYS = [
     "authToken", "authTokens", "allowUnauthedWrites", "corsOrigins", "principalHeader", "requirePrincipal", "autonomy",
     "commandPolicy", "compliancePosture", "lockedConfigKeys", "retentionPolicy", "retentionSweep",
-    "operatorPrincipals", "operatorSingleUser", "serviceTokenActsForDeployment", "configCatalogEnabled", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
-    "principalJwtMaxTtlSec", "authBridgeIssuer", "bindHost", "bindHostSource",
+    "operatorPrincipals", "operatorDrainPrincipals", "operatorSingleUser", "serviceTokenActsForDeployment", "configCatalogEnabled", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
+    "principalJwtMaxTtlSec", "authBridgeIssuer", "bindHost",
 ];
 const ORCHESTRATION_GROUP_KEYS = [
     "sandboxGit", "remoteExec", "remoteExecHomeDir", "worktreeIsolation", "leaderEnabled", "leaderFanoutEnabled", "routerEnabled", "selfOrchestrationEnabled",
@@ -2750,7 +2796,7 @@ function k8sWorkspaceStore() {
             secretKey,
             ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
             ...(keyPrefix !== undefined ? { keyPrefix } : {}),
-            ...((n) => (n !== undefined ? { presignTtlSec: n } : {}))(optNumEnvStrict("WORKSPACE_SNAPSHOT_TTL_SEC")),
+            ...((n) => (n !== undefined ? { presignTtlSec: n } : {}))(workspaceSnapshotTtlKnob(process.env.WORKSPACE_SNAPSHOT_TTL_SEC)),
         },
     };
 }
@@ -2825,7 +2871,7 @@ export function loadConfig() {
         throw new Error(retentionRefusal);
     }
     const { directApprovalDoor, durableApproval: dgDurable, approvalHmacKeys: dgHmacKeys } = approval;
-    const { principalJwtPubkeys, principalJwtIss, principalJwtAud, operatorPrincipals: dgOperators, operatorSingleUser, authTokens } = auth;
+    const { principalJwtPubkeys, principalJwtIss, principalJwtAud, operatorPrincipals: dgOperators, operatorDrainPrincipals, operatorSingleUser, authTokens } = auth;
     const directDoorActive = directApprovalDoor && dgDurable && dgHmacKeys.length > 0 && principalJwtPubkeys.length > 0 && !!principalJwtIss && !!principalJwtAud;
     const doorRefusal = halfOpenDirectDoorRefusal({
         directApprovalDoor,
@@ -2844,10 +2890,14 @@ export function loadConfig() {
     if (operatorsRefusal !== undefined) {
         throw new Error(operatorsRefusal);
     }
-    const singleUserOperatorRefusal = operatorSingleUserRefusal({ operatorSingleUser, requirePrincipal, operatorPrincipals: dgOperators });
+    const singleUserOperatorRefusal = operatorSingleUserRefusal({ operatorSingleUser, requirePrincipal, operatorPrincipals: dgOperators, operatorDrainPrincipals });
     if (singleUserOperatorRefusal !== undefined) {
         throw new Error(singleUserOperatorRefusal);
     }
+    const rosterRefusal = operatorRosterWellFormedRefusal({ operatorPrincipals: dgOperators, operatorDrainPrincipals });
+    if (rosterRefusal !== undefined) {
+        throw new Error(rosterRefusal);
+    }
     const bakeOperatorsRefusal = bakeOperatorPrincipalsRefusal({ imageBakes: orchestration.imageBakes, operatorPrincipals: dgOperators });
     if (bakeOperatorsRefusal !== undefined) {
         throw new Error(bakeOperatorsRefusal);

package/dist/control-socket.d.ts

@@ -0,0 +1,51 @@
+import type { Server } from "node:http";
+/** 开不了口的原因词(闭集;`listening` 行的 `controlSocketUnavailable` 取值;顺序 = 开口序)。 */
+export declare const CONTROL_SOCKET_UNAVAILABLE_REASONS: readonly ["unsupported_platform", "data_root_not_exclusive", "path_too_long", "dir_not_private", "path_occupied", "bind_failed"];
+export type ControlSocketUnavailableReason = (typeof CONTROL_SOCKET_UNAVAILABLE_REASONS)[number];
+/** 开口的结局:在听(绝对路径)或缺席(原因词)—— 恰一形。 */
+export type ControlSocketOpening = {
+    readonly listening: true;
+    readonly path: string;
+} | {
+    readonly listening: false;
+    readonly reason: ControlSocketUnavailableReason;
+};
+/** 数据根(锁所守的物理路径)→ 控制 socket 的绝对路径。唯一推导:`listening` 行报的、开口判的、附着方连的是同一只。 */
+export declare function controlSocketPathOf(physicalDataRoot: string): string;
+/** 私有判的读数(`lstat`,不跟符号链接)。`absent` = 不在;`unreadable` = 读不出(按不私有处置)。 */
+export type ControlPathReading = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "unreadable";
+} | {
+    readonly kind: "directory" | "socket" | "symlink" | "other";
+    readonly uid: number;
+    readonly mode: number;
+};
+/** 读一只路径(`lstat`)。不在 ⇒ `absent`;别的读错 ⇒ `unreadable`。 */
+export declare function readControlPath(path: string): ControlPathReading;
+/** `control/` 私有吗:是目录(不是符号链接)∧ 属主 = `euid` ∧ 无组 / 他人位。任何别的读数 ⇒ 否。 */
+export declare function controlDirIsPrivate(reading: ControlPathReading, euid: number): boolean;
+/** `engine.sock` 是不是本用户的 socket:是 socket(不是符号链接)∧ 属主 = `euid`。任何别的读数 ⇒ 否。 */
+export declare function controlSocketIsOwned(reading: ControlPathReading, euid: number): boolean;
+export interface ControlSocketOpenOptions {
+    /** 本进程持锁独占的物理数据根(`StoreBackend.exclusiveDataRoot()`);缺席 ⇒ 不开口。 */
+    readonly exclusiveDataRoot: string | undefined;
+    /** 平台读数(缺省 = 全仓唯一平台读点 `HOST_PLATFORM`)。 */
+    readonly platform?: string;
+    /** 属主判对照的 euid(缺省 `process.geteuid()`)。 */
+    readonly euid?: number;
+}
+/**
+ * 在 `server`(控制口那只 `http.Server`,`createHttpServer` 交出的 `controlSocketServer`)上开控制 socket —— 判序见头注。
+ * 结局恰一形;`listening: false` 时 `server` 不在听(绑上又判不过的那一形已先关)。调用点:TCP listen 成功之后、`listening` 行之前(起服第 10 段)。
+ */
+export declare function openControlSocket(server: Server, opts: ControlSocketOpenOptions): Promise<ControlSocketOpening>;
+/** `listening` 行的两键 —— 同一次开口结局的投影,恰一键在场(`controlSocket` ⟺ 在听;`controlSocketUnavailable` ⟺ 缺席)。 */
+export interface ControlSocketLineKeys {
+    readonly controlSocket?: string;
+    readonly controlSocketUnavailable?: ControlSocketUnavailableReason;
+}
+/** 开口结局 → `listening` 行两键(唯一投影)。 */
+export declare function controlSocketLineKeysOf(opening: ControlSocketOpening): ControlSocketLineKeys;
+//# sourceMappingURL=control-socket.d.ts.map

package/dist/control-socket.js

@@ -0,0 +1,115 @@
+import { lstatSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ensureDir } from "@sema-agent/core";
+import { HOST_PLATFORM } from "./plugins/host-platform.js";
+export const CONTROL_SOCKET_UNAVAILABLE_REASONS = ["unsupported_platform", "data_root_not_exclusive", "path_too_long", "dir_not_private", "path_occupied", "bind_failed"];
+const SUN_PATH_MAX_BYTES = {
+    darwin: 104,
+    linux: 107,
+    aix: "unsupported",
+    android: "unsupported",
+    freebsd: "unsupported",
+    haiku: "unsupported",
+    openbsd: "unsupported",
+    sunos: "unsupported",
+    win32: "unsupported",
+    cygwin: "unsupported",
+    netbsd: "unsupported",
+};
+export function controlSocketPathOf(physicalDataRoot) {
+    return join(physicalDataRoot, "control", "engine.sock");
+}
+function readingOf(stats) {
+    const kind = stats.isSymbolicLink() ? "symlink" : stats.isDirectory() ? "directory" : stats.isSocket() ? "socket" : "other";
+    return { kind, uid: stats.uid, mode: stats.mode };
+}
+export function readControlPath(path) {
+    try {
+        return readingOf(lstatSync(path));
+    }
+    catch (err) {
+        return err.code === "ENOENT" ? { kind: "absent" } : { kind: "unreadable" };
+    }
+}
+export function controlDirIsPrivate(reading, euid) {
+    return reading.kind === "directory" && reading.uid === euid && (reading.mode & 0o077) === 0;
+}
+export function controlSocketIsOwned(reading, euid) {
+    return reading.kind === "socket" && reading.uid === euid;
+}
+function sunPathMaxBytesOf(platform) {
+    if (!Object.hasOwn(SUN_PATH_MAX_BYTES, platform))
+        return undefined;
+    const limit = SUN_PATH_MAX_BYTES[platform];
+    return typeof limit === "number" ? limit : undefined;
+}
+const unavailable = (reason) => ({ listening: false, reason });
+async function ioStep(act) {
+    try {
+        await act();
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+function listenOn(server, path) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        server.once("error", onError);
+        server.listen(path, () => {
+            server.removeListener("error", onError);
+            resolve();
+        });
+    });
+}
+export async function openControlSocket(server, opts) {
+    const maxBytes = sunPathMaxBytesOf(opts.platform ?? HOST_PLATFORM);
+    if (maxBytes === undefined)
+        return unavailable("unsupported_platform");
+    const euid = opts.euid ?? process.geteuid?.();
+    if (euid === undefined)
+        return unavailable("unsupported_platform");
+    const root = opts.exclusiveDataRoot;
+    if (root === undefined)
+        return unavailable("data_root_not_exclusive");
+    const path = controlSocketPathOf(root);
+    if (Buffer.byteLength(path, "utf8") > maxBytes)
+        return unavailable("path_too_long");
+    const dir = dirname(path);
+    await ioStep(() => ensureDir(dir));
+    if (!controlDirIsPrivate(readControlPath(dir), euid))
+        return unavailable("dir_not_private");
+    const existing = readControlPath(path);
+    switch (existing.kind) {
+        case "absent":
+            break;
+        case "socket":
+            if (!controlSocketIsOwned(existing, euid))
+                return unavailable("path_occupied");
+            if (!(await ioStep(() => unlinkSync(path))).ok)
+                return unavailable("bind_failed");
+            break;
+        case "directory":
+        case "symlink":
+        case "other":
+            return unavailable("path_occupied");
+        case "unreadable":
+            return unavailable("bind_failed");
+        default: {
+            const unknownReading = existing;
+            throw new Error(`control socket: unknown path reading ${JSON.stringify(unknownReading)}`);
+        }
+    }
+    if (!(await ioStep(() => listenOn(server, path))).ok)
+        return unavailable("bind_failed");
+    if (!controlSocketIsOwned(readControlPath(path), euid) || !controlDirIsPrivate(readControlPath(dir), euid)) {
+        await new Promise((resolve) => server.close(() => resolve()));
+        return unavailable("bind_failed");
+    }
+    return { listening: true, path };
+}
+export function controlSocketLineKeysOf(opening) {
+    return opening.listening ? { controlSocket: opening.path } : { controlSocketUnavailable: opening.reason };
+}
+//# sourceMappingURL=control-socket.js.map

package/dist/deployment-governance.d.ts

@@ -64,7 +64,8 @@ export interface PathAdjudication {
  *  · `durable` —— checkpoint suspend/resume 服 ask(HTTP 腿 durable 开、park 赎回腿)。core 的问答策略
  *    (`createDurableQuestionPolicy()`,原形逐字)**只**叠在这一形上:它对引擎的问题工具答 `ask`,落点归 core 的同步优先
  *    (有问题席 ⇒ 先投卡、席在窗内拿到答即交答;没拿到 ⇒ 停驻 —— 卡由活面呈出而窗走完的那一问除外:席抛,引擎的投递失败臂不停驻)。
- *  · `live`    —— Runner 的活 onAsk 席当场服 ask(run-local 的 `createLocalApprover`:TTY 问 y/N / 无 TTY 当场拒;
+ *  · `live`    —— Runner 的活 onAsk 席当场服 ask(run-local 的 `createLocalApprover`:TTY 问 y/N / 无 TTY 当场拒;leader 车道不耐久的腿
+ *    (`leader/leader.ts` `leaderLegDurability` 判为不耐久:各修复腿、没递停驻设施或续跑上下文没落的 worker)的无人值守层:答集内的类按策略答,其余交回 core 的缺席路 —— 这条腿没有停驻设施 ⇒ 拒;
  *    core `isLiveApproverSeat(onAsk)` 为真时 `suspendAsk` 早退,ask 落回调)。三张名单与 durable 席**同一只**策略。
  *  · `absent`  —— 没有谁服 ask ⇒ adjudicated allow-all;**只**服务零名单(HTTP 腿「durable 关 ∧ 单用户零意图」)。
  *    带名单进来 = 响亮拒:名单被一条没有席的腿静默吞掉,正是 [ref] 的病形。

package/dist/deployment-shape.d.ts

@@ -17,7 +17,7 @@
  * `holds` 的入参型 = 所声明轴读入形的交叉({@link DeploymentShapeInput}),所以调用方递完整 `ServiceConfig` 或只递那几键的窄形都行。
  *
  * ## 什么进表、什么不进
- * 进表的是**形规则**:只由部署形事实决定的布尔(去重后 15 行;同一条规则的多个消费者读同一行,不各成一行)。
+ * 进表的是**形规则**:只由部署形事实决定的布尔(去重后 16 行;同一条规则的多个消费者读同一行,不各成一行)。
  * 把一行与**非形事实**(锁键、合规档位、审批意图、请求身份、请求体)合取的能力判据是**消费者**,住在它自己的模块
  * (`mcpInjectionHonored` = 锁 ∧ 合规 ∧ `!multiTenant`;`taskHooksHonored`;身份门 …),读行、不读原始键。
  * 车道表(`execution-lane-caps.ts`)按车道词键控的布尔列(`laneIsolated` 等)是车道轴自己的事实表,不是「部署」的谓词;行读它们。
@@ -111,6 +111,14 @@ export declare const DEPLOYMENT_SHAPE_PREDICATES: Readonly<{
      * 一次性迁移 M48 的输入(`plugins/store-backend.ts`:有边界 ⇒ 不改写哨兵属主)。
      */
     identityBoundary: DeploymentShapePredicate<"principal" | "identity">;
+    /**
+     * 「这台部署接没接**过凭据门**的来源」的问法 —— 身份来源律 5(`identity-source.ts` 头注)在部署上的投影:配置接了的来源里有凭据门认的那一类
+     * (service 凭据,或鉴权桥 issuer —— 含中心回退;`passesCredentialGate` 那一列)。**不是** {@link DEPLOYMENT_SHAPE_PREDICATES.identityBoundary}:
+     * 那一行把 `REQUIRE_PRINCIPAL` / 只读 trace 凭据 / 直连门也算作边界(它们让主体头不再是 dev-open 的自报),本行只问「有没有一类凭据过得了门」——
+     * 三样都不过,所以只配其中之一的部署两行答案相反,这是两问,不是一问两答。没接 ⇒ 写门(问请求)对每一次请求都拒(`ALLOW_UNAUTHED_WRITES` 之外)。
+     * 读者:记忆整理阀门的启动期告警(`boot/stage-06-runners.ts`;「这台部署上 run 口对谁都开不了」)。请求面不读本行:写门问的是请求。
+     */
+    credentialGateSource: DeploymentShapePredicate<"identity">;
     /**
      * 租户轴的问法。今天与 {@link DEPLOYMENT_SHAPE_PREDICATES.principalRequired} 读**同一个声明**([ref] ①:托管 / 多租 ⇔ `REQUIRE_PRINCIPAL=true`,
      * 签发方配置是身份验签轴、不算租户证据)—— 两个问题、一根轴、一个读口;「鉴权必需」与「多租形」拆成两个声明时只改这一行的判官。

package/dist/deployment-shape.js

@@ -1,5 +1,5 @@
 import { capabilitiesFor, executionLaneCaps, executionLaneOf, handsOnWorkerFilePlane, laneWiresExecutionEnv } from "./execution-lane-caps.js";
-import { configuredIdentitySources } from "./identity-source.js";
+import { configuredIdentitySources, passesCredentialGate } from "./identity-source.js";
 function readPrincipalAxis(deployment) {
     return { declared: deployment.requirePrincipal === true };
 }
@@ -54,6 +54,7 @@ const VM_ISOLATION_RUNTIME_CLASSES = new Set(["kata", "kata-qemu", "kata-clh", "
 export const DEPLOYMENT_SHAPE_PREDICATES = Object.freeze({
     principalRequired: createPredicate(["principal"], "身份轴:运维声明了 REQUIRE_PRINCIPAL=true —— 每个调用方都必须带一个验过的主体。", ({ principal }) => principal.declared),
     identityBoundary: createPredicate(["principal", "identity"], "身份轴:这台部署有身份边界 —— 声明了 REQUIRE_PRINCIPAL,或配置接了任一已验身份来源(service 凭据 / 鉴权桥 / 直连门),或声明了只读 trace 凭据。", ({ principal, identity }) => principal.declared || identity.sources.length > 0 || identity.traceTokenDeclared),
+    credentialGateSource: createPredicate(["identity"], "身份轴:这台部署接了一类过凭据门的来源 —— service 凭据,或鉴权桥(登录令牌);只开 REQUIRE_PRINCIPAL / 只配 trace 凭据 / 只开直连门都不算。", ({ identity }) => identity.sources.some(passesCredentialGate)),
     multiTenant: createPredicate(["principal"], "租户轴:这台部署服务不止一个主人(托管 / 多租;C-R100 ① 由 REQUIRE_PRINCIPAL=true 声明)。", ({ principal }) => principal.declared),
     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),

package/dist/device-protocol.d.ts

@@ -7,11 +7,12 @@
  *
  * 为什么是精选而不是把 `device-ws-protocol.ts` 整只暴露:那个模块里还有**服务端**自己的半场(帧解析与准入、
  * 验签、各种铸 id)。把它们变成公开面,等于替实现细节背上 semver。这里只再导出 executor **会用到**的:
- * 闭集常量、两向帧型、构造握手签名字节所需的两只纯函数,以及两份「随协议修订号走」的事实:结局码按修订号分行的增量表
- * (`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` + 取集函数 `deviceOutcomeErrorCodesAt`:executor 按自己声明的修订号裁剪会发的词)与
+ * 闭集常量、两向帧型、构造握手签名字节所需的两只纯函数,以及三份「随协议修订号走」的事实:结局码按修订号分行的增量表
+ * (`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` + 取集函数 `deviceOutcomeErrorCodesAt`:executor 按自己声明的修订号裁剪会发的词)、指令 kind 按修订号分行的增量表
+ * (`DEVICE_INSTRUCTION_KINDS_BY_REVISION` + 取集函数 `deviceInstructionKindsAt`:executor 按自己声明的修订号裁剪 `hello.supports` —— 高于它的 kind 声明了也不会下发)与
  * helloAck 数值位的界表(`DEVICE_HELLO_ACK_BOUNDS` + 判据 `deviceHelloAckNumberFlaw`:executor 读到越界值 ⇒ 协议违例)。要加名字 = 改这只文件 + 同批改
  * `test/device-protocol-subpath.test.ts` 的闭集(新增公开面必须是一次有意的动作)。
  */
-export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
-export type { DeviceFrameType, DeviceServerFrameType, DeviceHelloRejectCode, DeviceByeReason, DeviceGoodbyeReason, DeviceChunkKind, DeviceCancelState, DeviceInstructionKind, DeviceOutcomeErrorCode, DeviceProtocolRevision, DeviceHelloAckNumericField, WireFileInfo, WireWriteExpectation, DeviceInstructionOutcome, DeviceInstructionArgsByKind, DeviceChallengeFrame, DeviceHelloAckFrame, DeviceHelloRejectFrame, DeviceInstructionFrame, DevicePayloadFrame, DeviceServerFrame, DeviceHelloFrame, DeviceFrame, DeviceResultFrame, DeviceChunkFrame, DeviceGoodbyeFrame, DeviceHeartbeatFrame, } from "./device-ws-protocol.js";
+export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_INSTRUCTION_KINDS_BY_REVISION, DEVICE_BOUND_READ_OPS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceInstructionKindsAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
+export type { DeviceFrameType, DeviceServerFrameType, DeviceHelloRejectCode, DeviceByeReason, DeviceGoodbyeReason, DeviceChunkKind, DeviceCancelState, DeviceInstructionKind, DeviceBoundReadOp, DeviceOutcomeErrorCode, DeviceProtocolRevision, DeviceHelloAckNumericField, WireFileInfo, WireWriteExpectation, DeviceInstructionOutcome, DeviceInstructionArgsByKind, DeviceChallengeFrame, DeviceHelloAckFrame, DeviceHelloRejectFrame, DeviceInstructionFrame, DevicePayloadFrame, DeviceServerFrame, DeviceHelloFrame, DeviceFrame, DeviceResultFrame, DeviceChunkFrame, DeviceGoodbyeFrame, DeviceHeartbeatFrame, } from "./device-ws-protocol.js";
 //# sourceMappingURL=device-protocol.d.ts.map

package/dist/device-protocol.js

@@ -1,2 +1,2 @@
-export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
+export { DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_HELLO_DOMAIN_TAG, DEVICE_WS_LIMITS, DEVICE_FRAME_TYPES, DEVICE_SERVER_FRAME_TYPES, DEVICE_HELLO_REJECT_CODES, DEVICE_BYE_REASONS, DEVICE_GOODBYE_REASONS, DEVICE_CHUNK_KINDS, DEVICE_CANCEL_STATES, DEVICE_INSTRUCTION_KINDS, DEVICE_INSTRUCTION_KINDS_BY_REVISION, DEVICE_BOUND_READ_OPS, DEVICE_OUTCOME_ERROR_CODES, DEVICE_OUTCOME_ERROR_CODES_BY_REVISION, DEVICE_HELLO_ACK_BOUNDS, buildHelloSignaturePayload, decodeUlid16, deviceOutcomeErrorCodesAt, deviceInstructionKindsAt, deviceHelloAckNumberFlaw, } from "./device-ws-protocol.js";
 //# sourceMappingURL=device-protocol.js.map

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

@@ -40,6 +40,7 @@ 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";
+import type { NonPersonTier } from "./operator-roster.js";
 /** 交给调用方的一片上行流(`data` 已从 base64 解回字节)。 */
 export interface DeviceChunkDelivery {
     streamSeq: number;
@@ -129,6 +130,12 @@ export interface DeviceWsHubOptions {
     enrollment: DeviceEnrollment;
     /** 本副本 id(写进连接租约行,跨副本排障用)。 */
     replicaId: string;
+    /**
+     * hello 准入的属主圈禁读者:这一台设备行的属主此刻落在名册的哪一档**非人档**(圈禁,`undefined` = 不圈禁)。答「是」⇒ `helloReject: auth_failed`,不夺租约、不顶替旧连接。
+     * 汇聚端自己不 import 名册、不判档位:判官只有一只(`http/principal-gate.ts` 的 `confinedTierOf`,设备读点 `deviceOwnerConfinedTier`),装配方(`boot/device-lane.ts`)把它连进来。
+     * **必填**:可选会让漏接静默(没接 = 不圈禁,安全轴上的静默放宽)—— 漏接编译红。每次 hello 现读(名册是现态,不拍快照);读者抛 ⇒ 握手失败、连接关(`device_hello_failed`),不放行。
+     */
+    ownerConfinedTier: (owner: DeviceOwner) => NonPersonTier | undefined;
     logger?: DeviceWsHubLogger;
     metrics?: {
         inc(name: string, labels?: Record<string, string>): void;

package/dist/device-ws-hub.js

@@ -5,7 +5,7 @@ import { WebSocketServer } from "ws";
 import { DEVICE_DRAINING_CODE, DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, assertDeviceIdShape, } from "./device-store.js";
 import { MAX_TIMER_DELAY_MS } from "./config-types.js";
 import { canonicalAddress, createTrustedProxySet } from "./net-address.js";
-import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, deviceProtocolRevisionRefusal, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
+import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKindAt, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, deviceProtocolRevisionRefusal, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
 const OUTCOME_UNKNOWN_SENTENCE = "outcome unknown — the command may have already executed on the device; verify its effect before re-running";
 const SETTLED_MEMO_MAX = 512;
 const DRAIN_RETRY_AFTER_SEC = 15;
@@ -66,6 +66,7 @@ const ALLOWED_SUCCESS_OUTCOME_KINDS = {
     remove: ["void"],
     createTempDir: ["write"],
     createTempFile: ["write"],
+    openBound: ["stat", "read"],
 };
 const HELLO_ACK_FIELD_SOURCES = {
     heartbeatIntervalMs: "option heartbeatIntervalMs",
@@ -120,7 +121,7 @@ function forwardedHopAddress(hop) {
     return canonicalAddress(t);
 }
 export function createDeviceWsHub(options) {
-    const { store, enrollment, replicaId, logger, metrics } = options;
+    const { store, enrollment, replicaId, ownerConfinedTier, logger, metrics } = options;
     const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15_000;
     const heartbeatMisses = options.heartbeatMisses ?? 3;
     const leaseSeconds = options.leaseSeconds ?? 45;
@@ -437,6 +438,12 @@ export function createDeviceWsHub(options) {
         }
         if (row.status === "revoked")
             return rejectHello(conn, "revoked");
+        const confined = ownerConfinedTier(row.owner);
+        if (confined !== undefined) {
+            logger?.warn("device_hello_owner_confined", { deviceId: row.deviceId, tier: confined });
+            metrics?.inc("device_hello_rejected_total", { code: "auth_failed" });
+            return rejectHello(conn, "auth_failed");
+        }
         const existing = conns.get(row.deviceId);
         if (existing && existing !== conn) {
             const fresh = Date.now() - existing.lastFrameAt < heartbeatIntervalMs * heartbeatMisses;
@@ -500,7 +507,7 @@ export function createDeviceWsHub(options) {
         conn.workspaceRoot = frame.workspaceRoot;
         const supported = new Set();
         for (const s of frame.supports) {
-            const k = asInstructionKind(s);
+            const k = asInstructionKindAt(s, frame.protocolVersion);
             if (k !== null)
                 supported.add(k);
         }