@sema-agent/server 7.133.0 → 7.134.0

package/dist/plugins/session-placement.d.ts

@@ -33,7 +33,7 @@
  *    宿主可枚举、release 不真删的普通会话 ——「声明了 full tier 却在静默说谎」。⇒ 在**声明了分区**的
  *    店上,带 placement 的 acquire 必须回读到**已持久化**且同一元组身份的行,回读缺失/异组=响亮拒。
  */
-import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord } from "@sema-agent/core";
+import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore } from "@sema-agent/core";
 /**
  * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`)。
  *
@@ -88,20 +88,18 @@ export interface PlacementAcquireOpts {
     placement?: SessionPlacement;
 }
 /**
- * 准入判据 —— **两个方向**(顶注 ①②;core `TtlSessionStore.assertPlacementAdmission` 的 SQL 镜像,
- * 逐条同义,文案自铸)。
- *
- * @param persisted 该 id 在库里**已持久化**的元组(缺席 = 普通会话 / 无此行)。
- *
- * · 方向①(claim 关门):`persisted` 在场 + 非 `requireExisting` + 调用方没带创建 placement ⇒ 拒。
- *   `requireExisting`(读/复活形,义务 5)与「创建调用及其幂等重取」(带 placement 的可信内部链)
- *   是仅有的两个合法形。placement 不可变意味着带 placement 的参数**永远重写不了**任何东西——持久化
- *   的那一份恒赢,所以放行它不开任何口子。
- * · 方向②(镜像/squat):带 placement 的创建形回读到**缺席**或**异组**元组 ⇒ 拒。缺席 = 并发的
- *   claim 形抢先建出了普通会话(或带外写把元组抹了);异组 = 同 id 上坐着另一条委派链的转录。
- *   两者都不许让「声明了 durable 分区」这句话在静默中变成谎。
+ * 准入判据 —— 只有引擎那一只:core 包根导出 `admitSessionPlacement(sessionId, persisted, request, capability)`(core 7.54.0 #1468 K2;
+ * `TtlSessionStore` 自己调的同一只函数,两个方向:claim 关门 / 镜像·squat,`placement_refused`)。`capability.subagentPlacement` 读的是**店自己的声明**
+ * (`placements.subagent` 在场 —— 与 core `TtlSessionStore` 同一只读法,{@link placementCapabilityOf}),不是另写一个「这只店声明了」的常量:声明只有一处。
+ * 修前本模块持一份 SQL 镜像(`assertPlacementAdmission`,逐条同义、文案自铸)—— 与引擎是两份判据;随 7.54.0 退役、零别名。
+ * 拒句随之换成引擎的句子(缺元组那一形的结尾词:「or the repo dropped the tuple」,此前本仓写「written away out of band」)——
+ * 按原句匹配告警的运维规则要跟着改(MIGRATION 7.134.0 节记了这一句)。
  */
-export declare function assertPlacementAdmission(sessionId: string, persisted: SessionPlacementRecord | undefined, opts?: PlacementAcquireOpts): void;
+export declare function placementCapabilityOf(store: {
+    readonly placements?: SessionStore["placements"];
+}): {
+    readonly subagentPlacement: boolean;
+};
 /**
  * 一次 `listPlaced` 最多带回的行数。
  *

package/dist/plugins/session-placement.js

@@ -45,21 +45,8 @@ export function placementInsertValues(placement, placedAt) {
         placedAt,
     ];
 }
-export function assertPlacementAdmission(sessionId, persisted, opts) {
-    if (opts?.requireExisting === true)
-        return;
-    if (persisted !== undefined && opts?.placement === undefined) {
-        throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${persisted.kind} placement partition — a claim-form acquire cannot attach to it (read it with requireExisting, or address the agent through its a* handle)`);
-    }
-    if (opts?.placement === undefined)
-        return;
-    const want = opts.placement;
-    if (persisted === undefined) {
-        throw new SessionError("placement_refused", `session ${sessionId} exists OUTSIDE the ${want.kind} placement partition it was declared into — refusing to run a subagent transcript on it (a concurrent claim-form create won this id, or the tuple was written away out of band)`);
-    }
-    if (persisted.kind !== want.kind || persisted.scope !== want.scope || persisted.handle !== want.handle) {
-        throw new SessionError("placement_refused", `session ${sessionId}'s persisted placement does not match the declared one (persisted ${persisted.kind}/${persisted.scope ?? "-"}/${persisted.handle ?? "-"} vs declared ${want.kind}/${want.scope ?? "-"}/${want.handle ?? "-"}) — refusing a cross-tuple attach`);
-    }
+export function placementCapabilityOf(store) {
+    return { subagentPlacement: store.placements?.subagent !== undefined };
 }
 export const LIST_PLACED_BATCH = 1000;
 //# sourceMappingURL=session-placement.js.map

package/dist/plugins/tidb-session-store.d.ts

@@ -187,7 +187,7 @@ export declare class TiDBSessionStore implements SessionStore {
      * We instead SELECT the entire `session_event` log ordered by seq — every durable entry, compaction floor
      * bypassed — and re-seq it dense from 0 into the new session, ids/parents/payload byte-verbatim.
      */
