@sema-agent/server 7.130.0 → 7.131.0

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

@@ -15,12 +15,15 @@
  * (`MODEL_GATEWAY_FALLBACK_URLS`)是主网关的镜像,没有主就没有镜像 ⇒ 拒。
  *
  * ## 执法点(判据只在这里,执法点在调用处 —— 与 S-475 `gateway-url-userinfo` 同形)
- *  · boot:`config.ts` 九域解析之后的跨域不变量区(锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启;经 `model-route-gap.ts`
- *    的 {@link judgeModelRouteGap}(env 读成本文件判据要的切面,与包根导出的纯判官是**同一只**);严格名册
- *    布防(`isRosterGateArmed`)时 env 腿是占位、从不被派发 ⇒ 不判它(备用网关那一条照判);
- *  · 热路径:`web-admin-client/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务;
- *  · run-local:配置源解析完之后按真要派发的表再判一次(`run-local.ts`,7.98.0 合并复审 F2)—— 本入口没有名册门,
- *    loadConfig 对严格名册布防的占位豁免在这里兑现不了;没布防时恒惰性;
+ * **判官只判「将要服务的那张表」,拒因句按视图说真话**(视图词 = {@link ModelTableLeg} 两词,进判据入参,不靠调用方拼句):
+ *  · boot:装配第 2 段**目录应用之后**的跨域不变量区(`boot/stage-02-web-admin-pull.ts`,锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启 ——
+ *    经 {@link judgeServedModelRoute}:目录被采纳 ⇒ 判目录表(目录视图),目录缺席 / 被整拒 / 没有启用条目 ⇒ 判 env 表(env 视图);
+ *    严格名册布防(`isRosterGateArmed`)时 env 表是占位、从不被派发 ⇒ 不判它(备用网关那一条与表无关,照判)。
+ *    不在 `loadConfig()`:那是目录应用**之前**,env 表还不知道会不会服务(目录一旦采纳就整张换掉它);
+ *  · 包根导出的 `judgeModelRouteGap(env)`(`model-route-gap.ts`)问的是**env 腿**:「这份 env 交给引擎、没有目录时起不起得来」—— 同一只判据的 env 视图,
+ *    目录在场时起服以目录为准;
+ *  · 热路径:`web-admin-client/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务(目录视图);
+ *  · run-local:配置源解析完之后按真要派发的表判(`run-local.ts`)—— 本入口没有名册门,不豁免占位;
  *  · 登记:`config-invariants.ts` 的 `model-route-endpoint` 条(表的「不许有表外不变量」职责);
  *  · 派发面:titler / hook 选模型(`hooks/hook-llm.ts`)与降级腿 / 启动摘要(`brain.ts`)求有效端点时调
  *    {@link openaiRouteBaseUrl},不再各写一个 `model.baseUrl || gatewayBaseUrl`。
@@ -34,6 +37,7 @@
  * `brain.ts` / `hooks/hook-llm.ts` 都可以安全引它。
  */
 import type { Model } from "@sema-agent/core";
+import { type ModelTableLeg } from "./model-select.js";
 /** 机读码(拼法随 `config.*` 家族,按**规则**命名不按键名):一条 openai 路由解析不到端点。 */
 export declare const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
 /** 同族第二码:备用网关设了、主网关没设。与上一码分开是因为出路不同(补主网关 / 撤备用 vs 补主网关 / 给条目 baseUrl)。 */
@@ -43,7 +47,7 @@ export declare const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fal
  *
  * 与上面的**码**是两根轴:码是组拒的机读词(`ModelPlaneRefusalCode`,settings-schema 属主),这里是**出路**:
  *  · `endpoint_missing` —— 缺的是网关端点:openai 兼容腿上的条目解析不到 base URL(或备用网关设了、主网关没设);
- *    出路 = 设 `MODEL_GATEWAY_BASEURL`,或给条目自己的 `baseUrl`;
+ *    出路 = 设 `MODEL_GATEWAY_BASEURL`,或(目录视图)给条目自己的 `baseUrl` / (env 视图)挂 anthropic 路由、或不设 `MODEL_ID` 让目录缺省服务;
  *  · `lane_credential_missing` —— 缺的是**车道凭据**:条目的 provider 词是 `anthropic`(用户选的是 anthropic 车道),
  *    却因 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 都没有而没装上 anthropic 路由、落进了 openai 腿,那条腿又没有端点;
  *    出路 = 补那两把钥匙之一(设网关是另一条出路,拒因句一并给);
@@ -75,8 +79,11 @@ export type OpenaiRouteEndpoint = {
     readonly ok: false;
     readonly refusal: string;
 };
-/** 单条 openai 路由的有效端点 / 拒因(拒因与部署级判据是**同一只**铸点 {@link routeEndpointMissingRefusal})。 */
-export declare function resolveOpenaiRouteEndpoint(routeName: string, routeBaseUrl: string | undefined, gatewayBaseUrl: string | undefined): OpenaiRouteEndpoint;
+/**
+ * 单条 openai 路由的有效端点 / 拒因(拒因与部署级判据是**同一只**铸点 {@link routeEndpointMissingRefusal};`leg` = 这条路由所在的表的视图词)。
+ * `route` = 这条路由的条目(只读 `baseUrl` 与 `provider`);条目都没有(模型名解不出)⇒ 传 `undefined`,按「无自有 baseUrl、非 anthropic 词」判。
+ */
+export declare function resolveOpenaiRouteEndpoint(routeName: string, route: Pick<Model, "baseUrl" | "provider"> | undefined, gatewayBaseUrl: string | undefined, leg: ModelTableLeg): OpenaiRouteEndpoint;
 /** 部署级判据读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
 export interface ModelRouteEndpointView {
     readonly gatewayBaseUrl?: string;
@@ -96,7 +103,7 @@ export interface ModelRouteEndpointView {
  * `default` 键是目录里另一条的别名(env 腿 `{default: m, [m.id]: m}`、center 腿 `models.default = models[picked]`),
  * 与别的键指同一只对象时不重复点名;只有它一个键时(手搓夹具)照样点名 `default`。
  */
-export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView): string | undefined;
+export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView, leg: ModelTableLeg): string | undefined;
 /** S-768:部署级判决的结构化形 —— 码与拒因句由**同一次**判决给出(一个不变量 id 两个码,组拒码在判决那刻当数据带出,不从句子里抠)。 */
 export interface ModelRouteEndpointVerdict {
     readonly code: typeof GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE | typeof MODEL_ROUTE_ENDPOINT_MISSING_CODE;
@@ -107,6 +114,39 @@ export interface ModelRouteEndpointVerdict {
 /**
  * **判据属主**(S-768 起的结构化形;{@link modelRouteEndpointRefusal} 是它的句子投影):`undefined` = 通过。判序即 {@link modelRouteEndpointRefusal}
  * 头注所列 —— ① 备用无主先说,② 逐条目解析不到端点全部点名。加一枝 = 在这里同时给出码与句(返回型强制两者同在)。
+ * `leg` = `view.models` 是哪一张表({@link ModelTableLeg}):判据本身两视图同一把,**句子**按视图铸(出路在 env 表与目录表上不是同一组)。
+ */
+export declare function judgeModelRouteEndpoint(view: ModelRouteEndpointView, leg: ModelTableLeg): ModelRouteEndpointVerdict | undefined;
+/** {@link judgeServedModelRoute} 读的切面:路由判据的切面 + 「服务的是哪张表」的事实(`ServiceConfig` 结构满足)。 */
+export interface ServedModelRouteView extends ModelRouteEndpointView {
+    readonly model: object;
+    readonly envModel: object;
+}
+/** {@link judgeServedModelRoute} 的旁路入参。 */
+export interface ServedModelRouteOptions {
+    /**
+     * env 表是不是**占位**(只在服务的是 env 表时有意义)。严格名册布防(`isRosterGateArmed`:远程 registry ∧ 非 dryRun ∧ `CONFIG_REQUIRE_ROSTER=true`)=
+     * 运维声明 env `MODEL_ID` 是占位:名册落地前计费提交 503、落地后整表换装 ⇒ env 表从不被派发,不在「能派发到的」射程里(备用网关那一条与表无关,照判)。
+     * 布防是中心接入的事实,配置读不出 ⇒ 由调用方给。没有名册门的入口(run-local)传 `false`。
+     */
+    readonly envTableIsPlaceholder: boolean;
+}
+/**
+ * **起服段的路由判官:只判「将要服务的那张表」**。`undefined` = 通过。
+ *
+ * 服务的是哪张表由 {@link servedModelTableLeg} 读出来,判据与句子随它走(同一只属主判据 {@link judgeModelRouteEndpoint},零第二判官):
+ *  · 目录被采纳 ⇒ 判目录表(目录视图;模型面 stage 已对同一张表判过同一只判据,这里是装配终点上的复核);
+ *  · 目录缺席 / 被整拒 / 没有启用条目 ⇒ 判 env 表(env 视图);占位豁免见 {@link ServedModelRouteOptions.envTableIsPlaceholder}。
+ *
+ * 必须在**目录应用之后**调(装配第 2 段 / run-local 配置源解析完):在那之前没有「将要服务的表」可判 ——
+ * 对 env 表提前拒启,会把「条目写进目录、再设 `MODEL_ID`」的部署无谓拒掉(目录一旦采纳,引擎从不读 env `MODEL_ID`)。
+ */
+export declare function judgeServedModelRoute(config: ServedModelRouteView, opts: ServedModelRouteOptions): ModelRouteEndpointVerdict | undefined;
+/**
+ * **没有目录要应用的直接装配**(开发脚本 / 基准 / 嵌入方的纯 env 形:`loadConfig()` → `createBrain` → `Runner`)的拒启口:服务的表就是 `loadConfig()` 铸的 env 表,
+ * 判决 ⇒ 抛(`Error.message` = 判决的 `reason` 原样)。`loadConfig()` 不判路由 —— 没有这一步,缺端点的 env 行会一路跑到第一次模型调用才失败(基准里是十次失败调用、
+ * 全零统计、退出 0)。装配第 2 段与 `run-local` 要锚、要在目录应用之后判,调的是 {@link judgeServedModelRoute};本函数只是它的抛出形。
+ * 源码类钉(`test/served-model-route.test.ts` ⑨):`src/` 与 `scripts/` 里每个调 `loadConfig()` 的入口,要么在同文件里判过路由,要么是登记在册的例外。
  */
-export declare function judgeModelRouteEndpoint(view: ModelRouteEndpointView): ModelRouteEndpointVerdict | undefined;
+export declare function assertServedModelRoute(config: ServedModelRouteView, opts: ServedModelRouteOptions): void;
 //# sourceMappingURL=model-route-endpoint.d.ts.map

package/dist/model-route-endpoint.js

@@ -1,5 +1,5 @@
 import { dispatchBrainLane } from "./model-provider.js";
-import { DEFAULT_MODEL_REF } from "./model-select.js";
+import { DEFAULT_MODEL_REF, servedModelTableLeg } from "./model-select.js";
 export const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
 export const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
 export const MODEL_ROUTE_GAP_WORDS = ["endpoint_missing", "lane_credential_missing", "none"];
@@ -10,14 +10,19 @@ function declared(url) {
 export function openaiRouteBaseUrl(routeBaseUrl, gatewayBaseUrl) {
     return declared(routeBaseUrl) ?? declared(gatewayBaseUrl);
 }
-export function resolveOpenaiRouteEndpoint(routeName, routeBaseUrl, gatewayBaseUrl) {
-    const baseUrl = openaiRouteBaseUrl(routeBaseUrl, gatewayBaseUrl);
-    return baseUrl !== undefined ? { ok: true, baseUrl } : { ok: false, refusal: routeEndpointMissingRefusal([`"${routeName}"`]) };
+function unresolvedRouteLabel(name, provider) {
+    return provider === "anthropic"
+        ? `"${name}" (provider "anthropic", but no Anthropic route is mounted — ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN are unset — so it falls to the openai-compatible lane)`
+        : `"${name}"`;
 }
-export function modelRouteEndpointRefusal(view) {
-    return judgeModelRouteEndpoint(view)?.reason;
+export function resolveOpenaiRouteEndpoint(routeName, route, gatewayBaseUrl, leg) {
+    const baseUrl = openaiRouteBaseUrl(route?.baseUrl, gatewayBaseUrl);
+    return baseUrl !== undefined ? { ok: true, baseUrl } : { ok: false, refusal: routeEndpointMissingRefusal([unresolvedRouteLabel(routeName, route?.provider)], leg) };
 }
-export function judgeModelRouteEndpoint(view) {
+export function modelRouteEndpointRefusal(view, leg) {
+    return judgeModelRouteEndpoint(view, leg)?.reason;
+}
+export function judgeModelRouteEndpoint(view, leg) {
     const gateway = declared(view.gatewayBaseUrl);
     if (gateway === undefined && view.gatewayFallbackUrls.length > 0) {
         const reason = (`env MODEL_GATEWAY_FALLBACK_URLS is set but MODEL_GATEWAY_BASEURL is not [${GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE}] — ` +
@@ -38,28 +43,45 @@ export function judgeModelRouteEndpoint(view) {
             continue;
         if (openaiRouteBaseUrl(m.baseUrl, gateway) !== undefined)
             continue;
-        const anthropicWordWithoutRoute = m.provider === "anthropic";
-        laneCredentialMissing ||= anthropicWordWithoutRoute;
-        unresolved.push(anthropicWordWithoutRoute
-            ? `"${name}" (provider "anthropic", but no Anthropic route is mounted — ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN are unset — so it falls to the openai-compatible lane)`
-            : `"${name}"`);
+        laneCredentialMissing ||= m.provider === "anthropic";
+        unresolved.push(unresolvedRouteLabel(name, m.provider));
     }
     if (unresolved.length === 0)
         return undefined;
-    return { code: MODEL_ROUTE_ENDPOINT_MISSING_CODE, gap: laneCredentialMissing ? "lane_credential_missing" : "endpoint_missing", reason: routeEndpointMissingRefusal(unresolved) };
+    return { code: MODEL_ROUTE_ENDPOINT_MISSING_CODE, gap: laneCredentialMissing ? "lane_credential_missing" : "endpoint_missing", reason: routeEndpointMissingRefusal(unresolved, leg) };
 }
-function routeEndpointMissingRefusal(quotedNames) {
+function routeEndpointMissingRefusal(quotedNames, leg) {
     const one = quotedNames.length === 1;
     const subject = one ? `model ${quotedNames[0]} rides` : `models ${quotedNames.join(", ")} ride`;
-    return (`${subject} the openai-compatible lane but ${one ? "resolves" : "resolve"} to no endpoint ` +
-        `[${MODEL_ROUTE_ENDPOINT_MISSING_CODE}] — ${one ? "it has no" : "none has a"} baseUrl of its own, and MODEL_GATEWAY_BASEURL is unset. ` +
-        "MODEL_GATEWAY_BASEURL has no factory default: the former silent placeholder (this machine's port 8000) let such a " +
+    const head = `${subject} the openai-compatible lane but ${one ? "resolves" : "resolve"} to no endpoint [${MODEL_ROUTE_ENDPOINT_MISSING_CODE}] — `;
+    const noDefault = "MODEL_GATEWAY_BASEURL has no factory default: the former silent placeholder (this machine's port 8000) let such a " +
         "deployment start fine and then fail on the first model call, far from the cause (\"fetch failed … ECONNREFUSED\", or " +
-        "a container dialling its own loopback when compose passes an empty value). " +
-        `Set it explicitly — for a gateway on this machine: ${LOCAL_GATEWAY_HINT} — or give ${one ? "that model" : "each named model"} its own baseUrl in the catalog. ` +
-        "(A model defined by MODEL_ID / MODEL_CHEAP_ID has no baseUrl of its own: it needs the gateway, or MODEL_PROVIDER=anthropic " +
-        "with ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN. It is judged at boot even when a catalog will replace it later — it is what this " +
-        "process serves whenever no catalog lands: the config source unreachable, a refused candidate, or zero enabled models — unless " +
-        "CONFIG_REQUIRE_ROSTER=true on a remote registry declares it a placeholder that is never served.)");
+        "a container dialling its own loopback when compose passes an empty value). ";
+    switch (leg) {
+        case "catalog":
+            return (head +
+                `${one ? "it has no" : "none has a"} baseUrl of its own, and MODEL_GATEWAY_BASEURL is unset. ` +
+                noDefault +
+                `Set it explicitly — for a gateway on this machine: ${LOCAL_GATEWAY_HINT} — or give ${one ? "that model" : "each named model"} its own baseUrl in the catalog.`);
+        case "env":
+            return (head +
+                `${one ? "it is" : "they are"} defined by env (MODEL_ID / MODEL_CHEAP_ID), which gives ${one ? "it" : "them"} no baseUrl of its own, and MODEL_GATEWAY_BASEURL is unset. ` +
+                noDefault +
+                `This process serves the env model table because no catalog is in force (none configured, the config source unreachable, the candidate refused, or no enabled model in it). Pick one way out: ` +
+                `(1) set MODEL_GATEWAY_BASEURL explicitly — for a gateway on this machine: ${LOCAL_GATEWAY_HINT}; ` +
+                "(2) mount the Anthropic route — MODEL_PROVIDER=anthropic with ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN (plus ANTHROPIC_BASE_URL for a non-default endpoint); " +
+                "(3) leave MODEL_ID unset and let the default entry of a catalog (config.d/models.json, or the web-admin) serve — a catalog in force replaces the env model table. " +
+                "(With CONFIG_REQUIRE_ROSTER=true on a remote registry the env model is declared a placeholder that is never served, and is not judged here.)");
+    }
+}
+export function judgeServedModelRoute(config, opts) {
+    const leg = servedModelTableLeg(config);
+    const view = leg === "env" && opts.envTableIsPlaceholder ? { ...config, models: {} } : config;
+    return judgeModelRouteEndpoint(view, leg);
+}
+export function assertServedModelRoute(config, opts) {
+    const verdict = judgeServedModelRoute(config, opts);
+    if (verdict !== undefined)
+        throw new Error(verdict.reason);
 }
 //# sourceMappingURL=model-route-endpoint.js.map

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

@@ -81,8 +81,8 @@ export interface ModelRouteGapOptions {
 /**
  * 判官的读数(闭集三词,穷举 switch 消费):
  *  · `none` —— 无缺口,仅此一键;
- *  · 缺口两词 —— `code` = 起服拒启的机读码(与 `reason` 里的方括号码同一个词;`lane_credential_missing` 也带 `config.model_route_endpoint_missing`),
- *    `reason` = 起服拒启句原文(点名条目与出路)。
+ *  · 缺口两词 —— `code` = 机读码(与 `reason` 里的方括号码同一个词;`lane_credential_missing` 也带 `config.model_route_endpoint_missing`),
+ *    `reason` = 起服判官对 env 表拒启时的句子原文(env 视图:点名条目与三条 env 出路)。
  */
 export type ModelRouteGapReading = {
     readonly gap: "none";
@@ -94,9 +94,10 @@ export type ModelRouteGapReading = {
     };
 }[ModelRouteGapBreach];
 /**
- * **起服前可调的模型路由缺口纯判官**(与起服判官同一实现;包根导出)。
+ * **起服前可调的模型路由缺口纯判官**(与起服判官判 env 表时同一实现、同一句拒因;包根导出)。答的是 **env 腿**:没有目录在管时,这份 env 起不起得来
+ * (目录在场时起服以目录为准,见文件头注)。
  *
- * @param env 一份 env 快照(只读 {@link MODEL_ROUTE_ENV_KEYS} 那八把键;`process.env` 也行 —— 起服段就是这样调的)。
+ * @param env 一份 env 快照(只读 {@link MODEL_ROUTE_ENV_KEYS} 那八把键;`process.env` 也行)。
  * @returns 三词之一;有缺口时带 `code` 与 `reason`(见 {@link ModelRouteGapReading})。
  */
 export declare function judgeModelRouteGap(env: ModelRouteEnv, opts?: ModelRouteGapOptions): ModelRouteGapReading;

package/dist/model-route-gap.js

@@ -72,7 +72,7 @@ export function judgeModelRouteGap(env, opts = {}) {
         gatewayFallbackUrls: r.gatewayFallbackUrls,
         anthropic: r.anthropicRouteMounted ? {} : undefined,
         models,
-    });
+    }, "env");
     if (verdict === undefined)
         return { gap: "none" };
     return { gap: verdict.gap, code: verdict.code, reason: verdict.reason };

package/dist/model-select.d.ts

@@ -34,6 +34,41 @@ export declare function readAtMention(raw: unknown): AtMention | undefined;
  *  `resolveModel("default", catalog)` 解它)。**单点**:读面要说「这台部署的主模型是谁」时读同一个词
  *  (`auto-mode-face.ts` 的席解析器入参),两处各写一个 `"default"` 字面串正是漂移的成因。 */
 export declare const DEFAULT_MODEL_REF = "default";
+/**
+ * **进程服务的是哪一张模型表**(闭集两词,消费方用穷举 switch —— 加一词不补臂 ⇒ 编译红)。路由端点判官与缺省模型判官的「视图词」:
+ * 拒因句的出路按视图说真话,不靠调用方拼句。
+ *  · `env` —— env 表(`MODEL_ID` / `MODEL_CHEAP_ID` 铸的 `{default, [id]}`):**没有目录在管** —— 没配目录、配置源不可达且无 LKG、
+ *    候选被整拒、或候选没有一条启用条目。env 行永远没有自己的 `baseUrl`;
+ *  · `catalog` —— 目录表:一份目录的模型面落地之后**整张换掉** env 表(`config.model = config.models.default`),引擎从不读 env `MODEL_ID`。
+ */
+export declare const MODEL_TABLE_LEGS: readonly ["env", "catalog"];
+export type ModelTableLeg = (typeof MODEL_TABLE_LEGS)[number];
+/**
+ * 这个进程**此刻**服务的是哪一张表。读法只有一个事实:`config.model` 与 `config.envModel` 是不是同一个对象 ——
+ * `envModel` 在 `loadConfig` 铸一次、此后永不换,并与 `model` 在 boot 那一刻是同一只引用;`model` 的唯一写口是目录的模型面落地
+ * (`web-admin-client/apply-effective.ts` 的 commit 段,`config.model = config.models.default`)。所以「`model` 还是那只 env 模型」⇔
+ * 没有任何一份目录落过模型面 ⇔ 服务的是 env 表。不另记一个会与它漂开的「目录采纳了吗」旗子。
+ */
+export declare function servedModelTableLeg(config: {
+    readonly model: object;
+    readonly envModel: object;
+}): ModelTableLeg;
+/**
+ * 目录服务、而 env 里还设着 `MODEL_ID` ⇒ 启动时说一行(沿 `config_env_set_but_ineffective` 通告族:值合法、却不参与服务)。
+ * 这不是拒:目录一旦被采纳就整张换掉 env 表,`MODEL_ID` 在这一形下本来就不是缺省来源(缺省来自目录)—— 运维该知道自己的那一行
+ * 没在服务,否则会以为改它有效。env 表服务(或没设 `MODEL_ID`)⇒ `undefined`。
+ *
+ * 不读 `process.env`:env 的读数在 `loadConfig` 铸 `envModel` 时已定(`envModel.id` 就是 `MODEL_ID`,空串 = 没设)。
+ * 返回 plain data(事件名 + 字段)。**唯一发声点** = `web-admin-client/apply-effective.ts` 的 `applyEffective` commit 之后、服务表由 env 换成目录的那一拍(进程一生至多一次):
+ * 启动(含 LKG / 按组回落)、`run-local`、迟到 boot、refresh 都经那一个函数,「恰好一次」是构造出来的,没有去重表。
+ */
+export declare function buildEnvModelIdNotServedNotice(config: {
+    readonly model: Pick<Model, "id" | "name">;
+    readonly envModel: Pick<Model, "id">;
+}): {
+    readonly event: string;
+    readonly fields: Record<string, unknown>;
+} | undefined;
 /**
  * 本仓给一条**没选模型**的 task 铸的主模型 —— {@link DEFAULT_MODEL_REF} 在**展开**目录上(与引擎构造期 `expandTiers(models, tiers)`
  * 之后再解逐字同源)解到的那只**目录条目**(对象引用)。`boot/resolve-spec.ts` 每条 spec 都盖 `spec.model`,所以引擎眼里的 main
@@ -153,6 +188,29 @@ export type ModelImageInput = (typeof MODEL_IMAGE_INPUTS)[number];
 export declare function modelImageInput(model: {
     input?: unknown;
 } | undefined): ModelImageInput;
+/**
+ * 「这个目录条目的 `reasoning` 位声明了什么」的**唯一读法**:`true` / `false` 原样,**缺席 = 未声明 = `undefined`**(不替没声明的模型答「是」也不答「否」)。
+ * `GET /v1/models` 的 `reasoning` 列与 `GET /v1/config/catalog` 的 `MODEL_REASONING` 行都投影它。非布尔(手写错形)与条目不在,同归未声明:没有可信的声明。
+ */
+export declare function modelReasoningDecl(model: {
+    reasoning?: unknown;
+} | undefined): boolean | undefined;
+/** 两个能力位的**声明**(三态:`true` / `false` / 缺席 = 未声明)—— 铸 `Model` 上对应键的输入,见 {@link mintCapabilityKeys}。 */
+export interface ModelCapabilityDecl {
+    readonly reasoning?: boolean;
+    readonly vision?: boolean;
+}
+/**
+ * 能力位声明 ⇒ `Model` 上的两个键,**缺席不铸键**:`reasoning` 原样;`vision` 翻成 `input`(`true` ⇒ `["text","image"]`,`false` ⇒ `["text"]`)。
+ * env 腿(`MODEL_REASONING` / `MODEL_VISION`)、cheap 槽(`MODEL_CHEAP_*`)与中心腿(`models[].reasoning` / `vision`)都经它铸 —— 三条腿一个铸法、一个「缺席」的意思。
+ * 读回的唯一读法是 {@link modelReasoningDecl} 与 {@link modelImageInput}(带图预检与 `GET /v1/models` 同读后者)。
+ *
+ * 🔴 **本仓唯一的类型接缝**:引擎 7.51.2 的 `Model` 型面把 `reasoning` / `input` 写成必填,而它自己的读法对缺席有定义 ——
+ * `input` 缺席 ⇒ 支持图(`modelSupportsVision`:`model?.input === undefined ? true : …`),`reasoning` 缺席 ⇒ 真值判假(`!!model.reasoning`)。所以交给引擎的目录里缺席的键是安全的,
+ * 只是型面还没跟上;返回型因此对 `Pick<Model, …>` 说了一句「可能为空」的谎,把断言收在这一处 —— 调用点的 `Model` 字面量照旧带 `Model` 注解(其余每个键仍被 tsc 逐个核,
+ * 读表门按注解收字面量的 core 键)。型面归引擎:引擎把这两位放成可选之日,本接缝(返回型 + 这一处断言)整件删除。
+ */
+export declare function mintCapabilityKeys(decl: ModelCapabilityDecl): Pick<Model, "reasoning" | "input">;
 /**
  * 带图预检:只有目录条目**明说**不收图({@link modelImageInput} 为 `"no"`)才为假 —— 提交时据此计数并告警(引擎会把这些图换成给模型的
  * 占位句);没声明的条目为真(不出信号,图原样交给模型)。

package/dist/model-select.js

@@ -7,6 +7,25 @@ export function readAtMention(raw) {
     return r.success ? r.data : undefined;
 }
 export const DEFAULT_MODEL_REF = "default";
+export const MODEL_TABLE_LEGS = ["env", "catalog"];
+export function servedModelTableLeg(config) {
+    return config.model === config.envModel ? "env" : "catalog";
+}
+export function buildEnvModelIdNotServedNotice(config) {
+    if (servedModelTableLeg(config) !== "catalog" || config.envModel.id === "")
+        return undefined;
+    const served = config.model.name || config.model.id;
+    return {
+        event: "config_env_set_but_ineffective",
+        fields: {
+            env: "MODEL_ID",
+            raw: config.envModel.id,
+            problem: `a catalog is in force and replaces the env model table — the catalog default "${served}" serves this process, and MODEL_ID (with MODEL_CHEAP_ID) takes no part in it; remove the env line or point the catalog's default at the model you mean`,
+            servedBy: "catalog",
+            catalogDefault: served,
+        },
+    };
+}
 export function resolveMainModel(plane) {
     const expanded = expandTiers(plane.models, plane.tiers ?? {}) ?? plane.models;
     return coreResolveTaskModel({ model: DEFAULT_MODEL_REF }, { ...(expanded !== undefined ? { models: expanded } : {}) }).model;
@@ -101,6 +120,18 @@ export function modelImageInput(model) {
         return "undeclared";
     return model.input.includes("image") ? "yes" : "no";
 }
+export function modelReasoningDecl(model) {
+    return typeof model?.reasoning === "boolean" ? model.reasoning : undefined;
+}
+const CAPABILITY_MODEL_KEYS = { reasoning: "reasoning", input: "input" };
+export function mintCapabilityKeys(decl) {
+    const keys = {};
+    if (decl.reasoning !== undefined)
+        keys[CAPABILITY_MODEL_KEYS.reasoning] = decl.reasoning;
+    if (decl.vision !== undefined)
+        keys[CAPABILITY_MODEL_KEYS.input] = decl.vision ? ["text", "image"] : ["text"];
+    return keys;
+}
 export function modelSupportsImages(model) {
     return modelImageInput(model) !== "no";
 }

package/dist/namespaced-rule-name.d.ts

@@ -9,7 +9,7 @@
  * **调它的面**(点名,不是「每个面」):运维三张名表(`APPROVAL_REQUIRE` / `DENY` / `NEVER_AUTO`)与中心下发的同名表、请求
  * `settings.permissions.{ask,deny}`(经 `config.ts` 的 `unmatchableToolNamesRefusal`)。会话规则写口直接调 core 的 `assertSessionRuleNamesCurrent`
  * (同一只判官的店形);引擎 allow 层的条目表(请求 `settings.permissions.allow`、运维 `APPROVAL_GRANT`、技能两只清单)交引擎 `compileAllowList`
- * (名册 = {@link NO_DECLARED_TOOL_NAMES};判官判非现役的条目读成 `tool_name`)。
+ * (名册 = {@link TOOL_NAME_ROSTER};判官判非现役的条目读成 `tool_name`,名册里有的只差大小写读成 `near_miss`)。
  * **不调它的面**:`/v1/rules` 的持久规则写口与 `cc-import` 导入口(`http/routes/rules.ts`、`rules-consent.ts` 与两只持久规则店零判官调用)—— 如实未接,
  * 在那里写铸不出的服务器段仍被收下、永不命中;把它接上判官 = 另一件事(`unmatchableRuleNameOf` 就是现成的那一只)。
  * 子代的工具名表 `agents[].allowTools` / `denyTools` 不是本文件的面:core 7.45.0 #1377 / #1385 起名字归引擎在开跑前一只判(三来源同判,`spec-fields.ts`
@@ -28,10 +28,13 @@ import { type RuleToolNameVerdict } from "@sema-agent/core";
  */
 export declare function ruleEntryToolName(entry: string): string;
 /**
- * 判官的名册:本仓的配置表 / 请求表 / 会话规则写口都不声明「部署在退役名下挂了自有工具」(本仓没有这样的工具;boot / 请求期也没有哪一跑的名册可看)
- * ⇒ 恒为空集。引擎判官、`compileAllowList` 的第三参、会话规则店同读这一只。
+ * **名册 —— 本仓唯一的一张**:引擎目录的全部工具名(`catalogToolNames()`:引擎自己出的每一只工具的线上名,别名在内)∪ 本仓自己铸给模型的工具名({@link HOST_TOOL_NAMES}:取自铸它们的那一处的常量,不手抄)。
+ * 引擎判官 `judgeRuleToolName` 与 `compileAllowList` 的第三参读它:名册里有的名字是「现役」,条目只差大小写的读成 `near_miss`(`BASH` ⇒ 现名 `Bash`、`SENDUSERFILE` ⇒ `SendUserFile`),
+ * 退役名 / 无前缀短名 / 对端段铸不出的名字照旧读成 `tool_name`。引擎在开跑时读的是这一 run 真挂着的名册 —— 受理口读不到它,读得到的就是上面这两份:任何部署都带的引擎工具,加本仓自己挂的工具。
+ * 每一处读条目名的地方(请求体的规则表与工具名清单、技能清单、运维 / 中心的审批名单、会话规则写口)传这一张;**读成空 = 放行 / 静默收窄**的那些表因此不再有「空名册读不出孪生」的一读。
+ * 界:调用方自带的宿主工具(嵌入方 `createHttpServer` 之外自挂的)不在其中 —— 它们的孪生仍只由引擎在开跑时告知运维。
  */
-export declare const NO_DECLARED_TOOL_NAMES: ReadonlySet<string>;
+export declare const TOOL_NAME_ROSTER: ReadonlySet<string>;
 /** 一个规则名永远匹配不到工具的判词(闭集)= 引擎判官的非现行判词。 */
 export type UnmatchableRuleName = Exclude<RuleToolNameVerdict, {
     kind: "current";

package/dist/namespaced-rule-name.js

@@ -1,11 +1,12 @@
-import { PROTOCOL_TABLE, judgeRuleToolName, parsePermissionRule } from "@sema-agent/core";
+import { PROTOCOL_TABLE, catalogToolNames, judgeRuleToolName, parsePermissionRule } from "@sema-agent/core";
+import { HOST_TOOL_NAMES } from "./capabilities/host-tool-names.js";
 import { displayListEntry } from "./list-entry-display.js";
 export function ruleEntryToolName(entry) {
     return parsePermissionRule(entry).toolName;
 }
-export const NO_DECLARED_TOOL_NAMES = new Set();
+export const TOOL_NAME_ROSTER = new Set([...catalogToolNames(), ...HOST_TOOL_NAMES]);
 export function unmatchableRuleNameOf(name) {
-    const verdict = judgeRuleToolName(name, NO_DECLARED_TOOL_NAMES);
+    const verdict = judgeRuleToolName(name, TOOL_NAME_ROSTER);
     return verdict.kind === "current" ? undefined : verdict;
 }
 export function describeUnmatchableRuleName(v, name) {

package/dist/observability/fail-open.d.ts

@@ -93,7 +93,7 @@ export declare const FAIL_OPEN_TAGS: {
     };
     readonly "server.hitl.frame-undelivered-stream-closed": {
         readonly cls: "P-DEBT";
-        readonly note: "HITL 的 **open** 帧写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,该 ask 挂到 TTL 才按无人应答结算。⚠️ #173 后 question 开帧改走断流 THROW(立即结算 unavailable),因此本 tag 在产的只剩 **elicitation** 一族——读计数时勿把它当作 question 的人在环缺口。no-op 而非 throw 对 elicitation 仍是既有的刻意决定,本条只保证它不再无声。";
+        readonly note: "HITL 的 **open** 帧写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,该 ask 挂到 TTL 才按无人应答结算。⚠️ #173 后 question 开帧改走断流 THROW(立即结算 unavailable),因此本 tag 在产的只剩 **elicitation** 一族,且只在**无账本孪生**(无 durable run 行)的部署上——有孪生的腿直写面已死时帧在账本里、不算丢——读计数时勿把它当作 question 的人在环缺口。no-op 而非 throw 对 elicitation 仍是既有的刻意决定,本条只保证它不再无声。";
     };
     readonly "server.stream.frame-dropped-stream-closed": {
         readonly cls: "F";
@@ -243,6 +243,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-995(`hooks/hook-runner.ts` 的 `toolMatcherIssue`,fresh 受理面「工具事件 matcher 选中别名而选不中正名 ⇒ 400」判据的**未判**臂;detail = `event=… reason=… matcherChars=…`,不带 matcher 原字节):一只 matcher 没能被判 ⇒ 照旧受理。判据一条顺序、两档共用(7.114.0 修复轮):长度上限 → 形只问契约包的 `hookMatcherForm`(literal 形〔名字表 / 空 / `*`〕两档都直接问 `hookMatcherSelects`、不占预算;regex 形 regex 档把同一只契约函数交进 vm 带每次求值各一份的固定预算〔超时 = 灾难回溯 ⇒ 确定的 400 拒,不是未判、不登记〕、literal 档不适用;invalid 形 regex 档 = 确定的 400 拒〔S-1455 收尾:不是未判、不登记;运行期另记 `hook_matcher_invalid`〕、literal 档不适用)。现在只有一种 reason —— `oversize`(两档:超 8 192 字符不读;多租户车道上 hooks 不装配,这一笔只为让超长输入显形)。`invalid_regex` 臂自 S-1455 收尾(7.126.0)起退役:它是确定性的坏配置、不是「判不了」,与超预算同类 ⇒ 受理当场 400。**不记**的:literal 档(多租户车道)遇正则形 = 不适用 —— 该车道 hooks 整只不装配,没有被守的对象,不是未判。放行的最坏后果 = **那一只 matcher 没被这条判据守住**:它若真写了别名,照旧永不命中(7.112.0 对正则形一律不判,同一后果);**不是安全闸**(受理面的有效性判 = S-924 的「响亮」,决定不了任何放行 / 拒绝 / 权限;hook 的 deny 语义在运行期 hook-runner)。拒放集合相对 7.113.0 的一处放宽:超过上限的字面别名 matcher 7.113.0 拒、7.114.0 两档未判受理(已披露)。计数让「受理面一直判不了」(超长 matcher)显形。";
     };
+    readonly "server.hooks.resume-reader-refused": {
+        readonly cls: "P-DEBT";
+        readonly note: "续跑重放(`task-settings.ts` 的 `parseTaskSettings`,经 `boot/resolve-spec.ts` 装配)读存下的请求体里的 `settings.hooks`,而 hooks 配置的唯一读者(契约包分类器,`hooks/hook-runner.ts` 的 `parseHooksConfig`)判不过、也没被一次性迁移 M20 接住(窗已关,或拒因不属 M20 的两形 —— 藏着守卫迹象的未知字段 / JSON `__proto__` 事件键)⇒ 这份 hooks **整只不采纳**(`task_settings_deferred` 记账),任务照常续跑 —— 其中若有真在拦的 `PreToolUse` 钩子,续跑后不再拦。M20 窗开着时那两形不进这一臂(剥键重读、守卫照跑,一行 `hooks_read_as_before_upgrade`)。只在 hooks 会被采纳的单用户车道计数(多租户整只忽略 hooks,无物可丢);fresh 提交不进这一臂(受理面 400)。放行的最坏后果:升级前停驻、体里 hooks 带那两形之一的任务,在窗关之后才续跑的(发布后才升级的部署、调长了 `APPROVAL_TERMINAL_BACKSTOP_MS` 的部署、滚动升级里旧副本在窗内新写的行),或体里 hooks 带别的坏形的,失去这份 hooks 里原本真在拦的钩子。方向已裁:持久数据面走 M20 窗内迁移,窗关后整份不采纳 + 本计数(存量停驻行此时已被收割,计数应趋零)。detail = `leg=`。计数非零 = 有任务带着被读者拒掉的存量 hooks 在续跑。";
+    };
     readonly "server.hooks.notice-sink-threw": {
         readonly cls: "F";
         readonly note: "#281:hook 观测回调(`onHookNotice`,部署把它接到 fleet 流)自己抛了。放行的最坏后果 = **这一条观测帧**缺席;补偿是结构性的:①日志终点在投递之前就已逐字落定(`hook_command_failed` / `hook_command_timeout` / `hook_command_spawn_failed` 一族),运维面零回退;②观测帧不参与任何门/裁决(纯 observe,#281 全族判据里「裁决面一个字节不动」是承重条款),故 F 类。不放行的代价严重不对称:异常会掀回 core 的 hook 回调栈,把一次**观察动作**变成一次**工具调用失败** —— 「观察一件事的动作反过来改变了那件事」正是本 tag 要根除的形,而它伤的恰恰是 hook 已经坏掉、用户最需要任务照跑的那一刻。留痕承重:静默吞掉之后「这台机器为什么一条 hook 通知都没有」在遥测里与「hook 从来没坏过」同形。";
@@ -474,11 +478,12 @@ export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;
  * 只有 open 帧是"人在环这道门被跳过"的证据,其余都是体验损失。
  *
  * ⚠️ **两条 question 臂在生产上已不可达**([ref] 之后,2026-08-07):本函数唯一的生产调用点是
- * `routes/tasks.ts` 的 `emitAsk` 断流臂,而 question 与 question_complete 两型帧都先过同文件
- * `emitQuestion` 的断流守卫(两道守卫同步相邻、其间无 await)并在断流时 throw,永不抵达这里;另一条
- * question 路(`runs.ts` 的 durable append)根本不经 emitAsk。在产的只剩 elicitation 族与 default。
- * 两臂**保留不删**:它们是本映射的语义定义(单测直打的纯函数),elicit 侧若哪天照 question 收紧、或
- * 新增第四条 emit 腿忘了守卫,留着的臂是正确落点而不是死码。读遥测时按上面这段判在产分布。
+ * `routes/tasks.ts` 的 `emitAsk` 断流臂,而 question 与 question_complete 两型帧的直写口
+ * (同文件 `writeQuestionLive`)先过断流守卫(两道守卫同步相邻、其间无 await)并在断流时 throw,永不抵达这里;
+ * 另一条 question 路(`runs.ts` 的 durable append)根本不经 emitAsk。elicitation 族自账本孪生起也只在**无 durable
+ * run 行**的部署上抵达这里(有孪生的腿直写面已死时孪生即送达,不碰死连接)。在产的只剩那一形与 default。
+ * 两臂**保留不删**:它们是本映射的语义定义(单测直打的纯函数),新增第四条 emit 腿忘了守卫时,
+ * 留着的臂是正确落点而不是死码。读遥测时按上面这段判在产分布。
  */
 export declare function failOpenTagForDroppedFrame(frameType: string): FailOpenTag;
 /** {@link createFailOpenRecorder} 返回的活对象(有行为、有状态 ⇒ `create*` 而非 `build*`)。 */

package/dist/observability/fail-open.js

@@ -74,7 +74,7 @@ export const FAIL_OPEN_TAGS = {
     },
     "server.hitl.frame-undelivered-stream-closed": {
         cls: "P-DEBT",
-        note: "HITL 的 **open** 帧写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,该 ask 挂到 TTL 才按无人应答结算。⚠️ #173 后 question 开帧改走断流 THROW(立即结算 unavailable),因此本 tag 在产的只剩 **elicitation** 一族——读计数时勿把它当作 question 的人在环缺口。no-op 而非 throw 对 elicitation 仍是既有的刻意决定,本条只保证它不再无声。",
+        note: "HITL 的 **open** 帧写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,该 ask 挂到 TTL 才按无人应答结算。⚠️ #173 后 question 开帧改走断流 THROW(立即结算 unavailable),因此本 tag 在产的只剩 **elicitation** 一族,且只在**无账本孪生**(无 durable run 行)的部署上——有孪生的腿直写面已死时帧在账本里、不算丢——读计数时勿把它当作 question 的人在环缺口。no-op 而非 throw 对 elicitation 仍是既有的刻意决定,本条只保证它不再无声。",
     },
     "server.stream.frame-dropped-stream-closed": {
         cls: "F",
@@ -224,6 +224,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-995(`hooks/hook-runner.ts` 的 `toolMatcherIssue`,fresh 受理面「工具事件 matcher 选中别名而选不中正名 ⇒ 400」判据的**未判**臂;detail = `event=… reason=… matcherChars=…`,不带 matcher 原字节):一只 matcher 没能被判 ⇒ 照旧受理。判据一条顺序、两档共用(7.114.0 修复轮):长度上限 → 形只问契约包的 `hookMatcherForm`(literal 形〔名字表 / 空 / `*`〕两档都直接问 `hookMatcherSelects`、不占预算;regex 形 regex 档把同一只契约函数交进 vm 带每次求值各一份的固定预算〔超时 = 灾难回溯 ⇒ 确定的 400 拒,不是未判、不登记〕、literal 档不适用;invalid 形 regex 档 = 确定的 400 拒〔S-1455 收尾:不是未判、不登记;运行期另记 `hook_matcher_invalid`〕、literal 档不适用)。现在只有一种 reason —— `oversize`(两档:超 8 192 字符不读;多租户车道上 hooks 不装配,这一笔只为让超长输入显形)。`invalid_regex` 臂自 S-1455 收尾(7.126.0)起退役:它是确定性的坏配置、不是「判不了」,与超预算同类 ⇒ 受理当场 400。**不记**的:literal 档(多租户车道)遇正则形 = 不适用 —— 该车道 hooks 整只不装配,没有被守的对象,不是未判。放行的最坏后果 = **那一只 matcher 没被这条判据守住**:它若真写了别名,照旧永不命中(7.112.0 对正则形一律不判,同一后果);**不是安全闸**(受理面的有效性判 = S-924 的「响亮」,决定不了任何放行 / 拒绝 / 权限;hook 的 deny 语义在运行期 hook-runner)。拒放集合相对 7.113.0 的一处放宽:超过上限的字面别名 matcher 7.113.0 拒、7.114.0 两档未判受理(已披露)。计数让「受理面一直判不了」(超长 matcher)显形。",
     },
+    "server.hooks.resume-reader-refused": {
+        cls: "P-DEBT",
+        note: "续跑重放(`task-settings.ts` 的 `parseTaskSettings`,经 `boot/resolve-spec.ts` 装配)读存下的请求体里的 `settings.hooks`,而 hooks 配置的唯一读者(契约包分类器,`hooks/hook-runner.ts` 的 `parseHooksConfig`)判不过、也没被一次性迁移 M20 接住(窗已关,或拒因不属 M20 的两形 —— 藏着守卫迹象的未知字段 / JSON `__proto__` 事件键)⇒ 这份 hooks **整只不采纳**(`task_settings_deferred` 记账),任务照常续跑 —— 其中若有真在拦的 `PreToolUse` 钩子,续跑后不再拦。M20 窗开着时那两形不进这一臂(剥键重读、守卫照跑,一行 `hooks_read_as_before_upgrade`)。只在 hooks 会被采纳的单用户车道计数(多租户整只忽略 hooks,无物可丢);fresh 提交不进这一臂(受理面 400)。放行的最坏后果:升级前停驻、体里 hooks 带那两形之一的任务,在窗关之后才续跑的(发布后才升级的部署、调长了 `APPROVAL_TERMINAL_BACKSTOP_MS` 的部署、滚动升级里旧副本在窗内新写的行),或体里 hooks 带别的坏形的,失去这份 hooks 里原本真在拦的钩子。方向已裁:持久数据面走 M20 窗内迁移,窗关后整份不采纳 + 本计数(存量停驻行此时已被收割,计数应趋零)。detail = `leg=`。计数非零 = 有任务带着被读者拒掉的存量 hooks 在续跑。",
+    },
     "server.hooks.notice-sink-threw": {
         cls: "F",
         note: "#281:hook 观测回调(`onHookNotice`,部署把它接到 fleet 流)自己抛了。放行的最坏后果 = **这一条观测帧**缺席;补偿是结构性的:①日志终点在投递之前就已逐字落定(`hook_command_failed` / `hook_command_timeout` / `hook_command_spawn_failed` 一族),运维面零回退;②观测帧不参与任何门/裁决(纯 observe,#281 全族判据里「裁决面一个字节不动」是承重条款),故 F 类。不放行的代价严重不对称:异常会掀回 core 的 hook 回调栈,把一次**观察动作**变成一次**工具调用失败** —— 「观察一件事的动作反过来改变了那件事」正是本 tag 要根除的形,而它伤的恰恰是 hook 已经坏掉、用户最需要任务照跑的那一刻。留痕承重:静默吞掉之后「这台机器为什么一条 hook 通知都没有」在遥测里与「hook 从来没坏过」同形。",

package/dist/plugins/local-session-store.js

@@ -12,7 +12,7 @@ import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { noteReplayInSessionOpenScope, openSessionForItself } from "../session-records-skipped-notice.js";
 import { createCorruptReadFailOpenSeat } from "../observability/corrupt-read-seat.js";
-import { buildObjectivePreview } from "../user-authored-text.js";
+import { buildObjectivePreview, isAttachmentFrame } from "../user-authored-text.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
@@ -21,7 +21,7 @@ function userText(entry) {
     if (entry.type !== "message")
         return null;
     const msg = entry.message;
-    if (msg.role !== "user")
+    if (msg.role !== "user" || isAttachmentFrame(msg))
         return null;
     const c = msg.content;
     if (typeof c === "string")

package/dist/plugins/one-time-migrations.d.ts

@@ -181,6 +181,15 @@
  *    停驻的行)、把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署、滚动升级里仍跑 7.129.x 的副本在窗内新写的行。与 M7 / M18 一样如实登记,不为它们加长窗。
  *    **它是上游字段标准的限时例外**:引擎对 `toolAxes` 的标准是「坏键不丢、坏词不默认」(core `mcp-server-spec.d.ts`),窗内这一臂恰恰剔坏留好 ——
  *    依据是持久数据律(存量数据不能「变红」,只许一次性迁移、窗关删码),只对升级前已经按这种读法跑过的存量体,且对运维响亮。新提交与部署腿不受它影响。
+ *  · **M20 续跑重放腿上的存量 `settings.hooks`**(7.131.0)—— hooks 配置的唯一读者是契约包的 `classifyHooksConfig`(经 `parseHooksConfig`);升级前的读者(12.x zod 面)对两形照收:
+ *    条目 / 匹配器上**契约不认识的字段里藏着守卫迹象**(未知字段被剥掉,同份里真在拦的 `PreToolUse` 钩子照拦)与 JSON 写出的 **`__proto__` 事件键**(被跳过)。现读者对这两形整份拒,
+ *    续跑重放腿重放的是升级前存下的体 ⇒ 停驻任务续跑后整份 hooks 不采纳、守卫不再拦。与 M19 同形:不改写存下的字节,是一只**窗内才生效的行为臂** —— 窗开着时(运行期读本表 M20 行的
+ *    `removableAfter`,见 {@link migrationWindowOpen}),**只在续跑重放腿**、**只在会采纳 hooks 的单用户车道**、**只对读者拒因全部属这两形**的存体:把读者点名的那一块(条目 / 匹配器)里按类型确属未知的键
+ *    一次全剥(12.x 读者对一个条目本来就是剥掉全部未知字段、保留其余),剩下的文档**重新过同一只读者**,过了就采纳;整次重读恰一行运维 warn `hooks_read_as_before_upgrade`(点名 sessionId 与被剥的坐标)。
+ *    **不复制旧读者**:`stored-request-hooks-m20.ts` 不判值形、不判整份是否合法(那是读者的答案),只做「读者点名了哪些块、这一块里哪些键按它的类型确属未知、整块剥掉再问一次,剥到读者受理为止」;
+ *    「确属未知」按该条目自己的 `type` 取契约字段名表(不用各型字段的并集,表由契约类型面穷举)。拒因里混进别的(真坏的守卫条目、点名了本型契约字段的拒因 …)⇒ 不迁移,整份照拒。
+ *    窗关之后 ⇒ 续跑整份不采纳,fail-open 登记 `server.hooks.resume-reader-refused` 照打(可见);fresh 腿不受影响(受理面照 400)。没有起服读数(它不写库)。
+ *    窗 = 发布日 + 30 天 = 停驻行的终局兜底窗缺省 —— 与 M19 同一条论证与同三类逃出窗的部署(发布后才升级的、调长了 `APPROVAL_TERMINAL_BACKSTOP_MS` 的、滚动升级里旧副本在窗内新写的行),如实登记。
  *
  * ## 幂等
  * 改写的几条都可重复跑(M4:`detail IS NOT NULL AND … = 'null'`;M5:列在场探针 + `WHERE incarnation = ''`;M6:`WHERE error_code IS NULL`;
@@ -306,7 +315,7 @@ export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
 /**
  * 一条登记行的窗**此刻**开着没有(`today` = UTC 日历日 YYYY-MM-DD):未发布形(`removableAfter: null`)⇒ 开;否则今天不晚于 `removableAfter` ⇒ 开
  * (窗关当天仍开,与到期门「今天严格晚于才红」同一条边界)。
- * 只给**窗内才生效的行为臂**用(M10 的认领、M19 的续跑重读):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
+ * 只给**窗内才生效的行为臂**用(M10 的认领、M19 / M20 的续跑重读):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
  */
 export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow, "removableAfter">, today: string): boolean;
 /** local 车道上 SQL 独有的几条(M4 / M5 / M8 / M9 / M11 / M17 / M18)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */

package/dist/plugins/one-time-migrations.js

@@ -149,7 +149,7 @@ export const ONE_TIME_MIGRATIONS = [
         removal: "删模式词读法记号的判据与拒臂:`http/stored-body-replay.ts` 的 `permissionModeReadingUnstated`;`http/checkpoint-ctx.ts` 的 `permissionModeReadingStated` / `permissionModeReadingRefusal` / `PERMISSION_MODE_READINGS`、" +
             "`StoredBodyReplayRefusal` 的 `permission_mode_reading` 臂及其日志字段与答复臂、`buildCheckpointCtx` 与 `withPermissionModeRewritten` 两处记号写点" +
             "(后者删后 `resume-legs.ts` `drivePlanReview` 里对它的那一处调用回到只换体的 `{ ...ctx, body }`)、`CheckpointCtx.permissionModeReading`、" +
-            "`http/stored-body-replay.ts` `storedBodyReplayRefusal` 的 `autonomy` 形参(只服务这一问)与四个问点(`resume-legs.ts` 两处、`approval-sweeps.ts`、`routes/runs.ts`)传 `deps.config.autonomy` 的那一句",
+            "`http/stored-body-replay.ts` 里 `StoredReplayDeployment` 的 `autonomy` 位与 `storedBodyReplayRefusal` 读 `deployment.autonomy` 的那一句(这一位只服务这一问;四个问点传 `deps.config` 整份,home 位还服务 `permissions` 一问,不动)",
         afterRemoval: "没有响亮臂:删码之后仍停驻、在 7.121.x 及以前写下的行(把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署,或跳过了带本条的版本直接升的库)在设了 " +
             "`AUTONOMY=plan` 的部署上按体里的原词重放(运维的 plan 不再被按段重钳)—— 升级前把这些停驻的 run 决掉 / 取消,或升级窗内设 `AUTONOMY=read-only`",
         reportKeys: [],
@@ -258,6 +258,21 @@ export const ONE_TIME_MIGRATIONS = [
             "调长了 `APPROVAL_TERMINAL_BACKSTOP_MS` 的部署、滚动升级里旧副本在窗内新写的行(头注 M19 段)",
         reportKeys: [],
     },
+    {
+        id: "M20",
+        introducedIn: "7.131.0",
+        releasedOn: "2026-10-16",
+        removableAfter: "2026-11-15",
+        removal: "删 `src/stored-request-hooks-m20.ts` 整只文件(`storedHooksRereadM20` / `rereadStoredHooksM20` / `StoredHooksRereadM20` / `ENTRY_FIELD_NAMES` / `MATCHER_FIELD_NAMES` / `nodeAt` / `cloneDoc` / `removeKeyAt`);" +
+            "`boot/resolve-spec.ts` 里递给 `parseTaskSettings` 的重读座实参(`opts?.leg === \"fresh\" || !taskHooksHonored(config) ? {} : { storedHooksReread: storedHooksRereadM20(…) }`)与它的 import、" +
+            "`hooks_read_as_before_upgrade` 那一段 warn;`task-settings.ts` 的 `ParseTaskSettingsSeats` / `ParseTaskSettingsResult.hooksReread` / `parseTaskSettings` 第二形参与 hooks 臂里的重读那一支;" +
+            "`hooks/hook-runner.ts` 的 `ParseHooksConfigResult.pieces` / `HooksRefusalPiece`(若再无别的读者)与 `hooksCoordinate` 的 export;" +
+            "`test/hooks-stored-reread-m20.test.ts`(窗关那一格 —— 整份不采纳 + `server.hooks.resume-reader-refused` 计一笔 —— 改钉到 `test/hooks-entry-admission.test.ts` 的续跑腿组)",
+        afterRemoval: "没有新的臂,接住它的是今天的读法(删码零行为变化:窗关那一刻起重读臂已经不生效):升级前存下的请求体里带这两形的 `settings.hooks`,续跑重放时整份不采纳(其中真在拦的 `PreToolUse` 钩子也不再拦)," +
+            "运维 warn `task_settings_deferred`(字段 `hooks`)+ fail-open 登记 `server.hooks.resume-reader-refused`(计数 + 探针 + 一次性 warn,census 第 140 行),任务照常续跑 —— " +
+            "出路是把这类停驻任务决掉、删掉那个未知字段 / `__proto__` 键后重新提交。会撞上它的是活过窗的升级前停驻行:发布后才升级的部署、调长了 `APPROVAL_TERMINAL_BACKSTOP_MS` 的部署、滚动升级里旧副本在窗内新写的行(头注 M20 段)",
+        reportKeys: [],
+    },
 ];
 export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;

package/dist/question.d.ts

@@ -23,20 +23,29 @@ export interface QuestionFrame {
     /** "question" only: `serverNowMs + expiresInMs` — absolute deadline on the server's clock. */
     expiresAtMs?: number;
 }
-/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's live stream; `abortSignal`
- *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts. */
+/** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's stream; `abortSignal`
+ *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts.
+ *
+ *  🔴 ONE LAW for every leg: a question frame that enters a run's stream has a LEDGER TWIN (the row
+ *  `GET /v1/runs/:id/events` replays — a page reload recovers the open card from it); the leg decides only whether it
+ *  ALSO writes a live socket. The background leg has no socket, so its `emit` IS the durable append; the synchronous
+ *  stream leg lands the same frame in the ledger first and then writes the SSE connection (`createLedgerTwinEmit`).
+ *  The ledger carries the CARD, not the answer door: `POST /v1/questions/:id/respond` stays live-only (this replica's
+ *  memory, `ttlMs`), so a replayed card is answerable only until its own `expiresAtMs` and only on this replica. */
 export interface QuestionRunContext {
     taskId: string;
     owner: string | null;
     emit: (frame: QuestionFrame) => void | Promise<void>;
     abortSignal?: AbortSignal;
-    /** OPTIONAL reachability predicate for this leg's delivery face, consulted by {@link QuestionCoordinator.hasLiveContext}
-     *  (the park-vs-live adjudication probe), NOT by `question` itself. CONSTRAINT: a leg whose face can go away WHILE the
-     *  leg keeps running MUST supply it — `/v1/tasks/stream` under `x-detach-on-disconnect: true` keeps executing inside
-     *  this ALS scope after the client left, and `emit` there writes to a dead socket and is silently dropped (question
-     *  frames have no durable ledger twin, unlike SendUserFile's ledgerSink). Without the predicate the adjudication would
-     *  read "live" and hand the leg to a face nobody can reach. ABSENT ⇒ always reachable, which is exactly right for the
-     *  background leg (emit appends to the durable events tail, readable whenever a client attaches). */
+    /** OPTIONAL reachability predicate for this leg's LIVE delivery face — one reading, two consumers:
+     *  {@link QuestionCoordinator.hasLiveContext} (the park-vs-live adjudication probe) and the OPEN frame itself (a face
+     *  that cannot show the card right now refuses the ask on the spot, the same failed-delivery arm, instead of parking it
+     *  to TTL on a ledger row nobody is watching). CONSTRAINT: a leg whose face can go away WHILE the leg keeps running MUST
+     *  supply it — `/v1/tasks/stream` under `x-detach-on-disconnect: true` keeps executing inside this ALS scope after the
+     *  client left. Without the predicate the adjudication would read "live" and hand the leg to a face nobody can reach.
+     *  ABSENT ⇒ always reachable, which is exactly right for the background leg (its face IS the durable events tail,
+     *  readable whenever a client attaches). The CLOSE frame never asks it: it is a record, and it lands in the ledger twin
+     *  whether or not the socket is still there. */
     deliverable?: () => boolean;
 }
 /** The per-run question window the deployment owns (core caps nothing). Env: `QUESTION_MAX_CONCURRENT_PER_RUN` /