@sema-agent/server 7.145.0 → 7.146.0

package/dist/config.d.ts

@@ -502,11 +502,16 @@ export declare function parseCapEnv(name: string, raw: string | undefined): {
  * 这里**不改解析**(让配置根跟着 `LOCAL_DATA_ROOT` 走,会让现有部署的 config.d 当场失踪 —— 代价比
  * 分家本身大得多)。只回一个「分家了,两个根分别是什么」的事实,由 boot 期打告警,合一旋钮 = `CONFIG_LOCAL_DIR`。
  *
- * @returns 分家时回两个根;一致(或已被 CONFIG_LOCAL_DIR/AGENT_DATA_DIR 统一)时回 undefined。
+ * 判的是「**一声不响**的分家」,不是「两个根不同」:合一旋钮一旦给出就是运维表过的态 —— `CONFIG_LOCAL_DIR`
+ * 等于数据根 = 合一,不等 = 有意分家,两者都不报。只有配置根是**推导**来的(`AGENT_DATA_DIR` / 家目录缺省)
+ * 且 ≠ 数据根,才可能是没人表过态的分家 ⇒ 报。
+ *
+ * @returns 一声不响的分家时回两个根;一致、或 `CONFIG_LOCAL_DIR` 显式在场(等 = 合一,不等 = 有意分家)时回 undefined。
  */
 export declare function splitLocalRoots(a: {
     /** optional:类型上可缺席(config-types 里是 `localDataRoot?`)——缺席时无从比较,判为不分家。 */
     localDataRoot: string | undefined;
+    /** `CONFIG_LOCAL_DIR`(`loadConfig` 已把空串归为缺席):在场 ⇒ 运维用合一旋钮表过态,本函数不再判。 */
     configLocalDir: string | undefined;
     agentDataDir: string | undefined;
     home: string;

package/dist/config.js

@@ -3,7 +3,7 @@ import { DEFAULT_AT_MENTION, DEFAULT_MODEL_REF, mintCapabilityKeys } from "./mod
 import { homedir } from "node:os";
 import { isAbsolute, join, posix as posixPath } from "node:path";
 import { fileURLToPath } from "node:url";
-import { compileAllowList, inheritEnvPolicyProblem, BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES, compileReadDeny, resolveReadDenyBuiltins, isModelPriced, PROTOCOL_TABLE, RECOMMENDED_SENSITIVE_PATTERNS, judgeRuleToolName, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules, WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, principalInboxConsumerOf, carriesCredential } from "@sema-agent/core";
+import { compileAllowList, inheritEnvPolicyProblem, BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES, compileReadDeny, resolveReadDenyBuiltins, isModelPriced, PROTOCOL_TABLE, RECOMMENDED_SENSITIVE_PATTERNS, judgeRuleToolName, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules, WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, principalInboxConsumerOf, carriesCredential, isReplicableScope } from "@sema-agent/core";
 import { ROSTER_PRIMARY_ROLES, ROSTER_CHEAP_ROLES, WEB_ADMIN_ENV, retiredEnvRefusal, stripControlAndBidi } from "@sema-agent/settings-schema";
 import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
@@ -16,6 +16,7 @@ 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 { parseTrustedProxyCidr } from "./net-address.js";
 import { DEVICE_HELLO_ACK_BOUNDS } from "./device-ws-protocol.js";
 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";
@@ -59,6 +60,7 @@ 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";
+import { ADOPTION_IMPORT_MAX_SESSIONS_DEFAULT, ADOPTION_IMPORT_MAX_SESSIONS_FLOOR, ADOPTION_IMPORT_MAX_SESSION_BYTES_CEILING, ADOPTION_IMPORT_MAX_SESSION_BYTES_DEFAULT, ADOPTION_IMPORT_MAX_SESSION_BYTES_FLOOR } from "./adoption/import-limits.js";
 import { buildDeclaredEngineWithoutCoordinatesRefusal, missingSqlCoordinateKeys } from "./sql-engine-coordinates.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
@@ -274,6 +276,11 @@ function clampEnvWithWarn(name, fallback, min, max = Number.POSITIVE_INFINITY) {
         CONFIG_WARNINGS.push({ env: name, raw: env(name, fallback), used: String(used), kind: "clamped" });
     return used;
 }
+function countEnvClamped(name, fallback, min, max = Number.POSITIVE_INFINITY) {
+    if (!Number.isInteger(numEnv(name, String(fallback))))
+        throw new Error(`env ${name}=${env(name, String(fallback))} must be a whole number (it is a count)`);
+    return clampEnvWithWarn(name, String(fallback), min, max);
+}
 function numEnvOr(name, fallback) {
     const raw = process.env[name];
     if (raw === undefined || raw === "")
@@ -439,6 +446,19 @@ function parseDevicePreAuthPerRemoteEnv() {
     }
     return n;
 }
+function parseDeviceTrustedProxyCidrsEnv(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    const items = raw.split(",").map((item) => item.replace(/^[ \t]+|[ \t]+$/g, ""));
+    return items.map((item, i) => {
+        const r = parseTrustedProxyCidr(item);
+        if (r.ok)
+            return r.text;
+        throw new Error(`env DEVICE_TRUSTED_PROXY_CIDRS item ${i + 1} of ${items.length} (${JSON.stringify(item)}) ${r.flaw}. ` +
+            `This list names the reverse proxies whose X-Forwarded-For the device pre-auth cap trusts — list only your own proxies, comma-separated ` +
+            `(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 parseFileHistoryRetention() {
     const raw = process.env.FILE_HISTORY_RETENTION_KEEP;
     if (raw === undefined || raw === "")
@@ -1590,19 +1610,30 @@ function parentPidEnv() {
     return { parentPid: n };
 }
 const ENGINE_LINGER_FLOOR_MS = 1_000;
+const ENGINE_HANDOVER_LINGER_FLOOR_MS = 60_000;
 const ENGINE_LINGER_CEIL_MS = 24 * 60 * 60 * 1_000;
-function lingerMsEnv(name, raw, defaultMs, disableHint) {
+function engineWindowZeroSentence(zero) {
+    switch (zero.kind) {
+        case "refused":
+            return `There is no "disable" value here — ${zero.disableHint}`;
+        case "noGrace":
+            return `the literal "0" is the one value below the floor accepted here — ${zero.offHint}`;
+    }
+}
+function lingerMsEnv(name, raw, defaultMs, floorMs, zero) {
     if (raw === undefined || raw.trim() === "")
         return defaultMs;
+    if (zero.kind === "noGrace" && raw.trim() === "0")
+        return 0;
     const n = parseNumOrFail(name, raw);
-    if (!Number.isSafeInteger(n) || n < ENGINE_LINGER_FLOOR_MS || n > ENGINE_LINGER_CEIL_MS) {
+    if (!Number.isSafeInteger(n) || n < floorMs || n > ENGINE_LINGER_CEIL_MS) {
         throw new Error(`env ${name}="${raw}" must be an INTEGER number of MILLISECONDS in ` +
-            `[${ENGINE_LINGER_FLOOR_MS}, ${ENGINE_LINGER_CEIL_MS}] (1s … 24h) — it is how long ` +
+            `[${floorMs}, ${ENGINE_LINGER_CEIL_MS}] (${floorMs / 1_000}s … 24h) — it is how long ` +
             `"nobody attached, no run in flight, no HTTP touch" must hold CONTINUOUSLY before the engine self-exits. ` +
             `A value like "60" is the seconds-for-milliseconds slip: a 60ms window kills the engine inside a shell's own ` +
             `restart gap. A value like "1e100" passes a naive "is it a positive integer" check but the elapsed clock can ` +
             `NEVER reach it, which silently turns self-exit off while looking configured. ` +
-            `There is no "disable" value here — ${disableHint}`);
+            engineWindowZeroSentence(zero));
     }
     return n;
 }
@@ -1757,6 +1788,10 @@ function parseMemoryDomain(ctx) {
         if (scope === undefined) {
             throw new Error("MEMORY_SYNC_URL is set but no sync scope is derivable (memory engine off or multi-tenant without an explicit scope) — set MEMORY_SYNC_SCOPE, or run the single-user file memory engine with a typed MEMORY_SCOPE (e.g. user:<tenant>) so it provides one");
         }
+        if (!isReplicableScope(scope)) {
+            throw new Error(`${memorySyncScopeRaw !== undefined ? "MEMORY_SYNC_SCOPE" : "MEMORY_SCOPE"} names a userlocal: memory layer as the sync layer — that layer family never leaves the store it is written in ` +
+                "(the engine refuses to sync it before any read or request), so this sync leg would fail every round. Set MEMORY_SYNC_SCOPE to a layer that may be replicated, or unset MEMORY_SYNC_URL.");
+        }
         if (carriesCredential(scope)) {
             throw new Error(`${memorySyncScopeRaw !== undefined ? "MEMORY_SYNC_SCOPE" : "MEMORY_SCOPE"} (the memory sync layer's name) holds a credential-shaped part — the layer name travels verbatim in every sync request path and report, so it is refused, never cleaned: rename the layer`);
         }
@@ -1915,6 +1950,7 @@ function parseAuthDomain(ctx) {
         ...parseGovernanceDeclarations(),
         operatorPrincipals: csv("OPERATOR_PRINCIPALS"),
         operatorSingleUser: boolEnv("OPERATOR_SINGLE_USER", false),
+        serviceTokenActsForDeployment: boolEnv("SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT", true),
         configCatalogEnabled: boolEnv("CONFIG_CATALOG_ENABLED", true),
         principalJwtPubkeys,
         principalJwtIss,
@@ -2062,6 +2098,7 @@ function parseOrchestrationDomain(ctx) {
                                                                 ...((n) => (n !== undefined ? { maxInflightPerDevice: n } : {}))(parseDeviceBoundedIntEnv("DEVICE_MAX_INFLIGHT_PER_DEVICE", process.env.DEVICE_MAX_INFLIGHT_PER_DEVICE, DEVICE_HELLO_ACK_BOUNDS.maxInflight)),
                                                                 ...((n) => (n !== undefined ? { maxPreAuthPerRemote: n } : {}))(parseDevicePreAuthPerRemoteEnv()),
                                                                 ...((n) => (n !== undefined ? { enrollTokenTtlSec: n } : {}))(parseDeviceEnrollTokenTtlEnv()),
+                                                                ...((n) => (n !== undefined ? { trustedProxyCidrs: n } : {}))(parseDeviceTrustedProxyCidrsEnv(process.env.DEVICE_TRUSTED_PROXY_CIDRS)),
                                                                 relay: parseDeviceRelayUrlEnv(process.env.DEVICE_RELAY_URL),
                                                                 ...(process.env.DEVICE_SUPERSEDE ? { supersede: enumEnv("DEVICE_SUPERSEDE", "stale_only", ["stale_only", "deny"]) } : {}),
                                                             }
@@ -2158,6 +2195,8 @@ function parseLimitsHttpDomain() {
             ? { attachmentMimeAllowlist: csv("ATTACHMENT_MIME_ALLOWLIST").map((s) => s.toLowerCase()) }
             : {}),
         attachmentUnboundTtlMs: clampEnvWithWarn("ATTACHMENT_UNBOUND_TTL_MS", String(24 * 3600 * 1000), LIMITS_HTTP_FLOORS.attachmentUnboundTtlMs),
+        adoptionImportMaxSessions: countEnvClamped("ADOPTION_IMPORT_MAX_SESSIONS", ADOPTION_IMPORT_MAX_SESSIONS_DEFAULT, ADOPTION_IMPORT_MAX_SESSIONS_FLOOR),
+        adoptionImportMaxSessionBytes: countEnvClamped("ADOPTION_IMPORT_MAX_SESSION_BYTES", ADOPTION_IMPORT_MAX_SESSION_BYTES_DEFAULT, ADOPTION_IMPORT_MAX_SESSION_BYTES_FLOOR, ADOPTION_IMPORT_MAX_SESSION_BYTES_CEILING),
         infraCostRates: {
             toolCallMicroUsd: clampEnvWithWarn("INFRA_COST_TOOL_CALL", "0", 0),
             sandboxSecMicroUsd: clampEnvWithWarn("INFRA_COST_SANDBOX_SEC", "0", 0),
@@ -2173,9 +2212,23 @@ function parseLimitsHttpDomain() {
         sighupIdleGraceMs: clampEnvWithWarn("SIGHUP_IDLE_GRACE_MS", String(120_000), 5_000),
         ...parentPidEnv(),
         engineAutoExit: boolEnv("ENGINE_AUTO_EXIT", false),
-        engineLingerMs: lingerMsEnv("ENGINE_LINGER_MS", process.env.ENGINE_LINGER_MS, 60_000, "set ENGINE_AUTO_EXIT=false to turn self-exit off entirely."),
-        engineOrphanLingerMs: lingerMsEnv("ENGINE_ORPHAN_LINGER_MS", process.env.ENGINE_ORPHAN_LINGER_MS, 2_000, "this window only applies once the SEMA_PARENT_PID process is gone — unset SEMA_PARENT_PID to stop watching the parent at all."),
+        engineLingerMs: lingerMsEnv("ENGINE_LINGER_MS", process.env.ENGINE_LINGER_MS, 60_000, ENGINE_LINGER_FLOOR_MS, { kind: "refused", disableHint: "set ENGINE_AUTO_EXIT=false to turn self-exit off entirely." }),
+        engineOrphanLingerMs: lingerMsEnv("ENGINE_ORPHAN_LINGER_MS", process.env.ENGINE_ORPHAN_LINGER_MS, 2_000, ENGINE_LINGER_FLOOR_MS, {
+            kind: "refused",
+            disableHint: "this window only applies once the SEMA_PARENT_PID process is gone — unset SEMA_PARENT_PID to stop watching the parent at all.",
+        }),
+        engineFirstAttachMs: lingerMsEnv("ENGINE_FIRST_ATTACH_MS", process.env.ENGINE_FIRST_ATTACH_MS, 180_000, ENGINE_LINGER_FLOOR_MS, {
+            kind: "noGrace",
+            offHint: "it means no extra grace before the first non-probe request (the window is then ENGINE_LINGER_MS, as before this knob existed); " +
+                "set ENGINE_AUTO_EXIT=false to turn self-exit off entirely.",
+        }),
+        engineHandoverLingerMs: lingerMsEnv("ENGINE_HANDOVER_LINGER_MS", process.env.ENGINE_HANDOVER_LINGER_MS, 1_800_000, ENGINE_HANDOVER_LINGER_FLOOR_MS, {
+            kind: "refused",
+            disableHint: "this window only applies after a shell hands the engine over (POST /v1/engine/handover) — a shell that never does so never uses it; set ENGINE_AUTO_EXIT=false and unset SEMA_PARENT_PID to turn self-exit off entirely.",
+        }),
         rateLimitPerMin: numEnv("RATE_LIMIT_RPM", "0"),
+        runMaxConcurrent: nonNegativeIntEnv("RUN_MAX_CONCURRENT", "在飞 run 全局并发帽"),
+        runMaxConcurrentPerPrincipal: nonNegativeIntEnv("RUN_MAX_CONCURRENT_PER_PRINCIPAL", "按主体在飞 run 并发帽"),
         maxTaskCostUsd: numEnv("MAX_TASK_COST_USD", "0"),
         maxTaskTokens: numEnv("MAX_TASK_TOKENS", "0"),
         maxPrincipalCostUsd: numEnv("MAX_PRINCIPAL_COST_USD", "0"),
@@ -2484,7 +2537,7 @@ const MEMORY_GROUP_KEYS = [
 const AUTH_GROUP_KEYS = [
     "authToken", "authTokens", "allowUnauthedWrites", "corsOrigins", "principalHeader", "requirePrincipal", "autonomy",
     "commandPolicy", "compliancePosture", "lockedConfigKeys", "retentionPolicy", "retentionSweep",
-    "operatorPrincipals", "operatorSingleUser", "configCatalogEnabled", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
+    "operatorPrincipals", "operatorSingleUser", "serviceTokenActsForDeployment", "configCatalogEnabled", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
     "principalJwtMaxTtlSec", "authBridgeIssuer", "bindHost", "bindHostSource",
 ];
 const ORCHESTRATION_GROUP_KEYS = [
@@ -2501,8 +2554,9 @@ const ORCHESTRATION_GROUP_KEYS = [
 const LIMITS_HTTP_GROUP_KEYS = [
     "port", "attachmentOrphanGraceMs", "workspaceFileMaxBytes", "attachmentMaxBytes", "attachmentMimeAllowlist",
     "attachmentUnboundTtlMs", "infraCostRates", "drainGraceMs", "drainSecondSignalMinGapMs", "sighupIdleGraceMs", "parentPid",
-    "engineAutoExit", "engineLingerMs", "engineOrphanLingerMs",
-    "rateLimitPerMin", "maxTaskCostUsd",
+    "engineAutoExit", "engineLingerMs", "engineOrphanLingerMs", "engineFirstAttachMs", "engineHandoverLingerMs",
+    "rateLimitPerMin", "runMaxConcurrent", "runMaxConcurrentPerPrincipal", "maxTaskCostUsd",
+    "adoptionImportMaxSessions", "adoptionImportMaxSessionBytes",
     "maxTaskTokens", "maxPrincipalCostUsd", "costQuotaWindowSec", "reapIntervalSec", "runStaleSec", "toolResultTtlSec",
 ];
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
@@ -2729,7 +2783,9 @@ export function parseCapEnv(name, raw) {
     return { value: n };
 }
 export function splitLocalRoots(a) {
-    const configRoot = a.configLocalDir ?? a.agentDataDir ?? join(a.home, ".ai-agent");
+    if (a.configLocalDir !== undefined)
+        return undefined;
+    const configRoot = a.agentDataDir ?? join(a.home, ".ai-agent");
     if (!a.localDataRoot || a.localDataRoot === configRoot)
         return undefined;
     return { dataRoot: a.localDataRoot, configRoot };

package/dist/deleted-session-ids.d.ts

@@ -0,0 +1,19 @@
+import type { DeploymentShapeInput } from "./deployment-shape.js";
+/** 表的条数上限(一条约百字节量级)。引擎的会话暂存自己按会话数有上限(超了整会话驱逐最旧);本表的上限比它宽得多。 */
+export declare const DELETED_SESSION_ID_CAP = 50000;
+/**
+ * **铸点**(唯一):本进程的在线删除协调器在删除会话本体之前记一笔 —— 围栏先立,id 才空出来。删除随后失败也无害:
+ * 这一笔只拒「别的属主」,而会话还在时别的属主本来就用不了它。
+ * 同一只 id 再删一次:这一次的删前属主对已记的每一位都等价(同一只等价律判)⇒ 收进集合(前几位一位不丢 —— 等价律有方向、不传递,只记最新一位会让
+ * 「哨兵删 → 无主重登再删 → `default` 用」绕过「哨兵 ≢ `default`」);对某一位不等价 ⇒ 记成「谁都不是」。后一次删除从不覆盖前一位(前一位的暂存仍可能在本进程)。
+ * `deployment` = 部署形(等价律的窄互认臂读它;调用方递 `ServiceConfig` 整份)。
+ */
+export declare function retireSessionId(sessionId: string, owner: string | null, deployment: DeploymentShapeInput<"principal">): void;
+/**
+ * **读点**(唯一;执行上下文解析器 `http/execution-context.ts` 步 ① 调):这只 id 在本进程被删过、而删前的属主不是 `owner` ⇒ `true`(解析器拒)。
+ * `owner` = 这条执行要服务的属主(根会话行上那一读的住客);`undefined` = 判不出 ⇒ 删过就为真(fail-closed)。
+ * 同一位 = 对**每一位**删前属主,会话属主等价律 `sameSessionOwner(deployment, 删前属主, owner)` 都成立(删前属主是行上记下的那一格,本次住客是这一次的调用方);
+ * 被互不等价的属主各删过一次的 id 对谁都为真。
+ */
+export declare function sessionIdRetiredFor(sessionId: string, owner: string | null | undefined, deployment: DeploymentShapeInput<"principal">): boolean;
+//# sourceMappingURL=deleted-session-ids.d.ts.map

package/dist/deleted-session-ids.js

@@ -0,0 +1,26 @@
+import { recordFailOpen } from "./observability/fail-open.js";
+import { sameSessionOwner } from "./security.js";
+export const DELETED_SESSION_ID_CAP = 50_000;
+const DELETED_UNDER_SEVERAL = Symbol("deleted under several owners");
+const formerOwners = new Map();
+export function retireSessionId(sessionId, owner, deployment) {
+    const prior = formerOwners.get(sessionId);
+    const recorded = prior === undefined ? [owner] : sessionIdRetiredFor(sessionId, owner, deployment) ? DELETED_UNDER_SEVERAL : prior === DELETED_UNDER_SEVERAL || prior.includes(owner) ? prior : [...prior, owner];
+    formerOwners.delete(sessionId);
+    formerOwners.set(sessionId, recorded);
+    if (formerOwners.size <= DELETED_SESSION_ID_CAP)
+        return;
+    const oldest = formerOwners.keys().next().value;
+    if (oldest !== undefined)
+        formerOwners.delete(oldest);
+    recordFailOpen("server.session-id-tombstone.evicted", `cap=${DELETED_SESSION_ID_CAP}`);
+}
+export function sessionIdRetiredFor(sessionId, owner, deployment) {
+    const former = formerOwners.get(sessionId);
+    if (former === undefined)
+        return false;
+    if (owner === undefined || former === DELETED_UNDER_SEVERAL)
+        return true;
+    return !former.every((f) => sameSessionOwner(deployment, f, owner));
+}
+//# sourceMappingURL=deleted-session-ids.js.map

package/dist/deploy-facts.d.ts

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

package/dist/deploy-facts.js

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

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

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