-    fork(sourceId: string, owner: string | null): Promise<string | null>;
+    fork(sourceId: string, owner?: string | null): Promise<string | null>;
     /**
      * 2c session-sync — EXPORT a session's full durable entry log for cross-backend migration. This is the
      * READ half of {@link fork}, surfaced as the core `SessionRepo.exportEntries` seam: the WHOLE `session_event` log,

package/dist/plugins/tidb-session-store.js

@@ -1,4 +1,4 @@
-import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry } from "@sema-agent/core";
+import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./tidb-session-storage.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
 import { jsonColumnText } from "./sql-json-column.js";
@@ -9,8 +9,9 @@ import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
 import { createLogger } from "../observability/logger.js";
-import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
-import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
 export class TiDBSessionStore {
     pool;
     retention = MANAGED_RETENTION;
@@ -32,7 +33,7 @@ export class TiDBSessionStore {
         const inflight = this.pending.get(sessionId);
         if (inflight) {
             const acquired = await inflight;
-            assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
+            admitSessionPlacement(sessionId, await this.placementOf(sessionId), opts ?? {}, placementCapabilityOf(this));
             return acquired;
         }
         const p = this.load(sessionId, false, opts).finally(() => this.pending.delete(sessionId));
@@ -42,7 +43,7 @@ export class TiDBSessionStore {
     async load(sessionId, requireExisting = false, opts) {
         let storage = await TiDBSessionStorage.wake(this.pool, sessionId);
         if (storage) {
-            assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
+            admitSessionPlacement(sessionId, (await storage.getMetadata()).placement, opts ?? {}, placementCapabilityOf(this));
             return { session: new StoredSession(storage), sessionId };
         }
         if (requireExisting)
@@ -52,10 +53,15 @@ export class TiDBSessionStore {
         if (!storage) {
             throw new SessionError("storage", `session ${sessionId} vanished between register and wake (a concurrent purge won the race) — retry`);
         }
-        assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
+        admitSessionPlacement(sessionId, (await storage.getMetadata()).placement, opts ?? {}, placementCapabilityOf(this));
         return { session: new StoredSession(storage), sessionId };
     }
     async register(sessionId, owner) {
+        if (typeof owner !== "string" && owner !== null) {
+            if ((await this.ownerOf(sessionId)) !== undefined)
+                return;
+            assertFirstOwnerWritable(sessionId, owner);
+        }
         await this.insertMeta(sessionId, owner, undefined);
     }
     async createOnAcquire(sessionId, placement) {
@@ -259,10 +265,11 @@ export class TiDBSessionStore {
         }
     }
     async fork(sourceId, owner) {
-        const [metaRows] = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = ?", [sourceId]);
+        const [metaRows] = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = ?", [sourceId]);
         if (!metaRows[0])
             return null;
         const leafId = metaRows[0].leaf_id ?? null;
+        const forkOwner = forkOwnerOf(owner, metaRows[0].owner ?? null) ?? null;
         const [eventRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
         const newId = uuidv7();
         const now = new Date();
@@ -274,7 +281,7 @@ export class TiDBSessionStore {
                 const payload = String(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?)", [newId, owner, now, now, leafId, eventRows.length, mintSessionIncarnation()]);
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?)", [newId, forkOwner, now, now, leafId, eventRows.length, mintSessionIncarnation()]);
             await conn.commit();
             return newId;
         }
@@ -476,6 +483,23 @@ class TiDBStagingHandle {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            const now = new Date();
+            const minted = mintSessionIncarnation();
+            if (opts.expectedOwner !== undefined) {
+                const [cas] = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = ? AND owner <=> ?", [this.realSessionId, opts.expectedOwner]);
+                if (cas.affectedRows !== 1) {
+                    await conn.rollback();
+                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                }
+            }
+            else {
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,NULL,0,?) ON DUPLICATE KEY UPDATE session_id = session_id", [this.realSessionId, owner, now, now, minted]);
+                const [claimed] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [this.realSessionId]);
+                if (String(claimed[0]?.incarnation) !== minted) {
+                    await conn.rollback();
+                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                }
+            }
             const [stagedRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const [dstRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const [dstMeta] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ?", [this.realSessionId]);
@@ -484,15 +508,15 @@ class TiDBStagingHandle {
                 throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${String(dstMeta[0].placement_kind)} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
             }
             const srcIds = stagedRows.map((r) => String(r.entry_id));
-            const dstIds = dstMeta[0] ? dstRows.map((r) => String(r.entry_id)) : null;
+            const dstIds = opts.expectedOwner !== undefined ? dstRows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
-            if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
+            if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 await conn.rollback();
                 throw new SyncConflictError(this.realSessionId, rel);
             }
-            if (rel.relation === "fast_forward" && opts?.resolution !== "overwrite-dst" && dstIds !== null && dstIds.length > 0) {
-                const [dstFull] = await conn.query(`SELECT seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [this.realSessionId]);
-                const [stagedFull] = await conn.query(`SELECT entry_id, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [this.stagingId]);
+            if (rel.relation === "fast_forward" && opts.resolution !== "overwrite-dst" && dstIds !== null && dstIds.length > 0) {
+                const [dstFull] = await conn.query(`SELECT seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE`, [this.realSessionId]);
+                const [stagedFull] = await conn.query(`SELECT entry_id, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE`, [this.stagingId]);
                 const dstSet = new Set(dstIds);
                 const dstEntries = dstFull.map((r) => decodeSessionEventPayload(r.payload, this.realSessionId, r.seq));
                 const stagedShared = stagedFull
@@ -506,13 +530,11 @@ class TiDBStagingHandle {
             }
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [this.realSessionId]);
             await conn.query("UPDATE session_event SET session_id = ? WHERE session_id = ?", [this.realSessionId, this.stagingId]);
-            const [lastRow] = await conn.query(`SELECT ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq DESC LIMIT 1`, [this.realSessionId]);
+            const [lastRow] = await conn.query(`SELECT ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq DESC LIMIT 1 FOR UPDATE`, [this.realSessionId]);
             let leafId = null;
             if (lastRow[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRow[0].payload, this.realSessionId, "last staged row"));
-            const now = new Date();
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?) " +
-                "ON DUPLICATE KEY UPDATE owner = VALUES(owner), updated_at = VALUES(updated_at), leaf_id = VALUES(leaf_id), leaf_seq = VALUES(leaf_seq)", [this.realSessionId, owner, now, now, leafId, srcIds.length, mintSessionIncarnation()]);
+            await conn.query("UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ? WHERE session_id = ?", [owner, now, leafId, srcIds.length, this.realSessionId]);
             const [afterMeta] = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = ?", [this.realSessionId]);
             if (afterMeta[0]?.placement_kind != null) {
                 await conn.rollback();

package/dist/request-tool-axes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 请求侧 `toolAxes` 声明的读法 —— `mcpServers[].toolAxes`(`task-mcp.ts`)与 `a2aPeers[].toolAxes`(`task-a2a.ts`)同一只。
+ *
+ * 律(一句):判官是引擎包根的 `readToolAxes(declared, at)`;请求侧再多一条 —— **不许写 `boundaryFlow`**。
+ * `boundaryFlow: "engine"`(须同条 `egress: false`)声明一只引擎专用工具:名册行读成零条腿,设备车道的发射闸对它的调用不欠任何东西。
+ * 引擎分不出一条声明来自请求还是部署,所以这个位只许部署声明(`config.d` / 配置中心)写 —— 那两条腿原样交引擎(由引擎判 `egress: false`)。
+ * 读数形与引擎判官同一只(`ToolAxesRead`):请求侧写了这个位 ⇒ `ok: false`,原因句点名工具(或 skill)与出路;各腿按自己既有的「判不过」处置读它
+ * (MCP 新提交 400 点名 / 续跑重放整条 server 不进;A2A 整条对端不挂、warn 点名)。
+ */
+import { type ToolAxesRead, type ToolAxesSurface } from "@sema-agent/core";
+export declare function readRequestToolAxes(declared: unknown, at: ToolAxesSurface): ToolAxesRead;
+//# sourceMappingURL=request-tool-axes.d.ts.map

