@sema-agent/server 1.323.0 → 2.0.0

package/dist/memory-export.d.ts

@@ -1,3 +1,4 @@
 import type { MemoryBackend, MemoryEntry } from "@sema-agent/core";
+/** All entries of one scope, deterministic id order (both backend read faces ORDER BY id). */
 export declare function exportMemoryScope(backend: MemoryBackend, scope: string): Promise<MemoryEntry[]>;
 //# sourceMappingURL=memory-export.d.ts.map

package/dist/memory-export.js

@@ -1,8 +1,12 @@
+/** All entries of one scope, deterministic id order (both backend read faces ORDER BY id). */
 export async function exportMemoryScope(backend, scope) {
     const headers = await backend.listHeaders([scope]);
     if (headers.length === 0)
         return [];
     const entries = await backend.getByIds(headers.map((h) => h.id));
+    // Defense-in-depth: getByIds is id-keyed (no scope filter). The ids came from THIS scope's own
+    // headers, but a header-read/entry-read race (concurrent cross-scope re-add) must never leak a
+    // foreign scope's entry into an owner-gated export — filter honestly.
     return entries.filter((e) => e.scope === scope);
 }
 //# sourceMappingURL=memory-export.js.map

package/dist/memory-scope.d.ts

@@ -1,14 +1,63 @@
 import { FileMemoryEngineBackend } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+/** Resolve the memory scope for a request (design/138 S1 — the file-based memory engine is the only plane).
+ *
+ *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
+ *  regardless of any principal label the caller self-reports (a single-user worker's `anon:*` / ad-hoc
+ *  principals are surface labels, not isolation identities — keying memory by them would split the one
+ *  user's memory across surfaces). Explicit `MEMORY_SCOPE` wins (it IS config.memoryScope).
+ *
+ *  MULTI-TENANT (REQUIRE_PRINCIPAL=true): always `undefined` ⇒ no `spec.memory` ⇒ memory is DARK,
+ *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
+ *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
+ *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
 export declare function memoryScopeFor(config: ServiceConfig, principal?: string, projectId?: string): string | undefined;
+/**
+ * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core design/138) materializes and
+ * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
+ * the SANDBOX fs — the planes never meet: materialized memory is invisible inside the sandbox (the injected
+ * instructions burn failing Write turns) and sandbox writes are never harvested (add=0). Until core defines
+ * the boundary (engine routed through the ExecutionEnv seam, or host-only by contract — relayed on the team
+ * channel), a remote lane forces memory DARK unless the operator explicitly vouches both lanes share one fs
+ * (`MEMORY_ENGINE_REMOTE_LANE=allow`, e.g. ssh to a host on the same NFS mount).
+ *
+ * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
+ * (no remote lane, or the `host` lane), `dark` = split + fail-closed, `forced` = split + operator override.
+ */
 export declare function memoryEngineRemoteLanePosture(config: ServiceConfig): {
     lane: string;
     posture: "dark" | "forced";
 } | undefined;
+/**
+ * design/138 S1 wiring gate (pure — unit-testable without booting main): build the file-based memory-engine
+ * backend for this deployment, or `undefined` when memory must stay dark.
+ *
+ *  - SINGLE-USER TURNKEY ONLY (`requirePrincipal !== true`): the engine's file basement
+ *    (`FileMemoryEngineBackend` over one directory tree) has NO tenant isolation, so a multi-tenant
+ *    deployment gets `undefined` — memory dark, fail-closed (never a shared cross-tenant store).
+ *  - `MEMORY_ENGINE=off` (`config.memoryEngineEnabled === false`) is the explicit operator kill-switch.
+ *  - REMOTE EXEC LANE (N0): a plane-splitting lane (any non-`host` remoteExec) forces `undefined` — memory
+ *    dark, fail-closed — unless `MEMORY_ENGINE_REMOTE_LANE=allow` (see memoryEngineRemoteLanePosture above).
+ *  - Directory: `<root>/memory` where root = `resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot)`
+ *    (explicit `MEMORY_ENGINE_DIR` → caller's data root → `AGENT_DATA_DIR` env → `~/.ai-agent`). The
+ *    FileBackend PINS this directory (core §2.7: `directoryRoot` wins over per-repo derivation), so the
+ *    single user has ONE memory home across repos/tasks — the CC `~/.claude` posture.
+ *
+ * Returns the backend + the resolved config root (the root also rides on `RunnerDeps.memoryEngineDir` so
+ * core derives the B3 control plane beside it).
+ */
 export declare function memoryEngineBackendFor(config: ServiceConfig, fallbackRoot?: string): {
     backend: FileMemoryEngineBackend;
     root: string;
 } | undefined;
+/**
+ * MF-30 memory PAUSE (option B, per-request — clay 2026-06-27): build the `TaskSpec.memory` spec for ONE run from
+ * the resolved memory `scope` + the request's `memoryWrite` toggle. `memoryWrite === false` ⇒ `writeScope: null`
+ * (design/138 engine read-only: normalizeMemorySpec's writeScope:null — materialize/read still works, harvest
+ * commits nothing). Absent/true ⇒ normal read+write. No scope (engine off / multi-tenant dark) ⇒ undefined
+ * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
+ * engine-backend presence guard.
+ */
 export declare function memorySpecForRequest(scope: string | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[]): {
     scope: string;
     scopes?: string[];

package/dist/memory-scope.js

@@ -1,38 +1,121 @@
+// design/158 N17: the memory-plane resolvers moved VERBATIM out of security.ts (lens4 §4.1 — "budget.ts"'s
+// sibling finding: security.ts's name says auth, but ~110 of its 765 lines were memory-scope config
+// resolution with nothing to do with authentication). security.ts re-exports all four for compat (its own
+// createAuthorizer still calls memoryScopeFor); index.ts's npm-facing re-export is unaffected (package.json
+// "exports" only ever exposed "." and "./main" — dist/security.js was never a reachable deep-import path).
 import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope } from "@sema-agent/core";
