@sema-agent/server 7.51.0 → 7.52.1

package/dist/http/routes/runs.js

@@ -15,7 +15,7 @@ import { scopedIdempotencyKey } from "../idempotency.js";
 import { streamSseLog } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
-import { resolveStreamApprovalGate } from "../../tool-approval.js";
+import { ASK_DECISION_CONSUMER_ABSENT, resolveStreamApprovalGate } from "../../tool-approval.js";
 import { MAX_DECISION_NOTE_CHARS } from "../../approval-ask-machine.js";
 import { normalizeRunEventType } from "../../trace/project.js";
 import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
@@ -30,6 +30,7 @@ export const RUN_CANCEL_RE = /^\/v1\/runs\/([^/]+)\/cancel$/;
 export const RUN_STEER_RE = /^\/v1\/runs\/([^/]+)\/steer$/;
 export const RUN_DETACH_RE = /^\/v1\/runs\/([^/]+)\/detach$/;
 export const RUN_COMPACT_RE = /^\/v1\/runs\/([^/]+)\/compact$/;
+export const RUN_INTERRUPT_RE = /^\/v1\/runs\/([^/]+)\/interrupt$/;
 export const ELICIT_RESPOND_RE = /^\/v1\/elicitations\/([^/]+)\/respond$/;
 export const QUESTION_RESPOND_RE = /^\/v1\/questions\/([^/]+)\/respond$/;
 export const TOOL_APPROVAL_RESPOND_RE = /^\/v1\/tool-approvals\/([^/]+)\/respond$/;
@@ -51,6 +52,20 @@ const AskDecisionBodySchema = z
     actor: z.object({ label: z.string().max(ASK_ACTOR_LABEL_MAX) }).strict().optional(),
 })
     .strict();
