@sema-agent/server 7.141.0 → 7.143.0

package/dist/capabilities/skills.d.ts

@@ -1,4 +1,4 @@
-import type { SkillSpec, TaskSpec } from "@sema-agent/core";
+import type { SkillSpec } from "@sema-agent/core";
 import type { RemoteExecProvider } from "../execution-lane-caps.js";
 import { type Logger } from "../observability/logger.js";
 /**
@@ -105,22 +105,6 @@ export type ScenarioSkillEntry = SkillListEntry<SkillSource>;
 export type RunSkillSource = SkillSource | "request";
 /** run 级名册的一条(`wiring_manifest.skills[]`)。铸点唯一:`capabilities/scenarios.ts` 的 `buildRunSkills`。 */
 export type RunSkillEntry = SkillListEntry<RunSkillSource>;
-/**
- * run 级技能名册在 TaskSpec 上的**显式字段键** —— 与执行车道字段(`hands-lane.ts` 的 `HANDS_LANE_FIELD`,[ref])同一形:symbol 键随
- * spread / rest 解构走(续跑腿的 `taskConfig` 就是 rest 解构出来的),对上游 core 的键面不可见(JSON / 结构化克隆跳过 symbol 键)。
- * 铸点唯一 = `boot/resolve-spec.ts` 的 resolveSpec 出口({@link stampRunSkills});读点唯一 = {@link runSkillsOf}(每条投 `wiring_manifest` 的腿)。
- */
-export declare const RUN_SKILLS_FIELD: unique symbol;
-/**
- * 铸名册(**单一属主**:只许 resolveSpec 的出口调用)。字段 `enumerable`(复制得走)、`writable:false` + `configurable:false`(同一只 spec 被第二次铸 ⇒
- * 当场 TypeError,两个写者是漂移的成因)。名册冻结一份拷贝(spec 与腿不共享可变引用)。
- */
-export declare function stampRunSkills<T extends TaskSpec>(spec: T, roster: readonly RunSkillEntry[]): T;
-/**
- * 读名册。`undefined` = 这只 spec 不是本仓装配出口产的(嵌入方自写 `resolveSpec` / 测试桩)⇒ 腿上没有关于技能的陈述(段缺席)。
- * 不是保护型量(缺席只少一段披露,不放宽任何东西)⇒ 缺席照常跑,与车道字段的「缺席即拒」不同。入参收 `object`:续跑腿手里是 rest 解构出来的 taskConfig。
- */
-export declare function runSkillsOf(spec: object): readonly RunSkillEntry[] | undefined;
 /** 一个技能范围的卡上清单 —— 与 {@link skillsForScenario} 同一只过滤、同一个序,只是投影不同。 */
 export declare function scenarioSkillEntries(loaded: readonly LoadedSkill[], scope: string): ScenarioSkillEntry[];
 /** {@link parseFrontmatter} 的三种读数(闭集):`absent` = 第一行不是围栏,没有 frontmatter(正当的全局技能)· `block` = 围栏收好了的块 · `unclosed` = 第一行是围栏而块没收好(读不了 —— 调用方拒载)。 */

package/dist/capabilities/skills.js

