@sema-agent/server 7.103.1 → 7.104.0

package/dist/boot/execution-lane.js

@@ -0,0 +1,95 @@
+import { loadRemoteExec } from "@sema-agent/settings-schema/node";
+import { crossInvariant } from "../config-invariants.js";
+import { executionLaneCaps, executionLaneOf } from "../execution-lane-caps.js";
+export const FILE_SOURCED_LANES = ["host", "local-docker"];
+export async function composeExecutionLane(config, ctx) {
+    if (ctx.configSource === "local")
+        await applyRemoteExecFile(config, ctx);
+    assertExecutionLaneInvariants(config);
+}
+export function assertExecutionLaneInvariants(config) {
+    const judge = (id) => crossInvariant(id).check({ live: config, next: config });
+    const leader = judge("leader-host-lane");
+    if (leader !== undefined) {
+        throw new Error(leader);
+    }
+    const shared = judge("multi-tenant-shared-lane");
+    if (shared !== undefined) {
+        throw new Error(shared);
+    }
+    const deviceStore = judge("device-durable-store");
+    if (deviceStore !== undefined) {
+        throw new Error(deviceStore);
+    }
+    const deviceApproval = judge("device-durable-approval");
+    if (deviceApproval !== undefined) {
+        throw new Error(deviceApproval);
+    }
+}
+async function applyRemoteExecFile(config, ctx) {
+    const { localRoot, logger } = ctx;
+    let fileRx;
+    try {
+        fileRx = await loadRemoteExec(localRoot);
+    }
+    catch (err) {
+        logger.error("remote_exec_file_invalid", { root: localRoot, err: String(err) });
+        throw new Error(`config.d/remote-exec.json under ${localRoot} is invalid: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (!fileRx)
+        return;
+    const preemptedLane = executionLaneOf(config.remoteExec?.provider);
+    const isolatedLane = (lane) => executionLaneCaps(lane).isolation === "supported";
+    const disclosePreemption = (winner) => {
+        if (winner === preemptedLane)
+            return;
+        const downgrade = isolatedLane(preemptedLane) && !isolatedLane(winner);
+        logger.warn("remote_exec_lane_preempted_by_file", {
+            preemptedLane,
+            effectiveLane: winner,
+            root: localRoot,
+            isolationDowngrade: downgrade,
+            note: `config.d/remote-exec.json (CONFIG_PROVIDER=local, file-wins) replaced the env-derived execution lane ` +
+                `"${preemptedLane}" with "${winner}" — any REMOTE_EXEC/lane coordinate env for "${preemptedLane}" is now INERT` +
+                (downgrade ? `. This is an ISOLATION DOWNGRADE: tasks run on a non-isolated target. Delete/fix the file, or unset the lane env if the file is the intended source.` : `. Delete/fix the file, or unset the lane env if the file is the intended source.`),
+        });
+    };
+    const drives = (lane) => ctx.drivesFromFile.includes(lane);
+    if (fileRx.provider === "host" && drives("host")) {
+        config.remoteExec = {
+            provider: "host",
+            ...(fileRx.workdir ? { workspaceBase: fileRx.workdir } : {}),
+            ...(fileRx.commandTimeoutMs != null ? { commandTimeoutMs: fileRx.commandTimeoutMs } : {}),
+        };
+        disclosePreemption("host");
+        logger.info("remote_exec_from_file", { provider: "host", root: localRoot });
+        return;
+    }
+    if (fileRx.provider === "local-docker" && drives("local-docker")) {
+        config.remoteExec = {
+            provider: "local-docker",
+            image: fileRx.image,
+            ...(fileRx.mountPath ? { mountPath: fileRx.mountPath } : fileRx.workdir ? { mountPath: fileRx.workdir } : {}),
+            ...(fileRx.memory ? { memory: fileRx.memory } : {}),
+            ...(fileRx.cpus != null ? { cpus: fileRx.cpus } : {}),
+            ...(fileRx.network ? { network: fileRx.network } : {}),
+        };
+        disclosePreemption("local-docker");
+        logger.info("remote_exec_from_file", { provider: "local-docker", root: localRoot, image: fileRx.image });
+        return;
+    }
+    const fileLane = fileRx.provider;
+    const sourceable = FILE_SOURCED_LANES.some((lane) => lane === fileLane);
+    logger.warn("remote_exec_file_isolated_lane_unwired", {
+        provider: fileLane,
+        effectiveLane: preemptedLane,
+        reason: sourceable ? "entry-has-no-executor" : "needs-name-resolution",
+        note: sourceable
+            ? `config.d/remote-exec.json names "${fileLane}", but this entry has no executor for it (it drives ${ctx.drivesFromFile.join(" / ")} ` +
+                `from the file; the HTTP service drives ${FILE_SOURCED_LANES.join(" / ")}) — the env-derived lane above stays in force`
+            : `this entry drives ${ctx.drivesFromFile.join(" / ")} from config.d/remote-exec.json; "${fileLane}" (like the other isolated lanes ` +
+                `e2b / k8s / ssh / adb) is sourced from REMOTE_EXEC env until file-source NAME→value resolution lands (center field map) — the ` +
+                `env-derived lane above stays in force`,
+    });
+}
+//# sourceMappingURL=execution-lane.js.map

package/dist/boot/memory-consolidation.d.ts

@@ -1,9 +1,51 @@
 import type { RestartSliceCtx } from "../config-center/restart-signal.js";
+import type { MemoryConsolidationDriverConfig, ServiceConfig } from "../config-types.js";
 import { type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type MemoryBackend, type MemoryConsolidationDriverDeps, type RunMemoryConsolidationOptions, type SessionCaptureRecordStore } from "@sema-agent/core";
 /** D3 投影的座标签闭集。`role:<name>` 里的 name 只可能是 core 的 role 链两跳之一。 */
 export type ConsolidationSeatLabel = "explicit" | "role:consolidate" | "role:summarize";
 /** {@link buildConsolidationValveAudit} 的告警名闭集(事件名进日志 ⇒ 运维可按名过滤/告警)。 */
 export type ConsolidationValveWarningTag = "memory_consolidation_valve_unreachable" | "memory_consolidation_run_credential_gated";
+/** {@link resolveConsolidationValve} 的起服提示名闭集(S-824 / [ref];事件名进日志 ⇒ 运维可按名过滤/告警)。 */
+export type ConsolidationValveNoticeTag = "memory_consolidation_default_off_no_cheap_model" | "memory_consolidation_on_main_model";
+/**
+ * 阀门判决(S-824 / [ref])。`build*`/`create*` 之外的第三种:纯数据,由 {@link resolveConsolidationValve} 产出。
+ * 阀门开关的**唯一**属主:座解析、操作面、引擎面两席、审计告警、武装日志全读 `enabled`,不再各读一次表态。
+ */
+export interface ConsolidationValve {
+    readonly enabled: boolean;
+    /** 这一位是谁定的:运维的显式词(`explicit`),还是出厂缺省派生(`derived`)。 */
+    readonly source: "explicit" | "derived";
+    /**
+     * 这一判决**随目录变**吗(S-824 codex 车内复审 F2)。真 = 派生判决读了整理座落在谁身上(未设 ∧ 结构上跑得起来),
+     * 中心热改 roles / 档位就可能翻它 ⇒ 要有一份重启读数盯着({@link createConsolidationValveWatch})。显式词、以及结构上
+     * 跑不起来的派生关 ⇒ 假(目录怎么改都翻不动)。
+     */
+    readonly catalogDependent: boolean;
+    /** 起服时要落的那一行(缺席 = 没有要说的)。 */
+    readonly notice?: {
+        readonly tag: ConsolidationValveNoticeTag;
+        readonly detail: string;
+    };
+}
+/**
+ * 整理座若开,会落在哪只模型上 —— **相对主模型**(S-824 的「便宜模型在场」判据;{@link consolidationSeatBillingOf} 产出)。
+ *  · `own-model`   = 座解到的目录条目**不是**主模型那一条(按条目身份 = 对象引用判,不比 id 串;`MODEL_CHEAP_ID`,或目录的
+ *                    consolidate / summarize / flash 档位绑定);
+ *  · `main-model`  = 座解到主模型那一条本身(env 角色表在 `MODEL_CHEAP_ID` 缺席 —— 或与 `MODEL_ID` 同 id、不铸 cheap 槽 —— 时把
+ *                    summarize 指回 `default`)⇒ 整库折叠按主模型计费;
+ *  · `unresolvable`= 座解不出来(core 的 role 链刻意不回落主模型;`fault` = core 的原句,当数据交出、不吞)。
+ */
+export type ConsolidationSeatBilling = {
+    readonly kind: "own-model";
+    readonly seatModel: string;
+    readonly mainModel: string;
+} | {
+    readonly kind: "main-model";
+    readonly mainModel: string;
+} | {
+    readonly kind: "unresolvable";
+    readonly fault: string;
+};
 /** 座解析的产物:core 的 options 原样 + 给投影用的两位自证。 */
 export interface ConsolidationDriverSeat {
     /** `runMemoryConsolidationDriver` 的第三参,core 的 `resolveMemoryConsolidationDriver` 原样产出。 */
@@ -66,8 +108,6 @@ export interface ConsolidationSeatWatch {
 }
 /** 解席的输入面 = boot 期真席用的同三件(活引用:refresh 就地换代,`read()` 每次现取)。 */
 export type ConsolidationSeatPlane = Pick<MemoryConsolidationDriverDeps, "models" | "tiers" | "roles">;
-/** `create*`:返回带捕获状态(boot 那只指纹)的活对象。须在真席解析的**同一时刻**调(同一份输入)。 */
-export declare function createConsolidationSeatWatch(plane: () => ConsolidationSeatPlane): ConsolidationSeatWatch;
 /**
  * **每 scope 单飞**(codex 交叉复审 [high],验真后修)—— 同一 scope 上在飞的那一轮被后来者**并入**,
  * 而不是各起一轮。`create*`:返回带状态的活对象。
@@ -105,18 +145,146 @@ export declare function createPerScopeSingleFlight<T>(): (scope: string, run: ()
  *     写进句子 —— core 的那句话只提到 provenance,而运维要知道是哪一根把这台机器拦下的。
  *
  * 阀门关着 ⇒ 整条门不判(缺省姿态,[ref]「缺席不在律内」)。
+ *
+ * 🔴 S-824 起判据拆成「判官 + 拒启包装」两半:判官 {@link consolidationDriverUnwirable} 是三条臂的**唯一**
+ * 属主,拒启包装只在阀门开着时把它的拒因抛出去;出厂缺省派生({@link resolveConsolidationValve})读同一只判官决定
+ * 「结构上跑不起来 ⇒ 缺省恒关」—— 两处读一只,不是两份三臂。
  */
-export declare function assertConsolidationDriverWirable(input: {
+export declare function assertConsolidationDriverWirable(input: ConsolidationWiringFacts & {
     enabled: boolean;
+}): void;
+/** 阀门跑不跑得起来的三件结构事实(换部署形态才会变 —— 所以判在启动期)。 */
+export interface ConsolidationWiringFacts {
     /** 本部署接了记忆引擎吗(`boot/stores.ts` 的 `memoryEngine !== undefined`)。 */
-    memoryEngineWired: boolean;
+    readonly memoryEngineWired: boolean;
     /** 记忆后端自带控制面归属吗(`typeof backend.controlPlaneRoot === "string"` 且非空)。 */
-    controlPlaneOwned: boolean;
+    readonly controlPlaneOwned: boolean;
     /** 只进文案 —— 让「该去拧哪根旋钮」这句话指向该腿上**真的**有效的那一根。 */
-    memoryEngineBackend: "file" | "pg" | "tidb";
+    readonly memoryEngineBackend: "file" | "pg" | "tidb";
     /** 部署声明的 provenance 姿态(`config.memoryProvenance`;缺席 ≡ core 缺省 `carry`)。 */
-    provenance?: "off" | "carry";
-}): void;
+    readonly provenance?: "off" | "carry";
+}
+/** 「阀门若开,这台部署结构上跑不起来」的三种成因(闭集;加一种 = 下面两只穷举 switch 编译红)。 */
+export type ConsolidationUnwirable = "no-memory-engine" | "no-control-plane" | "provenance-off";
+/**
+ * 「阀门若开,这台部署结构上跑不跑得起来」的**判官**(三臂逐条理由见 {@link assertConsolidationDriverWirable} 头注)。
+ * 返回成因词;`undefined` = 跑得起来。两处读它:显式 on 的拒启(句子 = {@link unwirableRefusal}),以及出厂缺省派生
+ * (成因在场 ⇒ 缺省恒关零提示;半配拒启的「为什么没开」从句 = {@link unwirableClause})—— 派生形的句子不再借显式 on 的口吻
+ * (车PI 修复轮 ⑦(c):修前派生形的从句里夹着一句「MEMORY_CONSOLIDATION_DRIVER=on arms…」,而那台机器根本没写 on)。
+ */
+export declare function consolidationDriverUnwirable(input: ConsolidationWiringFacts): ConsolidationUnwirable | undefined;
+/**
+ * 整理座若开会落在哪只模型上(S-824 的「便宜模型在场」判据)—— **问 core 的同一只解析器**,不抄 role 链
+ * ({@link seatLabel} 注里同一条理由:抄一份就是第二真源,而 `ROLE_TIER_DEFAULTS` 的 flash 缺省会让手抄版答错)。
+ *
+ * 为什么不按 env `MODEL_CHEAP_ID` 的拼写判:它只是供座的一条路。env 角色表在它缺席时把 summarize 指回
+ * `default`(`config.ts` 的 `cheapRef`),而目录(`config.d/models.json` / 配置中心)的 roles / 档位同样能供
+ * consolidate / summarize 两跳 —— 判「装配后的座落不落主模型」才与计费事实同形(整理跑按座的模型计费)。
+ *
+ * 主模型 = 本仓给每条 task 铸的 `DEFAULT_MODEL_REF` 解到的那只(`boot/resolve-spec.ts` 每条 spec 都盖 `spec.model`),
+ * **不是** core 的 `default` 角色链 —— 与 `auto-mode-face.ts` 的 `classifierRouteFor` 同一口径(共用 `model-select.ts`
+ * `resolveMainModel`);喂**展开**目录,与引擎构造期 `expandTiers` 之后再解逐字同源。比的是**目录条目身份**(对象引用),
+ * **不比 `Model.id` 串**(车PI 修复轮 ⑤ / codex C-2:两条不同名的条目可以共享上游 id 却各带不同的 baseUrl / 凭据 / 价,那是两只
+ * 模型;与 `model-select.ts` `isModelAllowlisted` 同一口径)。env 的「cheap id == 主 id」不会走到这里变成两只:`config.ts` 在铸造处
+ * 就不铸那只影子条目(车PI 验修轮 B)。
+ * 探针 brain 零请求:座解析只 `brainToRuntime` 它一次,真被调用 = 装配缺陷,响亮抛。
+ * ⚠️ **爆炸半径**(车PI 验修轮 F10,如实登记):判决的每一臂 —— 包括未设 + 没配便宜模型的派生关(TOC 最常见的形)—— 都走
+ * {@link probeConsolidationSeat} 的 chat 探针。core 哪天改了 chat 闭包的次序(先做别的再问凭据席),**所有没显式 off 的部署**
+ * 起服即拒(句子点名这是提货缺陷),不再只是阀门开着的那几台。接受这个半径的理由:判据只有一只(不为派生关另写一份不走探针的
+ * 解析);钉在 test/memory-consolidation-driver.test.ts ⑭ 的真 core 探针格,提货批当场红,红在发版之前。
+ */
+export declare function consolidationSeatBillingOf(plane: ConsolidationSeatPlane): ConsolidationSeatBilling;
+/**
+ * 🔴 S-824 / clay **[ref]** —— **阀门判决**:开不开、谁定的、起服时要说什么。阀门开关的**唯一**属主(stage-06 的座解析 /
+ * 操作面 / 引擎面两席 / 审计告警 / 武装日志全读它的 `enabled`)。
+ *
+ *  · **显式词恒赢**:`off` ⇒ 关、零提示、**零探针**(一眼都不看角色表 —— off = 零装配零探针那句承诺);`on` ⇒ 开
+ *    (结构上跑不起来由下游 D1 三条拒启臂照拒,本判决不吞);开而座落主模型 ⇒ 开 + 一行
+ *    `memory_consolidation_on_main_model`(部署方显式承担,但必须知道账按主模型记)。
+ *  · **未设 = 出厂缺省派生**([ref] 取代 [ref] ① 的「出厂 off」实况):
+ *      结构上跑不起来(判官 {@link consolidationDriverUnwirable} 有成因:多租户 / `MEMORY_ENGINE=off` / pg·tidb
+ *      记忆后端 / `MEMORY_PROVENANCE=off`)⇒ **恒关、零提示、零探针** —— 派生开撞上 D1 拒启臂 = 每台配了便宜模型的
+ *      多租户 worker 升级即起不来;而配不配便宜模型它都开不了,一句指向 `MODEL_CHEAP_ID` 的提示是误导;
+ *      座不落主模型({@link consolidationSeatBillingOf} = `own-model`)⇒ **开**;
+ *      否则(落主模型 / 解不出)⇒ **关** + 一行 `memory_consolidation_default_off_no_cheap_model`(点名 `MODEL_CHEAP_ID`,
+ *      出路 = 配便宜模型,或显式 `off` 静音)。
+ *  · **半配拒启**(`MEMORY_EMBEDDER_*` 同族,S-824 起判定点挪到这里):scope 表 / 节律配了而阀门最终**没开** ⇒ 拒启,
+ *    拒因说清「为什么没开」。在 `loadConfig` 判会把「未设 + scope + 便宜模型在场」这台本该派生成开的部署当场拒掉。
+ *
+ * ⚠️ **起服判一次**(restart-to-apply):判决落在 boot 第 4 段的装配点 {@link createConsolidationValve} —— 目录已应用
+ * (`config.d/models.json` / 配置中心的 boot 采纳或 LKG)、记忆引擎已接线;座解析在第 6 段读这份判决。之后中心热改了 roles / 档位(或 boot 拉取超窗、目录迟到),**阀门不跟着翻**,
+ * 但翻的**需要**由 `memory-consolidation` 重启片报出来({@link createConsolidationValveWatch}):开着的那台盯座位漂移;
+ * 派生关的那台盯「此刻重判会不会开」(codex 车内复审 F2:修前派生关没有任何读数,热加一只便宜模型零信号、阀门永远关着)。
+ */
+export declare function resolveConsolidationValve(input: {
+    /** 部署表态(`config.memoryConsolidationDriver`)。 */
+    driver: MemoryConsolidationDriverConfig;
+    /** 判官 {@link consolidationDriverUnwirable} 对本部署的答案(成因 + 句子要用的结构事实;`undefined` = 跑得起来)。 */
+    unwirable: {
+        readonly code: ConsolidationUnwirable;
+        readonly facts: ConsolidationWiringFacts;
+    } | undefined;
+    /** 装配后的 models / tiers / roles —— 与真座解析同一份输入。只在需要时读。 */
+    plane: ConsolidationSeatPlane;
+}): ConsolidationValve;
+/**
+ * 阀门判决的**重启读数** —— `memory-consolidation` 重启片的两侧值,**一只** watch(车PI 修复轮 ⑥,codex C-3)。`create*`:返回
+ * 带捕获状态的活对象。两侧都是**同一个投影**:「判决开着 ⇒ `{ valve: "on", seat: 座位指纹 }`;关着 ⇒ `{ valve: "off" }`」——
+ * baked = boot 判决的投影,current = 此刻拿活配置**重判**一次的投影(`plane` 给活引用的 getter,refresh 就地换代后现取)。
+ *  · 判决翻了(派生开 → 关:主模型被挪到整理座那一条上,或座被挪回主模型;派生关 → 开:目录给整理座绑上别的模型 / 目录迟到)
+ *    ⇒ 两侧不等 ⇒ 签重启(重启后 boot 重判)。修前是两臂:开时只盯座位指纹、关时只盯「会不会开」—— 只动主模型的那一形零信号。
+ *  · 开着而座漂了(中心改了座会解到的那只模型)⇒ 座位指纹不等 ⇒ 签(S-668 波 0 的既有信号,显式 on 同走这一臂)。
+ *  · 关着而目录怎么变都不翻 ⇒ 两侧同为 `{ valve: "off" }` ⇒ 不签(主模型换代而判决不翻,不造一次什么都不改变的重启)。
+ * 主模型条目是判决的**输入**(它决定开 / 关),不进投影本身 —— 进了就会在每一次主模型换代时签一次不翻判决的重启。
+ * 显式 off / 结构上跑不起来的派生关 ⇒ `undefined`(判决不随目录变,没有可盯的东西)。
+ * 🔴 车PI 验修轮 F13([ref] 验修 opus):baked 与 current 出自**同一只**判决函数 —— baked = 构造这一拍拿同一组输入判一次。修前 baked
+ * 取自调用方另递的 `valve`,一个事实两个来源:递来的与 driver / unwirable / plane 不一致,第一拍就签一次假重启。入参里因此没有 valve 位。
+ */
+export declare function createConsolidationValveWatch(input: {
+    driver: MemoryConsolidationDriverConfig;
+    unwirable: Parameters<typeof resolveConsolidationValve>[0]["unwirable"];
+    plane: () => ConsolidationSeatPlane;
+}): ConsolidationSeatWatch | undefined;
+/**
+ * 阀门的**装配点**(车PI 修复轮 ⑦(a)(e):boot 第 4 段调它,测试调同一只 —— 不在测试里手抄接线)。`create*`:产出带行为的 watch。
+ *
+ * 一次做完四件,顺序即契约:纯判({@link judgeConsolidationValve}:判官 → 判决,半配拒启在这里抛;`run-local` 只调这一步)→ 判决带出的
+ * 起服提示落日志 → D1 的结构拒启(显式 on 而跑不起来)→ 重启读数({@link createConsolidationValveWatch})。
+ * ⚠️ **位置**:判决要两件 openStores(第 3 段)的装配结果 —— 记忆引擎接没接线、后端有没有控制面归属 —— 更早判就得在配置层把那两件
+ * 复算一遍(第二份判据),所以落在第 4 段(第一个同时持有已应用目录与店的位置),早于执行环境 / Runner 装配;座解析与操作面引擎
+ * 仍在第 6 段(要 brain 与凭据席)。`config` 给活引用:重启读数的 plane getter 每次现取 refresh 换代后的三张表。
+ */
+export declare function createConsolidationValve(input: ConsolidationValveInput & {
+    logger: {
+        warn: (event: string, fields?: Record<string, unknown>) => void;
+    };
+}): {
+    valve: ConsolidationValve;
+    watch: ConsolidationSeatWatch | undefined;
+};
+/** 阀门判决的两件输入(装配点与纯判共用一只形 —— 两个入口递的是同一组事实)。 */
+export interface ConsolidationValveInput {
+    readonly config: Pick<ServiceConfig, "memoryConsolidationDriver" | "memoryEngineBackend" | "memoryProvenance" | "models" | "tiers" | "roles">;
+    /** 只读两件:在不在(记忆引擎接没接线)、后端有没有控制面归属(`backendOwnsControlPlane` 只问那一个面)。 */
+    readonly memoryEngine: {
+        readonly backend: unknown;
+    } | undefined;
+}
+/**
+ * 🔴 车QK F5(7.104.0 合并复审 opus 腿)—— 阀门的**纯判**:结构事实(判官 {@link consolidationDriverUnwirable})→ 判决
+ * ({@link resolveConsolidationValve},**半配拒启在这里抛**)。不落日志、不判 D1、不建重启读数 —— 那三件属于有整理座的入口
+ * ({@link createConsolidationValve} 在它之上做完)。
+ *
+ * 两个入口各调它一次:HTTP 服务第 4 段经 {@link createConsolidationValve};`run-local` 在记忆引擎接线之后直接调(它没有整理座 ——
+ * 不挂手动口、不接 `RunnerDeps` 的整理两席 —— 判决本身对它没有用处,要的只是拒因)。修前这道拒只长在 HTTP 那条装配链上
+ * (S-824 从 `loadConfig` 挪过来时 `run-local` 没跟上):共享 `.env` 上同一组键,HTTP 服务拒启、`run-local` 带着零效果的 scope 表
+ * 静默起跑。判据只有这一只 ⇒ 两个入口对同一份 env 同判同句(未设 + 便宜模型在场 ⇒ 两边都派生开、都照起)。
+ */
+export declare function judgeConsolidationValve(input: ConsolidationValveInput): {
+    valve: ConsolidationValve;
+    wiring: ConsolidationWiringFacts;
+    unwirable: Parameters<typeof resolveConsolidationValve>[0]["unwirable"];
+};
 /**
  * 阀门上了场之后的**可达性**告警两条(自查 + codex 交叉复审;姿态=warn 不拒启)。
  *
@@ -137,9 +305,17 @@ export declare function assertConsolidationDriverWirable(input: {
  * 同族先例逐字:`permission_rules_lane_unavailable`(旋钮开着却上不了场 ⇒ 打一行,不拒启)。
  * 反过来说,**沉默**同样不行:那正是「设了但没生效」病族,而这一形连能力位都是诚实的假,唯一缺的
  * 就是一句把因果说清楚的话。
+ *
+ * ## 只审**显式**开的阀门(S-824 / [ref] 起)
+ *
+ * 两条告警的前提都是「运维**显式**拧了 on」(上面那句原话)——它们是一次**表态**够不着的诊断。出厂缺省**派生**开的
+ * 那台(配了便宜模型的单用户部署)没有表态可审:引擎面的自动整理照跑(不走这两个口),手动口是一件它没要过的东西。
+ * 照审的后果是每一台这样的部署升级后每次起服多两行 warn,点名一根它从没设过的 `MEMORY_CONSOLIDATION_DRIVER=on`,
+ * 教它去配一个它不需要的操作面。判据读阀门判决的 `source`,不读表态原词(判决是阀门开关的唯一属主)。
  */
 export declare function buildConsolidationValveAudit(input: {
-    enabled: boolean;
+    /** 阀门判决({@link resolveConsolidationValve} 的 `enabled` + `source`)。 */
+    valve: Pick<ConsolidationValve, "enabled" | "source">;
     operatorPrincipals: readonly string[];
     /** 这台部署配了任何一把 service 凭证吗(`config.authToken` 或 `config.authTokens` 非空)。 */
     hasServiceAuth: boolean;

package/dist/boot/memory-consolidation.js

@@ -1,5 +1,7 @@
 import { redactSecrets } from "../trace/redact.js";
 import { memoryMountRootOf } from "../memory-scope.js";
+import { DEFAULT_MODEL_REF, resolveMainModel } from "../model-select.js";
+import { backendOwnsControlPlane } from "../memory-operator-faces.js";
 import { expandTiers, MemoryEngine, readConsolidationDriverRun, resolveMemoryConsolidationDriver, runMemoryConsolidationDriver, } from "@sema-agent/core";
 export function resolveConsolidationDriverSeat(deps) {
     let options;
@@ -16,11 +18,7 @@ export function resolveConsolidationDriverSeat(deps) {
     }
     return { options, seat: seatLabel(deps), model: options.model };
 }
-export function createConsolidationSeatWatch(plane) {
-    const baked = consolidationSeatFingerprint(plane());
-    return { read: () => ({ baked, current: consolidationSeatFingerprint(plane()) }) };
-}
-function consolidationSeatFingerprint(plane) {
+function probeConsolidationSeat(plane) {
     const stop = new Error("consolidation seat probe: stopped before any request");
     const refuse = () => {
         throw stop;
@@ -43,12 +41,18 @@ function consolidationSeatFingerprint(plane) {
     }
     void options.chat({ system: "", user: "", maxTokens: 1, temperature: 0 }).catch(() => undefined);
     if (seen.model === undefined) {
-        throw new Error("MEMORY_CONSOLIDATION_DRIVER=on, but the consolidation seat's restart probe could not observe which model the " +
-            "engine's seat resolver chose (the resolved chat seat no longer asks the per-model credential seat before its " +
-            "first await) — refusing rather than leave this seat's restart signal blind. This is an engine-pickup defect " +
-            "in boot/memory-consolidation.ts (createConsolidationSeatWatch), not a deployment setting.");
+        throw new Error("the memory-consolidation valve's seat probe could not observe which model the engine's seat resolver chose (the " +
+            "resolved chat seat no longer asks the per-model credential seat before its first await) — refusing rather than " +
+            "leave the valve's decision and restart signal blind. This is an engine-pickup defect in " +
+            "boot/memory-consolidation.ts (probeConsolidationSeat), not a deployment setting.");
     }
-    const { cost: _cost, ...route } = seen.model;
+    return { entry: seen.model };
+}
+function consolidationSeatFingerprint(plane) {
+    const seat = probeConsolidationSeat(plane);
+    if ("unresolvable" in seat)
+        return seat;
+    const { cost: _cost, ...route } = seat.entry;
     return route;
 }
 function seatLabel(deps) {
@@ -81,29 +85,183 @@ export function createPerScopeSingleFlight() {
 export function assertConsolidationDriverWirable(input) {
     if (!input.enabled)
         return;
-    if (!input.memoryEngineWired) {
-        throw new Error(`MEMORY_CONSOLIDATION_DRIVER=on arms the memory-consolidation valve, but this deployment wires NO memory engine ` +
-            `— there is no library to fold, and the two admin endpoints would answer over an engine that does not exist. ` +
-            `(The engine is wired only on single-user deployments with MEMORY_ENGINE on; a multi-tenant worker keeps memory ` +
-            `dark by design.) Wire the memory engine, or set MEMORY_CONSOLIDATION_DRIVER=off.`);
+    const code = consolidationDriverUnwirable(input);
+    if (code !== undefined)
+        throw new Error(unwirableRefusal(code, input));
+}
+export function consolidationDriverUnwirable(input) {
+    if (!input.memoryEngineWired)
+        return "no-memory-engine";
+    if (!input.controlPlaneOwned)
+        return "no-control-plane";
+    if (input.provenance === "off")
+        return "provenance-off";
+    return undefined;
+}
+function unwirableRefusal(code, facts) {
+    switch (code) {
+        case "no-memory-engine":
+            return (`MEMORY_CONSOLIDATION_DRIVER=on arms the memory-consolidation valve, but this deployment wires NO memory engine ` +
+                `— there is no library to fold, and the two admin endpoints would answer over an engine that does not exist. ` +
+                `(The engine is wired only on single-user deployments with MEMORY_ENGINE on; a multi-tenant worker keeps memory ` +
+                `dark by design.) Wire the memory engine, or set MEMORY_CONSOLIDATION_DRIVER=off.`);
+        case "no-control-plane":
+            return (`MEMORY_CONSOLIDATION_DRIVER=on arms the memory-consolidation valve, but the wired memory backend ` +
+                `(MEMORY_ENGINE_BACKEND=${facts.memoryEngineBackend}) does NOT own an engine control plane (controlPlaneRoot) — ` +
+                `core would derive one on THIS replica's local disk, and a consolidation run's resumable account would die with ` +
+                `the pod (a lost run re-mints the whole library at full model cost on the next attempt). The file memory backend ` +
+                `owns a control plane; the pg/tidb memory backends do not. Set MEMORY_ENGINE_BACKEND=file, or set ` +
+                `MEMORY_CONSOLIDATION_DRIVER=off.`);
+        case "provenance-off":
+            return (`MEMORY_CONSOLIDATION_DRIVER=on is incompatible with MEMORY_PROVENANCE=off — core refuses to enable consolidation ` +
+                `under provenance "off" because the fold law must be able to MINT origin markers (a marked input's product would ` +
+                `otherwise commit unmarked, i.e. the fold would launder provenance). Set MEMORY_PROVENANCE=carry (or unset it, ` +
+                `which is the same posture), or set MEMORY_CONSOLIDATION_DRIVER=off.`);
+        default: {
+            const unreachable = code;
+            throw new Error(`unhandled consolidation unwirable code: ${String(unreachable)}`);
+        }
     }
-    if (!input.controlPlaneOwned) {
-        throw new Error(`MEMORY_CONSOLIDATION_DRIVER=on arms the memory-consolidation valve, but the wired memory backend ` +
-            `(MEMORY_ENGINE_BACKEND=${input.memoryEngineBackend}) does NOT own an engine control plane (controlPlaneRoot) — ` +
-            `core would derive one on THIS replica's local disk, and a consolidation run's resumable account would die with ` +
-            `the pod (a lost run re-mints the whole library at full model cost on the next attempt). The file memory backend ` +
-            `owns a control plane; the pg/tidb memory backends do not. Set MEMORY_ENGINE_BACKEND=file, or set ` +
-            `MEMORY_CONSOLIDATION_DRIVER=off.`);
+}
+function unwirableClause(code, facts) {
+    switch (code) {
+        case "no-memory-engine":
+            return "no memory engine is wired here (multi-tenant posture, or MEMORY_ENGINE=off), so there is no library to fold";
+        case "no-control-plane":
+            return `the memory backend (MEMORY_ENGINE_BACKEND=${facts.memoryEngineBackend}) owns no engine control plane, so a consolidation run could not keep its account`;
+        case "provenance-off":
+            return "MEMORY_PROVENANCE=off, and consolidation needs provenance to mint origin markers";
+        default: {
+            const unreachable = code;
+            throw new Error(`unhandled consolidation unwirable code: ${String(unreachable)}`);
+        }
+    }
+}
+export function consolidationSeatBillingOf(plane) {
+    const seat = probeConsolidationSeat(plane);
+    if ("unresolvable" in seat)
+        return { kind: "unresolvable", fault: seat.unresolvable };
+    let main;
+    try {
+        main = resolveMainModel(plane);
     }
-    if (input.provenance === "off") {
-        throw new Error(`MEMORY_CONSOLIDATION_DRIVER=on is incompatible with MEMORY_PROVENANCE=off — core refuses to enable consolidation ` +
-            `under provenance "off" because the fold law must be able to MINT origin markers (a marked input's product would ` +
-            `otherwise commit unmarked, i.e. the fold would launder provenance). Set MEMORY_PROVENANCE=carry (or unset it, ` +
-            `which is the same posture), or set MEMORY_CONSOLIDATION_DRIVER=off.`);
+    catch (err) {
+        return { kind: "unresolvable", fault: `the main model (${DEFAULT_MODEL_REF}) does not resolve: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    return seat.entry === main ? { kind: "main-model", mainModel: main.id } : { kind: "own-model", seatModel: seat.entry.id, mainModel: main.id };
+}
+export function resolveConsolidationValve(input) {
+    const decided = decideConsolidationValve(input);
+    const { intervalSec, scopes } = input.driver;
+    if (decided.offBecause !== undefined && (intervalSec > 0 || scopes.length > 0)) {
+        throw new Error(`MEMORY_CONSOLIDATION_INTERVAL_SEC / MEMORY_CONSOLIDATION_SCOPES are configured but MEMORY_CONSOLIDATION_DRIVER is not "on" ` +
+            `(${decided.offBecause}) — the consolidation valve is OFF, so neither knob reaches anything (the two admin endpoints are not ` +
+            `even mounted). Set MEMORY_CONSOLIDATION_DRIVER=on (or, while it is unset, configure a cheaper consolidation model via ` +
+            `MODEL_CHEAP_ID so the factory default arms the valve), or unset the other two.`);
+    }
+    return decided.valve;
+}
+export function createConsolidationValveWatch(input) {
+    const decide = (plane) => decideConsolidationValve({ driver: input.driver, unwirable: input.unwirable, plane }).valve;
+    const project = (valve, plane) => (valve.enabled ? { valve: "on", seat: consolidationSeatFingerprint(plane) } : { valve: "off" });
+    const bootPlane = input.plane();
+    const bakedValve = decide(bootPlane);
+    if (!bakedValve.enabled && !bakedValve.catalogDependent)
+        return undefined;
+    const baked = project(bakedValve, bootPlane);
+    return {
+        read: () => {
+            const plane = input.plane();
+            return { baked, current: project(decide(plane), plane) };
+        },
+    };
+}
+export function createConsolidationValve(input) {
+    const { config, logger } = input;
+    const { valve, wiring, unwirable } = judgeConsolidationValve(input);
+    if (valve.notice !== undefined)
+        logger.warn(valve.notice.tag, { detail: valve.notice.detail });
+    assertConsolidationDriverWirable({ ...wiring, enabled: valve.enabled });
+    const plane = () => ({ models: config.models, tiers: config.tiers, roles: config.roles });
+    return { valve, watch: createConsolidationValveWatch({ driver: config.memoryConsolidationDriver, unwirable, plane }) };
+}
+export function judgeConsolidationValve(input) {
+    const { config, memoryEngine } = input;
+    const wiring = {
+        memoryEngineWired: memoryEngine !== undefined,
+        controlPlaneOwned: backendOwnsControlPlane(memoryEngine?.backend),
+        memoryEngineBackend: config.memoryEngineBackend,
+        ...(config.memoryProvenance !== undefined ? { provenance: config.memoryProvenance } : {}),
+    };
+    const code = consolidationDriverUnwirable(wiring);
+    const unwirable = code !== undefined ? { code, facts: wiring } : undefined;
+    const valve = resolveConsolidationValve({ driver: config.memoryConsolidationDriver, unwirable, plane: { models: config.models, tiers: config.tiers, roles: config.roles } });
+    return { valve, wiring, unwirable };
+}
+function decideConsolidationValve(input) {
+    const declared = input.driver.valve;
+    switch (declared) {
+        case "off":
+            return { valve: { enabled: false, source: "explicit", catalogDependent: false }, offBecause: `it is "off"` };
+        case "on": {
+            if (input.unwirable !== undefined)
+                return { valve: { enabled: true, source: "explicit", catalogDependent: false } };
+            const billing = consolidationSeatBillingOf(input.plane);
+            if (billing.kind !== "main-model")
+                return { valve: { enabled: true, source: "explicit", catalogDependent: false } };
+            return {
+                valve: {
+                    enabled: true,
+                    source: "explicit",
+                    catalogDependent: false,
+                    notice: {
+                        tag: "memory_consolidation_on_main_model",
+                        detail: `MEMORY_CONSOLIDATION_DRIVER=on armed the memory-consolidation valve, but its consolidation seat resolves to the main model ` +
+                            `"${billing.mainModel}" (no MODEL_CHEAP_ID naming another model, and no catalog roles.consolidate / roles.summarize / "flash" tier binding to another ` +
+                            `model) — every consolidation round (the manual endpoint, and the automatic one after each recommending task unless ` +
+                            `MEMORY_AUTO_CONSOLIDATION=off) reads the whole library (~1e5 prompt tokens per cycle) at the main model's rate. Honored because ` +
+                            `it was declared explicitly; set MODEL_CHEAP_ID to a cheaper model on the same gateway to move consolidation off the main model.`,
+                    },
+                },
+            };
+        }
+        case undefined: {
+            if (input.unwirable !== undefined) {
+                return { valve: { enabled: false, source: "derived", catalogDependent: false }, offBecause: `it is unset, and the valve cannot run on this deployment: ${unwirableClause(input.unwirable.code, input.unwirable.facts)}` };
+            }
+            const billing = consolidationSeatBillingOf(input.plane);
+            if (billing.kind === "own-model")
+                return { valve: { enabled: true, source: "derived", catalogDependent: true } };
+            const seatFact = billing.kind === "main-model"
+                ? `Here the seat resolves to the main model "${billing.mainModel}" (no MODEL_CHEAP_ID naming another model, and no catalog roles.consolidate / roles.summarize / "flash" tier binding to another model)`
+                : `Here no consolidation seat resolves at all (${billing.fault})`;
+            return {
+                valve: {
+                    enabled: false,
+                    source: "derived",
+                    catalogDependent: true,
+                    notice: {
+                        tag: "memory_consolidation_default_off_no_cheap_model",
+                        detail: `MEMORY_CONSOLIDATION_DRIVER is unset, so the memory-consolidation valve takes its factory default: ON only when the ` +
+                            `consolidation seat runs on a model other than the main one. ${seatFact} — so the valve stays OFF (no manual endpoints, ` +
+                            `no automatic whole-library folds): one consolidation round reads the whole library (~1e5 prompt tokens per cycle) and ` +
+                            `would bill at the main model's rate. Set MODEL_CHEAP_ID to a cheaper model on the same gateway (or bind roles.consolidate / ` +
+                            `roles.summarize / a "flash" tier to one in the catalog) to arm it; set MEMORY_CONSOLIDATION_DRIVER=off to silence this ` +
+                            `line (MEMORY_CONSOLIDATION_DRIVER=on arms it on the main model deliberately).`,
+                    },
+                },
+                offBecause: `it is unset, and the factory default arms the valve only when the consolidation seat runs on a model other than the main ` +
+                    `one — ${billing.kind === "main-model" ? `here it resolves to the main model "${billing.mainModel}"` : `here no seat resolves (${billing.fault})`}`,
+            };
+        }
+        default: {
+            const unreachable = declared;
+            throw new Error(`unhandled MEMORY_CONSOLIDATION_DRIVER declaration: ${String(unreachable)}`);
+        }
     }
 }
 export function buildConsolidationValveAudit(input) {
-    if (!input.enabled)
+    if (!input.valve.enabled || input.valve.source !== "explicit")
         return { warnings: [] };
     const warnings = [];
     if (input.operatorPrincipals.length === 0) {
@@ -151,10 +309,12 @@ export function assertAutoConsolidationWirable(input) {
         `recommended one — memory content EGRESSES to the configured consolidation model), but this deployment wires NO ` +
         `engine-side consolidation seat (RunnerDeps.memoryConsolidation). The engine refuses that combination at EVERY ` +
         `prepare (config.auto_consolidation), so this worker would boot fine and then fail every single task. ` +
-        `The engine-side seats are wired IFF MEMORY_CONSOLIDATION_DRIVER=on and a memory engine is wired — so either ` +
-        `set MEMORY_CONSOLIDATION_DRIVER=on (which also mounts the manual valve, and note that BOTH knobs then bill ` +
-        `whole-library model calls), or set MEMORY_AUTO_CONSOLIDATION=off (unsetting it is NOT the same: the engine's ` +
-        `named default is ON as of core 7.21.1).`);
+        `The engine-side seats are wired IFF the consolidation valve is on and a memory engine is wired — the valve is on ` +
+        `with MEMORY_CONSOLIDATION_DRIVER=on, or with it unset when the consolidation seat runs on a model other than the ` +
+        `main one (MODEL_CHEAP_ID; the factory default) — so either set MEMORY_CONSOLIDATION_DRIVER=on (which also mounts the ` +
+        `manual valve, and note that BOTH knobs then bill whole-library model calls), configure MODEL_CHEAP_ID and leave it ` +
+        `unset, or set MEMORY_AUTO_CONSOLIDATION=off (unsetting it is NOT the same: the engine's named default is ON as of ` +
+        `core 7.21.1).`);
 }
 export function createMemoryConsolidationFaces(store, input) {
     const engine = new MemoryEngine({

package/dist/boot/resolve-spec.d.ts

@@ -39,6 +39,8 @@ export interface ResolveSpecCtx {
     /** 两张 per-session 登记簿的**租户围栏**(codex R1-F1):每次提交对拍本会话的主人,换主即清。
      *  论证(为什么 device lane 把这条从「不需要」变成「必需」)逐字见 `createSessionScopedRegistries` 头注。 */
     fenceSessionOwner: (sid: string, owner: string | null) => void;
+    /** S-506([ref] §5):装配期化身读数的写腿(per-session 登记簿,与围栏同一只;记忆座同步从那里读)。 */
+    noteSessionIncarnation: (sid: string, incarnation: string | undefined) => void;
     hookLlm: ReturnType<typeof createHookLlm>["hookLlm"];
     hookAgent: HookLlmCall;
     fleetBus: FleetEventBus;