@sema-agent/server 1.323.0 → 2.0.0

package/dist/config-center/restart-signal.d.ts

@@ -1,12 +1,34 @@
 import type { EffectiveConfig } from "./types.js";
 export type RestartSlice = "skills" | "mcp" | "scenarios" | "runtime-gates" | "models-tiers";
+/** Structured restart signal an orchestrator consumes (GET /health → `restart`). Change-detected against the
+ *  process's BOOT config, NOT presence — so it stays absent when nothing baked-at-boot changed (presence would
+ *  re-fire every refresh → a restart LOOP). `restartRequired` is always true when this object exists. */
 export interface RestartSignal {
     restartRequired: true;
+    /** Which restart-to-apply slices differ from the value baked at boot. */
     reasons: RestartSlice[];
+    /** The sema-registry version that currently differs from boot (latest seen). */
     version: number;
+    /** Epoch ms when this restart first became required (stable across refreshes while `reasons` is unchanged). */
     since: number;
 }
+/** Restart-to-apply slices that DIFFER between this process's BOOT config and a freshly-pulled one. Empty =
+ *  nothing baked-at-boot changed (only hot-apply slices moved, or nothing) → no restart needed. An orchestrator
+ *  can auto rolling-restart on a non-empty result WITHOUT a restart loop, because the comparison is always
+ *  against boot (a refresh that re-fires the same diff is idempotent, not a fresh trigger). */
 export declare function restartReasons(boot: EffectiveConfig | undefined, current: EffectiveConfig): RestartSlice[];
+/** codex R10 (models-tiers 窗收口): TRUE when the MODEL PLANE (enabled models + active tier table + resolved
+ *  default) of `next` differs from the last-APPLIED plane `prev`. Under a tier-frozen Runner (tiers non-empty at
+ *  construction → private expanded copy) main.ts DEFERS the whole plane mutation until restart when this is true —
+ *  admission (/v1/models, the catalog gates) and the Runner then stay on ONE generation through the restart
+ *  window, so a same-key retarget can never silently route/bill the stale Model object. `prev === undefined`
+ *  (env-boot plane, no EffectiveConfig to compare) is conservatively "changed" — one deferred adoption + restart
+ *  converges. Deliberately NOT gated on tier activity of either side (unlike the restart slice): a frozen Runner
+ *  goes stale on ANY plane change, including a tiers-off flip. */
+/** codex R12: TRUE when this candidate resolves an ACTIVE tier table. Used by main.ts's defer predicate — a
+ *  tier-less-booted Runner never re-runs expandTiers, so hot-applying an ARRIVING tier table splits admission
+ *  (tier words pass the expanded gate) from execution (core throws "Unknown model ref"). Hot-apply of the model
+ *  plane is safe only when BOTH the constructed generation and the candidate are tier-less. */
 export declare function planeHasActiveTiers(eff: EffectiveConfig): boolean;
 export declare function modelPlaneChanged(prev: EffectiveConfig | undefined, next: EffectiveConfig): boolean;
 //# sourceMappingURL=restart-signal.d.ts.map

package/dist/config-center/restart-signal.js

@@ -1,6 +1,15 @@
+/**
+ * Restart-to-apply CHANGE detection — the structured `RestartSignal` an orchestrator consumes (GET /health →
+ * `restart`), computed against the process's BOOT config (not presence, else a refresh would re-fire the same
+ * diff and loop-restart). Also owns the model-plane deferral predicates (`planeHasActiveTiers`/
+ * `modelPlaneChanged`) main.ts uses to decide whether a hot-apply is safe under a tier-frozen Runner. Split out
+ * of `sema-registry.ts` (design/158 A13, internal-lossless — the facade re-exports every symbol below unchanged).
+ */
 import { resolveActiveTiers } from "@sema-agent/registry-core";
 import { RUNTIME_GATE_KEYS, runtimeGatePresent, resolveDefaultModelName } from "./apply-effective.js";
 const RESTART_SLICES = ["skills", "mcp", "scenarios", "runtime-gates", "models-tiers"];
+/** Canonical, key-sorted JSON (array order preserved) so two semantically-equal effective slices fingerprint
+ *  identically regardless of object key order from the center serializer. */
 function stableStringify(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v) ?? "null";
@@ -12,6 +21,11 @@ function stableStringify(v) {
         .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`)
         .join(",")}}`;
 }
