@sema-agent/server 7.138.0 → 7.139.0

package/dist/http/routes/tasks.js

@@ -24,7 +24,8 @@ import { collectSsePreamble } from "../sse-log.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
 import { approvalPreambleReplays, createApprovalCardEmitter, declaredApprovalFrameFamilies, resolveApprovalLeg, resolveStreamApprovalGate } from "../../tool-approval.js";
 import { buildActiveRunConflict, isActiveRunConflictBody, toDoneFrameResult } from "../active-run-conflict.js";
-import { commitPlacement, devicePlacementErrorBody } from "../device-placement.js";
+import { commitExecutionContext } from "../execution-context.js";
+import { rootSessionAbsentAnswer } from "../execution-context.js";
 import { commitSessionInheritEnv } from "../session-inherit-env.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk, runIdentityOf } from "../principal-gate.js";
 import { failOpenTagForDroppedFrame, recordFailOpen } from "../../observability/fail-open.js";
@@ -177,7 +178,7 @@ export async function handleTasks(req, res, match, ctx) {
                     sendError(res, 400, "request.field_conflict", "verify / cascade are not supported on /v1/tasks/stream (both are multi-attempt, not a single stream) — use /v1/tasks or /v1/runs", fieldConflictFacts("cascade_verify", prepared.verify ? (prepared.cascade ? ["verify", "cascade"] : ["verify"]) : ["cascade"]));
                     return;
                 }
-                const earlyDurableTid = facts.durableRuns(deps).available && prepared.spec.sessionId ? uuidv7() : undefined;
+                const earlyDurableTid = facts.durableRuns(deps).available ? uuidv7() : undefined;
                 const streamLegStartedAt = Date.now();
                 const detachOnDisconnect = headerStr(req.headers["x-detach-on-disconnect"]) === "true";
                 if (detachOnDisconnect && earlyDurableTid === undefined) {
@@ -289,19 +290,19 @@ export async function handleTasks(req, res, match, ctx) {
                     let runRowSettled = false;
                     let durableTaskId;
                     let durableHeartbeat;
-                    const cancelledResult = (errorMessage, cause) => mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId ?? "", startedAtMs: streamLegStartedAt, message: errorMessage, cause });
+                    const cancelledResult = (errorMessage, cause) => mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId, startedAtMs: streamLegStartedAt, message: errorMessage, cause });
                     let userMsgEntryId;
                     const promptCommit = createPromptCommitReader();
                     let anchorPut = false;
                     const putRewindAnchor = () => {
-                        if (anchorPut || !userMsgEntryId || !durableTaskId || !prepared.spec.sessionId || !deps.resumeAnchorStore)
+                        if (anchorPut || !userMsgEntryId || !durableTaskId || !deps.resumeAnchorStore)
                             return;
                         anchorPut = true;
                         void deps.resumeAnchorStore
                             .put(prepared.spec.sessionId, durableTaskId, userMsgEntryId, principal ?? null)
                             .catch(() => deps.metrics?.inc("resume_anchor_capture_failed"));
                     };
-                    if (deps.runStore && prepared.spec.sessionId) {
+                    if (deps.runStore) {
                         const tid = earlyDurableTid ?? uuidv7();
                         const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), identity: runIdentityOf(req, deps.config, principal ?? null), idem: idem ?? null });
                         if (created.ok)
@@ -313,22 +314,25 @@ export async function handleTasks(req, res, match, ctx) {
                             sseData(res, { type: "done", result: doneResultOfOutcome(replay), replay: true });
                             return replay;
                         }
+                        if (created.sessionAbsent) {
+                            const refused = rootSessionAbsentAnswer();
+                            sseData(res, { type: "done", result: doneResultOfOutcome(refused) });
+                            return refused;
+                        }
                         if (!created.ok) {
                             const conflict = await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId);
                             const refused = { status: 409, body: conflict };
                             sseData(res, { type: "done", result: doneResultOfOutcome(refused) });
                             return refused;
                         }
-                        const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
+                        const placementReject = await commitExecutionContext(deps, { kind: "run", runStore: deps.runStore, taskId: tid }, prepared.execution);
                         if (placementReject) {
-                            const body = devicePlacementErrorBody(placementReject);
-                            const refused = { status: placementReject.status, body };
-                            sseData(res, { type: "done", result: doneResultOfOutcome(refused) });
-                            return refused;
+                            sseData(res, { type: "done", result: doneResultOfOutcome(placementReject) });
+                            return placementReject;
                         }
                         durableTaskId = tid;
                     }
