@sema-agent/server 7.147.0 → 7.149.0

package/dist/local-store-declaration.js

@@ -0,0 +1,59 @@
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
+import { SESSION_DURABILITY } from "./plugins/session-placement.js";
+export const LOCAL_STORE_DECLARATION_WORDS = ["ephemeral"];
+export const LOCAL_STORE_DECLARATION_RULES = ["declared_ephemeral", "callers_own_volatile_disk", "store_design"];
+export function engineDurabilityOfDeclarationRule(rule) {
+    switch (rule) {
+        case "declared_ephemeral":
+        case "callers_own_volatile_disk":
+            return "process-local";
+        case "store_design":
+            return SESSION_DURABILITY;
+        default: {
+            const unhandled = rule;
+            throw new Error(`store posture: no ruling for local store declaration rule ${String(unhandled)}`);
+        }
+    }
+}
+export function localStoreDeclarationOf(deployment, dataRootMedium) {
+    const of = (rule) => ({ rule, durability: engineDurabilityOfDeclarationRule(rule) });
+    const word = deployment.localStoreDurability;
+    switch (word) {
+        case "ephemeral":
+            return of("declared_ephemeral");
+        case undefined:
+            if (dataRootMedium === "ephemeral" && DEPLOYMENT_SHAPE_PREDICATES.callerOwnsWorkerDisk.holds(deployment))
+                return of("callers_own_volatile_disk");
+            return of("store_design");
+        default: {
+            const unhandled = word;
+            throw new Error(`unhandled LOCAL_STORE_DURABILITY word ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+export function describeLocalStoreDeclaration(d) {
+    switch (d.rule) {
+        case "declared_ephemeral":
+            return "the operator declared LOCAL_STORE_DURABILITY=ephemeral";
+        case "callers_own_volatile_disk":
+            return "the store sits on the caller's own disk (host execution lane, single owner), and that disk does not survive a container / Pod replacement";
+        case "store_design":
+            return "the local file store's own declaration";
+        default: {
+            const unhandled = d.rule;
+            throw new Error(`store posture: no wording for local store declaration rule ${String(unhandled)}`);
+        }
+    }
+}
+export function parseLocalStoreDurabilityWord(raw) {
+    const w = raw?.trim() ?? "";
+    if (w === "")
+        return undefined;
+    const word = LOCAL_STORE_DECLARATION_WORDS.find((x) => x === w);
+    if (word !== undefined)
+        return word;
+    throw new Error(`LOCAL_STORE_DURABILITY=${JSON.stringify(raw)} is not a recognized declaration — the only word is ${LOCAL_STORE_DECLARATION_WORDS.map((x) => `"${x}"`).join(", ")} ` +
+        `(the local store declares itself process-local: sessions, parked approvals and memory do not survive a container / Pod replacement). ` +
+        `Leave it unset for the store's own durable declaration. Refusing to boot rather than reading a declaration nobody can read as either one.`);
+}
+//# sourceMappingURL=local-store-declaration.js.map

package/dist/lsp-evict.d.ts

@@ -8,9 +8,11 @@
  * while the dir is rm'd (rooted there, it just sees ENOENT). Only the ephemeral lane is wrapped by the caller — the
  * caller-cwd (deployment-shape row `callerCwd`) persistent-project path keeps its warm server (stable root, reused across turns = CC-parity, no leak).
  *
- * Structural param types (no `ExecutionEnv`/`NodeLspManager` import): a non-evicting manager (e2b/k8s bridge) or an
- * env without a string `cwd` / callable `destroy` is returned UNWRAPPED (probe-guarded), so this is a safe no-op
- * everywhere the precondition doesn't hold.
+ * The manager is the one the mint point `createLspManager` returns (core `NodeLspManager`), typed by the one method used
+ * (`Pick<NodeLspManager, "evict">`: the class has private members, so a structural test stub could not stand in for the
+ * whole class type). The env stays structural: an env without a string `cwd` / callable `destroy` is returned UNWRAPPED
+ * (probe-guarded), so this is a safe no-op wherever that precondition doesn't hold.
  */
-export declare function evictLspOnDestroy<E extends object>(env: E, lsp: unknown): E;
+import type { NodeLspManager } from "@sema-agent/core";
+export declare function evictLspOnDestroy<E extends object>(env: E, lsp: Pick<NodeLspManager, "evict">): E;
 //# sourceMappingURL=lsp-evict.d.ts.map

package/dist/lsp-evict.js

@@ -1,12 +1,11 @@
 export function evictLspOnDestroy(env, lsp) {
-    const evict = lsp?.evict;
     const e = env;
-    if (typeof evict !== "function" || typeof e.cwd !== "string" || typeof e.destroy !== "function")
+    if (typeof e.cwd !== "string" || typeof e.destroy !== "function")
         return env;
     const origDestroy = e.destroy.bind(e);
     const root = e.cwd;
     e.destroy = () => {
-        void evict.call(lsp, root).catch(() => { });
+        void lsp.evict(root).catch(() => { });
         return origDestroy();
     };
     return env;

package/dist/mcp-assertion-header.d.ts

@@ -5,7 +5,7 @@
  * 请求面条目的形 = 契约包的请求传输形({@link RequestMcpServerSpec}:stdio 带 `env`、http 带 `headers` / `principalHeader` / `assertionHeader`),wire 上的形由它说。
  * 交给引擎的声明不带件值:引擎的声明收据对带 `headers` / `env` 的声明整条拒,件由部署的对端座在发送时作答。所以每条条目按它那一臂的处置表
  * ({@link MCP_STDIO_TRANSPORT_DISPOSITION} / {@link MCP_HTTP_TRANSPORT_DISPOSITION})拆成草稿:`env` / `headers` 进草稿的件,`assertionHeader` 承载不发送,其余进声明。
- * 拆法只有 `plain-string-record.ts` 的 `splitDeclaration` 一只、键的去处只有表一处说;两张表各带三道编译格(请求臂加 / 减键、引擎臂加键、引擎臂删键都编译红)。
+ * 拆法只有 `request-declaration-disposition.ts` 的 `splitDeclaration` 一只、键的去处只有表一处说;两张表各带三道编译格(请求臂加 / 减键、引擎臂加键、引擎臂删键都编译红)。
  * 草稿只有胜出者(部署同名者赢,`task-mcp.ts` 的 `mergeRequestMcp`)才经对端座的唯一铸点(`peer-seat.ts` 的 `mintDeclaration`)登记,登记换来的引用放进声明的传输臂。
  *
  * ## `assertionHeader`:一条律,一个键一种读法

package/dist/mcp-assertion-header.js

@@ -1,4 +1,4 @@
-import { splitDeclaration } from "./plain-string-record.js";
+import { splitDeclaration } from "./request-declaration-disposition.js";
 export const MCP_STDIO_TRANSPORT_DISPOSITION = { args: "engine", command: "engine", env: "seat", kind: "engine" };
 export const MCP_HTTP_TRANSPORT_DISPOSITION = { assertionHeader: "withheld", headers: "seat", kind: "engine", principalHeader: "engine", url: "engine" };
 const MCP_REQUEST_TRANSPORT_ARMS = {

package/dist/memory-operator-faces.d.ts

@@ -178,9 +178,9 @@ export interface MemoryOriginFaces {
         origin: MemoryEntryOrigin;
         provenance: EntryProvenanceAccount;
     }>>;
-    /** §13-4② 读半场:清标审计账(**同步** —— core 的 `listOriginClearances` 就是一次严格 sidecar 读;
-     *  账本损坏 ⇒ `ControlPlaneCorruptError`,fail-closed,绝不回半张表)。 */
-    listClearances: (at?: MemoryLayerSeat) => OriginClearanceRow[];
+    /** §13-4② 读半场:清标审计账(**异步** —— core 7.66.0 [ref] 起 `listOriginClearances` 经引擎的治理店读那份账(`Promise`;
+     *  File 后端 = 同一份控制面文件、同字节);账本损坏 ⇒ `ControlPlaneCorruptError`,fail-closed,绝不回半张表)。 */
+    listClearances: (at?: MemoryLayerSeat) => Promise<OriginClearanceRow[]>;
     /** §13-4② 写半场:审计化的 UN-MARK 阀门。拒因族是 core 的**闭集码**,本层零翻译原样上抛。 */
     clear: (entryId: string, input: {
         requestId: string;
@@ -199,7 +199,8 @@ export interface MemoryOriginFaces {
  * ## 控制面归属:判据与合规两口**逐字同一条**(§1 F-9 裁),但理由更硬
  *
  * 亲读 core 5.59.0(不信 JSDoc,读 `engine.js` 实装):
- *  · `listOriginClearances` = `readOriginClearances(this.controlDir)`;
+ *  · `listOriginClearances` = `readOriginClearances(this.controlDir)`(core 7.66.0 [ref] 起经引擎的治理店 `this.governanceStore` 读,答 `Promise`;
+ *    本族只挂在自带控制面的 File 后端上,那只店就是同一控制面上的 File 店 —— 同目录、同名、同字节);
  *  · `clearEntryOrigin` 整条弧都压在 `this.controlDir` 上 —— 写前开行(`openOriginClearance`)、
  *    墓碑落定登记(`markOriginClearanceTombstoned`)、终态事件(`settleOriginClearance`);
  *  · `listExternalOriginEntries` 每一行都要 `provenanceOf`,而它读 `challengedEntryIds` /

package/dist/memory-operator-faces.js

@@ -80,7 +80,7 @@ export function createMemoryOriginFaces(stores, opts) {
     });
     return {
         listExternal: async (scopes) => engineOf(memoryStoreForRequest(stores, scopes)).listExternalOriginEntries(scopes),
-        listClearances: (at) => engineOf(memoryStoreForRequest(stores, seatLayers(at))).listOriginClearances(),
+        listClearances: async (at) => engineOf(memoryStoreForRequest(stores, seatLayers(at))).listOriginClearances(),
         clear: async (entryId, input, at) => engineOf(memoryStoreForRequest(stores, seatLayers(at))).clearEntryOrigin(entryId, input),
     };
 }

package/dist/memory-project-layer.js

@@ -29,7 +29,7 @@ export function createMemoryProjectLayers(deps) {
     };
     return {
         async prepare(config, scope, taskRoot) {
-            const layer = memoryProjectLayerFor(config, scope, taskRoot);
+            const layer = await memoryProjectLayerFor(config, scope, taskRoot);
             const current = layer?.key.scope;
             if (layer === undefined || current === undefined)
                 return layer?.key;

package/dist/memory-scope.d.ts

@@ -1,6 +1,7 @@
 import { FileMemoryEngineBackend, type TaskSpec } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import { type ExecutionLane } from "./execution-lane-caps.js";
+import type { Logger } from "./observability/logger.js";
 import { type MemoryProjectKey, type ProjectLayerOfTask } from "./project-identity.js";
 /** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
 export declare const V2_SCOPE_PREFIXES: readonly string[];
@@ -61,8 +62,8 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  * 读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,
  * core 铸 operator 通知 `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
  *
- * 🔴 [ref] 键形:项目层 = **全局层的属主 × 项目身份**,`userrepo:<属主段>/<档>.<摘要>`(文法 `project-layer-key.ts`,身份 `project-identity.ts`);
- * 属主 = `projectLayerOwnerOf(scope)`。
+ * 🔴 [ref] 键形:项目层 = **全局层的属主 × 项目身份**,`userrepo:<属主段>/<档>.<摘要>`(文法 `project-layer-key.ts`,身份 `project-identity.ts`
+ * —— 检出带 `.sema/project` 记号 ⇒ 记号档,读法与引擎判官同一只;没有记号 ⇒ git 根回落);属主 = `projectLayerOwnerOf(scope)`。
  *
  * 🔴 **写家只落复制路径覆盖得到的层**(7.98.0 合并复审 F1,主会话裁「统一规则,不做特判」):写家 = 读列表里、本部署
  * **每一条已配置的复制路径都覆盖到**的最具体的一层。项目层不在覆盖面里 ⇒ 本任务**不按项目键控**,写家落全局层 —— 否则开了
@@ -76,9 +77,9 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  *  · 记忆面暗(`scope` 缺席)—— 没有 spec 可铸,也就不读盘;
  *  · 本任务的项目层不在复制覆盖面里(见上)—— 让位给全局层。
  */
-export declare function memoryProjectKeyFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): MemoryProjectKey | undefined;
+export declare function memoryProjectKeyFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): Promise<MemoryProjectKey | undefined>;
 /** {@link memoryProjectKeyFor} 的同一条规则,带上本 checkout 要折进当前层的旧层(`memory-project-layer.ts` 读它)。 */
-export declare function memoryProjectLayerFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): ProjectLayerOfTask | undefined;
+export declare function memoryProjectLayerFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): Promise<ProjectLayerOfTask | undefined>;
 /**
  * 本部署记忆的**复制覆盖面** —— 唯一属主(7.98.0 合并复审 F1)。「复制路径」= 把某一层记忆搬出本机的腿;今天只有一条:
  * TOC 同步客户端腿(`MEMORY_SYNC_*`,`memory-sync-client.ts`)。🔴 [ref]:一条复制路径复制**它那一层**(`config.memorySync.scope`)
@@ -177,17 +178,26 @@ export declare function fileMemoryEngineRoot(config: Pick<ServiceConfig, "memory
  * 一条路径的**规范形**(给 {@link judgeMemoryRootOutsideDataRoot} 的 `canonical` 座用的生产实现):
  *  · 既存的绝对路径 ⇒ **原样**交给 `realpath`(`.native`:大小写不敏感的文件系统上返回盘上的拼写;符号链接、macOS 的 `/var` → `/private/var` 在这一步展平)。
  *    不先在字串上折 `..`:操作系统在展开符号链接**之后**才折 `..`,`/link/..` 的真身是链接目标的父目录,字串折叠会把它读成 `/`;
- *  · 其余(尚不存在 / 相对)⇒ 绝对化并折叠 → 取**最深既存祖先**的 `realpath` → 接回尚不存在的尾巴(尾巴只做字串规范化)。
+ *  · 其余(尚不存在 / 相对)⇒ 绝对化(**不折叠**)后逐段走:既存的前缀每进一段取一次 `realpath`(符号链接在这一步展开),`..` 折在**已展开**的前缀上 ——
+ *    与操作系统同序(`/别名/../新目录` 的真身在链接目标的父目录下;先在字串上折会读成别名的父目录,判到另一只挂载上);第一段不存在起,余下是尚不存在的尾巴
+ *    (尾巴只做字串规范化,与 `mkdir -p` 建出来的同形)。
  *
  * 为什么按「最深既存祖先」而不是直接 `realpath(p)`:boot 期记忆根常常还没建出来(新数据根),`realpath` 对不存在的路径抛 ENOENT,
  * 而数据根那一侧已经存在、会被展平 —— 两侧拼写空间不一样,同一个目录会被读成「不在其下」。祖先用 `existsSync` 找(它对 ENOENT / ENOTDIR / EACCES / ELOOP
  * 一律答 `false`,不抛),所以走到的那一级一定 stat 得动;`realpath` 仍可能在「探完到取值之间目录被挪走 / 搜索权限被收」的竞态里抛 ——
  * 不在本函数里吞(吞了就是一条无声的降级臂),由 boot 调用点接住并响亮报一行(`memory_engine_dir_check_unavailable`),起服照常。
  *
- * 取舍:尾巴(不存在的那几段)只比规范化字串,**不折大小写**,`..` 也按字串折:两个只差大小写、且都还不存在的拼写在大小写不敏感的盘上会被读成两处 ——
+ * 取舍:尾巴(不存在的那几段)只比规范化字串,**不折大小写**,尾巴里的 `..` 按字串折:两个只差大小写、且都还不存在的拼写在大小写不敏感的盘上会被读成两处 ——
  * 方向是多报一条 warn(这条判据的失败方向),不会漏报。
  */
 export declare function canonicalPathOf(p: string): string;
+/**
+ * **路径包含**(含相等)的判官:`child` 是不是 `root` 本身或它的后代 —— `path.relative(canonical(root), canonical(child))` 不是 `..`、不以 `..` 加分隔符起头、也不是绝对路径(跨盘符)。
+ * `..` 要按**整段**判:名为 `..data` 的子目录在其下;`startsWith("..")` 会把它读成在其外。`canonical` 座缺省 `path.resolve`(字串规范形),boot 递 {@link canonicalPathOf} 取符号链接展平后的形;
+ * 两侧同一只座(先 root、后 child)。读者两处:记忆根「在数据根之外」那一判({@link judgeMemoryRootOutsideDataRoot})与起服时「配置根是不是工作区的祖先」那一判(`sema-config-dir.ts`);
+ * 树里别处内联的同形表达式(`boot/deployment-mods.ts` · `plugins/local-data-dir-modes-m39.ts` · `plugins/remote-env-host.ts` · `plugins/worktree-isolation.ts`)不在本次收口范围。
+ */
+export declare function pathIsWithin(root: string, child: string, canonical?: (p: string) => string): boolean;
 /** {@link judgeMemoryRootOutsideDataRoot} 的读数:记忆引擎的根落在本机数据根**之外**。三键即 boot 日志行的字段(`hint` 是一句带两条真路径的人话)。 */
 export type MemoryRootOutsideDataRoot = {
     readonly root: string;
@@ -273,6 +283,23 @@ onIncident?: (err: Error & {
     backend: FileMemoryEngineBackend;
     root: string;
 } | undefined;
+/**
+ * **起服期读 file 记忆控制面账本的形:一行 warn,不拒启**([ref])。
+ *
+ * 病:core >= 7.64.0 的 File 记忆店不再升级「绑定之前」的旧形账本(裸 id → rev 映射)—— 构造器既不碰盘也不抛,读账本的那一刻才抛
+ * `ControlPlaneCorruptError`,本仓的记忆面把它答成 `500 internal.memory_control_plane_corrupt`(`http/memory-face-fault-reply.ts`)。
+ * 于是升级前账本还是旧形(或任何引擎拒的形)的 file 记忆部署,升级后**起服一切正常、第一次读账本的记忆面才 500**,起服日志里零提示。
+ *
+ * 读法:只经 core 导出读口 `readMemoryLedgerForm`(只读、不升级、不加锁、不建文件)问「账本是什么形」—— 本仓不自读账本文件、不认它的文件名
+ * (一件事一个读者)。答词是闭集三个,穷尽 `switch`。位置 = 构造 file 后端之前:boot 与 run-local 两个宿主各在 {@link memoryEngineBackendFor} 前调一次;
+ * 坐标取 {@link fileMemoryPlaneFor} 单铸点,与那只工厂同门(工厂不接线的部署形 —— 多租户 / `MEMORY_ENGINE=off` / 平面分裂车道未 allow —— 这里也不读)。
+ *
+ * 失败方向:**披露面,不拒启**(不是安全轴;拒启要新码、另票):
+ *  · `malformed` ⇒ 一行 warn `memory_ledger_malformed`(`root` 数据根 · `controlDir` 控制面目录 · `hint` 一句带出路的话);`v2` / `absent` ⇒ 零输出;
+ *  · 读口自己抛(账本路径是目录 / 无权读 / 环路:引擎答「没有形」,既不是 `absent` 也不是 `malformed`)⇒ 另报一行 `memory_ledger_check_unavailable`
+ *    (类名 + 机器码,不带消息原文,与 `memory_engine_dir_check_unavailable` 同形),照常起服,不编一个形。
+ */
+export declare function announceMemoryLedgerForm(config: ServiceConfig, fallbackRoot: string | undefined, log: Logger): Promise<void>;
 /**
  * core 7.49.0 [ref] —— **记忆店根搬动 ⇒ 拒启**(不降级)。店根的物理路径是控制面里的一条记录(`root-anchor.json`),每次打开都比对;
  * 目录被搬走 / 换成指向别处的链接之后,File 后端的**构造器**就抛 `memory.target_outside_store`(`detail` 恰在这一形上带

package/dist/memory-scope.js

@@ -1,7 +1,8 @@
 import { existsSync, realpathSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { FileMemoryEngineBackend, readMemoryLedgerForm, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
 import { capabilitiesFor, executionLaneOf } from "./execution-lane-caps.js";
+import { errorCodeOf, errorKindOf } from "./observability/err-text.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 import { projectLayerForTaskRoot } from "./project-identity.js";
 import { parseProjectLayerKey, projectLayerOwnerOf } from "./project-layer-key.js";
@@ -33,13 +34,13 @@ export function memoryScopeFor(config, principal, projectId) {
     }
     return config.memoryScope;
 }
-export function memoryProjectKeyFor(config, scope, taskRoot) {
-    return memoryProjectLayerFor(config, scope, taskRoot)?.key;
+export async function memoryProjectKeyFor(config, scope, taskRoot) {
+    return (await memoryProjectLayerFor(config, scope, taskRoot))?.key;
 }
-export function memoryProjectLayerFor(config, scope, taskRoot) {
+export async function memoryProjectLayerFor(config, scope, taskRoot) {
     if (config.requirePrincipal === true || scope === undefined)
         return undefined;
-    const layer = projectLayerForTaskRoot(taskRoot, projectLayerOwnerOf(scope));
+    const layer = await projectLayerForTaskRoot(taskRoot, projectLayerOwnerOf(scope));
     if (layer.key.scope !== undefined && !replicationCovers(memoryReplicationCoverage(config), layer.key.scope))
         return undefined;
     return layer;
@@ -113,25 +114,40 @@ export function fileMemoryEngineRoot(config, fallbackRoot) {
 export function canonicalPathOf(p) {
     if (isAbsolute(p) && existsSync(p))
         return realpathSync.native(p);
-    const abs = resolve(p);
-    let existing = abs;
+    const abs = isAbsolute(p) ? p : `${process.cwd()}${sep}${p}`;
+    const { root } = parse(abs);
+    let existing = root;
     const tail = [];
-    while (!existsSync(existing)) {
-        const parent = dirname(existing);
-        if (parent === existing)
-            return abs;
-        tail.unshift(basename(existing));
-        existing = parent;
+    for (const seg of abs.slice(root.length).split(sep === "\\" ? /[\\/]+/ : /\/+/)) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (tail.length > 0) {
+            if (seg === "..")
+                tail.pop();
+            else
+                tail.push(seg);
+            continue;
+        }
+        if (seg === "..") {
+            existing = dirname(existing);
+            continue;
+        }
+        const next = join(existing, seg);
+        if (existsSync(next))
+            existing = realpathSync.native(next);
+        else
+            tail.push(seg);
     }
-    return join(realpathSync.native(existing), ...tail);
+    return join(existing, ...tail);
+}
+export function pathIsWithin(root, child, canonical = resolve) {
+    const rel = relative(canonical(root), canonical(child));
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
 export function judgeMemoryRootOutsideDataRoot(a) {
     if (!a.dataRoot)
         return undefined;
-    const canonical = a.canonical ?? resolve;
-    const rel = relative(canonical(a.dataRoot), canonical(a.memoryRoot));
-    const inside = rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
-    if (inside)
+    if (pathIsWithin(a.dataRoot, a.memoryRoot, a.canonical))
         return undefined;
     return {
         root: a.memoryRoot,
@@ -171,6 +187,39 @@ export function memoryEngineBackendFor(config, fallbackRoot, onIncident) {
     }
     return { backend, root: plane.root };
 }
+const MEMORY_LEDGER_MIGRATION_EXIT = "先用上一版引擎开一次再升级";
+export async function announceMemoryLedgerForm(config, fallbackRoot, log) {
+    const plane = fileMemoryPlaneFor(config, fallbackRoot);
+    if (plane === undefined)
+        return;
+    const where = { root: plane.root, controlDir: plane.controlDir };
+    let form;
+    try {
+        form = await readMemoryLedgerForm(plane.controlDir);
+    }
+    catch (err) {
+        log.warn("memory_ledger_check_unavailable", { ...where, errorKind: errorKindOf(err), errorCode: errorCodeOf(err) });
+        return;
+    }
+    switch (form) {
+        case "v2":
+        case "absent":
+            return;
+        case "malformed":
+            log.warn("memory_ledger_malformed", {
+                ...where,
+                hint: `the memory control plane at ${plane.controlDir} holds a committed-rev ledger this engine refuses to read — the memory faces that read it answer ` +
+                    `500 internal.memory_control_plane_corrupt (the server itself starts regardless). If it is the pre-binding v1 form (a bare id → rev map, no longer ` +
+                    `upgraded on open), the exit is, from MIGRATION.md: 「${MEMORY_LEDGER_MIGRATION_EXIT}」`,
+            });
+            return;
+        default: {
+            const unknownForm = form;
+            log.warn("memory_ledger_check_unavailable", { ...where, errorKind: `UnknownLedgerForm:${String(unknownForm)}` });
+            return;
+        }
+    }
+}
 export function memoryStoreRootMovedRefusal(e) {
     const err = e;
     const d = err?.detail;

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

@@ -1,5 +1,5 @@
 /**
- * **店形拒**(store-form refusal)在本仓的唯一读法属主(纯叶:零 http / 零 boot 依赖)—— core 店形拒**一族**(族表 `STORE_FORM_REFUSAL_CODES`,引擎 7.65.0 起三码;
+ * **店形拒**(store-form refusal)在本仓的唯一读法属主(纯叶:零 http / 零 boot 依赖)—— core 店形拒**一族**(族表 `STORE_FORM_REFUSAL_CODES`,引擎 7.66.0 起四码;
  * 本仓按族读,下面点名的成员只是举例与历史,不是判据):
  *  · `memory.target_outside_store`(core 7.31.1 [ref]):记忆 store 里的一个目录经软链通到了 store **外**(或 store 根在 backend 打开 / 引擎首次
  *    挂载之后被改指)⇒ 引擎对落点在外的删 / 写 / 重放 / 自身写一律**不做**;
@@ -7,7 +7,10 @@
  *    (`detail.form` ∈ `symlink` | `file` | `other`,`lstat` 判、不跟链)。修前 core 对这一形抛不带码的 `ControlPlaneCorruptError`(与真控制面损坏同类同形),
  *    平铺布局(条目直接住在 home 里)于是答 500,而同一换法在嵌套布局下一层答 409 —— 现在两布局同答这一码;
  *  · `memory.control_plane_links_unsupported`(core 7.65.0):记忆控制面所在的文件系统不能建硬链接 ⇒ File 记忆店在打开处被拒(构造期抛 ⇒ 起服拒;
- *    引擎 mount 时开它自己的店被拒 ⇒ Runner 记忆相 fail-open,这一跑 memoryless,见 `memory-incident-sink.ts`)。
+ *    引擎 mount 时开它自己的店被拒 ⇒ Runner 记忆相 fail-open,这一跑 memoryless,见 `memory-incident-sink.ts`);
+ *  · `memory.control_plane_strays`(core 7.66.0 [ref] HB-5):后端自带治理店(不是引擎控制面上那只 File 店),而控制面里还留着旧的治理文档 /
+ *    控制对象 ⇒ 引擎构造期拒、一个字节不写(句子点名 `adoptReplicaControlPlane`)。本服务三种后端都构造不出这一形(File 后端钉住自己的控制面、
+ *    治理店就是那只;SQL 两只不带治理店 ⇒ 引擎用控制面上的 File 店)—— 按族入族,零专门臂。
  * 族里各码的形相同:普通 `Error` + `.code` + `.detail`(`{ path }`;home 那一码多 `form`),**句子以码领头、不含任何宿主路径**(core 7.44.0 起,
  * 路径只在 `detail.path`)。core 的读法:operator 要处置的盘形(去掉那只链 / 放回真目录),**不是**可重试的 IO 故障,也**不是**对调用方的裁决;
  * 盘形修好之前重发恒拒。本仓据此一条规则:族内同答、409、码原样;路径只进运维行(HTTP 映射一处,见 `http/memory-store-refusal-reply.ts`)。

package/dist/memory-sync-client.d.ts

@@ -25,8 +25,9 @@ export declare function buildMemorySyncEnabledFields(peer: string, scope: string
 };
 /**
  * fetch transport(core `MemorySyncTransport` 的部署实现)。`peer` = {@link memorySyncPeerOf}(`url`)(建时铸一次;拒的地址在这里抛,一个请求都不发),
- * `post` 打 `${peer}${path}`(core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedPrincipal 的 verified-principal 门对齐)。
- * 非 2xx throw(status + body 前 200 字节——中心 4xx/5xx 的 typed error body 就是最好的诊断线索);2xx 返回解码后的 JSON(形状校验在 core
+ * `post` 打 `${peer}${path}`(core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedSubject 的 verified-principal 门对齐)。
+ * 非 2xx throw(status + 体长 —— 体的字节不进报错句,与配置中心拉取同一条律:摘录在座前切会把跨界的令牌切成脱敏器认不出的前缀,座后切又会因前面的凭据被压短而
+ * 越过原来的源界、带出词表不认的形;对端是本服务的 `MEMORY_SYNC_SERVE`,拒因在对端自己的运维行);2xx 返回解码后的 JSON(解码经上游读口,不是 JSON ⇒ 句子只带体长;形状校验在 core
  * parseMemorySyncResponse,职责不重复)。`timeoutMs`(缺省 60s,AbortSignal.timeout)是活性保护:fire-and-forget 轮挂死会把 inflight 节流永久卡住
  * (undici 默认 headers 超时 300s 太钝)。
  */

package/dist/memory-sync-client.js

@@ -3,12 +3,14 @@ import { readFile, readdir, rename, rmdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { carriesCredential, ensureDir, syncMemoryScope, } from "@sema-agent/core";
 import { replicationCovers } from "./memory-scope.js";
-import { parseProjectLayerKey } from "./project-layer-key.js";
+import { compareProjectLayersForSync, parseProjectLayerKey } from "./project-layer-key.js";
 import { atomicWriteFileAsync } from "./plugins/owner-only-file-mode.js";
 import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
 import { buildMemorySyncIdentityBootRefusal, readMemorySyncIdentity } from "./memory-sync-identity.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
+import { createEgressFetch } from "./egress-redirect.js";
 import { errorText } from "./observability/err-text.js";
+import { buildBodyWithheldNote, parseUpstreamJson } from "./upstream-body.js";
 export function memorySyncPeerOf(url) {
     const r = readMemorySyncIdentity(url);
     if ("flaw" in r) {
@@ -22,7 +24,8 @@ export function buildMemorySyncEnabledFields(peer, scope, cursorPath) {
 }
 export function createMemorySyncTransport(opts) {
     const peer = memorySyncPeerOf(opts.url);
-    const fetchImpl = opts.fetchImpl ?? fetch;
+    const injected = opts.fetchImpl;
+    const fetchImpl = createEgressFetch("declare the final address as MEMORY_SYNC_URL", injected === undefined ? undefined : (input, init) => injected(typeof input === "string" ? input : input instanceof URL ? input.href : input.url, init ?? {}));
     const timeoutMs = opts.timeoutMs ?? 60_000;
     return Object.freeze({
         peer,
@@ -35,8 +38,8 @@ export function createMemorySyncTransport(opts) {
             });
             const text = await res.text();
             if (!res.ok)
-                throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
-            return JSON.parse(text);
+                throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${buildBodyWithheldNote(text)}`);
+            return parseUpstreamJson(text);
         },
     });
 }
@@ -269,7 +272,7 @@ export function createMemorySyncRunner(opts) {
             opts.log.warn("memory_sync_layer_enumeration_unsupported", { scope: opts.scope, reason: local.reason, note: "only the sync layer and tracked project layers are synced" });
         }
         const projectLayers = new Set([...(local.supported ? local.scopes : []), ...tracked].filter(isCoveredProjectLayer));
-        return [opts.scope, ...[...projectLayers].sort()];
+        return [opts.scope, ...[...projectLayers].sort(compareProjectLayersForSync)];
     };
     const syncLayer = async (scope, reason, calls) => {
         const cursorPath = memorySyncCursorPath(memoryEngineDir, scope);

package/dist/model-compat.d.ts

@@ -14,7 +14,7 @@
  * (`thinkingFormat: "qwen-chat-template"`),否则 auto 档每一轮都白烧一段思考。
  *
  * ## 对表全部**从 core 的型面铸**,本仓一个词都不枚举
- * `THINKING_LEVEL_TABLE` / `THINKING_FORMAT_TABLE` / `MAX_TOKENS_FIELD_TABLE` / `THINKING_MODE_TABLE` 都是 `Record<闭集词, true>`,
+ * `THINKING_TIER_TABLE` / `MODEL_THINKING_LEVEL_TABLE` / `THINKING_FORMAT_TABLE` / `MAX_TOKENS_FIELD_TABLE` / `THINKING_MODE_TABLE` 都是 `Record<闭集词, true>`,
  * `COMPAT_KEY_READERS` 是 `{ [A in 线路]: { [K in keyof Required<Model<A>["compat"]>]: 读器 } }` 的**映射型**(线路 = 契约 `ModelEntry.api` 的闭集):
  * core 加词/删词、加键/删键,或契约加一条线路,表当场 tsc 红(`MODEL_DEGRADE_ON` 的 `Set<DegradeReason>` 同款纪律)。
  * 映射型这一步是刻意的 —— 只钉「键集相等」会留下一个洞:core 加一键、有人把它补进白名单却忘了写读器,
@@ -32,7 +32,7 @@
  * 判形**整只判**(每条线路内):任一键不合 —— 含写了另一条线路的键 —— ⇒ 整只声明不收(和 `toolFaces` 每只工具「applied whole or not at all」
  * 同律)。留下好的那几键 = 让运维以为整条声明生效了,而实际发出去的请求是半张脸。
  */
-import type { Model } from "@sema-agent/core";
+import { type Model } from "@sema-agent/core";
 import type { ModelEntry } from "@sema-agent/settings-schema";
 /** 目录条目的线路闭集 = 契约 `ModelEntry.api`(契约加一条线路 ⇒ 读器表缺一行 ⇒ tsc 红)。 */
 export type CatalogApi = ModelEntry["api"];
@@ -42,13 +42,22 @@ export type CompatOf<A extends CatalogApi> = NonNullable<Model<A>["compat"]>;
 export type OpenAICompletionsCompat = CompatOf<"openai-completions">;
 /** core `AnthropicMessagesCompat`。 */
 export type AnthropicMessagesCompat = CompatOf<"anthropic-messages">;
-/** 六档思考梯(core `ThinkingLevel`)。`MODEL_DEFAULT_THINKING` / `MODEL_REASONING_EFFORT_LEVELS` /
- *  `compat.reasoningEffortLevels` 三处共用**这一张**表 —— [ref] 件⑤ 起就是「上游加一档而这里不补 ⇒
- *  编译红」的锁步姿势,本模块只是把它挪到了它真正的家(compat 的一个键)。 */
+/** 六档思考**梯**(core `ThinkingLevel`:一个端点吃得下哪几档的 effort 梯子)。型取自梯子座本身 —— `compat.reasoningEffortLevels`
+ *  (anthropic 线路的 `effortLevels` 同型)—— 而不是模型缺省档座:core 7.66.0 [ref] HB-1 起两座分家,缺省档多一档 `off`,梯子仍是六档
+ *  (`off` 永远不是梯子上的一级)。`MODEL_REASONING_EFFORT_LEVELS` / `compat.reasoningEffortLevels` / `compat.effortLevels` 共用**这一张**表;
+ *  上游加一档而这里不补 ⇒ 编译红([ref] 件⑤ 起的锁步姿势)。 */
+export type ThinkingTier = NonNullable<OpenAICompletionsCompat["reasoningEffortLevels"]>[number];
+/** 六档梯闭集(有序:低→高,取自上表的书写序),梯子两根旋钮的拒因文案与读器的单一真源。 */
+export declare const THINKING_LEVELS: readonly ThinkingTier[];
+export declare const isThinkingTier: (w: unknown) => w is ThinkingTier;
+/** 模型**缺省档**(core `ModelThinkingLevel` = `off` + 六档;`Model.defaultThinking` 的型):请求与角色都没点档时这只模型的请求走哪一档,
+ *  `off` = 缺省关(引擎发线路上的显式关),**不是**「没有缺省」—— 没有缺省 = 不铸键(core 7.66.0 [ref])。表 = 梯子六档 + `off`(展开同一张梯表,不写第二份);
+ *  core 给缺省档座加 / 删一词而这里不跟 ⇒ 编译红。 */
 export type ModelThinkingLevel = NonNullable<Model["defaultThinking"]>;
-/** 六档闭集(有序:低→高,取自上表的书写序),目录行 `enumValues` 与拒因文案的单一真源。 */
-export declare const THINKING_LEVELS: readonly ModelThinkingLevel[];
-export declare const isThinkingTier: (w: unknown) => w is ModelThinkingLevel;
+/** 七档缺省闭集(六档梯在前、`off` 在末,取自上表的书写序):`MODEL_DEFAULT_THINKING` 的目录 `enumValues` 与拒因文案的单一真源。 */
+export declare const MODEL_THINKING_LEVELS: readonly ModelThinkingLevel[];
+/** 七档判词 = core 包根的 `isThinkingLevel`(引擎自己判这七档的那一只;上表只留作有序列表与编译期锁步,不另写第二只判词)。 */
+export declare const isModelThinkingLevel: (w: unknown) => w is ModelThinkingLevel;
 /** `thinkingFormat` 七词闭集(core:openai / openrouter / deepseek / together / zai / qwen / qwen-chat-template)。 */
 export type ModelThinkingFormat = NonNullable<OpenAICompletionsCompat["thinkingFormat"]>;
 export declare const THINKING_FORMATS: readonly ModelThinkingFormat[];

package/dist/model-compat.js

@@ -1,6 +1,10 @@
-const THINKING_LEVEL_TABLE = { minimal: true, low: true, medium: true, high: true, xhigh: true, max: true };
-export const THINKING_LEVELS = Object.keys(THINKING_LEVEL_TABLE);
+import { isThinkingLevel } from "@sema-agent/core";
+const THINKING_TIER_TABLE = { minimal: true, low: true, medium: true, high: true, xhigh: true, max: true };
+export const THINKING_LEVELS = Object.keys(THINKING_TIER_TABLE);
 export const isThinkingTier = (w) => typeof w === "string" && THINKING_LEVELS.includes(w);
+const MODEL_THINKING_LEVEL_TABLE = { ...THINKING_TIER_TABLE, off: true };
+export const MODEL_THINKING_LEVELS = Object.keys(MODEL_THINKING_LEVEL_TABLE);
+export const isModelThinkingLevel = (w) => isThinkingLevel(w);
 const THINKING_FORMAT_TABLE = { openai: true, openrouter: true, deepseek: true, together: true, zai: true, qwen: true, "qwen-chat-template": true };
 export const THINKING_FORMATS = Object.keys(THINKING_FORMAT_TABLE);
 export const isThinkingFormat = (w) => typeof w === "string" && THINKING_FORMATS.includes(w);

package/dist/model-context-window.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A model's context window: ONE resolver, ONE spelling of the assumed number, ONE word for where the window came from.
+ *
+ * ## The rule
+ * A window is either **declared** — someone along the model's inheritance chain wrote a number: the catalog entry's `contextWindow`,
+ * the deployment's `MODEL_CONTEXT_WINDOW` (inherited by every catalog entry that writes none, BL-8), or `MODEL_CHEAP_CONTEXT_WINDOW`
+ * (the cheap slot; unset ⇒ it inherits the main slot's resolution) — or **assumed**: nobody along the chain wrote one, and this server
+ * fills {@link ASSUMED_CONTEXT_WINDOW}. {@link resolveContextWindow} is the only place that decides; it hands back the number AND its
+ * source as one value, and an inheriting reader passes the parent's resolution down whole — so the source travels with the number and
+ * no reader re-derives "was it declared?" on its own.
+ *
+ * Readers: the env leg (`config.ts`: main slot, cheap slot inheriting the main resolution), the center leg (`web-admin-client/apply-effective.ts`:
+ * entry → env main resolution), and the config catalog's default note (`config-catalog.ts`, which describes the assumed arm and so names the constant).
+ * The source is disclosed twice and read from the same per-model table both times (`ServiceConfig.contextWindowSources`): the `GET /v1/models`
+ * row key `contextWindowSource`, and the operator line {@link buildContextWindowAssumedNotice} (once per served model whose window is assumed; the one
+ * emitter is `context-window-notice.ts`, run after the served table settles).
+ *
+ * ## The assumed number
+ * A conservative guess, not a measurement: the engine needs a window to size its compaction trigger and the tool-schema defer
+ * threshold, and an undeclared window must never be read optimistically — so every model that reaches the engine carries SOME window,
+ * declared or this one. "Conservative" has one meaning here: the number is no larger than the smallest real window any model family in
+ * this stack's own deployments is known to declare, so an undeclared window errs toward "compaction and tool-schema deferral start
+ * earlier than the model needs", not toward "the model reaches its limit before compaction starts". It is ONE number, not a table keyed
+ * by model family — a per-family table would be a second source for the same fact. A model whose real window is larger declares it
+ * (catalog entry `contextWindow` / `MODEL_CONTEXT_WINDOW`); the disclosure above is how an operator / client learns which rows still
+ * ride on this number.
+ *
+ * Pure leaf: no imports.
+ */
+export declare const ASSUMED_CONTEXT_WINDOW = 131072;
+/** Where a model's window came from — closed set; consumers switch exhaustively. */
+export declare const CONTEXT_WINDOW_SOURCES: readonly ["declared", "assumed"];
+export type ContextWindowSource = (typeof CONTEXT_WINDOW_SOURCES)[number];
+/** A resolved window: the number the engine gets and where it came from (one value — never split across two reads). */
+export interface ResolvedContextWindow {
+    readonly window: number;
+    readonly source: ContextWindowSource;
+}
+/**
+ * The one resolver. `declared` = the number this level of the chain wrote (`undefined` = wrote none); `inherited` = the parent level's
+ * resolution (omitted at the root ⇒ the assumed arm). Declared ⇒ that number, `declared`; otherwise the parent's resolution unchanged —
+ * a catalog entry that writes no window under a deployment that declared `MODEL_CONTEXT_WINDOW` is declared, under one that did not it is assumed.
+ */
+export declare function resolveContextWindow(declared: number | undefined, inherited?: ResolvedContextWindow): ResolvedContextWindow;
+/**
+ * The operator line for one served model whose window is assumed (plain data; both legs emit this shape, the event name lives here only).
+ * `declareAt` names where the operator writes the number to make it declared (the env knob for an env slot, the catalog entry otherwise).
+ */
+export declare function buildContextWindowAssumedNotice(row: {
+    readonly model: string;
+    readonly window: number;
+    readonly declareAt: string;
+}): {
+    readonly event: "model_context_window_assumed";
+    readonly fields: Record<string, string>;
+};
+//# sourceMappingURL=model-context-window.d.ts.map

package/dist/model-context-window.js

@@ -0,0 +1,21 @@
+export const ASSUMED_CONTEXT_WINDOW = 131072;
+export const CONTEXT_WINDOW_SOURCES = ["declared", "assumed"];
+const ASSUMED = Object.freeze({ window: ASSUMED_CONTEXT_WINDOW, source: "assumed" });
+export function resolveContextWindow(declared, inherited = ASSUMED) {
+    return declared !== undefined ? { window: declared, source: "declared" } : inherited;
+}
+export function buildContextWindowAssumedNotice(row) {
+    return {
+        event: "model_context_window_assumed",
+        fields: {
+            model: row.model,
+            contextWindow: String(row.window),
+            declareAt: row.declareAt,
+            note: `no context window is declared for model "${row.model}" — this server assumes ${row.window} tokens (a conservative guess, not a measurement): ` +
+                `the engine sizes its compaction trigger on it, so a model whose real window is smaller reaches its limit before compaction starts, ` +
+                `and a model whose real window is larger compacts earlier than it needs to. ` +
+                `GET /v1/models marks this row contextWindowSource:"assumed". Declare the real window at ${row.declareAt} — said once per model.`,
+        },
+    };
+}
+//# sourceMappingURL=model-context-window.js.map