@sema-agent/server 7.140.0 → 7.142.0

package/dist/http/routes/run-permission-mode.js

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { isParkedRunStatus, isTerminalRunStatus, runProvenElsewhere } from "../../plugins/store-contracts.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { readOwnedRun } from "../owner-access.js";
+import { runNotFoundMessage } from "../route-ctx.js";
+import { assertNever } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
+import { PERMISSION_MODE_WORDS, coercePermissionModeStrict, parseTaskSettings } from "../../task-settings.js";
+import { admitPermissionModeWord } from "../../permission-mode-admission.js";
+import { readResumeCtx, resumeCtxCorruptAnswer, resumeCtxUnsealableAnswer } from "../resume-ctx-read.js";
+import { sealCheckpointCtx, withPermissionModeRewritten } from "../checkpoint-ctx.js";
+import { serviceVersion } from "../../service-version.js";
+import { recordFailOpen } from "../../observability/fail-open.js";
+export const PERMISSION_MODE_PERSIST_MISSES = ["claim_released", "context_absent", "store_failed"];
+const BodySchema = z.object({ mode: z.string() }).strict();
+const switchChains = new WeakMap();
+function serialOnStream(stream, work) {
+    const prior = switchChains.get(stream) ?? Promise.resolve();
+    const job = prior.then(work, work);
+    switchChains.set(stream, job.catch(() => undefined));
+    return job;
+}
+export function switchLegHolds(fenced, thisInstanceId, liveNow, switched) {
+    return !runProvenElsewhere(fenced, thisInstanceId) && liveNow === switched;
+}
+export async function handlePermissionMode(req, res, match, ctx) {
+    const { deps } = ctx;
+    switch (match.decl.id) {
+        case "run-permission-mode": {
+            if (ctx.helpers.rateLimited(req, res))
+                return;
+            const seat = facts.permissionModeWrite(deps);
+            if (!seat.available) {
+                switch (seat.why) {
+                    case "run_store_absent":
+                        sendError(res, 501, "capability.run_store_required", "changing a running run's permission mode requires a durable run store (DB_BACKEND=mysql|pg|local)");
+                        return;
+                    case "checkpoint_store_absent":
+                        sendError(res, 501, "capability.checkpoint_store_required", "changing a running run's permission mode requires the checkpoint store (DURABLE_APPROVAL): the run's stored request is where its permission mode lives and where the task's own settings are read");
+                        return;
+                    default:
+                        return assertNever(seat.why);
+                }
+            }
+            const { runStore, checkpointStore } = seat;
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && principal === undefined) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return;
+            }
+            const taskId = match.params.taskId;
+            const parsed = BodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
+            if (!parsed.success) {
+                sendError(res, 400, "request.body_shape", `body must be { mode: ${PERMISSION_MODE_WORDS} } — the permission-mode verb takes no other keys`);
+                return;
+            }
+            const word = coercePermissionModeStrict(parsed.data.mode);
+            if (word === undefined) {
+                sendError(res, 422, "steering.invalid_content", `mode must be one of ${PERMISSION_MODE_WORDS} (got ${JSON.stringify(parsed.data.mode.slice(0, 64))})`);
+                return;
+            }
+            const run = await readOwnedRun(deps.config, runStore, principal, taskId, "owner_or_operator");
+            if (!run) {
+                sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
+                return;
+            }
+            if (!ctx.helpers.runSessionAcceptOk(req, res, run, "run.permission_mode"))
+                return;
+            const live = ctx.registry.steerableRuns.get(taskId);
+            if (!live) {
+                if (isParkedRunStatus(run.status)) {
+                    sendError(res, 409, "steering.not_running", "run is waiting on a pending decision — the permission-mode verb changes a running run; when it resumes, its mode is rebuilt from the run's stored request (a plan review's approval names the mode it continues in)");
+                    return;
+                }
+                if (isTerminalRunStatus(run.status)) {
+                    sendError(res, 409, "steering.not_running", "run already ended — the permission-mode verb changes a running run; submit the next turn of this session with the permissionMode you want");
+                    return;
+                }
+                if (runProvenElsewhere(run, deps.instanceId)) {
+                    sendError(res, 409, "steering.not_running", "run is live on another replica — the permission-mode verb must reach the replica holding the stream; resend it there");
+                    return;
+                }
+                sendError(res, 409, "steering.not_running", "no live steerable face for this run on this replica — a verify or cascade submission exposes none, so the permission-mode verb has nothing to switch");
+                return;
+            }
+            const sessionId = run.sessionId;
+            const out = await serialOnStream(live, async () => {
+                const read = await readResumeCtx(checkpointStore.getCtx(sessionId), { sessionId, opener: deps.checkpointCtxSealing });
+                if (read.kind === "corrupt" || read.kind === "unsealable") {
+                    const { status, body: { error, errorCode, ...facts } } = read.kind === "corrupt" ? resumeCtxCorruptAnswer(read.where) : resumeCtxUnsealableAnswer(read);
+                    sendError(res, status, errorCode, error, facts);
+                    return { kind: "answered" };
+                }
+                if (read.kind === "absent") {
+                    sendError(res, 409, "conflict.resume_context_unavailable", "this run's stored request is missing — its permission mode cannot be changed (the task's settings are read from it and the new mode is written back to it)");
+                    return { kind: "answered" };
+                }
+                const stored = read.ctx;
+                const admission = admitPermissionModeWord(word, { deployment: deps.config, settings: parseTaskSettings(stored.body.settings).settings });
+                if (admission.kind === "refused") {
+                    sendError(res, admission.status, admission.code, admission.message);
+                    return { kind: "answered" };
+                }
+                const admitted = admission.admitted ?? word;
+                let receipt;
+                try {
+                    receipt = await live.setPermissionMode(admitted);
+                }
+                catch (e) {
+                    const code = e.code;
+                    if (code === "steering.invalid_content") {
+                        sendError(res, 422, "steering.invalid_content", e instanceof Error ? e.message : String(e));
+                        return { kind: "answered" };
+                    }
+                    if (code === "steering.not_running") {
+                        sendError(res, 409, "steering.not_running", "run just finished — the permission-mode verb needs a running run; submit the next turn of this session with the permissionMode you want");
+                        return { kind: "answered" };
+                    }
+                    throw e;
+                }
+                let persistMiss;
+                try {
+                    const next = sealCheckpointCtx({ ...withPermissionModeRewritten(stored, { ...stored.body, permissionMode: admitted }), writerVersion: serviceVersion() }, deps.checkpointCtxSealing, sessionId);
+                    const rewrite = await checkpointStore.rewriteCtxWhileClaimed(sessionId, taskId, next, (fenced) => switchLegHolds(fenced, deps.instanceId, ctx.registry.steerableRuns.get(taskId), live));
+                    persistMiss = rewrite === "written" ? undefined : rewrite;
+                }
+                catch (e) {
+                    persistMiss = "store_failed";
+                    deps.logger?.warn?.("run_permission_mode_write_back_failed", { taskId, sessionId, err: e instanceof Error ? e.message : String(e) });
+                }
+                if (persistMiss !== undefined) {
+                    recordFailOpen("server.run-permission-mode.write-back-unpersisted", `miss=${persistMiss} mode=${admitted}`);
+                    deps.logger?.warn?.("run_permission_mode_unpersisted", { taskId, sessionId, mode: admitted, miss: persistMiss });
+                }
+                return {
+                    kind: "switched",
+                    receipt,
+                    ...(admission.foldedBy !== undefined ? { admission: { requested: word, admitted, foldedBy: admission.foldedBy } } : {}),
+                    ...(persistMiss !== undefined ? { persistMiss } : {}),
+                };
+            });
+            switch (out.kind) {
+                case "answered":
+                    return;
+                case "switched": {
+                    const reply = {
+                        taskId,
+                        sessionId,
+                        status: "running",
+                        permissionMode: out.receipt,
+                        ...(out.admission !== undefined ? { admission: out.admission } : {}),
+                        persisted: out.persistMiss === undefined,
+                        ...(out.persistMiss !== undefined ? { persistMiss: out.persistMiss } : {}),
+                    };
+                    sendJson(res, 200, reply);
+                    return;
+                }
+                default:
+                    return assertNever(out);
+            }
+        }
+        default:
+            return assertNever(match.decl.id);
+    }
+}
+export const RUN_PERMISSION_MODE_ROUTES = [
+    { id: "run-permission-mode", pattern: /^\/v1\/runs\/(?<taskId>[^/]+)\/permission-mode$/, label: "/v1/runs/:id/permission-mode", methods: ["POST"] },
+];
+//# sourceMappingURL=run-permission-mode.js.map

