@sema-agent/server 7.146.0 → 7.148.0

package/dist/leader/wire.js

@@ -21,9 +21,46 @@ import { attachRepairLoopDeps } from "./repair-wire.js";
 import { routePlanWithFallback, validateSubtasks } from "./planner.js";
 import { createEngineNoticeSeat } from "../boot/runner-deps.js";
 import { buildInternalRunCtx } from "../internal-run-env.js";
-import { currentPrincipal } from "../observability/principal-context.js";
+import { currentSubject } from "../observability/principal-context.js";
+import { partsOf } from "../owner-brands.js";
+import { taskSpecIdentityOf } from "../engine-identity.js";
 import { redactHead } from "../observability/run-terminal.js";
 const REPAIR_LOOP_WIRED = true;
+export const LEADER_APPROVAL_SCOPE = "_leader";
+export function leaderResourceScope(workerId) {
+    return `_leader-resource-${workerId}`;
+}
+const PARK_DRAIN_MAX = 64;
+export function createLeaderParkExpirer(store) {
+    return async (workers) => {
+        let expired = 0;
+        let lost = 0;
+        const seen = new Set();
+        for (const w of workers) {
+            for (const scope of [LEADER_APPROVAL_SCOPE, leaderResourceScope(w.workerId)]) {
+                const key = `${w.sessionId}\u0000${scope}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const tried = new Set();
+                for (let i = 0;; i++) {
+                    const token = await store.findPendingTokenBySession(w.sessionId, scope);
+                    if (token === null || token === undefined)
+                        break;
+                    if (tried.has(token) || i >= PARK_DRAIN_MAX) {
+                        throw new Error(`leader park expiry: the checkpoint store kept answering pending token for session ${w.sessionId} in scope ${scope} after expiring it — refusing to spin (expired=${expired}, lost=${lost})`);
+                    }
+                    tried.add(token);
+                    if (await store.expire(token, scope))
+                        expired++;
+                    else
+                        lost++;
+                }
+            }
+        }
+        return { expired, lost };
+    };
+}
 const sh = (env) => async (cmd) => {
     const r = await env.exec(`bash -lc ${JSON.stringify(cmd)}`);
     if (!r.ok)
@@ -111,20 +148,20 @@ export function createCoordinatorPush(durableRemote, targetRef, ident) {
         const dir = mkdtempSync(join(tmpdir(), "leader-coord-"));
         const gitEnv = { ...gitSubprocessEnv({ site: "server.leader.git-push", isolateConfig: false }), LC_ALL: "C" };
         try {
-            execFileSync("git", ["clone", "-q", durableRemote, dir], { env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
-            execFileSync("git", ["-C", dir, "config", "user.name", ident.name], { env: gitEnv, timeout: LEADER_PUSH_LOCAL_TIMEOUT_MS });
-            execFileSync("git", ["-C", dir, "config", "user.email", ident.email], { env: gitEnv, timeout: LEADER_PUSH_LOCAL_TIMEOUT_MS });
+            execFileSync("git", ["clone", "-q", durableRemote, dir], { stdio: "pipe", env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
+            execFileSync("git", ["-C", dir, "config", "user.name", ident.name], { stdio: "pipe", env: gitEnv, timeout: LEADER_PUSH_LOCAL_TIMEOUT_MS });
+            execFileSync("git", ["-C", dir, "config", "user.email", ident.email], { stdio: "pipe", env: gitEnv, timeout: LEADER_PUSH_LOCAL_TIMEOUT_MS });
             writeFileSync(join(dir, ".leader.patch"), integratedPatch);
-            execFileSync("git", ["-C", dir, "am", "--3way", ".leader.patch"], { env: gitEnv, timeout: LEADER_PUSH_LOCAL_TIMEOUT_MS });
+            execFileSync("git", ["-C", dir, "am", "--3way", ".leader.patch"], { stdio: "pipe", env: gitEnv, timeout: LEADER_PUSH_LOCAL_TIMEOUT_MS });
             rmSync(join(dir, ".leader.patch"));
             const ref = targetRef ?? "refs/heads/main";
-            const ls = execFileSync("git", ["-C", dir, "ls-remote", "--refs", "origin", ref], { encoding: "utf8", env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
+            const ls = execFileSync("git", ["-C", dir, "ls-remote", "--refs", "origin", ref], { stdio: "pipe", encoding: "utf8", env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
             const exists = ls.split("\n").some((l) => l.split("\t")[1] === ref);
             if (exists) {
-                execFileSync("git", ["-C", dir, "push", `--force-with-lease=${ref}:${baseSha}`, "origin", `HEAD:${ref}`], { env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
+                execFileSync("git", ["-C", dir, "push", `--force-with-lease=${ref}:${baseSha}`, "origin", `HEAD:${ref}`], { stdio: "pipe", env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
             }
             else {
-                execFileSync("git", ["-C", dir, "push", `--force-with-lease=${ref}:`, "origin", `HEAD:${ref}`], { env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
+                execFileSync("git", ["-C", dir, "push", `--force-with-lease=${ref}:`, "origin", `HEAD:${ref}`], { stdio: "pipe", env: gitEnv, timeout: LEADER_PUSH_NETWORK_TIMEOUT_MS });
             }
             return { ok: true, ref };
         }
@@ -168,20 +205,21 @@ export function createLeaderRunner(cfg) {
     const deploymentPostureSeat = () => cfg.deploymentPosture?.() ?? {};
     const tracerSeat = cfg.tracer ? { tracer: cfg.tracer } : {};
     const modsSeat = cfg.mods ? { mods: cfg.mods } : {};
+    const handsSeat = cfg.hands ? { hands: cfg.hands } : {};
     const servedTableSeat = { models: cfg.models, roles: cfg.roles, ...(cfg.tiers ? { tiers: cfg.tiers } : {}) };
     const usageWindowSeat = cfg.usageWindows && cfg.usageWindowStore ? { usageWindows: cfg.usageWindows, usageWindowStore: cfg.usageWindowStore } : {};
     const promptSourceSeat = cfg.promptSource ? { promptSource: cfg.promptSource } : {};
     const onErrorSeat = cfg.onError ? { onError: cfg.onError } : {};
     const principalSpec = () => {
-        const p = currentPrincipal();
-        return p ? { principal: p } : {};
+        const subject = currentSubject();
+        return taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject));
     };
     const mkRepair = (rawEnv, repoDir, oracleFiles, entry) => {
         if (repairRounds <= 0)
             return undefined;
         return {
             maxRounds: repairRounds,
-            run: async ({ round, errorText, testCmd }) => {
+            run: async ({ round, errorText, testCmd, signal }) => {
                 for (const f of oracleFiles) {
                     await rawEnv.remove(f.path).catch(() => { });
                     const ex = await rawEnv.exists(f.path);
@@ -189,7 +227,7 @@ export function createLeaderRunner(cfg) {
                         throw new Error(`oracle still present after remove (${f.path}) — refusing repair (measurement integrity)`);
                 }
                 try {
-                    const runner = new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, executionEnv: rawEnv, rootPath: repoDir });
+                    const runner = new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat, executionEnv: rawEnv, rootPath: repoDir });
                     const objective = [
                         `The integrated project at ${repoDir} fails its build/test. Make the MINIMAL change to the working tree so this command exits 0 (cd into the repo and run it yourself to confirm):`,
                         `  ${testCmd}`,
@@ -203,6 +241,7 @@ export function createLeaderRunner(cfg) {
                         objective,
                         ...principalSpec(),
                         sessionId: `leader-repair-${Date.now()}-${round}`,
+                        signal,
                         limits: { maxCostUsd: repairBudgetUsd, maxWalltimeMs: Math.max(300_000, Math.floor(leaderTimeoutMs / 2)) },
                     }, entry))
                         .result();
@@ -220,7 +259,7 @@ export function createLeaderRunner(cfg) {
             },
         };
     };
-    return async (raw) => {
+    return async (raw, signal) => {
         const body = raw;
         if (!body.objective || !body.durableRemote || !body.testCmd || !body.seedCmd || !body.baseSha) {
             return { ok: false, reports: [], cancelled: false, error: "request must provide objective, durableRemote, baseSha, testCmd, seedCmd" };
@@ -256,12 +295,13 @@ export function createLeaderRunner(cfg) {
             if (Array.isArray(body.subtasks) && body.subtasks.length > 0) {
                 return validateSubtasks(body.subtasks);
             }
-            const planRunner = new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat });
+            const planRunner = new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat });
             const runRoute = async (prompt) => {
                 const res = await planRunner.runTaskStream({
                     objective: prompt,
                     ...principalSpec(),
                     sessionId: `leader-route-${Date.now()}`,
+                    signal,
                     ...(cfg.routerModel ? { model: cfg.routerModel } : { modelRole: "classifier" }),
                 }).result();
                 return res.result ?? "";
@@ -285,7 +325,7 @@ export function createLeaderRunner(cfg) {
                 durableSpec = {
                     toolPolicy: combinePolicies(createDurableQuestionPolicy(), createDurableAskPolicy({ requireApproval: d.requireApproval, ...(d.deny ? { deny: d.deny } : {}), ...(d.autoBudget ? { autoBudget: d.autoBudget } : {}), ...(d.neverAuto ? { neverAuto: d.neverAuto } : {}) })),
                     checkpointStore: d.checkpointStore,
-                    durableApproval: { scope: "_leader", ...(d.ttlMs ? { ttlMs: d.ttlMs } : {}) },
+                    durableApproval: { scope: LEADER_APPROVAL_SCOPE, ...(d.ttlMs ? { ttlMs: d.ttlMs } : {}) },
                     onQuestion: QUESTION_AWAITS_RESUME,
                 };
                 await d.checkpointStore.putCtx(sessionId, storedResumeCtx).catch((e) => {
@@ -300,7 +340,7 @@ export function createLeaderRunner(cfg) {
             if (resourceCfg && !repairLoopActive && durable && cfg.toolResultStore && cfg.sessionStore) {
                 resourceSpec = {
                     checkpointStore: durable.checkpointStore,
-                    resourceSuspend: { scope: `_leader-resource-${sub.workerId}`, totalBudgetUsd: resourceCfg.totalBudgetUsd },
+                    resourceSuspend: { scope: leaderResourceScope(sub.workerId), totalBudgetUsd: resourceCfg.totalBudgetUsd },
                     limits: { ...workerLimits.limits, maxCostUsd: resourceCfg.sliceMaxCostUsd },
                     maxSuspends: resourceCfg.maxSuspends,
                 };
@@ -350,7 +390,7 @@ export function createLeaderRunner(cfg) {
                     workerId: sub.workerId, sessionId, branch: sub.branch,
                     baseSha,
                     runner: keepCtxWarm(new Runner({
-                        brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat,
+                        brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat,
                         ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}),
                         ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}),
                         executionEnvFactory: async (ctx) => {
@@ -375,7 +415,7 @@ export function createLeaderRunner(cfg) {
             const baseSha = await sh(env)(`cd ${repo} && git rev-parse HEAD`);
             return {
                 workerId: sub.workerId, sessionId, branch: sub.branch, baseSha,
-                runner: keepCtxWarm(new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}), ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}), executionEnv: env })),
+                runner: keepCtxWarm(new Runner({ brain: cfg.brain, ...servedTableSeat, pricing: cfg.pricing, ...onNoticeSeat, ...governanceSeat, ...deploymentPostureSeat(), ...tracerSeat, ...usageWindowSeat, ...promptSourceSeat, ...onErrorSeat, ...modsSeat, ...handsSeat, ...(cfg.toolResultStore ? { toolResultStore: cfg.toolResultStore } : {}), ...(cfg.sessionStore ? { sessionStore: cfg.sessionStore } : {}), executionEnv: env })),
                 diffEnv: env,
                 destroy: () => env.destroy().then(() => { }),
                 spec: withLeaderLeg({ ...workerLimits, ...sub.spec, ...durableSpec, ...resourceSpec, ...principalSpec() }, resumeBody),
@@ -419,6 +459,7 @@ export function createLeaderRunner(cfg) {
         const push = createCoordinatorPush(body.durableRemote, body.targetRef, ident);
         const deps = {
             entry,
+            signal,
             plan,
             provisionWorker,
             provisionIntegrationSandbox,

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/memory-embedder-reembed.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `memory-embedder-reembed.ts` —— 「清列重嵌」**确认口令**的单一属主:`MEMORY_EMBEDDER_REEMBED=<model>/<dimensions>`。
+ *
+ * ## 律(一句)
+ *
+ * embedder 指纹门(`plugins/memory-embedder-fingerprint.ts`)从不凭自己的判断清列:记下的身份与配置的身份对不上
+ * (changed / unattributed / unreadable 三态)⇒ 拒启;唯一出路是运维显式确认「把向量列清掉、按**这个**身份重嵌」——
+ * 口令的值就是**配置的那个身份**。口令绑定身份,所以它天然是一次性的:清完并记下这个身份之后,下一次起服判「相等」,
+ * 口令不再有东西可确认;之后再换一次模型,留着的旧口令对不上新配置 ⇒ 起服拒(不会替下一次换模型静默清列)。
+ *
+ * ## 为什么是一只顶层叶模块
+ *
+ * 两个消费方在不同层:`config.ts` 在 boot 期解析并判口令(拼错 / 对不上配置 ⇒ 拒启),指纹门在拒句里**写出**这条口令。
+ * config 层不得值引 plugins 层;口令的读写形只有一份,两层各按需引 —— 这是本文件存在的全部理由。零依赖。
+ *
+ * 句子里写给运维**照抄**的那条赋值只有一个写者 {@link formatReembedAssignment}:值按 POSIX 单引号包起(模型名可以含空格 / `$` / 引号,
+ * 不包就粘不进 shell);引号只是 shell 的写法,shell 读完赋给 env 的值仍是 `<model>/<dimensions>` 本身(config 读的就是它)。
+ */
+/** 口令那一键的名字(config 读它、门的拒句写它)。 */
+export declare const MEMORY_EMBEDDER_REEMBED_ENV = "MEMORY_EMBEDDER_REEMBED";
+/** 口令所确认的身份形(与指纹门的 `EmbedderIdentity` 同形;本叶不引 zod)。 */
+export interface EmbedderIdentityToken {
+    readonly model: string;
+    readonly dimensions: number;
+}
+/** 身份 → 口令值:`<model>/<dimensions>`。模型名自身可以含 `/`(`BAAI/bge-m3`)—— 维度恒在**最后一个** `/` 之后。 */
+export declare function formatEmbedderIdentityToken(identity: EmbedderIdentityToken): string;
+/**
+ * 运维照抄的那条赋值:`MEMORY_EMBEDDER_REEMBED='<model>/<dimensions>'`。POSIX 单引号:值内唯一的元字符是 `'` 本身,写成 `'\''`
+ * (关引号、转义一个 `'`、再开引号)。拒句与 config 的出路句都经这里写,不各拼一份。
+ */
+export declare function formatReembedAssignment(identity: EmbedderIdentityToken): string;
+/**
+ * 口令值 → 身份;形不对 ⇒ `undefined`(调用方拒启并给出期望形,不猜)。判据:最后一个 `/` 之前非空(模型名),
+ * 之后是十进制正整数(无前导零、无符号、无空白)。`true` / `1` / `yes` 这类「开关形」一律不是口令。
+ */
+export declare function parseEmbedderIdentityToken(raw: string): EmbedderIdentityToken | undefined;
+//# sourceMappingURL=memory-embedder-reembed.d.ts.map

package/dist/memory-embedder-reembed.js

@@ -0,0 +1,20 @@
+export const MEMORY_EMBEDDER_REEMBED_ENV = "MEMORY_EMBEDDER_REEMBED";
+export function formatEmbedderIdentityToken(identity) {
+    return `${identity.model}/${identity.dimensions}`;
+}
+export function formatReembedAssignment(identity) {
+    return `${MEMORY_EMBEDDER_REEMBED_ENV}='${formatEmbedderIdentityToken(identity).replace(/'/g, "'\\''")}'`;
+}
+export function parseEmbedderIdentityToken(raw) {
+    const cut = raw.lastIndexOf("/");
+    if (cut <= 0)
+        return undefined;
+    const digits = raw.slice(cut + 1);
+    if (!/^[1-9][0-9]*$/.test(digits))
+        return undefined;
+    const dimensions = Number(digits);
+    if (!Number.isSafeInteger(dimensions))
+        return undefined;
+    return { model: raw.slice(0, cut), dimensions };
+}
+//# sourceMappingURL=memory-embedder-reembed.js.map

package/dist/memory-incident-sink.d.ts

@@ -1,31 +1,3 @@
-/**
- * 记忆引擎 **incident 席**在本仓的唯一落点形。
- *
- * ## 为什么要一只共用工厂(而不是每个宿主各写一行 `logger.warn`)
- * core 的记忆引擎有**两条**到宿主的披露路:
- *  · **mount 路**——`MemoryEngine` 自己的 `onIncident`,由 core 的 Runner 在 `prepare-memory` 里桥到
- *    `RunnerDeps.onError(err, { phase: "memory", sessionId })`(亲读 `dist/core/runner/prepare-memory.js`
- *    的 `const onEngineIncident = (err) => deps.onError?.(err, { phase: "memory", sessionId })`);
- *  · **无锁公开面路**——`FileMemoryEngineBackend` 的**构造期** `onIncident`,是那条腿上唯一的披露口
- *    (`adoptLayoutLocked` 取 `onIncident ?? this.onIncident`)。
- * 同一条事实(例如一次性的目录布局搬家)会按调用路径落到其中**一条**,而本仓有**两个宿主**
- * (HTTP 服务的 `boot/runner-deps.ts` 与 `run-local.ts`)各自持有 `onError` 座。四个落点各写一行 =
- * 四份会各自漂移的形;实际已经漂过一次:服务腿把整族印成 `memory_consolidation_failed`(只有一支是
- * consolidation),run-local 腿把整族印成 `engine_error` 并用 `String(err)` 抹掉 `err.code`。
- *
- * ## 形(一处定义,四处引用)
- * `memory_engine_incident` + `{ sessionId?, code?, detail }`,并计 `memory_engine_incident_total{code?}`。
- * 🔴 `code` 是**结构化字段**而不是被折进散文:它是运维唯一能按名告警的那一位,而这一族里最要紧的几条
- * (一次性布局搬家、无主根内容、控制面写失败)一辈子只发生一次 —— 折平就等于没说。
- * 码的读法与 `boot/runner-deps.ts` 的 `onError` 汇点其余七条行**同一只**(`terminal.ts` 的 `codeFieldOf`:不抛的读口 + 码判官 `isCodeToken`):是码才带;
- * 无码(core 里有大量不带 `.code` 的记忆相 Error)、不是串 / 空串、非 `Error` 抛出物、读取时抛、或带的不是码(超长 / 含空白 / 凭据形 —— 引擎错上的 `code` 是别人写的串)⇒ 行里**没有** `code` 键、
- * 计数**没有** `code` 标签:不编码,也不写 `null` / `"none"` 之类的占位。
- *
- * ⚠️ 与三只 **operator 面**引擎座(`memory_compliance_incident` / `memory_origin_incident` /
- * `memory_consolidation_incident`)**事件名刻意不合并**:那三条的事件名回答「哪一张操作面」,是三个产品面的
- * 分辨位;本工厂回答「引擎事故席」,是同一件事的四个落点。合并会丢掉前者的分辨位。三座有自己的工厂
- * {@link createOperatorFaceIncidentSink}(事件名由装配处点名),`code` 位与本工厂读同一只 `codeFieldOf`。
- */
 import type { Logger } from "./observability/logger.js";
 import type { Metrics } from "./observability/metrics.js";
 /** 落点依赖。`metrics` 可缺席(run-local 的 backend 构造期座就没有计数面的消费者)。 */

package/dist/memory-incident-sink.js

@@ -1,3 +1,5 @@
+import { recordFailOpen } from "./observability/fail-open.js";
+import { isStoreFormRefusalCode } from "./memory-store-refusal.js";
 import { redactIncarnations } from "./session-incarnation.js";
 import { codeFieldOf } from "./terminal.js";
 import { seatText } from "./trace/exit-seat.js";
@@ -10,6 +12,9 @@ export function createMemoryEngineIncidentSink(deps) {
             detail: redactIncarnations(String(err)),
         });
         deps.metrics?.inc("memory_engine_incident_total", { ...codeField });
+        const { code } = codeField;
+        if (isStoreFormRefusalCode(code))
+            recordFailOpen("server.memory.store-form-refused-step-skipped", `code=${code}`);
     };
 }
 export function createOperatorFaceIncidentSink(deps, event) {

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-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[];
@@ -57,7 +58,7 @@ export declare function memoryScopeFor(config: ServiceConfig, principal?: string
  *
  * **一条规则,与车道无关**(主会话 09-23 裁 ②):项目根 = spec 解析出的**真任务根**(`boot/resolve-spec.ts`
  * 的 `realTaskRootOf`,[ref] 属主;run-local 腿 = 它的 `workspaceDir`)。本进程读得到这个根 ⇒ 求项目身份并铸项目层键
- * (in-process 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是「项目 = 任务根指向的地方」,不需要另一个词);
+ * (无手的 `none` 车道的真任务根是 `process.cwd()`,读得到,所以照常铸 —— 它的语义就是「项目 = 任务根指向的地方」,不需要另一个词);
  * 读不到(根在沙箱/设备盘上,或 host 车道会话没登记 cwd、spec 期还不知道根)⇒ 调用方传 `undefined` ⇒ `{ absent: "unreadable" }`,
  * core 铸 operator 通知 `memory.project_scope_absent`,写照常落全局层 —— **响亮**,不是静默落 `local`。
  *
@@ -106,7 +107,7 @@ export declare function replicatesProjectLayersOf(coverage: MemoryReplicationCov
  * (`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
- * (the lane's file plane IS this worker's fs — `in-process` / `host`), `dark` = split + fail-closed, `forced` =
+ * (the lane's file plane IS this worker's fs — `none` / `host`), `dark` = split + fail-closed, `forced` =
  * split + operator override.
  * The plane question reads the execution environment block (`hostLocalPaths`, sole author `capabilitiesFor`) — it used to be the
  * hand-written synonym `lane === undefined || lane === "host"`; readings are unchanged lane by lane.
@@ -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";
@@ -68,7 +69,7 @@ export function replicatesProjectLayersOf(coverage, owner) {
     }
 }
 export function memoryEngineRemoteLanePosture(config) {
-    const lane = executionLaneOf(config.remoteExec?.provider);
+    const lane = config.remoteExec.provider;
     if (capabilitiesFor(config).hostLocalPaths)
         return undefined;
     return { lane, posture: config.memoryEngineRemoteLaneAllowed === true ? "forced" : "dark" };
@@ -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,13 +1,19 @@
 /**
- * **店形拒**(store-form refusal)在本仓的唯一读法属主(纯叶:零 http / 零 boot 依赖)—— core 一只铸点(`layout.ts` `storeFormRefusal`)的**两码一族**:
+ * **店形拒**(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 打开 / 引擎首次
  *    挂载之后被改指)⇒ 引擎对落点在外的删 / 写 / 重放 / 自身写一律**不做**;
  *  · `memory.scope_home_not_directory`(core 7.44.0 [ref]):一只 scope home(`<memoryDir>/<label>`)不是真目录 —— 被换成软链 / 普通文件 / 特殊文件
  *    (`detail.form` ∈ `symlink` | `file` | `other`,`lstat` 判、不跟链)。修前 core 对这一形抛不带码的 `ControlPlaneCorruptError`(与真控制面损坏同类同形),
- *    平铺布局(条目直接住在 home 里)于是答 500,而同一换法在嵌套布局下一层答 409 —— 现在两布局同答这一码。
- * 两码的形相同:普通 `Error` + `.code` + `.detail`(`{ path }`;home 那一码多 `form`),**句子以码领头、不含任何宿主路径**(core 7.44.0 起,
+ *    平铺布局(条目直接住在 home 里)于是答 500,而同一换法在嵌套布局下一层答 409 —— 现在两布局同答这一码;
+ *  · `memory.control_plane_links_unsupported`(core 7.65.0):记忆控制面所在的文件系统不能建硬链接 ⇒ File 记忆店在打开处被拒(构造期抛 ⇒ 起服拒;
+ *    引擎 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`)。
+ * 盘形修好之前重发恒拒。本仓据此一条规则:族内同答、409、码原样;路径只进运维行(HTTP 映射一处,见 `http/memory-store-refusal-reply.ts`)。
  *
  * ## 两条到达车道,两个读者(本模块各给一只,别处不许再写第二份判据)
  *  ① **抛出面**(抹除 / 出处 / 外源列表 / 清标 / bundle 导出导入 —— 凡触 store 树的 backend 面):`.code` 就是码
@@ -36,6 +42,16 @@
  */
 import { type ScopeHomeForm, type StoreFormRefusalCode } from "@sema-agent/core";
 import type { Logger } from "./observability/logger.js";
+/**
+ * 词表与型全取 core 包根([ref] / core 7.45.0 [ref];此前 core 不导出,本文件自写两只码字面量与族表 —— 那份手抄随本版退役):
+ *  · 族 = `STORE_FORM_REFUSAL_CODES`,型 `StoreFormRefusalCode`;族判只读族表、不点成员(族的成员归 core,不在这里由人裁)。HTTP 映射逐码写字面量
+ *    (错误码目录门扫源码字面量,变量态的码对它隐形),两处穷举:`http/memory-store-refusal-reply.ts`(operator 面)与 `http/memory-compliance-failure-reply.ts`(会话所有者面)——
+ *    引擎加一码 ⇒ 两处编译红、各补一臂(引擎 7.65.0 的第三码 `CONTROL_PLANE_LINKS_UNSUPPORTED` 就是这样补的);记忆相上撞到它的 fail-open 臂〔mount 开店被拒 / mount 后的一步记忆活被拒〕在 `memory-incident-sink.ts` 登记;
+ *  · 抛出面的形 = `StoreFormRefusal`(普通 `Error` + `code` + `detail: StoreFormRefusalDetail`);
+ *  · `detail.form` 的闭集 = `SCOPE_HOME_FORMS`(型 `ScopeHomeForm`):闭集内原样读,闭集外不读(引擎说不出的词不进运维行)。
+ */
+/** 族判(族表 `STORE_FORM_REFUSAL_CODES` 的唯一判据):{@link storeFormRefusalOf} 用它判抛出面的 `.code`;记忆事故席用它判 `codeFieldOf` 已经读出的码(那一席码只许读一次)。 */
+export declare const isStoreFormRefusalCode: (code: unknown) => code is StoreFormRefusalCode;
 /** 一次店形拒的读数(纯数据)。`path` / `form` 取自 core 的 `detail`(读不出 ⇒ `undefined`,不猜、不从句子里抠)。 */
 export interface StoreFormRefusalReading {
     readonly code: StoreFormRefusalCode;

package/dist/memory-store-refusal.js

@@ -1,5 +1,5 @@
 import { SCOPE_HOME_FORMS, STORE_FORM_REFUSAL_CODES } from "@sema-agent/core";
-const isStoreFormRefusalCode = (code) => STORE_FORM_REFUSAL_CODES.includes(code);
+export const isStoreFormRefusalCode = (code) => STORE_FORM_REFUSAL_CODES.includes(code);
 const isScopeHomeForm = (form) => SCOPE_HOME_FORMS.includes(form);
 export function storeFormRefusalOf(err) {
     if (!(err instanceof Error))