@sema-agent/server 7.142.0 → 7.144.0

package/dist/capabilities/scenarios.d.ts

@@ -5,6 +5,7 @@ import { type RepoReadClient } from "./repo-tools.js";
 import { type LoadedSkill, type RunSkillEntry, type ScenarioSkillEntry, type SkillSource } from "./skills.js";
 import { type ScenarioHands } from "./hands-lane.js";
 import type { DelegationRootWitness } from "../delegated-session-owner.js";
+import type { BackgroundCompletionSinkFor } from "../session-notify-door.js";
 /**
  * Scenario routing — a deployment serves many scenarios from one image. Each request's `scenario`
  * selects a pre-wired capability bundle: tools (incl. subagent roster) + its prompt seats + skills.
@@ -83,11 +84,11 @@ export interface ScenarioContext {
      */
     sessionId?: string;
     /**
-     * [ref] / [ref]:**委派树根的见证**(停驻挂点的属主来源)—— 根会话 id + 调用方判断那一刻读到的根行住客(`delegated-session-owner.ts` 的 `DelegationRootWitness`)。
-     * 由**每一个**接了停驻挂点的取用方显式交出(一条读法,没有回落):请求腿 = 本请求经鉴权解析的会话与受理时那一读(`boot/resolve-spec.ts`);`/decide` 赎回面 = 行上的
-     * `rootSessionId` 与赎回腿写口放行的那一位住客(`parked-revive-surface.ts`,交不交座都交)。它**只**喂停驻挂点,不挂任何会话级设施(那是 {@link sessionId} 的事,
-     * 判据是「这只 bundle 是不是在那只会话上取用的」,与属主来源是两个独立判据)。缺席 = 没有根可交(boot 期探针、run-local、行上没有根)⇒ 律给哨兵。
-     * 挂点在停驻那一刻再读一次根行:住客不是见证的那一位(删了、同 id 被重新登记)⇒ 停驻否决 —— 不按新住客认领。
+     * [ref]:**委派树根的见证** —— 根会话 id + 调用方判断那一刻读到的根行住客(`delegated-session-owner.ts` 的 `DelegationRootWitness`)。
+     * 由取用方显式交出(一条读法,没有回落):请求腿 = 本请求经鉴权解析的会话与受理时那一读(`boot/resolve-spec.ts`);`/decide` 赎回面 = 行上的
+     * `rootSessionId` 与赎回腿写口放行的那一位住客(`parked-revive-surface.ts`,交不交座都交)。它只喂 Runner 之外的后台子代完成 relay(会话通知门的目标住客:属主与化身),
+     * 不挂任何会话级设施(那是 {@link sessionId} 的事,判据是「这只 bundle 是不是在那只会话上取用的」)。缺席 = 没有根可交(boot 期探针、run-local、行上没有根)⇒ 不接 relay。
+     * 停驻挂点不读它(core 7.62.0 起挂点只比对引擎交来的委派树属主;根见证在停驻挂点的读法随 [ref] P-5 退役)。
      */
     delegationRoot?: DelegationRootWitness;
 }
