@sema-agent/server 7.118.0 → 7.120.0

package/dist/capabilities/builtin-tools.d.ts

@@ -1,19 +1,42 @@
-import type { SubagentSpawnContext, ToolSpec } from "@sema-agent/core";
+import type { SubagentSpawnContext, SubagentToolOptions, ToolSpec } from "@sema-agent/core";
 /** Current time — the model has no clock; OA/most tasks need it. No side effects. CC-parity tool name `Now`
  *  (PascalCase, core 1.176 first-party rename wrap-up — the SERVICE owns this one; `nowTool` is not a core tool).
  *  effect:"read" so it never suspends → no durable-resume rename strand (no pending-tool checkpoint to canonicalize). */
 export declare function nowTool(): ToolSpec;
 /**
- * #1110(core 7.32.0)—— 委派子代的**逐次注入**工厂(`SubagentToolOptions.extraTools`):`Now` + 部署的 extra tools(今天 = SendUserFile)。
+ * 委派子代逐次注入的**一组**工具:`tools` 是这组**可能**注入的全部工具对象,`forSpawn` 只在这些对象里选「这一次 spawn 拿不拿」(缺席 = 每次都拿)。
+ * 名册与工厂读的是同一张 `tools` —— 工厂只能交出名册里那几只对象,结构上交不出名册外的东西(core 7.46.0 #1432 的「声明不说谎」在本仓由形状保证,
+ * 不靠两张表对拍)。
+ */
+export interface SubagentExtraToolSet {
+    readonly tools: readonly ToolSpec[];
+    readonly forSpawn?: (ctx: SubagentSpawnContext) => boolean;
+}
+/** 委派工具上与逐次注入相关的两键(core `SubagentToolOptions` 的 `extraTools` / `extraToolNames`):工厂(本仓的恒同步)+ 它的名册。 */
+export interface SubagentExtraToolOptions {
+    readonly extraTools: (ctx: SubagentSpawnContext) => ToolSpec[];
+    readonly extraToolNames: NonNullable<SubagentToolOptions["extraToolNames"]>;
+}
+/**
+ * #1110(core 7.32.0)—— 委派子代的**逐次注入**:`Now` + 部署的 extra tools(今天 = SendUserFile)。
  *
  * 为什么 `Now` 走这条通道:core 7.32.0 起子代按**身份**继承场景层 bundle 的工具(`assembleCodeTools` 交给 Agent 的
  * `inheritedTools` ∩ 父 run 真挂载),而 `Now` 是本仓在 bundle **旁边**组的宿主工具(scenarios.ts),宿主工具**从不**被继承
  * (core:继承整张 `spec.tools` 会把宿主工具带过宿主自己的逐次门)—— 逐次注入是它到达子代的唯一通道。一个工厂、两个产地:
- * 部署工厂的门(SendUserFile 的审批面预判 / 只读内建排除)原样在它自己那只函数里,这里只做合成。
- * ⚠️ 工厂恒在场 ⇒ core 不再给 Agent 工具铸静态 `agentToolPool`(core:工厂可在 spawn 时注入身份未知的工具 ⇒ 池不可静态知 ⇒
- * 记忆内容来源读者按「外部」读,fail-closed)。本仓 default bundle 的继承面本来就含 WebFetch(外部),这一翻面只在
- * 「子代面恰好不含任何外部工具」的窄形上把委派结果多判一次外部,方向是收紧。
- * 工厂**不抛**:`nowTool()` 是纯构造;部署工厂的抛由 core 收成「这一 spawn 什么都不继承 + 模型面披露句」(onExtraToolsError 记 warn)。
+ * 部署那一组的门(只读内建排除)在它自己的 `forSpawn` 里,这里只做合成。
+ *
+ * core 7.46.0 #1432 —— **工厂与名册一个来源**:返回委派工具的两键,`extraTools`(每次 spawn 交出 `forSpawn` 选中的那几只)与
+ * `extraToolNames`(全部可能交出的那几只的名字 / 别名 / 内容来源,从同一批 `ToolSpec` 读出)。名册在场 ⇒ 引擎重新能列出子代的工具池:
+ * 定义级 / 工具级 / `TaskSpec.agents` 清单里的退役拼法与大小写孪生回到开跑前拒(`config.agent.unknown_tool`),记忆内容来源读者按声明读这几只。
+ * 修前(core 7.32.0–7.45.x)工厂恒在场 ⇒ 池不可静态知 ⇒ 那一族拼法只告不拒、委派结果一律按「外部」读。
+ * 工厂**不抛**:各组的 `tools` 是装配期就建好的对象;部署 `forSpawn` 的抛由 core 收成「这一 spawn 什么都不继承 + 模型面披露句」(onExtraToolsError 记 warn)。
+ * 一种拼法出现在两只工具上(部署工具与 `Now` 撞名 / 别名撞)⇒ core 在建委派工具处抛 `config.extra_tool_names`(`shape`),不静默取其一。
+ */
+export declare function createSubagentExtraTools(deployment?: SubagentExtraToolSet): SubagentExtraToolOptions;
+/**
+ * `onExtraToolsError` 收到的错误 → 运维行 `subagent_extra_tools_error` 的字段:句子,加上错误**自带**的码与 `detail.reason`(在场才铸)。
+ * core 7.46.0 #1432 被拒的 spawn(产物不在名册里)带 `config.extra_tool_names` + `undeclared_name` / `undeclared_origin`;部署工厂自己抛的错多半两位都不带。
+ * 本仓不按码分支、不重铸 —— 只把错误说的话原样过境到运维面(修前只记句子,码与原因词丢在这一跳)。
  */
-export declare function createSubagentExtraTools(deployment?: (ctx: SubagentSpawnContext) => ToolSpec[]): (ctx: SubagentSpawnContext) => ToolSpec[];
+export declare function extraToolsErrorFields(err: unknown): Record<string, unknown>;
 //# sourceMappingURL=builtin-tools.d.ts.map

package/dist/capabilities/builtin-tools.js

