@sema-agent/server 7.99.0 → 7.101.0

package/dist/instruction-source-notice.js

@@ -0,0 +1,78 @@
+import { recordFailOpen } from "./observability/fail-open.js";
+export const INSTRUCTION_SOURCE_CHANGED = "instructions.source_changed";
+export function encodeInstructionSource(source) {
+    return source ?? "";
+}
+export function sameInstructionSourceBaseline(a, b) {
+    if (!a.recorded || !b.recorded)
+        return a.recorded === b.recorded;
+    return a.source === b.source;
+}
+export function decodeInstructionSource(raw) {
+    if (raw === null || raw === undefined)
+        return { recorded: false };
+    if (typeof raw !== "string")
+        throw new TypeError(`instruction_source holds a ${typeof raw}, not a string`);
+    return { recorded: true, source: raw === "" ? null : raw };
+}
+export function instructionSourceStoreOf(sessionStore) {
+    const s = sessionStore;
+    if (typeof s?.readInstructionSource !== "function" || typeof s.recordInstructionSource !== "function")
+        return undefined;
+    return { readInstructionSource: s.readInstructionSource.bind(s), recordInstructionSource: s.recordInstructionSource.bind(s) };
+}
+export function createInstructionSourceSeat(sessionStore, emit) {
+    const store = instructionSourceStoreOf(sessionStore);
+    return store && emit ? { store, emit } : undefined;
+}
+const describeSource = (source) => source ?? "no project instruction file";
+export const BASELINE_IO_DEADLINE_MS = 2_000;
+class BaselineDeadlineExceeded extends Error {
+}
+function withinDeadline(op) {
+    const running = Promise.resolve().then(op);
+    running.catch(() => undefined);
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new BaselineDeadlineExceeded(`no answer within ${BASELINE_IO_DEADLINE_MS}ms`)), BASELINE_IO_DEADLINE_MS);
+        timer.unref?.();
+    });
+    return Promise.race([running, deadline]).finally(() => clearTimeout(timer));
+}
+export async function announceInstructionSource(seat, sessionId, current) {
+    let baseline;
+    try {
+        baseline = await withinDeadline(() => seat.store.readInstructionSource(sessionId));
+    }
+    catch (e) {
+        degraded("read", sessionId, e);
+        return;
+    }
+    if (baseline.recorded && baseline.source === current)
+        return;
+    if (baseline.recorded) {
+        const previous = baseline.source;
+        try {
+            seat.emit({
+                code: INSTRUCTION_SOURCE_CHANGED,
+                message: `Project instructions for this run come from ${describeSource(current)}; the previous run of this session read ${describeSource(previous)}.`,
+                detail: { previous, current, sessionId },
+                sessionId,
+            });
+        }
+        catch (e) {
+            degraded("emit", sessionId, e);
+        }
+    }
+    try {
+        await withinDeadline(() => seat.store.recordInstructionSource(sessionId, baseline, current));
+    }
+    catch (e) {
+        degraded("write", sessionId, e);
+    }
+}
+function degraded(op, sessionId, e) {
+    const why = e instanceof BaselineDeadlineExceeded ? `timeout=${BASELINE_IO_DEADLINE_MS}ms` : `err=${e instanceof Error ? e.message : String(e)}`;
+    recordFailOpen("server.instruction-source.announce-degraded", `op=${op} session=${sessionId} ${why}`);
+}
+//# sourceMappingURL=instruction-source-notice.js.map

package/dist/leader/wire.d.ts

@@ -3,6 +3,15 @@ import type { CheckpointStoreFull } from "../plugins/store-backend.js";
 import { type LeaderDeps, type LeaderResult } from "./leader.js";
 import { type DeploymentPostureSeats } from "../boot/runner-deps.js";
 import type { LeaderRequestBody } from "./endpoint.js";