@@ -127,14 +127,6 @@ function skillsInScope(loaded, scope) {
 export function skillsForScenario(loaded, scope) {
     return skillsInScope(loaded, scope).map((k) => k.spec);
 }
-export const RUN_SKILLS_FIELD = Symbol("sema-server.runSkills");
-export function stampRunSkills(spec, roster) {
-    Object.defineProperty(spec, RUN_SKILLS_FIELD, { value: Object.freeze(roster.map((e) => Object.freeze({ ...e }))), enumerable: true, writable: false, configurable: false });
-    return spec;
-}
-export function runSkillsOf(spec) {
-    return spec[RUN_SKILLS_FIELD];
-}
 export function scenarioSkillEntries(loaded, scope) {
     return skillsInScope(loaded, scope).map((k) => ({ name: k.spec.name, description: k.spec.description, source: k.source }));
 }

package/dist/capability-facts.d.ts

@@ -21,9 +21,8 @@
 import type { FlatServiceDeps } from "./http/server.js";
 import type { ServiceConfig } from "./config.js";
 import type { OwnerAwareSessionStore } from "./security.js";
-import type { ServiceFileHistoryStore } from "./plugins/store-backend.js";
+import type { ServiceBlobExchange, ServiceFileHistoryStore } from "./plugins/store-backend.js";
 import { resolveStreamApprovalGate, type ApprovalFrameFamily } from "./tool-approval.js";
-import { type SyncBlobHistoryStore } from "./session-sync.js";
 import { type WorkspaceSyncCapability } from "./workspace-space.js";
 import type { WorkspaceCacheCapability } from "./workspace-cache.js";
 /** why 闭集:词 → 给运维看的一句义(诊断 / 测试读它;wire 上的拒句由各门自写)。 */
@@ -47,7 +46,7 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly session_export_absent: "the session store has no entry export faces (exportEntries / exportEntriesStream)";
     readonly session_import_staging_absent: "the session store has no staged-import face (beginImportStaging)";
     readonly policy_purge_absent: "the session policy store has no deleteBySession purge verb";
-    readonly sync_blob_faces_absent: "the file-history store has no blob transfer faces (SQL backends only)";
+    readonly blob_exchange_absent: "the file-history store carries no blob exchange (FileHistoryStore.blobExchange — SQL backends only)";
     readonly device_hub_absent: "the device lane hub is not wired";
     readonly device_store_absent: "the device store is not wired";
     readonly device_enrollment_absent: "device enrollment is not wired";
@@ -65,6 +64,9 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly memory_origin_faces_absent: "the memory engine's origin marking faces are not wired";
     readonly consolidation_valve_closed: "the memory consolidation valve is closed (MEMORY_CONSOLIDATION_DRIVER)";
     readonly memory_optout_grant_absent: "no memory-capture opt-out grant store is wired (SQL backends only)";
+    readonly memory_db_plane_absent: "this is not a DB memory plane (MEMORY_ENGINE_BACKEND=pg|mysql): the central memory faces are not wired";
+    readonly memory_sync_identity_undeclared: "the DB memory plane declares no sync identity (MEMORY_SYNC_SERVE_IDENTITY), so it serves no sync round";
+    readonly memory_sync_leg_absent: "no memory sync leg runs here (a file memory engine with MEMORY_SYNC_URL)";
     readonly outcome_ledger_unqueryable: "the outcome sink has no query face (File sink)";
     readonly config_catalog_disabled: "the config catalog is switched off (CONFIG_CATALOG_ENABLED=false)";
     readonly rule_store_absent: "no permission-rule store is wired";
@@ -190,10 +192,11 @@ export declare function sessionSync(d: Pick<Deps, "backend" | "sessionStorage" |
     sessionStorage: SyncSessionStore;
     historyStore: ServiceFileHistoryStore;
 }>;
-/** 会话同步的**文件历史半族**:对话半族 ∧ 文件历史店有 blob 搬运面(只有 SQL 两只店有)。「店有没有 blob 两面」只在 `syncBlobFacesOf` 判一次(marker 门,不做名字探测),
- *  blob 取值口 `blobGetterOf` 读的是同一只 —— 本事实为真 ⟺ 取值口通到 `historyStore.getBlob`。 */
-export declare function sessionSyncFileHistory(d: Pick<Deps, "backend" | "sessionStorage" | "fileHistoryStore" | "sessionPolicyStore">): Fact<SessionSyncWhy | "sync_blob_faces_absent", {
-    historyStore: SyncBlobHistoryStore;
+/** 会话同步的**文件历史半族**:对话半族 ∧ 文件历史店带 blob 交换组(只有 SQL 两只店有)。「店能不能交换 blob」只在 `blobExchangeOf` 判一次(core 判官),
+ *  blob 取值口 `blobGetterOf` 读的是同一只 —— 本事实为真 ⟺ 取值口通到 `blobExchange.get`;判过的组随事实交出,路由的 GET / PUT / 在场预检只读它。 */
+export declare function sessionSyncFileHistory(d: Pick<Deps, "backend" | "sessionStorage" | "fileHistoryStore" | "sessionPolicyStore">): Fact<SessionSyncWhy | "blob_exchange_absent", {
+    historyStore: ServiceFileHistoryStore;
+    blobExchange: ServiceBlobExchange;
 }>;
 /** 持久审批底座(checkpoint 店)在场 —— `/v1/approvals/*` 与 `/v1/assistant/*` 整条车道、会话 wake 都站在它上面。 */
 export declare function checkpointPark(d: Pick<Deps, "checkpointStore">): Fact<"checkpoint_store_absent", {
@@ -272,6 +275,27 @@ export declare function sharedMemoryRead(d: Pick<Deps, "sharedMemoryStore" | "or
     provider: Store<"sharedMemoryStore">;
     directory: Store<"orgMemoryDirectory">;
 }>;
+/** 中心侧记忆导出读(`GET /v1/memory/export`):DB 记忆平面的导出读面在场(只在 DB 记忆平面装配)。门读本事实,不读 `MEMORY_ENGINE_BACKEND`。 */
+export declare function memoryExport(d: Pick<Deps, "memoryExport">): Fact<"memory_db_plane_absent", {
+    read: Store<"memoryExport">;
+}>;
+/**
+ * 中心侧同步口(`POST /v2/memory/sync/:scope`):DB 记忆平面的同步执行位在场 ∧ 本中心声明了同步身份(`MEMORY_SYNC_SERVE_IDENTITY`)。
+ * 见证 = 执行位 + 那份声明 —— 能力位 `memorySyncServe` 的 `{ identity }` 逐字投影它,入站 `peer` 与它按串比:一处声明,两个读者读同一个值。
+ */
+export declare function memorySyncServe(d: Pick<Deps, "memorySync" | "config">): Fact<"memory_db_plane_absent" | "memory_sync_identity_undeclared", {
+    perform: Store<"memorySync">;
+    identity: string;
+}>;
+/**
+ * 会话记忆同步触发口(`POST /v1/sessions/:id/memory/sync`):本机同步腿在场 ∧ 持久 run 账面(读集 = 会话最近一条已结腿的记忆观测;收割栅栏读会话的 run 认领)
+ * ∧ 会话头读(属主门与 `sourceRevision` = 同一次头读的叶子)。
+ */
+export declare function sessionMemorySync(d: Pick<Deps, "memorySyncLeg" | "runStore" | "sessionStorage">): Fact<"memory_sync_leg_absent" | "run_store_absent" | "session_head_face_absent", {
+    leg: Store<"memorySyncLeg">;
+    runStore: Store<"runStore">;
+    sessionStorage: HeadReadingSessionStore;
+}>;
 /** 跨主体投递门在座(`POST /v1/principal-inbox/messages` 的可用性门与能力位 `principalInboxDelivery` 同读这一只)。门的装配本身是
  *  一道合取(收件箱消费方声明 ∧ 耐久 mailbox ∧ org 成员目录 ∧ 配额店,缺一拒启 —— `boot/stage-06-runners.ts`),
  *  所以这里只判「门在不在」:在 ⟺ 那四件都在。 */

package/dist/capability-facts.js

@@ -4,7 +4,7 @@ import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 import { presentedApprovalFrameFamily, resolveStreamApprovalGate } from "./tool-approval.js";
 import { selfOrchestrationDenial } from "./task-workflow.js";
 import { centerEntitlementSourceWired } from "./runtime-caps-resolver.js";
-import { overwriteWipeIncapable, syncBlobFacesOf } from "./session-sync.js";
+import { blobExchangeOf, overwriteWipeIncapable } from "./session-sync.js";
 import { WORKSPACE_PERSIST_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, workspaceSnapshotTimeoutOf } from "./workspace-space.js";
 import { headReadOf } from "./session-incarnation.js";
 export const CAPABILITY_FACT_WHY = {
@@ -27,7 +27,7 @@ export const CAPABILITY_FACT_WHY = {
     session_export_absent: "the session store has no entry export faces (exportEntries / exportEntriesStream)",
     session_import_staging_absent: "the session store has no staged-import face (beginImportStaging)",
     policy_purge_absent: "the session policy store has no deleteBySession purge verb",
-    sync_blob_faces_absent: "the file-history store has no blob transfer faces (SQL backends only)",
+    blob_exchange_absent: "the file-history store carries no blob exchange (FileHistoryStore.blobExchange — SQL backends only)",
     device_hub_absent: "the device lane hub is not wired",
     device_store_absent: "the device store is not wired",
     device_enrollment_absent: "device enrollment is not wired",
@@ -45,6 +45,9 @@ export const CAPABILITY_FACT_WHY = {
     memory_origin_faces_absent: "the memory engine's origin marking faces are not wired",
     consolidation_valve_closed: "the memory consolidation valve is closed (MEMORY_CONSOLIDATION_DRIVER)",
     memory_optout_grant_absent: "no memory-capture opt-out grant store is wired (SQL backends only)",
+    memory_db_plane_absent: "this is not a DB memory plane (MEMORY_ENGINE_BACKEND=pg|mysql): the central memory faces are not wired",
+    memory_sync_identity_undeclared: "the DB memory plane declares no sync identity (MEMORY_SYNC_SERVE_IDENTITY), so it serves no sync round",
+    memory_sync_leg_absent: "no memory sync leg runs here (a file memory engine with MEMORY_SYNC_URL)",
     outcome_ledger_unqueryable: "the outcome sink has no query face (File sink)",
     config_catalog_disabled: "the config catalog is switched off (CONFIG_CATALOG_ENABLED=false)",
     rule_store_absent: "no permission-rule store is wired",
@@ -187,8 +190,8 @@ export function sessionSyncFileHistory(d) {
     const sync = sessionSync(d);
     if (!sync.available)
         return sync;
-    const faces = syncBlobFacesOf(sync.historyStore);
-    return faces !== undefined ? yes({ historyStore: faces }) : no("sync_blob_faces_absent");
+    const blobExchange = blobExchangeOf(sync.historyStore);
+    return blobExchange !== undefined ? yes({ historyStore: sync.historyStore, blobExchange }) : no("blob_exchange_absent");
 }
 export function checkpointPark(d) {
     return d.checkpointStore !== undefined ? yes({ checkpointStore: d.checkpointStore }) : no("checkpoint_store_absent");
@@ -286,6 +289,26 @@ export function sharedMemoryRead(d) {
         return no("org_memory_directory_absent");
     return yes({ provider: d.sharedMemoryStore, directory: d.orgMemoryDirectory });
 }
+export function memoryExport(d) {
+    return d.memoryExport !== undefined ? yes({ read: d.memoryExport }) : no("memory_db_plane_absent");
+}
+export function memorySyncServe(d) {
+    if (d.memorySync === undefined)
+        return no("memory_db_plane_absent");
+    const identity = d.config.memorySyncServeIdentity;
+    return identity !== undefined ? yes({ perform: d.memorySync, identity }) : no("memory_sync_identity_undeclared");
+}
+export function sessionMemorySync(d) {
+    if (d.memorySyncLeg === undefined)
+        return no("memory_sync_leg_absent");
+    const runs = durableRuns(d);
+    if (!runs.available)
+        return runs;
+    const owned = sessionOwnership(d);
+    if (!owned.available)
+        return owned;
+    return yes({ leg: d.memorySyncLeg, runStore: runs.runStore, sessionStorage: owned.sessionStorage });
+}
 export function principalInboxDelivery(d) {
     return d.orgDeliveryGate !== undefined ? yes({ gate: d.orgDeliveryGate }) : no("org_delivery_gate_absent");
 }

package/dist/card-void.d.ts

@@ -1,18 +1,15 @@
 /**
- * **结算时作废一张本服务兑现不了的卡** —— 全仓「结算作废」的唯一动词:读卡 → 卡仍 pending ∧ 卡在调用方说的那只会话上 ⇒
+ * **结算时作废一张本 run 自己会话上的、本服务兑现不了的卡** —— 读卡 → 卡仍 pending ∧ 卡在调用方说的那只会话上 ⇒
  * 按卡**自己的** scope 走 checkpoint 店的 `expire`(与引擎的本进程仲裁器、续跑的 resolve 同一只 CAS,恰一个赢家)。不新增任何持久态。
  *
- * 规则只有一条:**本服务兑现不了的卡不留在待决面上**。两个产地读这一只动词,各自只答「手里是哪一张卡、它该在哪只会话上」:
- *  · 验证器自己的停驻(`verifier-pause-card.ts`):卡在验证器现铸的会话上,本服务的续跑链连不回它;
- *  · 停驻没落定就以失败收场的腿(`runs.ts` 的 `voidHeldParkCard`:后台腿与续跑腿):卡在本 run 的会话上,但兑现它的那条 run 已经
- *    `failed`、认领已放 —— 卡的命运先于认领释放(调用方先调本动词、再放认领)。
+ * 规则只有一条:**本服务兑现不了的卡不留在待决面上**。产地 = 停驻没落定就以失败收场的腿(`runs.ts` 的 `voidHeldParkCard`:后台腿与
+ * 续跑腿):卡在本 run 的会话上,但兑现它的那条 run 已经 `failed`、认领已放 —— 卡的命运先于认领释放(调用方先调本动词、再放认领)。
+ * 验证器自己的停驻卡不走这里:它由引擎的 `Runner.voidVerifierPause` 作废(引擎读卡上的组合腿判它是不是验证器的卡,
+ * `verifier-pause-card.ts`);那只动词只收验证器的卡,本 run 自己会话上的卡按引擎的读法仍走店级 `expire`。
  *
  * 不抛:作废没做成(店读 / 作废抛错、卡的会话对不上、没接店)⇒ 卡回到「留在待决面上、由审批兜底收割收走」的形,按产地登记的 tag
  * 响亮留痕(计数 + 探针行 + 一次 warn),结算照常往下走。卡已不 pending / 已不在 ⇒ 什么都不做(CAS 输给了别的结算者,结局相同)。
- *
- * ## 🚧 过渡(引擎动词到货即改调)
- * 店级 `expire` 只作废卡,**不释放**引擎为这张卡钉住的会话(引擎在停驻时 pin 会话,只在续跑终局 / 续跑失败臂 unpin):
- * 被作废的卡的会话在本副本内存里一直常驻到进程重启。引擎给出「作废停驻卡并释放其会话」的动词之后,本动词改调它(两个产地一字不改)。
+ * 店级 `expire` 只作废卡,不动引擎在停驻时给这只会话打的钉(钉在续跑终局 / 续跑失败臂放)。
  */
 import type { CheckpointToken } from "@sema-agent/core";
 import { type FailOpenTag } from "./observability/fail-open.js";

package/dist/config-catalog.js

@@ -273,6 +273,7 @@ export const CONFIG_CATALOG = [
     r("MEMORY_SYNC_MAX_PULL_ENTRIES", "memory", "number", "TOC 同步单轮 pull 条数帽(设了必须 ≥1 整数)", { derivedDefaultNote: "缺席 ⇒ 键缺席,core 默认" }),
     r("MEMORY_SYNC_MAX_PUSH_ENTRIES", "memory", "number", "TOC 同步单轮 push 条数帽(设了必须 ≥1 整数)", { derivedDefaultNote: "缺席 ⇒ 键缺席,core 默认" }),
     r("MEMORY_SYNC_SCOPE", "memory", "string", "TOC 同步 scope 覆写(本服务铸的项目键族 `userrepo:` / `repo:` 拒启:项目层由同步腿按属主自己选)", { derivedDefaultNote: "缺席 ⇒ = MEMORY_SCOPE,仅当它已是 typed 键;非 typed 键拒启(S-964)" }),
+    r("MEMORY_SYNC_SERVE_IDENTITY", "memory", "url", "记忆同步中心(DB 记忆平面)声明的同步身份 = 客户端用来到达本中心同步口的基址;必须已是规范形(小写协议与主机、无缺省端口、无尾斜杠、无查询串 / 片段 / 凭据),否则拒启并给出规范形;能力位 `memorySyncServe.identity` 逐字公开,入站 `peer` 按串与它比", { derivedDefaultNote: "缺席 ⇒ 本中心不服务同步(501 feature.memory_sync_serve_disabled)", configKey: "memorySyncServeIdentity" }),
     r("MEMORY_SYNC_TOKEN", "memory", "secret", "TOC 同步中心面的 Bearer(URL 设了它必须在,半配拒启)", { danger: SEC }),
     r("MEMORY_SYNC_URL", "memory", "url", "TOC 同步中心地址(设了=开;file 记忆形专用,DB 后端配了拒启;同步覆盖同步层与同属主的项目层 `userrepo:<属主>/…` ⇒ 同步层与 MEMORY_SCOPE 同属主时单用户任务照常按项目键控并随同步推拉;不同属主 ⇒ 写家落全局层,启动通知 `memory_project_scope_yields_to_sync`)"),
     r("METRICS_TOKEN", "observability", "secret", "/metrics 只读令牌", { danger: SEC }),
@@ -336,7 +337,7 @@ export const CONFIG_CATALOG = [
             return compat.reasoningEffortLevels ?? null;
         },
     }),
-    r("MODEL_ROUTER_ID", "modelPlane", "string", "leader 路由分类模型覆写", { derivedDefaultNote: "缺席 ⇒ MODEL_CHEAP_ID,再退 default", danger: BILL }),
+    r("MODEL_ROUTER_ID", "modelPlane", "string", "leader 路由分类模型覆写", { derivedDefaultNote: "缺席 ⇒ 在服务表里解 classifier 角色(classifier → summarize → default;env cheap 槽绑 summarize,采纳的目录绑它自己的)", danger: BILL }),
     r("MODEL_THINKING_FORMAT", "modelPlane", "enum", "本网关收「开/关思考」的拼法(上 core OpenAICompletionsCompat.thinkingFormat;缺省开思考的 vLLM/Qwen 网关只有 qwen-chat-template 关得掉;anthropic 腿不铸此键;未知词拒启)", {
         enumValues: [...THINKING_FORMATS],
         derivedDefaultNote: "缺席 ⇒ 不铸此键,core 按 baseUrl/模型 id 自行推断(默认 openai 的 reasoning_effort)",

package/dist/config-dir-trust.js

@@ -1,5 +1,6 @@
 import { lstat, readFile, readdir, readlink, realpath, stat } from "node:fs/promises";
 import path from "node:path";
+import { CONFIG_ROOT_DOCUMENTS } from "@sema-agent/settings-schema";
 import { LOCAL_READER_DOCUMENTS } from "./config-d-migration.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { HOST_PLATFORM } from "./plugins/host-platform.js";
@@ -244,35 +245,44 @@ async function confirmUnreached(lexical) {
     return { kind: "unresolvable", path: lexical };
 }
 const documentFiles = () => LOCAL_READER_DOCUMENTS.map((d) => `${d}.json`);
-async function reachDir(lexical, ctx) {
+const rootDocumentFiles = () => CONFIG_ROOT_DOCUMENTS.map((d) => `${d}.json`);
+async function reach(lexical, want, ctx) {
     const top = await lstatStep("/");
     if (!isStats(top))
         return "finding" in top ? top.finding : undefined;
     const rootVerdict = await judgeComponent("/", top, ctx);
     if (typeof rootVerdict !== "string")
         return rootVerdict;
-    const step = await walk({ start: "/", stats: top, open: rootVerdict === "open", hops: 0 }, lexical.split("/"), "dir", ctx);
+    const step = await walk({ start: "/", stats: top, open: rootVerdict === "open", hops: 0 }, lexical.split("/"), want, ctx);
     if ("finding" in step)
         return step.finding;
     return step.reached ? step : confirmUnreached(lexical);
 }
-async function judgePosix(configDir, ctx) {
-    const dir = await reachDir(configDir, ctx);
-    if (dir === undefined || "kind" in dir)
-        return dir;
-    for (const file of documentFiles()) {
-        const doc = await walk({ start: dir.physical, stats: dir.stats, open: dir.open, hops: dir.hops }, [file], "file", ctx);
+async function judgeDocumentsIn(at, lexical, files, ctx) {
+    for (const file of files) {
+        const doc = await walk({ start: at.physical, stats: at.stats, open: at.open, hops: at.hops }, [file], "file", ctx);
         if ("finding" in doc)
             return doc.finding;
         if (!doc.reached) {
-            const unseen = await confirmUnreached(path.join(configDir, file));
+            const unseen = await confirmUnreached(path.join(lexical, file));
             if (unseen !== undefined)
                 return unseen;
         }
     }
     return undefined;
 }
-async function judgeWin32(configDir) {
+async function judgePosix(root, configDir, ctx) {
+    for (const file of rootDocumentFiles()) {
+        const doc = await reach(path.join(root, file), "file", ctx);
+        if (doc !== undefined && "kind" in doc)
+            return doc;
+    }
+    const dir = await reach(configDir, "dir", ctx);
+    if (dir === undefined || "kind" in dir)
+        return dir;
+    return judgeDocumentsIn(dir, configDir, documentFiles(), ctx);
+}
+async function judgeWin32(root, configDir) {
     const resolveStep = async (p) => {
         try {
             return await realpath(p);
@@ -286,26 +296,44 @@ async function judgeWin32(configDir) {
             return { kind: "unreadable", path: p, errno: code ?? String(e) };
         }
     };
-    const dir = await resolveStep(configDir);
-    if (dir === undefined)
+    const judgeDocs = async (dir, files) => {
+        let present = 0;
+        for (const file of files) {
+            const doc = await resolveStep(path.join(dir, file));
+            if (doc === undefined)
+                continue;
+            if (typeof doc !== "string")
+                return doc;
+            const st = await stat(doc);
+            if (!st.isFile())
+                return { kind: "not-regular", path: doc, type: typeOf(st) };
+            if (st.size > CONFIG_DOCUMENT_MAX_BYTES)
+                return { kind: "too-large", path: doc, bytes: st.size };
+            present += 1;
+        }
+        return present;
+    };
+    const rootAt = await resolveStep(root);
+    if (rootAt === undefined)
         return undefined;
-    if (typeof dir !== "string")
-        return dir;
-    if (!(await stat(dir)).isDirectory())
+    if (typeof rootAt !== "string")
+        return rootAt;
+    if (!(await stat(rootAt)).isDirectory())
         return undefined;
-    for (const file of documentFiles()) {
-        const doc = await resolveStep(path.join(dir, file));
-        if (doc === undefined)
-            continue;
-        if (typeof doc !== "string")
-            return doc;
-        const st = await stat(doc);
-        if (!st.isFile())
-            return { kind: "not-regular", path: doc, type: typeOf(st) };
-        if (st.size > CONFIG_DOCUMENT_MAX_BYTES)
-            return { kind: "too-large", path: doc, bytes: st.size };
+    const rootDocs = await judgeDocs(rootAt, rootDocumentFiles());
+    if (typeof rootDocs !== "number")
+        return rootDocs;
+    const dir = await resolveStep(path.join(rootAt, path.basename(configDir)));
+    if (dir !== undefined && typeof dir !== "string")
+        return dir;
+    const dirIsDir = dir !== undefined && (await stat(dir)).isDirectory();
+    if (dirIsDir) {
+        const docs = await judgeDocs(dir, documentFiles());
+        if (typeof docs !== "number")
+            return docs;
     }
-    recordFailOpen(WIN32_UNVERIFIED_TAG, `config.d=${dir}`);
+    if (dirIsDir || rootDocs > 0)
+        recordFailOpen(WIN32_UNVERIFIED_TAG, dirIsDir ? `config.d=${dir}` : `config root=${rootAt}`);
     return undefined;
 }
 export function localConfigDirOf(root) {
@@ -314,14 +342,15 @@ export function localConfigDirOf(root) {
 export async function judgeLocalConfigDir(input) {
     const host = input.host ?? processHost();
     const configDir = localConfigDirOf(input.root);
+    const root = path.dirname(configDir);
     if (host.platform === "win32")
-        return judgeWin32(configDir);
+        return judgeWin32(root, configDir);
     const owners = new Set([0]);
     if (host.euid !== undefined)
         owners.add(host.euid);
     if (input.declaredOwnerUid !== undefined)
         owners.add(input.declaredOwnerUid);
-    return judgePosix(configDir, { owners, mountinfo: host.mountinfo ?? processMountinfo });
+    return judgePosix(root, configDir, { owners, mountinfo: host.mountinfo ?? processMountinfo });
 }
 const octal = (mode) => `0${(mode & 0o7777).toString(8).padStart(3, "0")}`;
 export function buildConfigDirUntrustedSentence(f, ctx) {

package/dist/config-invariants.d.ts

@@ -26,6 +26,7 @@
  * 不引 config.ts,故 config.ts / runs.ts 都可以安全引它。
  */
 import type { ConfigProviderWord, ServiceConfigFlat } from "./config-types.js";
+import { type EnvTableReplacementInput } from "./env-model-table-gate.js";
 /**
  * 活体心跳周期(ms)——`runs.ts` 的 `HEARTBEAT_MS` 就是它(那边 re-export,单源在此)。
  *
@@ -34,7 +35,7 @@ import type { ConfigProviderWord, ServiceConfigFlat } from "./config-types.js";
  */
 export declare const LIVENESS_HEARTBEAT_MS = 30000;
 /** 闭集:新增一条不变量必须在这里加词(拼错 = 编译红,而不是运行期悄悄不判)。 */
-export type CrossInvariantId = "run-stale-heartbeat" | "bind-posture" | "bake-runner-credential" | "direct-door-anchors" | "operator-principals-required" | "operator-single-user" | "bake-operator-principals" | "sensitive-write-patterns" | "leader-host-lane" | "multi-tenant-shared-lane" | "leader-durable-store" | "device-durable-store" | "device-durable-approval" | "model-provider-word" | "gateway-url-userinfo" | "anthropic-credential-exclusive" | "model-route-endpoint" | "default-model-resolvable" | "refused-names-not-minted" | "require-execution-lane" | "center-one-identity" | "workflow-park-decision-domain" | "remote-config-provider-url" | "retention-lane-complete";
+export type CrossInvariantId = "run-stale-heartbeat" | "bind-posture" | "bake-runner-credential" | "direct-door-anchors" | "operator-principals-required" | "operator-single-user" | "bake-operator-principals" | "sensitive-write-patterns" | "leader-host-lane" | "multi-tenant-shared-lane" | "leader-durable-store" | "device-durable-store" | "device-durable-approval" | "model-provider-word" | "gateway-url-userinfo" | "anthropic-credential-exclusive" | "model-route-endpoint" | "default-model-resolvable" | "refused-names-not-minted" | "env-table-replacement-acknowledged" | "require-execution-lane" | "center-one-identity" | "workflow-park-decision-domain" | "remote-config-provider-url" | "retention-lane-complete";
 /** 表读的键集(取自平铺配置型 ⇒ 键名/类型永不与真配置漂)。 */
 export type CrossInvariantView = Readonly<Pick<ServiceConfigFlat, "runStaleSec" | "authToken" | "authTokens" | "allowUnauthedWrites" | "imageBakes" | "directApprovalDoor" | "durableApproval" | "approvalHmacKeys" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "requirePrincipal" | "operatorPrincipals" | "operatorSingleUser" | "sensitiveWritePatterns" | "leaderEnabled" | "selfOrchestrationEnabled" | "workflowRunStoreBackend" | "remoteExec" | "requireExecutionLane" | "dbBackend" | "tidb" | "pg" | "envModel" | "gatewayBaseUrl" | "gatewayFallbackUrls" | "anthropic" | "models" | "modelRefusals" | "tiers" | "authBridgeIssuer" | "webAdmin" | "configProvider" | "retentionPolicy" | "retentionSweep">>;
 export interface CrossInvariantInput {
@@ -42,6 +43,11 @@ export interface CrossInvariantInput {
     readonly live: CrossInvariantView;
     /** 候选(stage 期 = 现役 + 本批 staged 赋值)。 */
     readonly next: CrossInvariantView;
+    /**
+     * 一份**模型面候选**随身带的、不在配置键里的事实(它从哪条配置腿来、本地腿上配置根的 env 模型表决定在同一拍读作什么、引擎铸的 env 表)——
+     * 只有模型面 stage 带(它是装模型表的唯一写口);全表扫描(限额批的候选视图)不装模型表、不带。读它的不变量:`env-table-replacement-acknowledged`。
+     */
+    readonly candidate?: EnvTableReplacementInput;
 }
 export interface CrossInvariant {
     readonly id: CrossInvariantId;

package/dist/config-invariants.js

@@ -4,6 +4,7 @@ import { modelRouteUrlRefusal } from "./model-route-url.js";
 import { anthropicCredentialRefusal } from "./model-route-gap.js";
 import { modelRouteEndpointRefusal } from "./model-route-endpoint.js";
 import { defaultModelRefusal, refusedNameMintedRefusal } from "./model-entry-refusal.js";
+import { judgeEnvTableReplacement } from "./env-model-table-gate.js";
 import { WEB_ADMIN_ENV, httpUrlFlaws } from "@sema-agent/settings-schema";
 import { authBridgeIssuerOf } from "./auth-bridge.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
@@ -318,6 +319,12 @@ export const CONFIG_CROSS_INVARIANTS = [
         bootAnchor: { file: "src/boot/stage-02-web-admin-pull.ts", marker: "CROSS-INVARIANT:refused-names-not-minted" },
         check: ({ live, next }) => (next.models === live.models ? undefined : refusedNameMintedRefusal(next)),
     },
+    {
+        id: "env-table-replacement-acknowledged",
+        keys: ["models"],
+        restartReason: "env-model-table",
+        check: ({ candidate }) => (candidate === undefined ? undefined : judgeEnvTableReplacement(candidate)?.reason),
+    },
     {
         id: "center-one-identity",
         keys: ["authBridgeIssuer", "webAdmin"],

package/dist/config-provider.d.ts

@@ -1,5 +1,7 @@
 import { type DroppedConfigEntry, type UnreadConfigFile, type UnreadConfigKey } from "./web-admin-client/read-warnings.js";
 import { FileConfigStore } from "@sema-agent/settings-schema/node";
+import { type EnvModelsDecision } from "@sema-agent/settings-schema";
+import { type CatalogSource } from "./env-model-table-gate.js";
 import { type ConfigDocumentRefusal, type EffectiveConfig as AgentConfigEffective, type EffectiveReadWarning } from "@sema-agent/settings-schema";
 import { fetchEffective as remoteFetchEffective, fetchSkillContent as remoteFetchSkillContent, type EffectiveConfig } from "./web-admin-client/facade.js";
 import type { CenterEndpoint } from "./web-admin-client/center-request.js";
@@ -28,6 +30,8 @@ import type { ConfigProviderWord } from "./config-types.js";
  *  (与域判形失败同一条回落链、同一行拒判);缺席 = 没有。远端腿:wire 上只有墓碑一种,那一键不进 effective、其余域照读、版本照读;本地腿:契约的单读口
  *  `FileConfigStore.read()` 交 `refused` ⇒ 被拒文档 = 那一读的拒单原样,什么域内容都没装配 —— 候选是空的 effective(被整拒,不会被应用),版本 = 那一读的契约版本(按文档内容寻址)。 */
 /** `unreadKeys`:本地读腿读了那份文件、却结构上不读其中一键(`prompts.json` 的 `workers`)—— 同 `unreadFiles`,不进候选门,调用方一键一行 `config_unread_key`。 */
+/** `catalogSource`:这份候选**从哪条配置腿来**(必填;`env-model-table-gate.ts`)—— 本地腿另带配置根上 env 模型表决定在**同一拍**的读数(契约的唯一读者
+ *  `readEnvModelsDecision`;本地 etag 并入同一份读数的身份)。调用方原样交给 `applyEffective` / `logEffectiveDiff`,模型面 stage 的本地腿确认闸只读它。 */
 export type FetchEffectiveResult = {
     effective: EffectiveConfig;
     etag?: string;
@@ -41,6 +45,7 @@ export type FetchEffectiveResult = {
     refusedDocuments?: ConfigDocumentRefusal[];
     readWarnings: readonly EffectiveReadWarning[];
     credentialIdentity?: string;
+    catalogSource: CatalogSource;
 } | null;
 /**
  * 引号段 = **一条规则**:先过 `redactSecrets`;文本里没有引号字符(`"` / `'`)⇒ 原样返回;有 ⇒ 从**第一个**引号到**最后一个**引号(含两端,
@@ -161,6 +166,11 @@ export declare class RemoteConfigProvider implements ConfigProvider {
  */
 /** 本地读腿对契约文件店只有一种读法 —— 单读口 `read()`(一次读整棵 `config.d`,交一个结局)。注入缝(测试)按这一形给;严读 / 容错档位不在这条腿的类型里。 */
 export type LocalConfigReader = Pick<FileConfigStore, "read">;
+/**
+ * 本地配置源的 etag(纯字符串,唯一拼法):契约文件店的内容版本 ⊕ 配置根上决定读数的身份(`envModelsDecisionTag`:`absent` / `d:<digest>` / `io:<errno>`)。
+ * 只改决定、不改目录 ⇒ etag 也变(下一拍重判);运行记录不进 etag(只在起服读)。
+ */
+export declare function buildLocalConfigEtag(version: number, envModels: EnvModelsDecision): string;
 export declare class LocalConfigProvider implements ConfigProvider {
     #private;
     readonly kind: "local";

package/dist/config-provider.js

@@ -1,7 +1,9 @@
 import { readMcpSourceLabel } from "./mcp-source-label.js";
 import { createHmac, randomBytes } from "node:crypto";
 import { splitFoldedReadWarnings, withDroppedCatalogEntries } from "./web-admin-client/read-warnings.js";
-import { FileConfigStore } from "@sema-agent/settings-schema/node";
+import { FileConfigStore, readEnvModelsDecision } from "@sema-agent/settings-schema/node";
+import { envModelsDecisionTag } from "@sema-agent/settings-schema";
+import { REMOTE_CATALOG_SOURCE } from "./env-model-table-gate.js";
 import { assertLocalConfigDirTrusted } from "./config-dir-trust.js";
 import { danglingRefs, emptyEffective, findSkillContent, promptArtifactFor, renderRefIssue, skillContentHash, } from "@sema-agent/settings-schema";
 import { redactSecrets } from "./trace/redact.js";
@@ -52,10 +54,13 @@ export class RemoteConfigProvider {
     async fetchEffective(etag) {
         const fn = this.deps.fetchEffective ?? remoteFetchEffective;
         const r = await fn(this.cc, etag, undefined, this.cc.worker);
-        if (r === null || (r.domainErrors === undefined && r.droppedEntries === undefined && r.refusedDocuments === undefined))
-            return r;
+        if (r === null)
+            return null;
+        if (r.domainErrors === undefined && r.droppedEntries === undefined && r.refusedDocuments === undefined)
+            return { ...r, catalogSource: REMOTE_CATALOG_SOURCE };
         return {
             ...r,
+            catalogSource: REMOTE_CATALOG_SOURCE,
             ...(r.domainErrors !== undefined ? { domainErrors: r.domainErrors.map((de) => ({ domain: de.domain, error: redactConfigError(de.error) })) } : {}),
             ...(r.droppedEntries !== undefined ? { droppedEntries: r.droppedEntries.map(redactDroppedEntry) } : {}),
             ...(r.refusedDocuments !== undefined ? { refusedDocuments: r.refusedDocuments.map(redactRefusedDocument) } : {}),
@@ -73,6 +78,9 @@ export class RemoteConfigProvider {
         }
     }
 }
+export function buildLocalConfigEtag(version, envModels) {
+    return `${String(version)}+${envModelsDecisionTag(envModels)}`;
+}
 export class LocalConfigProvider {
     kind = "local";
     skillBodyCacheDir = undefined;
@@ -88,7 +96,9 @@ export class LocalConfigProvider {
     async fetchEffective(etag) {
         await assertLocalConfigDirTrusted({ root: this.root, declaredOwnerUid: this.#declaredOwnerUid });
         const read = await this.#store.read();
-        const tag = String(read.kind === "refused" ? read.version : read.effective.version);
+        const envModels = await readEnvModelsDecision(this.root);
+        const catalogSource = { kind: "local", root: this.root, envModels };
+        const tag = buildLocalConfigEtag(read.kind === "refused" ? read.version : read.effective.version, envModels);
         if (etag !== undefined && etag === tag)
             return null;
         const readWarnings = [...read.warnings];
@@ -98,6 +108,7 @@ export class LocalConfigProvider {
             ...faces,
             etag: tag,
             readWarnings,
+            catalogSource,
             ...(folded.unreadFiles.length > 0 ? { unreadFiles: folded.unreadFiles } : {}),
         };
     }

package/dist/config-root-migration.d.ts

@@ -0,0 +1,13 @@
+import { type EnvModelsMigration } from "@sema-agent/settings-schema/node";
+import type { ConfigDirMigrationLog } from "./config-d-migration.js";
+/** 一次起服的输入:配置根、目标引擎的 env(契约只读两槽、只用来点名被顶替的 env 模型)、env 表是不是占位(严格名册布防 —— 与模型面闸同一只谓词)。 */
+export interface EnvModelsMigrationInput {
+    readonly root: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly envTableIsPlaceholder: boolean;
+}
+/** 契约的迁移体调一次(本仓不改写它的判序,只调度)。 */
+export declare function runEnvModelsMigration(input: EnvModelsMigrationInput): Promise<EnvModelsMigration>;
+/** 结局的**唯一**说法(两个入口同调)。 */
+export declare function logEnvModelsMigration(log: ConfigDirMigrationLog, input: EnvModelsMigrationInput, m: EnvModelsMigration): void;
+//# sourceMappingURL=config-root-migration.d.ts.map