@@ -141,22 +142,27 @@ export interface ScenarioDeps {
      * pre-153 行为(子代 SAFETY ask 照旧 deny+continue,零回归)。
      *  - `checkpointStore` 必须与 `RunnerDeps.checkpointStore`(主 runner 的 per-task spec 面)**同实例**
      *    ——子代 suspend 在那里铸 token,异实例 = park 全静默失效(core JSDoc 钉过症状,组装区注释同步)。
-     *  - `ensureChildSessionDurable` = park 提交前的 capability 挂点(core 签名 `(sessionId) => Promise<void>`)
-     *    ——resolve = 该子代 session 已从任意进程可读,reject/缺席 = veto(子代按 pre-153 settle failed,
-     *    checkpoint 被 expire)。**本车保守实现**:只在子代 session 已经真正路由到宿主 durable 会话店
-     *    **且真有内容**(`getLeafId() !== null`——排除 F-7 同族的空壳 claim-create 行,那种行 acquire
-     *    命中但零内容,是`register()`对任意自报 sessionId 的副作用,不是真正 durable 的会话)时 resolve
-     *    (=fork 续聊的常见形),其余一律 reject——不做「主动迁移私店会话进 durable 店」这一步
-     *    (ForkRoutingSessionStore 的路由表是私有状态,无迁移 API;主动迁移是更大的活,candidate 留给
-     *    后续按需再做)。
+     *  - `ensureChildSessionDurable` = park 提交前的 capability 挂点(core 签名 `(sessionId, given: { owner }) => Promise<void>`,下面那个字段)
+     *    ——resolve = 该子代 session 已从任意进程可读且属主是引擎交来的那一位,reject/缺席 = veto(子代按 pre-153 settle failed,
+     *    checkpoint 被 expire)。实现只验不搬(`plugins/session-store.ts` 的 `attestChildSessionDurable`):宿主店里在、有真内容
+     *    (`getLeafId() !== null`——排除 F-7 同族的空壳 claim-create 行)、属主相等,才 resolve。
      */
     checkpointStore?: CheckpointStore;
     /**
-     * [ref]:比 core 挂点多一个参数 —— `root` = **委派树根的见证,由取用这只 bundle 的调用方交出**({@link ScenarioContext.delegationRoot};缺席 = 没有根可交)。
-     * core 的挂点只给子代 id,停驻写下 / 定夺的宿主行属主却要按委派继承律取委派树根的属主;场景工厂把见证绑进交给 core 的那只闭包,同一棵树里任何深度的后台子代
-     * 停驻都经它(子代沿用父的委派工具实例)。
+     * 停驻挂点 —— 签名就是 core 的(`(sessionId, given: { owner }) => Promise<void>`,core 7.62.0 [ref]):`given.owner` = 引擎判的委派树属主,挂点只比对宿主行属主与它
+     * (`plugins/session-store.ts` 的 `attestChildSessionDurable`)。场景工厂原样交给委派工具,不绑任何调用方见证(委派树根见证闭包随 [ref] P-5 退役)。
      */
-    ensureChildSessionDurable?: (sessionId: string, root: DelegationRootWitness | undefined) => Promise<void>;
+    ensureChildSessionDurable?: (sessionId: string, given: {
+        readonly owner: string | null;
+    }) => Promise<void>;
+    /**
+     * **Runner 之外的后台子代完成**交给哪里 —— 按委派树根见证({@link ScenarioContext.delegationRoot})造委派工具挂载期的 `background.notify`。
+     * 停驻赎回腿的复活、操作员 `handle.resume` 都不是哪一次 run 内的调用,没有调用车道;引擎只在能解出一只完成 sink(调用 ?? 挂载)时才起后台续跑,
+     * 解不出 ⇒ 拒(`revive.no_background`)。sink = 委派树根会话的会话通知门(`session-notify-door.ts` 的 `createBackgroundCompletionRelay`;律与地址、
+     * 竞态、条目形都写在那里)。Runner 之内的调用照旧走调用车道,这只 sink 不被调。缺席(没有门的装配:run-local)⇒ 不接 ——
+     * 不接一只空 sink(接了 = 引擎起续跑、完成没人收)。
+     */
+    backgroundCompletionSinkFor?: BackgroundCompletionSinkFor;
     /**
      * [ref]([ref] F2 症状 → [ref] 定谳):**会话级**任务清单店解析器,属主 =
      * `boot/task-list-lane.ts` 的 {@link import("../boot/task-list-lane.js").createTaskListLane}

package/dist/capabilities/scenarios.js

@@ -38,7 +38,6 @@ export function buildScenarios(deps) {
         const webSearch = requestWebSearchBackend(deps.requirePrincipal !== true
             ? judgeRequestWebSearch(req?.settings?.webSearch)
             : { kind: "absent" }, deps.webSearch, deps.logger);
-        const ensureChildSessionDurable = deps.ensureChildSessionDurable;
         const delegationRoot = ctx?.delegationRoot;
         return {
             tools: [
@@ -58,7 +57,8 @@ export function buildScenarios(deps) {
                             scope: "default",
                             ...(deps.backgroundAgentStore ? { agentStore: deps.backgroundAgentStore } : {}),
                             ...(deps.checkpointStore ? { checkpointStore: deps.checkpointStore } : {}),
-                            ...(ensureChildSessionDurable !== undefined ? { ensureChildSessionDurable: (childSessionId) => ensureChildSessionDurable(childSessionId, delegationRoot) } : {}),
+                            ...(deps.ensureChildSessionDurable !== undefined ? { ensureChildSessionDurable: deps.ensureChildSessionDurable } : {}),
+                            ...(deps.backgroundCompletionSinkFor !== undefined && delegationRoot !== undefined ? { notify: deps.backgroundCompletionSinkFor(delegationRoot) } : {}),
                         },
                         ...createSubagentExtraTools(deps.subagentExtraTools),
                         ...(deps.logger

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";
@@ -193,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", {
@@ -280,7 +280,7 @@ export declare function memoryExport(d: Pick<Deps, "memoryExport">): Fact<"memor
     read: Store<"memoryExport">;
 }>;
 /**
- * 中心侧同步口(`POST /v1/memory/sync/:scope`):DB 记忆平面的同步执行位在场 ∧ 本中心声明了同步身份(`MEMORY_SYNC_SERVE_IDENTITY`)。
+ * 中心侧同步口(`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", {

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",
@@ -190,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");

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

@@ -337,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-d-migration.d.ts

@@ -28,6 +28,8 @@ export interface ConfigDirMigrationLog {
  *  · `noop` / `no-documents` / 目录不在 ⇒ 不出声(没有东西可迁);
  *  · `refused` ⇒ warn `config_dir_migration_refused`(一字未写;逐条点名迁移 id、坐标与契约的拒句 —— 读侧随后对这些旧形照旧响亮拒);
  *  · `unreadable` / 调用抛 ⇒ warn `config_dir_migration_failed`(一字未写或写到一半;原因 —— 坏文件的句子与读腿同一只判官)。
+ *    契约的 `unreadable` 不带成因,本仓分不出两类:① 读腿同一拍也会拒的坏文本(空 / 坏 JSON / 不是对象 / 嵌得过深〔根下 199 层〕:同一只文本判官,读腿随后另有一行 `config_candidate_rejected`,同一件事两行);
+ *    ② 只有迁移读不了的(目录列不了、悬空符号链接 —— 读腿接受,这一行是唯一的信号)。静默 ① 就会连 ② 一起吞,所以两类同一行;契约交出成因后 ① 改为只留读腿那一行(待契约)。
  *  · `pending` 只在契约的 `check: true` 下出现,本仓从不传 ⇒ 撞上即是接线错,响亮抛。
  */
 export declare function logConfigDirMigration(log: ConfigDirMigrationLog, m: ConfigDirMigration): void;

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