+/** The comparable value of one restart-to-apply slice (undefined config / unpublished slice → null, so
+ *  "center started/stopped publishing skills" is itself a detectable change). Skills/MCP/scenarios fingerprint
+ *  ONLY the ENABLED entries — the runtime consumers (applyCenterSkills / resolveMcpServers / centerScenarios) skip
+ *  `enabled:false`, so a disabled entry's content has zero runtime effect and must NOT trigger a restart.
+ *  Every enable/disable FLIP still changes the filtered set → still triggers, correctly. */
 function enabledOnly(rows) {
     if (!rows)
         return null;
@@ -38,19 +52,44 @@ function restartSliceValue(eff, slice) {
             return Object.keys(present).length ? present : null;
         }
         case "models-tiers": {
+            // Fingerprint the models+tiers pair ONLY when this side resolves an active tier table (the Runner-copy
+            // decoupling only exists under tiers). Tier-less side → null: both sides tier-less never signals (hot-apply
+            // is real there); a tiers on/off FLIP is itself a detectable change (null vs object) — correctly signals,
+            // because the flip only takes effect at Runner construction.
             const active = eff.models ? resolveActiveTiers(eff.models) : undefined;
             if (!active || Object.keys(active).length === 0)
                 return null;
             const enabled = enabledOnly(eff.models?.models);
+            // codex R8: the resolved DEFAULT rides the fingerprint too — the Runner's frozen copy carries its own
+            // boot-time `default` entry, so a refresh that ONLY moves the default source (models.default /
+            // roles.default / tier binding) re-points config.models.default while spec.model="default" keeps routing
+            // the stale Runner entry. SAME resolver as applyEffective (resolveDefaultModelName, single source);
+            // dangling candidates fall through silently here — applyEffective owns the warn.
             const names = new Set((enabled ?? []).map((m) => m.name));
             const def = resolveDefaultModelName(eff, (n) => names.has(n), enabled?.[0]?.name ?? "");
             return { models: enabled, tiers: active, default: def.name };
         }
     }
 }
+/** Restart-to-apply slices that DIFFER between this process's BOOT config and a freshly-pulled one. Empty =
+ *  nothing baked-at-boot changed (only hot-apply slices moved, or nothing) → no restart needed. An orchestrator
+ *  can auto rolling-restart on a non-empty result WITHOUT a restart loop, because the comparison is always
+ *  against boot (a refresh that re-fires the same diff is idempotent, not a fresh trigger). */
 export function restartReasons(boot, current) {
     return RESTART_SLICES.filter((s) => stableStringify(restartSliceValue(boot, s)) !== stableStringify(restartSliceValue(current, s)));
 }
+/** codex R10 (models-tiers 窗收口): TRUE when the MODEL PLANE (enabled models + active tier table + resolved
+ *  default) of `next` differs from the last-APPLIED plane `prev`. Under a tier-frozen Runner (tiers non-empty at
+ *  construction → private expanded copy) main.ts DEFERS the whole plane mutation until restart when this is true —
+ *  admission (/v1/models, the catalog gates) and the Runner then stay on ONE generation through the restart
+ *  window, so a same-key retarget can never silently route/bill the stale Model object. `prev === undefined`
+ *  (env-boot plane, no EffectiveConfig to compare) is conservatively "changed" — one deferred adoption + restart
+ *  converges. Deliberately NOT gated on tier activity of either side (unlike the restart slice): a frozen Runner
+ *  goes stale on ANY plane change, including a tiers-off flip. */
+/** codex R12: TRUE when this candidate resolves an ACTIVE tier table. Used by main.ts's defer predicate — a
+ *  tier-less-booted Runner never re-runs expandTiers, so hot-applying an ARRIVING tier table splits admission
+ *  (tier words pass the expanded gate) from execution (core throws "Unknown model ref"). Hot-apply of the model
+ *  plane is safe only when BOTH the constructed generation and the candidate are tier-less. */
 export function planeHasActiveTiers(eff) {
     const active = eff.models ? resolveActiveTiers(eff.models) : undefined;
     return active !== undefined && Object.keys(active).length > 0;

package/dist/config-center/skills-mcp.d.ts

@@ -3,11 +3,30 @@ import type { ScopedMcpServer } from "../config-types.js";
 import type { Logger } from "../observability/logger.js";
 import type { LoadedSkill } from "../capabilities/skills.js";
 import type { CenterMcpServer, CenterSkillManifest } from "./types.js";
+/**
+ * Merge center skills OVER the image baseline (design/41-sibling B1; `docs/MCP-SKILLS.md`). Load order =
+ * `loadSkills(SKILLS_DIR)` baseline → center skills lazily fetched by hash and overlaid BY NAME (center
+ * wins on a clash → can override a built-in; guarded center-side by publisher RBAC + the publish gate).
+ * `enabled:false` is skipped. Content is verified + cached by hash (same hash fetched once). A skill whose
+ * content fetch/verify fails is skipped (the baseline version, if any, stays) — never blocks startup.
+ * Restart-to-apply: this runs at boot, before `buildScenarios` bakes skills into scenarios.
+ */
 export declare function applyCenterSkills(baseline: LoadedSkill[], manifest: {
     skills: CenterSkillManifest[];
-}, baseUrl: string, token: string, logger?: Logger, fetchImpl?: typeof fetch, diskCacheDir?: string): Promise<LoadedSkill[]>;
+}, baseUrl: string, token: string, logger?: Logger, fetchImpl?: typeof fetch, 
+/** LKG 姊妹面(clay 拍 2026-07-18):skill 正文的 content-addressed 盘缓存目录。读序=内存→盘(验
+ *  hash,坏文件忽略)→中心(成功后 best-effort 回写)。让 LKG-boot 在中心不可达时不再于正文拉取上
+ *  挂数秒(live 实测黑洞 +5.3s/skill 批),顺带省正常 refresh 的重复拉取。undefined=无盘缓存(原行为)。 */
+diskCacheDir?: string): Promise<LoadedSkill[]>;
+/**
+ * Resolve center MCP servers (`/effective.mcp`) into core `McpServerSpec`s + the scenarios each applies to.
+ * env-NAME refs → real values from THIS service's env (secret boundary unchanged); a server with any missing
+ * ref is skipped (`resolveRefs` → null). `enabled:false` skipped. Restart-to-apply (filtered per scenario in
+ * `resolveSpec` via `mcpForScenario`).
+ */
 export declare function resolveMcpServers(mcp: {
     servers: CenterMcpServer[];
 }, logger?: Logger): ScopedMcpServer[];