+/** Resolve the memory scope for a request (design/138 S1 — the file-based memory engine is the only plane).
+ *
+ *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
+ *  regardless of any principal label the caller self-reports (a single-user worker's `anon:*` / ad-hoc
+ *  principals are surface labels, not isolation identities — keying memory by them would split the one
+ *  user's memory across surfaces). Explicit `MEMORY_SCOPE` wins (it IS config.memoryScope).
+ *
+ *  MULTI-TENANT (REQUIRE_PRINCIPAL=true): always `undefined` ⇒ no `spec.memory` ⇒ memory is DARK,
+ *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
+ *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
+ *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
 export function memoryScopeFor(config, principal, projectId) {
     if (config.requirePrincipal === true) {
+        // S3-TOB(设计 §1.3):multi-tenant lights up ONLY on a DB backend (scope column = tenant
+        // partition) — the scope is the VERIFIED principal, never MEMORY_SCOPE (a shared-env scope here would
+        // be a cross-tenant bleed, 复审 F6) and never absent-principal (anonymous run ⇒ no memory).
+        // NOTE (复审 F-07): the scope column is data PARTITIONING; tenant AUTHORIZATION is exactly this
+        // binding — verified principal in, one tenant's scope out. File backend stays dark (no isolation).
+        // 142-S1.5(core 1.268.0 到货即切,免费迁移窗=现网点亮前存量 0):bare principal → the v2 typed
+        // key `user:<tenant>` via core's formatUserScope (encodeScopeSegment inside — principal chars are
+        // segment-encoded, never truncated/collided). Paired with scopeContract:"v2" on the spec face below
+        // (opt-in is EXPLICIT per design/142 §1.2 — no prefix sniffing anywhere).
+        // 142-S4(派生 v1=项目盘):a SHAPE-VALIDATED projectId(authorizer 的 PROJECT_ID_REGEX 门)
+        // 在场 ⇒ 项目盘 v2 键 `proj:<tenant>/<projectId>`(core formatProjScope;tenant 段 = verified
+        // principal,身份永远不来自 body — projectId 只挑盘)。铁律:proj: 键经我方 DB 的场景=无仓
+        // project(有仓 project 权威=git,根本不到这条派生线)。userproj: 派生不在 v1(待拍板)。
         if (config.memoryEngineBackend === "pg" || config.memoryEngineBackend === "tidb") {
             if (!principal)
                 return undefined;
             return projectId ? formatProjScope(principal, projectId) : formatUserScope(principal);
         }
-        return undefined;
+        return undefined; // file backend: dark, fail-closed (no tenant isolation in the file engine)
     }
-    return config.memoryScope;
+    return config.memoryScope; // single-user: one shared scope — principal labels never partition memory
 }
+/**
+ * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core design/138) materializes and
+ * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
+ * the SANDBOX fs — the planes never meet: materialized memory is invisible inside the sandbox (the injected
+ * instructions burn failing Write turns) and sandbox writes are never harvested (add=0). Until core defines
+ * the boundary (engine routed through the ExecutionEnv seam, or host-only by contract — relayed on the team
+ * channel), a remote lane forces memory DARK unless the operator explicitly vouches both lanes share one fs
+ * (`MEMORY_ENGINE_REMOTE_LANE=allow`, e.g. ssh to a host on the same NFS mount).
+ *
+ * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
+ * (no remote lane, or the `host` lane), `dark` = split + fail-closed, `forced` = split + operator override.
+ */
 export function memoryEngineRemoteLanePosture(config) {
     const lane = config.remoteExec?.provider;
     if (lane === undefined || lane === "host")
-        return undefined;
+        return undefined; // hands work THIS machine's fs — same plane
     return { lane, posture: config.memoryEngineRemoteLaneAllowed === true ? "forced" : "dark" };
 }
+/**
+ * design/138 S1 wiring gate (pure — unit-testable without booting main): build the file-based memory-engine
+ * backend for this deployment, or `undefined` when memory must stay dark.
+ *
+ *  - SINGLE-USER TURNKEY ONLY (`requirePrincipal !== true`): the engine's file basement
+ *    (`FileMemoryEngineBackend` over one directory tree) has NO tenant isolation, so a multi-tenant
+ *    deployment gets `undefined` — memory dark, fail-closed (never a shared cross-tenant store).
+ *  - `MEMORY_ENGINE=off` (`config.memoryEngineEnabled === false`) is the explicit operator kill-switch.
+ *  - REMOTE EXEC LANE (N0): a plane-splitting lane (any non-`host` remoteExec) forces `undefined` — memory
+ *    dark, fail-closed — unless `MEMORY_ENGINE_REMOTE_LANE=allow` (see memoryEngineRemoteLanePosture above).
+ *  - Directory: `<root>/memory` where root = `resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot)`
+ *    (explicit `MEMORY_ENGINE_DIR` → caller's data root → `AGENT_DATA_DIR` env → `~/.ai-agent`). The
+ *    FileBackend PINS this directory (core §2.7: `directoryRoot` wins over per-repo derivation), so the
+ *    single user has ONE memory home across repos/tasks — the CC `~/.claude` posture.
+ *
+ * Returns the backend + the resolved config root (the root also rides on `RunnerDeps.memoryEngineDir` so
+ * core derives the B3 control plane beside it).
+ */
 export function memoryEngineBackendFor(config, fallbackRoot) {
     if (config.requirePrincipal === true || !config.memoryEngineEnabled)
         return undefined;
     if (memoryEngineRemoteLanePosture(config)?.posture === "dark")
-        return undefined;
+        return undefined; // N0: worker/sandbox file planes split
     const root = resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot);
     const dir = join(root, "memory");
