@sema-agent/server 7.52.0 → 7.53.0

package/dist/config.d.ts

@@ -1,10 +1,10 @@
 import { type Model } from "@sema-agent/core";
 import type { Autonomy } from "./runtime-governance.js";
 import type { ServiceConfig, ServiceConfigFlat, ServiceConfigGroups } from "./config-types.js";
-/** design/158 A1: the config TYPE face lives in the leaf module config-types.ts; re-exported here so
+/** [ref] A1: the config TYPE face lives in the leaf module config-types.ts; re-exported here so
  *  every existing `from "./config.js"` importer compiles unchanged (pure-type consumers should prefer
  *  importing config-types.js directly — a type-only leaf, no loader baggage). */
-export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat, ServiceConfigGroups, ServiceStoreConfig, ServiceModelPlaneConfig, ServiceApprovalConfig, ServiceMemoryConfig, ServiceAuthConfig, ServiceOrchestrationConfig, ServiceLimitsHttpConfig, ServiceObservabilityConfig, ServiceIntegrationsConfig, MemoryEmbedderConfig, // #228:embedder 坐标(plugins/memory-embedder.ts 消费同一属主类型)
+export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat, ServiceConfigGroups, ServiceStoreConfig, ServiceModelPlaneConfig, ServiceApprovalConfig, ServiceMemoryConfig, ServiceAuthConfig, ServiceOrchestrationConfig, ServiceLimitsHttpConfig, ServiceObservabilityConfig, ServiceIntegrationsConfig, MemoryEmbedderConfig, // [ref]:embedder 坐标(plugins/memory-embedder.ts 消费同一属主类型)
 A2aServeConfig, A2aServeSkill, RetentionMode, RetentionSweepConfig, MemoryConsolidationDriverConfig, } from "./config-types.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 /** Parse the AUTONOMY env into a validated autonomy mode. Unset/empty → undefined (unmanaged → no extra
@@ -13,13 +13,21 @@ export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config
  *  config overlay (config-center/facade.ts `applyRuntimeHot`) can re-derive the ENV BASELINE to revert to when center
  *  stops managing `autonomy` (a stale center override must not stick — see applyRuntimeHot). */
 export declare function parseAutonomy(raw: string | undefined): Autonomy | undefined;
-/** design/166-T1 — parse `USAGE_WINDOWS`(单键 JSON 数组;逐窗散键在窗数可变时组合爆炸,JSON 是唯一
+/** [ref]-T1 — parse `USAGE_WINDOWS`(单键 JSON 数组;逐窗散键在窗数可变时组合爆炸,JSON 是唯一
  *  封闭形)。unset/空串 → undefined(关)。fail-loud 族(numEnv 同纪律):坏 JSON/非数组/空数组/
- *  非正有限整数/未知 anchor 全部 boot throw 点名——「设了但无意义」静默关掉=部署方以为有治理实际没有。
- *  server 严于 core(core 允 maxTokens=0=恒拒锅;这里要求正整数,0 配置显然是笔误不是意图)。 */
+ *  坏值/未知 anchor 全部 boot throw 点名——「设了但无意义」静默关掉=部署方以为有治理实际没有。
+ *  [ref](core 7.0.0 `UsageWindow.maxCostUsd`,dist/core/usage-window-store.d.ts:44-68 亲读):
+ *  `maxTokens` 与 `maxCostUsd` 是两只**独立** ceiling——each optional on its own、**at least one
+ *  required**(双缺=拒:a window with neither admits nothing it can govern),whichever fills first
+ *  即耗尽;缺席的 ceiling 不参与(非 0、非 ∞)。修前这里的白名单重铸只认三键,$ 键配了也被静默
+ *  剥掉——正是本函数要消灭的那族病自己。
+ *  server 严于 core(core 允两 ceiling 取 0=恒满锁死窗;这里都要求正数,0 配置显然是笔误不是意图);
+ *  `maxCostUsd` 另提前执行 core 的 micro-USD 门(×1e6 仍有限——超界 ceiling 在账本单位里读作 ∞,
+ *  「看起来被治理、实际什么都不拦」,core 在门口拒,这里拒在 boot)。 */
 export declare function parseUsageWindows(raw: string | undefined): readonly {
     windowMs: number;
-    maxTokens: number;
+    maxTokens?: number;
+    maxCostUsd?: number;
     anchor: "first-use" | "rolling";
 }[] | undefined;
 /** Numeric env with validation: a non-numeric value FAILS at startup instead of silently becoming `NaN`
@@ -56,7 +64,7 @@ export declare function parseNumOrFailNonNegative(name: string, raw: string | un
  *  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). */
 /**
- * #210(黑板 [3425]③):一条配置诊断的**种类**。
+ * [ref](黑板 [ref]③):一条配置诊断的**种类**。
  *
  * ⚠️ 为什么是显式 `kind` 而不是「`used` 在不在场」(codex 自审 R2-F1 真修):第一版拿可选字段当判别式,
  * 于是三件语义完全不同的事挤在两个出口上 —— 空串**保留原值**被报成「越界夹取」、坏值**回默认**因为带了
@@ -82,7 +90,7 @@ export declare function drainConfigNotices(): Array<{
     event: string;
     fields: Record<string, string>;
 }>;
-/** F10 (codex audit): drain + log BOTH pre-logger diagnostic collectors (S20 soft-knob warnings + [792]④ boot
+/** F10 (codex audit): drain + log BOTH pre-logger diagnostic collectors (S20 soft-knob warnings + [ref]④ boot
  *  notices) in one place. EVERY entrypoint that calls loadConfig() then builds a logger must call this right
  *  after (main.ts, run-local.ts) — a new entry that forgets it would silently drop operator-facing diagnostics
  *  (run-local historically did exactly that), so the drain lives beside the collectors, not in one entrypoint. */
@@ -91,7 +99,7 @@ export declare function logConfigDiagnostics(logger: {
     info?: (event: string, fields?: Record<string, unknown>) => void;
     debug?: (event: string, fields?: Record<string, unknown>) => void;
 }): void;
-/** design/158 N8/N9 — the BOOLEAN member of this module's env-parser family (`env`/`env2`/`numEnv`/
+/** [ref] N8/N9 — the BOOLEAN member of this module's env-parser family (`env`/`env2`/`numEnv`/
  *  `numEnvBounded`/`optFinitePositiveEnv`/`enumEnv`/`headerNameEnv`/`firstSetEnv`). Until now booleans were the
  *  one type parsed by a hand-written literal comparison at every single site, and that is exactly why the same
  *  `*_ENABLED` suffix grew FOUR incompatible polarities (opt-in `=== "true"`, opt-out `!== "false"`, the posture
@@ -122,7 +130,7 @@ export interface ConfigKnobRecord {
 }
 /** The registered boolean knobs, sorted by name — the data behind `logConfigDiagnostics`'s polarity table. */
 export declare function configKnobTable(): ConfigKnobRecord[];