+/** The MCP servers applicable to a scenario: tagged with it, or untagged (global). undefined when none. */
 export declare function mcpForScenario(servers: ScopedMcpServer[] | undefined, scenario: string): McpServerSpec[] | undefined;
 //# sourceMappingURL=skills-mcp.d.ts.map

package/dist/config-center/skills-mcp.js

@@ -1,6 +1,25 @@
+/**
+ * Two small consumption lanes that both project a center manifest domain onto a per-request runtime shape:
+ * skills application (`applyCenterSkills` — merge center skills OVER the image baseline, content-addressed
+ * fetch+verify+cache) and MCP server resolution (`resolveMcpServers`/`mcpForScenario` — env-NAME ref
+ * resolution + per-scenario filtering). Split out of `sema-registry.ts` (design/158 A13, internal-lossless —
+ * the facade re-exports every symbol below unchanged).
+ */
 import { skillContentHash } from "@sema-agent/registry-core";
 import { fetchSkillContent } from "./http-client.js";
-export async function applyCenterSkills(baseline, manifest, baseUrl, token, logger, fetchImpl = fetch, diskCacheDir) {
+/**
+ * Merge center skills OVER the image baseline (design/41-sibling B1; `docs/MCP-SKILLS.md`). Load order =
+ * `loadSkills(SKILLS_DIR)` baseline → center skills lazily fetched by hash and overlaid BY NAME (center
+ * wins on a clash → can override a built-in; guarded center-side by publisher RBAC + the publish gate).
+ * `enabled:false` is skipped. Content is verified + cached by hash (same hash fetched once). A skill whose
+ * content fetch/verify fails is skipped (the baseline version, if any, stays) — never blocks startup.
+ * Restart-to-apply: this runs at boot, before `buildScenarios` bakes skills into scenarios.
+ */
+export async function applyCenterSkills(baseline, manifest, baseUrl, token, logger, fetchImpl = fetch, 
+/** LKG 姊妹面(clay 拍 2026-07-18):skill 正文的 content-addressed 盘缓存目录。读序=内存→盘(验
+ *  hash,坏文件忽略)→中心(成功后 best-effort 回写)。让 LKG-boot 在中心不可达时不再于正文拉取上
+ *  挂数秒(live 实测黑洞 +5.3s/skill 批),顺带省正常 refresh 的重复拉取。undefined=无盘缓存(原行为)。 */
+diskCacheDir) {
     const { promises: fsp } = await import("node:fs");
     const { join: joinPath } = await import("node:path");
     const diskRead = async (hash) => {
@@ -8,17 +27,21 @@ export async function applyCenterSkills(baseline, manifest, baseUrl, token, logg
             return undefined;
         const hex = hash.replace(/^sha256:/, "");
         if (!/^[0-9a-f]{64}$/.test(hex))
-            return undefined;
+            return undefined; // hash 形不对=不碰盘(路径安全)
         try {
             const text = await fsp.readFile(joinPath(diskCacheDir, hex), "utf8");
             if (skillContentHash(text) === hash)
-                return text;
+                return text; // content-addressed:必验,坏文件=undefined 走中心
             logger?.warn("sema_registry_skill_cache_corrupt", { hash, note: "on-disk body fails its own hash — ignored, refetching from center" });
         }
         catch {
+            /* absent/unreadable → center */
         }
         return undefined;
     };
+    // F5(LKG 复审三轮):写盘 promises 收集、函数返回前 await——fire-and-forget 会让 persistLkgDurable
+    // 的「先落正文再发信号」序失效(await 只等到 fetch,rename 还在飞,窗口内重启=离线 boot 缺 skill)。
+    // 单写失败仍 warn 软降级(收集的是 catch 过的 promise,Promise.all 不会炸)。
     const pendingWrites = [];
     const diskWrite = (hash, content) => {
         if (!diskCacheDir)
@@ -32,8 +55,8 @@ export async function applyCenterSkills(baseline, manifest, baseUrl, token, logg
         })().catch((err) => logger?.warn("sema_registry_skill_cache_write_failed", { hash, err: String(err) })));
     };
     const byName = new Map(baseline.map((s) => [s.spec.name, s]));
-    const contentCache = new Map();
-    const seenNames = new Set();
+    const contentCache = new Map(); // content-addressed: same hash fetched once
+    const seenNames = new Set(); // duplicate names WITHIN the center manifest collapse last-wins — warn so a bad publish is diagnosable
     for (const m of manifest.skills ?? []) {
         if (m.enabled === false)
             continue;
@@ -46,7 +69,7 @@ export async function applyCenterSkills(baseline, manifest, baseUrl, token, logg
                 content = await diskRead(m.contentHash);
             if (content === undefined) {
                 content = await fetchSkillContent(baseUrl, token, m.contentHash, fetchImpl);
-                diskWrite(m.contentHash, content);
+                diskWrite(m.contentHash, content); // best-effort 回写(content-addressed,幂等)
             }
             contentCache.set(m.contentHash, content);
             const overrodeBuiltin = byName.has(m.name);
@@ -57,9 +80,12 @@ export async function applyCenterSkills(baseline, manifest, baseUrl, token, logg
             logger?.warn("sema_registry_skill_failed", { name: m.name, hash: m.contentHash, err: String(err), note: "keeping baseline if any; skipping center version" });
         }
     }
-    await Promise.all(pendingWrites);
+    await Promise.all(pendingWrites); // F5:返回=正文已 durable(或已 warn),调用方的落盘序才成立
     return [...byName.values()];
 }
+/** Resolve env-NAME refs (target-key → ENV_NAME) to real values from THIS service's env. Returns null when
+ *  ANY referenced env var is unset → the caller skips the whole server (fail-safe: never wire a half-credentialed
+ *  endpoint). Mirrors the missing-apiKeyEnv handling for models (the secret boundary is unchanged). */
 function resolveRefs(refs, server, kind, logger) {
     if (!refs)
         return {};
@@ -74,12 +100,20 @@ function resolveRefs(refs, server, kind, logger) {
     }
     return out;
 }
+/**
+ * Resolve center MCP servers (`/effective.mcp`) into core `McpServerSpec`s + the scenarios each applies to.
+ * env-NAME refs → real values from THIS service's env (secret boundary unchanged); a server with any missing
+ * ref is skipped (`resolveRefs` → null). `enabled:false` skipped. Restart-to-apply (filtered per scenario in
+ * `resolveSpec` via `mcpForScenario`).
+ */
 export function resolveMcpServers(mcp, logger) {
     const out = [];
     for (const s of mcp.servers ?? []) {
         if (s.enabled === false)
             continue;
         const allow = s.allowTools && s.allowTools.length > 0 ? { allowTools: s.allowTools } : {};
+        // E23 (shell-host contract): carry the per-server inbound-elicitation opt-in onto McpServerSpec.elicitation. Only when
+        // explicitly true (default OFF / fail-closed) — core advertises the capability only when this AND onElicit hold.
         const elicit = s.elicitation === true ? { elicitation: true } : {};
         if (s.transport.kind === "stdio") {
             const env = resolveRefs(s.transport.envRefs, s.name, "env", logger);
@@ -104,6 +138,7 @@ export function resolveMcpServers(mcp, logger) {
         logger?.info("sema_registry_mcp", { servers: out.map((s) => s.spec.name) });
     return out;
 }
+/** The MCP servers applicable to a scenario: tagged with it, or untagged (global). undefined when none. */
 export function mcpForScenario(servers, scenario) {
     if (!servers || servers.length === 0)
         return undefined;

package/dist/config-center/types.d.ts

@@ -1,3 +1,10 @@
+/**
+ * config-center wire types — the sema-registry `/api/config/effective` payload shapes (`CenterModel`,
+ * `CenterTeam`, `CenterSkillManifest`, `CenterMcpServer`, `EffectiveConfig`) plus the per-principal
+ * execution/session-mirror ruling shapes riding the caps view (`ExecutionRuling`/`SessionMirrorRuling`).
+ * Pure type/interface declarations — no runtime logic. Split out of `sema-registry.ts` (design/158 A13,
+ * internal-lossless: the facade re-exports every symbol below unchanged).
+ */
 import type { CollabTemplateWire } from "../capabilities/collab-wire.js";
 import type { Autonomy, CommandRule } from "../runtime-governance.js";
 export interface CenterModel {
@@ -7,6 +14,10 @@ export interface CenterModel {
     api: "openai-completions" | "anthropic-messages";
     baseUrl?: string;
     apiKeyEnv?: string;
+    /** registry-core 0.10.5 sealed-box 托管密文(浏览器端 crypto_box_seal 封给执行域公钥,center
+     *  只存密文)。执行侧按 publicKeyId 精确选本机私钥解封 → 明文进内存 key 管道(config.modelApiKeys)。
+     *  互斥语义(契约):与 apiKeyEnv 双设 = sealed 优先,且解封失败**不回落** env 引用(fail-loud,见
+     *  applyEffective)。🔴 ciphertext 绝不进任何日志(registry-core write-only 纪律的执行侧半场)。 */
     sealedApiKey?: {
         ciphertext: string;
         publicKeyId: string;
@@ -18,7 +29,12 @@ export interface CenterModel {
     vision?: boolean;
     contextWindow?: number;
     maxTokens?: number;
+    /** [818]① 1M dual-window (core 1.289 `Model.autoCompactTokens`): an EXPLICIT roster value wins the
+     *  contextWindow derivation in toModel (applyAutoCompactWindow). Declared on the type face (codex F5) so the
+     *  config-provider local-lane projection carries it — toModel keeps its structural read for older shapes. */
     autoCompactTokens?: number;
+    /** design/123 D2 (core 1.226): chars ≈ 1 token for this model's tokenizer, feeding every structural
+     *  (non-usage-anchored) token estimate. CJK-heavy models should declare 2–3; absent → env default → core 4. */
     charsPerToken?: number;
     cost?: {
         input: number;
@@ -26,10 +42,26 @@ export interface CenterModel {
         cacheRead?: number;
         cacheWrite?: number;
     };
+    /** registry-core 0.6.0 配额倍率(models 域 ModelEntry.quotaWeight,缺省=1):weight-at-burn——
+     *  记账时固化进 UsageEntry.{weightedTokens,quotaWeightAtUse} 与 lease weightedTokens 轴;改倍率只影响
+     *  此后记账,不回算窗口内历史(registry types.d.ts 同句契约)。 */
     quotaWeight?: number;
+    /** design/111 L2②: per-model declarative thinking config (center roster). defaultThinking = this model's DEFAULT
+     *  tier (resolution chain spec.thinking ?? role.thinking ?? model.defaultThinking); reasoningEffortLevels (openai
+     *  endpoints) = tiers the endpoint accepts. Validated against core's ThinkingLevel in toModel; "off" is dropped. */
     defaultThinking?: string;
     reasoningEffortLevels?: string[];
+    /** Generation-tuning passthrough, mirrors core `Model.extraBody` (1.60) — e.g. frequency/presence
+     *  penalties that *prevent* degenerate looping. Same category as `cost`/`tier`: logical model metadata,
+     *  no secrets. Carried through `toModel()` verbatim. When a center roster replaces the env model this is
+     *  the ONLY way to keep per-model tuning that lived in env (`MODEL_FREQUENCY_PENALTY` etc.) — see the
+     *  review-gw heterogeneous-roster migration. MUST be static per published version (prompt-cache prefix). */
     extraBody?: Record<string, unknown>;
+    /** registry-core 0.10.13 ([1002]/[998]⑤c): per-model behavior-slot mitigation sentences, mirrors core
+     *  `Model.promptGuidance` (core 1.303+ assembles them into the volatile tail's per-model position).
+     *  Same category as `extraBody`: logical model metadata, carried verbatim — without this projection the
+     *  configured sentences parse fine in registry-core but never reach the assembly face ([1028]① 排雷:
+     *  the missing leg made every promptGuidance pilot a false control). */
     promptGuidance?: string[];
     enabled?: boolean;
 }
@@ -56,6 +88,7 @@ export interface CenterTeam {
     maxTranscriptTokens?: number;
     enabled?: boolean;
 }
+/** Skill MANIFEST entry (content is NOT inline — fetched by hash; see `fetchSkillContent`). */
 export interface CenterSkillManifest {
     name: string;
     description: string;
@@ -63,18 +96,27 @@ export interface CenterSkillManifest {
     contentHash: string;
     enabled?: boolean;
 }
+/** MCP server registry entry. `envRefs`/`headerRefs` are env-NAME refs (target-key → ENV_NAME), NOT secrets. */
 export interface CenterMcpServer {
     name: string;
     scenarios: string[];
     enabled?: boolean;
     allowTools?: string[];
+    /** E23 (shell-host contract): opt THIS server into INBOUND elicitation — it may ask the END USER for input mid-tool-call.
+     *  Maps to `McpServerSpec.elicitation`; core advertises the capability ONLY when this is true AND the service wired
+     *  `RunnerDeps.onElicit` (MCP_ELICITATION_ENABLED). Default OFF (omitted) — a server cannot pull a human into the
+     *  loop unless an operator explicitly opts it in. */
     elicitation?: boolean;
     transport: {
         kind: "stdio";
         command: string;
         args?: string[];
         envRefs?: Record<string, string>;
-    } | {
+    }
+    /** `principalHeader` (design/62): the header name into which the runner injects the task's authenticated
+     *  end-user principal per-task, so a consumer MCP (e.g. oa-mcp) can enforce per-user RBAC. Not a ref — a
+     *  literal header name. The runner fills the value (never the model). */
+     | {
         kind: "http";
         url: string;
         headerRefs?: Record<string, string>;
@@ -89,9 +131,15 @@ export interface EffectiveConfig {
         roles: Record<string, CenterRoleTarget>;
         atModelAllowlist?: string[];
     };
+    /** OPTIONAL since registry-core 0.7 deleted the teams domain: a 0.7+ center /effective payload
+     *  has NO teams key (collab is its successor). Absent/empty ⇒ registerTeams resets to BUILTIN_TEAMS (the
+     *  permanent builtin base). */
     teams?: {
         teams: CenterTeam[];
     };
+    /** registry-core 0.7 collab domain (teams' successor) — consumed by the slice-① read-only
+     *  projection (projectCollabToTeams → registerTeams). Both lanes carry it: the remote worker /effective view
+     *  ships collab, and local FileConfigStore reads config.d/collab.json (PORTABLE_DOMAINS includes collab). */
     collab?: {
         templates: CollabTemplateWire[];
     };
@@ -101,6 +149,11 @@ export interface EffectiveConfig {
     mcp?: {
         servers: CenterMcpServer[];
     };
+    /** Center-declared scenarios (composition-as-config; capability stays code-pinned): each entry names a
+     *  deploy-registered TOOLSET (`none` / `repo-readonly`) + an optional static prompt (≤4KB, audited at
+     *  publish). Restart-to-apply like skills/mcp (baked into the scenario table at boot). Center entries
+     *  MAY shadow built-in scenario names (clay 2026-06-11: usability first) — shadows are logged at boot.
+     *  Validation/registry live in capabilities/scenarios.ts `centerScenarios`. */
     scenarios?: {
         scenarios: Array<{
             name: string;
@@ -108,6 +161,9 @@ export interface EffectiveConfig {
             enabled?: boolean;
         }>;
     };
+    /** Fleet governance/limit gates (phase-2, center SERVICE-INTEGRATION「Runtime 治理/限额闸」). All restart-to-apply,
+     *  non-secret, all center `.optional()` (center `f95438a`): absent = unmanaged → keep env; present (incl. an
+     *  explicit 0/[] = "publish OFF") = override. Consumption precedence is in `applyRuntimeGates`. */
     runtime?: {
         rateLimitPerMin?: number;
         approvalRequire?: string[];
@@ -115,27 +171,62 @@ export interface EffectiveConfig {
         maxTaskTokens?: number;
         maxPrincipalCostUsd?: number;
         costQuotaWindowSec?: number;
+        /** Runtime governance second baton (center §10): autonomy mode + per-command rules. UNLIKE the 6 gates above,
+         *  these are per-request HOT (read live in resolveSpec, not baked into boot middleware) → applied on boot AND
+         *  refresh by `applyRuntimeHot` (NOT in RUNTIME_GATE_KEYS / restart-to-apply). Same presence rule (undefined =
+         *  unmanaged → keep). */
         autonomy?: Autonomy;
         commandPolicy?: CommandRule[];
     };
+    /** 142-S4(registry-core 0.10.0 第 15 域):center 项目登记簿。wire 面 verbatim JSON —
+     *  registry-core `ProjectsConfig` 的形状是 `{projects: Record<projectId, ProjectRegistration>}`(skills/mcp
+     *  同款域包裹),但本 interface 宽读两种形态(包裹/裸 Record——projectId 是 UUID,永远不会撞 "projects"
+     *  字面键,判包裹无歧义)。消费=applyEffective → config.projects(displayName/gitRemotes/defaultScopes
+     *  三个 runtime 字段;审计字段不进 ServiceConfig)。 */
     projects?: {
         projects?: Record<string, unknown>;
     } | Record<string, unknown>;
+    /** registry-core 0.6:治理三件(autonomy/commandPolicy/approvalRequire)拆新 governance 域=真值;
+     *  过渡期 effective 在 runtime 位双写镜像。读取优先 governance 新位、runtime 旧位 fallback(顺序契约:
+     *  消费端先切换、确认后 center 才撤双写,治理闸零 fail-open 窗口)。 */
     governance?: {
         autonomy?: Autonomy;
         commandPolicy?: CommandRule[];
         approvalRequire?: string[];
     };
+    /** plugins 域(registry-core 0.5 additive;契约冻结 [1361]②/[1362]/[1366]①,消费半场 2026-07-28
+     *  开工车):center 只存"插件从哪来"(PluginSpec 引用,永不承载可执行字节);worker 半场在
+     *  capabilities/center-plugins.ts `applyCenterPlugins`(https-only+ALLOW_HOSTS 纵深复验/sha 钉扎/
+     *  隔离 clone/LKG/撞名让位)。此前本 interface 无此键 ⇒ wire 上的 plugins 被 server 静默丢弃。 */
     plugins?: {
         plugins?: unknown[];
     };
+    /** prompts 域(additive key;双轴 wire=registry-core `EffectivePromptsWire` 或 legacy 平铺形——
+     *  server 侧判形/采用全在 capabilities/center-prompts.ts `validatePromptsDomain`,本 interface 只
+     *  声明键位存在(unknown:候选门是唯一解释者,这里不复刻形)。 */
     prompts?: unknown;
 }
+/** (stage7 P5,registry-core 0.8 `execution` 域): the center-resolved per-principal execution
+ *  ruling riding the caps view. `required=false` / ruling absent = no enforcement (legacy). `allowedLanes` is
+ *  an OPEN value domain (adding one is never BREAKING; consumers tolerate unknown names). Known lane names:
+ *  `host`/`e2b`/`k8s`/`ssh`/`adb`/`local-docker` (the REMOTE_EXEC providers) **plus `in-process`** — the
+ *  REMOTE_EXEC-unset fleet posture (OA/review-style workers; named distinctly from the explicit
+ *  `host` lane on purpose). ⚠️ Admins writing `required=true` policies must include `in-process` when such
+ *  workers should stay admittable — center UI/doc 词表待补齐。 */
 export interface ExecutionRuling {
     required: boolean;
     allowedLanes: string[];
+    /** registry-core 0.10.1-0.10.2:org 会话镜像策略,
+     *  execution 域收编字段,center 若把它附在 caps view 的 execution ruling 上则宽读透传(缺席=老
+     *  center/未配置 → undefined,零行为差)。**server 侧只做观测面,不是执法面**——「该镜像而未镜像」
+     *  的违规发生在数据产生端(壳),server 收不到该信号(论证见 http/server.ts sync/import 的
+     *  session_mirror audit 注释);本字段供 audit 日志/metrics 关联镜像到达与治理态。 */
     sessionMirror?: SessionMirrorRuling;
 }
+/** 两层形状(registry-core `SessionMirrorPolicy` 的消费侧镜像):`required:false`=便利默认值(壳解析
+ *  序第三腿);`required:true`=org 治理强制(镜像默认开且不可关,本地覆盖不生效——
+ *  org 压一切)。锁定执法在壳(CC managed-settings 心智,registry-core 域头注「required 的锁今天也是
+ *  CLIENT-SIDE 执法」);service 半场=观测。 */
 export interface SessionMirrorRuling {
     engineUrl: string;
     required: boolean;

package/dist/config-lkg.d.ts

@@ -1,3 +1,4 @@
+/** 落盘信封。`effective`/`etag` 逐字=当时的 fetchEffective 返回(JSON verbatim 面)。 */
 export interface PersistedLkg {
     formatVersion: 1;
     savedAt: string;
@@ -5,9 +6,20 @@ export interface PersistedLkg {
     etag?: string;
     effective: Record<string, unknown>;
 }
+/** 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)。`CONFIG_LKG_PATH` 覆写;
+ *  `CONFIG_LKG_ENABLED=false` 关闭(读写双关;design/158 B4 正名前叫 `CONFIG_LKG_DISABLED=true`,兼容期内仍认)。 */
 export declare function defaultLkgPath(worker: string | undefined): string;
+/** 原子落盘一个干净候选(tmp+rename,0600)。BEST-EFFORT:失败=一条 warn 的素材(调用方发),绝不
+ *  影响在飞的应用链——LKG 缓存丢失的代价只是下次冷启动回到 env 兜底。 */
 export declare function saveLkg(path: string, worker: string | undefined, effective: Record<string, unknown>, etag: string | undefined): Promise<void>;
+/**
+ * 读盘上 LKG。返回 undefined 的所有情形都「安静地回 env 兜底」(调用方 warn 点名 reason):
+ * 文件缺席/JSON 坏/信封形不对/worker 不匹配(防同名文件跨 worker 串包)/prompts 面复判失败。
+ */
 export declare function loadLkg(path: string, worker: string | undefined): Promise<{
     lkg: PersistedLkg;
 } | {

package/dist/config-lkg.js

@@ -1,16 +1,43 @@
+/**
+ * LKG 落盘(clay 拍,2026-07-18)——干净配置候选的本机持久化,boot 的第三级来源:
+ *   中心(预算窗内)> 盘上 LKG > env 兜底。
+ *
+ * 为什么存在(1.222.0 发版复审的残余环,clay 重裁量证据):boot 抢答窗让慢中心不再阻塞启动,但
+ * skills/mcp/scenarios/runtime-gates 四个 restart-to-apply 面是 boot 烤进进程的——配置迟到只能发
+ * restartRequired 信号。center 发布了这些面 + 中心**持续**慢于预算 + orchestrator 自动重启 ⇒ 每个
+ * 新进程都为真缺失的面发一次信号 = 反复重启环。盘上 LKG 让下一进程 boot 直读上一进程验证过的干净
+ * 候选(全部面进 buildScenarios),到货后与之比较通常零差异 ⇒ 无信号无环;中心恢复自然收敛。
+ * 白拿的第二收益:重启秒起且配置齐全(不再有「起服后几秒 roster pending」窗口)。
+ *
+ * 安全边界:config plane 恒只携带 env-NAME 引用(apiKeyEnv/tokenEnv/…),真实秘密从不入 effective
+ * ——落盘物按同一纪律无秘密;文件 0600 + 原子写(tmp+rename)。**只存干净候选**(候选门通过的:
+ * boot clean / refresh LKG advance / deferred clean),所以读侧只需防「文件坏形/被改」:JSON+信封
+ * 判形+prompts 面复判(validatePromptsDomain,与候选门同函数),任何不对 ⇒ 忽略文件走 env(warn
+ * 点名,绝不让坏缓存挡启动)。
+ *
+ * 范围:**remote lane only**——local lane 的 FileConfigStore 本来就是盘上即时读,无此需要。
+ * 文件按 worker 键控(`config-lkg-<worker|global>.json`),同宿主多 worker 不互踩。
+ */
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { validatePromptsDomain } from "./prompts-domain-validate.js";
+/** skill 正文的 content-addressed 盘缓存目录(LKG 的姊妹面):LKG 只含 skills MANIFEST(正文按
+ *  hash 另拉)——黑洞中心下 LKG-boot 会在 skill 正文拉取上再挂数秒(live 实测 +5.3s)。正文按
+ *  `<dir>/<sha-hex>` 落盘,读侧**必验 hash**(content-addressed 的全部意义;坏文件=忽略重拉)。 */
 export function defaultSkillCacheDir() {
     return join(process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema"), "skill-cache");
 }
+/** 默认路径(scheduler store 同门:SEMA_CONFIG_DIR → ~/.sema)。`CONFIG_LKG_PATH` 覆写;
+ *  `CONFIG_LKG_ENABLED=false` 关闭(读写双关;design/158 B4 正名前叫 `CONFIG_LKG_DISABLED=true`,兼容期内仍认)。 */
 export function defaultLkgPath(worker) {
     const dir = process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema");
     const key = (worker ?? "global").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64);
     return join(dir, `config-lkg-${key}.json`);
 }
+/** 原子落盘一个干净候选(tmp+rename,0600)。BEST-EFFORT:失败=一条 warn 的素材(调用方发),绝不
+ *  影响在飞的应用链——LKG 缓存丢失的代价只是下次冷启动回到 env 兜底。 */
 export async function saveLkg(path, worker, effective, etag) {
     const body = { formatVersion: 1, savedAt: new Date().toISOString(), worker: worker ?? "global", ...(etag !== undefined ? { etag } : {}), effective };
     const tmp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
@@ -18,6 +45,10 @@ export async function saveLkg(path, worker, effective, etag) {
     await fs.writeFile(tmp, JSON.stringify(body), { mode: 0o600 });
     await fs.rename(tmp, path);
 }
+/**
+ * 读盘上 LKG。返回 undefined 的所有情形都「安静地回 env 兜底」(调用方 warn 点名 reason):
+ * 文件缺席/JSON 坏/信封形不对/worker 不匹配(防同名文件跨 worker 串包)/prompts 面复判失败。
+ */
 export async function loadLkg(path, worker) {
     let text;
     try {
@@ -44,9 +75,18 @@ export async function loadLkg(path, worker) {
         return { reason: "bad effective" };
     if (p.etag !== undefined && typeof p.etag !== "string")
         return { reason: "bad etag" };
+    // 浅域判形(LKG 复审 F4):applyEffective 是 in-place mutate——半程炸=混态。载荷信任面与 live 远端
+    // 相同(config plane、本机文件=operator 权限),这里防的是**跨版本 schema 漂移/文件被改**的结构性坏形:
+    // 各域存在时必须是对象、其主数组存在时必须是数组、version 必须是数;更深的语义仍归 apply 层
+    // (live 载荷同待遇——LKG 不引入第二套 schema)。
     const eff = p.effective;
     if (typeof eff.version !== "number")
         return { reason: "bad effective.version" };
+    // codex R24(真存量 bug):teams 的真形=信封 `{ teams: CenterTeam[] }`(EffectiveConfig 声明形,
+    // applyEffective 消费 `eff.teams?.teams`)——旧判形要求裸数组,任何带 teams 的候选保存成功、下次 boot
+    // 被拒("bad effective.teams")→ env 兜底 → 慢中心下 defer 再签,正是交棒门要消的环。teams 改与其他域
+    // 同姿势:对象 + 主数组存在时必须是数组。(旧夹具 `teams: []` 曾遮住此形;裸数组从未被真实 save 产出,
+    // 拒掉无害:unusable → env 兜底 → 下个干净候选重写。)
     for (const [domain, arrayKey] of [["models", "models"], ["teams", "teams"], ["skills", "skills"], ["mcp", "servers"], ["scenarios", "scenarios"], ["runtime", null]]) {
         const v = eff[domain];
         if (v === undefined)
@@ -59,6 +99,7 @@ export async function loadLkg(path, worker) {
                 return { reason: `bad effective.${domain}.${arrayKey}` };
         }
     }
+    // prompts 面复判(候选门同函数):坏 prompts 若放行,boot 采用后每个任务 prepare 都会炸。
     const promptsRaw = p.effective.prompts;
     if (promptsRaw !== undefined && !validatePromptsDomain(promptsRaw).ok)
         return { reason: "prompts face fails re-validation" };