+    // 🔴 controlDir EXPLICIT: the backend's DEFAULT control plane derives from the ARGLESS
+    // resolveMemoryEngineRoot() — i.e. AGENT_DATA_DIR/~/.ai-agent, IGNORING an explicit MEMORY_ENGINE_DIR. With a
+    // custom dir the sidecars (ledger/shadow/quarantine) would land under the DEFAULT root while
+    // RunnerDeps.memoryEngineDir points core's engine at the custom root — a split control plane. Pin it beside
+    // OUR root using core's own derivation (key = the memory dir, the same shape as the backend's default).
     return { backend: new FileMemoryEngineBackend(dir, { controlDir: deriveControlPlaneDir(root, dir) }), root };
 }
+/**
+ * MF-30 memory PAUSE (option B, per-request — clay 2026-06-27): build the `TaskSpec.memory` spec for ONE run from
+ * the resolved memory `scope` + the request's `memoryWrite` toggle. `memoryWrite === false` ⇒ `writeScope: null`
+ * (design/138 engine read-only: normalizeMemorySpec's writeScope:null — materialize/read still works, harvest
+ * commits nothing). Absent/true ⇒ normal read+write. No scope (engine off / multi-tenant dark) ⇒ undefined
+ * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
+ * engine-backend presence guard.
+ */
 export function memorySpecForRequest(scope, memoryWrite, defaultScopes) {
     if (!scope)
         return undefined;
+    // 142-S1.5: a scope carrying a v2 typed prefix rides WITH the explicit contract marker — core validates
+    // the key fail-loud under "v2" (design/142 §1.2). Detection here is NOT sniffing: `user:`/`proj:` keys are
+    // OUR memoryScopeFor's own mint (formatUserScope/formatProjScope) and `defaultScopes` entries are the
+    // OPERATOR's center-registry declaration (config.projects — 登记簿说明其形态=v2 scope 键串),so the
+    // prefix is a self/operator-produced marker, never a guess about caller data; a legacy opaque scope
+    // (single-user config.memoryScope) with no defaultScopes stays contract-less byte-identical.
     const isV2 = (k) => k.startsWith("user:") || k.startsWith("org:") || k.startsWith("proj:") || k.startsWith("userproj:");
+    // 142-S4 defaultScopes 种子(config.projects[projectId].defaultScopes):额外的 READ 层(去重、去 scope
+    // 自身、去空串;保 center 声明顺序)。写路由不变:core normalizeMemorySpec 的 writeScope 缺省=scopes 的
+    // 最后一层,所以带种子时必须 EXPLICIT 钉 writeScope=派生 scope(否则 harvest 会写进登记簿的最后一个默认
+    // scope — 一个共享层,错)。无种子 = 形状逐字节等价旧版(additive 锁)。
     const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && arr.indexOf(s) === i);
     const layered = extras.length > 0 ? { scopes: [scope, ...extras], writeScope: scope } : {};
     const v2 = isV2(scope) || extras.some(isV2) ? { scopeContract: "v2" } : {};
+    // memoryWrite === false(MF-30 pause)wins over the layered writeScope pin — 只读语义在有种子时同样成立。
     return memoryWrite === false ? { scope, ...layered, writeScope: null, ...v2 } : { scope, ...layered, ...v2 };
 }
 //# sourceMappingURL=memory-scope.js.map

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

@@ -1,22 +1,45 @@
 import { type MemoryBackend, type MemorySyncClientResult, type MemorySyncTransport } from "@sema-agent/core";
+/** 结构化日志面(src/observability/logger.ts Logger 的结构子集——测试可注入捕获器)。 */
 export interface MemorySyncLog {
     info(msg: string, fields?: Record<string, unknown>): void;
     warn(msg: string, fields?: Record<string, unknown>): void;
 }
+/** 缺省对端名(core `syncMemoryScope` 同款缺省;cursor 按 (scope,peer) 分区)。 */
 export declare const DEFAULT_MEMORY_SYNC_PEER = "central";
