@sema-agent/server 7.138.0 → 7.139.0

package/dist/memory-sync-client.js

@@ -1,110 +1,202 @@
 import { createHash, randomBytes } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rmdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
+import { carriesCredential, syncMemoryScope, } from "@sema-agent/core";
 import { replicationCovers } from "./memory-scope.js";
 import { parseProjectLayerKey } from "./project-layer-key.js";
-const CURSOR_MISMATCH_CODE = "config.memory_sync_cursor_mismatch";
-const CURSOR_PREDATES_STORE_NOTICE = "memory_sync_cursor_predates_store";
-const CURSOR_PREDATES_STORE_OUTS = "this layer's sync baseline was written before sync cursors carried a store binding, so the layer does not sync until the operator picks one of two ways out: " +
-    "(1) run one sync round on the previous server version so deletions made since the last round reach the other side, then delete this file; " +
-    "(2) delete this file now to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
-    "and entries deleted on one side since the last round come back from the other side";
-export const DEFAULT_MEMORY_SYNC_PEER = "central";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
+import { pathBaseUrlRefusal } from "./web-admin-client/center-request.js";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
+export function memorySyncPeerOf(url) {
+    const refusal = pathBaseUrlRefusal("memory sync: MEMORY_SYNC_URL", url);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    const u = new URL(url);
+    const identity = `${u.origin}${u.pathname.replace(/\/+$/, "")}`;
+    if (carriesCredential(identity)) {
+        throw new Error("memory sync: MEMORY_SYNC_URL holds a credential (a token-shaped part of its path) — the sync peer identity travels verbatim in every request body and " +
+            "cursor, so it is refused, never cleaned: put the token in MEMORY_SYNC_TOKEN and set MEMORY_SYNC_URL to the central base address itself");
+    }
+    if (identity.length > MEMORY_SYNC_PEER_COLUMN_CHARS) {
+        throw new Error(`memory sync: MEMORY_SYNC_URL normalizes to ${identity.length} characters — the peer identity is the central request's peer, which holds at most ${MEMORY_SYNC_PEER_COLUMN_CHARS}: use a shorter base URL`);
+    }
+    return identity;
+}
+export function buildMemorySyncEnabledFields(peer, scope, cursorPath) {
+    return { peer: buildDisplaySafeUrl(peer), scope, cursorPath };
+}
 export function createMemorySyncTransport(opts) {
-    const base = opts.url.replace(/\/+$/, "");
+    const peer = memorySyncPeerOf(opts.url);
     const fetchImpl = opts.fetchImpl ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 60_000;
-    return async (path, body) => {
-        const res = await fetchImpl(`${base}${path}`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        const text = await res.text();
-        if (!res.ok)
-            throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
-        return JSON.parse(text);
-    };
+    return Object.freeze({
+        peer,
+        async post(path, body) {
+            const res = await fetchImpl(`${peer}${path}`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = await res.text();
+            if (!res.ok)
+                throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
+            return JSON.parse(text);
+        },
+    });
+}
+const SYNC_CURSOR_DIR = "sync-cursors";
+function scopeDigest(scope) {
+    return createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32);
 }
-export function memorySyncCursorPath(memoryRoot, peer, scope) {
-    return join(memoryRoot, "sync-cursors", encodeScopeSegment(peer), `${createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32)}.json`);
+export function memorySyncCursorPath(memoryRoot, scope) {
+    return join(memoryRoot, SYNC_CURSOR_DIR, `${scopeDigest(scope)}.json`);
 }
-function perPeerCursorPath(memoryRoot, peer) {
-    return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
+function unusableCursor(scope, path, why) {
+    return new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — the cursor file ${path} cannot be read as a sync cursor (${why}); the layer stays unsynced until the operator picks one of two ways out: ` +
+        "(1) restore the file from a backup; (2) delete it to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
+        "and entries deleted on one side since the last round come back from the other side");
 }
-async function readCursorFile(path) {
+function cursorOf(parsed) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return "not a JSON object";
+    const c = parsed;
+    const baseRevs = c["baseRevs"];
+    if (baseRevs === null || typeof baseRevs !== "object" || Array.isArray(baseRevs) || !Object.values(baseRevs).every((v) => typeof v === "string" && v.length > 0)) {
+        return "baseRevs is not a map of entry id to a non-empty rev";
+    }
+    const updatedAtMs = c["updatedAtMs"];
+    if (typeof updatedAtMs !== "number" || !Number.isFinite(updatedAtMs))
+        return "updatedAtMs is not a finite number";
+    return { scope: c["scope"], peer: c["peer"], store: c["store"], baseRevs: { ...baseRevs }, updatedAtMs };
+}
+async function loadLayerBaseline(path, scope) {
     let raw;
     try {
         raw = await readFile(path, "utf8");
     }
     catch (err) {
-        return err.code === "ENOENT" ? { kind: "absent" } : { kind: "unreadable", err: String(err) };
+        if (err.code === "ENOENT")
+            return { kind: "none" };
+        throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — cannot read the cursor file ${path} (${String(err)}); the next round reads it again once it is readable`);
     }
+    let parsed;
     try {
-        const value = JSON.parse(raw);
-        return { kind: "parsed", value };
+        parsed = JSON.parse(raw);
     }
-    catch (err) {
-        return { kind: "corrupt", err: String(err) };
+    catch {
+        throw unusableCursor(scope, path, "not JSON");
     }
+    const cursor = cursorOf(parsed);
+    if (typeof cursor === "string")
+        throw unusableCursor(scope, path, cursor);
+    return { kind: "cursor", cursor };
 }
-function predatesStoreBinding(parsed, scope, peer) {
+async function saveCursor(path, cursor) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+    await writeFile(tmp, JSON.stringify(cursor), "utf8");
+    await rename(tmp, path);
+}
+const LEGACY_PEER_SEGMENT = "central";
+const LEGACY_ROOT_CURSOR_FILE = "sync-cursor-central.json";
+function m31Window() {
+    const row = ONE_TIME_MIGRATIONS.find((w) => w.id === "M31");
+    if (row === undefined)
+        throw new Error("memory-sync-client: the one-time migration registry has no M31 row — this migration outlived its registry row; delete it with that row");
+    return row;
+}
+function scopeOfLegacyCursor(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
-        return false;
-    const c = parsed;
-    return c["scope"] === scope && c["peer"] === peer && c["store"] === undefined;
+        return undefined;
+    const scope = parsed["scope"];
+    return typeof scope === "string" && scope.length > 0 ? scope : undefined;
 }
-async function loadLayerBaseline(path, perPeer, scope, peer, log) {
-    const read = await readCursorFile(path);
-    switch (read.kind) {
-        case "absent": {
-            if (perPeer === undefined)
-                return { kind: "none" };
-            const legacy = await readCursorFile(perPeer);
-            return legacy.kind === "parsed" && predatesStoreBinding(legacy.value, scope, peer) ? { kind: "predates-store", path: perPeer } : { kind: "none" };
+export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
+    if (!migrationWindowOpen(opts.window ?? m31Window(), opts.today))
+        return { window: "closed", moved: 0, left: 0 };
+    let moved = 0;
+    let left = 0;
+    const codeOf = (err) => err?.code;
+    const exists = async (path) => {
+        try {
+            await stat(path);
+            return true;
         }
-        case "unreadable":
-            log.warn("memory_sync_cursor_read_failed", { path, err: read.err, note: "treating as first round" });
-            return { kind: "none" };
-        case "corrupt":
-            log.warn("memory_sync_cursor_corrupt", { path, err: read.err, note: "treating as first round" });
-            return { kind: "none" };
-        case "parsed": {
-            if (predatesStoreBinding(read.value, scope, peer))
-                return { kind: "predates-store", path };
-            const cursor = cursorOf(read.value, scope, peer);
-            if (cursor !== undefined)
-                return { kind: "cursor", cursor };
-            log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
-            return { kind: "none" };
+        catch (err) {
+            if (codeOf(err) === "ENOENT")
+                return false;
+            throw err;
+        }
+    };
+    const move = async (from, to) => {
+        if (await exists(to)) {
+            left += 1;
+            log.warn("memory_sync_cursor_not_relocated", { path: from, to, note: "this layer already has a cursor at its path, so the file written by an earlier version stays where it is and no round reads it; delete it" });
+            return;
         }
+        await mkdir(dirname(to), { recursive: true });
+        try {
+            await rename(from, to);
+        }
+        catch (err) {
+            if (codeOf(err) === "ENOENT")
+                return;
+            throw err;
+        }
+        moved += 1;
+        log.info("memory_sync_cursor_relocated", { from, to });
+    };
+    const legacyDir = join(memoryRoot, SYNC_CURSOR_DIR, LEGACY_PEER_SEGMENT);
+    let names = [];
+    try {
+        names = await readdir(legacyDir);
     }
-}
-function cursorOf(parsed, scope, peer) {
-    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-        const c = parsed;
-        const baseRevsRaw = c["baseRevs"];
-        if (c["scope"] === scope &&
-            c["peer"] === peer &&
-            typeof c["store"] === "string" &&
-            typeof c["updatedAtMs"] === "number" &&
-            Number.isFinite(c["updatedAtMs"]) &&
-            baseRevsRaw !== null &&
-            typeof baseRevsRaw === "object" &&
-            !Array.isArray(baseRevsRaw) &&
-            Object.values(baseRevsRaw).every((v) => typeof v === "string" && v.length > 0)) {
-            return { scope, peer, store: c["store"], baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
+    catch (err) {
+        if (codeOf(err) !== "ENOENT")
+            throw err;
+    }
+    for (const name of [...names].sort()) {
+        if (/^[0-9a-f]{32}\.json$/.test(name))
+            await move(join(legacyDir, name), join(memoryRoot, SYNC_CURSOR_DIR, name));
+    }
+    if (names.length > 0) {
+        try {
+            await rmdir(legacyDir);
+        }
+        catch (err) {
+            if (codeOf(err) !== "ENOENT" && codeOf(err) !== "ENOTEMPTY" && codeOf(err) !== "EEXIST")
+                throw err;
         }
     }
-    return undefined;
-}
-async function saveCursor(path, cursor) {
-    await mkdir(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
-    await writeFile(tmp, JSON.stringify(cursor), "utf8");
-    await rename(tmp, path);
+    const legacyFile = join(memoryRoot, LEGACY_ROOT_CURSOR_FILE);
+    let raw;
+    try {
+        raw = await readFile(legacyFile, "utf8");
+    }
+    catch (err) {
+        if (codeOf(err) !== "ENOENT")
+            throw err;
+    }
+    if (raw !== undefined) {
+        const scope = scopeOfLegacyCursor(raw);
+        if (scope === undefined) {
+            left += 1;
+            log.warn("memory_sync_cursor_not_relocated", { path: legacyFile, note: "a cursor file written by an earlier version that is not a JSON object naming its scope, so no layer can take it as its baseline; restore it from a backup and restart, or delete it" });
+        }
+        else {
+            await move(legacyFile, memorySyncCursorPath(memoryRoot, scope));
+        }
+    }
+    return { window: "open", moved, left };
 }
 export const MAX_SYNC_ROUNDS = 32;
 function enumerateScopes(backend) {
@@ -112,7 +204,7 @@ function enumerateScopes(backend) {
     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 now = opts.now ?? Date.now;
     const coverage = { kind: "layers", layers: [opts.scope] };
     const tracked = new Set();
     let enumerationWarned = false;
@@ -121,49 +213,34 @@ export function createMemorySyncRunner(opts) {
         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" });
+            opts.log.warn("memory_sync_layer_enumeration_unsupported", { scope: opts.scope, reason: local.reason, note: "only the sync layer and tracked project layers are synced" });
         }
         const projectLayers = new Set([...(local.supported ? local.scopes : []), ...tracked].filter(isCoveredProjectLayer));
         return [opts.scope, ...[...projectLayers].sort()];
     };
     const syncLayer = async (scope, reason) => {
-        const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer, scope);
-        const baseline = await loadLayerBaseline(cursorPath, scope === opts.scope ? perPeerCursorPath(opts.memoryRoot, peer) : undefined, scope, peer, opts.log);
-        if (baseline.kind === "predates-store") {
-            opts.log.warn(CURSOR_PREDATES_STORE_NOTICE, { scope, peer, path: baseline.path, note: CURSOR_PREDATES_STORE_OUTS });
-            throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — its baseline ${baseline.path} predates the store binding (see warn ${CURSOR_PREDATES_STORE_NOTICE})`);
-        }
+        const cursorPath = memorySyncCursorPath(opts.memoryRoot, scope);
+        const baseline = await loadLayerBaseline(cursorPath, scope);
         let cursor = baseline.kind === "cursor" ? baseline.cursor : undefined;
         let result;
         let subRound = 0;
         for (;;) {
             subRound += 1;
-            try {
-                result = await syncMemoryScope({
-                    backend: opts.backend,
-                    scope,
-                    transport: opts.transport,
-                    peer,
-                    ...(cursor !== undefined ? { cursor } : {}),
-                    ...(opts.now !== undefined ? { now: opts.now } : {}),
-                    ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
-                    ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
-                });
-            }
-            catch (err) {
-                if (cursor === undefined || err?.code !== CURSOR_MISMATCH_CODE)
-                    throw err;
-                opts.log.warn("memory_sync_cursor_rebound", { scope, peer, subRound, note: "the persisted cursor is bound to another store — running this round from no cursor and replacing it" });
-                cursor = undefined;
-                subRound -= 1;
-                continue;
-            }
+            result = await syncMemoryScope({
+                backend: opts.backend,
+                scope,
+                transport: opts.transport,
+                ...(cursor !== undefined ? { cursor } : {}),
+                ...(opts.now !== undefined ? { now: opts.now } : {}),
+                ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
+                ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
+            });
             for (const w of result.warnings ?? [])
-                opts.log.warn("memory_sync_warning", { scope, peer, subRound, warning: w });
+                opts.log.warn("memory_sync_warning", { scope, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
                 break;
             if (subRound >= MAX_SYNC_ROUNDS) {
-                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" });
+                opts.log.warn("memory_sync_rounds_exhausted", { scope, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
                 break;
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
@@ -175,12 +252,11 @@ export function createMemorySyncRunner(opts) {
                 }
             }
             cursor = result.cursor ?? cursor;
-            opts.log.info("memory_sync_continuation", { reason, scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
+            opts.log.info("memory_sync_continuation", { reason, scope, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
         }
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
                 scope,
-                peer,
                 side: c.side,
                 id: c.id,
                 reason: c.reason,
@@ -199,7 +275,6 @@ export function createMemorySyncRunner(opts) {
         opts.log.info("memory_sync_round", {
             reason,
             scope,
-            peer,
             ok: result.ok,
             cursorAdvanced: result.cursorAdvanced,
             pushedEntries: result.pushed.entries.length,
@@ -210,7 +285,12 @@ export function createMemorySyncRunner(opts) {
         });
         return result;
     };
+    let relocated = false;
     const round = async (reason) => {
+        if (!relocated) {
+            await relocateSyncCursorsM31(opts.memoryRoot, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
+            relocated = true;
+        }
         const layers = [];
         const failures = [];
         for (const scope of layersOfRound()) {
@@ -219,7 +299,7 @@ export function createMemorySyncRunner(opts) {
             }
             catch (err) {
                 failures.push({ scope, err });
-                opts.log.warn("memory_sync_layer_failed", { reason, scope, peer, err: String(err) });
+                opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(opts.memoryRoot, scope), err: String(err) });
             }
         }
         if (failures.length > 0) {
@@ -242,7 +322,7 @@ export function createMemorySyncRunner(opts) {
     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) });
+            opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, err: String(err) });
         });
     };
     const trigger = (reason) => {
@@ -259,6 +339,6 @@ export function createMemorySyncRunner(opts) {
         tracked.add(scope);
         queueRound("track");
     };
-    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, peer, scope), pending: () => pending };
+    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, scope), pending: () => pending };
 }
 //# sourceMappingURL=memory-sync-client.js.map

package/dist/memory-sync.d.ts

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

package/dist/memory-sync.js

@@ -1,5 +1,6 @@
 import { computeEntryRev, MEMORY_ORIGIN_CAUSES, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
 import { exportMemoryScope } from "./memory-export.js";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
 export const MEMORY_SYNC_MAX_ENTRIES = 500;
 export const MEMORY_SYNC_MAX_DELETES = 2000;
 export function parseMemorySyncRequest(body, scope) {
@@ -7,8 +8,8 @@ export function parseMemorySyncRequest(body, scope) {
         return { ok: false, error: "body must be a JSON object { peer, baseRevs, entries, deletes }" };
     const b = body;
     const peer = b["peer"];
-    if (typeof peer !== "string" || peer.length === 0 || peer.length > 190)
-        return { ok: false, error: "peer must be a non-empty string of at most 190 characters" };
+    if (typeof peer !== "string" || peer.length === 0 || peer.length > MEMORY_SYNC_PEER_COLUMN_CHARS)
+        return { ok: false, error: `peer must be a non-empty string of at most ${MEMORY_SYNC_PEER_COLUMN_CHARS} characters` };
     const rawBase = b["baseRevs"];
     if (rawBase === null || typeof rawBase !== "object" || Array.isArray(rawBase))
         return { ok: false, error: "baseRevs must be an object mapping entry id → rev (may be empty on the first round)" };

package/dist/observability/cost-taxonomy.d.ts

@@ -10,8 +10,8 @@
  * batch; stacking a second wide-fanout move on it in one session was the higher-risk option for no added
  * clarity.)
  *
- * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / memoryConsolidation
- * / compaction). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
+ * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / compaction, plus the
+ * suggestions and side-call lines). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
  * the service owns the data + rates for. This module is the thin report layer: it turns a
  * per-run infra USAGE + the deployment's RATES into an infra breakdown, then composes it with the core LLM
  * breakdown into one supervisor-facing total. Pure + rate-driven (rates default 0 ⇒ infra reads $0, exactly like

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

@@ -87,6 +87,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "P-DEBT";
         readonly note: "件6(#43 案 [4281]):`FileRunStore.hydrate()` 的 `readdirSync(runs/)` 失败 ⇒ 引擎以**空账**起动。旧形是空 catch + return:data root 不可读(权限/挂载丢失/路径被换走)时零告警,此后每一次 getRun 恒 miss —— 而「恒 miss」正是 #43 现场看到的形,一次环境故障被伪装成「本来就没有这条 run」。方向问题在于吞掉之后被读成的是「证不出有行 ⇒ 没有行」,两句话不等价。**缺省不拒启是刻意保留的行为**,所以这条留作债:响亮化(error 级启动日志带 runs 绝对路径+异常文案)+ 本计数,让它在遥测里显形而不是只活在一行日志里。⚠️ 2026-08-29(S-46 件B)起终局格已兑现:部署可用 `RUN_STORE_STRICT_HYDRATE=on` 把这一格换成 **fail-closed 启动门**(拒启,遗言同样带绝对路径+异常文案);本计数因此只在**缺省 off** 档上产生 —— 读遥测时别把「计数为零」直接读成「没有部署踩到这条路」,也可能是它们开了拒启门、根本起不来。";
     };
+    readonly "server.run-store.file-active-claims-unreadable": {
+        readonly cls: "P-DEBT";
+        readonly note: "`FileRunStore.hydrate()` 的第二处 `readdirSync(runs/active/)`(claim 平面 = 单活索引)失败,且 `RUN_STORE_STRICT_HYDRATE` 关(缺省)⇒ 服务照常起动、单活索引为**空**。放行的后果两条,都不报错:① 已有 run 行仍可读(`GET /v1/runs/:id` 照常答),但此后对这些会话的审批决定在请求里同步跑完、却找不到要更新的 run 行 —— run 行停在决前的 `suspended`;② 读单活索引的各处读到「没人占用」—— `getActiveTaskId` 恒答空,例如会话同步推送前的「会话有在飞 run」检查(与 `server.run-store.file-hydrate-unreadable` 同一句错话:「证不出有占用 ⇒ 没有占用」,只是换了一个盘面);新提交不读这张索引,claim 文件完好时仍按盘上的 claim 裁定,不受影响。同一条债的另一个盘面:缺省不拒启是刻意保留的行为,所以留作 P-DEBT —— error 级启动日志(`file_run_store_active_claims_unreadable`,带 `runs/active/` 绝对路径)早已在,本计数补的是遥测轴(此前 `runs/` 臂有计数、这一臂没有)。`RUN_STORE_STRICT_HYDRATE=on` 把这一格换成 fail-closed 启动门,本计数因此只在缺省 off 档的真放行时产生(拒启那一形不记)—— 读遥测时「计数为零」也可能是部署开了拒启门、根本起不来。";
+    };
     readonly "server.fork-routing.placed-probe-host-error": {
         readonly cls: "F";
         readonly note: "#292 placement 半场:hostPlacedProbe 对 host 店的 requireExisting 探针失败且**不是 not_found**(host 读故障)时折叠为 absent —— 路由回旧规则(claim-create 会在 transient 建新会话)。放行的是「host 暂不可达时 transient 腿保持独立可用」;最坏后果=故障窗内对一个真 placed id 铸出 transient 影子(host 恢复后双身,requireExisting 冷探针会重新指回 host 真身)。not_found 是常态路径不计数;只有真故障臂进本计数。";
@@ -549,6 +553,14 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "P-DEBT";
         readonly note: "S-163(`config-dir-trust.ts` `judgeWin32`,本地配置源 `config.d` 读之前的目录信任判官在 win32 上的那一半):Node 在 win32 上 `uid` 恒 0、模式位是只读属性的投影 ⇒ 「属主 ∈ {本服务用户, root, CONFIG_LOCAL_OWNER_UID}」与「不得组 / 他人可写」两判不可做;结构判(常规文件 / 16 MiB 上界 / 链接成环)照做。每一次读照常进行(起服一次 + 每拍一次)记一次。放行的最坏后果 = 一台多用户 Windows 机器上,别的本机用户若能写这台服务的 `config.d`(缺省的用户目录 ACL 不允许),改一份 `mcp.json` 就能让本服务以它的身份起命令 —— 与 7.132.x 逐字同。照 POSIX 拒启会让每个 Windows 本机引擎(含 cli 起的)升级即起不来,而让 cli 替用户设豁免键是中间层替部署者设安全旋钮。收口 = 有了 ACL 判据或一次裁定(改 R 或改拒启)那一版,本 tag 删或改类。detail = `config.d=<物理路径>`。";
     };
+    readonly "server.remote-write.staging-dir-left": {
+        readonly cls: "F";
+        readonly note: "远端五条车道的写(`plugins/remote-shell.ts` 的暂存编排):准备 / 提交脚本删一只私有暂存目录(`.<名>.stage-<十六进制>/`,生来 0700;只删这次写放进去的 `data` 与这只空目录,从不递归删)没删掉、在 stdout 写一条记录点名 —— 五处:`mv` 已把暂存件换到目标上之后删当前那只;跟一跳到别的目录重新暂存成功之后删原来那只;重新暂存却没用上(收紧不成 / 拷不成)的那一只;就地拷入 / 追加时删暂存名失败、或写完关掉 fd 后删私有目录失败(有的文件系统为仍打开着的文件留隐藏项:NFS / libfuse / SMB);准备时收不成私有 / 里面已有 `data` 的那一只。目录里多出了不是这次写放进去的东西(同一身份或 root 的别的进程往里写过 / 收紧之前别人放进来的)、目录被换成了符号链接、或文件系统拒删。写照它自己的结局答(提交已成 ⇒ 成功:答失败会让调用方以为目标没变),残留只在这里留痕。放行的最坏后果 = 目标(或链接所指)目录里多一只隐藏目录(空的,或装着别人放进去的东西;重新暂存没用上的那只可能装着这次写的半份新内容),只有写入方进得去;不是门、不是凭据、不碰目标内容。计数非零 = 那台目标机上有东西在往别人的暂存目录里写,或删不动,去看那只目录。detail = 残留目录的路径(一次写最多两只,逐只计)。";
+    };
+    readonly "server.remote-write.stage-seal-fallback": {
+        readonly cls: "F";
+        readonly note: "远端五条车道的写(`plugins/remote-shell.ts` 的暂存编排):准备脚本把刚建的私有暂存目录收成 0700 并读回核实(`chmod 700` 退出 0 ∧ `stat` 读回的模式低三位恰是 700 ∧ 属主 = 本身份),任一步不成 —— `chmod` 被文件系统 / 内核拒;退出 0 却没生效(不认权限位的文件系统);父目录带缺省 ACL 而掩码收不下来;目标机上没有 `stat` —— 准备退出 4、这次写**不暂存**,两只文件面、五条腿一律改为直接写目标(与「目标目录不收新名字」同一条回落;能追加写的腿直接追加,e2b / adb 的追加 = 读旧 + 拼 + 整份写目标 —— adb 的这一形就是 7.138.x 的追加,push 没有追加写)。修前这一步是 `chmod 700 … || :`:加固失败照样放行上传,字节落在一只别的身份可能读得到的目录里(P 轴 fail-open),那一臂已删,字节从不进一只没核成私有的目录。放行的最坏后果 = 这一次写失去「整旧或整新」(非原子:中途断 / 取消 ⇒ 目标可能只写了一半,整份写目标的 e2b / adb 上可能没了或只剩半份;写目标那一步因取消中断答 `unknown`,那一步开始之前取消答 `aborted`、目标未碰,那一步不收取消(ssh 的 sftp)照样写完);ssh / local-docker / k8s 写进原 inode、权限位不变,e2b 的 `files.write` 与 adb 的 push 整份写目标、inode / 权限位由对端定(adbd 不保,与 7.138.x 同形);不是门、不是凭据。Android 共享存储(`/sdcard` 一类:权限位由挂载派生、不认 chmod)上 adb 的写按 sdcardfs / MediaProvider FUSE 的权限语义**推断**每一次都走这里(未上真机,真机读数候 test;结构性,运维修不掉;工作区放在 `/data/local/tmp` 一类认权限位的目录就不走)。计数非零 = 这台目标机的这个目录上私有目录收不成私有(文件系统不认权限位 / 缺省 ACL 掩码收不下来 / 缺 `stat`),写在走非原子的退路,去看那个目录。detail = `<目标路径>: <准备脚本写的原因句>`。";
+    };
 };
 /** 词表键推导的闭集类型——未登记的 tag 传不进 {@link recordFailOpen}(编译期拒)。 */
 export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;

package/dist/observability/fail-open.js

@@ -68,6 +68,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "P-DEBT",
         note: "件6(#43 案 [4281]):`FileRunStore.hydrate()` 的 `readdirSync(runs/)` 失败 ⇒ 引擎以**空账**起动。旧形是空 catch + return:data root 不可读(权限/挂载丢失/路径被换走)时零告警,此后每一次 getRun 恒 miss —— 而「恒 miss」正是 #43 现场看到的形,一次环境故障被伪装成「本来就没有这条 run」。方向问题在于吞掉之后被读成的是「证不出有行 ⇒ 没有行」,两句话不等价。**缺省不拒启是刻意保留的行为**,所以这条留作债:响亮化(error 级启动日志带 runs 绝对路径+异常文案)+ 本计数,让它在遥测里显形而不是只活在一行日志里。⚠️ 2026-08-29(S-46 件B)起终局格已兑现:部署可用 `RUN_STORE_STRICT_HYDRATE=on` 把这一格换成 **fail-closed 启动门**(拒启,遗言同样带绝对路径+异常文案);本计数因此只在**缺省 off** 档上产生 —— 读遥测时别把「计数为零」直接读成「没有部署踩到这条路」,也可能是它们开了拒启门、根本起不来。",
     },
+    "server.run-store.file-active-claims-unreadable": {
+        cls: "P-DEBT",
+        note: "`FileRunStore.hydrate()` 的第二处 `readdirSync(runs/active/)`(claim 平面 = 单活索引)失败,且 `RUN_STORE_STRICT_HYDRATE` 关(缺省)⇒ 服务照常起动、单活索引为**空**。放行的后果两条,都不报错:① 已有 run 行仍可读(`GET /v1/runs/:id` 照常答),但此后对这些会话的审批决定在请求里同步跑完、却找不到要更新的 run 行 —— run 行停在决前的 `suspended`;② 读单活索引的各处读到「没人占用」—— `getActiveTaskId` 恒答空,例如会话同步推送前的「会话有在飞 run」检查(与 `server.run-store.file-hydrate-unreadable` 同一句错话:「证不出有占用 ⇒ 没有占用」,只是换了一个盘面);新提交不读这张索引,claim 文件完好时仍按盘上的 claim 裁定,不受影响。同一条债的另一个盘面:缺省不拒启是刻意保留的行为,所以留作 P-DEBT —— error 级启动日志(`file_run_store_active_claims_unreadable`,带 `runs/active/` 绝对路径)早已在,本计数补的是遥测轴(此前 `runs/` 臂有计数、这一臂没有)。`RUN_STORE_STRICT_HYDRATE=on` 把这一格换成 fail-closed 启动门,本计数因此只在缺省 off 档的真放行时产生(拒启那一形不记)—— 读遥测时「计数为零」也可能是部署开了拒启门、根本起不来。",
+    },
     "server.fork-routing.placed-probe-host-error": {
         cls: "F",
         note: "#292 placement 半场:hostPlacedProbe 对 host 店的 requireExisting 探针失败且**不是 not_found**(host 读故障)时折叠为 absent —— 路由回旧规则(claim-create 会在 transient 建新会话)。放行的是「host 暂不可达时 transient 腿保持独立可用」;最坏后果=故障窗内对一个真 placed id 铸出 transient 影子(host 恢复后双身,requireExisting 冷探针会重新指回 host 真身)。not_found 是常态路径不计数;只有真故障臂进本计数。",
@@ -509,6 +513,14 @@ export const FAIL_OPEN_TAGS = {
         cls: "P-DEBT",
         note: "S-163(`config-dir-trust.ts` `judgeWin32`,本地配置源 `config.d` 读之前的目录信任判官在 win32 上的那一半):Node 在 win32 上 `uid` 恒 0、模式位是只读属性的投影 ⇒ 「属主 ∈ {本服务用户, root, CONFIG_LOCAL_OWNER_UID}」与「不得组 / 他人可写」两判不可做;结构判(常规文件 / 16 MiB 上界 / 链接成环)照做。每一次读照常进行(起服一次 + 每拍一次)记一次。放行的最坏后果 = 一台多用户 Windows 机器上,别的本机用户若能写这台服务的 `config.d`(缺省的用户目录 ACL 不允许),改一份 `mcp.json` 就能让本服务以它的身份起命令 —— 与 7.132.x 逐字同。照 POSIX 拒启会让每个 Windows 本机引擎(含 cli 起的)升级即起不来,而让 cli 替用户设豁免键是中间层替部署者设安全旋钮。收口 = 有了 ACL 判据或一次裁定(改 R 或改拒启)那一版,本 tag 删或改类。detail = `config.d=<物理路径>`。",
     },
+    "server.remote-write.staging-dir-left": {
+        cls: "F",
+        note: "远端五条车道的写(`plugins/remote-shell.ts` 的暂存编排):准备 / 提交脚本删一只私有暂存目录(`.<名>.stage-<十六进制>/`,生来 0700;只删这次写放进去的 `data` 与这只空目录,从不递归删)没删掉、在 stdout 写一条记录点名 —— 五处:`mv` 已把暂存件换到目标上之后删当前那只;跟一跳到别的目录重新暂存成功之后删原来那只;重新暂存却没用上(收紧不成 / 拷不成)的那一只;就地拷入 / 追加时删暂存名失败、或写完关掉 fd 后删私有目录失败(有的文件系统为仍打开着的文件留隐藏项:NFS / libfuse / SMB);准备时收不成私有 / 里面已有 `data` 的那一只。目录里多出了不是这次写放进去的东西(同一身份或 root 的别的进程往里写过 / 收紧之前别人放进来的)、目录被换成了符号链接、或文件系统拒删。写照它自己的结局答(提交已成 ⇒ 成功:答失败会让调用方以为目标没变),残留只在这里留痕。放行的最坏后果 = 目标(或链接所指)目录里多一只隐藏目录(空的,或装着别人放进去的东西;重新暂存没用上的那只可能装着这次写的半份新内容),只有写入方进得去;不是门、不是凭据、不碰目标内容。计数非零 = 那台目标机上有东西在往别人的暂存目录里写,或删不动,去看那只目录。detail = 残留目录的路径(一次写最多两只,逐只计)。",
+    },
+    "server.remote-write.stage-seal-fallback": {
+        cls: "F",
+        note: "远端五条车道的写(`plugins/remote-shell.ts` 的暂存编排):准备脚本把刚建的私有暂存目录收成 0700 并读回核实(`chmod 700` 退出 0 ∧ `stat` 读回的模式低三位恰是 700 ∧ 属主 = 本身份),任一步不成 —— `chmod` 被文件系统 / 内核拒;退出 0 却没生效(不认权限位的文件系统);父目录带缺省 ACL 而掩码收不下来;目标机上没有 `stat` —— 准备退出 4、这次写**不暂存**,两只文件面、五条腿一律改为直接写目标(与「目标目录不收新名字」同一条回落;能追加写的腿直接追加,e2b / adb 的追加 = 读旧 + 拼 + 整份写目标 —— adb 的这一形就是 7.138.x 的追加,push 没有追加写)。修前这一步是 `chmod 700 … || :`:加固失败照样放行上传,字节落在一只别的身份可能读得到的目录里(P 轴 fail-open),那一臂已删,字节从不进一只没核成私有的目录。放行的最坏后果 = 这一次写失去「整旧或整新」(非原子:中途断 / 取消 ⇒ 目标可能只写了一半,整份写目标的 e2b / adb 上可能没了或只剩半份;写目标那一步因取消中断答 `unknown`,那一步开始之前取消答 `aborted`、目标未碰,那一步不收取消(ssh 的 sftp)照样写完);ssh / local-docker / k8s 写进原 inode、权限位不变,e2b 的 `files.write` 与 adb 的 push 整份写目标、inode / 权限位由对端定(adbd 不保,与 7.138.x 同形);不是门、不是凭据。Android 共享存储(`/sdcard` 一类:权限位由挂载派生、不认 chmod)上 adb 的写按 sdcardfs / MediaProvider FUSE 的权限语义**推断**每一次都走这里(未上真机,真机读数候 test;结构性,运维修不掉;工作区放在 `/data/local/tmp` 一类认权限位的目录就不走)。计数非零 = 这台目标机的这个目录上私有目录收不成私有(文件系统不认权限位 / 缺省 ACL 掩码收不下来 / 缺 `stat`),写在走非原子的退路,去看那个目录。detail = `<目标路径>: <准备脚本写的原因句>`。",
+    },
 };
 export function failOpenTagForDroppedFrame(frameType) {
     switch (frameType) {

package/dist/observability/run-terminal.js

@@ -593,7 +593,6 @@ const STATS_KEY_TREATMENT = {
     humanReview: "human-review",
 };
 const STATS_MECHANISMS_TREATMENT = {
-    finalVerifyInjected: "verbatim",
     finalVerifyInjections: "verbatim",
     attachmentsInjected: "verbatim",
     approachNoticesSent: "verbatim",

package/dist/orchestration/workflow-notify-journal.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { AppendLog, ensureDir } from "@sema-agent/core";
+import { AppendLog, REDACTION_MARKS, ensureDir } from "@sema-agent/core";
 import { buildFleetWorkflowRow } from "../fleet/fleet-bus.js";
 import { isTerminalWorkflowRowStatus, seedTerminalWorkflowRow } from "../fleet/fleet-terminal-window.js";
 import { buildParkSessionRows } from "./workflow-agent-session-index.js";
@@ -26,11 +26,11 @@ export function recoverySummary(status, error) {
         return "workflow completed";
     const base = error ? `workflow failed: ${error}` : "workflow failed";
     const redacted = base
-        .replace(/https?:\/\/[^\s"'`]+/gi, "[redacted-url]")
+        .replace(/https?:\/\/[^\s"'`]+/gi, REDACTION_MARKS.url)
         .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[redacted-token]")
         .replace(/\b(?:api[_-]?key|secret|token|password|authorization)\b\s*[:=]\s*"?[^\s"',}]+/gi, "[redacted-secret]")
-        .replace(/(?:\/[A-Za-z0-9_.-]+){2,}/g, "[redacted-path]")
-        .replace(/(?:[A-Za-z]:)?(?:\\{1,2}[A-Za-z0-9_.$-]+){2,}/g, "[redacted-path]");
+        .replace(/(?:\/[A-Za-z0-9_.-]+){2,}/g, REDACTION_MARKS.path)
+        .replace(/(?:[A-Za-z]:)?(?:\\{1,2}[A-Za-z0-9_.$-]+){2,}/g, REDACTION_MARKS.path);
     return redacted.length > SUMMARY_MAX ? `${redacted.slice(0, SUMMARY_MAX)}…[+${redacted.length - SUMMARY_MAX} chars]` : redacted;
 }
 export class WorkflowNotifyGate {

package/dist/org-memory-admission.d.ts

@@ -12,8 +12,9 @@
  * core 侧契约(RunnerDeps.memoryScopeAdmission,core types.d.ts):resolver 返回 {ok:false} ⇒ core 铸终局码
  * memory.admission_denied;resolver throw 一个带 `retryAfterMs`(ms)属性的 Error ⇒ core 铸瞬时码
  * memory.admission_required 并透传 retryAfterMs;{ok:true}.scopes 只能 ⊆ requested(多给 = resolver fault
- * 会被 core 整拒)。core 只在「存在 request-origin org scope 且 principal 缺席」时自己先拒——本模块仍防御
- * `principal === undefined` 这一支(不能信任「core 一定先拒过」这件事)。
+ * 会被 core 整拒)。「谁在问」只有引擎一处读法:入参按调用方在不在场分两形,无调用方那一形只装部署来源的 scope
+ * (请求来源的 scope 没有调用方 ⇒ 引擎在自己的门上先拒,不问本解析器)—— 本模块按这一判别式分支,不另判一次缺席;
+ * 引擎型不可达的那一组合(无调用方 ∧ 请求来源 scope)若仍到了这里 ⇒ 抛,不放行。
  */
 import type { MemoryScopeAdmission } from "@sema-agent/core";
 /**
@@ -72,7 +73,7 @@ export interface MemoryScopeAdmissionOptions {
     /** "audit": 判决照算但从不真拒——会拒的结果（终局 ok:false 或瞬时 throw）一律换成全额放行 + 观测记录
      *  would-deny；真通过的判决（含 write 收窄为 null）照常返回。"enforce": 判决即结果。 */
     mode: "audit" | "enforce";
-    /** 观测 hook。outcome ∈ "ok" | "denied" | "principal_missing" | "directory_absent" | "directory_stale" |
+    /** 观测 hook。outcome ∈ "ok" | "denied" | "directory_absent" | "directory_stale" |
      *  "directory_malformed"。audit 模式下的 would-deny 也走这里，`details.audited === true`。hook 本身绝不
      *  允许打断准入判决——一律吞掉它可能抛出的异常。 */
     onOutcome?: (outcome: string, details?: Record<string, unknown>) => void;

package/dist/org-memory-admission.js

@@ -164,8 +164,9 @@ export function createMemoryScopeAdmission(directory, opts) {
         catch {
         }
     };
-    return async ({ principal, requested, requestedWriteScope }) => {
-        const attributed = (details) => principal === undefined ? details : { principal, ...details };
+    return async (input) => {
+        const { requested, requestedWriteScope } = input;
+        const attributed = (details) => input.principal === undefined ? details : { principal: input.principal, ...details };
         const requestOriginRequested = requested.filter((r) => r.origin === "request");
         const writeIsRequestOrigin = requestedWriteScope?.origin === "request";
         const hasRequestOrigin = requestOriginRequested.length > 0 || writeIsRequestOrigin;
@@ -175,10 +176,9 @@ export function createMemoryScopeAdmission(directory, opts) {
         async function decide() {
             if (!hasRequestOrigin)
                 return { kind: "admit", verdict: admitFull() };
-            if (principal === undefined) {
-                return { kind: "deny", reason: "principal absent", outcome: "principal_missing" };
-            }
-            const lookup = await directory.lookup(principal);
+            if (input.principal === undefined)
+                throw new Error("org memory admission was asked with no caller yet holds a request-origin scope — the engine's caller-less arm carries deployment-origin scopes only, so this input is an engine contract break and is refused, never admitted");
+            const lookup = await directory.lookup(input.principal);
             if (lookup.kind === "unavailable") {
                 const outcome = lookup.reason === "stale_generation" ? "directory_stale" : lookup.reason === "malformed" ? "directory_malformed" : "directory_absent";
                 return { kind: "unavailable", retryAfterMs: lookup.retryAfterMs, outcome, lookupReason: lookup.reason, details: { reason: lookup.reason } };