package/dist/http/routes/runs.js

@@ -16,7 +16,7 @@ import { buildApprovalPreamble, buildApprovalPreambleSseFrames, readClosedWordSe
 import { heldAskOf, liveSettledBy, readDecidedBy, retiredDecisionKeyFacts, DECIDED_BY_NOT_IN_PROOF, DECIDED_BY_OUTSIDE_CLOSED_SET, POLICY_CANNOT_ALLOW_PERSON_ASK } from "../../host-decision.js";
 import { ASK_DECISION_CONSUMER_ABSENT, approvalPreambleReplays, outcomeOfDecidedRow, presentedApprovalFrameFamily, resolveStreamApprovalGate } from "../../tool-approval.js";
 import { MAX_DECISION_NOTE_CHARS, noteLandedOnRow, noteRecordedReceipt } from "../../approval-ask-machine.js";
-import { causeOfAskRow } from "../../approval-deny-reasons.js";
+import { askRowEndingCause } from "../../approval-deny-reasons.js";
 import { normalizeRunEventType, screenedStoredEventData } from "../../trace/project.js";
 import { invalidJsonError, sendJson, sendError, sendHttpError, sseHeaders } from "../send.js";
 import { mintCancelledResult } from "../../run-cancel-context.js";
@@ -1429,10 +1429,10 @@ export async function handleRunVerbs(req, res, match, ctx) {
                     return;
                 case "DENIED":
                 case "VOID": {
-                    const rowCause = causeOfAskRow(row);
+                    const endingCause = askRowEndingCause(row);
                     sendError(res, 410, "gone.ask", "this ask reached a terminal state without a human decision (cause says why: a routing failure, a cancellation or batch withdrawal or abort, or the process that held it ended) and can no longer be decided", {
                         state: row.state,
-                        ...(rowCause?.kind === "ending" ? { cause: rowCause.cause } : {}),
+                        ...(endingCause !== undefined ? { cause: endingCause } : {}),
                     });
                     return;
                 }

package/dist/http/routes/session-memory-sync.d.ts

@@ -0,0 +1,63 @@
+/**
+ * [ref] —— **会话记忆同步触发口**:`POST /v1/sessions/:id/memory/sync`  body `{ target: string }`
+ *   → 200 引擎的同步报告(core `memorySyncReportOf` 的产物,原样)
+ *
+ * 一口一件事:让本机的记忆同步腿**现在**对会话要去的那台引擎同步一轮,只回报这个会话读的那几层。壳在把会话推上云(fork)之前调它。
+ *
+ * ── 规则(规则账只减)────────────────────────────────────────────────────────────────────────────
+ *  R1 一轮 = 同步腿的一轮(`MemorySyncRunner.syncOnce`):交回每层每次调用如它落定的那样,从不整轮 reject —— 部分层失败落在报告的逐层结局里。
+ *  R2 同步身份一只铸点(`memory-sync-identity.ts`):`target` 必须**就是**目标引擎能力面公开的 `memorySyncServe.identity`(规范形、不带凭据),
+ *     与本机腿的 `peer` 按串相等比。壳不拼、本口不规范化。
+ *  R4 门之后的一切答复都是 core 报告:200 带 `layers`(每层恰一个结局)或整轮 `refused`(目标不符 / 会话有在飞的 run)。
+ *     HTTP 错误只留给报告产生之前的门(能力 / 身份 / id / 属主 / 体)与「读集不可取得」。本口不铸汇总键、不加第五种结局。
+ *  R5 可用性 = 能力事实 `sessionMemorySync`(本机同步腿 ∧ 持久 run 账面 ∧ 会话头读),与能力位同读一只;不从后端名推。
+ *
+ * ── 读集(这个会话读哪几层)────────────────────────────────────────────────────────────────────
+ * = 会话**最近一条已结腿**结果里引擎铸的记忆观测(run 店 `latestMemoryObservationForSession`;规则属主 `store-contracts.ts` 的
+ * `SettledLegMemoryObservation`):`mounted` ⇒ `scopes[].scope` 按服务序;`memoryless` / `none` ⇒ `[]`(那一腿没挂上记忆 —— 是值)。
+ * 那一腿没有观测(prepare 没走完)/ 会话还没有已结腿 / 会话没有叶子 ⇒ 409 `conflict.session_memory_unobserved`(有在飞 run 时带 `activeTaskId`)。
+ * 路由不重铸 spec:spec 只在受理时铸、不落会话行,重铸 = 重启前后两种答案。
+ *
+ * ── 门序(编号即执行序)──────────────────────────────────────────────────────────────────────────
+ *  1. 事实 `sessionMemorySync` 为假 ⇒ 501(码按 why)。先于身份:「这台部署有没有这一口」本由能力位公开。
+ *  2. 多租户部署上没有验过的身份 ⇒ 401/403(`sendPrincipalRefusal`,会话面同一只)。
+ *  3. 限流(本口会向远端发请求)。
+ *  4. 会话 id 段解码不了 ⇒ 400 `request.path_malformed`。
+ *  5. 一次头读:没有这只会话 / 不是你的 ⇒ 404 `not_found.session`(同码同串,无存在性 oracle;属主判据 = 会话面唯一谓词 `sessionOwnerOk`);
+ *     同一次头读的叶子 = `sourceRevision`(与 `GET /v1/sessions/:id/head` 的 `leafId` 同一读法)。
+ *  6. 体:闭集一键 `{ target }`,否则 400 `request.body_shape`;`target` 不是声明的同步身份 ⇒ 400 `request.field_invalid`(`field` / `reason`,不回显值)。
+ *  7. 读集(上一节)。
+ *  8. 目标比对:`target` ≠ 本机腿的 `peer` ⇒ 报告 `refused: config.memory_sync_target_mismatch`(句由 core 铸;零请求零本地写)。先于空读集出口。
+ *  9. 收割栅栏(前检):会话**不静** ⇒ 报告 `refused: session_active`(句由本服务铸)。零请求。
+ *     **静** = 一只谓词,前检与后检同读,三格合取:会话没有认领 ∧ 最近受理的腿**就是**观测所在的那一条(读完观测之后没有新 run 被受理)∧ 会话叶子仍是 `sourceRevision`
+ *     (会话的记录没有前进)。次序 = 认领 → 最近受理的腿 → 叶子:run 行在受理时同步落库、消息在那之后才追加,所以认领读之后才受理的 run 在第二只读里看得见;
+ *     第三格不靠建行时刻 —— 「最近受理」按建行时刻排序,副本之间钟偏 / 时钟回拨时一条后受理的 run 可以排在观测腿之前,而它只要跑过就挪动了叶子。
+ * 10. 一轮:读集为空 ⇒ 空报告(同一只铸点);否则 `syncOnce("session-trigger", { reading })`,只挑读集里的层的调用交给引擎出报告。
+ * 11. 收割栅栏(后检):轮落定后会话不静 ⇒ 第 9 步的报告 —— 这一轮的请求与写已经发生(幂等,下次触发重放),报告只是不再为这份读集作保。
+ *     报告之后、fork 之前的源前进不由本口封闭:壳拿 `sourceRevision` 与它推上云的会话头比。
+ * 12. 引擎的报告铸点自己抛 `TypeError`(名字带凭据 / 空串)⇒ 500 + 运维 warn(拒句不引原值)。同步层名起服时已过同一只凭据判官(`config.ts`),这一臂按构造不可达。
+ *
+ * ── 并发 ───────────────────────────────────────────────────────────────────────────────────────
+ * 同一会话、同一 `sourceRevision`、同一观测腿、同一 `target` 的请求各自走完 1–9,再**并入**在飞的那一轮,拿同一份报告(只减少重复工作,不延长等待)。
+ * 别的会话 / 后台轮经腿的同一条串行链(`exclusive`):会话触发的轮起跑晚于本请求到达。请求方断开不取消轮。本口不设自己的截止(= 各调用的传输超时之和)。
+ *
+ * ── 计费 / 门 ──────────────────────────────────────────────────────────────────────────────────
+ * 零模型工作(不 billable、不吃 drain 503);写的是调用方自己的记忆到它自己配置的中心 ⇒ 属主门兜底,不进无凭据改写门(会话自助抹除同判)。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { EffectiveMemoryScopes } from "../../plugins/store-contracts.js";
+/** 收割栅栏的句(本服务铸;码 `session_active` 是引擎报告闭集的成员)。 */
+export declare const SESSION_ACTIVE_SYNC_MESSAGE = "a run in this session is in flight, or the session moved on after the memory it reads was observed (a run was admitted or its transcript advanced) \u2014 wait for it to finish on its own, then sync again (do not cancel it to sync sooner)";
+/** 读集 = 最近一条已结腿的记忆观测(三态穷举;引擎加第四态 ⇒ 编译红)。 */
+export declare function sessionReadSetOf(observation: EffectiveMemoryScopes): readonly string[];
+export declare function handleSessionMemorySync(req: IncomingMessage, res: ServerResponse, match: RouteMatch<SessionMemorySyncRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const SESSION_MEMORY_SYNC_ROUTES: readonly [{
+    readonly id: "session-memory-sync";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/memory/sync";
+    readonly methods: readonly ["POST"];
+}];
+/** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
+export type SessionMemorySyncRouteId = RouteIdsOf<typeof SESSION_MEMORY_SYNC_ROUTES>;
+//# sourceMappingURL=session-memory-sync.d.ts.map

package/dist/http/routes/session-memory-sync.js

@@ -0,0 +1,157 @@
+import { memorySyncReportOf } from "@sema-agent/core";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import {} from "../route-ctx.js";
+import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
+import { sessionOwnerCellOf } from "../../security.js";
+import { leafOfAdmittedHead } from "../../session-incarnation.js";
+import { declaredMemorySyncIdentityFlaw, memorySyncIdentityRule } from "../../memory-sync-identity.js";
+export const SESSION_ACTIVE_SYNC_MESSAGE = "a run in this session is in flight, or the session moved on after the memory it reads was observed (a run was admitted or its transcript advanced) — wait for it to finish on its own, then sync again (do not cancel it to sync sooner)";
+export function sessionReadSetOf(observation) {
+    switch (observation.state) {
+        case "mounted":
+            return observation.scopes.map((s) => s.scope);
+        case "memoryless":
+        case "none":
+            return [];
+        default:
+            return assertNever(observation);
+    }
+}
+class ReportMintRefused extends Error {
+}
+function reportOf(round) {
+    try {
+        return memorySyncReportOf(round);
+    }
+    catch (err) {
+        if (err instanceof TypeError)
+            throw new ReportMintRefused(err.message);
+        throw err;
+    }
+}
+const inflightByLeg = new WeakMap();
+function mergedRound(leg, key, run) {
+    let table = inflightByLeg.get(leg);
+    if (table === undefined) {
+        table = new Map();
+        inflightByLeg.set(leg, table);
+    }
+    const inflight = table.get(key);
+    if (inflight !== undefined)
+        return inflight;
+    const owner = table;
+    const round = run().finally(() => {
+        if (owner.get(key) === round)
+            owner.delete(key);
+    });
+    table.set(key, round);
+    return round;
+}
+export async function handleSessionMemorySync(req, res, match, ctx) {
+    const { deps } = ctx;
+    switch (match.decl.id) {
+        case "session-memory-sync": {
+            const fact = facts.sessionMemorySync(deps);
+            if (!fact.available) {
+                switch (fact.why) {
+                    case "memory_sync_leg_absent":
+                        sendError(res, 501, "feature.memory_sync_disabled", "session memory sync is not available on this deployment — it runs only where a file memory engine syncs to a center (MEMORY_SYNC_URL)");
+                        return;
+                    case "run_store_absent":
+                        sendError(res, 501, "capability.run_store_required", "session memory sync requires a durable run store (DB_BACKEND=mysql|pg|local) — the session's read set is the memory its latest settled run observed");
+                        return;
+                    case "session_head_face_absent":
+                        sendError(res, 501, "capability.session_ownership_required", "session memory sync requires the session-ownership face (sessionStorage.headOf)");
+                        return;
+                    default:
+                        return assertNever(fact.why);
+                }
+            }
+            const { leg, runStore, sessionStorage } = fact;
+            if (deps.config.requirePrincipal && gatedPrincipal(req, deps.config) === undefined) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return;
+            }
+            if (ctx.helpers.rateLimited(req, res))
+                return;
+            const sessionId = ctx.helpers.safeDecode(match.params.sessionId);
+            if (sessionId === null) {
+                sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
+                return;
+            }
+            const readHead = () => sessionStorage.headOf(sessionId);
+            const head = await readHead();
+            if (head === undefined) {
+                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                return;
+            }
+            if (!ctx.helpers.sessionOwnerOk(req, res, await sessionOwnerCellOf(sessionStorage, sessionId, head.owner)))
+                return;
+            const sourceRevision = leafOfAdmittedHead(head);
+            const body = await ctx.helpers.readJson(req);
+            if (body === null || typeof body !== "object" || Array.isArray(body) || Object.keys(body).some((k) => k !== "target") || typeof body.target !== "string") {
+                sendError(res, 400, "request.body_shape", "body must be { target: string } — the sync identity the target engine publishes (GET /v1/capabilities → memorySyncServe.identity), verbatim; no other key");
+                return;
+            }
+            const target = body.target;
+            const flaw = declaredMemorySyncIdentityFlaw(target);
+            if (flaw !== undefined) {
+                sendError(res, 400, "request.field_invalid", `target ${memorySyncIdentityRule(flaw)} — send the target engine's memorySyncServe.identity exactly as GET /v1/capabilities publishes it`, { field: "target", reason: flaw });
+                return;
+            }
+            const observed = await runStore.latestMemoryObservationForSession(sessionId);
+            if (observed?.effectiveMemoryScopes === undefined || sourceRevision === null) {
+                const activeTaskId = await runStore.getActiveTaskId(sessionId);
+                sendError(res, 409, "conflict.session_memory_unobserved", "this session has no settled run with a memory observation yet, so there is nothing to say about which memory it reads — run a task in it (or let the run in flight finish), then sync", activeTaskId !== undefined ? { activeTaskId } : undefined);
+                return;
+            }
+            const scopes = sessionReadSetOf(observed.effectiveMemoryScopes);
+            const quiet = async () => {
+                if ((await runStore.getActiveTaskId(sessionId)) !== undefined)
+                    return false;
+                if ((await runStore.latestRunForSession(sessionId))?.taskId !== observed.taskId)
+                    return false;
+                const now = await readHead();
+                return now !== undefined && leafOfAdmittedHead(now) === sourceRevision;
+            };
+            const fenced = () => reportOf({ target, sourceRevision, scopes, refused: { code: "session_active", message: SESSION_ACTIVE_SYNC_MESSAGE } });
+            let report;
+            try {
+                if (target !== leg.peer) {
+                    report = reportOf({ target, sourceRevision, scopes, refused: { code: "config.memory_sync_target_mismatch", reaches: leg.peer } });
+                }
+                else if (!(await quiet())) {
+                    report = fenced();
+                }
+                else if (scopes.length === 0) {
+                    report = reportOf({ target, sourceRevision, scopes, layers: [] });
+                }
+                else {
+                    report = await mergedRound(leg, JSON.stringify([sessionId, sourceRevision, observed.taskId, target]), async () => {
+                        const round = await leg.syncOnce("session-trigger", { reading: scopes });
+                        if (!(await quiet()))
+                            return fenced();
+                        return reportOf({ target, sourceRevision, scopes, layers: round.calls.filter((c) => scopes.includes(c.scope)) });
+                    });
+                }
+            }
+            catch (err) {
+                if (!(err instanceof ReportMintRefused))
+                    throw err;
+                deps.logger?.warn?.("session_memory_sync_report_refused", { sessionId, err: err.message });
+                sendError(res, 500, "internal.error", "memory sync failed");
+                return;
+            }
+            sendJson(res, 200, report);
+            return;
+        }
+        default:
+            return assertNever(match.decl.id);
+    }
+}
+export const SESSION_MEMORY_SYNC_ROUTES = [
+    { id: "session-memory-sync", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/memory\/sync$/, label: "/v1/sessions/:id/memory/sync", methods: ["POST"] },
+];
+//# sourceMappingURL=session-memory-sync.js.map

package/dist/http/routes/session-sync.d.ts

@@ -9,7 +9,7 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionRulesRecord, type FileHistoryExport } from "@sema-agent/core";
-import { type StagingHandle } from "../../session-sync-kernel.js";
+import { type ImportAnchor, type StagingHandle } from "../../session-sync-kernel.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 import { type SessionRowPatch } from "../../session-row.js";
 export type PendingStaging = {
@@ -21,11 +21,8 @@ export type PendingStaging = {
     /** [ref]: the session's file-history envelope (or null — no history travelled). Replaces the E19 per-key manifests. */
     fileHistory: FileHistoryExport | null;
     policy: SessionRulesRecord[];
-    anchors: Array<{
-        eventId: string;
-        entryId: string;
-        owner: string | null;
-    }>;
+    /** 已在 Phase A 入口判过的锚(`readImportAnchors`:每条 `entryId` 都在 `declaredEntryIds` 里)—— 提交后的重放腿只迭代它,不再判;owner 不带(重钉到 `owner`)。 */
+    anchors: ImportAnchor[];
     /** 会话行的两位可写位(Phase A 体里带了哪几键就重放哪几键;老客户端不带 ⇒ `{}`,目的端两位不动)。提交后经会话店唯一写口落。 */
     row: SessionRowPatch;
     /** 交叉复查 A-3(HIGH):Phase A's DECLARED entry-id set — Phase B verifies the streamed NDJSON matches it

package/dist/http/routes/session-sync.js

@@ -4,7 +4,7 @@ import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator
 import { StringDecoder } from "node:string_decoder";
 import { FileHistoryUnreadableError, blobGetterOf, exportSessionManifest, exportedFileHistory, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, wipeSessionAttendants } from "../../session-sync.js";
 import * as facts from "../../capability-facts.js";
-import { classifySyncRelationshipByIds, SyncConflictError } from "../../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, readImportAnchors, SyncConflictError } from "../../session-sync-kernel.js";
 import { isUuidShape, legacyUnownedSessionOk, sessionOwnerCellOf } from "../../security.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, logRequestError, msg } from "../send.js";
 import { buildDisplaySafeUrl } from "../../trace/redact.js";
@@ -307,6 +307,11 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 400, "request.body_shape", "malformed import metadata");
                     return;
                 }
+                const anchorsRead = readImportAnchors(body.anchors, body.entryIds);
+                if ("problem" in anchorsRead) {
+                    sendError(res, 400, "request.field_invalid", anchorsRead.problem);
+                    return;
+                }
                 const policyRead = readSessionRulesRecords(body.policy);
                 if (policyRead.problem !== undefined) {
                     if (policyRead.problem.kind === "rules") {
@@ -350,7 +355,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const srcLogDigest = typeof body.logDigest === "string" && body.logDigest.length > 0 ? body.logDigest : undefined;
                 const entryIds = body.entryIds;
                 const policy = policyRead.records;
-                const anchors = body.anchors;
+                const anchors = anchorsRead.anchors;
                 const dstIds = (await sessionStorage.listEntryIds?.(sessionId)) ?? null;
                 const relA = classifySyncRelationshipByIds(entryIds, dstIds);
                 if ((relA.relation === "fork" || relA.relation === "stale") && resolution !== "overwrite-dst") {

package/dist/http/routes/sessions-list.d.ts

@@ -16,7 +16,8 @@ export declare function handleSessionsList(req: IncomingMessage, res: ServerResp
  * 会话列表行的 **wire 投影** —— `GET /v1/sessions` 的每一行与 `PATCH /v1/sessions/:id` 的 200 回执是**同一只**(店行 → wire 行只有这一处)。
  *  · 预览:店行读的是 run 行预览列的事实位(`""` = 有记录、剥完没有用户正文;NULL = 没记录);本面只说「有没有可显示的预览」⇒ 两者都是 `null`。
  *  · `tempo`:见上方 [ref] 注(由 `lastStatus` 经唯一一张表派生;omit-when-absent)。
- *  · 其余键(含 `title` / `pinned`)零投影透传 —— 店行是唯一铸点。
+ *  · 其余键(含 `title` / `pinned` / `rowTag` / `unreadable`)零投影透传 —— 店行是唯一铸点(`unreadable` 的码出自 `session-error-wire.ts` 的那一张表,
+ *    与全局兜底对同一只会话答的码同读;SQL 孪生的叶子是行上一列 ⇒ 恒缺席)。
  */
 export declare function projectSessionListRow(r: SessionListItem): SessionListItem & {
     tempo?: ReturnType<typeof sessionTempoOfRunStatus>;

package/dist/http/routes/sessions.js

@@ -526,14 +526,14 @@ export async function handleSessions(req, res, match, ctx) {
             }
             const auditFact = facts.sessionAuditView(deps);
             if (!auditFact.available) {
-                sendError(res, 501, "capability.memory_engine_required", "memory provenance and erasure are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
+                sendError(res, 501, "capability.memory_engine_required", "memory provenance and erasure are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/mysql memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
             if ((await readOwnedSessionView(auditFact.sessionAudit, sessionId)) === undefined)
                 return;
             const faces = deps.memoryCompliance;
             if (faces === undefined) {
-                sendError(res, 501, "capability.memory_engine_required", "memory provenance and erasure are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
+                sendError(res, 501, "capability.memory_engine_required", "memory provenance and erasure are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/mysql memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
             const raw = (await readJson(req));
@@ -585,14 +585,14 @@ export async function handleSessions(req, res, match, ctx) {
             }
             const auditFact = facts.sessionAuditView(deps);
             if (!auditFact.available) {
-                sendError(res, 501, "capability.memory_engine_required", "session memory status is not available on this deployment — it requires a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
+                sendError(res, 501, "capability.memory_engine_required", "session memory status is not available on this deployment — it requires a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/mysql memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
             if ((await readOwnedSessionView(auditFact.sessionAudit, sessionId)) === undefined)
                 return;
             const face = deps.sessionMemoryStatus;
             if (face === undefined) {
-                sendError(res, 501, "capability.memory_engine_required", "session memory status is not available on this deployment — it requires a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
+                sendError(res, 501, "capability.memory_engine_required", "session memory status is not available on this deployment — it requires a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/mysql memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
             const query = new URLSearchParams(match.search);
@@ -619,6 +619,7 @@ export async function handleSessions(req, res, match, ctx) {
                 sendJson(res, 200, {
                     sessionId,
                     autoConsolidationArmed: deps.memoryAutoConsolidationArmed,
+                    ...(deps.memorySyncLeg !== undefined ? { memorySync: { parked: deps.memorySyncLeg.parked().map((p) => ({ scope: p.scope, wayOut: p.wayOut })) } } : {}),
                     ...(s.captureOptedOut !== undefined ? { captureOptedOut: s.captureOptedOut } : {}),
                     ...(s.committedCount !== undefined ? { committedCount: s.committedCount } : {}),
                     ...(s.foldedCount !== undefined ? { foldedCount: s.foldedCount } : {}),