+/**
+ * fetch transport(core `MemorySyncTransport` 的部署实现)。`url` = 中心 server 基址(尾斜杠剥除,
+ * core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedPrincipal 的
+ * verified-principal 门对齐)。非 2xx throw(status + body 前 200 字节——中心 4xx/5xx 的 typed error
+ * body 就是最好的诊断线索);2xx 返回解码后的 JSON(形状校验在 core parseMemorySyncResponse,职责
+ * 不重复)。`timeoutMs`(缺省 60s,AbortSignal.timeout)是活性保护:fire-and-forget 轮挂死会把
+ * inflight 节流永久卡住(undici 默认 headers 超时 300s 太钝)。
+ */
 export declare function createMemorySyncTransport(opts: {
     url: string;
     token: string;
     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;
 export interface MemorySyncRunner {
+    /** 一轮同步(串行:排在上一轮之后)。返回 core 结构化结果供调用方记 metrics/日志;transport/
+     *  协议错误向上 throw(本地零副作用,core 契约)。cursor 读写、conflicts warn 都在轮内完成。 */
     syncOnce(reason: string): Promise<MemorySyncClientResult>;
+    /** fire-and-forget 一轮:上一轮在飞(排队/执行中)则跳过(inflight 节流);失败 warn 不上抛。 */
     trigger(reason: string): void;
+    /** cursor sidecar 的落盘路径(boot 日志/测试可见性)。 */
     readonly cursorPath: 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;
 export declare function createMemorySyncRunner(opts: {
     backend: MemoryBackend;
@@ -26,6 +49,7 @@ export declare function createMemorySyncRunner(opts: {
     log: MemorySyncLog;
     peer?: string;
     now?: () => number;
+    /** S2.5 分批(core 1.284 两 seam):push 集/pull 集单轮上限。未设=不分批(wire 字节不变)。 */
     maxPushEntries?: number;
     maxPullEntries?: number;
 }): MemorySyncRunner;

package/dist/memory-sync-client.js

@@ -1,7 +1,28 @@
+// 142-S2.5-W1 —— TOC 同步 client 腿:包 core `syncMemoryScope`(1.275.1 导出,一轮 =
+// 一 RTT 双向,cursor 保留纪律见 core sync-client.js 头注)。本模块只补 core 刻意留白的部署半场:
+//   ① transport:fetch POST `{MEMORY_SYNC_URL 去尾斜杠}{path}`(path 由 core 铸,scope 已
+//      encodeURIComponent),headers = Bearer + JSON;非 2xx throw(带 status + body 前 200 字节)。
+//      core 契约:transport 在任何本地写之前跑,throw = 本轮零本地副作用。
+//   ② cursor 持久化:`join(memoryRoot, "sync-cursor-" + encodeScopeSegment(peer) + ".json")`——
+//      读:不存在 ⇒ undefined(首轮);坏 JSON/形状不符/scope-peer 不匹配 ⇒ warn + 当首轮(core 对
+//      错配 cursor 是 fail-loud throw,这里预检降为首轮:空基线重收敛是协议的幂等安全面)。
+//      写:仅 cursorAdvanced 才写(core 保留纪律的落盘半场),tmp+rename 原子。
+//   ③ 串行化 + 节流:syncOnce 按 promise 链串行(两轮并发会在同一文件面上交错写);trigger =
+//      fire-and-forget,上一轮在飞(排队中/执行中)则跳过(设计:简单 inflight 布尔)。
+// conflicts = logger.warn 逐条上报(不自动 ladder——败者铸 sibling 的解决动作留给 operator/后续单)。
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
+/** 缺省对端名(core `syncMemoryScope` 同款缺省;cursor 按 (scope,peer) 分区)。 */
 export const DEFAULT_MEMORY_SYNC_PEER = "central";
+/**
+ * fetch transport(core `MemorySyncTransport` 的部署实现)。`url` = 中心 server 基址(尾斜杠剥除,
+ * core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedPrincipal 的
+ * verified-principal 门对齐)。非 2xx throw(status + body 前 200 字节——中心 4xx/5xx 的 typed error
+ * body 就是最好的诊断线索);2xx 返回解码后的 JSON(形状校验在 core parseMemorySyncResponse,职责
+ * 不重复)。`timeoutMs`(缺省 60s,AbortSignal.timeout)是活性保护:fire-and-forget 轮挂死会把
+ * inflight 节流永久卡住(undici 默认 headers 超时 300s 太钝)。
+ */
 export function createMemorySyncTransport(opts) {
     const base = opts.url.replace(/\/+$/, "");
     const fetchImpl = opts.fetchImpl ?? fetch;
@@ -19,9 +40,13 @@ export function createMemorySyncTransport(opts) {
         return JSON.parse(text);
     };
 }
+/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录
+ *  旁)下的 per-peer sidecar。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同)。 */
 export function memorySyncCursorPath(memoryRoot, peer) {
     return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
 }
+/** 读 cursor:不存在 ⇒ undefined(首轮);坏 JSON / 形状不符 / (scope,peer) 错配 ⇒ warn + undefined
+ *  (core 对错配 cursor fail-loud throw——这里预检降为首轮,空基线重收敛幂等安全)。 */
 async function loadCursor(path, scope, peer, log) {
     let raw;
     try {
@@ -57,12 +82,19 @@ async function loadCursor(path, scope, peer, log) {
     log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
     return undefined;
 }
+/** 写 cursor:tmp + rename 原子(半写的 cursor = 下轮坏 JSON 当首轮,重收敛而非错基线)。 */
 async function saveCursor(path, cursor) {
     await mkdir(dirname(path), { recursive: true });
     const tmp = `${path}.tmp`;
     await writeFile(tmp, JSON.stringify(cursor), "utf8");
     await rename(tmp, path);
 }
+/**
+ * 组装一个 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 const MAX_SYNC_ROUNDS = 32;
 export function createMemorySyncRunner(opts) {
     const peer = opts.peer ?? DEFAULT_MEMORY_SYNC_PEER;
@@ -71,6 +103,8 @@ export function createMemorySyncRunner(opts) {
         let cursor = await loadCursor(cursorPath, opts.scope, peer, opts.log);
         let result;
         let subRound = 0;
+        // S2.5 分批续轮:任一半场截断 ⇒ 立即续跑下一子轮(用上一轮返回的 cursor 作基线,协议幂等收敛);
+        // MAX_SYNC_ROUNDS 警戒 fail-loud(截断标志异常粘死时不无限烧请求,余量下轮 trigger 自然补)。
         for (;;) {
             subRound += 1;
             result = await syncMemoryScope({
@@ -93,7 +127,7 @@ export function createMemorySyncRunner(opts) {
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
                 try {
-                    await saveCursor(cursorPath, result.cursor);
+                    await saveCursor(cursorPath, result.cursor); // 子轮间也持久化(崩溃不回退基线)
                 }
                 catch (err) {
                     opts.log.warn("memory_sync_cursor_write_failed", { path: cursorPath, err: String(err) });
@@ -102,6 +136,7 @@ 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 });
         }
+        // conflicts 逐条 warn(server 半场 + 本地半场聚合,core 绝不隐藏;解决 ladder 不自动跑)。
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
                 scope: opts.scope,
@@ -113,6 +148,8 @@ export function createMemorySyncRunner(opts) {
                 ...(c.currentRev !== undefined ? { currentRev: c.currentRev } : {}),
             });
         }
+        // 保留纪律的落盘半场:仅 cursorAdvanced 才写。写失败只 warn(数据已按 CAS 落定,丢的是基线推进——
+        // 下轮按旧基线重放即幂等自愈,与中心侧 putCursor 失败的收敛论证同款),绝不把成功轮报成失败。
         if (result.cursorAdvanced && result.cursor !== undefined) {
             try {
                 await saveCursor(cursorPath, result.cursor);
@@ -135,6 +172,8 @@ export function createMemorySyncRunner(opts) {
         });
         return result;
     };
+    // 串行链:两轮并发会在同一 File plane / cursor 文件上交错(push 半场读集与 pull 半场落盘互踩)。
+    // `pending` = 排队+在飞的轮数(设计的“简单 inflight 布尔”推广到可排队形态:syncOnce 排队,trigger 跳过)。
     let chain = Promise.resolve();
     let pending = 0;
     const syncOnce = (reason) => {
@@ -149,7 +188,7 @@ export function createMemorySyncRunner(opts) {
     };
     const trigger = (reason) => {
         if (pending > 0)
-            return;
+            return; // 上一轮在飞 ⇒ 跳过(harvest 高频时的节流;漏掉的变更下一轮全量补上)
         void syncOnce(reason).catch((err) => {
             opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, peer, err: String(err) });
         });

package/dist/memory-sync.d.ts

@@ -1,14 +1,23 @@
 import { type MemoryBackend, type MemoryEntry, type PatchReport } from "@sema-agent/core";
 import type { MemorySyncStore } from "./plugins/memory-sync-store-pg.js";
+/** 一轮同步请求(验型后的干净形状——`parseMemorySyncRequest` 是唯一铸造点)。 */
 export interface MemorySyncRequest {
+    /** 对端标识(MemorySyncCursor.peer,per-(scope,peer) 游标分区键)。 */
     peer: string;
+    /** 客户端游标的共同基线:id → rev at last completed sync round(空 map = 首轮)。 */
     baseRevs: Record<string, string>;
+    /** push 半场:自基线以来客户端新增/变更的条目全量(scope 已验 = 路径 scope)。 */
     entries: MemoryEntry[];
+    /** 客户端删除的 id(每个都在 baseRevs 里——CAS 基线;验型层保证)。 */
     deletes: string[];
+    /** S2.5 分批腿(契约 settled 2026-07-14,全 additive):pull 半场条目数上限。缺席=不限(旧行为
+     *  字节不变)。截断规则见 performMemorySync ⑥。 */
     pull?: {
         limit: number;
     };
 }
+/** 一条冲突上报(applyPatches conflicts 同形 + 入站门/发散两类 reason)。`currentRev` = 中心侧
+ *  当前 rev(中心已删则缺席)——客户端按 core §3 ladder 解决(败者铸 sibling,绝不静默丢)。 */
 export interface MemorySyncConflictReport {
     id: string;
     reason: string;
@@ -16,20 +25,27 @@ export interface MemorySyncConflictReport {
     currentRev?: string;
 }
 export interface MemorySyncResponse {
+    /** 中心侧本轮真正落库的 op(backend PatchReport.applied 原样——幂等重放时为空)。 */
     applied: PatchReport["applied"];
     conflicts: MemorySyncConflictReport[];
+    /** pull 半场:中心侧自 baseRevs 以来新增/变更的条目全量(客户端按自己的 baseRevs CAS 应用)。 */
     serverEntries: MemoryEntry[];
+    /** pull 半场的删除腿(core plan.deleteRemote;草案偏离①——没它中心删除永不传播 = livelock)。 */
     serverDeletes: Array<{
         id: string;
         baseRev: string;
     }>;
+    /** 本轮落库的新基线(草案偏离②)——客户端应用完 pull 半场后把它持久化为自己的游标。 */
     cursor: {
         peer: string;
         baseRevs: Record<string, string>;
         updatedAtMs: number;
     };
+    /** S2.5 分批腿:serverEntries 被 pull.limit 截断时为 true(缺席=未截断)。客户端续轮直到缺席。 */
     pullTruncated?: true;
 }
+/** 一轮 push 的条目数上限 = core REMOTE_HARVEST_MAX_FILES 同款口径(一个 scope 的文件面上限 500;
+ *  同步一轮打满全集也在此内)。deletes 上限同基数放宽(全集删除也要能一轮表达)。 */
 export declare const MEMORY_SYNC_MAX_ENTRIES = 500;
 export declare const MEMORY_SYNC_MAX_DELETES = 2000;
 type ParseResult = {
@@ -39,7 +55,14 @@ type ParseResult = {
     ok: false;
     error: string;
 };
+/** Shape-validate + NORMALIZE the request body (picked-not-spread:只挑认识的字段重建,body 上的
+ *  多余键绝不透传进数据面)。`scope` = 路径上已过 owner 门的 scope——每个条目的 scope 必须逐字
+ *  等于它(否则一个 owner-gated 路由就成了跨租户写门)。 */
 export declare function parseMemorySyncRequest(body: unknown, scope: string): ParseResult;
+/**
+ * One full sync round for one (scope, peer). `backend` = 中心侧 entry plane(DB 权威),`cursors` =
+ * per-(scope,peer) 游标面(sync_cursors)。纯数据参数进(路由已完成鉴权/owner 门/验型),响应形状出。
+ */
 export declare function performMemorySync(backend: MemoryBackend, cursors: Pick<MemorySyncStore, "putCursor">, scope: string, req: MemorySyncRequest, now?: () => number): Promise<MemorySyncResponse>;
 export {};
 //# sourceMappingURL=memory-sync.d.ts.map

package/dist/memory-sync.js

@@ -1,7 +1,49 @@
+// 142-S2.5 中心侧同步 API 的执行内核(设计 docs/design/142-S4-DATAPLANE.md §2.5;裁定:
+// **plan 随数据走,core 零运行时半场**——core 的 `reconcileMemoryEntries`/`nextSyncBaseline`/
+// `screenInboundEntries` 是纯函数导出,持数据的一侧(本 server=DB 权威+per-(scope,peer) 游标)直接
+// import 调用算 plan 并执行 CAS;API 面全在 server,core 的承诺=纯函数语义稳定。
+//
+// 协议(POST /v1/memory/sync/:scope,http/server.ts 持路由/鉴权/验型;本模块只吃已验型请求):
+//   请求 = { peer, baseRevs, entries[], deletes[] } —— TOC 本地引擎按**自己的**游标把 push 半场打过来:
+//     entries = 自 baseRevs 以来本地新增/变更的条目全量;deletes = 本地删除(tombstone)的 id
+//     (CAS 基线 = baseRevs[id],所以 deletes ⊆ baseRevs 键——验型层已保证)。
+//   响应 = { applied[], conflicts[], serverEntries[], serverDeletes[], cursor } —— 一个 RTT 双向:
+//     serverEntries/serverDeletes = 中心侧自 baseRevs 以来变过/删过的条目 = 本地的 pull 半场。
+//
+// 与 §2.5 草案的两处**诚实偏离**(按 core JSDoc 实况,不硬凑草案):
+//   ① 响应加 `serverDeletes[]`:core MemorySyncPlan.deleteRemote—— 没有删除传播腿,
+//     中心侧删除永远过不去、每轮重摆同一状态 = livelock;草案响应形状缺这条腿。
+//   ② 响应加 `cursor`(本轮落库的 per-(scope,peer) 新基线):客户端应用完 pull 半场后持久化为
+//     自己的游标——它自己算不出(不持有中心全集)。
+//
+// 游标推进纪律(nextSyncBaseline 的 JSDoc 假设「POST-round 双方都已应用」,但响应发出时客户端还
+// **没有**应用 pull 半场——直接乐观推进会在客户端应用失败时把它的旧条目误判为「客户端改过」而回灌
+// 中心 = 数据回退):对 pull 半场(plan.push/plan.deleteRemote)的 id **保留旧基线**。两种客户端结局
+// 都收敛且零回退:客户端应用了 ⇒ 下轮 identical revs → no-op+基线推进;没应用 ⇒ 下轮干净重推。
+//
+// 执行序(任务书①-⑤):
+//   ① screenInboundEntries 入站门(拒 = 该条入 conflicts 上报,不落库不入队——门拒是终态)+
+//     rev 诚实校验(rev = core computeEntryRev 的内容哈希契约;谎报的 rev 会破坏 identical-revs
+//     收敛判定,按条拒入 conflicts,批内其余照常——applyPatches 的 per-patch 非致命姿势);
+//   ② 过门条目按 baseRevs[id] CAS applyPatches(基线有 ⇒ update+baseRev;基线无 ⇒ add——core
+//     MemorySyncPlan JSDoc 的 CAS 纪律原文:absent from the baseline ⇒ plain add);
+//   ③ deletes 同 CAS(plan.deleteLocal 的 {id, baseRev} → delete patch);
+//   ④ reconcileMemoryEntries(baseRevs, 中心集, 对端视图) 算双向 plan(对端视图 = push 条目 +
+//     「基线未提及 id 钉在基线 rev」的合成 stub——stub 永远不会被 pull/delete 判定选中,只参与
+//     rev 对比);⑤ nextSyncBaseline + 保留纪律 → putCursor。
+//
+// putCursor 失败于 applyPatches 之后 = 补丁已落、游标陈旧:向上抛(路由 500),客户端按同一
+// baseRevs 重放即幂等自愈(identical revs 全程 no-op)——游标写不是本轮正确性的一部分。
 import { computeEntryRev, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
 import { exportMemoryScope } from "./memory-export.js";
+// ── 验型(HTTP 面的 422 判据;返回 error 字符串而非 throw——validateUserSkills 姿势) ──────────
+/** 一轮 push 的条目数上限 = core REMOTE_HARVEST_MAX_FILES 同款口径(一个 scope 的文件面上限 500;
+ *  同步一轮打满全集也在此内)。deletes 上限同基数放宽(全集删除也要能一轮表达)。 */
 export const MEMORY_SYNC_MAX_ENTRIES = 500;
 export const MEMORY_SYNC_MAX_DELETES = 2000;
+/** Shape-validate + NORMALIZE the request body (picked-not-spread:只挑认识的字段重建,body 上的
+ *  多余键绝不透传进数据面)。`scope` = 路径上已过 owner 门的 scope——每个条目的 scope 必须逐字
+ *  等于它(否则一个 owner-gated 路由就成了跨租户写门)。 */
 export function parseMemorySyncRequest(body, scope) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be a JSON object { peer, baseRevs, entries, deletes }" };
@@ -104,12 +146,21 @@ export function parseMemorySyncRequest(body, scope) {
     }
     return { ok: true, value: { peer, baseRevs, entries, deletes, ...(pull !== undefined ? { pull } : {}) } };
 }
+// ── 执行内核 ─────────────────────────────────────────────────────────────────────────────────
+/** 基线 stub:对端在基线上、本轮未提及(或被门拒钉回基线)的 id 的合成占位。只有 id/rev 参与
+ *  reconcile 判定;rev === baseRevs[id] ⇒ remoteChanged 恒 false ⇒ 永不被 pull/deleteLocal 选中,
+ *  身体永不落任何盘。 */
 function baselineStub(id, rev, scope, slug) {
     return { id, rev, scope, slug: slug ?? `sync-baseline-stub/${id}`, frontmatter: {}, body: "" };
 }
+/**
+ * One full sync round for one (scope, peer). `backend` = 中心侧 entry plane(DB 权威),`cursors` =
+ * per-(scope,peer) 游标面(sync_cursors)。纯数据参数进(路由已完成鉴权/owner 门/验型),响应形状出。
+ */
 export async function performMemorySync(backend, cursors, scope, req, now = Date.now) {
     const conflicts = [];
-    const rejected = new Map();
+    // ① 入站门 + rev 诚实校验(拒 = 终态:上报 conflicts,不落库不入队;per-entry 非致命,批内其余照常)。
+    const rejected = new Map(); // id → reason
     for (const e of req.entries) {
         const computed = computeEntryRev(e);
         if (computed !== e.rev)
@@ -125,16 +176,23 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
         conflicts.push({ id, reason, ...(base !== undefined ? { baseRev: base } : {}) });
     }
     const clean = req.entries.filter((e) => !rejected.has(e.id));
+    // 中心侧全集(export 面同款读姿势:listHeaders → getByIds → scope 过滤纵深)。
     const central = await exportMemoryScope(backend, scope);
     const centralById = new Map(central.map((e) => [e.id, e]));
+    // 对端视图:push 条目 + 基线 stub。门拒的 id 钉回基线(有基线时)——绝不能让「拒收」被误判成
+    // 「对端删除」而触发 deleteLocal(中心副本会被误删);新条目被拒 = 视图里干脆没有它。
     const peerView = [...clean];
     const pushedOrDeleted = new Set([...clean.map((e) => e.id), ...req.deletes]);
     for (const [id, rev] of Object.entries(req.baseRevs)) {
         if (pushedOrDeleted.has(id))
             continue;
+        // 未提及 = 对端仍在基线(含被门拒钉回的);stub 只有 rev 参与判定。
         peerView.push(baselineStub(id, rev, scope, centralById.get(id)?.slug));
     }
+    // ④(判定先行)三方 reconcile:local = 中心,remote = 对端视图。
     const plan = reconcileMemoryEntries(req.baseRevs, central, peerView);
+    // ②③ 中心半场执行:pull(采纳对端 push)按 baseRevs CAS;deleteLocal 同 CAS。backend.applyPatches
+    // 的 per-id CAS 是并发纵深——本函数读集与落库之间挤进来的写者会让 baseRev 失配 = 冲突上报,绝不盲写。
     const patches = [
         ...plan.pull.map((e) => {
             const base = req.baseRevs[e.id];
@@ -146,6 +204,8 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
     for (const c of report.conflicts) {
         conflicts.push({ id: c.id, reason: c.reason, ...(c.baseRev !== undefined ? { baseRev: c.baseRev } : {}), ...(c.currentRev !== undefined ? { currentRev: c.currentRev } : {}) });
     }
+    // plan 冲突(双边自基线各自变过 / 删改相撞):currentRev = 中心当前 rev(中心已删则缺席),
+    // 客户端拿它走 §3 ladder(败者铸 sibling)。
     for (const c of plan.conflicts) {
         conflicts.push({
             id: c.id,
@@ -158,6 +218,7 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
             ...(c.local !== undefined ? { currentRev: c.local.rev } : {}),
         });
     }
+    // ⑤ 游标:POST-round 中心集(内存推演,只按 applied 口径——CAS 输掉的补丁不算)× 对端视图。
     const appliedByKey = new Set(report.applied.map((a) => `${a.op}\x1f${a.id}`));
     const appliedPatch = new Map();
     for (const p of patches)
@@ -174,6 +235,9 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
             centralPost.push(p.entry);
     }
     const nextBase = nextSyncBaseline(centralPost, peerView);
+    // 保留纪律(头注):pull 半场的 id 保留旧基线——客户端此刻还没应用 serverEntries/serverDeletes,
+    // 乐观推进会在「客户端没应用」的下一轮把它的旧条目误判成新改动回灌中心(数据回退)。保留旧基线
+    // 两种结局都收敛:应用了 ⇒ identical revs no-op+推进;没应用 ⇒ 干净重推/重删。
     for (const e of plan.push) {
         const base = req.baseRevs[e.id];
         if (base !== undefined)
@@ -181,6 +245,11 @@ export async function performMemorySync(backend, cursors, scope, req, now = Date
     }
     for (const d of plan.deleteRemote)
         nextBase[d.id] = d.baseRev;
+    // ⑥ S2.5 pull 分批(契约 settled 2026-07-14):serverEntries 稳定序(id 升序)截 limit;deletes 轻不截。
+    // cursor 精确化约束(core 回执):**不得预填未交付条目的 rev**——有基线的 pull id 上面的保留纪律已经
+    // 钉回旧值;无基线的新条目若未交付,必须从 nextBase 整个剔除(预填=客户端应用交付子集后持久化整张
+    // cursor,下轮把未交付 id 误判「baseline 已知」⇒ 该条目永久漏拉)。已交付的新条目保持 nextSyncBaseline
+    // 值(客户端按纪律应用完交付集才持久化 cursor,安全)。
     let serverEntries = plan.push;
     let pullTruncated = false;
     if (req.pull !== undefined && plan.push.length > req.pull.limit) {

package/dist/model-select.d.ts

@@ -1,9 +1,48 @@
+/**
+ * Resolve the model ref for a task spec from the request (CLI `/model` picker + `run --model`).
+ *
+ * Priority (a deliberate selection beats incidental free text):
+ *   1) an explicit, allow-listed `body.model` (the picker / `--model <ref>` flag),
+ *   2) an inline `@name` mention in the objective (core's `parseModelMention`),
+ *   3) the `default` role.
+ *
+ * Security: BOTH the explicit field and the @mention are gated by the SAME catalog (`config.models` keys), so
+ * untrusted body/text can pick WHICH configured model but can never inject a baseUrl/apiKey (parseModelMention
+ * only ever returns an allow-listed catalog name).
+ *
+ * [865]②(clay 生产实锤:onboard 选 kimi 实跑 Qwen):
+ *  - explicit ref 走 name+id 双键索引({@link matchCatalogModel})——壳 boot 回读的 mainLoopModel 是 **id 形**,
+ *    目录键是 **name 形**,单键索引把 id 形请求当「未知」静默落 default = session 中途静默换模型(最恶性的
+ *    上下文污染路径)。
+ *  - 真未知不再无声:FRESH submit 在 HTTP 门 400 fail-loud(带 available 列表,http/server.ts);本函数保持
+ *    不 throw(RESUME 重放持久化 body 不过 400 门——模型可能事后被移出目录,砖死 resume 比降级更糟),但把
+ *    未知 ref 透出给调用方(`unknownExplicit`),resolveSpec 记 warn——降级永远可见,绝不静默。
+ *
+ * Returns the chosen model ref AND the objective with any `@mention` stripped (parseModelMention's cleanedText).
+ *
+ * 🔴 Was a real defect: resolveSpec previously read ONLY the inline @mention, so `body.model` (the picker + the
+ * `--model` flag) was SILENTLY DROPPED — the picker UX was a no-op server-side. This restores it.
+ */
 export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>): {
     model: string;
     cleanedObjective: string;
     unknownExplicit?: string;
 };
+/**
+ * [865]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
+ *  - name 命中用 Object.hasOwn(🔴 不用真值索引:Object.prototype 继承键 "constructor"/"__proto__" 等在裸
+ *    索引下是真值,会绕过 allow-list——沿袭原实现的纪律)。
+ *  - id 命中扫目录值(`Model.id`),跳过 "default" 别名键(它与其指向的真身共享 id,解析到别名会让 /model
+ *    面板与实际路由再度撕裂);同 id 多 name 时取目录序第一个(与 /v1/models 列表序一致,确定性)。
+ */
 export declare function matchCatalogModel(ref: string, catalog: Record<string, unknown>): string | undefined;
+/**
+ * vision precheck: a catalog model can read images iff its `input` modality list
+ * includes `"image"` (the SAME test as the vision capability on GET /v1/models — `server.ts`). FALSE-SAFE on
+ * missing/unknown modality info: returns `true` (do NOT block) — only an EXPLICIT text-only `input` triggers the
+ * precheck, so a model that never declared its modalities is never wrongly 422'd. Lets a request with images 422
+ * up-front instead of hitting the downstream gateway as an opaque deserialize 400 on a text-only model.
+ */
 export declare function modelSupportsImages(model: {
     input?: unknown;
 } | undefined): boolean;