@@ -9,6 +9,27 @@ export function nowTool() {
     };
 }
 export function createSubagentExtraTools(deployment) {
-    return (ctx) => [nowTool(), ...(deployment?.(ctx) ?? [])];
+    const sets = [{ tools: [nowTool()] }, ...(deployment !== undefined ? [deployment] : [])];
+    return {
+        extraTools: (ctx) => sets.flatMap((s) => (s.forSpawn === undefined || s.forSpawn(ctx) ? [...s.tools] : [])),
+        extraToolNames: sets.flatMap((s) => s.tools).map((t) => ({
+            name: t.name,
+            ...(t.aliases !== undefined ? { aliases: [...t.aliases] } : {}),
+            ...(t.contentOrigin !== undefined ? { contentOrigin: t.contentOrigin } : {}),
+        })),
+    };
+}
+export function extraToolsErrorFields(err) {
+    const fields = { err: err instanceof Error ? err.message : String(err) };
+    if (err === null || typeof err !== "object")
+        return fields;
+    const code = Reflect.get(err, "code");
+    if (typeof code === "string")
+        fields.code = code;
+    const detail = Reflect.get(err, "detail");
+    const reason = detail !== null && typeof detail === "object" ? Reflect.get(detail, "reason") : undefined;
+    if (typeof reason === "string")
+        fields.reason = reason;
+    return fields;
 }
 //# sourceMappingURL=builtin-tools.js.map

package/dist/capabilities/center-plugins.d.ts

