@sema-agent/server 7.137.0 → 7.138.0

package/dist/memory-sync-client.js

@@ -4,6 +4,12 @@ import { dirname, join } from "node:path";
 import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
 import { replicationCovers } from "./memory-scope.js";
 import { parseProjectLayerKey } from "./project-layer-key.js";
+const CURSOR_MISMATCH_CODE = "config.memory_sync_cursor_mismatch";
+const CURSOR_PREDATES_STORE_NOTICE = "memory_sync_cursor_predates_store";
+const CURSOR_PREDATES_STORE_OUTS = "this layer's sync baseline was written before sync cursors carried a store binding, so the layer does not sync until the operator picks one of two ways out: " +
+    "(1) run one sync round on the previous server version so deletions made since the last round reach the other side, then delete this file; " +
+    "(2) delete this file now to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
+    "and entries deleted on one side since the last round come back from the other side";
 export const DEFAULT_MEMORY_SYNC_PEER = "central";
 export function createMemorySyncTransport(opts) {
     const base = opts.url.replace(/\/+$/, "");
@@ -25,32 +31,56 @@ export function createMemorySyncTransport(opts) {
 export function memorySyncCursorPath(memoryRoot, peer, scope) {
     return join(memoryRoot, "sync-cursors", encodeScopeSegment(peer), `${createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32)}.json`);
 }
-function legacyMemorySyncCursorPath(memoryRoot, peer) {
+function perPeerCursorPath(memoryRoot, peer) {
     return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
 }
-async function loadCursor(path, scope, peer, log) {
+async function readCursorFile(path) {
     let raw;
     try {
         raw = await readFile(path, "utf8");
     }
     catch (err) {
-        if (err.code !== "ENOENT")
-            log.warn("memory_sync_cursor_read_failed", { path, err: String(err), note: "treating as first round" });
-        return undefined;
+        return err.code === "ENOENT" ? { kind: "absent" } : { kind: "unreadable", err: String(err) };
     }
-    let parsed;
     try {
-        parsed = JSON.parse(raw);
+        const value = JSON.parse(raw);
+        return { kind: "parsed", value };
     }
     catch (err) {
-        log.warn("memory_sync_cursor_corrupt", { path, err: String(err), note: "treating as first round" });
-        return undefined;
+        return { kind: "corrupt", err: String(err) };
+    }
+}
+function predatesStoreBinding(parsed, scope, peer) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return false;
+    const c = parsed;
+    return c["scope"] === scope && c["peer"] === peer && c["store"] === undefined;
+}
+async function loadLayerBaseline(path, perPeer, scope, peer, log) {
+    const read = await readCursorFile(path);
+    switch (read.kind) {
+        case "absent": {
+            if (perPeer === undefined)
+                return { kind: "none" };
+            const legacy = await readCursorFile(perPeer);
+            return legacy.kind === "parsed" && predatesStoreBinding(legacy.value, scope, peer) ? { kind: "predates-store", path: perPeer } : { kind: "none" };
+        }
+        case "unreadable":
+            log.warn("memory_sync_cursor_read_failed", { path, err: read.err, note: "treating as first round" });
+            return { kind: "none" };
+        case "corrupt":
+            log.warn("memory_sync_cursor_corrupt", { path, err: read.err, note: "treating as first round" });
+            return { kind: "none" };
+        case "parsed": {
+            if (predatesStoreBinding(read.value, scope, peer))
+                return { kind: "predates-store", path };
+            const cursor = cursorOf(read.value, scope, peer);
+            if (cursor !== undefined)
+                return { kind: "cursor", cursor };
+            log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
+            return { kind: "none" };
+        }
     }
-    const cursor = cursorOf(parsed, scope, peer);
-    if (cursor !== undefined)
-        return cursor;
-    log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
-    return undefined;
 }
 function cursorOf(parsed, scope, peer) {
     if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
@@ -58,43 +88,18 @@ function cursorOf(parsed, scope, peer) {
         const baseRevsRaw = c["baseRevs"];
         if (c["scope"] === scope &&
             c["peer"] === peer &&
+            typeof c["store"] === "string" &&
             typeof c["updatedAtMs"] === "number" &&
             Number.isFinite(c["updatedAtMs"]) &&
             baseRevsRaw !== null &&
             typeof baseRevsRaw === "object" &&
             !Array.isArray(baseRevsRaw) &&
             Object.values(baseRevsRaw).every((v) => typeof v === "string" && v.length > 0)) {
-            return { scope, peer, baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
+            return { scope, peer, store: c["store"], baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
         }
     }
     return undefined;
 }
-async function adoptLegacyCursor(memoryRoot, scope, peer, log) {
-    const target = memorySyncCursorPath(memoryRoot, peer, scope);
-    const legacy = legacyMemorySyncCursorPath(memoryRoot, peer);
-    const facts = await Promise.all([readFile(target, "utf8").then(() => "present", (err) => (err.code === "ENOENT" ? "absent" : "present")), readFile(legacy, "utf8").then((text) => ({ text }), (err) => ({ err }))]);
-    const [targetFact, legacyRead] = facts;
-    if (targetFact === "present")
-        return;
-    if ("err" in legacyRead) {
-        if (legacyRead.err.code !== "ENOENT")
-            log.warn("memory_sync_cursor_read_failed", { path: legacy, err: String(legacyRead.err), note: "legacy cursor not adopted — this layer starts from its own cursor" });
-        return;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(legacyRead.text);
-    }
-    catch (err) {
-        log.warn("memory_sync_cursor_corrupt", { path: legacy, err: String(err), note: "legacy cursor not adopted" });
-        return;
-    }
-    if (cursorOf(parsed, scope, peer) === undefined)
-        return;
-    await mkdir(dirname(target), { recursive: true });
-    await rename(legacy, target);
-    log.info("memory_sync_cursor_adopted", { from: legacy, to: target, scope, peer });
-}
 async function saveCursor(path, cursor) {
     await mkdir(dirname(path), { recursive: true });
     const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
@@ -110,7 +115,6 @@ export function createMemorySyncRunner(opts) {
     const peer = opts.peer ?? DEFAULT_MEMORY_SYNC_PEER;
     const coverage = { kind: "layers", layers: [opts.scope] };
     const tracked = new Set();
-    let legacyCursorChecked = false;
     let enumerationWarned = false;
     const isCoveredProjectLayer = (scope) => scope !== opts.scope && parseProjectLayerKey(scope) !== undefined && replicationCovers(coverage, scope);
     const layersOfRound = () => {
@@ -124,21 +128,36 @@ export function createMemorySyncRunner(opts) {
     };
     const syncLayer = async (scope, reason) => {
         const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer, scope);
-        let cursor = await loadCursor(cursorPath, scope, peer, opts.log);
+        const baseline = await loadLayerBaseline(cursorPath, scope === opts.scope ? perPeerCursorPath(opts.memoryRoot, peer) : undefined, scope, peer, opts.log);
+        if (baseline.kind === "predates-store") {
+            opts.log.warn(CURSOR_PREDATES_STORE_NOTICE, { scope, peer, path: baseline.path, note: CURSOR_PREDATES_STORE_OUTS });
+            throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — its baseline ${baseline.path} predates the store binding (see warn ${CURSOR_PREDATES_STORE_NOTICE})`);
+        }
+        let cursor = baseline.kind === "cursor" ? baseline.cursor : undefined;
         let result;
         let subRound = 0;
         for (;;) {
             subRound += 1;
-            result = await syncMemoryScope({
-                backend: opts.backend,
-                scope,
-                transport: opts.transport,
-                peer,
-                ...(cursor !== undefined ? { cursor } : {}),
-                ...(opts.now !== undefined ? { now: opts.now } : {}),
-                ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
-                ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
-            });
+            try {
+                result = await syncMemoryScope({
+                    backend: opts.backend,
+                    scope,
+                    transport: opts.transport,
+                    peer,
+                    ...(cursor !== undefined ? { cursor } : {}),
+                    ...(opts.now !== undefined ? { now: opts.now } : {}),
+                    ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
+                    ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
+                });
+            }
+            catch (err) {
+                if (cursor === undefined || err?.code !== CURSOR_MISMATCH_CODE)
+                    throw err;
+                opts.log.warn("memory_sync_cursor_rebound", { scope, peer, subRound, note: "the persisted cursor is bound to another store — running this round from no cursor and replacing it" });
+                cursor = undefined;
+                subRound -= 1;
+                continue;
+            }
             for (const w of result.warnings ?? [])
                 opts.log.warn("memory_sync_warning", { scope, peer, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
@@ -192,10 +211,6 @@ export function createMemorySyncRunner(opts) {
         return result;
     };
     const round = async (reason) => {
-        if (!legacyCursorChecked) {
-            legacyCursorChecked = true;
-            await adoptLegacyCursor(opts.memoryRoot, opts.scope, peer, opts.log);
-        }
         const layers = [];
         const failures = [];
         for (const scope of layersOfRound()) {

package/dist/memory-sync.d.ts

@@ -2,7 +2,7 @@ import { type MemoryBackend, type MemoryEntry, type PatchReport } from "@sema-ag
 import type { MemorySyncStore } from "./plugins/memory-sync-store-pg.js";
 /** 一轮同步请求(验型后的干净形状——`parseMemorySyncRequest` 是唯一铸造点)。 */
 export interface MemorySyncRequest {
-    /** 对端标识(MemorySyncCursor.peer,per-(scope,peer) 游标分区键)。 */
+    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)。 */
     peer: string;
     /** 客户端游标的共同基线:id → rev at last completed sync round(空 map = 首轮)。 */
     baseRevs: Record<string, string>;

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

@@ -1,23 +1,3 @@
-/**
- * **env 模型路由读数的唯一读口**:`readModelRouteEnv(env)`、env 腿的条目表 `envLaneTable`,与车道值级端口 `laneAndEndpointFor`。
- *
- * ## 形(一只读口、一处调用)
- * 「env 里哪几把键是模型路由、空串 = 未设、provider 的显式 / 推断 / 缺省、env 腿铸哪几个条目槽」的读法只在这里:
- *  · {@link readModelRouteEnv}:`parseModelDomain`(`config.ts`,起服铸 `ServiceConfig` 的路由字段)吃它的读数(`process.env` 与测试快照是同一个入参位);
- *  · {@link envLaneTable}:env 腿的条目名与键序(`parseModelDomain` 铸真 `Model` 表经它);
- *  · {@link laneAndEndpointFor}:值级端口 —— 「这只模型在这张路由表上走哪条车道、这条车道的端点 / 凭据取哪一对 env 键」。车道只经 `brainLaneFor`
- *    (core `brainLaneOf` 对路由表的答案)取,键名取 {@link MODEL_ROUTE_ENV_KEYS};**只交键名不交值**。
- * 路由判据本身(「将要服务的那张表里每条 openai 兼容路由是否解析得到端点」)不在这里:唯一属主是 `model-route-endpoint.ts` 的 `judgeModelRouteEndpoint`,
- * 起服段与 `GET /v1/models.modelPlane` 经 `judgeServedModelRoute` 问它 —— 它们判的是**将要服务的那张表**(env 表或目录表),不是本文件读出的 env 视图。
- *
- * ## 对外
- * 本模块的精选再导出是子路径 `@sema-agent/server/model-route-env`(`src/model-route-env.ts`):引擎 core 是 BYOM(只吃调用方给的路由表,不读这些键),
- * 别仓要在引擎起之前回答「走哪条车道、端点 / 凭据取哪一对键」,读这一只,不各抄一份键名与车道判。
- *
- * ## 纯
- * 不读 `process.env`、不读文件、不枚举快照 —— 只按 {@link MODEL_ROUTE_ENV_KEYS} 点名取值(依赖闭包里没有 `node:*` / `process`,
- * `test/model-route-env-reading.test.ts` 钉)。同入同出;返回值是新对象。provider 词域外的值在这里按引擎派发的口径读作网关腿(`brainLaneFor`:域外词的路由表里没有那个键 ⇒ 引擎路由器落网关 fallback),不在此拒(域外拒启是 `model-provider-word` 那条不变量的事)。
- */
 import { type ModelBrainLane } from "./model-provider.js";
 /**
  * 路由读数读的九把 env 键(**闭表**;{@link readModelRouteEnv} 只碰这几把,测试用代理钉「读集 ⊆ 本表」)。
@@ -59,8 +39,9 @@ export interface ModelRouteEnvReading {
     /** `MODEL_GATEWAY_FALLBACK_URLS` 逐项 trim、丢空项。 */
     readonly gatewayFallbackUrls: string[];
     /**
-     * `MODEL_API_KEY`(网关腿的部署级凭据):**原样**读 —— 与其余各把不同,空串**不**折成未设。brain 装配以**真值**判这把凭据发不发(空串部署一个凭据字节都不发),
+     * `MODEL_API_KEY`(网关腿的部署级凭据):读数**原样**交出 —— 与其余各把不同,空串**不**折成未设:
      * 起服铸的 `ServiceConfig.gatewayApiKey` 逐字保留空串(compose 的 `${VAR:-}` 模板与空 Secret 挂载天天产它);读数改折叠会改变那一位。
+     * 「这把凭据设了没有」的问法不在读数里折,而是消费方问 {@link declaredCredential}(引擎的 `isBlankCredential`:空串与只含空白都 = 没有)。
      * 它只与网关端点配对(没有 {@link gatewayBaseUrl} 就不装载),配对由消费方判。
      */
     readonly gatewayApiKey: string | undefined;
@@ -85,6 +66,9 @@ export interface ModelRouteEnvReading {
     /** cheap 槽铸不铸(见 {@link EnvCheapSlot})。 */
     readonly cheapSlot: EnvCheapSlot;
 }
+/** 一把凭据键「设了没有」的唯一问法(两把 anthropic 键与网关键 `MODEL_API_KEY` 同读):引擎的 `isBlankCredential`(整串 trim 后为空 ⇒ 没有凭据)—— 与引擎对同一个值的读法同一只,
+ *  不自拼第二种「空」:只含空白的 key 旁边的 token 是 bearer(引擎让那只头作凭据照发),不是同设冲突;两把都空白 = 缺席、路由不挂;只含空白的网关 key = 没有部署凭据。 */
+export declare const declaredCredential: (v: string | undefined) => string | undefined;
 /** 逗号串读法的归一点:逐项 trim、丢空项(缺席 = 空串 = `[]`)。本文件的 CSV 路由键与 `config.ts` 的逗号串旋钮(按名薄壳 `csv(name)`)同读这一只;
  *  目录模块的回显分词与 `SERVICE_AUTH_TOKENS` 的 `k=v` 对分词是同形的另两处,尚未改调(清账版收,本函数届时挪到中性模块)。 */
 export declare const csvOf: (raw: string | undefined) => string[];
@@ -98,7 +82,7 @@ export declare function readModelRouteEnv(env: ModelRouteEnv): ModelRouteEnvRead
  *  · `ANTHROPIC_API_KEY`    ⇒ `x-api-key`(只发它);
  *  · `ANTHROPIC_AUTH_TOKEN` ⇒ `Authorization: Bearer`(只发它);
  *  · 两个都设 ⇒ `conflict`:两个名字说的是两种头,哪个赢都是替运维猜(7.135.0 及以前是「AUTH_TOKEN 优先」,x-api-key 被静默丢弃)⇒ 起服拒启,拒句 {@link anthropicCredentialRefusal}。
- * 空串 = 未设(与 {@link readModelRouteEnv} 同尺)。入参是两个名字各自的值 —— env 读数的两位或 `config.anthropic` 的 `apiKey` / `authToken` —— 不读 `process.env`。
+ * 「设了没有」按引擎的 `isBlankCredential` 读(空串与只含空白都 = 未设;与 {@link declaredCredential} 同一只)。入参是两个名字各自的值 —— env 读数的两位或 `config.anthropic` 的 `apiKey` / `authToken` —— 不读 `process.env`。
  * 读者:起服(`config.ts` 的拒启锚与跨键不变量表 `anthropic-credential-exclusive` 同一句)· brain 装配(交引擎哪种头)· hook 直连腿(哪种头、交引擎配对判官的那份值)·
  * 车道端口 {@link laneAndEndpointFor}(哪把键)· 起服的 Bearer 部署诊断(`boot/web-admin.ts`)。
  */

package/dist/model-route-gap.js

@@ -1,3 +1,4 @@
+import { isBlankCredential } from "@sema-agent/core";
 import { brainLaneFor, declaredRootUrl } from "./model-provider.js";
 import { DEFAULT_MODEL_REF } from "./model-select.js";
 export const MODEL_ROUTE_ENV_KEYS = {
@@ -22,14 +23,15 @@ export function mintedCheapId(slot) {
     }
 }
 const declaredValue = (v) => (v !== undefined && v !== "" ? v : undefined);
+export const declaredCredential = (v) => (v !== undefined && !isBlankCredential(v) ? v : undefined);
 export const csvOf = (raw) => (raw ?? "")
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean);
 export function readModelRouteEnv(env) {
     const K = MODEL_ROUTE_ENV_KEYS;
-    const anthropicApiKey = declaredValue(env[K.anthropicApiKey]);
-    const anthropicAuthToken = declaredValue(env[K.anthropicAuthToken]);
+    const anthropicApiKey = declaredCredential(env[K.anthropicApiKey]);
+    const anthropicAuthToken = declaredCredential(env[K.anthropicAuthToken]);
     const anthropicBaseUrl = declaredValue(env[K.anthropicBaseUrl]);
     const anthropicRouteMounted = anthropicApiKey !== undefined || anthropicAuthToken !== undefined;
     const explicitProvider = declaredValue(env[K.provider]);
@@ -58,8 +60,8 @@ export function readModelRouteEnv(env) {
 }
 export function judgeAnthropicCredential(names) {
     const K = MODEL_ROUTE_ENV_KEYS;
-    const apiKey = declaredValue(names.apiKey);
-    const authToken = declaredValue(names.authToken);
+    const apiKey = declaredCredential(names.apiKey);
+    const authToken = declaredCredential(names.authToken);
     if (apiKey !== undefined && authToken !== undefined)
         return { kind: "conflict" };
     if (apiKey !== undefined)
@@ -111,7 +113,7 @@ export function laneAndEndpointFor(env, model, routes) {
             };
         case "gateway": {
             const endpointDeclared = declaredRootUrl(reading.gatewayBaseUrl) !== undefined;
-            const credentialLoaded = endpointDeclared && reading.gatewayApiKey !== undefined && reading.gatewayApiKey !== "";
+            const credentialLoaded = endpointDeclared && declaredCredential(reading.gatewayApiKey) !== undefined;
             return { lane, endpointEnvName: K.gatewayBaseUrl, endpointDeclared, apiKeyEnvName: credentialLoaded ? K.gatewayApiKey : undefined };
         }
     }

package/dist/mods-declaration.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 部署声明的 mod 包 —— `MODS_ROOT` + `MODS_PACKAGES` 的**唯一读法**,以及部署座装配(`boot/deployment-mods.ts`)全部失败的**唯一词表与拒句**。
+ *
+ * ## 规则(一句)
+ * mod 包只从运维的部署声明装载;声明只说四件宿主的事实 —— 装哪个目录(`dir`)、叫什么(`name`,须与包自己的名逐字同)、站哪一档(`tier`)、
+ * 交给它什么(`options`);包里的三件文件只有引擎一只读者(`loadModPackage`),本仓**不读包内任何文件、不算摘要**。
+ *
+ * ## 声明的形
+ *  · `MODS_ROOT` —— 绝对路径;声明的每只包解析真实路径之后必须**严格**落在它(的真实路径)之下(按路径分量判,不是前缀;根本身不是包目录)。
+ *    单设它而不声明包 = 无事(形照判)。
+ *  · `MODS_PACKAGES` —— JSON 数组,每项闭集四键 `{ name, dir, tier, options? }`:`name` 非空串;`dir` 绝对路径;`tier` ∈ `prepend | user | append`
+ *    (宿主必填 —— 包不自报档;站不站得住由引擎的座 × 档表判,部署座三档都许);`options` 任意 JSON 值,原样交包的 `register`。
+ *    缺席 / 空串 = 不声明(部署座只有本仓自铸的注册,与没有这两根旋钮的版本逐字节同)。
+ *  · `MODS_PACKAGES` 是一份声明、不是凭据值:配置目录只回在场位与长度(不回显);`options` 不是凭据通道 —— 本服务不替包扣凭据(声明与包自己读的环境变量
+ *    都不在自有凭据声明里,宿主车道 `inheritEnv: "all"` 下模型的子进程照样继承)。
+ *
+ * ## 失败(两类,一张闭集词表,一种拒句)
+ *  · **声明 / 文件系统**(本仓判;任何一只包被装载之前,整张声明全部判完):
+ *    `config_invalid`(某一席的形不对 —— 整段 JSON、某一项、`MODS_ROOT`)· `root_missing`(声明了包而 `MODS_ROOT` 没设)·
+ *    `name_missing` · `duplicate_name` · `root_unreadable` · `dir_unreadable` · `outside_root` · `not_a_directory`;
+ *  · **读包者 / 准入**(引擎判,本仓只透传):`package_refused`(读包者拒了这只包)· `name_mismatch`(包自己的名与声明的不同)·
+ *    `admission_refused`(整列交引擎准入被拒)。
+ * 任一失败 = 拒启。拒句一行:`deployment mods refused: <词>(<主语>)[: <细节>]`,整行经出口座 `boot-refusal-line`(剥控制与双向字符、凭据形换记号、
+ * ≤ 512 码元含截断记号)—— 读包者 / 准入的机器码原样留在主语括号里;本仓写的句子不回显声明的值(路径、`options`),主语只点名是哪一席(`MODS_PACKAGES[2]`)
+ * 或哪只包;读包者 / 准入 / 包自己交回的话原样透传(过出口座),其中可能点名包目录 —— 那是运维要的诊断,包本身是受信代码。
+ */
+import type { ModRegistrationTier } from "@sema-agent/core";
+/** 声明的一只包(宿主的四件事实)。 */
+export interface DeclaredModPackage {
+    readonly name: string;
+    readonly dir: string;
+    readonly tier: ModRegistrationTier;
+    /** 缺席 = 声明里没写这一键(交给 `register` 的就是 `undefined`)。 */
+    readonly options?: unknown;
+}
+/**
+ * 部署声明(`loadConfig` 读一次;两只起服入口的装配都读这一份)。两种形,形即律:
+ *  · **没声明包** —— 没有 `packages` 这一席(变量缺席 / 空串 / 显式 `[]` 同一形);`root` 只在单设了 `MODS_ROOT` 时在(形照判、无事,配置目录照回);
+ *  · **声明了包** —— 至少一只,且**必有根**:「有包无根」「有根空表」都不是可表示的值(`root_missing` 只在本模块的读法里判,装配口没有这一臂)。
+ * 读者按 `d.packages === undefined` 分两形(`packages` 是判别位:没声明那一形上它只能缺席)。
+ */
+export type ModsDeclaration = {
+    readonly root?: string;
+    readonly packages?: never;
+} | {
+    readonly root: string;
+    readonly packages: readonly [DeclaredModPackage, ...DeclaredModPackage[]];
+};
+/** 声明里的一席:整根旋钮,或 `MODS_PACKAGES` 的第几项。 */
+export type DeclarationSeat = "MODS_ROOT" | "MODS_PACKAGES" | {
+    readonly entry: number;
+};
+/** 一次失败(词 + 主语 + 细节)。细节只有两种来源:本仓写死的句子,或读包者 / 准入交回的话(过出口座)。**失败词的唯一来源是本联合各成员的 `word`。** */
+export type DeploymentModsRefusal = {
+    readonly word: "config_invalid";
+    readonly seat: DeclarationSeat;
+    readonly why: string;
+} | {
+    readonly word: "root_missing";
+} | {
+    readonly word: "name_missing";
+    readonly entry: number;
+} | {
+    readonly word: "duplicate_name";
+    readonly entry: number;
+    readonly first: number;
+} | {
+    readonly word: "root_unreadable";
+    readonly cause: string;
+} | {
+    readonly word: "dir_unreadable";
+    readonly entry: number;
+    readonly cause: string;
+} | {
+    readonly word: "outside_root";
+    readonly entry: number;
+} | {
+    readonly word: "not_a_directory";
+    readonly entry: number;
+} | {
+    readonly word: "package_refused";
+    readonly name: string;
+    readonly code: string | undefined;
+    readonly reason: string;
+} | {
+    readonly word: "name_mismatch";
+    readonly name: string;
+    readonly packageName: string;
+} | {
+    readonly word: "admission_refused";
+    readonly code: string | undefined;
+    readonly reason: string;
+};
+/** 失败词(拒句的 `<词>`)= 联合成员的 `word`,不另写一份。渲染是穷尽 `switch`(加成员不加臂 = 编译红)。 */
+export type DeploymentModsRefusalWord = DeploymentModsRefusal["word"];
+/** 失败词闭集(运行期全集;「每词至少一格」的钉读它)。 */
+export declare const DEPLOYMENT_MODS_REFUSALS: readonly DeploymentModsRefusalWord[];
+/** 一次失败的拒句(一行;整行经出口座 `boot-refusal-line`:剥控制与双向字符、凭据形换记号、≤ 512 码元含截断记号)。 */
+export declare function buildDeploymentModsRefusalLine(r: DeploymentModsRefusal): string;
+/** 部署座装配的拒启(两只起服入口同一只类型;`refusal` 是机读的那一份,`message` 是它的拒句)。 */
+export declare class DeploymentModsRefusedError extends Error {
+    readonly refusal: DeploymentModsRefusal;
+    constructor(refusal: DeploymentModsRefusal);
+}
+/**
+ * 声明的形(纯函数,`loadConfig` 调;文件系统那一半在装配里):`MODS_ROOT` 的形 → `MODS_PACKAGES` 是不是 JSON 数组 → 逐项(序号升序;每项:是对象 →
+ * 键闭集 → `name` → `dir` → `tier` → 与前面的项重名)→ 声明了包而没设根。第一处不过即拒,拒句不回显声明的值。
+ */
+export declare function parseModsDeclaration(rootRaw: string | undefined, packagesRaw: string | undefined): ModsDeclaration;
+//# sourceMappingURL=mods-declaration.d.ts.map

package/dist/mods-declaration.js

@@ -0,0 +1,109 @@
+import { isAbsolute } from "node:path";
+import { seatText } from "./trace/exit-seat.js";
+const DECLARABLE_TIERS = { prepend: true, user: true, append: true };
+const TIER_WORDS = Object.keys(DECLARABLE_TIERS);
+const isDeclarableTier = (v) => typeof v === "string" && Object.hasOwn(DECLARABLE_TIERS, v);
+const ENTRY_KEYS = new Set(["name", "dir", "tier", "options"]);
+const REFUSAL_WORDS = {
+    config_invalid: true,
+    root_missing: true,
+    name_missing: true,
+    duplicate_name: true,
+    root_unreadable: true,
+    dir_unreadable: true,
+    outside_root: true,
+    not_a_directory: true,
+    package_refused: true,
+    name_mismatch: true,
+    admission_refused: true,
+};
+export const DEPLOYMENT_MODS_REFUSALS = Object.keys(REFUSAL_WORDS);
+const seatLabel = (seat) => (typeof seat === "string" ? seat : `MODS_PACKAGES[${seat.entry}]`);
+const entryLabel = (entry) => seatLabel({ entry });
+const nameLabel = (name) => JSON.stringify(name);
+function refusalText(r) {
+    const line = (subject, detail) => `deployment mods refused: ${r.word}${subject !== undefined ? `(${subject})` : ""}${detail !== undefined ? `: ${detail}` : ""}`;
+    switch (r.word) {
+        case "config_invalid":
+            return line(seatLabel(r.seat), r.why);
+        case "root_missing":
+            return line("MODS_ROOT", "MODS_PACKAGES declares packages but MODS_ROOT is not set — every declared package must resolve under that root");
+        case "name_missing":
+            return line(entryLabel(r.entry), "name must be a non-empty string — the package's own name (its .claude-plugin/plugin.json `name`), spelled exactly");
+        case "duplicate_name":
+            return line(entryLabel(r.entry), `same name as ${entryLabel(r.first)} — each declared package is one registration and a name is its identity`);
+        case "root_unreadable":
+            return line("MODS_ROOT", `its real path cannot be resolved (${r.cause})`);
+        case "dir_unreadable":
+            return line(entryLabel(r.entry), `dir's real path cannot be resolved (${r.cause})`);
+        case "outside_root":
+            return line(entryLabel(r.entry), "dir does not resolve strictly under MODS_ROOT (real paths, compared by path components; the root itself is not a package directory)");
+        case "not_a_directory":
+            return line(entryLabel(r.entry), "dir does not resolve to a directory");
+        case "package_refused":
+            return line(r.code !== undefined ? `${nameLabel(r.name)}, ${r.code}` : nameLabel(r.name), r.reason);
+        case "name_mismatch":
+            return line(nameLabel(r.name), `the package names itself ${nameLabel(r.packageName)} — the declared name must be the package's own name, spelled exactly`);
+        case "admission_refused":
+            return line(r.code, r.reason);
+    }
+}
+export function buildDeploymentModsRefusalLine(r) {
+    return seatText("boot-refusal-line", refusalText(r));
+}
+export class DeploymentModsRefusedError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(buildDeploymentModsRefusalLine(refusal));
+        this.refusal = refusal;
+    }
+}
+function refuse(r) {
+    throw new DeploymentModsRefusedError(r);
+}
+const isPlainRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function parseModsDeclaration(rootRaw, packagesRaw) {
+    const root = rootRaw === undefined || rootRaw === "" ? undefined : rootRaw;
+    if (root !== undefined && !isAbsolute(root))
+        refuse({ word: "config_invalid", seat: "MODS_ROOT", why: "must be an absolute path" });
+    const undeclared = root !== undefined ? { root } : {};
+    if (packagesRaw === undefined || packagesRaw.trim() === "")
+        return undeclared;
+    let parsed;
+    try {
+        parsed = JSON.parse(packagesRaw);
+    }
+    catch {
+        refuse({ word: "config_invalid", seat: "MODS_PACKAGES", why: "is not valid JSON" });
+    }
+    if (!Array.isArray(parsed))
+        refuse({ word: "config_invalid", seat: "MODS_PACKAGES", why: "must be a JSON array of { name, dir, tier, options? }" });
+    const packages = [];
+    const firstIndexOf = new Map();
+    for (const [entry, item] of parsed.entries()) {
+        if (!isPlainRecord(item))
+            refuse({ word: "config_invalid", seat: { entry }, why: "must be an object { name, dir, tier, options? }" });
+        const unknown = Object.keys(item).filter((k) => !ENTRY_KEYS.has(k));
+        if (unknown.length > 0)
+            refuse({ word: "config_invalid", seat: { entry }, why: `has keys outside { name, dir, tier, options }: ${unknown.map((k) => JSON.stringify(k)).join(", ")}` });
+        const { name, dir, tier } = item;
+        if (typeof name !== "string" || name === "")
+            refuse({ word: "name_missing", entry });
+        if (typeof dir !== "string" || !isAbsolute(dir))
+            refuse({ word: "config_invalid", seat: { entry }, why: "dir must be an absolute path" });
+        if (!isDeclarableTier(tier))
+            refuse({ word: "config_invalid", seat: { entry }, why: `tier must be one of ${TIER_WORDS.join(", ")} — the host declares it, a package never does` });
+        const first = firstIndexOf.get(name);
+        if (first !== undefined)
+            refuse({ word: "duplicate_name", entry, first });
+        firstIndexOf.set(name, entry);
+        packages.push({ name, dir, tier, ...(Object.hasOwn(item, "options") ? { options: item.options } : {}) });
+    }
+    const [head, ...tail] = packages;
+    if (head === undefined)
+        return undeclared;
+    if (root === undefined)
+        refuse({ word: "root_missing" });
+    return { root, packages: [head, ...tail] };
+}
+//# sourceMappingURL=mods-declaration.js.map

package/dist/observability/err-text.d.ts

@@ -9,4 +9,9 @@ export declare function errorText(e: unknown): string;
  * `name` 的 getter 抛、或它交回的不是字符串(拼进模板串会抛的 Symbol 等)⇒ `<unreadable>`。
  */
 export declare function errorKindOf(err: unknown): string;
+/**
+ * 错误自带的机器码(`err.code` 串:Node 的 `ENOENT`、引擎的 `config.mods_invalid` …)—— 第三只读口,同一处兜底 {@link readOr}:`code` 的 getter 抛 / 代理抛 /
+ * 不是串 ⇒ `undefined`(没有码,不编一个)。调用方按自己的形判(什么样的码配进一句拒句)再用它。
+ */
+export declare function errorCodeOf(err: unknown): string | undefined;
 //# sourceMappingURL=err-text.d.ts.map

package/dist/observability/err-text.js

@@ -21,4 +21,13 @@ export function errorKindOf(err) {
         return typeof name === "string" ? name : KIND_UNREADABLE;
     }, KIND_UNREADABLE);
 }
+export function errorCodeOf(err) {
+    const code = readOr(() => {
+        if (!(err instanceof Error) || !("code" in err))
+            return "";
+        const c = err.code;
+        return typeof c === "string" ? c : "";
+    }, "");
+    return code === "" ? undefined : code;
+}
 //# sourceMappingURL=err-text.js.map

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

@@ -193,7 +193,7 @@ export declare const FAIL_OPEN_TAGS: {
     };
     readonly "server.approvals.durable-row-checkpoint-id-missing": {
         readonly cls: "F";
-        readonly note: "7.133.0(`checkpoint-identity.ts` 的 `durableRowIdentity`;两只店的 `listPending` + `/v1/assistant/inbox` handler):三处 durable 读面(运维队列行 `GET /v1/approvals` 与 `/v1/approvals/stream` 的 `pending` 帧;停驻收件 `GET /v1/assistant/inbox` 的行)读到一行停驻门**没有可用的 `checkpointId`** ⇒ 这一行**照列、`checkpointId` 键缺席**(消费方按「这一行没有可 join 的身份」处理)。detail = `face=<approvals-queue|assistant-inbox> why=<absent|untrusted>`:`absent` = 行上没有这一格(core 5.42.0 之前停驻的老行 —— core 明写不回填);`untrusted` = 在场却没过信任边界(非串 / 空串 / 超长 / 含 resume token —— 数据污染;没过边界的值不上 wire)。放行(列、键缺席)的最坏后果 = 消费方对这一行做不了跨面 join(三面对账少一行)—— 行本身、决断口(`/v1/approvals/:sessionId/decide`,按会话)、到期收割都照常。不放行有两种形:整只拒的代价是一行老 / 坏行打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧);把这一行藏起来的代价更糟 —— 人看不到要批的东西(审批面上的 fail-open,方向反了)。故 F 类;必须留痕(两种成因从此可分)。计数非零 = 有老 / 坏行在飞(列着、没身份);`/stream` 每 3s 一拍重读,同一行每拍计一次(量值 = 行 × 拍数,在场才是信号)。 7.137.0 起第四面:park 账本行(`GET /v1/runs/:id/events` 的 `suspended` / `needs_review`;唯一构造器 `trace/project.ts` 的 `parkEventData`,写时判一次,detail `face=run-events-park`)—— 暂停因由上的门身份没过信任边界 ⇒ 行照写、`checkpointId` 键缺席(决断方回显不了这道门,退回不带键的决断或从 run 结果取原值;行本身、门、待批调用身份照常)。";
+        readonly note: "7.133.0(`checkpoint-identity.ts` 的 `durableRowIdentity`;两只店的 `listPending` + `/v1/assistant/inbox` handler):三处 durable 读面(运维队列行 `GET /v1/approvals` 与 `/v1/approvals/stream` 的 `pending` 帧;停驻收件 `GET /v1/assistant/inbox` 的行)读到一行停驻门**没有可用的 `checkpointId`** ⇒ 这一行**照列、`checkpointId` 键缺席**(消费方按「这一行没有可 join 的身份」处理)。detail = `face=<approvals-queue|assistant-inbox> why=<absent|untrusted>`:`absent` = 行上没有这一格(core 5.42.0 之前停驻的老行 —— core 明写不回填);`untrusted` = 在场却没过信任边界(非串 / 空串 / 超长 / 含 resume token —— 数据污染;没过边界的值不上 wire)。放行(列、键缺席)的最坏后果 = 消费方对这一行做不了跨面 join(三面对账少一行)—— 行本身、决断口(`/v1/approvals/:sessionId/decide`,按会话)、到期收割都照常。不放行有两种形:整只拒的代价是一行老 / 坏行打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧);把这一行藏起来的代价更糟 —— 人看不到要批的东西(审批面上的 fail-open,方向反了)。故 F 类;必须留痕(两种成因从此可分)。计数非零 = 有老 / 坏行在飞(列着、没身份);`/stream` 每 3s 一拍重读,同一行每拍计一次(量值 = 行 × 拍数,在场才是信号)。 7.137.0 起第四面:park 账本行(`GET /v1/runs/:id/events` 的 `suspended` / `needs_review`;唯一构造器 `trace/project.ts` 的 `parkEventData`,写时判一次,detail `face=run-events-park`)—— 暂停因由上的门身份没过信任边界 ⇒ 行照写、`checkpointId` 键缺席(决断方回显不了这道门,退回不带键的决断或从 run 结果取原值;行本身、门、待批调用身份照常)。 第五面:回决门族的 200 体(`/decide` / `/resume` / `/plan_review` 执行之前从选中的那一行捕获一次,`http/resume-legs.ts` 三处;detail `face=decision-receipt`)—— 选中那一行的门身份没过信任边界 ⇒ 结清证据照铸、体上 `checkpointId` 键缺席(决断方只是对不上身份;位、决定、续跑都照常)。每次走到捕获点的决断计一次(计的是选中那一行的事实,与这次决断随后走哪条车道无关)。";
     };
     readonly "server.approvals.queue-row-gate-kind-missing": {
         readonly cls: "F";
@@ -279,6 +279,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-690(`instruction-source-notice.ts announceInstructionSource`,项目指令换源通告的唯一铸点;detail 的 `op` 点名哪一步):基线**读**失败或超期(会话店抖动 / 列形坏 / 2s 期限到,detail 带 `timeout=`)⇒ 本 run 不比也不写;基线**写**失败或超期 ⇒ 本 run 的换源帧照发(它对本 run 为真),下一 run 可能再说一遍同一次换源(超期后才落地的写由 CAS 挡住,盖不掉更新的基线);通告**出口**抛 ⇒ 本 run 缺这一帧。放行的最坏后果 = 一次换源没被说出来或被多说一次 —— 通告是**披露**面,不参与任何门 / 裁决,模型读到的指令本身不受影响。不放行的代价严重不对称:铸点跑在 core 的 `loadProjectMemory` 席内,抛回去 core 会把这次 prepare 的项目记忆整块丢掉(不注入),为一条通告赔上指令本身。计数让「某台部署的会话店一直读不出基线」与「这台部署从来没换过源」在遥测上分得开。";
     };
+    readonly "server.session-workspace.record-degraded": {
+        readonly cls: "F";
+        readonly note: "会话行的位置与项目那一格(`session_meta.workspace` / local `session-workspaces.json`;唯一写者 `session-workspace.ts` 的腿记录座,唯一列属主 `plugins/session-workspace-cell.ts`;detail 的 `op` 点名哪一步):`op=write` 一次写失败(库抖 / 盘满 / 锁等待超时)⇒ 行停在上一帧,下一帧照写;`op=read` 一格读不出(被带外改坏)⇒ 读作没有记录,下一帧整格重写;`op=frame` 一帧投不成存储形(引擎不会铸出这种帧)⇒ 这一帧不记。这一格是宿主对**引擎判过的答案**的记录,不是判据 —— 引擎每条腿都重判项目(有记号就判记号,声明不等响亮拒)。放行的最坏后果 = 这只会话的下一条不带 `projectId` 的提交续声明的是旧的项目或不声明(没有记号的检出里这只会话少一次续声明);不放行的代价是把一条在跑的腿、或这只会话往后的每一次提交,为一份记录摔掉。计数非零 = 这台部署的会话店写不动 / 有人改过库。";
+    };
     readonly "server.engine-notice.wire-sink-threw": {
         readonly cls: "F";
         readonly note: "#310:`engine_notice` 分流器把一条白名单通告投给某条 run 腿的登记口时,那只口抛了(live 口写向已断/已撕裂的 SSE socket,或 durable 口的账本写同步抛)。放行的最坏后果 = **这一条通告的这一个终点**缺席:①日志终点在分流之前已经逐字打过(事实一条不丢);②两个终点注册成两只独立 sink ⇒ live 抛不牵连 durable(断连后仍看得见的那半保住);③同会话其余口照投。故 F 类。不放行的代价是把异常回抛给 core 的 `deliverEngineNotice` —— 它会吞掉,于是同一次失败**既没有留痕也没有第二只口**,正是本 tag 要根除的形。留痕是承重的:静默吞掉之后「wire 腿为什么总有几条通告不到」在遥测里与「core 本来就没发」同形。";

package/dist/observability/fail-open.js

@@ -174,7 +174,7 @@ export const FAIL_OPEN_TAGS = {
     },
     "server.approvals.durable-row-checkpoint-id-missing": {
         cls: "F",
-        note: "7.133.0(`checkpoint-identity.ts` 的 `durableRowIdentity`;两只店的 `listPending` + `/v1/assistant/inbox` handler):三处 durable 读面(运维队列行 `GET /v1/approvals` 与 `/v1/approvals/stream` 的 `pending` 帧;停驻收件 `GET /v1/assistant/inbox` 的行)读到一行停驻门**没有可用的 `checkpointId`** ⇒ 这一行**照列、`checkpointId` 键缺席**(消费方按「这一行没有可 join 的身份」处理)。detail = `face=<approvals-queue|assistant-inbox> why=<absent|untrusted>`:`absent` = 行上没有这一格(core 5.42.0 之前停驻的老行 —— core 明写不回填);`untrusted` = 在场却没过信任边界(非串 / 空串 / 超长 / 含 resume token —— 数据污染;没过边界的值不上 wire)。放行(列、键缺席)的最坏后果 = 消费方对这一行做不了跨面 join(三面对账少一行)—— 行本身、决断口(`/v1/approvals/:sessionId/decide`,按会话)、到期收割都照常。不放行有两种形:整只拒的代价是一行老 / 坏行打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧);把这一行藏起来的代价更糟 —— 人看不到要批的东西(审批面上的 fail-open,方向反了)。故 F 类;必须留痕(两种成因从此可分)。计数非零 = 有老 / 坏行在飞(列着、没身份);`/stream` 每 3s 一拍重读,同一行每拍计一次(量值 = 行 × 拍数,在场才是信号)。 7.137.0 起第四面:park 账本行(`GET /v1/runs/:id/events` 的 `suspended` / `needs_review`;唯一构造器 `trace/project.ts` 的 `parkEventData`,写时判一次,detail `face=run-events-park`)—— 暂停因由上的门身份没过信任边界 ⇒ 行照写、`checkpointId` 键缺席(决断方回显不了这道门,退回不带键的决断或从 run 结果取原值;行本身、门、待批调用身份照常)。",
+        note: "7.133.0(`checkpoint-identity.ts` 的 `durableRowIdentity`;两只店的 `listPending` + `/v1/assistant/inbox` handler):三处 durable 读面(运维队列行 `GET /v1/approvals` 与 `/v1/approvals/stream` 的 `pending` 帧;停驻收件 `GET /v1/assistant/inbox` 的行)读到一行停驻门**没有可用的 `checkpointId`** ⇒ 这一行**照列、`checkpointId` 键缺席**(消费方按「这一行没有可 join 的身份」处理)。detail = `face=<approvals-queue|assistant-inbox> why=<absent|untrusted>`:`absent` = 行上没有这一格(core 5.42.0 之前停驻的老行 —— core 明写不回填);`untrusted` = 在场却没过信任边界(非串 / 空串 / 超长 / 含 resume token —— 数据污染;没过边界的值不上 wire)。放行(列、键缺席)的最坏后果 = 消费方对这一行做不了跨面 join(三面对账少一行)—— 行本身、决断口(`/v1/approvals/:sessionId/decide`,按会话)、到期收割都照常。不放行有两种形:整只拒的代价是一行老 / 坏行打掉整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧);把这一行藏起来的代价更糟 —— 人看不到要批的东西(审批面上的 fail-open,方向反了)。故 F 类;必须留痕(两种成因从此可分)。计数非零 = 有老 / 坏行在飞(列着、没身份);`/stream` 每 3s 一拍重读,同一行每拍计一次(量值 = 行 × 拍数,在场才是信号)。 7.137.0 起第四面:park 账本行(`GET /v1/runs/:id/events` 的 `suspended` / `needs_review`;唯一构造器 `trace/project.ts` 的 `parkEventData`,写时判一次,detail `face=run-events-park`)—— 暂停因由上的门身份没过信任边界 ⇒ 行照写、`checkpointId` 键缺席(决断方回显不了这道门,退回不带键的决断或从 run 结果取原值;行本身、门、待批调用身份照常)。 第五面:回决门族的 200 体(`/decide` / `/resume` / `/plan_review` 执行之前从选中的那一行捕获一次,`http/resume-legs.ts` 三处;detail `face=decision-receipt`)—— 选中那一行的门身份没过信任边界 ⇒ 结清证据照铸、体上 `checkpointId` 键缺席(决断方只是对不上身份;位、决定、续跑都照常)。每次走到捕获点的决断计一次(计的是选中那一行的事实,与这次决断随后走哪条车道无关)。",
     },
     "server.approvals.queue-row-gate-kind-missing": {
         cls: "F",
@@ -260,6 +260,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-690(`instruction-source-notice.ts announceInstructionSource`,项目指令换源通告的唯一铸点;detail 的 `op` 点名哪一步):基线**读**失败或超期(会话店抖动 / 列形坏 / 2s 期限到,detail 带 `timeout=`)⇒ 本 run 不比也不写;基线**写**失败或超期 ⇒ 本 run 的换源帧照发(它对本 run 为真),下一 run 可能再说一遍同一次换源(超期后才落地的写由 CAS 挡住,盖不掉更新的基线);通告**出口**抛 ⇒ 本 run 缺这一帧。放行的最坏后果 = 一次换源没被说出来或被多说一次 —— 通告是**披露**面,不参与任何门 / 裁决,模型读到的指令本身不受影响。不放行的代价严重不对称:铸点跑在 core 的 `loadProjectMemory` 席内,抛回去 core 会把这次 prepare 的项目记忆整块丢掉(不注入),为一条通告赔上指令本身。计数让「某台部署的会话店一直读不出基线」与「这台部署从来没换过源」在遥测上分得开。",
     },
+    "server.session-workspace.record-degraded": {
+        cls: "F",
+        note: "会话行的位置与项目那一格(`session_meta.workspace` / local `session-workspaces.json`;唯一写者 `session-workspace.ts` 的腿记录座,唯一列属主 `plugins/session-workspace-cell.ts`;detail 的 `op` 点名哪一步):`op=write` 一次写失败(库抖 / 盘满 / 锁等待超时)⇒ 行停在上一帧,下一帧照写;`op=read` 一格读不出(被带外改坏)⇒ 读作没有记录,下一帧整格重写;`op=frame` 一帧投不成存储形(引擎不会铸出这种帧)⇒ 这一帧不记。这一格是宿主对**引擎判过的答案**的记录,不是判据 —— 引擎每条腿都重判项目(有记号就判记号,声明不等响亮拒)。放行的最坏后果 = 这只会话的下一条不带 `projectId` 的提交续声明的是旧的项目或不声明(没有记号的检出里这只会话少一次续声明);不放行的代价是把一条在跑的腿、或这只会话往后的每一次提交,为一份记录摔掉。计数非零 = 这台部署的会话店写不动 / 有人改过库。",
+    },
     "server.engine-notice.wire-sink-threw": {
         cls: "F",
         note: "#310:`engine_notice` 分流器把一条白名单通告投给某条 run 腿的登记口时,那只口抛了(live 口写向已断/已撕裂的 SSE socket,或 durable 口的账本写同步抛)。放行的最坏后果 = **这一条通告的这一个终点**缺席:①日志终点在分流之前已经逐字打过(事实一条不丢);②两个终点注册成两只独立 sink ⇒ live 抛不牵连 durable(断连后仍看得见的那半保住);③同会话其余口照投。故 F 类。不放行的代价是把异常回抛给 core 的 `deliverEngineNotice` —— 它会吞掉,于是同一次失败**既没有留痕也没有第二只口**,正是本 tag 要根除的形。留痕是承重的:静默吞掉之后「wire 腿为什么总有几条通告不到」在遥测里与「core 本来就没发」同形。",

package/dist/observability/secret-env-scrub.d.ts

@@ -62,7 +62,7 @@ export declare const SECRET_ENV_SCRUB_SITES: {
         readonly remedy: null;
     };
     readonly "server.hooks.spawn-env": {
-        readonly note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎组合,名单外一律不交;请求显式给的 `settings.env` 另叠在上面";
+        readonly note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎的 `hostChildEnv` 组合:名单外一律不交,本服务自有凭据任何情况都不交;请求的有效环境层(`settings.env`)作授予叠在上面;请求给工具 shell 的继承词对它不作用";
         readonly remedy: null;
     };
     readonly "server.project-memory.git-subprocess": {