@sema-agent/server 7.131.0 → 7.133.0

package/dist/memory-project-layer.js

@@ -0,0 +1,46 @@
+import { migrateScope } from "@sema-agent/core";
+import { memoryProjectLayerFor } from "./memory-scope.js";
+export function createMemoryProjectLayers(deps) {
+    const fold = async (backend, from, to) => {
+        let report;
+        try {
+            report = await migrateScope(backend, from, to);
+        }
+        catch (err) {
+            deps.log.warn("memory_project_layer_fold_failed", { from, to, err: String(err), note: "entries stay where they are; the next task in this project retries" });
+            return;
+        }
+        if (report.moved > 0)
+            deps.log.info("memory_project_layer_folded", { from, to, moved: report.moved, cursorMoved: report.cursorMoved });
+        if (report.conflicts.length > 0) {
+            deps.log.warn("memory_project_layer_fold_conflicts", { from, to, conflicts: report.conflicts.length, note: "conflicting entries stay in the old layer; the next task in this project retries" });
+        }
+    };
+    const occupied = async (backend, sources) => {
+        const out = [];
+        for (const from of sources) {
+            if ((await backend.listHeaders([from])).some((h) => h.scope === from))
+                out.push(from);
+        }
+        return out;
+    };
+    return {
+        async prepare(config, scope, taskRoot) {
+            const layer = memoryProjectLayerFor(config, scope, taskRoot);
+            const current = layer?.key.scope;
+            if (layer === undefined || current === undefined)
+                return layer?.key;
+            const backend = deps.backend;
+            if (backend !== undefined && (await occupied(backend, layer.foldFrom)).length > 0) {
+                const foldAll = async () => {
+                    for (const from of await occupied(backend, layer.foldFrom))
+                        await fold(backend, from, current);
+                };
+                await (deps.syncRunner !== undefined ? deps.syncRunner.exclusive(foldAll) : foldAll());
+            }
+            deps.syncRunner?.track(current);
+            return layer.key;
+        },
+    };
+}
+//# sourceMappingURL=memory-project-layer.js.map

package/dist/memory-scope.d.ts