+const ASK_DECISION_CONFIRM_TIMEOUT_MS = 2_000;
+function withDeadline(op, timeoutMs, label) {
+    let timer;
+    return Promise.race([
+        op,
+        new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            timer.unref?.();
+        }),
+    ]).finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+}
 export function projectDecisionActor(raw) {
     const parsed = AskDecisionActorSchema.safeParse(raw);
     return parsed.success ? parsed.data : undefined;
@@ -288,7 +303,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                     }
                 }
                 else {
-                    const claimed = await rs.markResuming(taskId);
+                    const claimed = await rs.markResuming(taskId, deps.instanceId ?? "default");
                     if (!claimed) {
                         const now = await rs.getRun(taskId);
                         const st = now?.status;
@@ -387,7 +402,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         const taskId = steerMatch[1];
         let body;
         try {
-            body = (await readJson(req));
+            body = ((await readJson(req)) ?? {});
         }
         catch (e) {
             if (e instanceof HttpError) {
@@ -482,6 +497,10 @@ async function handleRunsBody(req, res, url, ctx, miss) {
                     sendError(res, 422, "steering.invalid_content", e instanceof Error ? e.message : "invalid steering content");
                     return;
                 }
+                if (code === "steering.blocked_by_hook") {
+                    sendError(res, 422, "steering.blocked_by_hook", e instanceof Error ? e.message : "the deployment's userPromptSubmit hook refused this steering input (fail-closed)");
+                    return;
+                }
                 if (code === "steering.duplicate_input_id") {
                     parkDuplicateKey = e instanceof Error ? e.message : undefined;
                     sendDuplicateKey();
@@ -529,7 +548,13 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             return;
         }
         if (run.status === "running") {
-            sendNotRunning("run is active on another replica — cross-replica live-steer is not yet supported");
+            const provenElsewhere = typeof run.instanceId === "string" && run.instanceId.length > 0 && deps.instanceId !== undefined && run.instanceId !== deps.instanceId;
+            if (provenElsewhere) {
+                sendNotRunning("run is live on another replica — a live steer must reach the replica holding the stream; resend it there, or use POST /v1/runs/:id/cancel for a run-level stop");
+            }
+            else {
+                sendNotRunning("no live steerable face for this run on this replica — verify/cascade execution lanes expose none (those legs return a result, not a live stream); use POST /v1/runs/:id/cancel for a run-level stop");
+            }
             return;
         }
         if (deps.checkpointStore && deps.sessionStorage?.getLeafId) {
@@ -639,6 +664,152 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         sendNotRunning(`run is ${run.status} — not accepting steers`);
         return;
     }
+    const interruptMatch = req.method === "POST" ? RUN_INTERRUPT_RE.exec(url) : null;
+    if (interruptMatch) {
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+            return;
+        if (!deps.runStore) {
+            sendError(res, 501, "capability.run_store_required", "async runs require a durable run store (DB_BACKEND=mysql|pg|local)");
+            return;
+        }
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && principal === undefined) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const taskId = interruptMatch[1];
+        let interruptRaw;
+        try {
+            interruptRaw = await readJson(req);
+        }
+        catch (e) {
+            if (e instanceof HttpError) {
+                sendError(res, e.status, httpErrorCode(e.status, e.code), e.message);
+                return;
+            }
+            sendError(res, 400, "request.invalid_json", "invalid JSON body");
+            return;
+        }
+        const interruptNormalized = interruptRaw === null || interruptRaw === undefined ? {} : interruptRaw;
+        if (typeof interruptNormalized !== "object" || Array.isArray(interruptNormalized)) {
+            sendError(res, 400, "request.body_shape", "body must be {} (bare halt: cut the in-flight turn and stop the run at this boundary) or { text: string (non-empty) } (cut + steer: the text reaches the model after the cut)");
+            return;
+        }
+        const interruptBody = interruptNormalized;
+        const interruptBare = !("text" in interruptBody);
+        if (interruptBare && Object.keys(interruptBody).length > 0) {
+            sendError(res, 400, "request.body_shape", "body must be {} (bare halt: cut the in-flight turn and stop the run at this boundary) or { text: string (non-empty) } (cut + steer: the text reaches the model after the cut)");
+            return;
+        }
+        let text = "";
+        if (!interruptBare) {
+            if (typeof interruptBody.text !== "string" || interruptBody.text.length === 0) {
+                sendError(res, 400, "request.body_shape", "body must be {} (bare halt: cut the in-flight turn and stop the run at this boundary) or { text: string (non-empty) } (cut + steer: the text reaches the model after the cut)");
+                return;
+            }
+            text = interruptBody.text;
+        }
+        const interruptIdemRaw = headerStr(req.headers["idempotency-key"]);
+        const interruptScoped = interruptIdemRaw ? scopedIdempotencyKey(interruptIdemRaw, source, principal) : undefined;
+        const interruptInputId = interruptScoped ? `idem-${createHash("sha256").update(interruptScoped).digest("hex").slice(0, 32)}` : uuidv7();
+        const interruptMessageId = interruptInputId;
+        const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        if (!interruptBare) {
+            try {
+                validatePendingSteer({ text, trusted, inputId: interruptInputId });
+            }
+            catch (e) {
+                if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
+                    sendError(res, 422, "steering.invalid_content", e.message);
+                    return;
+                }
+                throw e;
+            }
+        }
+        const run = await deps.runStore.getRun(taskId);
+        if (!run) {
+            sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
+            return;
+        }
+        if (!trusted && run.owner !== null && run.owner !== principal) {
+            sendError(res, 404, "not_found.run", RUN_NOT_FOUND_MESSAGE);
+            return;
+        }
+        if (!runSessionAcceptOk(req, res, run, "run.interrupt"))
+            return;
+        const sendInterruptNotRunning = (error) => sendError(res, 409, "steering.not_running", error);
+        const sendNoLiveTurn = (status, streamJustSettled) => {
+            if (isParkedRunStatus(status)) {
+                sendError(res, 409, "interrupt.nothing_in_flight", "run is parked on a pending decision — there is no in-flight turn to interrupt; to deliver input use POST /v1/runs/:id/steer (it parks onto the checkpoint and injects on resume)");
+                return;
+            }
+            if (streamJustSettled) {
+                sendInterruptNotRunning("run just finished on this replica — no in-flight turn to interrupt");
+                return;
+            }
+            if (status === "running") {
+                const provenElsewhere = typeof run.instanceId === "string" && run.instanceId.length > 0 && deps.instanceId !== undefined && run.instanceId !== deps.instanceId;
+                if (provenElsewhere) {
+                    sendError(res, 409, "interrupt.not_held", "run is live on another replica — interrupt must reach the replica holding the stream; resend it there, or use POST /v1/runs/:id/cancel for a run-level stop");
+                }
+                else {
+                    sendError(res, 409, "interrupt.not_held", "no live interruptible turn face for this run on this replica — verify/cascade execution lanes expose none (those legs return a result, not a live stream); use POST /v1/runs/:id/cancel for a run-level stop");
+                }
+                return;
+            }
+            sendInterruptNotRunning(`run is ${status} — not accepting an interrupt`);
+        };
+        const liveStream = steerableRuns.get(taskId);
+        if (!liveStream) {
+            sendNoLiveTurn(run.status, false);
+            return;
+        }
+        if (interruptBare) {
+            let haltReceipt;
+            try {
+                haltReceipt = await liveStream.halt();
+            }
+            catch (e) {
+                if (e.code !== "steering.not_running")
+                    throw e;
+                const freshRun = await deps.runStore.getRun(taskId).catch(() => undefined);
+                sendNoLiveTurn(freshRun?.status ?? run.status, true);
+                return;
+            }
+            sendJson(res, 202, {
+                taskId,
+                status: run.status,
+                turnCut: haltReceipt.turnCut,
+                note: "halt accepted — cut + stop: turnCut reports whether THIS call cut a live turn (repeat calls answer turnCut:false once the stop is latched). The run now ends at this boundary as status:\"completed\" with haltedByUser:true — resume by submitting the next objective on the same session. Each real cut is marked by a task.turn_interrupted event with detail.cause:\"user_halt\"; a halt racing the run's natural last moments reports the natural completion, still carrying the haltedByUser seat.",
+            });
+            return;
+        }
+        try {
+            await liveStream.steer(text, { trusted, priority: "now", ...(interruptInputId !== undefined ? { inputId: interruptInputId } : {}) });
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === "steering.invalid_content") {
+                sendError(res, 422, "steering.invalid_content", e instanceof Error ? e.message : "invalid steering content");
+                return;
+            }
+            if (code === "steering.blocked_by_hook") {
+                sendError(res, 422, "steering.blocked_by_hook", e instanceof Error ? e.message : "the deployment's userPromptSubmit hook refused this input (fail-closed)");
+                return;
+            }
+            if (code === "steering.duplicate_input_id") {
+                sendError(res, 409, "steering.duplicate_input_id", e instanceof Error ? e.message : "this Idempotency-Key was already accepted with different content or at a different tier — reissue with a fresh key");
+                return;
+            }
+            if (code !== "steering.not_running")
+                throw e;
+            const freshRun = await deps.runStore.getRun(taskId).catch(() => undefined);
+            sendNoLiveTurn(freshRun?.status ?? run.status, true);
+            return;
+        }
+        sendJson(res, 202, { taskId, status: run.status, delivery: "queued-immediate", messageId: interruptMessageId, note: "interrupt accepted — the cut is best-effort: a task.turn_interrupted event on the run stream is the proof a turn was actually cut; with nothing in flight the text lands at the next turn boundary" });
+        return;
+    }
     const compactMatch = req.method === "POST" ? RUN_COMPACT_RE.exec(url) : null;
     if (compactMatch) {
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
@@ -722,7 +893,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         const taskId = detachMatch[1];
         let body;
         try {
-            body = (await readJson(req));
+            body = ((await readJson(req)) ?? {});
         }
         catch (e) {
             if (e instanceof HttpError) {
@@ -945,7 +1116,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         let body;
         try {
-            body = (await readJson(req));
+            body = ((await readJson(req)) ?? {});
         }
         catch (e) {
             if (e instanceof HttpError) {
@@ -1168,10 +1339,16 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             }
             return true;
         };
+        const observedSettled = new Map();
         const syncLiveFromDecidedRow = (row) => {
             if (!decidedRowIsAuthoritative(row))
                 return false;
+            if (observedSettled.has(row.askId))
+                return true;
+            if (deps.toolApproval?.editedDecisionInFlight(row.askId) === true)
+                return true;
             const settled = deps.toolApproval?.notifyExternalDecision(row.askId, row.decision === "approve");
+            observedSettled.set(row.askId, settled?.settled ?? 0);
             if (row.decision === "approve" && (settled?.settled ?? 0) > 0) {
                 recordFailOpen("server.hitl.row-derived-approve-drops-updated-input", "runs:sync-live-from-decided-row");
             }
@@ -1254,7 +1431,13 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             sendTerminal(row0);
             return;
         }
+        if (body.decision === "approve" && hasUpdatedInput && (deps.toolApproval?.liveConsumerCount(askId) ?? 0) === 0) {
+            deps.logger?.warn?.("ask_decision_edit_undeliverable", { taskId, askId });
+            sendError(res, 409, "conflict.ask_edit_undeliverable", "this decision carries an edited input but no live approval waiter for this ask exists on THIS replica — the edit cannot be bound to the decision (the durable ask row has no field for it), so committing would run the ORIGINAL input instead. Nothing was decided: re-send without updatedInput to approve the original as-is, or send the decision to the replica holding this ask (the live POST /v1/tool-approvals/:approvalId/respond leg is always same-replica)");
+            return;
+        }
         let outcome;
+        const releaseEditMark = body.decision === "approve" && hasUpdatedInput ? deps.toolApproval?.markEditedDecisionInFlight(askId) : undefined;
         try {
             outcome = await askStore.decideAsk(askId, row0.batchId, {
                 decision: body.decision,
@@ -1270,6 +1453,25 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                 hadIdempotencyKey: body.idempotencyKey !== undefined,
                 error: err instanceof Error ? err.message : String(err ?? ""),
             });
+            if (releaseEditMark !== undefined &&
+                body.idempotencyKey !== undefined &&
+                deps.toolApproval &&
+                deps.toolApproval.editedDecisionInFlightCount(askId) === 1) {
+                try {
+                    const confirmed = await withDeadline(askStore.getAsk(askId), ASK_DECISION_CONFIRM_TIMEOUT_MS, "getAsk(ambiguous-commit-confirm)");
+                    if (confirmed !== null &&
+                        confirmed.state === "DECIDED" &&
+                        confirmed.decision === body.decision &&
+                        confirmed.idempotencyKey === body.idempotencyKey &&
+                        !confirmed.provisional) {
+                        const settledNow = deps.toolApproval.notifyExternalDecision(askId, confirmed.decision === "approve", body.updatedInput).settled;
+                        deps.logger?.warn?.("ask_decision_edit_settled_after_ambiguous_commit", { taskId, askId, settled: settledNow });
+                    }
+                }
+                catch (confirmErr) {
+                    deps.logger?.warn?.("ask_decision_edit_confirm_failed", { taskId, askId, error: confirmErr instanceof Error ? confirmErr.message : String(confirmErr ?? "") });
+                }
+            }
             if (body.idempotencyKey !== undefined) {
                 sendError(res, 500, "internal.error", "the ask decision store failed around commit — the decision MAY already be persisted; retry with the same idempotencyKey to replay it instead of colliding with it");
             }
@@ -1278,6 +1480,9 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             }
             return;
         }
+        finally {
+            releaseEditMark?.();
+        }
         if (!outcome.ok) {
             if (outcome.row?.state === "DECIDED" && !syncLiveFromDecidedRow(outcome.row))
                 return;
@@ -1311,6 +1516,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             decidedAtMs: outcome.row.decidedAtMs,
             actor,
             ...(forwarded ? { updatedInputForwarded: true } : {}),
+            ...(settled === 0 ? { consumerState: ASK_DECISION_CONSUMER_ABSENT } : {}),
             ...decisionNoteEcho(outcome.row),
         });
         return;

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

@@ -8,7 +8,7 @@
  * `pendingStagings`(Phase A→B 的 staging 绑定)、`importLeases`(per-session 导入租约)与它的两个操作。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { type SessionRulesRecord } from "@sema-agent/core";
+import { type SessionRulesRecord, type FileHistoryExport } from "@sema-agent/core";
 import { type StagingHandle } from "../../session-sync-kernel.js";
 import type { RouteCtx } from "../route-ctx.js";
 export type PendingStaging = {
@@ -17,17 +17,15 @@ export type PendingStaging = {
     owner: string | null;
     resolution?: "overwrite-dst";
     operatorOk: boolean;
-    snapshots: Array<{
-        key: string;
-        manifest: Array<[string, string]>;
-    }>;
+    /** S-15: 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;
     }>;
-    /** 对抗复查 A-3(HIGH):Phase A's DECLARED entry-id set — Phase B verifies the streamed NDJSON matches it
+    /** 交叉复查 A-3(HIGH):Phase A's DECLARED entry-id set — Phase B verifies the streamed NDJSON matches it
      *  (a different tree under the same staging would otherwise commit while the parked snapshots/anchors
      *  still reference the DECLARED one). */
     declaredEntryIds: string[];

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

@@ -1,8 +1,8 @@
 import { once } from "node:events";
 import { randomBytes, createHash } from "node:crypto";
-import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, SessionError, SessionPolicyError } from "@sema-agent/core";
+import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, SessionError, SessionPolicyError, validateFileHistoryExport } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
-import { exportSessionManifest, fileSnapshotImportFace, replayPolicyRecords, overwriteWipeIncapable, wipeSessionAttendants } from "../../session-sync.js";
+import { exportSessionManifest, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, overwriteWipeIncapable, wipeSessionAttendants } from "../../session-sync.js";
 import { classifySyncRelationshipByIds, SyncConflictError } from "../../session-sync-kernel.js";
 import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, msg } from "../send.js";
@@ -37,7 +37,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
     const { readJson, readRawBody, safeDecode, sessionOwnerScopeForWrite, rateLimited } = ctx.helpers;
     const { pendingStagings, importLeases, touchImportLease, cleanupStaging } = ctx.local.sessionSync;
     {
-        const sm = /^\/v1\/sessions\/([^/]+)\/sync\/(manifest|entries|import|plan|blobs(?:\/([^/]+))?|snapshots\/([^/]+)\/blobs\/([^/]+)|import\/([^/]+)\/entries)$/.exec(url);
+        const sm = /^\/v1\/sessions\/([^/]+)\/sync\/(manifest|entries|import|plan|blobs(?:\/([^/]+))?|history\/blobs\/([^/]+)|import\/([^/]+)\/entries)$/.exec(url);
         if (sm) {
             const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
             if (!deps.backend || !ownerOf) {
@@ -130,23 +130,27 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
             if (sm[4] !== undefined && req.method === "GET") {
                 if (!pullGateOk())
                     return;
-                const key = safeDecode(sm[4]);
-                const hash = safeDecode(sm[5]);
-                if (key === null || hash === null) {
-                    sendError(res, 400, "request.path_malformed", "invalid snapshot key or blob hash");
+                const hash = safeDecode(sm[4]);
+                if (hash === null) {
+                    sendError(res, 400, "request.path_malformed", "invalid blob hash");
                     return;
                 }
                 if (!SHA256_HEX_RE.test(hash)) {
                     sendError(res, 400, "request.id_invalid", "blob hash must be 64 lowercase-hex chars");
                     return;
                 }
-                const fs = deps.fileSnapshotStore;
-                const manifest = await fs?.exportManifest?.(sessionId, key);
-                if (!manifest || ![...manifest.values()].includes(hash)) {
+                const fs = deps.fileHistoryStore;
+                if (fs?.syncBlobFaces !== true) {
                     sendError(res, 404, "not_found.blob", "blob not found");
                     return;
                 }
-                const bytes = await fs?.getBlob?.(hash);
+                const envelope = typeof fs.exportHistory === "function" ? await fs.exportHistory(sessionId) : null;
+                const referenced = envelope !== null && envelope !== undefined && envelope.tracked.some((t) => t.versions.some((v) => v.blobHash === hash));
+                if (!referenced) {
+                    sendError(res, 404, "not_found.blob", "blob not found");
+                    return;
+                }
+                const bytes = await fs.getBlob?.(hash);
                 if (!bytes) {
                     sendError(res, 404, "not_found.blob", "blob not found");
                     return;
@@ -165,9 +169,9 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.id_invalid", "blob hash must be 64 lowercase-hex chars");
                     return;
                 }
-                const fs = deps.fileSnapshotStore;
-                if (typeof fs?.putBlob !== "function") {
-                    sendError(res, 501, "capability.snapshot_store_required", "blob upload requires a durable snapshot store");
+                const fs = deps.fileHistoryStore;
+                if (fs?.syncBlobFaces !== true || typeof fs.putBlob !== "function") {
+                    sendError(res, 501, "capability.snapshot_store_required", "blob upload requires a durable file-history store");
                     return;
                 }
                 const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES);
@@ -215,11 +219,19 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
-                const snapshotsOk = Array.isArray(body.snapshots) && body.snapshots.every((s) => typeof s === "object" && s !== null && typeof s.key === "string" && Array.isArray(s.manifest));
-                if (!snapshotsOk || !Array.isArray(body.policy) || !Array.isArray(body.anchors)) {
+                if (!Array.isArray(body.policy) || !Array.isArray(body.anchors)) {
                     sendError(res, 400, "request.body_shape", "malformed import metadata");
                     return;
                 }
+                let fileHistory = null;
+                if (body.fileHistory !== undefined && body.fileHistory !== null) {
+                    const door = validateFileHistoryExport(body.fileHistory);
+                    if (!door.ok) {
+                        sendError(res, 400, "request.field_invalid", `fileHistory: ${door.error.message}`);
+                        return;
+                    }
+                    fileHistory = body.fileHistory;
+                }
                 if (body.resolution !== undefined && body.resolution !== "overwrite-dst") {
                     sendError(res, 400, "request.field_invalid", "resolution must be 'overwrite-dst'");
                     return;
@@ -227,7 +239,6 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 const resolution = body.resolution;
                 const srcLogDigest = typeof body.logDigest === "string" && body.logDigest.length > 0 ? body.logDigest : undefined;
                 const entryIds = body.entryIds;
-                const snapshots = body.snapshots;
                 const policy = body.policy;
                 const anchors = body.anchors;
                 const dstIds = (await deps.sessionStorage.listEntryIds?.(sessionId)) ?? null;
@@ -251,16 +262,21 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         digestSaysDiffer = true;
                 }
                 if (relA.relation === "identical" && !digestSaysDiffer) {
-                    const importFaceIdentical = fileSnapshotImportFace(deps.fileSnapshotStore);
-                    if (importFaceIdentical && deps.fileSnapshotStore?.getBlob && snapshots.length > 0) {
-                        const getBlobA = (h) => deps.fileSnapshotStore.getBlob(h);
-                        for (const snap of snapshots) {
-                            const r = await importFaceIdentical.importManifest(sessionId, snap.key, new Map(snap.manifest), getBlobA);
-                            if (!r.ok) {
-                                sendError(res, 422, r.error.code === "restore_failed" ? "restore_failed" : "missing_blob", `snapshot import failed (${r.error.code})`);
+                    if (fileHistory !== null && deps.fileHistoryStore?.syncBlobFaces === true && fileHistoryImportFace(deps.fileHistoryStore) && deps.fileHistoryStore.getBlob) {
+                        if (resolution === "overwrite-dst") {
+                            const activeNow = await deps.runStore?.getActiveTaskId(sessionId);
+                            if (activeNow) {
+                                sendError(res, 409, "session_active", "session has an active run; sync after it settles", { activeTaskId: activeNow });
                                 return;
                             }
                         }
+                        const getBlobA = (h) => deps.fileHistoryStore.getBlob(h);
+                        const r = await replayFileHistory(deps.fileHistoryStore, sessionId, fileHistory, getBlobA, { allowReplace: resolution === "overwrite-dst" });
+                        const failCode = r.ok ? undefined : r.error.code === "not_found" ? "missing_blob" : r.error.code;
+                        if (!r.ok) {
+                            sendError(res, 422, failCode, `file history import failed (${r.error.code})`);
+                            return;
+                        }
                     }
                     const opOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals);
                     if (deps.sessionPolicyStore)
@@ -299,13 +315,13 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         return;
                     }
                 }
-                const fss = deps.fileSnapshotStore;
-                const canImportSnapshots = fileSnapshotImportFace(fss) !== undefined;
-                if (canImportSnapshots) {
+                const fss = deps.fileHistoryStore;
+                if (fileHistory !== null && fileHistoryImportFace(fss) !== undefined) {
                     const distinct = new Set();
-                    for (const snap of snapshots)
-                        for (const [, hash] of snap.manifest)
-                            distinct.add(hash);
+                    for (const t of fileHistory.tracked)
+                        for (const v of t.versions)
+                            if (v.blobHash !== null)
+                                distinct.add(v.blobHash);
                     const all = [...distinct];
                     if (typeof fss?.hasBlobs === "function") {
                         const present = await fss.hasBlobs(all);
@@ -315,9 +331,9 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                             return;
                         }
                     }
-                    else {
+                    else if (typeof fss?.getBlob === "function") {
                         for (const hash of all) {
-                            if (!(await deps.fileSnapshotStore.getBlob(hash))) {
+                            if (!(await fss.getBlob(hash))) {
                                 sendError(res, 422, "missing_blob", "missing blob; PUT all referenced blobs before import");
                                 return;
                             }
@@ -332,13 +348,13 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 importLeases.set(sessionId, { at: Date.now(), stagingId });
                 pendingStagings.set(stagingId, {
                     handle, realSessionId: sessionId, owner: importingPrincipal, ...(resolution ? { resolution } : {}), operatorOk,
-                    snapshots, policy, anchors, declaredEntryIds: entryIds, openedBy: scope.gateOwner, openedFleetWide: scope.fleetWide,
+                    fileHistory, policy, anchors, declaredEntryIds: entryIds, openedBy: scope.gateOwner, openedFleetWide: scope.fleetWide,
                 });
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
             }
-            if (sm[6] !== undefined && req.method === "POST") {
-                const stagingId = safeDecode(sm[6]);
+            if (sm[5] !== undefined && req.method === "POST") {
+                const stagingId = safeDecode(sm[5]);
                 if (stagingId === null) {
                     sendError(res, 400, "request.id_invalid", "invalid staging id");
                     return;
@@ -352,8 +368,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                const getBlob = (h) => deps.fileSnapshotStore.getBlob(h);
-                const importFaceB = fileSnapshotImportFace(deps.fileSnapshotStore);
+                const getBlob = (h) => deps.fileHistoryStore?.getBlob ? deps.fileHistoryStore.getBlob(h) : Promise.resolve(undefined);
                 const validator = new StreamingImportValidator();
                 let lineBuf = "";
                 let pendingBatch = [];
@@ -453,17 +468,15 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 try {
                     const committed = await pending.handle.commit(pending.owner, pending.resolution ? { resolution: pending.resolution } : undefined);
                     if (pending.resolution === "overwrite-dst" && (committed.relation === "fork" || committed.relation === "stale")) {
-                        await wipeSessionAttendants({ fileSnapshotStore: deps.fileSnapshotStore, sessionPolicyStore: deps.sessionPolicyStore, resumeAnchorStore: deps.resumeAnchorStore }, sessionId);
+                        await wipeSessionAttendants({ fileHistoryStore: deps.fileHistoryStore, sessionPolicyStore: deps.sessionPolicyStore, resumeAnchorStore: deps.resumeAnchorStore }, sessionId);
                     }
-                    if (importFaceB) {
-                        const importManifest = importFaceB.importManifest;
-                        for (const snap of pending.snapshots) {
-                            const r = await importManifest(sessionId, snap.key, new Map(snap.manifest), getBlob);
-                            if (!r.ok) {
-                                sendError(res, 422, r.error.code === "restore_failed" ? "restore_failed" : "missing_blob", `snapshot import failed (${r.error.code})`);
-                                cleanupStaging(stagingId);
-                                return;
-                            }
+                    if (pending.fileHistory !== null && deps.fileHistoryStore && fileHistoryImportFace(deps.fileHistoryStore)) {
+                        const r = await replayFileHistory(deps.fileHistoryStore, sessionId, pending.fileHistory, getBlob, { allowReplace: pending.resolution === "overwrite-dst" });
+                        const failCode = r.ok ? undefined : r.error.code === "not_found" ? "missing_blob" : r.error.code;
+                        if (!r.ok) {
+                            sendError(res, 422, failCode, `file history import failed (${r.error.code})`);
+                            cleanupStaging(stagingId);
+                            return;
                         }
                     }
                     const policyStore = deps.sessionPolicyStore;