@sema-agent/server 7.151.0 → 7.152.0

package/dist/config-types.d.ts

@@ -398,20 +398,16 @@ export interface A2aServeConfig {
  *  off (the control plane never mounts). The runner-facing facts (the runner principal, the build-host CACHE_BASE,
  *  the default base ref) live here so image-api injects only VETTED, server-fixed values into the build.sh argv —
  *  operator free-text never reaches the runner. */
-/** [ref] 车3([ref] 流内审批协议)的配置面。总开关默认 **true**(clay 裁 2026-08-08,[ref] 翻真验证后;
- *  树上已生效,发布线落在 7.4.0 之后的下一个发布);从属旋钮**除 `windowMs` 外**只在开关为真时生效
- *  ([ref]:`STREAM_ASK_WINDOW_MS` 是活卡窗长,与协议上不上场解耦 —— 逐条辖域见各字段域注)
+/** [ref] 车3([ref] 流内审批协议)的配置面。协议上不上场只由装配在场性定(审批席 ∧ store backend ∧ park 设施,
+ *  `resolveStreamApprovalGate`)—— 没有总开关:审批只有呈卡族一个帧族,开关的「关」(回退发旧族活卡)随旧族退役。
+ *  从属旋钮**除 `windowMs` 外**只在协议上场时生效([ref]:`STREAM_ASK_WINDOW_MS` 与协议上不上场解耦 —— 逐条辖域见各字段域注)
  *  (语义与「谁需要 / 谁被伤 / 什么补偿」三问见 `ServiceConfigFlat.streamApproval` 的注)。 */
 export interface StreamApprovalConfig {
-    /** 协议总开关。`STREAM_APPROVAL_ENABLED`,默认 **true**(clay 裁 2026-08-08,[ref] 翻真验证后;7.5.0 起)。显式 false ⇒ 全链逐字 7.3.0 前行为(唯一干净还原键)。
-     *  翻真要等回决端点(车4)与对账收敛器(车5)到位——在此之前是个不完整协议(有卡无正规回决口、
-     *  有 PARKING 无收敛器、跨副本回决无唤醒路径)。 */
-    enabled: boolean;
     /** `ToolApprovalCoordinator` 的 `ttlMs` —— **一只活卡等人多久**([ref] §3.3 的「配置窗默认」)。
      *  `STREAM_ASK_WINDOW_MS`,默认 **300000**(同裁与 sync 腿既有 5min 活卡窗对齐)。
      *
      *  🔴 **辖域([ref] 起):无条件** —— 本值在**每一条**呈活卡的腿上生效,与流内协议上不上场无关
-     *  (`DB_BACKEND=local` / 无 park 设施 / `STREAM_APPROVAL_ENABLED=false` 的部署同样按它计窗)。
+     *  (无 park 设施的部署上它管的是「没有卡、每只问当场交政策口」之前的那一格 —— 那里没有窗可计)。
      *  旧文「开关为假 ⇒ 本值不参与,窗保持既有 `DEFAULT_APPROVAL_TTL_MS`(5min)」是**已修的病**,不是
      *  设计:那让一根部署级旋钮的生效与否挂在装配在场性上,运维配了它、没有任何一行说它没生效
      *  (clay 令:部署级旋钮禁挂在场性派生腿)。缺省值与那个常量同为 300000 ⇒ **没配过这根 env 的部署
@@ -1238,14 +1234,9 @@ export interface ServiceConfigFlat {
     /** plugins 域 clone host 白名单(`PLUGINS_ALLOW_HOSTS`,缺省 github.com;契约 [ref]① 双保险面,
      *  消费在 capabilities/center-plugins.ts)。 */
     pluginsAllowHosts: string[];
-    /** 监听绑址([ref] cli 实锤:此前 `HOST` **零消费**、`listen(port)` 恒绑所有接口)。
-     *  `BIND_HOST`(兼容 `HOST`)。显式值恒生效;缺省见 {@link resolveBindHost}——**无鉴权写面
+    /** 监听绑址:唯一来源 = `BIND_HOST`(`HOST` 不读 —— zsh 恒设 HOST=机器名,读它等于被 shell 环境暗配 bind 面)。显式值恒生效;缺省见 {@link resolveBindHost}——**无鉴权写面
      *  (allowUnauthedWrites 且零凭证)自动收窄到 127.0.0.1**,其余维持全接口(既有部署零影响)。 */
     bindHost?: string;
-    /** [ref]③ `bindHost` 的取值来源(BIND_HOST 显式 / HOST 兼容名 / 未设)。`"HOST"` 时 main.ts 打一行
-     *  启动告警:zsh 常把 HOST 设成机器名,`{...process.env}` 起底的壳会静默继承给引擎——bind 面被 shell
-     *  环境暗配而部署者不知情(HOST=机器名解析到 LAN 口时=静默扩暴露面)。 */
-    bindHostSource?: "BIND_HOST" | "HOST";
     /** D-1 附件孤儿对象 GC 的 grace(毫秒;`ATTACHMENT_ORPHAN_GRACE_MS`,默认 1h,**0=关掉本腿**)。
      *  复审 F10:同 tick 邻居(workflowOrphanGraceMs/attachmentUnboundTtlMs/scratchpadSweepTtlMs)都有
      *  旋钮——存量对象巨大的部署要调慢/停掉,不该被迫取消 MinIO 配置(那会连带关掉整个附件面)。 */
@@ -1266,7 +1257,8 @@ export interface ServiceConfigFlat {
      *  the unguessable-key capability URLs be enumerated); the private presigned track shares
      *  SESSION_SNAPSHOT_BUCKET (default "session-snapshots") under a "sendfile/" prefix.
      *  SEND_USER_FILE_URL_TTL = default ttl seconds when the tool call omits one; 0 = permanent (the settled
-     *  default). Unset/non-integer/negative fail-SAFE to 0 — never NaN into a signature. */
+     *  default). Unset / empty ⇒ 0; anything but canonical decimal digits does not load (read as 0 it would turn a link meant to expire into a
+     *  permanent public one), nor does a value over the SigV4 ceiling (`config.ts` `sendUserFileUrlTtlKnob`). */
     sendUserFile?: {
         endpoint: string;
         publicEndpoint?: string;
@@ -1387,6 +1379,11 @@ export interface ServiceConfigFlat {
      *  "empty = everyone on the approval queue" reading is gone). A single-user deployment must answer "who operates it" — a named list here or {@link operatorSingleUser}; neither ⇒ refusal
      *  (`operator-declaration-required`: the server process refuses at boot stage 1, and `createHttpServer` refuses for every assembler, embedders included). */
     operatorPrincipals: string[];
+    /** `OPERATOR_DRAIN_PRINCIPALS` —— 名册的**排空档**(服务主体名单;档表 `src/operator-roster.ts` 的 `drain` 行):名单内的验过主体只持 `drain` 一只运维权力、不是人 ——
+     *  它的身份只在声明了 `drain` 权力的路由(`POST /v1/admin/drain`)上算数,其余每条路由整次请求 403 `auth.principal_confined`,`GET /health` 按没出示凭据分档。
+     *  缺席 ≡ 空 = 这一档没人(少给权力,fail-closed;`loadConfig` 恒写)。与 `OPERATOR_PRINCIPALS` 同一个名字 / 不是主体名的条目 / 不是名字列表 ⇒ 拒启(`operator-roster-well-formed`);与 `OPERATOR_SINGLE_USER=true` 同在 ⇒ 拒启
+     *  (`operator-single-user`)。env 独有(没有中心写位),起服冻结。不算运维声明:单用户形只写它 ⇒ 照旧 `operator-declaration-required` 拒。 */
+    operatorDrainPrincipals?: readonly string[];
     /** `OPERATOR_SINGLE_USER=true` —— 单用户形显式声明「这台部署的每个调用方都是运维」([ref],[ref] ① 裁 A)。缺席 = 不声明(没人是,除非在名单里)。
      *  只在单用户形(`REQUIRE_PRINCIPAL` 未开)且名单为空时成立 —— 否则拒启(`config-invariants.ts` 的 `operator-single-user`:一个事实一个来源)。
      *  单用户形上它与具名名单二者必有其一,都没有 ⇒ 拒启(服务进程起服第 1 段;嵌入方在 `createHttpServer`;`operator-declaration-required`,[ref];`false` 与缺席同判)。
@@ -2027,10 +2024,12 @@ export interface ServiceConfigFlat {
      *  {@link import("./question.js").DEFAULT_QUESTION_THROTTLE}(与本旋钮族默认逐字同值)。 */
     questionThrottle?: QuestionThrottle;
     /** [ref]/[ref]② live tool-approval HITL — mount the ToolApprovalCoordinator on `RunnerDeps.onAsk` + the
-     *  `POST /v1/tool-approvals/:id/respond` route so a policy `ask` (the fs-write gate, ask-lists, non-durable safety
+     *  ask decision door (`POST /v1/tasks/:taskId/asks/:askId/decision`) so a policy `ask` (the fs-write gate, ask-lists, non-durable safety
      *  asks) routes to the live human as the CC three-choice card on the run's stream (core 1.290 sync-ask leg). A CC
      *  cap → posture-gated like askQuestion (single-user turnkey → ON; multi-tenant opt-in);
-     *  `TOOL_APPROVAL_ENABLED=true/false` overrides. Absent ⇒ core's headless auto-deny stands ([ref]⑤ fail-closed). */
+     *  `TOOL_APPROVAL_ENABLED=true/false` overrides. Absent ⇒ core's headless auto-deny stands ([ref]⑤ fail-closed).
+     *  Necessary, not sufficient: the coordinator mounts only when this worker presents approval cards (this knob ∧ a store backend ∧ a park
+     *  facility — `resolveStreamApprovalGate`); on a worker without them the knob has nothing to mount and the headless auto-deny stands too. */
     toolApprovalEnabled: boolean;
     /**
      * [ref] 车二(core [ref] 持久化权限规则「不再询问」车道)**总开关**。`PERMISSION_RULES_ENABLED`,
@@ -2061,17 +2060,11 @@ export interface ServiceConfigFlat {
      *  旋钮本身缺省对现行为零影响(D1)。`STREAM_ASK_WINDOW_MARGIN_MS`,默认 10000(10s）。ttl 概念沿用既有
      *  `approvalTimeoutSec` 族,本旋钮不新增第二个 TTL 概念。 */
     streamAskWindowMarginMs: number;
-    /** [ref] 车3([ref] 流内审批协议)总开关 + 四个从属旋钮。
+    /** [ref] 车3([ref] 流内审批协议)的从属旋钮(没有总开关:协议上不上场只由装配在场性定,见 {@link StreamApprovalConfig} 顶注)。
      *
-     *  **现行默认(clay 裁 2026-08-08 走 (a),[ref] 翻真验证后)**:`STREAM_APPROVAL_ENABLED` 默认 **true**
-     *  = 协议整体默认 **ON**;`STREAM_ASK_WINDOW_MS` 默认 **300000**(5min,与 sync 腿既有活卡窗、与
-     *  `DEFAULT_APPROVAL_TTL_MS` 对齐——「开协议」不再顺带把窗砍短)。⚠️ 版本坐标:翻转**已在树上生效**,
-     *  发布线上落在 7.4.0 之后的下一个发布,所以一台自报 7.4.0 的**已发布** worker 仍是 OFF,别只按
-     *  `/health` 的版本号推默认。显式 `STREAM_APPROVAL_ENABLED=false` 是**唯一干净还原键** ⇒ 全链逐字回到
-     *  翻转前行为:不发 `approval_request` 帧、不落 `approval_ask` 行、不起收敛器腿、`askStore` 不注入
-     *  协调器。⚠️ **窗不在这份还原清单里了([ref])**:`STREAM_ASK_WINDOW_MS` 自此在关协议的部署上照样
-     *  生效(缺省 300000 == `DEFAULT_APPROVAL_TTL_MS` ⇒ 没配过它的部署仍然字节不变),理由见
-     *  `StreamApprovalConfig.windowMs` 的辖域段。
+     *  **总开关 `STREAM_APPROVAL_ENABLED` 已退役**:它的「关」= 回退发旧族活卡(`tool_approval`),旧族退役后没有可关的东西;
+     *  部署 env 里还留着这一键 ⇒ 起服拒(退役墓碑,不论值)。`STREAM_ASK_WINDOW_MS` 默认 **300000**(5min,与
+     *  `DEFAULT_APPROVAL_TTL_MS` 对齐),理由见 `StreamApprovalConfig.windowMs` 的辖域段。
      *
      *  **旋钮为什么存在(2026-08-08 翻转前的成文前提,已被上面的裁定取代,留作沿革)**:那一版默认 false +
      *  60s 窗,三问记的是那个世界——
@@ -2084,7 +2077,7 @@ export interface ServiceConfigFlat {
      *  ⇒ 翻真时「窗变短」这一项被从翻转里摘出(窗默认抬回 300000),被伤面①②因此消失;60s 只在运维显式设
      *  `STREAM_ASK_WINDOW_MS=60000` 时才回来。
      *
-     *  `STREAM_APPROVAL_ENABLED` / `STREAM_ASK_WINDOW_MS` / `STREAM_APPROVAL_REPLAY_MAX` /
+     *  键:`STREAM_ASK_WINDOW_MS` / `STREAM_APPROVAL_REPLAY_MAX` /
      *  `STREAM_APPROVAL_ADMIT_MAX_PER_TASK` / `STREAM_APPROVAL_ADMIT_MAX_PER_OWNER` /
      *  `STREAM_APPROVAL_RECONCILE_BATCH` / `STREAM_APPROVAL_PENDING_GRACE_MS` /
      *  `STREAM_APPROVAL_ADHOC_GRACE_MS` / `STREAM_APPROVAL_ORPHAN_TTL_MS`(后四键 = 车5 收敛器)。 */
@@ -2103,7 +2096,7 @@ export interface ServiceConfigFlat {
      *
      * 施加点 = `ToolApprovalCoordinator` 的构造参 `unattendedPolicy`,五条「无人可答」的臂读同一
      * 个值;对账收敛器的同名构造参([ref],`boot/reapers.ts` 恒传同一个部署值)只供它的孤儿段打同一只终态 claim ——
-     * 两处读同一个值,于是崩溃恢复与 live 腿同答(设计稿 §1 的表:(a) 有店窗到期赢 CAS /(b) 无店窗到期 /(c) 店报错 catch /(d) windowZero 与
+     * 两处读同一个值,于是崩溃恢复与 live 腿同答(设计稿 §1 的表:(a) 有店窗到期赢 CAS /(b) 无店窗到期(7.152.0 起随无账协调器退役)/(c) 店报错 catch /(d) windowZero 与
      * headless 腿 /(e) 断连强转 + emit 全灭 + 写侧准入超限 + **投递集合入口活性过滤清空**([ref] 归
      * 位:与「查无活流」同一件事实的两个时刻,详见 `askBroadcast` 的该臂注))。`"timeout"` 宿主自报只留在 (b)(c) ——
      * 结束等待的确实是本仓的窗;其余三臂结束等待的是容量/连接/装配,自报恒缺席。
@@ -2115,14 +2108,11 @@ export interface ServiceConfigFlat {
      * `"timeout"` 自报(`approval_window_expired`)。
      *
      * 🔴 **射程边界(成文,不是遗漏)**:
-     *  · 唯一让本旋钮**无处施加**的键是 `TOOL_APPROVAL_ENABLED=false`(协调器整体不构造,core 走它自己的
-     *    headless 姿态)。**不造推断腿**:旋钮只在协调器在场时有意义,这一句是成文而不是代码分支。
-     *  · ⚠️ **与 `STREAM_APPROVAL_ENABLED` 正交**(codex 交叉复审 R2-F2 验真后纠正 —— 本注上一版把两者
-     *    写成了一回事,是错的):协议开关关掉只是不注入 `askStore`/协议窗,协调器照常在场,于是 R-13 的
-     *    D1 窗到期臂**照样**走 park 路由。这不是漏网:设计稿 §2 明写 park 的承载是 **core checkpoint**
-     *    而不是 server 的 ask 行,「无 askStore 但有 durable 设施」正是 R-13 点名的**主受益部署**。
-     *    要回滚 R-13 的行为面,键是 `UNATTENDED_APPROVAL_POLICY=deny`,**不是**协议开关。
-     *    射程钉:`test/unattended-approval-policy.test.ts` 的 codex R2-F2 两格。
+     *  · 本旋钮只在审批协调器在场时有处施加;协调器只在呈卡协议上场时构造(`TOOL_APPROVAL_ENABLED` ∧ store backend ∧ park 设施,
+     *    `boot/coordinators.ts`)。不上场的三形各自的终局与本旋钮无关:开关关 ⇒ core 自己的姿态(有 durable 设施时照常 park);
+     *    开关开而无 store backend / 无 park 设施 ⇒ 没有审批席也没有停驻处,core 的无审批席臂当场拒。**不造推断腿**:这一句是成文而不是代码分支。
+     *  · 总开关 `STREAM_APPROVAL_ENABLED` 7.152.0 起退役;要回滚 R-13 的行为面,键是 `UNATTENDED_APPROVAL_POLICY=deny`。
+     *    射程钉:`test/unattended-approval-policy.test.ts` 的「呈卡协议不上场与本旋钮的关系」一组。
      *  · APPROVAL_REQUIRE 名单工具:**要不要 ask** 由 `createApprovalBaselinePolicy` 的 durable gate 类裁决,那一层
      *    结构上读不到本旋钮;但那只 ask 的**答法**在协调器在场时与治理 ask 同走流内臂、同政策(引擎先问活席
      *    `onAsk`,答 `"unavailable"` 才 park)⇒ `deny` 部署对名单工具同样当场拒。旧注「不经流内臂、不受本旋钮
@@ -2415,7 +2405,7 @@ export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled"
  *  三者都是 operator 在配置面写下的**治理声明**(与 autonomy/commandPolicy 同族),不是存储旋钮
  *  ——`retentionPolicy` 尤其容易被误归 store 组:它的消费点是 core 的启动期能力校验与将来的调度面,
  *  config 这一层它只是一句声明。 */
-export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "configCatalogEnabled" | "retentionPolicy" | "retentionSweep" | "operatorPrincipals" | "operatorSingleUser" | "serviceTokenActsForDeployment" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "authBridgeIssuer" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
+export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "configCatalogEnabled" | "retentionPolicy" | "retentionSweep" | "operatorPrincipals" | "operatorDrainPrincipals" | "operatorSingleUser" | "serviceTokenActsForDeployment" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "authBridgeIssuer" | "principalJwtMaxTtlSec" | "bindHost">;
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
 export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "sandboxGit" | "remoteExec" | "remoteExecHomeDir" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "hooksTimeoutMs" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentStallMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sandboxPkgSourceCustom" | "sessionAutoTitle" | "sessionAutoTitleSource" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspHostEnabled" | "lspEnvAllow" | "hookEnvAllow" | "autoBackgroundOnTimeout" | "imageBakes" | "readFace" | "readFaceSource" | "taskWriteFaceEscalation" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "readDenyFloorRequired" | "sandboxReadFloor" | "agentConfigDir" | "configLkgPath" | "configLkgEnabled">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */

package/dist/config.d.ts

@@ -3,6 +3,7 @@ import { type ConfigProviderWord } from "./config-types.js";
 import { type CenterEndpoint } from "./web-admin-client/center-request.js";
 import { type ExecutionLane } from "./execution-lane-caps.js";
 import { type Autonomy } from "./runtime-governance.js";
+import { type EntryProblemReason } from "./entry-problems.js";
 import { type RunnerEnvNameAllowlistKnob, type ServerEnvNameAllowlistKnob } from "./env-name-allowlist-knobs.js";
 import type { ServiceConfig, LoadedConfig, RemoteExecConfig, ServiceConfigFlat, ServiceConfigGroups } from "./config-types.js";
 /** [ref] A1: the config TYPE face lives in the leaf module config-types.ts; re-exported here so
@@ -61,9 +62,9 @@ export declare function parseNumOrFail(name: string, raw: string | undefined): n
  */
 export declare function parseNumOrFailNonNegative(name: string, raw: string | undefined): number;
 /** Optional FAIL-SAFE numeric env for an OPTIONAL feature knob: a non-numeric / non-positive value yields `undefined`
- *  (the caller falls back to its own default) rather than NaN OR a hard startup throw. Used for SESSION_SNAPSHOT_TTL_SEC
- *  (finding 20): a typo like "600s" must NOT sign every presigned URL with X-Amz-Expires=NaN (total snapshot outage),
- *  but ALSO must not crash boot of an unrelated subsystem — degrade to the MinioBlobBackend default. */
+ *  (the caller falls back to its own default) rather than NaN OR a hard startup throw. A presigned-URL lifetime is not such a
+ *  knob: its spelling is judged by `presignLifetimeSpelled` and a non-decimal one does not load (a typo there must neither sign
+ *  `X-Amz-Expires=NaN` nor a `Number()` reading of what the operator wrote). */
 /** S20 (SILENT-FALLBACK P1): soft-knob parse rejects, collected here because config parsing runs BEFORE the
  *  logger exists. main.ts drains this once after createLogger and warns per entry ("configured X=raw is
  *  invalid, using the default"). Module-level on purpose; drain clears it (repeat loadConfig in tests is fine). */
@@ -387,9 +388,10 @@ export interface UnmatchableToolName {
     guidance: string;
     /**
      * 这一条为什么永远不生效 —— 机读位的 `reason`(`entry-problems.ts`):引擎名字判官的判词 `retired` / `unmintable_segment` / `unprefixed_namespace`、引擎规则文法的码原样(`invalid.*` /
-     * `unsupported.*`)、近似名 `near_miss`、名表消费者的 CC 规则形 `cc_rule_form`。句子里的 `guidance` 给人读,本字给机器读;两者在同一处同时铸。
+     * `unsupported.*`)、近似名 `near_miss`、名表消费者的 CC 规则形 `cc_rule_form`(本仓自铸,取闭集 `CC_RULE_FORM`)。句子里的 `guidance` 给人读,本字给机器读;两者在同一处同时铸。
+     * 型 = 条目问题 `reason` 的全部词表之并({@link EntryProblemReason}):这里写一个哪张表都没有的词 = tsc 红。
      */
-    reason: string;
+    reason: EntryProblemReason;
 }
 /**
  * [ref](core 7.9.0 [ref])—— **这条名单条目喂给谁**,决定「永不匹配」这句话怎么判。三个消费者形态:

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,6 +46,7 @@ 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";
@@ -494,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 === "")
@@ -1036,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"),
@@ -1050,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,
     };
@@ -1363,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;
             }
         }
@@ -1419,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"),
@@ -1443,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)`);
     }
@@ -2021,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),
@@ -2031,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),
@@ -2662,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",
@@ -2761,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)),
         },
     };
 }
@@ -2836,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,
@@ -2855,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/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

@@ -121,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;
@@ -438,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;

package/dist/elicitation.js

@@ -6,7 +6,7 @@ import { refusalBody } from "./http/refusal-body.js";
 import { keyAdmits, ownerCellOf, recoveredSubject } from "./owner-faces.js";
 import { createHitlOpenRace } from "./hitl-delivery.js";
 const MAX_ELICIT_MESSAGE_CHARS = 4096;
-const MAX_ELICIT_SCHEMA_BYTES = 8192;
+const MAX_ELICIT_SCHEMA_CHARS = 8192;
 const RELEASE_ACTION = { refused: "decline", unanswered: "cancel" };
 export const DEFAULT_ELICITATION_THROTTLE = {
     maxConcurrentPerRun: 2,
@@ -42,7 +42,7 @@ function boundSchema(schema) {
         return undefined;
     const redacted = redactDeep(schema);
     try {
-        if (JSON.stringify(redacted).length > MAX_ELICIT_SCHEMA_BYTES)
+        if (JSON.stringify(redacted).length > MAX_ELICIT_SCHEMA_CHARS)
             return undefined;
     }
     catch {