@@ -1,7 +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 MemoryProjectKey } from "./project-identity.js";
+import { type MemoryProjectKey, type ProjectLayerOfTask } from "./project-identity.js";
 /** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
 export declare const V2_SCOPE_PREFIXES: readonly string[];
 /**
@@ -41,17 +41,19 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  * S-512 / [ref] ① —— 这一请求的**项目身份声明**(`TaskSpec.memory.projectKey`)的唯一属主。
  *
  * **一条规则,与车道无关**(主会话 09-23 裁 ②):项目根 = spec 解析出的**真任务根**(`boot/resolve-spec.ts`
- * 的 `realTaskRootOf`,S-177 属主;run-local 腿 = 它的 `workspaceDir`)。本进程读得到这个根 ⇒ 求 canonical
- * 项目根并铸 `repo:` 键(in-process 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是
- * 「项目 = 任务根指向的地方」,不需要另一个词);读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、
- * spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,core 铸 operator 通知
- * `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
+ * 的 `realTaskRootOf`,S-177 属主;run-local 腿 = 它的 `workspaceDir`)。本进程读得到这个根 ⇒ 求项目身份并铸项目层键
+ * (in-process 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是「项目 = 任务根指向的地方」,不需要另一个词);
+ * 读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,
+ * core 铸 operator 通知 `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
+ *
+ * 🔴 S-640 键形:项目层 = **全局层的属主 × 项目身份**,`userrepo:<属主段>/<档>.<摘要>`(文法 `project-layer-key.ts`,身份 `project-identity.ts`);
+ * 属主 = `projectLayerOwnerOf(scope)`。
  *
  * 🔴 **写家只落复制路径覆盖得到的层**(7.98.0 合并复审 F1,主会话裁「统一规则,不做特判」):写家 = 读列表里、本部署
- * **每一条已配置的复制路径都覆盖到**的最具体的一层。项目层不在覆盖面里 ⇒ 本任务**不按项目键控**,写家落全局层,
- * 读列表与 7.97.0 同形 —— 否则开了 `MEMORY_SYNC_*` 的部署会把新记忆写进一个同步腿从不碰的层(静默不同步)。
- * 覆盖面只经 {@link memoryReplicationCoverage} 求(调用点零 `if (memorySync)`);以后项目层同步落地,只改覆盖面的
- * 来源,本规则不动。让位由启动通知 `memory_project_scope_yields_to_sync` 说出来(`config.ts` 记忆域,读同一只覆盖面)。
+ * **每一条已配置的复制路径都覆盖到**的最具体的一层。项目层不在覆盖面里 ⇒ 本任务**不按项目键控**,写家落全局层 —— 否则开了
+ * `MEMORY_SYNC_*` 的部署会把新记忆写进一个同步腿从不碰的层(静默不同步)。覆盖面只经 {@link memoryReplicationCoverage} 求(调用点零
+ * `if (memorySync)`);S-640 改的只是覆盖面的**来源**(一条复制路径复制它那一层与同属主的全部项目层),本规则一字不动。让位由启动通知
+ * `memory_project_scope_yields_to_sync` 说出来(`config.ts` 记忆域,读同一只覆盖面与 {@link replicatesProjectLayersOf})。
  * 缺席声明(`{ absent }`)不受覆盖面影响:它本来就写全局层,通知说的是「为什么没有项目层」。
  *
  * 返回 `undefined` 只有三形,都不是「忘了」:
@@ -60,20 +62,25 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  *  · 本任务的项目层不在复制覆盖面里(见上)—— 让位给全局层。
  */
 export declare function memoryProjectKeyFor(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): 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;
 /**
  * 本部署记忆的**复制覆盖面** —— 唯一属主(7.98.0 合并复审 F1)。「复制路径」= 把某一层记忆搬出本机的腿;今天只有一条:
- * TOC 同步客户端腿(`MEMORY_SYNC_*`,`memory-sync-client.ts`),它只同步**一层**(`config.memorySync.scope`,core
- * `syncMemoryScope` 按 `scope ===` 取条目)。没有复制路径 ⇒ `unreplicated`(没有哪一层会被复制落下)。
+ * TOC 同步客户端腿(`MEMORY_SYNC_*`,`memory-sync-client.ts`)。🔴 S-640:一条复制路径复制**它那一层**(`config.memorySync.scope`)
+ * **以及同一属主的全部项目层**(`userrepo:<属主>/…`,属主 = `projectLayerOwnerOf(那一层)`)—— 同步腿按同一判据选层
+ * (`memory-sync-client.ts` 读 {@link replicationCovers})。没有复制路径 ⇒ `unreplicated`(没有哪一层会被复制落下)。
  */
 export type MemoryReplicationCoverage = {
     readonly kind: "unreplicated";
 } | {
-    readonly kind: "scopes";
-    readonly scopes: readonly string[];
+    readonly kind: "layers";
+    readonly layers: readonly string[];
 };
 export declare function memoryReplicationCoverage(config: Pick<ServiceConfig, "memorySync">): MemoryReplicationCoverage;
-/** 覆盖面是否含这一层(`unreplicated` 含一切)。 */
+/** 覆盖面是否含这一层(`unreplicated` 含一切;复制层本身,或它同属主的项目层)。 */
 export declare function replicationCovers(coverage: MemoryReplicationCoverage, scope: string): boolean;
+/** 覆盖面复制不复制属主 `owner` 的项目层(有一条复制层与它同属主)。启动通知与 {@link replicationCovers} 读同一只判据。 */
+export declare function replicatesProjectLayersOf(coverage: MemoryReplicationCoverage, owner: string): boolean;
 /**
  * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core [ref]) materializes and
  * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
@@ -242,7 +249,7 @@ export declare function memoryStoreRootMovedRefusal(e: unknown): (Error & {
 export declare function memorySpecForRequest(scope: string | undefined, 
 /** S-512 / [ref] ①:本请求的项目身份声明({@link memoryProjectKeyFor} 的产物)。**必填位**(不是可选参数):
  *  每个铸点都得写出一个值 —— `undefined` 只合法地表示「本任务不按项目键控」(多租户 / 记忆暗 / 项目层不在复制覆盖面里)。
- *  · `{ scope: repoKey }` ⇒ 读 = `[repoKey, scope, ...extras]`、`writeScope` **显式** = `repoKey`(core 缺省取末层
+ *  · `{ scope: projectKey }`(S-640 起 `userrepo:…`)⇒ 读 = `[projectKey, scope, ...extras]`、`writeScope` **显式** = 项目层(core 缺省取末层
  *    = 全局层,不钉就是 M-03 本身;core 另有 `config.memory_write_scope_mismatch` 兜这一向);
  *  · `{ absent }` ⇒ 读 = `[scope, ...extras]`、`writeScope` 显式 = `scope`(全局层),core 铸 `memory.project_scope_absent`;
  *  · 两形都把声明原样落 `TaskSpec.memory.projectKey`(core 的生效面回显它)。 */