-                    if (deps.checkpointStore && prepared.spec.sessionId) {
+                    if (deps.checkpointStore) {
                         const ctxRefusal = await persistSubmitCtx(deps.checkpointStore, deps, durableTaskId !== undefined && deps.runStore ? { runStore: deps.runStore, taskId: durableTaskId } : undefined, prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope, writerVersion: serviceVersion() });
                         if (ctxRefusal) {
                             sseData(res, { type: "done", result: doneResultOfOutcome(ctxRefusal) });
@@ -336,8 +340,7 @@ export async function handleTasks(req, res, match, ctx) {
                         }
                     }
                     commitSessionInheritEnv(deps, prepared.spec.sessionId, prepared.body);
-                    if (prepared.spec.sessionId)
-                        markChildrenStoppedByUserOnAbort(ac.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
+                    markChildrenStoppedByUserOnAbort(ac.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
                     let ledgerSink;
                     let ledgerTerminal = false;
                     if (durableTaskId && deps.runStore) {
@@ -412,7 +415,7 @@ export async function handleTasks(req, res, match, ctx) {
                             }
                             : {}),
                     });
-                    if (deps.userInputLedger && durableTaskId && prepared.spec.sessionId)
+                    if (deps.userInputLedger && durableTaskId)
                         await deps.userInputLedger.announceUndrained({ sessionId: prepared.spec.sessionId, taskId: durableTaskId });
                     try {
                         const streamBody = async () => {
@@ -420,7 +423,7 @@ export async function handleTasks(req, res, match, ctx) {
                                 const tailContentMode = prepared.spec.forwardSubagentEvents === true ? "on" : "progress_only";
                                 const childReasoning = createReasoningSegments();
                                 const topReasoning = createReasoningSegments();
-                                const heldDecisions = prepared.spec.sessionId !== undefined ? await heldWorkflowParkDecisions(deps, prepared.spec.sessionId) : {};
+                                const heldDecisions = await heldWorkflowParkDecisions(deps, prepared.spec.sessionId);
                                 const fwdInternals = {
                                     ...heldDecisions,
                                     onForwardEvent: (e) => {
@@ -476,7 +479,7 @@ export async function handleTasks(req, res, match, ctx) {
                                         }
                                         const hadRow = isFleetAgentTerminalNotification(n) ? (fleetPub?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false) : false;
                                         const deliverable = syncLegLive && !res.writableEnded && !res.destroyed;
-                                        const parked = !deliverable && Boolean(deps.workflowCompletionInbox && prepared.spec.sessionId);
+                                        const parked = !deliverable && deps.workflowCompletionInbox !== undefined;
                                         deps.logger?.info?.("task_notification_observed", { route: "sync-stream", taskId: n.task_id, taskType: n.task_type, status: n.status, hadFleetRow: hadRow, legLive: syncLegLive, parkedDurable: parked });
                                         if (parked) {
                                             void deps.workflowCompletionInbox.enqueue(taskNotificationInboxEntry(prepared.spec.sessionId, askOwner, n, Date.now(), durableTaskId, opts?.priority)).catch((err) => deps.logger?.warn?.("park_enqueue_failed", { route: "sync-stream", taskId: n.task_id, err: err instanceof Error ? err.message : String(err) }));
@@ -521,7 +524,7 @@ export async function handleTasks(req, res, match, ctx) {
                                         if (durableTaskId && finalResult)
                                             finalResult = { ...finalResult, taskId: durableTaskId };
                                         if (causeAtDone !== undefined && finalResult !== undefined) {
-                                            finalResult = mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId ?? "", startedAtMs: streamLegStartedAt, message: "cancelled by user", cause: causeAtDone, engineResult: finalResult });
+                                            finalResult = mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId, startedAtMs: streamLegStartedAt, message: "cancelled by user", cause: causeAtDone, engineResult: finalResult });
                                         }
                                         finalizeTaskResult(ev.result, principal, prepared.spec.objective);
                                         noteRunOutcome(finalResult);
@@ -714,7 +717,8 @@ export async function handleTasks(req, res, match, ctx) {
                                 taskId: askTaskId,
                                 owner: askOwner,
                                 abortSignal: ac.signal,
-                                ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}),
+                                sessionId: prepared.spec.sessionId,
+                                executionLane: prepared.execution.lane,
                                 ...(streamApprovalOn
                                     ? {
                                         emitCard,
@@ -728,11 +732,12 @@ export async function handleTasks(req, res, match, ctx) {
                         if (deps.toolApproval) {
                             const toolApproval = deps.toolApproval;
                             prepared.spec.onAsk = unattended
-                                ? toolApproval.boundUnattendedAsk({ owner: askOwner, taskId: askTaskId, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) }, unattended)
+                                ? toolApproval.boundUnattendedAsk({ owner: askOwner, taskId: askTaskId, sessionId: prepared.spec.sessionId, executionLane: prepared.execution.lane }, unattended)
                                 : toolApproval.boundAsk({
                                     owner: askOwner,
                                     taskId: askTaskId,
-                                    ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}),
+                                    sessionId: prepared.spec.sessionId,
+                                    executionLane: prepared.execution.lane,
                                     ...(streamApprovalOn ? { legKey: "", ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}) } : {}),
                                 });
                         }
@@ -815,7 +820,7 @@ export async function handleTasks(req, res, match, ctx) {
                             try {
                                 const row = await deps.runStore.getRun(durableTaskId);
                                 if (row?.status === "running") {
-                                    const pending = prepared.spec.sessionId ? await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId) : undefined;
+                                    const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId);
                                     const backstopCause = ac.cause();
                                     if (pending) {
                                         if (ledgerSink && !ledgerTerminal) {
@@ -896,7 +901,7 @@ export async function handleTasks(req, res, match, ctx) {
                     const syncLegStartedAt = Date.now();
                     let durableTaskId;
                     let durableHeartbeat;
-                    if (deps.runStore && prepared.spec.sessionId) {
+                    if (deps.runStore) {
                         const tid = uuidv7();
                         const created = await deps.runStore.createRun(tid, prepared.spec.sessionId, principal ?? null, deps.instanceId ?? "default", { ...runMeta(prepared, source), identity: runIdentityOf(req, deps.config, principal ?? null), idem: idem ?? null });
                         if (created.ok)
@@ -905,22 +910,23 @@ export async function handleTasks(req, res, match, ctx) {
                             recordResourceWindow(tid, prepared.spec.resourceSuspend);
                         if (created.existing)
                             return await replayOfExistingRun(created.existing, { principal: submitter, idem }, "sync", deps, deps.runStore);
+                        if (created.sessionAbsent)
+                            return rootSessionAbsentAnswer();
                         if (!created.ok)
                             return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId) };
-                        const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
+                        const placementReject = await commitExecutionContext(deps, { kind: "run", runStore: deps.runStore, taskId: tid }, prepared.execution);
                         if (placementReject)
-                            return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
+                            return placementReject;
                         durableTaskId = tid;
                     }
-                    if (deps.checkpointStore && prepared.spec.sessionId) {
+                    if (deps.checkpointStore) {
                         const ctxRefusal = await persistSubmitCtx(deps.checkpointStore, deps, durableTaskId !== undefined && deps.runStore ? { runStore: deps.runStore, taskId: durableTaskId } : undefined, prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope, writerVersion: serviceVersion() });
                         if (ctxRefusal)
                             return ctxRefusal;
                     }
                     commitSessionInheritEnv(deps, prepared.spec.sessionId, prepared.body);
                     const syncCancelCtrl = createRunAbort();
-                    if (prepared.spec.sessionId)
-                        markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
+                    markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
                     if (durableTaskId && deps.runStore) {
                         const rs = deps.runStore;
                         const tid = durableTaskId;
@@ -950,7 +956,7 @@ export async function handleTasks(req, res, match, ctx) {
                     let result;
                     counters.uncountedBillableInflight++;
                     try {
-                        const heldDecisions = prepared.spec.sessionId !== undefined ? await heldWorkflowParkDecisions(deps, prepared.spec.sessionId) : {};
+                        const heldDecisions = await heldWorkflowParkDecisions(deps, prepared.spec.sessionId);
                         const verifyLeg = (v) => runWithVerification(prepared.runner, specWithSignal, v, heldDecisions);
                         const cascadeLeg = () => runCascade(prepared.runner, specWithSignal, cascadeConfig(deps.config.cascadeLadder, prepared.spec.limits?.maxCostUsd), heldDecisions);
                         const plainLeg = async () => {
@@ -976,7 +982,7 @@ export async function handleTasks(req, res, match, ctx) {
                     if (syncAbortCause !== undefined) {
                         result = mintCancelledResult({
                             taskId: durableTaskId ?? "",
-                            sessionId: prepared.spec.sessionId ?? "",
+                            sessionId: prepared.spec.sessionId,
                             startedAtMs: syncLegStartedAt,
                             message: "cancelled by user",
                             cause: syncAbortCause,
@@ -998,11 +1004,11 @@ export async function handleTasks(req, res, match, ctx) {
                     }
                     const exitResult = await mintSubmitExitResult(result, deps.checkpointStore);
                     const syncPlane = outwardPlane(result.terminal);
-                    if (syncPlane.status === "suspended" && deps.checkpointStore && deps.runStore && durableTaskId && prepared.spec.sessionId) {
+                    if (syncPlane.status === "suspended" && deps.checkpointStore && deps.runStore && durableTaskId) {
                         await deps.runStore.setSuspended(durableTaskId, exitResult);
                         return { status: 200, body: withSyncSubmitKeys(buildSyncSubmitBody(exitResult, { taskId: durableTaskId, sessionId: prepared.spec.sessionId, status: "suspended" })) };
                     }
-                    if (syncPlane.status === "needs_review" && deps.checkpointStore && deps.runStore && durableTaskId && prepared.spec.sessionId) {
+                    if (syncPlane.status === "needs_review" && deps.checkpointStore && deps.runStore && durableTaskId) {
                         await deps.runStore.setNeedsReview(durableTaskId, exitResult);
                         return { status: 200, body: withSyncSubmitKeys(buildSyncSubmitBody(exitResult, { taskId: durableTaskId, sessionId: prepared.spec.sessionId, status: "needs_review" })) };
                     }

package/dist/http/server.d.ts

@@ -9,6 +9,7 @@ import { type SessionMirrorRuling } from "../web-admin-client/facade.js";
 import type { RestartSignal } from "@sema-agent/settings-schema/fleet";
 import { type OwnerAwareSessionStore } from "../security.js";
 import type { PeerDesk, PeerLease } from "../peer-seat.js";
+import type { ExecutionRoot, ResolvedTaskSpec } from "./execution-context.js";
 import type { RunStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ApprovalNonceStore, ServiceSessionPolicyStore, ServiceFileHistoryStore, ToolResultStoreFull, StoreBackend } from "../plugins/store-backend.js";
 import type { RuleConsentLane } from "../rules-consent.js";
 import { type MemorySyncRequest, type MemorySyncResponse } from "../memory-sync.js";
@@ -52,6 +53,8 @@ export interface RequestAuth {
      *  defaultScopes(memory.scopes 种子)。resume 腿(checkpoint 重建 auth)缺席 — 回落持久化的
      *  body.projectId(原始提交已验形),那条回落腿自己再折一次小写,两腿查同一个键。 */
     resolvedProjectId?: string;
+    /** authorizer 判过的头(`security.ts` `createAuthorizer` 交出;语义见 `AuthContext.head`)⇒ fresh 执行上下文的 `judged`。自建 authorizer 不给 = 解析器不比住客。 */
+    head?: import("@sema-agent/core").SessionHead;
 }
 /**
  * [ref] A8 —— ServiceDeps 的**分组窄接口**。
@@ -60,7 +63,7 @@ export interface RequestAuth {
  * 平铺形的直接后果 = main.ts 一个上千行的装配字面量,键与键之间没有任何「属于同一件事」的编译期表达,
  * 键落错家/从未接线只能靠源码钉逐个盯(1.300/1.301/1.304/1.307/1.310 五起真缺陷都是这个病族)。
  *
- * 药:七个**窄**接口 + 顶层必填七件。装配点按组构造(每组一个带类型标注的中间 const ⇒ 受 TS 多余
+ * 药:七个**窄**接口 + 顶层必填八件。装配点按组构造(每组一个带类型标注的中间 const ⇒ 受 TS 多余
  * 属性检查保护),键放错组当场编译红。
  *
  * 兼容形(本批**不动消费点**):`ServiceDeps` = 平铺视图 ∩ 组槽。旧的平铺构造(96 个测试文件 +
@@ -68,8 +71,8 @@ export interface RequestAuth {
  * 入口摊平回平铺视图,server.ts 内的 ~700 处 `deps.x` 消费点原样保留。消费点迁移是后批的事——
  * 一步到位需要同批改 ~700 处 src + ~800 处 test 键位,与「先立形、后搬家」相比没有额外收益。
  */
-/** createHttpServer 的**必填七件**——引擎、部署配置、请求→TaskSpec 的映射、选路席、side-query 执行席、读口场景门、对端座的 desk。
- *  七者恒在场,故留在顶层(不进任何可选组):没有它们 server 根本起不来,包一层可选组只会把编译期
+/** createHttpServer 的**必填八件**——引擎、部署配置、提交的身份与根会话(authorizer)、请求→TaskSpec 的映射、选路席、side-query 执行席、读口场景门、对端座的 desk。
+ *  八者恒在场,故留在顶层(不进任何可选组):没有它们 server 根本起不来,包一层可选组只会把编译期
  *  错误推迟到运行期(本仓 E-HIGH-1 病族的成因就是「可选键从未接线、编译期无声」)。 */
 export interface ServiceCoreDeps {
     runner: Runner;
@@ -83,9 +86,22 @@ export interface ServiceCoreDeps {
     sideQuery: (spec: SideQuerySpec) => Promise<SideQueryResult>;
     config: ServiceConfig;
     /**
-     * Map an inbound request body + resolved auth to a full TaskSpec. The SERVICE/deployment owns model
-     * + tools + mcp here (callers only supply content). `auth` carries the ownership-checked sessionId
-     * and the principal-derived memory scope — prefer them over anything in the body.
+     * Resolve identity + the owned root session BEFORE the spec is built (S6). Throw `HttpError` to reject.
+     * 🔴 **必填**:它是一次提交的根会话**唯一**的来源与铸点(体里的 `sessionId` 只由它消费:有属主读的店判属主,单用户嵌入原样采用,
+     * 不带 ⇒ 现铸并登记)。省掉是编译错;绕过类型造的 deps 在 {@link createHttpServer} 入口拒启。单用户嵌入传
+     * `createAuthorizer(config, runner.sessions)`(包根导出)—— 店没有属主读时它退化为只派 principal 与会话 id。
+     */
+    authorize: (ctx: {
+        req: IncomingMessage;
+        body: TaskRequestBody;
+    }) => Promise<RequestAuth>;
+    /**
+     * Map an inbound request body + resolved auth to a TaskSpec. The SERVICE/deployment owns model
+     * + tools + mcp here (callers only supply content). `auth` carries the principal-derived memory scope —
+     * prefer it over anything in the body.
+     * The root session is NOT the resolver's to write: the return type carries no `sessionId`
+     * (`ResolvedTaskSpec`); the server stamps the root the authorizer resolved onto every spec it executes
+     * (`http/execution-context.ts` `stampSpecRoot`). A resolver that needs the root reads `opts.execution.root`.
      */
     /** `opts.leg` (codex R4, appendSystemPrompt 案): "fresh" ⇒ a NEW submit — resolveSpec may fail-loud 400 on
      *  combos that would silently discard caller payload (append rider / outputStyle on an append-less pack).
@@ -108,6 +124,8 @@ export interface ServiceCoreDeps {
      *  `opts.unattendedLeg`([ref] 候裁 18,codex r3 F1;[ref] ① 改形):续跑家族在 ctx 带无人值守标(`CheckpointCtx.unattendedLeg`)时递 `true` ——
      *  装配器在**全部折叠之后**经首跑同一只合并口 `withUnattendedLeg` 重挂那条腿(`default` + 按类作答的 onAsk)。只由续跑腿
      *  按服务端写的 ctx 位递,绝不从请求体读。 */
+    /** `opts.execution`(必填):这条腿的执行上下文(`http/execution-context.ts`;只 `fresh` / `continuation` 两形,`root` 恒在)。装配器要用这条腿的根会话
+     *  (场景设施的分区键、受理见证)读 `opts.execution.root` —— 它与 server 随后盖进 spec 的根是同一个值,装配器自己不写根。 */
     /** `opts.lease`(必填):这条腿的**宿主租约** —— 装配在它之下登记本腿交给引擎的对端声明(`peerDesk.declare(草稿, opts.lease)`)。
      *  租约由两只漏斗(受理 `prepareSpec` / 续跑 `resolveResumeSpecOrBlocked`)在调用本函数**之前**开、由漏斗的失败出口或拿到产物的那段作用域放;
      *  装配只借用,不放、不留。实现方自铸的声明归自己的 desk 时可以不理它。 */
@@ -117,7 +135,8 @@ export interface ServiceCoreDeps {
         onNotice?: (notice: EngineNotice) => void;
         unattendedLeg?: true;
         lease: PeerLease;
-    }) => TaskSpec | Promise<TaskSpec>;
+        execution: ExecutionRoot;
+    }) => ResolvedTaskSpec | Promise<ResolvedTaskSpec>;
     /**
      * [ref] 场景 hands lane 选路:按 `resolveSpec` 刚产出的 TaskSpec 取本任务的执行 Runner。
      * 装配点(`boot/stage-10-http-server.ts`)传的是 `createHandsRunnerSelector` —— 选路规则只有那一份实现,
@@ -146,7 +165,7 @@ export interface ServiceCoreDeps {
      * 本层用它开**宿主租约**:受理与续跑两只漏斗在装配之前各开一只(`lease("fresh")` / `lease("resume")`),经 `resolveSpec` 的 `opts.lease` 交给装配,
      * 随产物(`PreparedTaskSubmission.peerLease` / 续跑结果)交给拿到它的那段作用域,在那段作用域的 `finally` 放;活过那段作用域的驱动经 `heldFor` 自持一只。
      * 这只 desk 另有三处用法,不止这两只漏斗:① 探测口 `POST /v1/capabilities/mcp/probe` 的调用方臂在走查里开一只 `probe` 租约(三道前置拒之后开,拨号落地才放);
-     * ② 两张会话面板(`GET /v1/sessions/:id/mcp` · `…/a2a`)与探测走查拨名册声明时递它的座(`desk.seat.answer`),不开租约;③ 名册声明在起服时登记在一只进程寿命的 `roster` 租约下
+     * ② 两张会话面板(`GET /v1/sessions/:id/mcp` · `…/a2a`)与探测走查拨名册声明时递它的座(`desk.seat`),不开租约;③ 名册声明在起服时登记在一只进程寿命的 `roster` 租约下
      * (stage-07 / run-local 开,从不放),并且每只 Runner 的 `peerSeat` 是它的座。登记表的两个读数是 `/metrics` 的 `peer_registry_entries` / `peer_registry_holders`。
      * 🔴 **必填**:没有 MCP / A2A 凭据的嵌入也给一只 `createPeerDesk()`(零 IO)—— 一个部署只有一张登记表,缺席不是「没有座」的另一种读法。
      */
@@ -371,7 +390,7 @@ export interface ServiceSeamDeps {
     deviceStore?: import("../device-store.js").DeviceStore;
     /**
      * [ref](车C 余件):device lane 的**准入链**(`createDeviceEnrollment`)—— 管理面三个写动词
-     * (签发 / 注册 / 吊销)与首绑写协议(`commitPlacement`)的**唯一**判据属主。
+     * (签发 / 注册 / 吊销)与首绑写协议(`commitExecutionContext` 的设备那一支)的**唯一**判据属主。
      *
      * 🔴 为什么路由拿的是它而不是 {@link deviceStore}:enrollment 那一层持着两件路由造不出来的东西 ——
      * ①跨副本限速座(`DeviceEnrollRateLimiter`,§7-T5 ⑤:端点车**必须**传一个,而它由 boot 从既有
@@ -598,6 +617,9 @@ export interface ServiceSeamDeps {
      *  per-principal 查询走 caps client 的 executionRuling 同车(零额外 RTT);absent = 无 center(单用户/
      *  dry-run)⇒ 观测面不接线,零行为差。fail-open:观测失败绝不影响 sync 面本身。 */
     sessionMirrorRuling?: (principal: string | undefined) => Promise<SessionMirrorRuling | undefined>;
+    /** 主体的执行车道裁定(caps client 的 `executionRuling`,与场景裁定同车零额外 RTT)—— 执行上下文解析器步 ③ 的唯一输入(`http/execution-context.ts`,
+     *  判据 `runtime-caps-resolver.ts` `gateExecutionLane`)。缺席 = 无中心(单用户 / dry-run / 嵌入方)⇒ 不判,与已发同。 */
+    executionRuling?: (principal: string | undefined) => Promise<import("../web-admin-client/facade.js").ExecutionRuling | undefined>;
     /** Degenerate-output a/b instrument: on errorCode=output.degenerate, inspect the session's turns to
      *  classify where the salvageable answer was (counter + log). Fire-and-forget; no-op otherwise. */
     instrumentDegenerate?: (result: TaskResult) => void;
@@ -606,7 +628,9 @@ export interface ServiceSeamDeps {
      *  (手搭测试 deps;生产 main.ts 恒传)。 */
     sideQueryAccounting?: SideQueryAccounting;
     /** [ref](core 7.32.0):parked 赎回面工厂(按行解析驱动哪只 Agent 工具 + 同出一张列表的继承座;属主 `parked-revive-surface.ts`)。
-     *  缺席 = 这台部署没有 park 底座(checkpointStore / backgroundAgentStore 任一缺席),bg 赎回臂不接线。 */
+     *  缺席 = 这台部署没有 park 底座(checkpointStore / backgroundAgentStore 任一缺席),bg 赎回臂不接线。
+     *  🔴 **在场 ⇒ `sessionStorage` 必须带执行席 `executionPlacement`**:认领之后对根会话住客的唯一判官是执行席上的写口;缺 ⇒ `createHttpServer` 拒启
+     *  (句子 = `PARKED_REVIVE_EXECUTION_SEAT_REQUIRED`)。 */
     parkedReviveSurface?: import("../parked-revive-surface.js").ParkedReviveSurfaceFactory;
     /** 可选第三件:revive args 的 `subagent_type` roster 成员集([ref] Q1 成员性规则)。当前生产装配
      *  **恒缺席**(boot 内建 default 无自定义 agents roster,per-request 的 spec.agents 不进 boot 工具)
@@ -641,14 +665,6 @@ export interface ServiceObservabilityDeps {
 /** **准入/治理面**:身份解析与配额/限流/租约。每一件都是**拒绝**的权力(400/403/429),
  *  缺席 = 该道门不存在(不是「默认放行的门」——两者在事故复盘里语义完全不同)。 */
 export interface ServiceGovernanceDeps {
-    /**
-     * Resolve identity + the owned session BEFORE the spec is built (S6). Throw `HttpError` to reject.
-     * Optional: when omitted, no principal/ownership enforcement (the body's sessionId is used as-is).
-     */
-    authorize?: (ctx: {
-        req: IncomingMessage;
-        body: TaskRequestBody;
-    }) => Promise<RequestAuth>;
     /** 鉴权桥(registry-core api/auth-bridge):registry 用户 JWT → principal。缺席=分支不存在
      *  (bearer 只认 SERVICE_AUTH_TOKEN(S),现状不变)。 */
     webAdminJwtVerifier?: {
@@ -867,7 +883,7 @@ export interface ServiceDepGroups {
     deployment?: ServiceDeploymentDeps;
     knobs?: ServiceKnobDeps;
 }
-/** 平铺视图 = 必填七件 + 其余七组的全可选并集。**派生**自组接口,故与分组形永不漂。 */
+/** 平铺视图 = 必填八件 + 其余七组的全可选并集。**派生**自组接口,故与分组形永不漂。 */
 export type FlatServiceDeps = ServiceCoreDeps & Partial<ServiceStoreDeps & ServiceCoordinatorDeps & ServiceSeamDeps & ServiceObservabilityDeps & ServiceGovernanceDeps & ServiceDeploymentDeps & ServiceKnobDeps>;
 /** createHttpServer 的入参:两形皆可(平铺=存量,分组=推荐)。同名键两形都给时,**顶层显式键赢**
  *  (含显式 `undefined`)——一处装配点只该用一形,混用时以肉眼最近的那个为准。 */

package/dist/http/server.js

@@ -4,6 +4,7 @@ import { validatePendingSteer } from "@sema-agent/core";
 import {} from "../web-admin-client/facade.js";
 import { describeValueShape } from "@sema-agent/settings-schema";
 import { HttpError } from "../security.js";
+import { SessionForkInProgressError } from "../execution-placement.js";
 import {} from "../memory-sync.js";
 import {} from "../orchestration/workflow-agent-steer.js";
 import {} from "../orchestration/workflow-completion-inbox.js";
@@ -22,6 +23,7 @@ import { createRequestGuards } from "./request-guards.js";
 import { sqlEngineSeatIssue } from "../sql-engine-posture.js";
 import { parkDecisionStoreRefusal } from "../orchestration/workflow-park-decision.js";
 import { CHECKPOINT_CTX_SEALING_REQUIRED } from "./checkpoint-ctx.js";
+import { PARKED_REVIVE_EXECUTION_SEAT_REQUIRED } from "../parked-decide.js";
 import { retiredServiceDepsRefusal } from "./retired-service-deps.js";
 import { createAdmission, MAX_SKILL_CONTENT_CHARS, MAX_SYSTEM_PROMPT_CHARS, MAX_OUTPUT_SCHEMA_CHARS, validateUserSkills } from "./admission.js";
 import { createResumeLegs } from "./resume-legs.js";
@@ -61,6 +63,9 @@ export function createHttpServer(rawDeps) {
     if (typeof deps.runnerFor !== "function") {
         throw new Error("createHttpServer: the runnerFor seat is required (it picks each task's Runner from its execution lane) — pass the hands-lane selector, or `runnerFor: () => runner` for a single-Runner embedding; refusing to start rather than run every task on the widest Runner");
     }
+    if (typeof deps.authorize !== "function") {
+        throw new Error("createHttpServer: the authorize seat is required — it is the only resolver of a submission's root session; pass `createAuthorizer(config, runner.sessions)` for a single-user embedding; refusing to start rather than run submissions on a root nobody attested");
+    }
     {
         const retired = retiredServiceDepsRefusal(deps);
         if (retired !== undefined)
@@ -88,6 +93,8 @@ export function createHttpServer(rawDeps) {
     }
     if (deps.checkpointStore !== undefined && deps.checkpointCtxSealing === undefined)
         throw new Error(`createHttpServer: ${CHECKPOINT_CTX_SEALING_REQUIRED}`);
+    if (deps.parkedReviveSurface !== undefined && deps.sessionStorage?.executionPlacement === undefined)
+        throw new Error(`createHttpServer: ${PARKED_REVIVE_EXECUTION_SEAT_REQUIRED}`);
     const idemCache = new IdempotencyCache();
     const inflightRuns = new Map();
     const preemptableRuns = new DrainYieldingPreemptBook(() => deps.drainState?.draining === true);
@@ -164,6 +171,10 @@ export function createHttpServer(rawDeps) {
             }
             if (sendSessionError(res, err, "open"))
                 return;
+            if (err instanceof SessionForkInProgressError) {
+                sendError(res, 409, err.code, err.message);
+                return;
+            }
             sendError(res, 500, "internal.error", "internal error");
         });
     });

package/dist/http/session-inherit-env.d.ts

@@ -1,7 +1,7 @@
 /**
  * [ref] × 7.106.0 合并复审 X1(gpt-6 腿 A F1 [high],验证腿 B verified)—— 请求键 `inheritEnv` 的**会话绑定唯一提交点**。
  *
- * ── 分界(与 `device-placement.ts` 的首绑写协议同一句判据)──────────────────────────────────────────────────
+ * ── 分界(与 `execution-context.ts` 认领之后的执行放置提交同一句判据)──────────────────────────────────────────────────
  * 凡需要「这条会话此刻归我这条 run」才成立的事,排在 run 认领之后;其余全排在建任何东西之前。`inheritEnv` 的三道判
  * (值形 / 车道 / 射程)是**读**,住在 `resolveSpec`(两腿同判,任何副作用之前);而「本会话的 host 工厂下一次造环境按哪个词」
  * 是**写**,它只属于一条**被受理**的 run —— 修前它写在 `resolveSpec` 的最后一步,仍先于路由层的拒(`/v1/tasks/stream` 的
@@ -28,10 +28,9 @@ export interface SessionInheritEnvCommitCtx {
     bindSessionInheritEnv?: ((sessionId: string, policy: TaskInheritEnv | undefined) => void) | undefined;
 }
 /**
- * 在 run 认领之后调用:把受理的那条请求的 `inheritEnv`(缺席 = 清)写进本会话的绑定。`sessionId` 缺席(不接 authorizer 的嵌入形)⇒
- * 不写 —— `"all"` 在那一形已被 `resolveSpec` 响亮拒,`"scrub"` / 缺席与工厂缺省同形。
+ * 在 run 认领之后调用:把受理的那条请求的 `inheritEnv`(缺席 = 清)写进本会话(这条 run 的根会话)的绑定。
  */
-export declare function commitSessionInheritEnv(ctx: SessionInheritEnvCommitCtx, sessionId: string | undefined, body: {
+export declare function commitSessionInheritEnv(ctx: SessionInheritEnvCommitCtx, sessionId: string, body: {
     readonly inheritEnv?: TaskInheritEnv | undefined;
 }): void;
 //# sourceMappingURL=session-inherit-env.d.ts.map

package/dist/http/session-inherit-env.js

@@ -1,5 +1,5 @@
 export function commitSessionInheritEnv(ctx, sessionId, body) {
-    if (sessionId === undefined || ctx.bindSessionInheritEnv === undefined)
+    if (ctx.bindSessionInheritEnv === undefined)
         return;
     ctx.bindSessionInheritEnv(sessionId, body.inheritEnv);
 }

package/dist/http/wire-types.d.ts

@@ -195,7 +195,7 @@ export interface TaskRequestBody {
      *  after it"). core enforces the "before" edges and the service passes its rejection codes through UNCHANGED for the
      *  shell to render: `resume_at.before_target_not_user` (only plain user-message targets),
      *  `resume_at.before_root_unsupported` (can't rewind past the session root — start a new session),
-     *  `rewind_snapshot.unresolvable` (rewindFiles: no snapshot at/above the "before" branch point). Only meaningful
+     *  `rewind_snapshot.unresolvable` (restoreFiles: no snapshot at/above the "before" branch point). Only meaningful
      *  WITH `resumeAt` — sent alone it's a 400 (fail-loud, not a silent no-op). */
     resumeAtMode?: string;
     /** [ref] Phase3 (reuse-path warm-resume): require the `sessionId` to ALREADY exist. When `true` and the session
@@ -221,11 +221,6 @@ export interface TaskRequestBody {
     /** DV-15: opt-in tolerance for a PARTIAL file restore (default = loud terminal failure carrying the per-file
      *  ledger; `true` = keep going and disclose the same ledger on the result's rewindNotes). */
     acceptPartialRestore?: boolean;
-    /** RETIRED spelling (whole-tree epoch). Still accepted on the wire: its capture sense (true, no resumeAt) is
-     *  a tolerated no-op with a deprecation disclosure; its restore sense (true + resumeAt) is a typed rejection
-     *  naming `restoreFiles` — the restore semantics genuinely changed (whole tree ⇒ tracked set), so that
-     *  migration is explicit by design (core adjudicates; the server never remaps it silently). */
-    rewindFiles?: boolean;
     /** R8 code-only rewind (CC "Restore code" mode): converge the TRACKED set to the history boundary at a prior
      *  USER message WITHOUT forking the conversation (the session leaf is untouched — only the files move). The
      *  value is the same handle as `resumeAt` (the prompt's taskId); the service resolves it → the entry id. Honored ONLY
@@ -235,7 +230,7 @@ export interface TaskRequestBody {
      *  与 `checkpointStore` 同;没有 `"enabled"` —— 缺席就是「部署说了算」的唯一形,声明只能单向收紧)。`"disabled"` ⇒
      *  这条 run 零历史店调用:编辑照常落盘,但不做首次触碰备份、不铸回合边界、不做 fork 携带;委派出去的子代继承
      *  (core `ParentSpecSeat` 从本位铸,本仓零接线)。`wiring_manifest.fileHistory` 报 `"disabled"`。
-     *  同一个提交里再要还原(`restoreFiles` / `rewindFilesTo` / 退役 `rewindFiles`)= 体内矛盾 ⇒ **受理时** 400
+     *  同一个提交里再要还原(`restoreFiles` / `rewindFilesTo`)= 体内矛盾 ⇒ **受理时** 400
      *  `request.field_conflict`(`request-value-closure.ts` 的 `FILE_HISTORY_DISABLED_NO_RESTORE`):立门时 core 的 `rewind.capture_disabled`
      *  落在会话按 `resumeAt` 分叉之后、拒后不回滚,所以本层在副作用之前拒([ref] / core 7.35.0 [ref] 起 core 在分叉**之前**拒,
      *  本层 400 照旧有效)。续跑腿不过这道门。
@@ -472,7 +467,7 @@ export interface TaskRequestBody {
      *  · 仅 `REMOTE_EXEC=device` 的部署接受;其它车道收到它 = **400 响亮拒**(不静默忽略 —— 调用方会
      *    以为自己指定了执行设备,而那条声明从未存在);
      *  · 仅**根任务**提交携带(子代无条件继承根绑定,core 为 subagent/cascade/verify 另铸 sessionId);
-     *  · 首绑 = INSERT-if-absent CAS(并发单赢家);后续根提交:缺席 = 沿用绑定 / 携且同 = 幂等 /
+     *  · 首绑 = 根会话行执行格的 absent → writer(device, D)(按受理那一读的住客定址,并发单赢家);后续根提交:缺席 = 沿用绑定 / 携且同 = 幂等 /
      *    携且异 = 403 `device.identity_mismatch`(**v1 无隐式重绑**,换设备走
      *    `POST /v1/devices/sessions/:rootSessionId/rebind`);
      *  · resume 家族(`/decide` / `/answer` / `/plan_review` / `/wake`)**不收**这个键:车道随树固定。
@@ -491,10 +486,11 @@ export interface TaskRequestBody {
     /** [ref]⑧/[ref]/[ref] (core 5.23.0 `TaskSpec.oneShot`): this SUBMISSION is one-shot — no later turn exists
      *  in which an async background notification could land (the archetypal case is a headless `sema -p` whose
      *  process exits when the turn ends). PER-REQUEST on purpose: "does this submission expect to be continued" is
-     *  a property of the submission, not of the connection it arrived on. core consumes it as GUIDANCE ONLY (the
-     *  `RunWorkflow` / delegation receipts tell the model to block-wait via `TaskOutput({block:true})` instead of
-     *  "end your turn, you will be notified" — the latter is actively wrong here and loses background results); it
-     *  grants nothing, so there is no tenancy gate. Sibling of `interactiveTools` (the same `-p` posture) and passed
+     *  a property of the submission, not of the connection it arrived on. Since core 7.60.0 it changes when the
+     *  submission ends: where a one-shot run would end, the engine waits for the background agents and workflow runs
+     *  it started (a background command or Monitor watch is never waited for), bounded by the run's walltime, a cancel
+     *  and a 600 s ceiling; a sync submission therefore returns after that background work. It grants nothing, so
+     *  there is no tenancy gate. Sibling of `interactiveTools` (the same `-p` posture) and passed
      *  through the same way: a boolean rides, absent/garbage ⇒ key omitted (core's default = interactive). Rides the
      *  persisted body onto resume legs. */
     oneShot?: boolean;

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export type { TaskRequestBody } from "./http/wire-types.js";
 export { ensureCheckpointCtxSealing } from "./sealed-key.js";
 export type { CheckpointCtxSealing } from "./http/checkpoint-ctx.js";
 export { createHttpServer, type ServiceDeps, type RequestAuth, type FlatServiceDeps, type ServiceDepGroups, type ServiceCoreDeps, type ServiceStoreDeps, type ServiceCoordinatorDeps, type ServiceSeamDeps, type ServiceObservabilityDeps, type ServiceGovernanceDeps, type ServiceDeploymentDeps, type ServiceKnobDeps, } from "./http/server.js";
+export type { ExecutionContext, ResolvedTaskSpec, RootedTaskSpec } from "./http/execution-context.js";
 export { createPeerDesk } from "./peer-seat.js";
 export type { PeerDesk, PeerLease, McpDraft, A2aDraft } from "./peer-seat.js";
 export { createSideQueryLane, type KeyResolver, type SideQueryLane, type SideQueryLaneCtx } from "./boot/side-query-lane.js";

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

@@ -1,29 +1,68 @@
 import { type MemoryBackend, type MemorySyncClientResult, type MemorySyncTransport } from "@sema-agent/core";
+import { type OneTimeMigrationWindow } from "./plugins/one-time-migrations.js";
 /** 结构化日志面(src/observability/logger.ts Logger 的结构子集——测试可注入捕获器)。 */
 export interface MemorySyncLog {
     info(msg: string, fields?: Record<string, unknown>): void;
     warn(msg: string, fields?: Record<string, unknown>): void;
 }
-/** 缺省对端名(core `syncMemoryScope` 同款缺省;cursor 按 (scope,peer) 分区)。 */
-export declare const DEFAULT_MEMORY_SYNC_PEER = "central";
 /**
- * fetch transport(core `MemorySyncTransport` 的部署实现)。`url` = 中心 server 基址(尾斜杠剥除,
- * core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedPrincipal 的
- * verified-principal 门对齐)。非 2xx throw(status + body 前 200 字节——中心 4xx/5xx 的 typed error
- * body 就是最好的诊断线索);2xx 返回解码后的 JSON(形状校验在 core parseMemorySyncResponse,职责
- * 不重复)。`timeoutMs`(缺省 60s,AbortSignal.timeout)是活性保护:fire-and-forget 轮挂死会把
- * inflight 节流永久卡住(undici 默认 headers 超时 300s 太钝)。
+ * 中心基址 → 同步对端的身份(规范化基址)。本仓唯一的铸点:`config.ts` 读 env 时调它拒启(引擎关着也拒),transport 建时再调它铸身份 —— 同一只纯函数,同一个答案。
+ * 两道判,各归各的属主,本函数不另写规则:
+ *  ① 地址的形 —— 这只地址是「后面要拼路径的基址」座位(post 把同步路径拼在它后面),判官与拒句就是那一座位的那一只({@link pathBaseUrlRefusal}:层级式 http(s),
+ *     不带 userinfo / query / fragment;拒句只点名规则、值只到 origin);
+ *  ② 身份里有没有凭据 —— 判官是引擎包根的 `carriesCredential`(引擎同步客户端判 `transport.peer` 的同一只:任何 userinfo,或同主体出口脱敏会遮掉的任何一段,
+ *     例如路径段里的令牌形),判的就是规范化之后的身份 —— 引擎第一轮判的那个值。身份随每个请求体与落盘游标走,所以带凭据的地址拒而不清洗
+ *     (清洗过的身份是另一个身份;令牌只走 `MEMORY_SYNC_TOKEN`);拒句不引地址的任何部分。
+ * 规范化 = WHATWG URL 的 `origin`(协议与主机小写、缺省端口省掉)+ 路径去尾斜杠;规范化之后装不进中心侧 `peer` 列({@link MEMORY_SYNC_PEER_COLUMN_CHARS},
+ * 每一轮都会被中心拒)⇒ 同样拒。
+ */
+export declare function memorySyncPeerOf(url: string): string;
+/**
+ * 起服日志行 `memory_sync_enabled` 的字段(两处起服 —— `boot/stores.ts` 与 `run-local.ts` —— 同读这一只)。`peer` 是运维改绑游标时要抄的那个值:
+ * 它已过 {@link memorySyncPeerOf} 的两道判(带凭据的身份起不来);仍过展示铸点({@link buildDisplaySafeUrl}),日志里的 URL 值一律经它 —— 两只判官
+ * (引擎的出口脱敏与本仓的展示形状律)不是同一份实现,本仓的那一只若遮了引擎放行的一段,这一行带遮记号而不是逐字(响亮,不漏)。
+ */
+export declare function buildMemorySyncEnabledFields(peer: string, scope: string, cursorPath: string): {
+    readonly peer: string;
+    readonly scope: string;
+    readonly cursorPath: string;
+};
+/**
+ * fetch transport(core `MemorySyncTransport` 的部署实现)。`peer` = {@link memorySyncPeerOf}(`url`)(建时铸一次;拒的地址在这里抛,一个请求都不发),
+ * `post` 打 `${peer}${path}`(core 传来的 path 以 `/` 开头);`token` 走 Authorization: Bearer(与中心侧 gatedPrincipal 的 verified-principal 门对齐)。
+ * 非 2xx throw(status + body 前 200 字节——中心 4xx/5xx 的 typed error body 就是最好的诊断线索);2xx 返回解码后的 JSON(形状校验在 core
+ * parseMemorySyncResponse,职责不重复)。`timeoutMs`(缺省 60s,AbortSignal.timeout)是活性保护:fire-and-forget 轮挂死会把 inflight 节流永久卡住
+ * (undici 默认 headers 超时 300s 太钝)。
  */
 export declare function createMemorySyncTransport(opts: {
     url: string;
     token: string;
     timeoutMs?: number;
-    fetchImpl?: typeof fetch;
+    /** The one call shape this transport makes (`fetch` itself fits it). */
+    fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
 }): MemorySyncTransport;
-/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录旁)下的
- *  per-(peer, scope) sidecar(`sync-cursors/<peer>/<scope 摘要>.json`)。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同);scope 段取 sha256 前 32 hex
- *  (scope 键带 `:` `/` 且可长过段编码的 64 字符帽 —— 名字只需区分,内容里仍记原 scope,读时比对)。 */
-export declare function memorySyncCursorPath(memoryRoot: string, peer: string, scope: string): string;
+/** 一层的游标文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root)下 `sync-cursors/<scope 摘要>.json`。一层一只,不随对端变。
+ *  落在子目录里:与更早的根下一层文件名 `sync-cursor-<peer>.json` 的空间不相交。 */
+export declare function memorySyncCursorPath(memoryRoot: string, scope: string): string;
+/** M31 一次的读数(测试按它断言)。`window: "closed"` ⇒ 一行都没读。 */
+export interface SyncCursorRelocationM31Report {
+    readonly window: "open" | "closed";
+    readonly moved: number;
+    readonly left: number;
+}
+/**
+ * ⑤ 一次性迁移 M31:把升级前的游标搬到各自那一层的路径(`rename`,字节不变;只搬不改,判归引擎)。`today` = UTC 日历日;窗关 ⇒ 不搬。
+ *  · 上一版的分区目录 `sync-cursors/central/<scope 摘要>.json` ⇒ `sync-cursors/<同名>`(两种布局的文件名是同一只 scope 摘要);搬空的目录删掉;
+ *    名字不是摘要形的(写游标的 staging 残片)原地不动。
+ *  · 更早的 `sync-cursor-central.json` ⇒ 它记的那一层的路径;读不成对象 / 没有 scope ⇒ 原地不动、一行 warn(没法说它是哪一层的基线)。
+ *  · 目标路径上已有游标 ⇒ 不搬、不删,一行 warn(这一层用路径上的那一份;留下的那只没有读者)。
+ * 与同一数据根上并跑的另一个进程(server + run-local)同搬:源已被对方搬走(`ENOENT`)⇒ 跳过。残余(如实):先查目标再 `rename` 之间若有写者在目标路径上
+ * 落下游标,会被盖掉 —— 写者只有本模块的 runner,而 runner 写任何游标之前先跑完本步。别的读写错 ⇒ 抛(这一轮整轮失败、下一轮再搬)。
+ */
+export declare function relocateSyncCursorsM31(memoryRoot: string, log: MemorySyncLog, opts: {
+    readonly today: string;
+    readonly window?: Pick<OneTimeMigrationWindow, "removableAfter">;
+}): Promise<SyncCursorRelocationM31Report>;
 /** 一轮里一层的结果。 */
 export interface MemorySyncLayerResult {
     readonly scope: string;
@@ -59,9 +98,9 @@ export declare function createMemorySyncRunner(opts: {
     /** 同步层(`config.memorySync.scope`);它同属主的项目层随它一起同步。 */
     scope: string;
     memoryRoot: string;
+    /** 对端 = 它的 `peer`(这一轮的对端只有这一个来源;游标绑的对端由引擎对它判)。 */
     transport: MemorySyncTransport;
     log: MemorySyncLog;
-    peer?: string;
     now?: () => number;
     /** S2.5 分批(core 1.284 两 seam):push 集/pull 集单轮上限。未设=不分批(wire 字节不变)。 */
     maxPushEntries?: number;