package/dist/request-tool-axes.js

@@ -0,0 +1,20 @@
+import { readToolAxes } from "@sema-agent/core";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
+import { MAX_KEY_ECHO } from "./request-key-closure.js";
+const KEY_NOUN = { mcp: "tool", a2a: "skill" };
+export function readRequestToolAxes(declared, at) {
+    const read = readToolAxes(declared, at);
+    if (!read.ok || read.toolAxes === undefined)
+        return read;
+    for (const [name, axes] of Object.entries(read.toolAxes)) {
+        if (axes !== undefined && Object.hasOwn(axes, "boundaryFlow")) {
+            return {
+                ok: false,
+                problem: `the axes declared for ${KEY_NOUN[at]} ${JSON.stringify(stripControlAndBidi(name).slice(0, MAX_KEY_ECHO))} carry "boundaryFlow", which only a deployment's declaration may state ` +
+                    `(it declares an engine-only ${KEY_NOUN[at]}, so the device lane's launch gate would owe its calls nothing; the engine cannot tell a request's entry from a deployment's) — drop "boundaryFlow"`,
+            };
+        }
+    }
+    return read;
+}
+//# sourceMappingURL=request-tool-axes.js.map

package/dist/run-local.js

@@ -173,6 +173,7 @@ export const NO_TTY_ASK_CLASS_ROW = {
     unstated: { remedy: "grant", autoBudgetReleases: false },
     ordinary: { remedy: "grant", autoBudgetReleases: false },
     requires_user_interaction: { remedy: "terminal_only", autoBudgetReleases: false },
+    cross_boundary: { remedy: "terminal_only", autoBudgetReleases: false },
 };
 const NO_TTY_REMEDY_SENTENCE = {
     grant: () => `Nothing on the allow layer covers this call: the operator can clear this kind of question once with APPROVAL_GRANT ` +

package/dist/runs.d.ts

@@ -7,7 +7,7 @@ import { type RunAbort } from "./run-cancel-context.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "./budget.js";
 import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
-import { type ToolApprovalCoordinator } from "./tool-approval.js";
+import { type ApprovalFrameFamily, type ToolApprovalCoordinator } from "./tool-approval.js";
 import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
 import type { RunAcceptance } from "./run-acceptance.js";
@@ -329,6 +329,7 @@ approval?: {
     streamApprovalOn: boolean;
     windowMs: number | undefined;
     windowMarginMs: number;
+    declaredFamilies: ReadonlySet<ApprovalFrameFamily>;
 }, 
 /** [ref]:park 投影腿的 checkpoint 读口(`deps.checkpointStore`)。在场时,durable park 的
  *  `suspended` 事件带 `toolCallId`(graft 见 {@link parkToolCallId});缺席=旧字节逐字不变。 */

package/dist/runs.js

@@ -271,12 +271,13 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         windowMarginMs: approval?.windowMarginMs ?? 0,
         ...(typeof spec.limits?.maxWalltimeMs === "number" ? { legWalltimeMs: spec.limits.maxWalltimeMs } : {}),
         nowMonotonicMs: performance.now(),
+        declaredFamilies: approval?.declaredFamilies ?? new Set(),
     });
     const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
     if (approval) {
         const coordinator = approval.coordinator;
-        spec.onAsk = approvalLeg.windowZero
-            ? coordinator.boundUnattendedAsk({ owner: elicitOwner ?? owner, taskId, ...(spec.sessionId ? { sessionId: spec.sessionId } : {}) })
+        spec.onAsk = approvalLeg.unattended
+            ? coordinator.boundUnattendedAsk({ owner: elicitOwner ?? owner, taskId, ...(spec.sessionId ? { sessionId: spec.sessionId } : {}) }, approvalLeg.unattended)
             : coordinator.boundAsk({
                 owner: elicitOwner ?? owner,
                 taskId,
@@ -504,7 +505,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             const withQuestion = () => question
                 ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: questionEmit, abortSignal: cancelCtrl.signal }, withElicit)
                 : withElicit();
-            const withApproval = () => approval && approvalLeg.active && !approvalLeg.windowZero
+            const withApproval = () => approval && approvalLeg.active && approvalLeg.unattended === undefined
                 ? approval.coordinator.runWithContext({
                     taskId,
                     owner: elicitOwner ?? owner,

package/dist/sealed-key.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "./observability/logger.js";
+import { type CheckpointCtxSealing } from "./http/checkpoint-ctx.js";
 /** Algorithm tag — MUST equal registry-core's `SEALED_BOX_ALG` (v1 sole value; a different alg on
  *  the wire is a loud per-model rejection in applyEffective, never a guess). */
 export declare const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
@@ -61,6 +62,36 @@ export declare function deriveKeyId(publicKeyRaw: Uint8Array): string;
  * zero loadable keys AND generation failed).
  */
 export declare function ensureSealedKeyStore(dir: string, logger?: Logger): Promise<SealedKeyStore>;
+declare const checkpointCtxKeyStoreBrand: unique symbol;
+/**
+ * 停驻行封签那一域的保管店(品牌型):读口与 {@link SealedKeyStore} 同形,型不同 —— {@link createCheckpointCtxSealing} 只收它,模型钥匙那只店交进去是 tsc 错
+ * (「两域并成一对钥匙」那条路在型面上关掉,不靠注释)。唯一铸点 = {@link ensureCheckpointCtxSealing} 建店处(经 {@link mintCheckpointCtxKeyStore});
+ * 品牌断言的普查在 `test/owner-gate-single-owner.test.ts` ⑤b。
+ */
+export type CheckpointCtxKeyStore = SealedKeyStore & {
+    readonly [checkpointCtxKeyStoreBrand]: true;
+};
+/**
+ * 停驻行封签器的**生产工厂**(起服 web-admin 运行时与嵌入方同调这一只):在 `sealedKeyDir`(`<数据根>/sealed-key`)之下的 {@link CHECKPOINT_CTX_KEY_SUBDIR}
+ * 建这一域自己的保管店(同一只 {@link ensureSealedKeyStore}:目录 0700、钥匙文件 0600、空目录生成一把、读不了的文件跳过不删),再交 {@link createCheckpointCtxSealing}。
+ * 钥匙只在这里读进内存(起服一次):进程运行中补进目录的钥匙文件要重启才认。
+ * 抛 = 这一域没有封签器(目录建不了 / 改不了权限,或钥匙文件公私不配对);调用方当「没有封签器」处置。
+ */
+export declare function ensureCheckpointCtxSealing(sealedKeyDir: string, logger?: Logger): Promise<CheckpointCtxSealing>;
+/**
+ * 停驻行凭据的**封签器**(S-1907;形与规则的属主 = `http/checkpoint-ctx.ts` 末段「凭据位密封」)—— 从**这一域自己的**保管店派生(生产 = {@link ensureCheckpointCtxSealing};
+ * 入参型 {@link CheckpointCtxKeyStore}:模型钥匙那只店进不来),信封是:封进密文的明文是 `JSON.stringify([CHECKPOINT_CTX_SEAL_ALG, sessionId, value])`。
+ *  · **封**:对着保管店**最新**那把公钥 `crypto_box_seal`(只用公钥);封签记下那把钥匙的 id。
+ *  · **开**:按封签上的 id **精确**选私钥(保管店的 `open`,不逐把试),再判信封:三元数组、首元是本信封的词、第二元是**这一行的会话 id**,交回第三元(封进去的 JSON 值,任何类型) ——
+ *    任何一条不成立 ⇒ 抛。域隔离由钥匙给(两域两对钥匙:模型钥匙的密文放进停驻行凭据位 ⇒ 这一域不持有那把钥匙;反过来停驻行的封签放进 `sealedApiKey` ⇒ 模型钥匙店不持有),
+ *    信封再给**行绑定**(别的会话那一行的封签搬过来开不开)与格式词 —— 持有本对象的那一层(HTTP 续跑腿)拿到的是「只开停驻行封签」的口;
+ *    私钥本身、保管目录、持有 id 列表照旧够不着(只多一个 `holds(id)`:开之前判「这把钥匙在不在本副本」,`key_not_held` 与 `unopenable` 分开报)。
+ *  · 错误句不带明文:信封解析失败只报「不是停驻行封签」(`JSON.parse` 的报错会嵌入输入片段 —— 那里可能是一只模型钥匙),保管店的错误句只说哪把钥匙 / 哪种失败。
+ * 前置条件:`store` 来自 {@link ensureSealedKeyStore}(它已等过 libsodium 就绪);没就绪 ⇒ 当场响亮抛,不造一只封不了的对象。
+ * **自检**:交出之前对最新那把钥匙封一只探针、再开回来 —— 开不回来(保管档里公私钥不配对:长度都对,装载照收)⇒ 当场抛。封得进、开不出的封签器比没有更坏:
+ * 起服的一次性迁移 M28 会用它把还读得懂的明文行换成谁都开不开的密文。调用方(web-admin 运行时)把这一抛当「没有封签器」处置 ⇒ 耐久审批在场的部署起服拒。
+ */
+export declare function createCheckpointCtxSealing(store: CheckpointCtxKeyStore): CheckpointCtxSealing;
 /**
  * Best-effort public-key registration with the web-admin (`POST /api/config/execution-keys`).
  *
@@ -86,4 +117,5 @@ export declare function reportExecutionPublicKey(opts: {
     /** Test seam. */
     fetchImpl?: typeof fetch;
 }): Promise<void>;