@@ -286,7 +293,7 @@ declarations?: {
 /**
  * 「这一腿挂不挂记忆面」的**唯一属主**(合并复审 车HF F1,2026-09-18):与 core `prepareMemory` 的判据同源 ——
  * `normalizeMemorySpec(spec)?.enabled === true`。S-405 之后 `memory:"off"` 铸的是「键在场 + `enabled:false`」(保留事实),
- * 任何按「键在不在场」判挂没挂的读者从那一天起都读错(改前 `memory-notice` 正是那样,把无记忆面的披露一起吞掉)。
+ * 任何按「键在不在场」判挂没挂的读者从那一天起都读错(改前本仓的记忆披露判别式正是那样,把无记忆面的披露一起吞掉;那只判别式已随引擎接管披露退役)。
  * 消费方拿本函数的布尔,不拿 `spec.memory` 自己判。
  *
  * ⚠️ **本函数会抛,而「抛」本身就是一条判据**(S-424 补注)。`normalizeMemorySpec` 对两形直接 throw

package/dist/memory-scope.js

@@ -2,7 +2,8 @@ import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
 import { executionLaneCaps, executionLaneOf } from "./execution-lane-caps.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
-import { projectKeyForTaskRoot } from "./project-identity.js";
+import { projectLayerForTaskRoot } from "./project-identity.js";
+import { parseProjectLayerKey, projectLayerOwnerOf } from "./project-layer-key.js";
 const V2_SCOPE_PREFIX_BY_KIND = {
     user: "user:",
     org: "org:",
@@ -28,22 +29,37 @@ export function memoryScopeFor(config, principal, projectId) {
     return config.memoryScope;
 }
 export function memoryProjectKeyFor(config, scope, taskRoot) {
+    return memoryProjectLayerFor(config, scope, taskRoot)?.key;
+}
+export function memoryProjectLayerFor(config, scope, taskRoot) {
     if (config.requirePrincipal === true || scope === undefined)
         return undefined;
-    const declared = projectKeyForTaskRoot(taskRoot);
-    if (declared.scope !== undefined && !replicationCovers(memoryReplicationCoverage(config), declared.scope))
+    const layer = projectLayerForTaskRoot(taskRoot, projectLayerOwnerOf(scope));
+    if (layer.key.scope !== undefined && !replicationCovers(memoryReplicationCoverage(config), layer.key.scope))
         return undefined;
-    return declared;
+    return layer;
 }
 export function memoryReplicationCoverage(config) {
-    return config.memorySync === undefined ? { kind: "unreplicated" } : { kind: "scopes", scopes: [config.memorySync.scope] };
+    return config.memorySync === undefined ? { kind: "unreplicated" } : { kind: "layers", layers: [config.memorySync.scope] };
 }
 export function replicationCovers(coverage, scope) {
     switch (coverage.kind) {
         case "unreplicated":
             return true;
-        case "scopes":
-            return coverage.scopes.includes(scope);
+        case "layers": {
+            if (coverage.layers.includes(scope))
+                return true;
+            const projectLayer = parseProjectLayerKey(scope);
+            return projectLayer !== undefined && replicatesProjectLayersOf(coverage, projectLayer.owner);
+        }
+    }
+}
+export function replicatesProjectLayersOf(coverage, owner) {
+    switch (coverage.kind) {
+        case "unreplicated":
+            return true;
+        case "layers":
+            return coverage.layers.some((layer) => projectLayerOwnerOf(layer) === owner);
     }
 }
 export function memoryEngineRemoteLanePosture(config) {
@@ -140,7 +156,7 @@ export function memorySpecForRequest(scope, projectKey, memoryWrite, defaultScop
     const projectScope = projectKey?.scope;
     if (projectScope !== undefined && projectScope === scope) {
         throw new Error(`memory project scope ${JSON.stringify(projectScope)} equals the global memory scope (MEMORY_SCOPE) — the project layer and the global layer would be one directory. ` +
-            "Set MEMORY_SCOPE to a name outside the server-minted project-key family (see src/project-identity.ts).");
+            "Set MEMORY_SCOPE to a name outside the server-minted project-key families (see src/project-layer-key.ts).");
     }
     const isV2 = isV2ScopeKey;
     const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && s !== projectScope && arr.indexOf(s) === i);

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

@@ -20,29 +20,43 @@ export declare function createMemorySyncTransport(opts: {
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
 }): MemorySyncTransport;
-/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录
- *  旁)下的 per-peer sidecar。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同)。 */
-export declare function memorySyncCursorPath(memoryRoot: string, peer: string): string;
+/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录旁)下的
+ *  per-(peer, scope) sidecar(`sync-cursors/<peer>/<scope 摘要>.json`)。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同);scope 段取 sha256 前 32 hex
+ *  (scope 键带 `:` `/` 且可长过段编码的 64 字符帽 —— 名字只需区分,内容里仍记原 scope,读时比对)。 */
+export declare function memorySyncCursorPath(memoryRoot: string, peer: string, scope: string): string;
+/** 一轮里一层的结果。 */
+export interface MemorySyncLayerResult {
+    readonly scope: string;
+    readonly result: MemorySyncClientResult;
+}
+/** 一轮(按层)的结果:成功的各层,按同步序(同步层在前,项目层按键序)。 */
+export interface MemorySyncRound {
+    readonly layers: readonly MemorySyncLayerResult[];
+}
 export interface MemorySyncRunner {
-    /** 一轮同步(串行:排在上一轮之后)。返回 core 结构化结果供调用方记 metrics/日志;transport/
-     *  协议错误向上 throw(本地零副作用,core 契约)。cursor 读写、conflicts warn 都在轮内完成。 */
-    syncOnce(reason: string): Promise<MemorySyncClientResult>;
+    /** 一轮同步(串行:排在上一轮之后),逐层一轮。任一层 transport/协议错误 ⇒ 其余层照跑,轮末汇总 reject(失败层本地零副作用,
+     *  core 契约);cursor 读写、conflicts warn 都在层内完成。 */
+    syncOnce(reason: string): Promise<MemorySyncRound>;
     /** fire-and-forget 一轮:上一轮在飞(排队/执行中)则跳过(inflight 节流);失败 warn 不上抛。 */
     trigger(reason: string): void;
-    /** cursor sidecar 的落盘路径(boot 日志/测试可见性)。 */
-    readonly cursorPath: string;
+    /** 跟踪一只本层属主的项目层(本地还没有条目也每轮拉它);首次跟踪即排一轮。不是本同步腿覆盖的项目层 ⇒ 抛(调用方的错)。 */
+    track(scope: string): void;
+    /** 把一段动本地记忆面的工作排进同步的串行链(等在飞的轮落定、执行时没有轮在飞)—— 项目层折叠用(`memory-project-layer.ts`)。 */
+    exclusive<T>(work: () => Promise<T>): Promise<T>;
+    /** 某一层的 cursor sidecar 路径(boot 日志/测试可见性)。 */
+    cursorPathFor(scope: string): string;
     /** 排队+在飞的轮数(测试的确定性等待面;0 = 完全空闲)。 */
     pending(): number;
 }