@@ -97,6 +97,8 @@ export declare function materializablePlugins(eff: {
     url: string;
     sha?: string;
 }>;
+/** 总入口(条款 3/7/8):逐条物化 + 装载 + 让位合并。materialize 盘位 = `<cacheRoot>/<name>/live`
+ *  (成功后原子 rename 替换,失败保留旧盘位 = LKG)。 */
 export declare function applyCenterPlugins(baseline: LoadedSkill[], eff: {
     plugins?: unknown;
 }, opts: {

package/dist/capabilities/center-plugins.js

@@ -108,21 +108,39 @@ export function resolvePluginSkillsRoot(cloneRoot) {
     }
     return { ok: true, dir: candidate };
 }
+const PLUGINS_DOMAIN_FAILURE_NAME = "(plugins domain)";
 function declaredPlugins(eff) {
-    if (Array.isArray(eff.plugins))
-        return eff.plugins;
-    const wrapped = eff.plugins?.plugins;
-    return Array.isArray(wrapped) ? wrapped : [];
+    const domain = eff.plugins;
+    if (domain === undefined)
+        return { ok: true, decls: [] };
+    if (Array.isArray(domain))
+        return { ok: true, decls: domain };
+    if (typeof domain === "object" && domain !== null) {
+        const inner = domain.plugins;
+        if (Array.isArray(inner))
+            return { ok: true, decls: inner };
+        return { ok: false, reason: `plugins domain shape rejected: expected an array or { plugins: [...] }, got an object whose plugins member is ${wireTypeWord(inner)}` };
+    }
+    return { ok: false, reason: `plugins domain shape rejected: expected an array or { plugins: [...] }, got ${wireTypeWord(domain)}` };
 }
 export function materializablePlugins(eff, allowHosts) {
-    return declaredPlugins(eff).flatMap((decl) => {
+    const shape = declaredPlugins(eff);
+    if (!shape.ok)
+        return [];
+    return shape.decls.flatMap((decl) => {
         const v = validatePluginDecl(decl, allowHosts);
         return v.ok ? [{ name: v.name, url: v.url, ...(v.sha !== undefined ? { sha: v.sha } : {}) }] : [];
     });
 }
 export async function applyCenterPlugins(baseline, eff, opts) {
-    const declared = declaredPlugins(eff);
+    const shape = declaredPlugins(eff);
     const out = { skills: [...baseline], failures: [], letGo: [], lkgUsed: [] };
+    if (!shape.ok) {
+        opts.logger?.warn("center_plugins_domain_rejected", { reason: shape.reason });
+        out.failures.push({ plugin: PLUGINS_DOMAIN_FAILURE_NAME, reason: shape.reason });
+        return out;
+    }
+    const declared = shape.decls;
     if (declared.length === 0)
         return out;
     const runGit = opts.runGit ?? (async (args) => {

package/dist/capabilities/code-review-council.js

@@ -35,8 +35,10 @@ export function createCouncilTool(subRunner, repoTools, objective, opts = {}) {
         parameters: Type.Object({}),
         execute: async (_args, ctx) => {
             const active = pickLenses(opts.lensCount);
-            const lenses = await runLensReviews(subRunner, repoTools, objective, ctx.signal, active);
-            const findings = lenses.map((l) => `### ${l.lens} reviewer\n${l.text}`).join("\n\n");
+            const outcomes = await runLensReviews(subRunner, repoTools, objective, ctx.signal, active);
+            const lenses = outcomes.filter((o) => o.ok);
+            const failedLenses = outcomes.flatMap((o) => (o.ok ? [] : [{ lens: o.lens, reason: o.reason }]));
+            const findings = outcomes.map((o) => `### ${o.lens} reviewer\n${o.ok ? o.text : `(lens errored: ${o.reason})`}`).join("\n\n");
             const converge = await runConvergence(subRunner, repoTools, objective, findings, opts, ctx.signal, active);
             const totalTokens = lenses.reduce((s, l) => s + l.tokens, 0) + converge.tokens;
             const totalTurns = lenses.reduce((s, l) => s + l.turns, 0) + converge.turns;
@@ -46,10 +48,10 @@ export function createCouncilTool(subRunner, repoTools, objective, opts = {}) {
             opts.metrics?.inc("council_runs_total", { mode });
             opts.metrics?.inc("task_tokens_total", {}, totalTokens);
             opts.metrics?.observe("council_tokens", totalTokens);
-            opts.logger?.info("council_done", { mode, lenses: lenses.length, totalTokens, totalTurns });
+            opts.logger?.info("council_done", { mode, lenses: lenses.length, failedLenses, totalTokens, totalTurns });
             return {
                 content: converge.review,
-                details: { council: { mode, totalTokens, totalTurns, perLens: lenses.map((l) => ({ lens: l.lens, tokens: l.tokens })) } },
+                details: { council: { mode, totalTokens, totalTurns, perLens: lenses.map((l) => ({ lens: l.lens, tokens: l.tokens })), failedLenses } },
             };
         },
     };
@@ -65,16 +67,11 @@ async function runLensReviews(subRunner, repoTools, objective, signal, lenses) {
             enableBlockedReport: false,
             signal,
         });
-        return { lens: lens.name, text: r.result?.trim() || "(no findings)", tokens: r.stats.tokens, turns: r.stats.turns };
+        return { ok: true, lens: lens.name, text: r.result?.trim() || "(no findings)", tokens: r.stats.tokens, turns: r.stats.turns };
     }));
     return settled.map((s, i) => s.status === "fulfilled"
         ? s.value
-        : {
-            lens: lenses[i].name,
-            text: `(lens errored: ${s.reason instanceof Error ? s.reason.message : String(s.reason)})`,
-            tokens: 0,
-            turns: 0,
-        });
+        : { ok: false, lens: lenses[i].name, reason: s.reason instanceof Error ? s.reason.message : String(s.reason) });
 }
 async function runConvergence(subRunner, repoTools, objective, findings, opts, signal, lenses) {
     if (opts.debate) {

package/dist/capabilities/scenarios.d.ts

@@ -1,6 +1,7 @@
-import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type PromptProvider, type Runner, type SkillSpec, type SubagentSpawnContext, type TaskListStore, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
+import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type PromptProvider, type Runner, type SkillSpec, type TaskListStore, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
 import type { Metrics } from "../observability/metrics.js";
 import type { Logger } from "../observability/logger.js";
+import { type SubagentExtraToolSet } from "./builtin-tools.js";
 import { type RepoReadClient } from "./repo-tools.js";
 import { type LoadedSkill } from "./skills.js";
 import { type ScenarioHands } from "./hands-lane.js";
@@ -90,12 +91,13 @@ export interface ScenarioDeps {
      * core 1.287 `SubagentToolOptions.extraTools` seam wire-through — per-SPAWN dynamic tool injection into the
      * delegated (Agent-tool) child roster. Deployment-injected per-task tools (today: SendUserFile — its instance is
      * execute-time late-bound via ctx.taskId → TaskEnvRegistry, so ONE spec serves every spawn) cannot ride the
-     * ASSEMBLY-time static `subagent.tools` pool; this factory is evaluated by core at each spawn and its product is
-     * merged into the pool, then goes through core's `resolveToolSubset` whitelist like any other tool (agent-def
-     * allowTools/denyTools still govern — no extra gate needed on our side). Absent ⇒ no dynamic injection (children
-     * see exactly the static full-body roster, the pre-1.287 behavior).
+     * ASSEMBLY-time static `subagent.tools` pool; core evaluates the factory at each spawn and merges its product into the
+     * pool, then it goes through core's `resolveToolSubset` whitelist like any other tool (agent-def allowTools/denyTools
+     * still govern — no extra gate needed on our side). A SET, not a bare factory (core 7.46.0 #1432): its `tools` are both
+     * what a spawn can be handed and the roster the delegation tool declares (`extraToolNames`), so the factory cannot hand
+     * out a tool the roster does not name. Absent ⇒ the delegation tool injects `Now` alone.
      */
-    subagentExtraTools?: (ctx: SubagentSpawnContext) => ToolSpec[];
+    subagentExtraTools?: SubagentExtraToolSet;
     /**
      * core 1.364 durable background agents([ref] S1,[ref] 提货单②写半场):后台子代 `a*` 行的
      * durable 执行记录 store。**必须与 `RunnerDeps.backgroundAgentStore` 同实例**(读写双点配对,engine
@@ -174,7 +176,12 @@ export declare function semaIdentityProvider(): PromptProvider;
  */
 export declare function codePromptProvider(brand: boolean): PromptProvider;
 export declare function buildScenarios(deps: ScenarioDeps): Record<string, Scenario>;
-/** Resolve the scenario for a request (falls back to `default`). */
+/**
+ * Resolve the scenario bundle for a name. `undefined` = no preference ⇒ the built-in `default`; any OTHER name must be
+ * registered — an unregistered one is a caller bug and THROWS (it never falls back to `default`: a restricted principal's
+ * bundle must not silently widen). Request paths get their name from {@link gateScenarioRequest}, whose result is always
+ * registered, so the throw is unreachable from them; it is the loud arm for a direct caller that skipped the gate.
+ */
 export declare function selectScenario(scenarios: Record<string, Scenario>, name: string | undefined): Scenario;
 /** web 渲染契约(定稿形状;knobs 现在没有=整字段省略)。 */
 export interface ScenarioDetail {
@@ -259,16 +266,38 @@ export interface ScenarioRuling {
     /** 纯场景名集合(principal/组名不上 wire);空 = 该 principal 无任何指派 = 无治理。 */
     allowlist: string[];
 }
+/**
+ * 一个场景名的**来源**(闭集:新增一词 ⇒ {@link danglingScenarioRefusal} 的穷尽 switch 编译红)。
+ *  · `ruling` —— 中心按主体指派的场景(`ScenarioRuling.scenario`);
+ *  · `deployment` —— 部署自己写的缺省(`DEFAULT_SCENARIO` / config `defaultScenario`)。
+ * 请求体显式给的名字不在此列:那是调用方的话,不在册 ⇒ 400 `scenario_unknown`(见 {@link gateScenarioRequest})。
+ */
+export type ScenarioNameSource = "ruling" | "deployment";
+/**
+ * 🔴 **悬空场景名的判据与拒句 —— 全仓唯一属主。**
+ *
+ * 指派 / 部署缺省指向不在册的名字,此前一路被折成 `default`(工具 / 提示 / skills / mcp 整包跟着换,零 warn):受限场景的主体被
+ * 悄悄放进更宽的 default。本函数把那条回退链换成两条出路,**没有第三条**:
+ *  · `deployment` 悬空 ⇒ 起服拒启(`boot/stage-07-capability-layer.ts` 在 center 场景 overlay 之后调它、`throw new Error`);
+ *  · `ruling` 悬空 ⇒ 该 run 503 `state.scenario_assignment_unknown`({@link gateScenarioRequest} 调它);
+ *  · `deployment` 悬空到得了 run(只有自己装配 `resolveSpec`、没经过起服的嵌入方)⇒ 同码同判据同一句话 —— 起服拒启与这一条是同一个答案。
+ *
+ * 返回 `undefined` = 在册;否则是**拒句**(点名名字与来源、给在册词表、说怎么修)。判据按**自有键**(`known` 是场景表的
+ * `Object.keys`,`constructor` / `__proto__` 不是场景名)。
+ */
+export declare function danglingScenarioRefusal(name: string, source: ScenarioNameSource, known: readonly string[]): string | undefined;
 /**
  * resolveSpec 的执法入口(指派为默认、body.scenario 可换但限 allowlist)。返回本请求的
- * 生效场景名(未做 unknown→default 回退——那是 resolveSpec 既有职责,保持单点)。
+ * **在册**生效场景名 —— 返回值一定在 `known` 里:下游直接按它取场景,没有「未知名 → default」的回退臂。
  *
- *   - body.scenario 显式给出:allowlist 非空且集外 ⇒ typed 拒绝(400 `scenario_not_allowed`,附 allowlist
- *     ——机器码归 wire、人话归壳/web);集内 ⇒ 用户主动切换赢。allowlist 为空(无 ruling / 该 principal
- *     三层皆无指派 / caps 面故障)⇒ 无治理约束,现状放行(与「null 落兜底链」同一语义:分配面未覆盖 =
+ *   - body.scenario 显式给出:不在册 ⇒ typed 400 `scenario_unknown`(调用方的错);allowlist 非空且集外 ⇒ typed 拒绝
+ *     (400 `scenario_not_allowed`,附 allowlist ——机器码归 wire、人话归壳/web);集内 ⇒ 用户主动切换赢。allowlist 为空
+ *     (无 ruling / 该 principal 三层皆无指派 / caps 面故障)⇒ 无治理约束,现状放行(与「null 落兜底链」同一语义:分配面未覆盖 =
  *     不收紧,恒不比没有治理时更宽;caps 故障不把用户锁死在 default——场景切换不是权限放大面,fail-open
  *     到现状,与 workflows 面的 fail-closed 是刻意的 posture 差异,见 runtime-caps-resolver)。
- *   - body.scenario 未给:ruling 胜者 ⇒ 指派为默认;无胜者 ⇒ defaultScenario 现状链。
+ *   - body.scenario 未给:ruling 胜者 ⇒ 指派为默认;无胜者 ⇒ defaultScenario 现状链。链上的名字不在册 ⇒ 503
+ *     `state.scenario_assignment_unknown`(部署的错 / 中心的错,不是调用方的错),**不**折 default
+ *     ({@link danglingScenarioRefusal})。`principal` 只进那一行运维日志,不参与判定。
  */
-export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined, bodyScenario: unknown, defaultScenario: string, known: readonly string[], logger?: Logger): string;
+export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined, bodyScenario: unknown, defaultScenario: string, known: readonly string[], logger?: Logger, principal?: string): string;
 //# sourceMappingURL=scenarios.d.ts.map

package/dist/capabilities/scenarios.js

@@ -1,6 +1,6 @@
 import { CODE_AGENT_PROMPT, CODE_SYSTEM_PROMPT, DEFAULT_SYSTEM_PROMPT, WEB_FETCH_TOOL_NAME, assembleCodeTools, defaultTaskRegistry } from "@sema-agent/core";
-import { HttpError } from "../security.js";
-import { createSubagentExtraTools, nowTool } from "./builtin-tools.js";
+import { HttpError, createCodedHttpError } from "../security.js";
+import { createSubagentExtraTools, extraToolsErrorFields, nowTool } from "./builtin-tools.js";
 import { parseRepo, repoToolsFor } from "./repo-tools.js";
 import { createCouncilTool, clampRounds } from "./code-review-council.js";
 import { stablePrompt } from "./prompt.js";
@@ -70,9 +70,9 @@ export function buildScenarios(deps) {
                             ...(deps.checkpointStore ? { checkpointStore: deps.checkpointStore } : {}),
                             ...(deps.ensureChildSessionDurable ? { ensureChildSessionDurable: deps.ensureChildSessionDurable } : {}),
                         },
-                        extraTools: createSubagentExtraTools(deps.subagentExtraTools),
+                        ...createSubagentExtraTools(deps.subagentExtraTools),
                         ...(deps.logger
-                            ? { onExtraToolsError: (err, info) => deps.logger?.warn?.("subagent_extra_tools_error", { ...info, err: err instanceof Error ? err.message : String(err) }) }
+                            ? { onExtraToolsError: (err, info) => deps.logger?.warn?.("subagent_extra_tools_error", { ...info, ...extraToolsErrorFields(err) }) }
                             : {}),
                     },
                     ...(webSearch ? { webSearch } : {}),
@@ -120,8 +120,12 @@ export function buildScenarios(deps) {
     };
 }
 export function selectScenario(scenarios, name) {
-    const resolved = name;
-    return (resolved && Object.hasOwn(scenarios, resolved) && scenarios[resolved]) || scenarios.default;
+    if (name === undefined)
+        return scenarios.default;
+    const picked = Object.hasOwn(scenarios, name) ? scenarios[name] : undefined;
+    if (picked === undefined)
+        throw new Error(`scenario "${name}" is not registered — resolve a request's scenario through gateScenarioRequest, which only returns registered names`);
+    return picked;
 }
 function availabilityFields(deps, toolset) {
     const verdict = scenarioAvailability(deps, toolset);
@@ -295,11 +299,28 @@ export function mergeUserSkills(scenarioSkills, userSkills, logger) {
         logger?.warn("user_skills_dropped", { reason: "name reserved by scenario (or duplicate)", names: dropped });
     return out;
 }
-export function gateScenarioRequest(ruling, bodyScenario, defaultScenario, known, logger) {
+function registeredScenariosClause(known) {
+    return `this deployment's scenarios are: ${known.join(", ")}`;
+}
+export function danglingScenarioRefusal(name, source, known) {
+    if (known.includes(name))
+        return undefined;
+    switch (source) {
+        case "ruling":
+            return `the scenario assigned to this principal, "${name}", is not a scenario of this deployment — ${registeredScenariosClause(known)}; nothing ran — re-point the assignment (or add that scenario to this deployment) and retry`;
+        case "deployment":
+            return `DEFAULT_SCENARIO "${name}" does not name a scenario of this deployment — ${registeredScenariosClause(known)}; set DEFAULT_SCENARIO to one of them`;
+        default: {
+            const unhandled = source;
+            return unhandled;
+        }
+    }
+}
+export function gateScenarioRequest(ruling, bodyScenario, defaultScenario, known, logger, principal) {
     if (typeof bodyScenario === "string") {
         const requested = bodyScenario;
         if (!known.includes(requested)) {
-            throw new HttpError(400, `unknown scenario "${bodyScenario}" — this deployment's scenarios are: ${known.join(", ")}`, {
+            throw new HttpError(400, `unknown scenario "${bodyScenario}" — ${registeredScenariosClause(known)}`, {
                 code: "scenario_unknown",
                 extra: { known: [...known] },
             });
@@ -313,6 +334,12 @@ export function gateScenarioRequest(ruling, bodyScenario, defaultScenario, known
         }
         return requested;
     }
-    return ruling?.scenario ?? defaultScenario;
+    const [name, source] = ruling?.scenario != null ? [ruling.scenario, "ruling"] : [defaultScenario, "deployment"];
+    const refusal = danglingScenarioRefusal(name, source, known);
+    if (refusal !== undefined) {
+        logger?.warn("scenario_assignment_unknown", { scenario: name, source, ...(principal !== undefined ? { principal } : {}) });
+        throw createCodedHttpError(503, "state.scenario_assignment_unknown", refusal, { detail: { scenario: name, source } });
+    }
+    return name;
 }
 //# sourceMappingURL=scenarios.js.map

package/dist/capabilities/send-user-file-tool.d.ts

@@ -1,5 +1,6 @@
-import type { SubagentSpawnContext, ToolSpec } from "@sema-agent/core";
+import type { ToolSpec } from "@sema-agent/core";
 import type { IssuedFileLink } from "../plugins/send-user-file.js";
+import type { SubagentExtraToolSet } from "./builtin-tools.js";
 /** The frame the web/shell renders as a file card. Rides the durable events tail (replayable). */
 export interface FileLinkFrame {
     type: "file_link";
@@ -44,7 +45,9 @@ export declare function sendUserFileTool(deps: {
 }): ToolSpec;
 export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
 /**
- * Build the `SubagentToolOptions.extraTools` factory that injects SendUserFile into delegated-child rosters.
+ * The deployment's group for the delegated-child injection (`createSubagentExtraTools` in `builtin-tools.ts` composes it with
+ * `Now` into the delegation tool's `extraTools` factory AND its `extraToolNames` roster — one list, read twice): SendUserFile,
+ * handed to every spawn except a read-only builtin agent's.
  *
  * F2 (MED, codex; a product judgment of this server, kept): read-only builtin agents (Explore/Plan) must NOT get
  * SendUserFile — a read-only agent that can read sensitive files AND mint public links off them breaks the read-only
@@ -59,5 +62,5 @@ export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
  */
 export declare function subagentSendUserFileExtraTools(deps: {
     spec: ToolSpec;
-}): (ctx: SubagentSpawnContext) => ToolSpec[];
+}): SubagentExtraToolSet;
 //# sourceMappingURL=send-user-file-tool.d.ts.map

package/dist/capabilities/send-user-file-tool.js

@@ -94,6 +94,6 @@ export function sendUserFileTool(deps) {
 export const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
 const READONLY_BUILTIN_AGENT_TYPES = new Set(builtinAgentDefinitions().map((d) => d.name));
 export function subagentSendUserFileExtraTools(deps) {
-    return (ctx) => (ctx.agentType !== undefined && READONLY_BUILTIN_AGENT_TYPES.has(ctx.agentType) ? [] : [deps.spec]);
+    return { tools: [deps.spec], forSpawn: (ctx) => !(ctx.agentType !== undefined && READONLY_BUILTIN_AGENT_TYPES.has(ctx.agentType)) };
 }
 //# sourceMappingURL=send-user-file-tool.js.map

package/dist/config-catalog.js

@@ -94,7 +94,7 @@ export const CONFIG_CATALOG = [
     r("CONFIG_CATALOG_ENABLED", "auth", "boolean", "本目录端点 GET /v1/config/catalog 的旋钮(operator-only 面;合规部署可关 ⇒ 路径 404 + 能力位翻假)", { staticDefault: "true", danger: SEC, configKey: "configCatalogEnabled" }),
     r("CONFIG_LKG_DURABLE", "integrations", "boolean", "LKG 跨重启 handoff(严格 'true' 才开:重启先用 LKG 起服,tier 候选借此落地)", { staticDefault: "false" }),
     r("CONFIG_LKG_ENABLED", "integrations", "boolean", "last-known-good 配置盘缓存读写开关(仅远程 provider 有意义)", { staticDefault: "true" }),
-    r("CONFIG_LKG_PATH", "integrations", "path", "LKG 落盘路径", { derivedDefaultNote: "缺席 ⇒ SEMA_CONFIG_DIR(~/.sema)下按 worker 名派生" }),
+    r("CONFIG_LKG_PATH", "integrations", "path", "LKG 落盘路径(设了 ⇒ 派生读拒行:这条路径与它的真实落点各一行,按路径段串匹配 —— 任意深度出现即拒、大小写不敏感,用户仓里同段串的路径一并读不到;空串拒启)", { derivedDefaultNote: "缺席 ⇒ 配置根(SEMA_CONFIG_DIR,缺省 ~/.sema)下按 worker + 凭证身份分箱派生", configKey: "configLkgPath" }),
     r("CONFIG_LOCAL_DIR", "integrations", "path", "本地配置源根(config.d/<domain>.json);兼作数据根回落链一环", { configKey: "configLocalDir", danger: DATA }),
     r("CONFIG_PROVIDER", "integrations", "enum", "配置源双模选择(闭集,逐字比较;认不出的词 ⇒ 拒启,S-841)", { enumValues: CONFIG_PROVIDER_WORDS, derivedDefaultNote: "缺席:SEMA_REGISTRY_URL 在场 ⇒ remote,否则纯 env(无管道)", configKey: "configProvider" }),
     r("CONFIG_REQUIRE_ROSTER", "integrations", "boolean", "远程 registry 非 dryRun 时布防 ready 门:roster 未落地 ⇒ 计费提交 503 + /health ready:false(严格 'true')", { staticDefault: "false" }),
@@ -104,7 +104,7 @@ export const CONFIG_CATALOG = [
     r("CROSS_SESSION_INBOUND", "approval", "enum", "入站跨会话消息的部署/组织层治理(CC settings 键名 crossSessionInbound 的 managed 层;未设=本层不表态≠ next-turn;词表外拒启)", { danger: SEC, enumValues: [...CROSS_SESSION_INBOUND_SETTINGS], configKey: "crossSessionInbound", derivedDefaultNote: "缺席 ⇒ managed 层不设,由其余层与 mode-parity 决定", resolve: (c) => c.crossSessionInbound ?? null }),
     r("DB_BACKEND", "store", "enum", "store 后端引擎选择(mysql 兼容/pg/本机文件店/纯内存)", { enumValues: STORE_BACKENDS, danger: DATA, derivedDefaultNote: "裸 boot ⇒ local(多租户裸 boot ⇒ memory + notice);有 SQL 信号 ⇒ mysql", configKey: "dbBackend", resolve: (c) => c.dbBackend }),
     r("DB_QUERY_TIMEOUT_MS", "store", "number", "per-query DB 超时(ms;坏值回默认姿态+warn,绝不 NaN 进 driver)", { derivedDefaultNote: "缺席 ⇒ 池级不设/计数族 30s(按引擎)", configKey: "dbQueryTimeoutMs" }),
-    r("DEFAULT_SCENARIO", "integrations", "string", "出厂缺省场景(编码产品出厂态;通用中性 persona 用 default 显式选回)", { staticDefault: "code", configKey: "defaultScenario" }),
+    r("DEFAULT_SCENARIO", "integrations", "string", "出厂缺省场景(编码产品出厂态;通用中性 persona 用 default 显式选回);必须是本部署在册的场景名(内建 ∪ 配置中心声明的),不在册 ⇒ 拒启", { staticDefault: "code", configKey: "defaultScenario" }),
     r("DELEGATION_MAX_CONCURRENT", "orchestration", "number", "委派入口并发帽", { derivedDefaultNote: "缺席 ⇒ 不铸键,core 自缺省(CC parity 20)" }),
     r("DELEGATION_MAX_PER_SESSION", "orchestration", "number", "委派入口每会话累计帽", { derivedDefaultNote: "缺席 ⇒ 不铸键,core 自缺省(CC parity 200)" }),
     r("DEVICE_DELIVERY_TIMEOUT_MS", "orchestration", "number", "device 车道等在途槽上限(ms;到期 device.busy)", { derivedDefaultNote: "缺席 ⇒ adapter 默认 10s" }),
@@ -391,7 +391,7 @@ export const CONFIG_CATALOG = [
     r("SELF_ORCHESTRATION_MODELS", "orchestration", "csv", "workflow agent({modelName}) 显式词表(恒赢;缺席单用户=目录键全集/多租户 fail-closed)", { configKey: "selfOrchestrationModels" }),
     r("SELF_ORCHESTRATION_WORKER_ISOLATION", "orchestration", "boolean", "workflow 脚本跑 worker_thread(堆帽+terminate 的 DoS 隔离)", { staticDefault: "false", danger: SEC, configKey: "selfOrchestrationWorkerIsolation" }),
     r("SEMA_APT_MIRROR", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 apt 源地址(注入沙箱 pkg-source hook)"),
-    r("SEMA_CONFIG_DIR", "integrations", "path", "~/.sema 配置目录覆写(LKG/skill 缓存/scheduler 店同门)", { derivedDefaultNote: "缺席 ⇒ ~/.sema" }),
+    r("SEMA_CONFIG_DIR", "integrations", "path", "~/.sema 配置目录覆写(LKG/skill 缓存/scheduler 店同门;设了 ⇒ 起服时建出目录,交引擎在根下同护配置文件,能不能用由引擎判;空串拒启)", { derivedDefaultNote: "缺席 ⇒ ~/.sema", configKey: "agentConfigDir" }),
     r("SEMA_FAILOPEN_PROBE", "observability", "path", "F 类 fail-open 命中的探针文件路径(在场时逐次追加 fail-open 行;缺席只走计数+一次性 warn)"),
     r("SEMA_NODE_MIRROR", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 node 分发镜像地址"),
     r("SEMA_NPM_REGISTRY", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 npm registry 地址"),
@@ -411,7 +411,7 @@ export const CONFIG_CATALOG = [
     r("SERVICE_AUTH_TOKEN", "auth", "secret", "共享 service token(写面门;缺席且未开 ALLOW_UNAUTHED_WRITES ⇒ 拒提交)", { danger: SEC }),
     r("SERVICE_AUTH_TOKENS", "auth", "secret", "per-system 凭据表(tok=system CSV;source 从凭据派生,绝不自报)", { danger: SEC }),
     r("SESSION_AUTO_TITLE", "orchestration", "boolean", "首次提交自动铸 session 标题(一次 cheap 调用)", { staticDefault: "true", danger: BILL, configKey: "sessionAutoTitle" }),
-    r("SESSION_BACKEND", "store", "enum", "session 店引擎(auto=探到 DB 用 DB,探不到回内存;回显=boot 解析后的真引擎)", { enumValues: SESSION_BACKENDS, danger: DATA, derivedDefaultNote: "缺席:显式 DB_BACKEND=mysql|pg ⇒ mysql,否则 memory", configKey: "sessionBackend", resolve: (c) => (c.sessionBackend === "tidb" ? "mysql" : c.sessionBackend) }),
+    r("SESSION_BACKEND", "store", "enum", "session 店引擎(auto=配了该引擎的坐标就用那只库、没配就是内存;配了而此刻连不上 ⇒ 在 STORE_LOCK_WAIT_MS 窗内重试、到窗拒启,绝不落内存;回显=boot 解析后的真引擎)", { enumValues: SESSION_BACKENDS, danger: DATA, derivedDefaultNote: "缺席:显式 DB_BACKEND=mysql|pg ⇒ mysql,否则 memory", configKey: "sessionBackend", resolve: (c) => (c.sessionBackend === "tidb" ? "mysql" : c.sessionBackend) }),
     r("SESSION_CACHE_TTL_SEC", "store", "number", "session 读缓存 TTL(秒;0=关)", { staticDefault: "300", configKey: "sessionCacheTtlSec" }),
     r("SESSION_EVENTS_HOT_MS", "limitsHttp", "number", "session SSE 订阅热探针间隔(ms)", { derivedDefaultNote: "缺席 ⇒ 200" }),
     r("SESSION_EVENTS_MAX_CONNS", "limitsHttp", "number", "session SSE 并发连接帽", { derivedDefaultNote: "缺席 ⇒ 256" }),
@@ -431,7 +431,7 @@ export const CONFIG_CATALOG = [
     r("SSH_PORT", "orchestration", "number", "ssh 端口", { derivedDefaultNote: "缺席 ⇒ 22" }),
     r("SSH_PRIVATE_KEY", "orchestration", "secret", "ssh 私钥(adapter 持有,绝不进 workspace)", { danger: SEC }),
     r("SSH_USER", "orchestration", "string", "ssh 用户(必需件)"),
-    r("STORE_LOCK_WAIT_MS", "store", "number", "local 数据根 LOCK 撞上活持锁人时的有界等待窗(ms;0=当场拒;到窗仍拿不到 ⇒ 原码拒启,永不放行第二个写者)", { staticDefault: "60000", danger: DATA, configKey: "storeLockWaitMs" }),
+    r("STORE_LOCK_WAIT_MS", "store", "number", "store 启动期的有界等待窗(ms):local 数据根 LOCK 撞上活持锁人,或已配置的 SQL 库此刻连不上 / 建表失败;0=当场拒;到窗仍开不了 ⇒ 拒启(local 保持原码,永不放行第二个写者;SQL 点名后端与 host:port,永不退成内存)", { staticDefault: "60000", danger: DATA, configKey: "storeLockWaitMs" }),
     r("STORE_PROBE_INTERVAL_MS", "store", "number", "/health 活体 store 后台探针间隔(ms;0=显式关;仅 SQL 后端挂环)", { staticDefault: "15000", configKey: "storeProbeIntervalMs" }),
     r("STREAM_APPROVAL_ADHOC_GRACE_MS", "approval", "number", "流内审批 adhoc 腿窗后宽限(ms;须 window+grace < orphanTtl,破坏形拒启)", { staticDefault: "60000" }),
     r("STREAM_APPROVAL_ADMIT_MAX_PER_OWNER", "approval", "number", "流内审批 per-owner 未决帽", { staticDefault: "256" }),

package/dist/config-lkg.d.ts

@@ -11,11 +11,37 @@ export interface PersistedLkg {
 /** skill 正文的 content-addressed 盘缓存目录(LKG 的姊妹面):LKG 只含 skills MANIFEST(正文按
  *  hash 另拉)——黑洞中心下 LKG-boot 会在 skill 正文拉取上再挂数秒(live 实测 +5.3s)。正文按
  *  `<dir>/<sha-hex>` 落盘,读侧**必验 hash**(content-addressed 的全部意义;坏文件=忽略重拉)。 */
-export declare function defaultSkillCacheDir(): string;
-/** 默认路径(scheduler store 同门:SEMA_CONFIG_DIR → ~/.sema),按「worker + 凭证身份」分箱。`CONFIG_LKG_PATH`
- *  覆写(单一路径 ⇒ 不分箱,信封的 worker + identity 核仍守读回);`CONFIG_LKG_ENABLED=false` 关闭(读写双关)。
+export declare function defaultSkillCacheDir(config: {
+    readonly agentConfigDir?: string;
+}): string;
+/** 默认路径(scheduler store 同门:配置根 = 配置席 `agentConfigDir` → ~/.sema,{@link configRootOf}),按「worker + 凭证身份」分箱。`CONFIG_LKG_PATH`
+ *  覆写(`config.configLkgPath`,读法 {@link lkgPathOverrideOf};单一路径 ⇒ 不分箱,信封的 worker + identity 核仍守读回);`CONFIG_LKG_ENABLED=false` 关闭(读写双关)。
  *  🪦 正名前的 `CONFIG_LKG_DISABLED` 自 server 3.0.0 起是**fail-loud 墓碑**——设了(任何值)即拒启并指路新名,不再被读取。 */
-export declare function defaultLkgPath(worker: string | undefined, identity: string): string;
+export declare function defaultLkgPath(config: {
+    readonly agentConfigDir?: string;
+}, worker: string | undefined, identity: string): string;
+/**
+ * `CONFIG_LKG_PATH`(LKG 落盘路径覆写)的**唯一读法**:没设 ⇒ `undefined`(LKG 落在配置根下按箱派生,{@link defaultLkgPath});设了 ⇒ 绝对路径
+ * (相对值按进程 cwd 解,与文件被打开时同一个解法);空串 ⇒ 拒(起服拒):空串解出来是进程工作目录本身 —— 一条落盘路径不该是一个目录,
+ * 由它派生的读拒行({@link lkgReadDenyRows})会把整个工作目录读拒掉。`loadConfig` 调它铸 `configLkgPath`,读者只读那一席。
+ */
+export declare function lkgPathOverrideOf(raw: string | undefined): string | undefined;
+/**
+ * LKG(含凭据)实际所在位置的**读拒行** —— 一条规则:读拒从 LKG 落在哪派生,不写死位置。
+ *  · 没覆写 ⇒ LKG 落在配置根下(`config-lkg-<箱>.json`):引擎内建表的 `~/.sema/config-lkg-*.json` 行在家目录与声明的根(`agentConfigDir`,
+ *    根经链接时引擎连目标一起守)两处守它 ⇒ 不另加行(加了就是同一个文件两只判据,`READ_DENY_BUILTIN_EXCLUDE` 删那一行也删不掉它);
+ *  · 覆写 ⇒ LKG 在配置根外,引擎那一行够不着 ⇒ 这里派生行:它的**两种拼法**各一行 —— 覆写写下的绝对路径,与文件真正落的地方(路径经符号链接的
+ *    目录时,写进去的文件在链接目标下;只守拼写的话读真实路径就绕过了 —— 车内复审 [high])。两者相同 ⇒ 一行。大小写不敏感(与内建行同读法)。
+ *    拒句与内建行同一句(`sensitive-path read deny list (pattern …)`)。
+ *    **行的射程**(引擎读拒表的读法,不是本函数选的):行是路径段串 —— 引擎去掉开头的 `/`、不锚到根,这串段在任意深度出现即拒(大小写不敏感),
+ *    所以挡的不止 LKG 那一个文件:用户仓里同段串的路径(`/app/config-lkg.json` ⇒ `…/app/config-lkg.json`)一并读不到、Grep 结果里也不出现。
+ *    挡多了优于不挡;引擎提供锚定单文件的行之前如此(随包文案 MIGRATION / 目录行同句)。
+ * 读者:部署姿态座席族(`boot/runner-deps.ts` `buildDeploymentPostureSeats` 的 `readDenyPatterns` 席 = 运维的行 ∪ 本函数的行)—— 每次铸席现解一次链接。
+ */
+export declare function lkgReadDenyRows(configLkgPath: string | undefined): {
+    pattern: string;
+    caseSensitive: boolean;
+}[];
 /** 原子落盘一个干净候选(tmp+rename,0600)。BEST-EFFORT:失败=一条 warn 的素材(调用方发),绝不
  *  影响在飞的应用链——LKG 缓存丢失的代价只是下次冷启动回到 env 兜底。 */
 export declare function saveLkg(path: string, worker: string | undefined, identity: string, effective: Record<string, unknown>, etag: string | undefined): Promise<void>;
@@ -31,7 +57,9 @@ export declare function loadLkg(path: string, worker: string | undefined, identi
     reason: string;
 }>;
 /** 7.98.0 及以前的默认 LKG 路径(按当时的写法逐字保留 —— 这是盘上已有文件的名字,不是现行分箱规则)。 */
-export declare function legacyV1LkgPath(worker: string | undefined): string;
+export declare function legacyV1LkgPath(config: {
+    readonly agentConfigDir?: string;
+}, worker: string | undefined): string;
 export type LegacyLkgMigration = {
     readonly outcome: "none";
 }

package/dist/config-lkg.js

@@ -1,15 +1,60 @@
-import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { promises as fs, lstatSync, realpathSync } from "node:fs";
+import { basename, join, dirname, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
 import { validatePromptsDomain } from "./prompts-domain-validate.js";
 import { centerStateBin, pullTokenIdentity } from "./center-credential.js";
-export function defaultSkillCacheDir() {
-    return join(process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema"), "skill-cache");
+import { configRootOf } from "./sema-config-dir.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+export function defaultSkillCacheDir(config) {
+    return join(configRootOf(config), "skill-cache");
 }
-export function defaultLkgPath(worker, identity) {
-    const dir = process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema");
-    return join(dir, `config-lkg-${centerStateBin(worker, identity)}.json`);
+export function defaultLkgPath(config, worker, identity) {
+    return join(configRootOf(config), `config-lkg-${centerStateBin(worker, identity)}.json`);
+}
+export function lkgPathOverrideOf(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "") {
+        throw new Error('env CONFIG_LKG_PATH="" is empty — refusing to start: an empty path resolves to the working directory itself, which is no file the last-known-good ' +
+            "config can be kept in. Unset the variable to keep the LKG below the configuration root (SEMA_CONFIG_DIR, default ~/.sema), or set it to the file path you mean.");
+    }
+    return resolve(raw);
+}
+export function lkgReadDenyRows(configLkgPath) {
+    if (configLkgPath === undefined)
+        return [];
+    return [...new Set([configLkgPath, landedPathOf(configLkgPath)])].map((pattern) => ({ pattern, caseSensitive: false }));
+}
+function landedPathOf(p) {
+    const rest = [];
+    let landed = p;
+    let unresolved;
+    for (let head = p;; head = dirname(head)) {
+        try {
+            landed = join(realpathSync(head), ...rest);
+            break;
+        }
+        catch {
+            if (unresolved === undefined && head !== p && segmentPresent(head))
+                unresolved = head;
+            if (dirname(head) === head)
+                break;
+            rest.unshift(basename(head));
+        }
+    }
+    if (unresolved !== undefined)
+        recordFailOpen("server.config-lkg.landed-path-unresolved", `segment=${unresolved}`);
+    return landed;
+}
+function segmentPresent(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        return code !== "ENOENT" && code !== "ENOTDIR";
+    }
 }
 export async function saveLkg(path, worker, identity, effective, etag) {
     const body = { formatVersion: 2, savedAt: new Date().toISOString(), worker: worker ?? "global", identity, ...(etag !== undefined ? { etag } : {}), effective };
@@ -79,10 +124,9 @@ function lkgPayloadProblem(effective, etag) {
         return "prompts face fails re-validation";
     return undefined;
 }
-export function legacyV1LkgPath(worker) {
-    const dir = process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema");
+export function legacyV1LkgPath(config, worker) {
     const key = (worker ?? "global").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64);
-    return join(dir, `config-lkg-${key}.json`);
+    return join(configRootOf(config), `config-lkg-${key}.json`);
 }
 export async function migrateV1Lkg(o) {
     const refuse = (why) => ({

package/dist/config-types.d.ts

@@ -1994,6 +1994,13 @@ export interface ServiceConfigFlat {
      *  `READ_DENY_BUILTIN_EXCLUDE`=逗号分隔;不在表里的行名 / 空串**启动期响亮拒**。
      *  🔴 不变量(判据帖 G5b):删内建**绝不**削弱任务自己显式声明的 deny —— 那是另一层(additions)。 */
     readDenyBuiltinExclude?: readonly string[];
+    /** core 7.46.0 #1419:部署**声明**的配置根(`SEMA_CONFIG_DIR`,绝对路径;起服的供给动作建出目录,能不能用由引擎判)—— 交引擎 `RunnerDeps.agentConfigDir`
+     *  与守卫集 `createSensitivePathPolicy` 的同名入参:内建读拒表里以 `.sema` 开头的行在这个根下同样拒,写进根下要问一次。缺席 = 没声明
+     *  ⇒ 引擎读字面 `~/.sema`(与 LKG / skill 缓存 / scheduler 店的缺省落点同一处)。读法单一属主 `sema-config-dir.ts`。 */
+    agentConfigDir?: string;
+    /** LKG 落盘路径的覆写(`CONFIG_LKG_PATH`,绝对路径;单一读法 `config-lkg.ts` `lkgPathOverrideOf`)。缺席 = LKG 落在配置根下按箱派生。
+     *  读者:LKG 的落盘 / 读回(`boot/config-center.ts`)与读拒行(部署姿态座席族 —— LKG 在哪,读拒就守哪,`lkgReadDenyRows`)。 */
+    configLkgPath?: string;
     /** Structured log level. */
     logLevel: "debug" | "info" | "warn" | "error";
     /** Per-principal request cap per minute on task/run endpoints. 0 disables. */
@@ -2127,7 +2134,7 @@ export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled"
  *  config 这一层它只是一句声明。 */
 export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "compliancePosture" | "lockedConfigKeys" | "configCatalogEnabled" | "retentionPolicy" | "retentionSweep" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "authBridgeIssuer" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
-export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "remoteExecHomeDir" | "requireExecutionLane" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "hooksTimeoutMs" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "sessionAutoTitleSource" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "lspEnvAllow" | "imageBakes" | "readFace" | "readFaceSource" | "taskWriteFaceEscalation" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude">;
+export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "remoteExecHomeDir" | "requireExecutionLane" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "hooksTimeoutMs" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "sessionAutoTitleSource" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "lspEnvAllow" | "imageBakes" | "readFace" | "readFaceSource" | "taskWriteFaceEscalation" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "agentConfigDir" | "configLkgPath">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */
 export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "drainSecondSignalMinGapMs" | "sighupIdleGraceMs" | "parentPid" | "engineAutoExit" | "engineLingerMs" | "engineOrphanLingerMs" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
 /** 组:observability(可观测)。 */