+/** leader worker 的 durable 审批座(`LeaderWireConfig.durable` 函数席每次产出的一份)。 */
+export interface LeaderDurableSeat {
+    readonly checkpointStore: CheckpointStoreFull;
+    readonly requireApproval: string[];
+    readonly deny?: string[];
+    readonly ttlMs?: number;
+    readonly autoBudget?: number;
+    readonly neverAuto?: string[];
+}
 export interface LeaderWireConfig {
     /** Static-env compat mode (E2B only): the leader provisions/owns each env. Required when `envFactory` unset. */
     e2bApiKey?: string;
@@ -10,18 +19,17 @@ export interface LeaderWireConfig {
      *  REMOTE_EXEC (e2b or k8s/Kata) — workers and the integration sandbox run on envs from THIS factory.
      *  Requires `s3` (diff-out is the worker's self-upload; there is no leader-held env to pull from). */
     envFactory?: ExecutionEnvFactory;
-    /** Durable suspend/resume for SUB-WORKERS ([ref] C4): when set, each worker task carries the durable
-     *  question/ask policy + checkpoint store, so a gated ask/AskUserQuestion SUSPENDS the worker (checkpoint +
-     *  paused env) instead of failing — the trigger replan-lite C4 arbitrates on. Mirrors main.ts's per-task
-     *  durable wiring; ctx is seeded at provision so the surfaced token is resumable on the single-agent path. */
-    durable?: {
-        checkpointStore: CheckpointStoreFull;
-        requireApproval: string[];
-        deny?: string[];
-        ttlMs?: number;
-        autoBudget?: number;
-        neverAuto?: string[];
-    };
+    /** Durable suspend/resume for SUB-WORKERS ([ref] C4): when the seat yields a value, that worker task carries
+     *  the durable question/ask policy + checkpoint store, so a gated ask/AskUserQuestion SUSPENDS the worker
+     *  (checkpoint + paused env) instead of failing — the trigger replan-lite C4 arbitrates on. Mirrors main.ts's
+     *  per-task durable wiring; ctx is seeded at provision so the surfaced token is resumable on the single-agent path.
+     *
+     *  🔴 **函数席,不是快照**(S-668 波 2 ①;先例 = 下方 `deploymentPosture` 的 S-174 函数席):审批名单
+     *  (`governance.approvalRequire`)自本批起在进程内会被中心热换。boot 期取一次值会把这条腿钉在起服那一刻的名单上
+     *  —— 起服时名单为空 ⇒ 整块缺席、之后加进来的工具在 leader worker 上**永远**不被门住(fail-OPEN)。
+     *  `provisionWorker` 每只 worker 调一次(同一只 worker 的 toolPolicy / resource 停车 / ctx 保温读同一份);
+     *  返回 `undefined` = 这只 worker 不接 durable 审批(与修前「键缺席」同义)。 */
+    durable?: () => LeaderDurableSeat | undefined;
     /** Durable tool-result offload store (TiDB). REQUIRED for `durable` to actually suspend: core's suspend
      *  pre-commit refuses with the default InMemoryToolResultStore (offloaded results would deref to null after
      *  a cross-replica resume) and silently falls back to the synchronous onAsk gate — which the leader does not

package/dist/leader/wire.js

@@ -241,9 +241,10 @@ export function createLeaderRunner(cfg) {
         };
         const provisionWorker = async (sub) => {
             const sessionId = `leader-${sub.workerId}-${Date.now()}`;
+            const durable = cfg.durable?.();
             let durableSpec = {};
-            if (cfg.durable) {
-                const d = cfg.durable;
+            if (durable) {
+                const d = durable;
                 durableSpec = {
                     toolPolicy: combinePolicies(createDurableQuestionPolicy(), createDurableAskPolicy({ requireApproval: d.requireApproval, ...(d.deny ? { deny: d.deny } : {}), ...(d.autoBudget ? { autoBudget: d.autoBudget } : {}), ...(d.neverAuto ? { neverAuto: d.neverAuto } : {}) })),
                     checkpointStore: d.checkpointStore,
@@ -259,9 +260,9 @@ export function createLeaderRunner(cfg) {
             if (repairLoopActive && resourceCfg) {
                 cfg.logger?.warn?.("leader_resource_suspend_disabled_for_repair_loop", { workerId: sub.workerId, reason: "LEADER_REPAIR_LOOP active — resource-suspend mutually exclusive with the repair loop (§10.5)" });
             }
-            if (resourceCfg && !repairLoopActive && cfg.durable && cfg.toolResultStore && cfg.sessionStore) {
+            if (resourceCfg && !repairLoopActive && durable && cfg.toolResultStore && cfg.sessionStore) {
                 resourceSpec = {
-                    checkpointStore: cfg.durable.checkpointStore,
+                    checkpointStore: durable.checkpointStore,
                     resourceSuspend: { scope: `_leader-resource-${sub.workerId}`, totalBudgetUsd: resourceCfg.totalBudgetUsd },
                     limits: { ...workerLimits.limits, maxCostUsd: resourceCfg.sliceMaxCostUsd },
                     maxSuspends: resourceCfg.maxSuspends,
@@ -270,7 +271,7 @@ export function createLeaderRunner(cfg) {
             else if (resourceCfg && !repairLoopActive) {
                 cfg.logger?.warn?.("leader_resource_suspend_inactive", {
                     workerId: sub.workerId,
-                    reason: !cfg.durable
+                    reason: !durable
                         ? "no durable checkpoint store"
                         : !cfg.toolResultStore
                             ? "no durable tool-result store"
@@ -278,7 +279,7 @@ export function createLeaderRunner(cfg) {
                 });
             }
             const keepCtxWarm = (runner) => {
-                const d = cfg.durable;
+                const d = durable;
                 if (!d)
                     return runner;
                 const orig = runner.runTaskStream.bind(runner);

package/dist/memory-layer-legacy-lock.d.ts

@@ -0,0 +1,14 @@
+import type { EngineNotice } from "@sema-agent/core";
+import type { ServerNoticeCode } from "./trace/engine-notice-wire.js";
+export declare const MEMORY_LAYER_LOCKED_LEGACY: ServerNoticeCode;
+/** 探测读数:锁住的层名(排序)+ 看不全的目录条数。挂载面不存在(新数据根)⇒ 两者皆空。 */
+export interface LockedLegacyLayerProbe {
+    readonly layers: readonly string[];
+    readonly unreadable: number;
+}
+export declare function probeLockedLegacyMemoryLayers(memoryDir: string): LockedLegacyLayerProbe;
+/** 锁住的层 ⇒ 一条通告(纯数据);没有 ⇒ `undefined`。detail 两键:`layers`(层名)与 `remedy`(同一句 `chmod -R u+w <memoryDir>`)。 */
+export declare function buildMemoryLayerLockedLegacyNotice(memoryDir: string, layers: readonly string[]): EngineNotice | undefined;
+/** boot 期的唯一调用口:探测一次、有锁住的层就经 `emit` 发一条;看不全的子树走 F 类留痕。不抛(不拒启)。 */
+export declare function announceLockedLegacyMemoryLayers(memoryDir: string, emit: (notice: EngineNotice) => void): void;
+//# sourceMappingURL=memory-layer-legacy-lock.d.ts.map

package/dist/memory-layer-legacy-lock.js

@@ -0,0 +1,74 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { recordFailOpen } from "./observability/fail-open.js";
+export const MEMORY_LAYER_LOCKED_LEGACY = "memory.layer_locked_legacy";
+const OWNER_WRITE = 0o200;
+function shellQuoted(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+const isMissing = (err) => err?.code === "ENOENT";
+function treeHasLockedDir(dir, gaps) {
+    let st;
+    try {
+        st = lstatSync(dir);
+    }
+    catch (err) {
+        if (!isMissing(err))
+            gaps.n += 1;
+        return false;
+    }
+    if (!st.isDirectory())
+        return false;
+    if ((st.mode & OWNER_WRITE) === 0)
+        return true;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (!isMissing(err))
+            gaps.n += 1;
+        return false;
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && treeHasLockedDir(join(dir, e.name), gaps))
+            return true;
+    }
+    return false;
+}
+export function probeLockedLegacyMemoryLayers(memoryDir) {
+    const gaps = { n: 0 };
+    let top;
+    try {
+        top = readdirSync(memoryDir, { withFileTypes: true });
+    }
+    catch (err) {
+        return { layers: [], unreadable: isMissing(err) ? 0 : 1 };
+    }
+    const layers = top.filter((e) => e.isDirectory() && treeHasLockedDir(join(memoryDir, e.name), gaps)).map((e) => e.name);
+    return { layers: layers.sort(), unreadable: gaps.n };
+}
+export function buildMemoryLayerLockedLegacyNotice(memoryDir, layers) {
+    if (layers.length === 0)
+        return undefined;
+    const remedy = `chmod -R u+w ${shellQuoted(memoryDir)}`;
+    const one = layers.length === 1;
+    return {
+        code: MEMORY_LAYER_LOCKED_LEGACY,
+        message: `memory layer${one ? "" : "s"} ${layers.map((l) => JSON.stringify(l)).join(", ")} ${one ? "still carries" : "still carry"} the read-only permission bits ` +
+            "an engine from 7.30.x or earlier (a server replica at 7.100.0 or earlier) sets on every layer it mounts read-only — deleting an " +
+            "entry there (memory erase / origin clear) fails for a server that does not run as root: the request answers 500, its journal " +
+            `stays on disk and this replica's next start fails. Run \`${remedy}\` once no such engine still runs on this store (an older ` +
+            "replica sets the bits again whenever it mounts a layer read-only). Starting anyway.",
+        detail: { layers: [...layers], remedy },
+    };
+}
+export function announceLockedLegacyMemoryLayers(memoryDir, emit) {
+    const probe = probeLockedLegacyMemoryLayers(memoryDir);
+    if (probe.unreadable > 0)
+        recordFailOpen("server.memory.locked-layer-probe-partial", `unreadable=${probe.unreadable}`);
+    const notice = buildMemoryLayerLockedLegacyNotice(memoryDir, probe.layers);
+    if (notice !== undefined)
+        emit(notice);
+}
+//# sourceMappingURL=memory-layer-legacy-lock.js.map

package/dist/memory-store-refusal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * core 7.31.1 #1094 —— **`memory.target_outside_store`** 在本仓的唯一读法属主(纯叶:零 http / 零 boot 依赖)。
+ *
+ * ## 这个码说的是什么(core `docs/wire-consumption/7.31.1.md` 逐 face 表,tag v7.31.1 亲读)
+ * 记忆 store 里的一个目录经软链通到了 store **外**(或 store 根在 backend 打开 / 引擎首次挂载之后被改指)⇒ 引擎对落点在外的
+ * 删 / 写 / 重放 / 自身写一律**不做**,抛普通 `Error` + `.code`(文案以码领头,点名动作、路径、解析到哪)。core 的读法原话:
+ * operator 要处置的拒(去掉那只目录链),**不是**可重试的 IO 故障,也**不是**对调用方的裁决;链去掉之前重发恒拒。
+ *
+ * ## 两条到达车道,两个读者(本模块各给一只,别处不许再写第二份判据)
+ *  ① **抛出面**(抹除 / 出处 / 外源列表 / 清标 / bundle 导出导入 —— 凡触 store 树的 backend 面):`.code` 就是码
+ *     ⇒ {@link targetOutsideStoreOf}。HTTP 映射在 `http/memory-store-refusal-reply.ts`(409,一处字面量)。
+ *  ② **报告面**(harvest `incident`):core 契约写明 report 车道上码**只在文本里** —— `sidecar_corrupt` 的 detail 恰两种形
+ *     `memory commit refused: memory.target_outside_store: …` / `memory control plane refused: memory.target_outside_store: …`
+ *     (core `docs/wire-consumption/7.31.1.md` 的 harvest 行逐字)⇒ {@link targetOutsideStoreInIncident} 只认**这两个 lead 紧跟码**
+ *     的位置:lead 与码都是 core 铸的字面,路径与引用数据全在码之后。🔴 不做全文子串找(codex 一审 C2:一条真控制面损坏若在
+ *     它引用的坏数据里恰好带着这串字,子串找会把它标成目录链 —— 两者运维动作相反)。不读散文、不猜语义;结构化码位
+ *     (`HarvestReport.incident` / `.warnings` 带码)是向 core 索取的欠账。
+ *     ⚠️ 同一拒的**还原类**(缺失文件还原 / 只读层还原 / `MEMORY.md` 写)只进 `HarvestReport.warnings`(可以 `ok:true`、无 incident),
+ *     那几行的前缀是**条目路径**(模型可写)—— 本仓今天不读 warnings 车道(既有面,不是本批回归),也不在模型可写的文本上
+ *     找码;这一半候 core 的结构化码位(登记在案,codex 一审 C3)。
+ *
+ * ## 不是这个码的三形(core 同表「different surface」,本仓**不**自拼码,如实走各自既有臂)
+ *  · journal 重放目标目录成链 ⇒ `ControlPlaneCorruptError`(无 `.code`,KL-1094-b)⇒ 路由 typed 500 `internal.memory_control_plane_corrupt`;
+ *  · 引擎原地写撞硬链(nlink>1)⇒ 文本 `has N names (a hard link)`、无码(KL-1094-g / #1105)⇒ 走该写点既有的失败车道(harvest
+ *    warnings / 挂载失败),抛出面够不着;
+ *  · 解析故障(`EACCES` / `ELOOP` / `ENOTDIR`)⇒ 以 errno 本身抛 ⇒ 路由未分类 500 + 运维 warn(`String(err)` 带 core 补救句)。
+ */
+/** core 的码(`src/core/memory-engine/layout.ts` `TARGET_OUTSIDE_STORE`;core 不在包根导出它,本常量是它在本仓的唯一写点)。 */
+export declare const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+/** 抛出面:`err` 是这一拒 ⇒ 原样交回(已窄化成 `Error`,调用方要它的 `message`);否则 `undefined`。形 = core 的 `Error` + `.code`。 */
+export declare function targetOutsideStoreOf(err: unknown): Error | undefined;
+/** 报告面:harvest `incident` 是这一拒 ⇒ 码;否则 `undefined`(真控制面损坏的 `sidecar_corrupt` 走这一臂 —— 不被说成链)。 */
+export declare function targetOutsideStoreInIncident(incident: {
+    readonly kind: string;
+    readonly detail: string;
+}): typeof TARGET_OUTSIDE_STORE | undefined;
+//# sourceMappingURL=memory-store-refusal.d.ts.map

package/dist/memory-store-refusal.js

@@ -0,0 +1,14 @@
+export const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+export function targetOutsideStoreOf(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const { code } = err;
+    return code === TARGET_OUTSIDE_STORE ? err : undefined;
+}
+const INCIDENT_PREFIXES = [`memory commit refused: ${TARGET_OUTSIDE_STORE}: `, `memory control plane refused: ${TARGET_OUTSIDE_STORE}: `];
+export function targetOutsideStoreInIncident(incident) {
+    if (incident.kind !== "sidecar_corrupt")
+        return undefined;
+    return INCIDENT_PREFIXES.some((p) => incident.detail.startsWith(p)) ? TARGET_OUTSIDE_STORE : undefined;
+}
+//# sourceMappingURL=memory-store-refusal.js.map

package/dist/model-entry-refusal.d.ts

@@ -0,0 +1,130 @@
+/** 不可用的成因 —— **闭集**(加一个成因 ⇒ {@link MODEL_ENTRY_REFUSAL_CODES} 与 {@link refusalEventOf} 编译红)。 */
+export type ModelEntryRefusalReason = "no_brain" | "entry_invalid";
+/** 机读码(拼法随 `config.*` 家族,按**规则**命名):出现在拒因句的方括号里、warn 字段里、`modelRefusals` 里。 */
+export declare const MODEL_ENTRY_REFUSAL_CODES: {
+    readonly no_brain: "config.model_no_brain";
+    readonly entry_invalid: "config.model_entry_invalid";
+};
+export type ModelEntryRefusalCode = (typeof MODEL_ENTRY_REFUSAL_CODES)[ModelEntryRefusalReason];
+/** 「这张表没有缺省模型」的机读码(S-705;boot 拒启与热路径模型面组拒同一个码)。 */
+export declare const DEFAULT_MODEL_MISSING_CODE = "config.default_model_missing";
+/** 🔴 S-712「被拒的名字被档位 / 别名增广铸到了别的条目上(或读不出被丢条目的名字,无从证明没有)」的机读码
+ *  (不变量 `refused-names-not-minted`;热路径 / boot 首次 apply / dry-run 同一个码)。 */
+export declare const REFUSED_NAME_MINTED_CODE = "config.model_refused_name_minted";
+/**
+ * 一条不可用条目的**事实**(纯数据;`config.modelRefusals[<name>]` 的值)。
+ * 🔴 不含任何值:不含 baseUrl、不含钥匙、不含坏字段的原值 —— 只有成因、码、上游 id(显式选择按 id 形也要命中)、
+ * 坏字段的**键名**,与一句给运维的出路。
+ */
+export interface ModelEntryRefusal {
+    readonly reason: ModelEntryRefusalReason;
+    readonly code: ModelEntryRefusalCode;
+    /** 条目的上游 `id`(壳常按 id 形回读 mainLoopModel —— 按 id 选中同样要拿到拒因,不许落「未知模型」)。 */
+    readonly id: string;
+    /** 条目写的 provider 词(`no_brain` 的主语;`entry_invalid` 时照录,词可能本身就是坏的那一处)。 */
+    readonly provider: string;
+    /** `entry_invalid`:不合形的字段键路径(`contextWindow` / `cost.input` / `api` …);`no_brain` 恒空。 */
+    readonly fields: readonly string[];
+    /** 一句话:为什么不可用 + 出路(不含值)。 */
+    readonly detail: string;
+}
+/** 判据要知道的**部署事实**(不在条目里)。 */
+export interface CatalogEntryVerdictCtx {
+    /** anthropic 路由装上了没有(= `config.anthropic` 在场,`createBrain` 同判)。 */
+    readonly anthropicRouteMounted: boolean;
+}
+/** 条目最小读面(`CenterModel` 与本地投影都结构满足;形判走 settings-schema,不信这张型)。 */
+export interface CatalogEntryLike {
+    readonly name: string;
+    readonly id: string;
+    readonly provider: string;
+}
+/**
+ * **逐条判据**:`undefined` = 本部署能完整服务它。判序即语义:先形(不合形的条目谈不上走哪条腿),再腿。
+ *
+ * 形判的属主是 settings-schema 的 `ModelEntry`(两条读腿用的就是它)—— 本仓不手抄任何一条字段规则;这里只是
+ * 在第二道边界(绕过读腿的输入)上**再问一次同一个属主**,并把答案变成一条带码的拒因。只取 `success` 与 issue
+ * 坐标,不取它的输出(输出会补缺省、剥扩展键,那是读腿的事)。
+ */
+export declare function judgeCatalogEntry(m: CatalogEntryLike, ctx: CatalogEntryVerdictCtx): ModelEntryRefusal | undefined;
+/** 一批已启用条目的判决:可用的(保序)、不可用的(按 catalog name)、以及身份证明不了的被丢条目(坐标)。 */
+export interface CatalogEntriesVerdict<M extends CatalogEntryLike> {
+    readonly usable: readonly M[];
+    readonly refused: Readonly<Record<string, ModelEntryRefusal>>;
+    /** S-712:读腿逐条丢掉、而身份证明不了的条目坐标(`models.3`;载体上不带 `name` 的那些 —— 读腿只在原文档对不上本次解析时
+     *  这样交出,见 `read-warnings.ts` `DroppedModelIdentity`)。非空 ⇒ 不变量 `refused-names-not-minted` 无从成立 ⇒ 模型面组拒。 */
+    readonly unreadable: readonly string[];
+}
+/**
+ * 批量形(模型面 stage 与 dry-run 共用这一只 —— 报数与真 apply 永不撕裂)。
+ * S-712:`dropped` = 读腿交出的被丢条目身份(`EffectiveConfig.models.droppedIdentities`)—— 它们与逐条判据判出的 `entry_invalid`
+ * 是**同一件事**(条目不合 `ModelEntry` 形),只是在第一道边界就被丢了;带名字的铸墓碑,不带名字的(读腿证明不了身份)进
+ * `unreadable`。没有字符串名的坏行读腿已按停用处置、根本不进载体(7.101.0 验修轮 V-2:没有名字就没有可保留的名字)。
+ * 入参按 `unknown` 判形:载体可能来自盘上 LKG(本仓写的,但文件可被改),形不对的一律按证明不了处置(fail-closed)。
+ * 与一条可用 / 已判不可用条目同名时不覆盖(可用条目仍可用;同名撞车由不变量 `refused-names-not-minted` 响亮拒)。
+ */
+export declare function judgeCatalogEntries<M extends CatalogEntryLike>(enabled: readonly M[], ctx: CatalogEntryVerdictCtx, dropped?: unknown): CatalogEntriesVerdict<M>;
+/** 成因 → 它那一条 warn 的事件名(**穷举**)。两个名字是票面点名的既有/新事件,运维的告警规则按名挂。 */
+export declare function refusalEventOf(reason: ModelEntryRefusalReason): "sema_registry_model_no_brain" | "sema_registry_model_entry_invalid";
+/** warn 字段(不含值):`field` = 第一处坏字段(告警规则最常按它分组),`fields` = 全部。 */
+export declare function refusalWarnFields(name: string, r: ModelEntryRefusal): Record<string, unknown>;
+/**
+ * 一次**显式选择**命中了不可用条目时的拒因句(HTTP `request.model_unavailable` 的 `error`、run-local 的 stderr、
+ * hook 选模型的失败文案 —— 各处同一句)。`field` = 调用方的通道名(`model` / `compactionModel` / `agents[0].model` /
+ * `@-mention`),`requested` = 调用方发来的原形(name 或 id),已由调用方截断。
+ */
+export declare function modelUnavailableMessage(field: string, requested: string, name: string, r: ModelEntryRefusal): string;
+/** 缺省模型不变量读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
+export interface DefaultModelView {
+    readonly models: Readonly<Record<string, unknown>>;
+    readonly modelRefusals: Readonly<Record<string, ModelEntryRefusal>>;
+}
+/**
+ * 这张表是从哪条腿来的(闭集 —— 拒因句的出路按腿分:加腿不补 {@link defaultModelRefusal} 的臂 = 编译红)。
+ *  · `env` —— 进程此刻服务的表**没有目录在管**(没配目录 / 目录迟到且无 LKG / 目录的模型面这一组被拒):`MODEL_ID` 是出路之一;
+ *  · `catalog` —— 判的是一份**目录候选**(模型面 stage):目录一旦生效就整张换掉 env 表,`MODEL_ID` 救不了这份候选 ——
+ *    出路只在目录里(修条目 / 换绑)。opus 腿 ④(7.101.0 合并复审):此前两腿同一句,目录腿教「设 MODEL_ID 即可」是假话。
+ */
+export type ModelTableLeg = "env" | "catalog";
+/**
+ * 🔴 S-705 —— **这张模型表有没有一只缺省模型**(`models.default`)。`undefined` = 有。
+ *
+ * 规则只有一句:**进程服务的那张表必须有 `default`**。env 腿(`MODEL_ID`)与目录腿(缺省解析)是它的两个来源,
+ * 任一在场即过;目录一旦生效就整张换掉 env 表,所以判的永远是「生效之后的那张表」—— 这正是它必须在目录应用
+ * **之后**判的理由(此前 `parseModelDomain` 在目录应用之前就对 `MODEL_ID` 空串拒启,把只配了目录的用户无谓拒掉)。
+ *
+ * 拒因一句:码 + 这条腿上**真实**的出路 + 若目录在场但每条都不可用,点名它们与各自的码。env 腿句首保留 `MODEL_ID is required`
+ * 这个既有的可 grep 片段(壳与运维脚本认它);目录腿不提 `MODEL_ID`(见 {@link ModelTableLeg})。
+ */
+export declare function defaultModelRefusal(view: DefaultModelView, leg: ModelTableLeg): string | undefined;
+/** 一个被铸出的被拒名字:`name` = 被拒条目的名字,`target` = 增广把它指向的那条条目,`via` = 它是以什么身份被铸出的。 */
+export interface MintedRefusedName {
+    readonly name: string;
+    readonly target: string;
+    /** `tier-word`(档位词)/ `cc-alias`(CC 别名 → 它的档位)/ `best`(头档别名)/ `catalog-entry`(一条可用条目与它同名)。 */
+    readonly via: string;
+    /** 被拒条目自己的拒因码。 */
+    readonly code: ModelEntryRefusalCode;
+}
+/** 不变量 `refused-names-not-minted` 读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
+export interface RefusedNameView {
+    readonly models: Readonly<Record<string, unknown>>;
+    readonly tiers: Readonly<Record<string, string>>;
+    readonly modelRefusals: Readonly<Record<string, ModelEntryRefusal>>;
+}
+/**
+ * 🔴 S-712 —— 不变量 `refused-names-not-minted` 的判据:**这张表回应的每一个名字(目录键 ∪ core `expandTiers` 增广出来的档位词 /
+ * CC 别名 / `best`)都不是一个被拒条目的名字**。返回撞上的那些(空 = 成立)。
+ *
+ * 为什么是「增广之后」:引擎在构造 / 换装时自己 `expandTiers(models, tiers)`,显式 `model:"sonnet"` 与角色绑定 `advisor→sonnet` 都在
+ * 增广目录上解析。一条条目被拒(不可用 / 被 schema 丢掉)之后它的名字空出来,同名的档位词 / CC 别名就不再被它 shadow,增广把
+ * 那个词铸到另一条条目上 —— 点它的请求被静默换了目的地、端点与账号(gpt-6 腿 F2 / F3,真复现)。判「增广之后」让引擎拿到的目录
+ * **永远没有**被拒名:显式点它落 `request.model_unavailable`(选择面让出名字 + 查拒因表),角色绑定落引擎对未知名的响亮拒。
+ * 可用条目与被拒条目同名(同一个名字发布了两条、其中一条坏的)同样算撞:哪一条才是运维的意思无从判,拒比猜安全。
+ */
+export declare function mintedRefusedNames(view: RefusedNameView): MintedRefusedName[];
+/** 不变量 `refused-names-not-minted` 的拒因句(`undefined` = 成立)。warn 与世代账 / 拒因同一句;逐对明细另走 {@link mintedRefusedNames}。 */
+export declare function refusedNameMintedRefusal(view: RefusedNameView): string | undefined;
+/** 身份证明不了的被丢条目的拒因句(同一不变量同一个码:证明不了的名字无从证明它不被增广铸出)。 */
+export declare function unreadableDroppedRefusal(entries: readonly string[]): string;
+//# sourceMappingURL=model-entry-refusal.d.ts.map

package/dist/model-entry-refusal.js

@@ -0,0 +1,157 @@
+import { CC_MODEL_TIER_ALIASES, DEFAULT_TIER_ORDER, expandTiers } from "@sema-agent/core";
+import { ModelEntry } from "@sema-agent/settings-schema";
+import { catalogBrainLane } from "./model-provider.js";
+import { describeSchemaIssueFields, describeSchemaIssues } from "./config-center/read-warnings.js";
+import { DEFAULT_MODEL_REF } from "./model-select.js";
+export const MODEL_ENTRY_REFUSAL_CODES = {
+    no_brain: "config.model_no_brain",
+    entry_invalid: "config.model_entry_invalid",
+};
+export const DEFAULT_MODEL_MISSING_CODE = "config.default_model_missing";
+export const REFUSED_NAME_MINTED_CODE = "config.model_refused_name_minted";
+function laneMount(lane, ctx) {
+    switch (lane) {
+        case "gateway":
+            return { mounted: true, how: "" };
+        case "anthropic":
+            return { mounted: ctx.anthropicRouteMounted, how: "ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) in this service's env" };
+    }
+}
+export function judgeCatalogEntry(m, ctx) {
+    const shape = ModelEntry.safeParse(m);
+    if (!shape.success) {
+        const fields = describeSchemaIssueFields(shape.error);
+        return entryInvalidRefusal(typeof m.id === "string" ? m.id : "", typeof m.provider === "string" ? m.provider : "", fields, describeSchemaIssues(shape.error) ?? fields.join(", "));
+    }
+    const lane = catalogBrainLane(m.provider);
+    const mount = laneMount(lane, ctx);
+    if (!mount.mounted) {
+        return {
+            reason: "no_brain",
+            code: MODEL_ENTRY_REFUSAL_CODES.no_brain,
+            id: m.id,
+            provider: m.provider,
+            fields: [],
+            detail: `provider "${m.provider}" rides the ${lane} brain, which is not mounted on this deployment — the entry is not served here ` +
+                `(it is never routed to another brain with its own key); set ${mount.how}, ` +
+                'or change the entry\'s provider to an OpenAI-compatible route ("gateway" / "vllm") with its own baseUrl',
+        };
+    }
+    return undefined;
+}
+function entryInvalidRefusal(id, provider, fields, issues) {
+    return {
+        reason: "entry_invalid",
+        code: MODEL_ENTRY_REFUSAL_CODES.entry_invalid,
+        id,
+        provider,
+        fields: [...fields],
+        detail: `the catalog entry does not match the settings-schema ModelEntry shape (${issues}) — it is dropped from this ` +
+            "deployment's catalog on its own (the other entries keep serving) instead of being served with a value nothing validated; fix the entry to bring it back",
+    };
+}
+export function judgeCatalogEntries(enabled, ctx, dropped) {
+    const usable = [];
+    const refused = {};
+    for (const m of enabled) {
+        const r = judgeCatalogEntry(m, ctx);
+        if (r === undefined)
+            usable.push(m);
+        else
+            refused[String(m.name)] = r;
+    }
+    const unreadable = [];
+    for (const d of Array.isArray(dropped) ? dropped : []) {
+        const e = (typeof d === "object" && d !== null ? d : {});
+        const where = typeof e.entry === "string" ? e.entry : "(unknown coordinate)";
+        if (typeof e.name !== "string") {
+            unreadable.push(where);
+            continue;
+        }
+        if (Object.hasOwn(refused, e.name))
+            continue;
+        const fields = Array.isArray(e.fields) ? e.fields.filter((f) => typeof f === "string") : [];
+        refused[e.name] = entryInvalidRefusal(typeof e.id === "string" ? e.id : "", typeof e.provider === "string" ? e.provider : "", fields, typeof e.issues === "string" ? e.issues : fields.join(", "));
+    }
+    return { usable, refused, unreadable };
+}
+export function refusalEventOf(reason) {
+    switch (reason) {
+        case "no_brain":
+            return "sema_registry_model_no_brain";
+        case "entry_invalid":
+            return "sema_registry_model_entry_invalid";
+    }
+}
+export function refusalWarnFields(name, r) {
+    return {
+        model: name,
+        provider: r.provider,
+        code: r.code,
+        ...(r.fields.length > 0 ? { field: r.fields[0], fields: [...r.fields] } : {}),
+        hint: r.detail,
+    };
+}
+export function modelUnavailableMessage(field, requested, name, r) {
+    const alias = requested === name ? "" : ` (catalog entry "${name}")`;
+    return `${field} "${requested}"${alias} is published in the catalog but unavailable on this deployment [${r.code}] — ${r.detail}`;
+}
+export function defaultModelRefusal(view, leg) {
+    if (Object.hasOwn(view.models, DEFAULT_MODEL_REF) && view.models[DEFAULT_MODEL_REF] !== undefined)
+        return undefined;
+    const refused = Object.entries(view.modelRefusals).map(([n, r]) => `"${n}" [${r.code}]`);
+    const unavailable = refused.length > 0 ? ` (every enabled catalog entry is unavailable on this host: ${refused.join(", ")})` : "";
+    switch (leg) {
+        case "env":
+            return (`MODEL_ID is required when no catalog default resolves [${DEFAULT_MODEL_MISSING_CODE}] — this model table has no default model` +
+                unavailable +
+                ". Set MODEL_ID=<model name your gateway serves>, or enable at least one model this host can serve in the catalog " +
+                "(config.d/models.json, or the config center) — either one is enough (a config center that answers after the boot budget " +
+                "counts as absent at boot: raise CONFIG_BOOT_FETCH_BUDGET_MS to wait for it).");
+        case "catalog":
+            return (`this catalog candidate has no default model [${DEFAULT_MODEL_MISSING_CODE}]` +
+                unavailable +
+                " — fix the named entries (each has its own warn with the reason) or enable / bind a default this host can serve, in the catalog itself " +
+                "(a catalog in force replaces the env model table, so MODEL_ID cannot stand in for it).");
+    }
+}
+function mintedVia(name, own, tiers) {
+    if (own)
+        return "catalog-entry";
+    if (Object.hasOwn(CC_MODEL_TIER_ALIASES, name))
+        return `cc-alias of tier "${CC_MODEL_TIER_ALIASES[name]}"`;
+    if (name === "best")
+        return "best-tier alias";
+    if (DEFAULT_TIER_ORDER.includes(name) || Object.hasOwn(tiers, name))
+        return "tier word";
+    return "expansion key";
+}
+export function mintedRefusedNames(view) {
+    const refusedNames = Object.keys(view.modelRefusals);
+    if (refusedNames.length === 0)
+        return [];
+    const expanded = (expandTiers(view.models, view.tiers) ?? view.models);
+    const out = [];
+    for (const name of refusedNames) {
+        if (!Object.hasOwn(expanded, name) || expanded[name] === undefined)
+            continue;
+        const t = expanded[name]?.name;
+        out.push({ name, target: typeof t === "string" && t.length > 0 ? t : name, via: mintedVia(name, Object.hasOwn(view.models, name), view.tiers), code: view.modelRefusals[name].code });
+    }
+    return out;
+}
+export function refusedNameMintedRefusal(view) {
+    const minted = mintedRefusedNames(view);
+    if (minted.length === 0)
+        return undefined;
+    const pairs = minted.map((m) => `"${m.name}" [${m.code}] → "${m.target}" (${m.via})`);
+    return (`unavailable catalog entries would be re-minted onto other entries by the tier/alias expansion [${REFUSED_NAME_MINTED_CODE}]: ${pairs.join(", ")} — ` +
+        "an explicit pick of that name (or a role bound to it) would silently run on the other entry's endpoint and account; " +
+        "rename the unavailable entry, fix it (see its own warn), or rebind / drop the tier binding that mints the name.");
+}
+export function unreadableDroppedRefusal(entries) {
+    return (`catalog entries dropped by the settings-schema read could not be identified [${REFUSED_NAME_MINTED_CODE}]: ${entries.join(", ")} — ` +
+        "the raw document could not be matched to the snapshot that was parsed (e.g. the local file changed between two reads), so the candidate cannot prove the tier/alias expansion does not re-mint their names; " +
+        "the next read re-judges (fix the named entries if this persists).");
+}
+//# sourceMappingURL=model-entry-refusal.js.map

package/dist/model-provider.d.ts

@@ -69,9 +69,11 @@ export declare function modelBrainLane(provider: ModelProvider): ModelBrainLane;
  * unrecognized provider)" 是它的原话)。本函数做的只是把那句散文变成**一个有名字的判词**,于是
  * 「目录里写了个没人认识的 provider」这件事在代码里有一处可指的坐标,而不是散在两个 `=== "anthropic"` 里。
  *
- * ⚠️ **未闭环**(S-461 收车档登记):目录词今天仍然**无声**地落进网关腿。要让它也响亮,需要的是一条
- * **热路径上的**告警/拒收(config-center 应用期逐条校验 + 运维可读的拒因),那是另一件事、另一台车 ——
- * 在这里加一个 throw 会让一次热发布打死在跑的副本,方向反了。
+ * ⚠️ **未闭环(收窄后如实)**:认不出的目录词今天仍然**无声**地落进网关腿(OpenAI 兼容;条目带自己的 baseUrl /
+ * 钥匙,打的是它自己的端点 —— 不是凭据越界,是词面失真)。S-704(7.101.0)已把**热路径上的逐条判据**落地
+ * (`model-entry-refusal.ts`:本部署没有对应 brain 的条目整条不可用 —— 今天那一形是「anthropic 词 + 本机没装
+ * anthropic 路由」),但**域外词**是否也该不可用是另一个问题(web-admin 的新条目缺省就写 `"openai"`,预设写厂商名;
+ * 把它们判不可用会让大量在跑的目录整条消失),另车带三问定。在这里加一个 throw 会让一次热发布打死在跑的副本,方向反了。
  */
 export declare function catalogBrainLane(provider: string | undefined): ModelBrainLane;
 /**
@@ -85,6 +87,10 @@ export declare function catalogBrainLane(provider: string | undefined): ModelBra
  * 所以「这条路由要不要一个 openai 端点」的判据必须同时看词与装配:词判 {@link catalogBrainLane},
  * 装配判路由在不在。本函数是这一合取的**唯一**写法 —— 端点判官(`model-route-endpoint.ts`)、降级腿与
  * 启动摘要(`brain.ts`)都调它,不再各写一个 `=== "anthropic" && config.anthropic`。
+ *
+ * 🔴 S-704(7.101.0):**目录条目**已到不了「anthropic 词、路由没装」这一格 —— 模型面 stage 的逐条判据把它判成不可用
+ * (`config.model_no_brain`,不进 `config.models`)。这一格今天只剩 **env 腿**:`MODEL_PROVIDER=anthropic` 而没配 anthropic
+ * 凭据的部署,env 模型落网关腿、用的是网关自己的 `MODEL_API_KEY`(凭据与端点同属网关,不越界;是否也该拒启另车)。
  */
 export declare function dispatchBrainLane(provider: string | undefined, anthropicRouteMounted: boolean): ModelBrainLane;
 //# sourceMappingURL=model-provider.d.ts.map

package/dist/model-route-endpoint.d.ts

@@ -17,7 +17,7 @@
  * ## 执法点(判据只在这里,执法点在调用处 —— 与 S-475 `gateway-url-userinfo` 同形)
  *  · boot:`config.ts` 九域解析之后的跨域不变量区(锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启;严格名册
  *    布防(`isRosterGateArmed`)时 env 腿是占位、从不被派发 ⇒ 不判它(备用网关那一条照判);
- *  · 热路径:`config-center/apply-effective.ts` 的模型面 stage ⇒ 候选整批拒、上一代继续服务;
+ *  · 热路径:`config-center/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务;
  *  · run-local:配置源解析完之后按真要派发的表再判一次(`run-local.ts`,7.98.0 合并复审 F2)—— 本入口没有名册门,
  *    loadConfig 对严格名册布防的占位豁免在这里兑现不了;没布防时恒惰性;
  *  · 登记:`config-invariants.ts` 的 `model-route-endpoint` 条(表的「不许有表外不变量」职责);