-/**
- * 组装一个 per-(scope,peer) 的同步执行器:cursor 持久化 + core `syncMemoryScope` + conflicts 上报 +
- * 串行化/节流。`backend` = 本地 File authority plane(memoryEngineBackendFor 的产物);`memoryRoot` =
- * resolved config root(cursor sidecar 落在 memory/ 目录旁)。
- */
 /** S2.5 分批 loop 的轮数上限(fail-loud 警戒,防协议异常时死循环;正常收敛远低于此)。 */
 export declare const MAX_SYNC_ROUNDS = 32;
+/**
+ * 组装同步执行器:同步层 `scope` + 同属主的项目层,逐层一轮(cursor 持久化 + core `syncMemoryScope` + conflicts 上报),串行化/节流。
+ * `backend` = 本地 File authority plane(memoryEngineBackendFor 的产物);`memoryRoot` = resolved config root(cursor sidecar 落在 memory/ 目录旁)。
+ */
 export declare function createMemorySyncRunner(opts: {
     backend: MemoryBackend;
+    /** 同步层(`config.memorySync.scope`);它同属主的项目层随它一起同步。 */
     scope: string;
     memoryRoot: string;
     transport: MemorySyncTransport;

package/dist/memory-sync-client.js

@@ -1,7 +1,9 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 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";
 export const DEFAULT_MEMORY_SYNC_PEER = "central";
 export function createMemorySyncTransport(opts) {
     const base = opts.url.replace(/\/+$/, "");
@@ -20,7 +22,10 @@ export function createMemorySyncTransport(opts) {
         return JSON.parse(text);
     };
 }
-export function memorySyncCursorPath(memoryRoot, peer) {
+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) {
     return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
 }
 async function loadCursor(path, scope, peer, log) {
@@ -41,6 +46,13 @@ async function loadCursor(path, scope, peer, log) {
         log.warn("memory_sync_cursor_corrupt", { path, err: String(err), note: "treating as first round" });
         return undefined;
     }
+    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)) {
         const c = parsed;
         const baseRevsRaw = c["baseRevs"];
@@ -55,9 +67,34 @@ async function loadCursor(path, scope, peer, log) {
             return { scope, peer, baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
         }
     }
-    log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
     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")}`;
@@ -65,18 +102,36 @@ async function saveCursor(path, cursor) {
     await rename(tmp, path);
 }
 export const MAX_SYNC_ROUNDS = 32;
+function enumerateScopes(backend) {
+    const face = backend.listScopes;
+    return typeof face === "function" ? face.call(backend) : { supported: false, reason: "the memory backend has no listScopes face" };
+}
 export function createMemorySyncRunner(opts) {
     const peer = opts.peer ?? DEFAULT_MEMORY_SYNC_PEER;
-    const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer);
-    const round = async (reason) => {
-        let cursor = await loadCursor(cursorPath, opts.scope, peer, opts.log);
+    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 = () => {
+        const local = enumerateScopes(opts.backend);
+        if (!local.supported && !enumerationWarned) {
+            enumerationWarned = true;
+            opts.log.warn("memory_sync_layer_enumeration_unsupported", { scope: opts.scope, peer, 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()];
+    };
+    const syncLayer = async (scope, reason) => {
+        const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer, scope);
+        let cursor = await loadCursor(cursorPath, scope, peer, opts.log);
         let result;
         let subRound = 0;
         for (;;) {
             subRound += 1;
             result = await syncMemoryScope({
                 backend: opts.backend,
-                scope: opts.scope,
+                scope,
                 transport: opts.transport,
                 peer,
                 ...(cursor !== undefined ? { cursor } : {}),
@@ -85,11 +140,11 @@ export function createMemorySyncRunner(opts) {
                 ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
             });
             for (const w of result.warnings ?? [])
-                opts.log.warn("memory_sync_warning", { scope: opts.scope, peer, subRound, warning: w });
+                opts.log.warn("memory_sync_warning", { scope, peer, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
                 break;
             if (subRound >= MAX_SYNC_ROUNDS) {
-                opts.log.warn("memory_sync_rounds_exhausted", { scope: opts.scope, peer, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
+                opts.log.warn("memory_sync_rounds_exhausted", { scope, peer, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
                 break;
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
@@ -101,11 +156,11 @@ export function createMemorySyncRunner(opts) {
                 }
             }
             cursor = result.cursor ?? cursor;
-            opts.log.info("memory_sync_continuation", { reason, scope: opts.scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
+            opts.log.info("memory_sync_continuation", { reason, scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
         }
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
-                scope: opts.scope,
+                scope,
                 peer,
                 side: c.side,
                 id: c.id,
@@ -124,7 +179,7 @@ export function createMemorySyncRunner(opts) {
         }
         opts.log.info("memory_sync_round", {
             reason,
-            scope: opts.scope,
+            scope,
             peer,
             ok: result.ok,
             cursorAdvanced: result.cursorAdvanced,
@@ -136,11 +191,32 @@ 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()) {
+            try {
+                layers.push({ scope, result: await syncLayer(scope, reason) });
+            }
+            catch (err) {
+                failures.push({ scope, err });
+                opts.log.warn("memory_sync_layer_failed", { reason, scope, peer, err: String(err) });
+            }
+        }
+        if (failures.length > 0) {
+            throw new Error(`memory sync round failed for ${failures.length} layer(s): ${failures.map((f) => `${f.scope}: ${f.err instanceof Error ? f.err.message : String(f.err)}`).join("; ")}`);
+        }
+        return { layers };
+    };
     let chain = Promise.resolve();
     let pending = 0;
-    const syncOnce = (reason) => {
+    const exclusive = (work) => {
         pending += 1;
-        const run = chain.then(() => round(reason));
+        const run = chain.then(work);
         chain = run.then(() => {
             pending -= 1;
         }, () => {
@@ -148,13 +224,26 @@ export function createMemorySyncRunner(opts) {
         });
         return run;
     };
-    const trigger = (reason) => {
-        if (pending > 0)
-            return;
+    const syncOnce = (reason) => exclusive(() => round(reason));
+    const queueRound = (reason) => {
         void syncOnce(reason).catch((err) => {
             opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, peer, err: String(err) });
         });
     };
-    return { syncOnce, trigger, cursorPath, pending: () => pending };
+    const trigger = (reason) => {
+        if (pending > 0)
+            return;
+        queueRound(reason);
+    };
+    const track = (scope) => {
+        if (!isCoveredProjectLayer(scope)) {
+            throw new Error(`memory sync track(): ${JSON.stringify(scope)} is not a project layer of this sync leg (layer ${JSON.stringify(opts.scope)} replicates its own project layers only)`);
+        }
+        if (tracked.has(scope))
+            return;
+        tracked.add(scope);
+        queueRound("track");
+    };
+    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, peer, scope), pending: () => pending };
 }
 //# sourceMappingURL=memory-sync-client.js.map

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

@@ -116,10 +116,18 @@ export declare function refusedNamesLogFields(key: string, names: readonly strin
 export declare function refusalEventOf(reason: ModelEntryRefusalReason): "web_admin_model_no_brain" | "web_admin_model_entry_invalid";
 /** warn 字段(不含值):`field` = 第一处坏字段(告警规则最常按它分组),`fields` = 全部。S-805:`model` 只在名可披露时写。 */
 export declare function refusalWarnFields(name: string, r: ModelEntryRefusal): Record<string, unknown>;
+/** 调用方写的模型 ref(`model` / `compactionModel` / `agents[i].model` / `@name`)回到人面前 —— 拒句与留声日志 —— 的字符上限。 */
+export declare const MODEL_REF_ECHO_CHARS = 120;
+/**
+ * 调用方写的模型 ref 的回显形:过回显的一只口径 {@link echoCallerText}(剥控制与双向字符,截到 {@link MODEL_REF_ECHO_CHARS} 字,超出加 `…`)。
+ * 目录门、`resolveSpec`、side-query 的拒句,以及它们写进运维日志的 `requested` 字段,**都**调这一只 —— 不在站点手写 `slice`。
+ */
+export declare function echoModelRef(ref: string): string;
 /**
  * 一次**显式选择**命中了不可用条目时的拒因句(HTTP `request.model_unavailable` 的 `error`、run-local 的 stderr、
  * hook 选模型的失败文案 —— 各处同一句)。`field` = 调用方的通道名(`model` / `compactionModel` / `agents[0].model` /
- * `@-mention`),`requested` = 调用方发来的原形(name 或 id),已由调用方截断。
+ * `@-mention`),`requested` = 调用方发来的**原形**(name 或 id;本函数回显它时过 {@link echoModelRef},调用方不预先截)。
+ * 别名段(`(catalog entry …)`)的判断读原形:ref 与条目名逐字相同 ⇒ 不带,不因回显截短而误判成「另有条目」。
  */
 export declare function modelUnavailableMessage(field: string, requested: string, name: string, r: ModelEntryRefusal): string;
 /** 缺省模型不变量读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */

package/dist/model-entry-refusal.js

@@ -3,6 +3,7 @@ import { ModelEntry, formatConfigPath, isReportableRefusalName } from "@sema-age
 import { catalogBrainLane } from "./model-provider.js";
 import { readCatalogEntryHeaders } from "./model-entry-headers.js";
 import { DroppedCatalogEntryRow, describeSchemaIssueFields, describeSchemaIssues } from "./web-admin-client/read-warnings.js";
+import { echoCallerText } from "./caller-text-echo.js";
 import { DEFAULT_MODEL_REF } from "./model-select.js";
 export const ENTRY_REFUSAL_REASON_OF = {
     "config.model_no_brain": "no_brain",
@@ -132,9 +133,13 @@ export function refusalWarnFields(name, r) {
         hint: r.detail,
     };
 }
+export const MODEL_REF_ECHO_CHARS = 120;
+export function echoModelRef(ref) {
+    return echoCallerText(ref, { maxChars: MODEL_REF_ECHO_CHARS });
+}
 export function modelUnavailableMessage(field, requested, name, r) {
     const alias = requested === name ? "" : ` (catalog entry "${name}")`;
-    return `${field} "${requested}"${alias} is published in the catalog but unavailable on this deployment [${r.code}] — ${r.detail}`;
+    return `${field} "${echoModelRef(requested)}"${alias} is published in the catalog but unavailable on this deployment [${r.code}] — ${r.detail}`;
 }
 export function defaultModelRefusal(view, leg) {
     if (Object.hasOwn(view.models, DEFAULT_MODEL_REF) && view.models[DEFAULT_MODEL_REF] !== undefined)

package/dist/model-plane-face.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `GET /v1/models` 顶层 `modelPlane` 的**唯一铸点** —— 壳问「这台引擎服务的是哪张模型表 / 目录采纳了没有 / 起服路由判官怎么说」读这一格,不自己预测。
+ *
+ * ## 为什么在 server 里答
+ * 判官的输入是服务进程的事实:采纳之后 `config.model` 是不是还是那只 env 模型(对象同一性)、anthropic 路由装没装(凭据在场性)、名册布防(env 表是占位)。
+ * 壳拼不出这些,只能镜像两道判(目录条目逐条合形、车道 / 端点可解析)—— 镜像会随时间与真判官漂开(同一问两份读法)。所以结论只有 server 说,壳读它。
+ *
+ * ## 四个字段,两根轴
+ *  · `servedTable` —— **谁在服**:{@link servedModelTableLeg}(此刻服务 env 表还是目录表;同一只读法,不另记旗子)。
+ *  · `catalog` —— **最近一份目录候选的结局**({@link CATALOG_STANCES}):
+ *      `refused` —— 候选被整拒:候选判官整拒(`candidateRejectionState` 座),或模型面组拒(`modelRefusalsState().plane` 在场;各码见
+ *                   settings-schema `MODEL_PLANE_REFUSAL_CODES`)。没有 LKG 时服务的是 env 表,有 LKG(或上一代已采纳)时仍服目录表 —— 谁在服归 `servedTable` 答,
+ *                   不在这一格里合并(合并 = 一个字段两个意思);逐条被拒(条目不可用,`entries`)不是整拒,那些条目之外的目录照服;
+ *      `adopted` —— 没有整拒、且服务的是目录表;
+ *      `absent`  —— 没有整拒、且服务的是 env 表:没配目录源 / 配了但没有启用条目(候选不管模型面,不是拒)/ 纯 env 部署。
+ *    两个座(候选判官的结论座与模型面组拒的信号座)是候选在两道判官各自留下的事实,本格只读它们,不另算第二份。
+ *    **不在内**:候选过了两道判官、却在装配期被引擎整份拒收(`applyEffective` 里引擎拒收 `apiKeyEnv` 声明 / Runner 拒收换装;活配置零触碰,只有日志与 `/health` 世代账的 target≠applied)——
+ *    这一形今天没有座,`catalog` 仍按上一代读;`adopted` 说的是「没有被判官整拒」,不是「最新候选已落地」(那一问归世代账)。要覆盖它得先给装配期拒收立一个座(另案设计)。
+ *  · `refusalCode` / `gap` —— **起服路由判官对当前 config 的判决**:`judgeServedModelRoute` 同一只函数(装配第 2 段与 `run-local` 调的就是它),通过 ⇒ 两键缺席。
+ *    进程既然起来了,正常是缺席;测试夹具 / 自建装配 / 不拒启的入口可能在场 —— 如实投,不替它们编造通过。**不带句子**(拒因句只走日志与起服错误)。
+ *
+ * ## 只在起服后可答
+ * 读面挂在运行中的进程上;判官必须在目录应用之后调(`judgeServedModelRoute` 头注),起服前没有「将要服务的表」,所以没有起服前的预判口。
+ */
+import type { ModelRefusalsSignal } from "@sema-agent/settings-schema";
+import { type ModelRouteEndpointVerdict, type ModelRouteGap, type ServedModelRouteView } from "./model-route-endpoint.js";
+import { type ModelTableLeg } from "./model-select.js";
+import type { CandidateRejection } from "./web-admin-client/candidate-gate.js";
+/** `modelPlane.catalog` 的闭集(消费方用穷举 switch —— 加一词不补臂 ⇒ 编译红)。 */
+export declare const CATALOG_STANCES: readonly ["absent", "adopted", "refused"];
+export type CatalogStance = (typeof CATALOG_STANCES)[number];
+/** `GET /v1/models.modelPlane` 的 wire 形(纯数据;条件键缺席,不铸 `null` / 空串)。 */
+export interface ModelPlaneFace {
+    readonly servedTable: ModelTableLeg;
+    readonly catalog: CatalogStance;
+    /** 起服路由判官判决的机读码(`ModelPlaneRefusalCode` 的子集:路由端点族两码)。 */
+    readonly refusalCode?: ModelRouteEndpointVerdict["code"];
+    /** 同一次判决的出路轴(缺口两词)。 */
+    readonly gap?: ModelRouteGap;
+}
+/** {@link buildModelPlaneFace} 读的进程事实(都由调用方从各自的座取,本函数不碰任何全局)。 */
+export interface ModelPlaneFacts {
+    /** 严格名册布防(`isRosterGateArmed`):env 表是占位、不被判(装配第 2 段传的是同一只谓词)。 */
+    readonly envTableIsPlaceholder: boolean;
+    /** 候选判官最近一次整拒的结论座(`WebAdminRuntime.candidateRejectionState()`);座空 / 没有配置管道 ⇒ `undefined`。 */
+    readonly candidateRejection: CandidateRejection | undefined;
+    /** 模型拒因信号(`WebAdminRuntime.modelRefusalsState()`);`plane` 在场 ⇒ 最近一份候选的模型面被整组拒。 */
+    readonly modelRefusals: Pick<ModelRefusalsSignal, "plane"> | undefined;
+}
+export declare function buildModelPlaneFace(config: ServedModelRouteView, facts: ModelPlaneFacts): ModelPlaneFace;
+//# sourceMappingURL=model-plane-face.d.ts.map

package/dist/model-plane-face.js

@@ -0,0 +1,24 @@
+import { judgeServedModelRoute } from "./model-route-endpoint.js";
+import { servedModelTableLeg } from "./model-select.js";
+export const CATALOG_STANCES = ["absent", "adopted", "refused"];
+function catalogStanceOf(served, wholeRefused) {
+    if (wholeRefused)
+        return "refused";
+    switch (served) {
+        case "catalog":
+            return "adopted";
+        case "env":
+            return "absent";
+    }
+}
+export function buildModelPlaneFace(config, facts) {
+    const servedTable = servedModelTableLeg(config);
+    const wholeRefused = facts.candidateRejection !== undefined || facts.modelRefusals?.plane !== undefined;
+    const verdict = judgeServedModelRoute(config, { envTableIsPlaceholder: facts.envTableIsPlaceholder });
+    return {
+        servedTable,
+        catalog: catalogStanceOf(servedTable, wholeRefused),
+        ...(verdict !== undefined ? { refusalCode: verdict.code, gap: verdict.gap } : {}),
+    };
+}
+//# sourceMappingURL=model-plane-face.js.map