-/** design/158 N8 (D-family) + server 3.0.0 墓碑 —— a knob whose CANONICAL name is positive (`X_ENABLED`,
+/** [ref] N8 (D-family) + server 3.0.0 墓碑 —— a knob whose CANONICAL name is positive (`X_ENABLED`,
  *  default ON) and whose retired negative name (`X_DISABLED`) is now a **fail-loud tombstone**.
  *
  *  Why the flip at all: `X_DISABLED !== "true"` is a double negative at the read site, so the four knobs that
@@ -130,7 +138,7 @@ export declare function configKnobTable(): ConfigKnobRecord[];
  *  without inverting twice in your head, and `projectMemoryDisabled` was the ONE negative boolean on a
  *  `ServiceConfig` that otherwise carries 16 positive `*Enabled`/`*Allowed` fields.
  *
- *  🔴 3.0.0([1989],clay 令「不做兼容」):旧名不再有兼容窗——**设了就拒启**。这个函数保留 legacy 形参
+ *  🔴 3.0.0([ref],clay 令「不做兼容」):旧名不再有兼容窗——**设了就拒启**。这个函数保留 legacy 形参
  *  不是为了继续读它,而正是为了**认出它在场并拒绝启动**(把墓碑放在唯一知道这对名字关系的地方)。
  *
  *  Resolution order:
@@ -149,12 +157,12 @@ export declare const configLkgEnabled: () => boolean;
 export declare const hostBackgroundShellEnabled: () => boolean;
 /** The `host` exec lane's spool-file stdio form; false ⇒ the pre-1.226 pipe fallback (read per exec). */
 export declare const hostExecSpoolEnabled: () => boolean;
-/** [818]① 1M dual-window (core 1.289 `Model.autoCompactTokens`): an EXPLICIT positive value wins (env
+/** [ref]① 1M dual-window (core 1.289 `Model.autoCompactTokens`): an EXPLICIT positive value wins (env
  *  `MODEL_AUTO_COMPACT_TOKENS` / center roster `autoCompactTokens`); else the **model-id table** applies —
  *  sonnet-5-family id ∧ contextWindow>=1e6 ⇒ 967000 (the faithful shape of CC's single-entry per-model
  *  config; a small-window sonnet is NOT derived — a field above the physical window is undefined core
  *  behavior); anything else ⇒ REMOVED (a spread-inherited value from a bigger-window base model would
- *  mis-trigger a small window). ⚠️ A-065 P2-6 rescinded the old `contextWindow>=1e6 ⇒ 967000` derivation:
+ *  mis-trigger a small window). ⚠️ [ref] P2-6 rescinded the old `contextWindow>=1e6 ⇒ 967000` derivation:
  *  it handed a sonnet-5-only constant to ANY 1M model with no corpus/upstream backing (the earlier note
  *  here claiming this was "the exact CC alignment core recommends embedders set" mis-read core's per-model
  *  advice as a width rule). Returns a discriminant so the env lane can turn the removed implicit value into
@@ -163,7 +171,7 @@ export declare const hostExecSpoolEnabled: () => boolean;
 export declare function applyAutoCompactWindow(m: Model, explicit?: number): "explicit" | "sonnet5" | "removed-1m" | "removed";
 /**
  * 一条工具名**永不匹配任何现役工具**的三种拼法,及其修正指引。审批/权限名单是 server 侧 ToolPolicy 的
- * RAW 逐字比对(canonicalToolName 折叠面已随 core 5.0.0 RB-476 退役),所以写错的名字不会报错、只会静默
+ * RAW 逐字比对(canonicalToolName 折叠面已随 core 5.0.0 [ref] 退役),所以写错的名字不会报错、只会静默
  * 不生效——对 deny/ask 名单而言这是**失守方向**(运维/客户端以为加了门,实际什么都没加)。
  *
  * 判据在此**单点成文**,三条腿共用(它们此前各自为政,拼法覆盖面不一致才是真缺口):
@@ -173,7 +181,7 @@ export declare function applyAutoCompactWindow(m: Model, explicit?: number): "ex
  *   ③ per-request 腿(`settings.permissions.{ask,deny}`,task-settings.ts)—— 该请求 422。
  *
  * 五种拼法:
- *   - CC 形规则条目(`Bash(ps:*)`/`Edit(src/**)`,#186 [3047]§七 装机实测):CC 的权限规则 DSL 写法。这些
+ *   - CC 形规则条目(`Bash(ps:*)`/`Edit(src/**)`,[ref] [ref]§七 装机实测):CC 的权限规则 DSL 写法。这些
  *     名单比的是**整串工具名**,带括号那串不是任何活工具的名字 ⇒ 永不匹配。指引=按命令名走
  *     `runtime.commandPolicy`,整条 shell 进门走 `MANUAL_MODE_SHELL_GATE=always`。判别式见
  *     {@link findCcRuleFormNames}(它同时是 `allow` 腿的**唯一**判据,见下方例外说明)。
@@ -183,19 +191,19 @@ export declare function applyAutoCompactWindow(m: Model, explicit?: number): "ex
  *     少一段同样永不匹配。旧判据「含 `__` 且 protocolOf 认不出」放过了这一族(前缀恰好认得出),从另一侧
  *     漏出去,失守方向与 `figma__x` 完全相同。
  *   - **core 的文法编不出来的串**(名字里带反斜杠、单条 >512 字符、空串):判词取自 core 自己的
- *     `validatePermissionRules`,见 {@link uncompilableRuleGuidance}。#359①(A-075.5)补齐 ——
+ *     `validatePermissionRules`,见 {@link uncompilableRuleGuidance}。[ref]①([ref])补齐 ——
  *     此前只有 `ask` 腿(经 `createPermissionRulePolicy` 的 throw)拒得出这一族,`deny` 静默 no-op。
  *
  * 已接受的权衡(与退役表墓碑同一条):部署自有工具真叫 `figma__x` 的极端形会被误拒——boot 期无 roster 可
  * 豁免,且失败响亮、指引明确,好过静默失守。
  *
- * 🔴 **三条腿的消费者现已全部认 covering**(#450 孪生修,[5246];此前本段记的「分家」已作废):
+ * 🔴 **三条腿的消费者现已全部认 covering**([ref] 孪生修,[ref];此前本段记的「分家」已作废):
  * core 的每一只 name-keyed policy(`createAllowDenyPolicy` / `createPermissionRulePolicy` /
  * `createApprovalPolicy`)都解 covering 拼法,而 operator 腿的消费者 `createDurableAskPolicy`
  * (`src/approval.ts`)自 core 5.60.1 的谓词根导出到货后,deny/neverAuto/require 三集合也改成
  * 「精确 ∪ covering」(同一只 `namespacedRuleNameCovers`)。于是本函数放行的
  * `<ns>__<server>__*` / `<ns>__<server>__<glob>` 在**每一条**腿上都是**真判**,不再是
- * 「放行进 no-op」—— 而那正是 #450 病形(`APPROVAL_DENY=mcp__figma__*` 判 allow)的根。
+ * 「放行进 no-op」—— 而那正是 [ref] 病形(`APPROVAL_DENY=mcp__figma__*` 判 allow)的根。
  *
  * ⚠️ 仍然拒的那一格,理由**换了**(别再照旧引「approval.ts 还不认」):`<ns>__<peer>` **两段形**
  * (`mcp__figma`)core 全家解成 covering,本函数判它「缺段」拒。挡它的不再是消费腿的能力,而是
@@ -213,23 +221,23 @@ export declare function findUnmatchableToolNames(names: readonly string[]): Unma
 /** {@link findUnmatchableToolNames} 的成句形——三条腿的文案同源(只有前缀/出口不同)。 */
 export declare function formatUnmatchableToolNames(source: string, bad: readonly UnmatchableToolName[]): string;
 /**
- * design/170 件B/C/D —— 三条**部署治理声明**的 env 解析(auth 域的一段,fail-loud 全在这里)。
+ * [ref] 件B/C/D —— 三条**部署治理声明**的 env 解析(auth 域的一段,fail-loud 全在这里)。
  *
  * 三条的词表真源都在 core(`ComplianceProfile` / `ComplianceCapability` / `LOCKED_KEY_REGISTRY`),本函数
  * 只负责「env 文本 → 闭集值」这一步,并且**每一步坏值都拒启**:这三根旋钮全在安全/治理轴上,一个静默
- * 不生效的档位或一个拼错的锁键,是「以为在管、其实没管」——比没配更贵(#210 A 档 + design/170 §3.4)。
+ * 不生效的档位或一个拼错的锁键,是「以为在管、其实没管」——比没配更贵([ref] A 档 + [ref] §3.4)。
  *
  * 半配也拒:`COMPLIANCE_ADDITIONAL_DENIES` 没有 profile 可收紧时是一句无处安放的话,静默丢掉它等于
  * 让 operator 以为多禁了一条(与 `MEMORY_EMBEDDER_*` 的半配拒启同族)。
  */