+export {};
 //# sourceMappingURL=sealed-key.d.ts.map

package/dist/sealed-key.js

@@ -6,6 +6,7 @@ import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { createCenterCredentialSource } from "./center-credential.js";
 import { centerFetch } from "./web-admin-client/center-request.js";
 import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
+import { CHECKPOINT_CTX_SEAL_ALG } from "./http/checkpoint-ctx.js";
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
 const SEAL_OVERHEAD_BYTES = 48;
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
@@ -70,7 +71,7 @@ export async function ensureSealedKeyStore(dir, logger) {
         await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
         await chmod(path, 0o600);
         keys.set(record.publicKeyId, { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt });
-        logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair — register the PUBLIC key with the registry (see sealed_key_public_key)" });
+        logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair in this directory — the private key exists only here: keep the directory across restarts and identical on every replica that has to open what it sealed, and back it up as a private key" });
     }
     const latestEntry = [...keys.entries()].sort((a, b) => (a[1].createdAt < b[1].createdAt ? 1 : a[1].createdAt > b[1].createdAt ? -1 : a[0] < b[0] ? -1 : 1))[0];
     return {
@@ -88,6 +89,59 @@ export async function ensureSealedKeyStore(dir, logger) {
         },
     };
 }
+const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+function mintCheckpointCtxKeyStore(store) {
+    return store;
+}
+export async function ensureCheckpointCtxSealing(sealedKeyDir, logger) {
+    return createCheckpointCtxSealing(mintCheckpointCtxKeyStore(await ensureSealedKeyStore(join(sealedKeyDir, CHECKPOINT_CTX_KEY_SUBDIR), logger)));
+}
+export function createCheckpointCtxSealing(store) {
+    const sodium = _sodium;
+    if (typeof sodium.crypto_box_seal !== "function")
+        throw new Error("createCheckpointCtxSealing: libsodium is not initialized — build the store with ensureSealedKeyStore() first");
+    const { publicKeyId } = store.latest;
+    const publicKey = b64ToBytes(store.latest.publicKey, "publicKey");
+    const sealing = createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey);
+    const probeSession = "sealed-key-self-test";
+    let roundTrip;
+    try {
+        roundTrip = sealing.open(sealing.seal(probeSession, probeSession), probeSession);
+    }
+    catch {
+        roundTrip = undefined;
+    }
+    if (roundTrip !== probeSession) {
+        throw new Error(`createCheckpointCtxSealing: self-test failed — a value sealed against the newest public key (publicKeyId "${publicKeyId}") does not open with the private key held under that id; the key file's public and private halves do not belong together. Refusing to hand out a sealer whose seals nobody can open`);
+    }
+    return sealing;
+}
+function createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey) {
+    const sodium = _sodium;
+    return {
+        seal: (value, sessionId) => ({
+            alg: CHECKPOINT_CTX_SEAL_ALG,
+            publicKeyId,
+            sealed: Buffer.from(sodium.crypto_box_seal(sodium.from_string(JSON.stringify([CHECKPOINT_CTX_SEAL_ALG, sessionId, value])), publicKey)).toString("base64"),
+        }),
+        holds: (id) => store.has(id),
+        open: (sealed, sessionId) => {
+            const plaintext = store.open(sealed.sealed, sealed.publicKeyId);
+            let envelope;
+            try {
+                envelope = JSON.parse(plaintext);
+            }
+            catch {
+                throw new Error("sealed value is not a checkpoint-context seal");
+            }
+            if (!Array.isArray(envelope) || envelope.length !== 3 || envelope[0] !== CHECKPOINT_CTX_SEAL_ALG)
+                throw new Error("sealed value is not a checkpoint-context seal");
+            if (envelope[1] !== sessionId)
+                throw new Error("sealed value was sealed for a different session's resume context");
+            return envelope[2];
+        },
+    };
+}
 export async function reportExecutionPublicKey(opts) {
     const { baseUrl, adminToken, key, notes, logger } = opts;
     const manual = (why) => {

package/dist/security.d.ts

@@ -42,7 +42,7 @@ export interface SessionListItem {
  * 而 `DELETE /v1/sessions/:id`(删整条会话)不在其中 —— 同一风险形、爆炸半径**更大**,却没门。
  *
  * 风险形逐字同源(守卫自己的注释):「无 service token + 未开 `ALLOW_UNAUTHED_WRITES`」这一形下
- * `sessionOwnerScopeForWrite` 判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
+ * fleet 写档(`http/principal-gate.ts` 的 `fleetViewOf`,dev-open 臂)判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
  * policy 腿担心的是「forged principal 能 tighten/DoS 一个会话的工具」;DELETE 直接把会话删掉。
  *
  * ⇒ 枚举改**族判定**:新增一条破坏性会话路由时自动落进门内,不必记得回来加白名单。
@@ -89,7 +89,7 @@ export interface SessionCaller {
     readonly fleet: boolean;
 }
 /**
- * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**(S-1770 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除的存量互认臂 {@link legacyUnownedSessionOk}、
+ * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**(S-1770 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除 / 同步族的存量互认臂 {@link legacyUnownedSessionOk}、
  * 审批豁免面、notify 面的无主臂都经它,不各写一份):
  *  · 无主的**普通**会话行 ⇒ 成立(各臂照它自己的其余条件);
  *  · 无主的 **placed** 行(委派子代:属主 = 委派树根的属主,`delegated-session-owner.ts`)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
@@ -122,7 +122,12 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  * 🪦 墓碑注(与第一臂同源):这是两个表示法之间的**过渡承接**。存量随会话生命周期消亡后,本臂
  * 连同 {@link LEGACY_UNOWNED_AMNESTY_TENANT} 与几处调用点可**整删**,不留兼容层。
  *
- * ── 逐面判过、**刻意不放行**的三处(免得后人当遗漏再补一次)────────────────────────────────
+ * ── 同步族(`…/sync/*`:拉取 / 推送 / 开导入 / 导入第二阶段)──────────────────────────────────
+ *  同步族四口自 7.134.0 同走本臂(表态见 7.134.0 发车帖;三条件不变):属主门是 `http/routes/session-sync.ts` 的一只布尔 `mayTouch`,与 fork / 删除同一只谓词、同一对读法
+ *  (`sessionCallerOf` + `sessionOwnerCellOf`),不另立判据。这一族带破坏性的 import 腿,但单用户形下 `default` 是唯一用户,与已走本臂的删除同级,没有新增跨租风险;
+ *  多租形、非 `default` 主体、无主的 placed 行仍与不存在的会话同码同体。暂存句柄的归属不因本臂放宽(非 fleet 调用方只推自己开的暂存,fleet 调用方照旧可推任何一张)。
+ *
+ * ── 逐面判过、**刻意不放行**的两处(免得后人当遗漏再补一次)────────────────────────────────
  *  · `runOwnerOk` 三读面(head / audit 单读 / events):`owner === null` 那一支**本来就放行**
  *    (判据是 `owner !== null && principal !== owner`),不需要本臂。[ref] 帖文里「单读 404」一句
  *    经亲读实现行**不成立**,已加现状钉(session-head-probe.test.ts)锁住这个事实。
@@ -131,9 +136,6 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  *    这把键,替它读写规则只能**猜**一个 principal(猜错 = 200 说已生效,其实没有哪条 run 读它)。已经存下的规则不受影响:
  *    它们存在当初那个属主的键下,那个 principal 的 run 照读照生效(7.119.0 前 local 后端重启即把属主忘掉,于是那些规则
  *    在跑、却读不到也删不掉 —— 修在属主落盘,不在放宽本门)。放宽它等于制造一条 fail-open,不在本臂辖域。
- *  · `…/sync/*`(PULL/PUSH/import):PULL 虽是只读、形同 workspace,但这一族**带一条破坏性 import 腿**
- *    (`isDestructiveSessionWrite` 明列),而 [ref]/[ref] 裁的是会话**读面与生命周期**四门。放宽一个
- *    写面族超出裁定射程 —— 要做另立一次表态,不在本臂里顺手带过。
  *
  * @param requirePrincipal `config.requirePrincipal`(条件①)
  * @param caller 调用方(条件③ 读它验过的主体;fleet-wide 面不经本臂)
@@ -146,7 +148,7 @@ export declare function legacyUnownedSessionOk(requirePrincipal: boolean, caller
  * 🔴 单独存在的唯一理由是**列表面**:`GET /v1/sessions` 的第三条件(`owner === null`)不在 JS 里判,
  * 它是 store 侧 `owner = ? OR owner IS NULL` 这一句 SQL 谓词 —— 三条件仍然齐,只是第三条件由 SQL 承载
  * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
- * 单实体读/写点(fork/delete/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
+ * 单实体读/写点(fork/delete/同步族/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
  */
 export declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
 export type OwnerAwareSessionStore = SessionStore & {

package/dist/session-error-wire.d.ts

@@ -39,8 +39,11 @@
  *    (请求 core 把种类放进错误,而不是在这里解析句子)。
  *  · `invalid_entry` / `invalid_fork_target` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
  *    应答(它们在 core 的追加 / 分叉面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
- *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局
- *    (`terminal.code: "conflict"`),提交腿不另作处置;`storage` / `unknown` 是故障类,通用 500 就是它们今天的应答。
+ *  · `conflict` —— `import` 面 **409 `conflict`**(固定句 {@link STAGED_IMPORT_OWNER_CHANGED_SENTENCE});`open` 面留白。import 面上这个词只有一个来源:
+ *    暂存提交的属主 CAS(`session-sync-kernel.ts` 的 `StagedCommitOwnerChangedError`,三家店在提交事务里比「此刻的属主格 = 这次导入的门判过的那一格」,
+ *    不等 ⇒ 回滚)—— 码位与同族的提交期同步冲突(`SyncConflictError` ⇒ 409 `conflict`「sync conflict」)同一个,出路也相同:从第一阶段重来(重新过门)。
+ *    open 面上它是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局(`terminal.code: "conflict"`),提交腿不另作处置。
+ *  · `storage` / `unknown` —— 留白:故障类,通用 500 就是它们今天的应答。
  *
  * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
  * ([ref] 词表纪律;同形先例 `session-policy-wire.ts` 的 `sessionPolicyErrorHttp`)。
@@ -55,9 +58,8 @@ export interface SessionErrorWire {
     readonly status: number;
     readonly errorCode: string;
     /**
-     * 固定句(缺席 = 发 core 的原句,过既有脱敏)。只有 import 面的 `invalid_session` 用它:core 导入门的原句点名的是
-     * 调用方日志里的条目 id / 父子关系,修前这一口就只回一句固定话(冻结在 `test/api-error-text-freeze.test.ts` 的
-     * 常量锚格),本批逐字不改。
+     * 固定句(缺席 = 发 core 的原句,过既有脱敏)。import 面的三行用它(`invalid_session` / `placement_refused` / `conflict`):店与引擎的原句
+     * 点名条目 id / 会话 id / 引擎内部词,wire 上只回一句固定话(各自冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
      */
     readonly sentence?: string;
     /** 机读事实(体顶层的 `detail` 键;缺席 = 体里不带这个键)。只有 import 面的 `placement_refused` 用它:`{ placement_kind }`。 */
@@ -70,6 +72,11 @@ export declare const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed
  * (「placement partition」「delegation transcript」);固定句只说调用方能做什么(冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
  */
 export declare const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's transcript, so session sync cannot overwrite it; sync into a different session id";
+/**
+ * import 面 `conflict` 的固定句:暂存提交时会话的属主格已不是开暂存时门判过的那一格(另一副本在导入流式进行期间删建 / 认领 / 新建了它),提交事务回滚。
+ * 不发店的原句(它点名会话 id);固定句只说发生了什么与出路(冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
+ */
+export declare const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported \u2014 start the sync again";
 export declare function sessionErrorHttp(code: SessionErrorCode, face: SessionErrorFace): SessionErrorWire | undefined;
 export declare function isSessionErrorCode(code: string): code is SessionErrorCode;
 //# sourceMappingURL=session-error-wire.d.ts.map

package/dist/session-error-wire.js

@@ -1,9 +1,11 @@
 export const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
 export const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's transcript, so session sync cannot overwrite it; sync into a different session id";
 const PLACEMENT_KIND = "subagent";
+export const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported — start the sync again";
 const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
 const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
 const SESSION_PLACED = { status: 409, errorCode: "conflict.session_placed", sentence: PLACED_SESSION_SENTENCE, detail: { placement_kind: PLACEMENT_KIND } };
+const STAGED_IMPORT_OWNER_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OWNER_CHANGED_SENTENCE };
 export function sessionErrorHttp(code, face) {
     switch (code) {
         case "corrupt_session":
@@ -12,11 +14,12 @@ export function sessionErrorHttp(code, face) {
             return face === "import" ? INVALID_ENTRIES : undefined;
         case "placement_refused":
             return face === "import" ? SESSION_PLACED : undefined;
+        case "conflict":
+            return face === "import" ? STAGED_IMPORT_OWNER_CHANGED : undefined;
         case "not_found":
         case "invalid_entry":
         case "invalid_fork_target":
         case "storage":
-        case "conflict":
         case "unknown":
             return undefined;
         default: {