-/** #270 车2 —— sweep 节律的上界(秒)。`setInterval` 的 delay 是 32 位有符号毫秒(2^31-1);越界会被
+/** [ref] 车2 —— sweep 节律的上界(秒)。`setInterval` 的 delay 是 32 位有符号毫秒(2^31-1);越界会被
  *  Node **重置成 1ms**,理由与拒启判据见调用点。导出供判据与文档单点引用。 */
 export declare const RETENTION_SWEEP_INTERVAL_MAX_SEC: number;
 /** 域:limits+http(限额与 HTTP 面)—— 端口、附件/工作区体积与 TTL、成本与速率天花板、排空窗、回收周期。 */
 /**
- * #322:limitsHttp 组里**有下限**的三个数值旋钮的下限值 —— env 腿(夹取+点名)与 center 热腿(整批拒)
+ * [ref]:limitsHttp 组里**有下限**的三个数值旋钮的下限值 —— env 腿(夹取+点名)与 center 热腿(整批拒)
  * 共用同一组阈值。判据同源、**处置刻意不同**:env 值是既有部署的存量,夹取不打断服务;center 发布是一次
- * 显式且可重发的动作,拒绝才是有意义的反馈(#123 响亮拒)。
+ * 显式且可重发的动作,拒绝才是有意义的反馈([ref] 响亮拒)。
  */
 export declare const LIMITS_HTTP_FLOORS: {
     readonly attachmentMaxBytes: 1024;
@@ -249,7 +257,7 @@ export declare const CONFIG_GROUP_KEYS: {
  *  `loadConfig` 是主调用点;测试夹具(test/helpers/make-config.ts)构造 `ServiceConfigFlat` 后同样过它。 */
 export declare function attachConfigGroups(flat: ServiceConfigFlat): ServiceConfig;
 export declare function loadConfig(): ServiceConfig;
-/** 有效监听绑址([1934])。**显式 `BIND_HOST`/`HOST` 恒生效**(operator 保留在任何形下明示暴露的
+/** 有效监听绑址([ref])。**显式 `BIND_HOST`/`HOST` 恒生效**(operator 保留在任何形下明示暴露的
  *  权利);未显式时:**无鉴权写面 ⇒ 127.0.0.1**,其余 ⇒ undefined(Node 默认全接口,既有部署零影响)。
  *
  *  为什么缺省要自己收窄、而不是只加旋钮:桌面形的安全结论原本写着「safe ONLY because HOST is

package/dist/config.js

@@ -38,18 +38,38 @@ export function parseUsageWindows(raw) {
         parsed = JSON.parse(v);
     }
     catch (e) {
-        throw new Error(`env USAGE_WINDOWS is not valid JSON: ${String(e)} — expected e.g. [{"windowMs":18000000,"maxTokens":5000000,"anchor":"first-use"}]`);
+        throw new Error(`env USAGE_WINDOWS is not valid JSON: ${String(e)} — expected e.g. [{"windowMs":18000000,"maxTokens":5000000,"anchor":"first-use"}] or [{"windowMs":604800000,"maxCostUsd":25,"anchor":"rolling"}]`);
     }
     if (!Array.isArray(parsed) || parsed.length === 0) {
-        throw new Error(`env USAGE_WINDOWS must be a NON-EMPTY JSON array of {windowMs,maxTokens,anchor} (an empty array is a governance no-op nobody chose — unset the env to turn windows off)`);
+        throw new Error(`env USAGE_WINDOWS must be a NON-EMPTY JSON array of {windowMs, maxTokens?, maxCostUsd?, anchor} (an empty array is a governance no-op nobody chose — unset the env to turn windows off)`);
     }
     const out = parsed.map((w, i) => {
         const o = w;
         const posInt = (n) => typeof n === "number" && Number.isInteger(n) && n > 0;
-        if (typeof w !== "object" || w === null || !posInt(o.windowMs) || !posInt(o.maxTokens) || (o.anchor !== "first-use" && o.anchor !== "rolling")) {
-            throw new Error(`env USAGE_WINDOWS[${i}] is invalid: expected {windowMs: positive int ms, maxTokens: positive int, anchor: "first-use"|"rolling"} (got ${JSON.stringify(w)})`);
+        const posUsd = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 && Number.isFinite(n * 1e6);
+        if (typeof w !== "object" || w === null || !posInt(o.windowMs) || (o.anchor !== "first-use" && o.anchor !== "rolling")) {
+            throw new Error(`env USAGE_WINDOWS[${i}] is invalid: expected {windowMs: positive int ms, maxTokens?: positive int, maxCostUsd?: positive USD, anchor: "first-use"|"rolling"} (got ${JSON.stringify(w)})`);
         }
-        return Object.freeze({ windowMs: o.windowMs, maxTokens: o.maxTokens, anchor: o.anchor });
+        for (const k of Object.keys(w)) {
+            if (k !== "windowMs" && k !== "maxTokens" && k !== "maxCostUsd" && k !== "anchor") {
+                throw new Error(`env USAGE_WINDOWS[${i}] is invalid: unknown key \`${k}\` — the window shape is the CLOSED set {windowMs, maxTokens?, maxCostUsd?, anchor}; a misspelled ceiling (e.g. \`maxCostUSD\`) must not silently leave the deployment ungoverned (got ${JSON.stringify(w)})`);
+            }
+        }
+        if (o.maxTokens === undefined && o.maxCostUsd === undefined) {
+            throw new Error(`env USAGE_WINDOWS[${i}] is invalid: at least one ceiling is required — \`maxTokens\` (tokens) and/or \`maxCostUsd\` (absolute USD); a window with neither admits nothing it can govern (got ${JSON.stringify(w)})`);
+        }
+        if (o.maxTokens !== undefined && !posInt(o.maxTokens)) {
+            throw new Error(`env USAGE_WINDOWS[${i}] is invalid: \`maxTokens\` (when present) must be a positive integer (got ${JSON.stringify(w)})`);
+        }
+        if (o.maxCostUsd !== undefined && !posUsd(o.maxCostUsd)) {
+            throw new Error(`env USAGE_WINDOWS[${i}] is invalid: \`maxCostUsd\` (when present) must be a positive finite USD amount that stays finite in micro-USD (× 1e6) (got ${JSON.stringify(w)})`);
+        }
+        return Object.freeze({
+            windowMs: o.windowMs,
+            ...(o.maxTokens !== undefined ? { maxTokens: o.maxTokens } : {}),
+            ...(o.maxCostUsd !== undefined ? { maxCostUsd: o.maxCostUsd } : {}),
+            anchor: o.anchor,
+        });
     });
     return Object.freeze(out);
 }
@@ -252,6 +272,26 @@ function optNumEnvStrict(name) {
         return undefined;
     return parseNumOrFail(name, raw);
 }
+function parseDevicePreAuthPerRemoteEnv() {
+    const raw = process.env.DEVICE_MAX_PREAUTH_PER_REMOTE;
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (raw === "off")
+        return "off";
+    if (!/^[1-9]\d*$/.test(raw)) {
+        throw new Error(`env DEVICE_MAX_PREAUTH_PER_REMOTE=${JSON.stringify(raw)} must be a positive integer or the literal "off" — ` +
+            `a malformed cap would otherwise run as the default (8) while the operator believes their value is in force ` +
+            `(#210: deployment knobs never fall back silently). "0" is not a valid cap (it would refuse every device handshake); ` +
+            `use "off" to disable the per-remote layer explicitly (reverse-proxy / NAT deployments collapse source IPs, A-075.52).`);
+    }
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n)) {
+        throw new Error(`env DEVICE_MAX_PREAUTH_PER_REMOTE=${raw.length > 24 ? `${raw.slice(0, 24)}…(${raw.length} digits)` : raw} overflows the safe-integer range — ` +
+            `Number() would read it as ${n}, and a cap of Infinity silently disables the per-remote layer without taking the explicit "off" arm. ` +
+            `Use a value within Number.MAX_SAFE_INTEGER, or the literal "off".`);
+    }
+    return n;
+}
 function parseFileHistoryRetention() {
     const raw = process.env.FILE_HISTORY_RETENTION_KEEP;
     if (raw === undefined || raw === "")
@@ -1283,6 +1323,7 @@ function parseAuthDomain(ctx) {
         autonomy: parseAutonomy(process.env.AUTONOMY),
         ...parseGovernanceDeclarations(),
         operatorPrincipals: csv("OPERATOR_PRINCIPALS"),
+        configCatalogEnabled: boolEnv("CONFIG_CATALOG_ENABLED", true),
         principalJwtPubkeys,
         principalJwtIss,
         principalJwtAud,
@@ -1434,6 +1475,7 @@ function parseOrchestrationDomain(ctx) {
                                                                 ...((n) => (n !== undefined ? { reconnectGraceMs: n } : {}))(optNumEnvStrict("DEVICE_RECONNECT_GRACE_MS")),
                                                                 ...((n) => (n !== undefined ? { execTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_EXEC_TIMEOUT_MS")),
                                                                 ...((n) => (n !== undefined ? { maxInflightPerDevice: n } : {}))(optNumEnvStrict("DEVICE_MAX_INFLIGHT_PER_DEVICE")),
+                                                                ...((n) => (n !== undefined ? { maxPreAuthPerRemote: n } : {}))(parseDevicePreAuthPerRemoteEnv()),
                                                                 ...(process.env.DEVICE_SUPERSEDE ? { supersede: enumEnv("DEVICE_SUPERSEDE", "stale_only", ["stale_only", "deny"]) } : {}),
                                                             }
                                                             :
@@ -1725,7 +1767,7 @@ const MEMORY_GROUP_KEYS = [
 const AUTH_GROUP_KEYS = [
     "authToken", "authTokens", "allowUnauthedWrites", "corsOrigins", "principalHeader", "requirePrincipal", "autonomy",
     "commandPolicy", "compliancePosture", "lockedConfigKeys", "retentionPolicy", "retentionSweep",
-    "operatorPrincipals", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
+    "operatorPrincipals", "configCatalogEnabled", "principalJwtPubkeys", "principalJwtIss", "principalJwtAud",
     "principalJwtMaxTtlSec", "bindHost", "bindHostSource",
 ];
 const ORCHESTRATION_GROUP_KEYS = [

package/dist/degenerate-instrument.d.ts

@@ -3,7 +3,7 @@
  *
  * When a task fails with `errorCode === "output.degenerate"` (core 1.59), core hands back
  * `salvagedOutput` = the degenerate turn's text — **already tail-TRIMMED at the brain stream layer**.
- * 🔴 A-057.52 correction (this note used to claim "the **whole** text, good head + looped garbage tail";
+ * 🔴 [ref] correction (this note used to claim "the **whole** text, good head + looped garbage tail";
  * that was true of core 1.59 and false of every engine that ships `trimDegenerateTail` — verified against
  * the installed dist, not against JSDoc): on the main path `assemble-result` fills the seat from the same
  * final message the brain already trimmed, so what arrives here is `head + exactly ONE copy of the

package/dist/deployment-governance.d.ts

@@ -27,7 +27,7 @@ export interface PathAdjudication {
     /** 相对路径基准(core 的 `rootPath`)。缺席 ⇒ 相对形在真身那层判不了,补词法臂(见下)。 */
     readonly cwd?: string;
 }
-/** #152([2703] 案二):durable 部署上的 AskUserQuestion 门的活体面探针(QuestionCoordinator 的切面)。 */
+/** [ref]([ref] 案二):durable 部署上的 AskUserQuestion 门的活体面探针(QuestionCoordinator 的切面)。 */
 export interface LiveQuestionFace {
     hasLiveContext(): boolean;
 }
@@ -41,11 +41,11 @@ export interface DurableApprovalSeat {
     readonly onExempted?: DurableAskOptions["onExempted"];
 }
 /**
- * #152([2703] 案二):durable 部署上的 AskUserQuestion 门。活体面(QuestionCoordinator)缺席 ⇒ 原形
+ * [ref]([ref] 案二):durable 部署上的 AskUserQuestion 门。活体面(QuestionCoordinator)缺席 ⇒ 原形
  * `createDurableQuestionPolicy()`(恒 ask ⇒ 恒 durable park)。在场 ⇒ **判决时**按活流上下文分腿:
  * 活流腿(bg/SSE,coordinator.runWithContext 包裹且投递面此刻可达,ALS 判)allow——工具执行落到
  * RunnerDeps.onQuestion 的 coordinator,问正在 tail 流的活人;无活流腿(sync /v1/tasks、verify/cascade、
- * durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留(#166 后无活流腿放行执行
+ * durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留([ref] 后无活流腿放行执行
  * 也不会产出空答:coordinator 无 ALS ctx ⇒ 冻结 `{kind:"unavailable"}`(src/question.ts),永不悬挂;
  * park 仍是把问题送到人面前的唯一那条腿,正当性不变、只是反事实前提换了)。
  * 工具名字面量与 server.ts 的 pre-CAS 守卫同源("AskUserQuestion",core 未根导出常量)。
@@ -59,7 +59,7 @@ export declare function createDurableQuestionGate(live: LiveQuestionFace | undef
 /**
  * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 交叉复审 round1 finding 1,红先复现)。
  *
- * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,#165 裁定 1),而
+ * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,[ref] 裁定 1),而
  * `DeferredSandboxPathEnv.absolutePath` 对相对形一律报错。core 的 `canonicalizeTarget` 在
  * **absolutePath 失败**这一支不置 `unresolvedSymlink`,于是守卫策略走的是
  * 「判不了就弃权」的 `allow`(dist 亲读)。写门在场时这条腿被门的 `ask` 兜住;而
@@ -72,10 +72,10 @@ export declare function createDurableQuestionGate(live: LiveQuestionFace | undef
  *
  * 三条不可动的边界:
  *  · **绝对形一律弃权**(absolutePath 报错 ⇒ canon 失败且非 unresolvedSymlink ⇒ core 判 allow):
- *    绝对形归真身裁决那一层,#165「真身胜过名字」的裁定(域内良性软链名叫 `.ssh` 只 ask)不受影响。
+ *    绝对形归真身裁决那一层,[ref]「真身胜过名字」的裁定(域内良性软链名叫 `.ssh` 只 ask)不受影响。
  *  · **只会 deny,不会放行**:相对形自身拼写里出现的段,解析成绝对路径后仍在,所以词法命中即真命中;
  *    反过来一条名叫 `.env` 而真身良性的相对软链会被误 deny —— 方向是 fail-closed,与守卫集语义同向。
- *  · **覆盖面(2026-08-08 按 core 5.19.0 #108 校正;旧文见下方「历史」段)**:本层只在
+ *  · **覆盖面(2026-08-08 按 core 5.19.0 [ref] 校正;旧文见下方「历史」段)**:本层只在
  *    `ToolCallRequest.cwd` **缺席**那一形上说话。core 5.19.0 起每条路径解析型守卫按 `req.cwd ?? rootPath`
  *    解析写目标(dist `core/sensitive-path-policy.js`),而 `canonicalizeTarget` 拿到 baseCwd 后会先把
  *    相对形**拼成绝对形**再交给 env(dist `tools/fs/safety.js` 的 `baseCwd && !isAbsolutePathForm(...)`
@@ -89,12 +89,12 @@ export declare function createDurableQuestionGate(live: LiveQuestionFace | undef
  *
  *    📜 **历史(留档,别当现状读)**:2026-08-08 之前本层的覆盖面到「cwd 里的守卫段看不见」为止——
  *    本层把相对形挂在 `/` 上,而工具挂在 engine 活 cwd 上,`cd .git` 后 `Write("config")` 真写
- *    `<root>/.git/config` 而本层只看得到 `/config` ⇒ 弃权。design/181 刀3 的口径更正查明这条残余面
+ *    `<root>/.git/config` 而本层只看得到 `/config` ⇒ 弃权。[ref] 刀3 的口径更正查明这条残余面
  *    **不是沙箱 lane 局部的**:host 腿虽供了 `rootPath`,那也是装配期的静态值,一样追不上被 Bash `cd`
  *    就地改写的 `cwdRef.current`(run-local 端到端真复现:`cd .git/hooks` 后 `Write("pre-commit")` 真落盘)。
  *    当年判定属主是引擎那条缝(不是任何一条消费腿——在消费腿里自己拿静态 cwd 追 `cd`,是拿会漂的复制品
  *    追引擎的真值,本文件反复点名的病),并把两条钉写成「引擎缝落地后一起翻面」。**该缝即 core backlog
- *    #108,已在 5.19.0 到货**,两条钉按上述翻面完毕。另一条备选收口(守卫集开启即把沙箱 lane 相对写
+ *    [ref],已在 5.19.0 到货**,两条钉按上述翻面完毕。另一条备选收口(守卫集开启即把沙箱 lane 相对写
  *    一律 deny,有真受损方且无对应旋钮)因此作废,无需部署方拍板。
  */
 export declare class RelativeTargetLexicalEnv extends StubExecutionEnv {
@@ -105,7 +105,7 @@ export declare class RelativeTargetLexicalEnv extends StubExecutionEnv {
     exists(_path: string, _abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
 }
 /**
- * boot 期的守卫集**可编译性**门(#177 收口①,随 design/181 件一搬进本口 —— 三条消费腿同得)。
+ * boot 期的守卫集**可编译性**门([ref] 收口①,随 [ref] 件一搬进本口 —— 三条消费腿同得)。
  *
  * 守卫集的编译发生在**每个请求**上。core 的 `compilePatterns` 对「一个路径段都没有」的模式(`"/"`、
  * `"//"`)THROW,那条 throw 会变成**每一个任务一条 500**,且运维从错误里看不出是自己的 env 写错了。
@@ -126,7 +126,7 @@ export interface GateSeatView {
     readonly singleUserAutoAcceptBaseline: boolean;
 }
 /**
- * UNGATED 信号的**补偿**(design/181 件一收编 / 件三三腿同得)。
+ * UNGATED 信号的**补偿**([ref] 件一收编 / 件三三腿同得)。
  *
  * 审批基线铺开之后 core 的 `hasEffectAwareGate` 恒真,于是它那条 "write-capable hand tools are present
  * but UNGATED" 的 onError 不再触发(判据是 `policyLayers.length > 0`,prepare-task dist 亲读)。那条信号
@@ -136,12 +136,12 @@ export interface GateSeatView {
  * 判据(与信号消失的条件逐字互补):守卫集在场 ∧ 两条产**真**门的腿都不在场(durable 门关 ∧ 单用户
  * auto-accept 基线不适用)。三个量都是部署常量 ⇒ 消费腿在 boot 期说一次,不是每任务一次。
  *
- * ⚠️ 单一属主(design/181 件三):HTTP 腿与 run-local 腿共用本判据与文案。两处各写一份 = 一处改了另一处
+ * ⚠️ 单一属主([ref] 件三):HTTP 腿与 run-local 腿共用本判据与文案。两处各写一份 = 一处改了另一处
  * 没改,而两份都长得像对的 —— 那正是本文件存在的理由。
  */
 export declare function buildOnlySensitiveBaselineWarning(config: Pick<DeploymentGovernanceConfigView, "sensitiveWritePatterns">, seat: GateSeatView): OperatorWarning | undefined;
 /**
- * `applyRuntimeGovernance` 的 governance 实参预铸(design/181 件一)。
+ * `applyRuntimeGovernance` 的 governance 实参预铸([ref] 件一)。
  *
  * 键存在性 profile 逐字保持消费腿原样:`autonomy`/`commandPolicy` 恒在场(值可为 `undefined`),
  * `manualModeShellGate`/`sensitivePathPolicy` 按在场性条件展开 —— `applyRuntimeGovernance` 的
@@ -149,7 +149,7 @@ export declare function buildOnlySensitiveBaselineWarning(config: Pick<Deploymen
  */
 export declare function createDeploymentGovernanceInputs(config: DeploymentGovernanceConfigView, pathAdjudication: PathAdjudication): DeploymentGovernanceInputs;
 /**
- * 审批基线 —— `applyRuntimeGovernance` 那个 base 的 `toolPolicy` 座(design/181 件一)。**恒非
+ * 审批基线 —— `applyRuntimeGovernance` 那个 base 的 `toolPolicy` 座([ref] 件一)。**恒非
  * `undefined`**:治理层是 tighten-only 的叠加层,没有基线可叠时它自己也产不出「门在场」这件事。
  *
  * 两形:

package/dist/device-store.d.ts

@@ -29,7 +29,7 @@ export declare const DEVICE_ERROR_CODES: {
     /** 反枚举 404:设备不存在 **与** 设备不是你的,逐字节同形。 */
     readonly NOT_FOUND: "not_found.device";
 };
-/** {@link DEVICE_ERROR_CODES} 的值联合 —— 闭集(未知码 = 编译错误,#157 词表纪律)。 */
+/** {@link DEVICE_ERROR_CODES} 的值联合 —— 闭集(未知码 = 编译错误,[ref] 词表纪律)。 */
 export type DeviceErrorCode = (typeof DEVICE_ERROR_CODES)[keyof typeof DEVICE_ERROR_CODES];
 /**
  * 限流拒绝复用**既有**的通用码(`docs/ASSISTANT-WIRE-CONTRACT.md` 已收录,429)。
@@ -151,7 +151,7 @@ export declare function assertEnrollTokenHashShape(tokenHash: string): void;
 /**
  * 闭集列的**读侧**解码 —— 三个 `parse*` 是这些词表的唯一解码点(SQL 店读回的字符串必须经此)。
  *
- * 🔴 认不出的值 = **抛**,不是静默 cast(#157:安全轴的未知词是 fail-loud 而不是 fail-open)。
+ * 🔴 认不出的值 = **抛**,不是静默 cast([ref]:安全轴的未知词是 fail-loud 而不是 fail-open)。
  * 一行 `status='disabled'` 的设备如果被 `as DeviceStatus` 静默放行,准入链的 `status === "revoked"`
  * 判据就对它返回「不是吊销的」⇒ 一台被管理面停用的设备照常领活。写侧不可能产出这些值(入参是
  * TS 闭集),所以出现即「有人跳过本店直接写库」或「跨版本降级读新词」,两者都必须响亮。

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

@@ -31,7 +31,7 @@
  * ⚠️ 将来出现**第二个** upgrade 消费方时,这里要改成一张路由表 —— 两个 `server.on("upgrade")`
  * 监听器会**同时**收到每一次 upgrade,各自「不认就 404」会互相把对方的连接打死。
  *
- * ── 安全轴姿势(#157)────────────────────────────────────────────────────────────────────────────
+ * ── 安全轴姿势([ref])────────────────────────────────────────────────────────────────────────────
  * 未知帧型 / 坏形帧 / 世代不符 / pending 外 instructionId = **响亮拒 + 审计行**,没有一处空 catch,
  * 没有一处「认不出就当默认值」。审计写失败本身也是响亮的(logger.error + 计数),不是静默吞。
  */
@@ -75,7 +75,7 @@ export type DeviceDispatchInput = {
          *
          * 用途在 device lane 上是**保护型写原语**(`writeFileGuarded`/`writeFileExclusive`):它们的缺席被
          * core 读成「后端没有这个原语」并降级成非原子写,所以「铸的时候没有、下发的时候有了」= 一次静默的
-         * 保护降级(#157)。本座本身与语义无关,只做集合判断。
+         * 保护降级([ref])。本座本身与语义无关,只做集合判断。
          */
         refuseIfDeclared?: readonly DeviceInstructionKind[];
         /**
@@ -151,8 +151,10 @@ export interface DeviceWsHubOptions {
     chunkBufferMaxBytes?: number;
     /** codex R1-F3:本副本**未鉴权**连接的并发帽(超额在 upgrade 阶段就 503 拒)。 */
     maxPreAuthConnections?: number;
-    /** codex R1-F3:单来源地址的未鉴权连接并发帽。 */
-    maxPreAuthConnectionsPerRemote?: number;
+    /** codex R1-F3:单来源地址的未鉴权连接并发帽。[ref]([ref]):字面 `off` = 显式停用该层——
+     *  帽键是裸 remoteAddress,XFF 反代 / 公司 NAT 部署形把全员折叠成单键,这层从公平层退化成
+     *  「全员共享一份预算」;停层后全局帽(`maxPreAuthConnections`)照常兜底。 */
+    maxPreAuthConnectionsPerRemote?: number | "off";
 }
 export interface DeviceWsHub {
     /** 把 `GET /v1/device/ws` 的 upgrade 处理器挂到裸 `http.Server` 上。 */

package/dist/device-ws-hub.js

@@ -735,9 +735,15 @@ export function createDeviceWsHub(options) {
             if (draining || closed)
                 return refuseUpgrade(socket, 503);
             const remoteKey = req.socket.remoteAddress ?? "unknown";
-            if (preAuthCount >= maxPreAuthConnections || (preAuthByRemote.get(remoteKey) ?? 0) >= maxPreAuthConnectionsPerRemote) {
-                metrics?.inc("device_preauth_refused_total");
-                logger?.warn("device_preauth_cap_hit", { remoteKey, preAuthCount, cap: maxPreAuthConnections });
+            const perRemoteCount = preAuthByRemote.get(remoteKey) ?? 0;
+            const globalHit = preAuthCount >= maxPreAuthConnections;
+            const perRemoteHit = maxPreAuthConnectionsPerRemote !== "off" && perRemoteCount >= maxPreAuthConnectionsPerRemote;
+            if (globalHit || perRemoteHit) {
+                const arm = globalHit ? (perRemoteHit ? "both" : "global") : "per_remote";
+                metrics?.inc("device_preauth_refused_total", { arm });
+                logger?.warn("device_preauth_cap_hit", {
+                    remoteKey, arm, preAuthCount, cap: maxPreAuthConnections, perRemoteCount, perRemoteCap: maxPreAuthConnectionsPerRemote,
+                });
                 return refuseUpgrade(socket, 503);
             }
             preAuthCount += 1;

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

@@ -3,7 +3,7 @@ import type { ExecutionErrorCode, FileErrorCode } from "@sema-agent/core";
 export declare const DEVICE_WS_PATH = "/v1/device/ws";
 /** 本 server 铸/认的协议版本。加帧/加字段 = additive 不升版;改语义 = 升版(§5.6)。 */
 export declare const DEVICE_PROTOCOL_VERSION = 1;
-/** 低于此版本 ⇒ `helloReject: protocol_version_unsupported`(响亮拒,不静默降级,#157)。 */
+/** 低于此版本 ⇒ `helloReject: protocol_version_unsupported`(响亮拒,不静默降级,[ref])。 */
 export declare const DEVICE_MIN_PROTOCOL_VERSION = 1;
 /** 签名的 domain tag —— 换域即换 tag,防止别处的 Ed25519 签名被拿来当握手用。 */
 export declare const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
@@ -373,7 +373,7 @@ export declare function formatGeneration(n: number): string;
  * 设备帧的唯一解析入口。
  *
  * 🔴 顺序是 帽 → JSON → 对象 → 帧型 → 形:每一步都有自己的拒因词,审计行才能回答「它到底哪儿坏了」。
- * 没有任何一步会「尽量修一下再放行」——安全轴上的坏形帧只有响亮拒一条路(#157)。
+ * 没有任何一步会「尽量修一下再放行」——安全轴上的坏形帧只有响亮拒一条路([ref])。
  */
 export declare function parseDeviceFrameText(text: string, opts?: {
     maxBytes?: number;
@@ -396,7 +396,7 @@ export declare function buildHelloSignaturePayload(input: {
 /**
  * 验签判决。`reason` **只进日志**(wire 上永远是同一个 `auth_failed` —— 反枚举),但它必须存在:
  * 一个「公钥导入失败」和一个「签名对不上」在运维上是两回事,把它们一起折成 `false` 就等于把
- * 「这台设备的公钥列存坏了」这条事实永久删掉(#191 门② SHAPE C:错误要**当数据交出**,不是吞掉)。
+ * 「这台设备的公钥列存坏了」这条事实永久删掉([ref] 门② SHAPE C:错误要**当数据交出**,不是吞掉)。
  */
 export type HelloSignatureVerdict = {
     ok: true;

package/dist/digest-form.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/158 R12 收编叶子 — the sha256 content-address SHAPE constants, single-sourced. A neutral leaf (no
+ * [ref] R12 收编叶子 — the sha256 content-address SHAPE constants, single-sourced. A neutral leaf (no
  * imports of its own) so both `security.ts`-adjacent modules and prompt/image/session-sync consumers can
  * depend on it without a layering edge. Six call sites across the tree each ran their OWN literal copy of one
  * of these two regexes (a bare-hex form and a scheme-qualified form) — same shape, independently typed out.

package/dist/elicitation.d.ts

@@ -15,7 +15,7 @@ export interface ElicitationFrame {
     mode?: "form";
     /** "elicitation_complete" only: how it resolved. */
     action?: McpElicitResponse["action"];
-    /** Server-signed emit timestamp (additive, [2805]§五→[2806]). These side-frames are SERVER-minted — they have
+    /** Server-signed emit timestamp (additive, [ref]§五→[ref]). These side-frames are SERVER-minted — they have
      *  no core-stream anchor, so no `eventId` (absence is honest, not an omission); this is the frame's own time
      *  coordinate instead, same posture as the stream-approval frames' `serverNowMs`. */
     serverNowMs?: number;

package/dist/env-facts.d.ts

@@ -4,16 +4,16 @@ export interface SandboxEnvFacts {
     capabilities?: string[];
     pkgSource?: string;
     egress?: "none" | "allowlist" | "full";
-    /** [820]③ scratchpad first wave: core `TaskSpec.envFacts.scratchpadDir` (field + prompt chain —
+    /** [ref]③ scratchpad first wave: core `TaskSpec.envFacts.scratchpadDir` (field + prompt chain —
      *  buildScratchpadSection — shipped in core 1.257.3; only this server half was missing). Core renders the
      *  "# Scratchpad Directory" block steering temp files away from /tmp AND the user's project. Core's prompt
      *  wording promises: session-specific, isolated from the user's project, "can generally be used without
      *  permission prompts" — that last clause is exactly the exemption domain createFsWriteGatePolicy.exemptDirs
-     *  will honor ([819]③/[820]①), so the path is produced by the single-source {@link scratchpadDirFor} and the
+     *  will honor ([ref]③/[ref]①), so the path is produced by the single-source {@link scratchpadDirFor} and the
      *  1.290 wiring must reference the SAME function for exemptDirs. */
     scratchpadDir?: string;
-    /** [1467]②(core 1.360 B 半场)durable resume 铸句真值——server 按**车道能力面**填(部署静态事实,
-     *  非车道名判——[1452]③ 诚实裁:缺席字段=core 零句,绝不写死车道行为):
+    /** [ref]②(core 1.360 B 半场)durable resume 铸句真值——server 按**车道能力面**填(部署静态事实,
+     *  非车道名判——[ref]③ 诚实裁:缺席字段=core 零句,绝不写死车道行为):
      *   - e2b:VM snapshot suspend/resume ⇒ processes+scratch 双 preserved。
      *   - k8s(s3Snapshot):resume=fresh pod+workspace untar ⇒ processes+scratch 双 lost(note 讲清
      *     workspace 文件已从快照恢复——「scratch lost」≠「工作丢了」)。
@@ -61,7 +61,7 @@ export declare function scratchpadSessionSegment(sessionId: string): string;
 /** THE scratchpad path convention: `<localDataRoot>/scratchpad/<sessionSegment>`. Session-scoped (core's
  *  prompt says "session-specific" — every task on the session shares one dir, which is the useful semantics:
  *  intermediate artifacts survive across turns/resume legs). Exported as the single source both the envFacts
- *  composer (below) and the future createFsWriteGatePolicy `exemptDirs` wiring ([820]①, 1.290) must use. */
+ *  composer (below) and the future createFsWriteGatePolicy `exemptDirs` wiring ([ref]①, 1.290) must use. */
 export declare function scratchpadDirFor(localDataRoot: string, sessionId: string): string;
 /** Resolve + CREATE the session scratchpad dir (mkdir -p, idempotent). Returns the path, or undefined when
  *  creation fails (honest-facts posture: never advertise a directory that does not exist — same class as
@@ -69,7 +69,7 @@ export declare function scratchpadDirFor(localDataRoot: string, sessionId: strin
  *  {@link purgeScratchpadDir}(session delete)+ {@link sweepStaleScratchpads}(mtime 周期扫),keyed by the
  *  same scratchpadDirFor convention;接线(E21 DELETE purge + 周期 sweep)在 main.ts 侧(D 组)。 */
 export declare function ensureScratchpadDir(localDataRoot: string, sessionId: string): Promise<string | undefined>;
-/** G3([816] 壳侧承诺③/[820]③,[1840]§四接单):**壳供** scratchpad 路径的验收门。
+/** G3([ref] 壳侧承诺③/[ref]③,[ref]§四接单):**壳供** scratchpad 路径的验收门。
  *
  *  壳(cli)vendored getScratchpadDir 算出 per-session scratchpad 路径随 `TaskRequest.scratchpadDir` 发来;
  *  接受后它**优先于** server 自算(ensureScratchpadDir),喂 main.ts 的同一单点(envFacts 事实 +
@@ -81,7 +81,7 @@ export declare function ensureScratchpadDir(localDataRoot: string, sessionId: st
  *   - 绝对路径 + ≤{@link MAX_PATH}(core 渲染上限同源,超限=core 只能给模型假路径)+ canonical
  *     深度 ≥3(裸 /、/tmp、/home 一整块系统目录不能当豁免域;穿越形按 resolve 归一后判);
  *   - mkdir -p 确保存在(gate 的 canonicalize 与 core 根围栏都要真目录)。
- *  敏感路径的最后一道**不在**写门折叠里(#177 起搬家):守卫集 `SENSITIVE_WRITE_PATTERNS` 由
+ *  敏感路径的最后一道**不在**写门折叠里([ref] 起搬家):守卫集 `SENSITIVE_WRITE_PATTERNS` 由
  *  governance 拍(boot/resolve-spec.ts → applyRuntimeGovernance)无条件铸成 DENY 基线,经 tightenTaskSpec
  *  与写门 deny-wins 折叠 —— 结论不变(deny 恒赢,本函数放出的 exemptDirs 越不过它),但施加点已换。 */
 export declare function acceptShellScratchpadDir(raw: unknown, opts: {

package/dist/execution-lane-caps.d.ts

@@ -8,7 +8,7 @@
  * `isRemoteScratchpadLane` 查一个 `Set`、`isSandboxPathAdjudicationLane` 取 `!== "host"` 的否定、
  * `sandboxSendLaneEnabled` 是一串 if。于是「lane 词表加一个词」的病形不是编译错,是**每一处的默认
  * 答案静默错**:新词不在 Set 里 ⇒ 静默 false;不等于 `"host"` ⇒ 静默 true。没有一处会报,每一处都
- * 给出一个**没有人表过态**的答案(DISEASE-SHAPES V1/V2;#157 执行车道轴的同族病)。
+ * 给出一个**没有人表过态**的答案(DISEASE-SHAPES V1/V2;[ref] 执行车道轴的同族病)。
  *
  * ## 本模块 = 那张表的单源(三件)
  *
@@ -33,7 +33,7 @@
  * 车道语义绑死(host 的单用户前提),所以进了 {@link LaneCapability} 的第三个词而不是靠调用方记住。
  *
  * 依赖纪律:本文件是**叶**(只 type-import config-types),不引 config.ts —— config.ts 反过来引它取
- * {@link RemoteExecProvider}(#157 必需 env 表按同一联合键控)。
+ * {@link RemoteExecProvider}([ref] 必需 env 表按同一联合键控)。
  */
 import type { ServiceConfigFlat } from "./config-types.js";
 /** 一位能力的三态。`single-user-only` = 车道支持,但只在单用户部署(`requirePrincipal !== true`)开 ——
@@ -74,7 +74,7 @@ export interface ExecutionLaneCaps {
     readonly suspendable: LaneCapability;
     /** `/tmp/scratchpad/<sessionId>` 远端约定。判别式:`plugins/remote-scratchpad.ts` 的 `isRemoteScratchpadLane`。 */
     readonly remoteScratchpad: LaneCapability;
-    /** 写门走 #165 的 `DeferredSandboxPathEnv` 代理裁决(而不是直接拿 worker 本机 fs 裁)。
+    /** 写门走 [ref] 的 `DeferredSandboxPathEnv` 代理裁决(而不是直接拿 worker 本机 fs 裁)。
      *  判别式:`boot/deferred-sandbox-path-env.ts` 的 `isSandboxPathAdjudicationLane`。 */
     readonly sandboxPathAdjudication: LaneCapability;
     /** git-worktree 隔离。判别式:`boot/execution-env.ts` 的 host 臂 vs `worktree_isolation_unsupported_lane` warn。 */
@@ -97,7 +97,7 @@ export interface ExecutionLaneCaps {
  *  · `callerCwd: supported` —— 员工在自己设备的项目目录里干活是这条车道的**存在理由**;host 闸防的
  *    「跨租户宿主路径穿越」在此结构性不存在(路径落在发起者自己的设备上,归属已由 deviceId↔principal
  *    绑定验证),故不要求单用户。今天 `cwdHonored` 还答 false ⇒ 登记在 {@link PLANNED_LANE_DIVERGENCES}。
- *  · `sandboxPathAdjudication: supported` —— 自动判真且**这是深思后的正确默认**:写门经 #165 代理把四读
+ *  · `sandboxPathAdjudication: supported` —— 自动判真且**这是深思后的正确默认**:写门经 [ref] 代理把四读
  *    原语转发到设备取真文件系统事实,云盘永不参与设备写目标的裁决。
  *  · `remoteScratchpad: supported` —— executor 平台闭集 = darwin|linux,`/tmp/scratchpad/<sessionId>`
  *    的惰性 mkdir 约定原样适用;不加词则 scratchpad envFact 对模型整块缺席。
@@ -119,7 +119,7 @@ export declare const ALL_EXECUTION_LANES: readonly ExecutionLane[];
  *
  * · `undefined`(REMOTE_EXEC 未设)⇒ `"in-process"`,那是真车道不是缺席;
  * · 认不出的词 ⇒ `undefined`,**调用方必须 fail-closed**(禁静默按某个默认车道处理)。生产链上这一臂
- *   不可达:`loadConfig` 的 #157 拒启门先咬未知词;它存在是为了消费点自卫时有个响亮出口。
+ *   不可达:`loadConfig` 的 [ref] 拒启门先咬未知词;它存在是为了消费点自卫时有个响亮出口。
  */
 export declare function executionLaneOf(provider: string | undefined): ExecutionLane | undefined;
 /** 把一位能力在**具体部署**上落成布尔:租户面是唯一入参(旋钮由消费点自己再合取)。