@botlearn-course/daemon 0.0.20-beta.1 → 0.0.20-beta.10

package/dist/agent-service-sandbox.js

@@ -1,4 +1,7 @@
-import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { chmodSync, closeSync, createWriteStream, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import path from "node:path";
 import { ensureDaemonHome } from "./auth-store.js";
 import { AGENT_SERVICE_WS_SCHEMA, AGENT_SERVICE_WS_SUBPROTOCOL, createSandboxFrame, createWorkspaceFileChunk, parseSandboxFrame, UnsupportedSandboxProtocolError, WORKSPACE_FILE_READ_BINARY_CAPABILITY, } from "./agent-service-ws-protocol.js";
@@ -10,6 +13,15 @@ import { parseRuntimeSkillProviderGrantSet, prepareRuntimeSkillProvider, Runtime
 import { RunDispatcher, } from "./run-dispatcher.js";
 import { cleanupRuntimeSessionWorkspaceCopyStaging, copyRuntimeSessionWorkspace, ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, finalizeRuntimeSessionWorkspaceCopy, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, runtimeSessionWorkspaceDir, WORKSPACE_COPY_POLICY_V1, WorkspaceCopyError, workspaceCopyV1Supported, } from "./workspace.js";
 import { readWorkspaceFile, WorkspaceFileReadError } from "./workspace-file-read.js";
+import { checkpointWorkspace, WorkspaceSnapshotControlError, } from "./workspace-snapshot-control.js";
+import { assertWorkspaceWriterFreezeSupported, freezeRuntimeWriters, issueWorkspaceWriterFreezeProof, quiesceRuntimeWriters, thawRuntimeWriters, } from "./runtime-quiescence.js";
+import { WorkspaceSnapshotStagingError } from "./workspace-snapshot-staging.js";
+import { validateWorkspaceEntrySet, WorkspaceEntrySetError, } from "./workspace-entry-set.js";
+import { WORKSPACE_SNAPSHOT_POLICY_V1, workspaceSnapshotPolicyCapability, } from "./workspace-snapshot-policy.js";
+import { assertWorkspaceRestoreCapacity, restoreWorkspaceSnapshot, WorkspaceRestoreError, } from "./workspace-restore.js";
+import { readWorkspaceMaterializationMarker } from "./workspace-materialization.js";
+import { assertWorkspaceFilesystem, flushWorkspaceFilesystem, nasWorkspaceEnabled, } from "./workspace-filesystem.js";
+import { applyRuntimeWorkspaceQuota } from "./workspace-quota.js";
 import { WebSocketClient, } from "./websocket-client.js";
 const RECONNECT_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
 const MAX_SPOOL_FRAMES = 1024;
@@ -19,6 +31,14 @@ const LEGACY_EVENT_ACK_WINDOW = 1;
 const INPUT_ATTACHMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 /** 出站 seq 基址：seq = connection_epoch * SEQ_EPOCH_BASE + n，跨重连单调（合同 §1.1）。 */
 const SEQ_EPOCH_BASE = 1_000_000_000;
+function agentServiceHttpBase(wsUrl) {
+    const url = new URL(wsUrl);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    url.pathname = "/internal/v1";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
 const RUNTIME_LOG_WINDOW_MS = 60_000;
 const WORKSPACE_FILE_TRANSFER_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const DISABLED_RUNTIME_LOG_POLICY = {
@@ -346,6 +366,7 @@ export class AgentServiceSandboxClient {
     sessionProfiles = new Map();
     /** activation-scoped 模型短凭据；只保存在内存中，绝不进入 state.json。 */
     activationContexts = new Map();
+    activationCleanupTasks = new Map();
     pendingAcks = new Map();
     pendingFileReports = new Map();
     inflightCommands = new Set();
@@ -438,7 +459,7 @@ export class AgentServiceSandboxClient {
         session.nativeSessionId = nativeSessionId.trim() || null;
         this.persist();
     }
-    finishTurn(payload) {
+    async finishTurn(payload) {
         const scope = this.turnScopes.get(payload.agent_run_id);
         if (!scope)
             return;
@@ -454,7 +475,7 @@ export class AgentServiceSandboxClient {
             };
             this.persist();
             try {
-                this.completePendingActivationCleanup(scope.sessionId);
+                await this.completePendingActivationCleanup(scope.sessionId);
             }
             catch (error) {
                 this.log.error("failed to revoke a terminal runtime session workspace", {
@@ -472,19 +493,31 @@ export class AgentServiceSandboxClient {
             this.currentTurnSessionId = null;
         this.persist();
     }
-    completePendingActivationCleanup(sessionId) {
+    async completePendingActivationCleanup(sessionId) {
+        const existing = this.activationCleanupTasks.get(sessionId);
+        if (existing)
+            return await existing;
+        const task = this.runPendingActivationCleanup(sessionId);
+        this.activationCleanupTasks.set(sessionId, task);
+        try {
+            await task;
+        }
+        finally {
+            if (this.activationCleanupTasks.get(sessionId) === task) {
+                this.activationCleanupTasks.delete(sessionId);
+            }
+        }
+    }
+    async runPendingActivationCleanup(sessionId) {
         const session = this.state.sessions[sessionId];
         const pending = session?.pendingActivationCleanup;
         if (!session || !pending)
             return;
-        revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
         const activation = this.activationContexts.get(sessionId);
         if (activation?.activationId === pending.activationId) {
             this.activationContexts.delete(sessionId);
             this.sessionProfiles.delete(sessionId);
         }
-        if (session.activationId === pending.activationId)
-            session.activationId = null;
         if (!session.completedActivations.includes(pending.activationId)) {
             // Session-close/generation-rotate are the retention bounds. Never evict an
             // activation tombstone while the session is alive: activation IDs are opaque, so
@@ -499,15 +532,13 @@ export class AgentServiceSandboxClient {
         delete session.acceptedCommands[commandId];
         session.pendingActivationCleanup = null;
         this.turnScopes.delete(pending.agentRunId);
-        if (this.activeSessionId === sessionId)
-            this.activeSessionId = null;
         if (this.currentTurnSessionId === sessionId)
             this.currentTurnSessionId = null;
         this.persist();
     }
-    recoverPendingActivationCleanups() {
+    async recoverPendingActivationCleanups() {
         for (const sessionId of Object.keys(this.state.sessions)) {
-            this.completePendingActivationCleanup(sessionId);
+            await this.completePendingActivationCleanup(sessionId);
         }
     }
     async run() {
@@ -568,6 +599,23 @@ export class AgentServiceSandboxClient {
         this.removeOperationalLogSink();
         this.socket?.close(1000, "daemon_stopping");
     }
+    async stopGracefully() {
+        this.dispatcher.cancelAll();
+        await quiesceRuntimeWriters(null);
+        await flushWorkspaceFilesystem();
+        this.stop();
+    }
+    async drainWorkspace(fence) {
+        if (!(await this.dispatcher.drain(10_000)) || !this.isCurrentLifecycleFence(fence)) {
+            return;
+        }
+        await quiesceRuntimeWriters(null);
+        await flushWorkspaceFilesystem();
+        if (!this.isCurrentLifecycleFence(fence))
+            return;
+        await this.sendControlFrame("sandbox.drained", {});
+        this.stop();
+    }
     async postEvent(agentRunId, event) {
         const scope = this.turnScopes.get(agentRunId);
         if (!scope)
@@ -578,6 +626,8 @@ export class AgentServiceSandboxClient {
         if (!this.sandboxGeneration || !this.connectionEpoch) {
             throw new Error("Agent Service sandbox is not authenticated");
         }
+        // Terminal truth is never delayed by object storage. Durable workspace checkpointing
+        // is a separate lifecycle command issued only for pause/cleanup/rotation.
         if (event.type === "run.block") {
             await this.waitForEventCapacity();
         }
@@ -782,10 +832,11 @@ export class AgentServiceSandboxClient {
         if (frame.sandbox_generation !== this.state.sandboxGeneration) {
             // Generation change wipes every session shard (contract §1.4).
             this.dispatcher.cancelAll();
+            await quiesceRuntimeWriters(null);
             this.rejectPending(new Error("Agent Service sandbox generation changed"));
             for (const sessionId of Object.keys(this.state.sessions)) {
                 revokeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration);
-                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration);
+                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration, nasWorkspaceEnabled());
             }
             this.state.sessions = {};
             this.state.sandboxGeneration = frame.sandbox_generation;
@@ -800,7 +851,7 @@ export class AgentServiceSandboxClient {
         this.connectionEpoch = frame.connection_epoch;
         this.inboundSeq = frame.seq;
         this.outboundSeq = frame.connection_epoch * SEQ_EPOCH_BASE;
-        this.recoverPendingActivationCleanups();
+        await this.recoverPendingActivationCleanups();
         const heartbeatSeconds = Number(frame.payload.heartbeat_seconds ?? 15);
         this.heartbeatMs = Math.max(1_000, Math.min(60_000, heartbeatSeconds * 1000));
         const staleSeconds = Number(frame.payload.stale_after_seconds ?? 45);
@@ -815,12 +866,19 @@ export class AgentServiceSandboxClient {
         this.runtimeLogPolicy = runtimeLogPolicy(frame.payload.runtime_log_policy);
         await cleanupRuntimeSessionWorkspaceCopyStaging();
         this.persist();
+        assertWorkspaceFilesystem(process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT ?? "");
+        assertWorkspaceWriterFreezeSupported();
         await this.sendControlFrame("sandbox.ready", {
             protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
             capabilities: [
                 WORKSPACE_FILE_READ_BINARY_CAPABILITY,
+                "workspace_writer_freeze_v1",
+                "workspace_snapshot_v2",
+                "workspace_restore_v1",
+                ...(nasWorkspaceEnabled() ? ["workspace_nas_v1"] : []),
                 ...(workspaceCopyV1Supported() ? ["workspace_copy_v1"] : []),
             ],
+            workspace_snapshot_policy: workspaceSnapshotPolicyCapability(),
             daemon_version: this.options.daemonVersion,
             runtime_versions: {
                 course_daemon: this.options.daemonVersion,
@@ -952,16 +1010,19 @@ export class AgentServiceSandboxClient {
                     });
                 });
                 return;
+            case "workspace.checkpoint":
+                this.scheduleLifecycle("workspace.checkpoint", () => this.handleWorkspaceCheckpoint(frame));
+                return;
+            case "workspace.thaw":
+                await thawRuntimeWriters();
+                await this.sendCommandAck(frame, "ok");
+                return;
             case "sandbox.shutdown":
-                this.stop();
+                await this.stopGracefully();
                 return;
             case "sandbox.drain":
                 await this.sendCommandAck(frame, "ok");
-                this.scheduleLifecycle("sandbox.drain", async (fence) => {
-                    if (await this.dispatcher.drain(10_000) && this.isCurrentLifecycleFence(fence)) {
-                        await this.sendControlFrame("sandbox.drained", {});
-                    }
-                });
+                this.scheduleLifecycle("sandbox.drain", (fence) => this.drainWorkspace(fence));
                 return;
             case "protocol.error":
                 throw new Error(`server protocol error: ${String(frame.payload.code ?? "unknown")}`);
@@ -979,16 +1040,15 @@ export class AgentServiceSandboxClient {
             this.scheduleLifecycle("sandbox.sync.close", (fence) => this.closeSession(sessionId, "sync_close", frame, fence));
         }
         const state = frame.payload.state;
+        if (frame.payload.thaw_runtime_writers === true) {
+            await thawRuntimeWriters();
+        }
         if (state === "shutdown") {
-            this.stop();
+            await this.stopGracefully();
             return;
         }
         if (state === "drain") {
-            this.scheduleLifecycle("sandbox.sync.drain", async (fence) => {
-                if (await this.dispatcher.drain(10_000) && this.isCurrentLifecycleFence(fence)) {
-                    await this.sendControlFrame("sandbox.drained", {});
-                }
-            });
+            this.scheduleLifecycle("sandbox.sync.drain", (fence) => this.drainWorkspace(fence));
         }
         // idle/run/cancel：实际工作全部由显式命令帧下发（合同 §1.3）。
     }
@@ -998,6 +1058,7 @@ export class AgentServiceSandboxClient {
         const courseRunId = frame.payload.course_run_id;
         const requestedWorkspaceRef = frame.payload.workspace_ref;
         const requestedCopy = frame.payload.workspace_copy;
+        const requestedRestore = frame.payload.workspace_restore;
         const requestedCopyRecord = requestedCopy && typeof requestedCopy === "object"
             ? requestedCopy
             : undefined;
@@ -1018,7 +1079,11 @@ export class AgentServiceSandboxClient {
                     typeof copyId !== "string" ||
                     copyId.length < 1 ||
                     typeof requestedCopySource !== "string" ||
-                    requestedCopySource.length < 1))) {
+                    requestedCopySource.length < 1))
+            || (requestedRestore !== null && requestedRestore !== undefined &&
+                (typeof requestedRestore !== "object" || Array.isArray(requestedRestore)))
+            || (requestedCopy !== null && requestedCopy !== undefined &&
+                requestedRestore !== null && requestedRestore !== undefined)) {
             throw new Error("invalid session.open payload");
         }
         if (session.courseRunId !== null && session.courseRunId !== courseRunId) {
@@ -1032,6 +1097,165 @@ export class AgentServiceSandboxClient {
         const isNewSession = session.courseRunId === null;
         let markerPath = null;
         try {
+            if (requestedRestore && typeof requestedRestore === "object") {
+                const raw = requestedRestore;
+                const descriptorRaw = raw.descriptor;
+                const controlFence = raw.control_fence;
+                let restoreControlToken = raw.control_token;
+                if (!controlFence || typeof controlFence !== "object" || Array.isArray(controlFence)) {
+                    throw new Error("invalid workspace restore control fence");
+                }
+                if (typeof restoreControlToken !== "string" || restoreControlToken.length < 32) {
+                    throw new Error("invalid workspace restore control token");
+                }
+                if (!descriptorRaw || !Array.isArray(raw.entries)) {
+                    throw new Error("invalid workspace restore payload");
+                }
+                const descriptor = {
+                    sandboxId: this.options.sandboxId,
+                    sandboxGeneration: this.sandboxGeneration,
+                    runtimeSessionId: sessionId,
+                    continuityState: descriptorRaw.continuity_state,
+                    continuityErrorCode: descriptorRaw.continuity_error_code,
+                    snapshotId: descriptorRaw.snapshot_id,
+                    revision: Number(descriptorRaw.revision),
+                    contentSha256: descriptorRaw.content_sha256,
+                    expectedFileCount: Number(descriptorRaw.expected_file_count),
+                    expectedEntryCount: Number(descriptorRaw.expected_entry_count),
+                    expectedTotalBytes: Number(descriptorRaw.expected_total_bytes),
+                };
+                const workspaceDirectory = runtimeSessionWorkspaceDir(sessionId, this.sandboxGeneration);
+                const requiredFreeBytes = Math.max(WORKSPACE_SNAPSHOT_POLICY_V1.requiredRestoreFreeBytes, descriptor.expectedTotalBytes + WORKSPACE_SNAPSHOT_POLICY_V1.requiredRestoreFreeBytes);
+                // Fail before issuing or consuming any object grant. The download staging is a
+                // sibling on this same bounded backing filesystem and is renamed, not copied,
+                // into the atomic restore staging tree.
+                assertWorkspaceRestoreCapacity({
+                    workspaceDirectory,
+                    descriptor,
+                    requiredFreeBytes,
+                    entryCopies: 2,
+                });
+                const entries = [];
+                const predownloadRoot = path.join(path.dirname(workspaceDirectory), `.botlearn-predownload-${sessionId}-${randomUUID()}`);
+                mkdirSync(predownloadRoot, { recursive: true, mode: 0o700 });
+                try {
+                    let nextCursor = null;
+                    do {
+                        if (nextCursor !== null && nextCursor.length > 2048) {
+                            throw new Error("invalid workspace restore cursor");
+                        }
+                        const pageSignal = AbortSignal.timeout(60_000);
+                        const response = await fetch(`${agentServiceHttpBase(this.options.wsUrl)}/runtime-sessions/${sessionId}/restore-grants`, {
+                            method: "POST",
+                            headers: {
+                                Authorization: `Bearer ${restoreControlToken}`,
+                                "Content-Type": "application/json",
+                            },
+                            body: JSON.stringify({
+                                policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId,
+                                fence: controlFence,
+                                cursor: nextCursor,
+                                // Fetch one canonical entry at a time so a grant is consumed as soon as
+                                // it is signed, including deployments using the minimum 60-second TTL.
+                                max_entries: 1,
+                            }),
+                            signal: pageSignal,
+                        });
+                        if (!response.ok) {
+                            let code = "workspace_restore_unavailable";
+                            let retryable = response.status >= 500 || response.status === 408 ||
+                                response.status === 429;
+                            try {
+                                const rejected = await response.json();
+                                const detail = rejected.detail;
+                                if (detail && typeof detail === "object" && !Array.isArray(detail)) {
+                                    const stableCode = detail.code;
+                                    if (typeof stableCode === "string" && stableCode.length <= 120) {
+                                        code = stableCode;
+                                    }
+                                    if (typeof detail.retryable === "boolean") {
+                                        retryable = detail.retryable;
+                                    }
+                                }
+                            }
+                            catch {
+                                // Content-free fallback retains the stable local failure code.
+                            }
+                            throw new WorkspaceRestoreError(code, retryable);
+                        }
+                        const page = await response.json();
+                        if (!Array.isArray(page.entries))
+                            throw new Error("invalid workspace restore page");
+                        if (typeof page.control_token !== "string" || page.control_token.length < 32) {
+                            throw new Error("invalid refreshed workspace restore control token");
+                        }
+                        restoreControlToken = page.control_token;
+                        const pageFiles = [];
+                        for (const value of page.entries) {
+                            if (!value || typeof value !== "object" || Array.isArray(value)) {
+                                throw new Error("invalid workspace restore entry");
+                            }
+                            const item = value;
+                            if (item.entry_type === "directory") {
+                                entries.push({ type: "directory", path: String(item.path), mode: "0700" });
+                                continue;
+                            }
+                            if (item.entry_type !== "file" || !item.grant || typeof item.grant !== "object") {
+                                throw new Error("invalid workspace restore file grant");
+                            }
+                            const entry = {
+                                type: "file",
+                                path: String(item.path),
+                                mode: item.mode,
+                                sizeBytes: Number(item.size_bytes),
+                                sha256: String(item.sha256),
+                            };
+                            entries.push(entry);
+                            pageFiles.push({ entry, grant: item.grant });
+                        }
+                        // Validate all paths and duplicates before using any page path locally.
+                        validateWorkspaceEntrySet({ schemaVersion: "agent-workspace-entry-set/1", entries }, WORKSPACE_SNAPSHOT_POLICY_V1.limits);
+                        for (const { entry, grant } of pageFiles) {
+                            if (typeof grant.url !== "string")
+                                throw new Error("workspace restore grant missing");
+                            const destination = path.join(predownloadRoot, ...entry.path.split("/"));
+                            mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+                            const part = `${destination}.part`;
+                            const downloadSignal = AbortSignal.timeout(60_000);
+                            const download = await fetch(grant.url, {
+                                method: "GET",
+                                headers: grant.headers,
+                                signal: downloadSignal,
+                            });
+                            if (!download.ok)
+                                throw new Error(`workspace_restore_download_${download.status}`);
+                            if (!download.body)
+                                throw new Error("workspace_restore_download_body_missing");
+                            await pipeline(Readable.fromWeb(download.body), createWriteStream(part, { mode: 0o600 }), { signal: downloadSignal });
+                            renameSync(part, destination);
+                        }
+                        const rawNext = page.next_cursor;
+                        if (rawNext !== null && rawNext !== undefined && typeof rawNext !== "string") {
+                            throw new Error("invalid workspace restore cursor");
+                        }
+                        nextCursor = rawNext ?? null;
+                    } while (nextCursor !== null);
+                    await restoreWorkspaceSnapshot({
+                        workspaceDirectory,
+                        controlDirectory: path.join(ensureDaemonHome(), "agent-service-sandboxes", this.options.sandboxId, "workspace-control"),
+                        descriptor,
+                        entrySet: { schemaVersion: "agent-workspace-entry-set/1", entries },
+                        limits: WORKSPACE_SNAPSHOT_POLICY_V1.limits,
+                        requiredFreeBytes,
+                        downloadFile: async (entry, partPath) => {
+                            renameSync(path.join(predownloadRoot, ...entry.path.split("/")), partPath);
+                        },
+                    });
+                }
+                finally {
+                    rmSync(predownloadRoot, { recursive: true, force: true });
+                }
+            }
             if (typeof requestedCopySource === "string" && typeof copyId === "string") {
                 if (session.workspaceCopyReceipt !== null) {
                     const receipt = session.workspaceCopyReceipt;
@@ -1075,28 +1299,161 @@ export class AgentServiceSandboxClient {
                 });
                 return;
             }
+            if (requestedRestore) {
+                const restoreError = error instanceof WorkspaceRestoreError ? error : null;
+                await this.sendSessionFrame("session.open_failed", sessionId, {
+                    error_code: restoreError?.code ?? "workspace_restore_unavailable",
+                    retryable: restoreError?.retryable ?? true,
+                });
+                return;
+            }
             throw error;
         }
         session.courseRunId = courseRunId;
         session.workspaceRef = session.workspaceRef ?? (typeof requestedWorkspaceRef === "string"
             ? requestedWorkspaceRef
             : `ws_${sessionId.replaceAll("-", "")}_g${this.sandboxGeneration}`);
-        if (session.workspaceCopyReceipt === null) {
+        // Replaying session.open is part of reconnect reconciliation.  An already-active
+        // runtime may still be creating files in this workspace, so never transiently revoke
+        // its group write/execute access before the following session.activate arrives.
+        if (session.workspaceCopyReceipt === null && (isNewSession || session.activationId === null)) {
             ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration);
         }
-        this.state.sessions[sessionId] = session;
-        this.persist();
         if (markerPath !== null) {
             await finalizeRuntimeSessionWorkspaceCopy(markerPath);
         }
+        try {
+            if (!nasWorkspaceEnabled()) {
+                await applyRuntimeWorkspaceQuota(sessionId, this.sandboxGeneration);
+            }
+        }
+        catch (error) {
+            if (requestedRestore) {
+                await this.sendSessionFrame("session.open_failed", sessionId, {
+                    error_code: "workspace_restore_unavailable",
+                });
+                return;
+            }
+            if (requestedCopy) {
+                await this.sendSessionFrame("session.open_failed", sessionId, {
+                    error_code: "workspace_migration_io_failed",
+                });
+                return;
+            }
+            throw error;
+        }
+        this.state.sessions[sessionId] = session;
+        this.persist();
+        const materialization = readWorkspaceMaterializationMarker(this.options.sandboxId, sessionId);
         await this.sendSessionFrame("session.opened", sessionId, {
             workspace_ref: session.workspaceRef,
             native_session_id: session.nativeSessionId,
+            ...(materialization
+                ? {
+                    workspace_marker_version: 1,
+                    workspace_continuity_state: materialization.workspaceContinuityState,
+                    workspace_snapshot_id: materialization.snapshotId,
+                    workspace_revision: materialization.revision,
+                    workspace_content_sha256: materialization.contentSha256,
+                }
+                : {}),
             ...(session.workspaceCopyReceipt !== null
                 ? { workspace_copy_receipt: session.workspaceCopyReceipt }
                 : {}),
         });
     }
+    async handleWorkspaceCheckpoint(frame) {
+        const sessionId = frame.runtime_session_id;
+        const session = this.state.sessions[sessionId];
+        const checkpointId = frame.payload.checkpoint_id;
+        const controlToken = frame.payload.control_token;
+        const baseRevision = Number(frame.payload.base_revision);
+        const sourceKind = frame.payload.source_kind;
+        if (!session ||
+            this.currentTurnSessionId === sessionId ||
+            typeof checkpointId !== "string" ||
+            typeof controlToken !== "string" ||
+            controlToken.length < 32 ||
+            frame.payload.policy_id !== "WorkspaceSnapshotPolicyV1" ||
+            ![
+                "sandbox_pause",
+                "sandbox_cleanup",
+                "generation_rotation",
+                "initial_migration",
+                "live_workspace_copy",
+                "maintenance_repair",
+            ].includes(String(sourceKind)) ||
+            !Number.isSafeInteger(baseRevision) ||
+            baseRevision < 0 ||
+            frame.payload.agent_run_id != null ||
+            frame.payload.worker_attempt != null ||
+            frame.payload.activation_id != null) {
+            await this.sendCommandAck(frame, "rejected", "invalid_workspace_checkpoint");
+            return;
+        }
+        const lifecycleCheckpoint = [
+            "sandbox_pause",
+            "sandbox_cleanup",
+            "generation_rotation",
+        ].includes(String(sourceKind));
+        let checkpointCommitted = false;
+        try {
+            await freezeRuntimeWriters();
+            const freezeProof = issueWorkspaceWriterFreezeProof({
+                sandboxId: this.options.sandboxId,
+                sandboxGeneration: this.sandboxGeneration,
+                runtimeSessionId: sessionId,
+                checkpointId,
+            });
+            await checkpointWorkspace({
+                wsUrl: this.options.wsUrl,
+                reconnectToken: controlToken,
+                workspaceDirectory: runtimeSessionWorkspaceDir(sessionId, this.sandboxGeneration),
+                scope: {
+                    checkpointId,
+                    baseRevision,
+                    sandboxId: this.options.sandboxId,
+                    sandboxGeneration: this.sandboxGeneration,
+                    connectionEpoch: this.connectionEpoch,
+                    runtimeSessionId: sessionId,
+                },
+                freezeProof,
+            });
+            checkpointCommitted = true;
+            const marker = readWorkspaceMaterializationMarker(this.options.sandboxId, sessionId);
+            if (!marker)
+                throw new Error("workspace checkpoint marker missing");
+            await this.sendSessionFrame("session.opened", sessionId, {
+                workspace_ref: session.workspaceRef,
+                native_session_id: session.nativeSessionId,
+                workspace_marker_version: 1,
+                workspace_continuity_state: marker.workspaceContinuityState,
+                workspace_snapshot_id: marker.snapshotId,
+                workspace_revision: marker.revision,
+                workspace_content_sha256: marker.contentSha256,
+            });
+            await this.sendCommandAck(frame, "ok");
+            if (!lifecycleCheckpoint)
+                await thawRuntimeWriters();
+        }
+        catch (error) {
+            if (!lifecycleCheckpoint || !checkpointCommitted) {
+                await thawRuntimeWriters().catch(() => undefined);
+            }
+            this.log.error("workspace baseline checkpoint failed", {
+                sandboxId: this.options.sandboxId,
+                runtimeSessionId: sessionId,
+                error: error instanceof Error ? redactSecretString(error.message) : "unexpected",
+            });
+            const deterministic = (error instanceof WorkspaceSnapshotStagingError && !error.retryable) ||
+                error instanceof WorkspaceEntrySetError ||
+                (error instanceof WorkspaceSnapshotControlError && !error.retryable);
+            const errorCode = deterministic && "code" in error
+                ? String(error.code)
+                : "workspace_checkpoint_retryable";
+            await this.sendCommandAck(frame, "rejected", errorCode, !deterministic);
+        }
+    }
     async handleSessionActivate(frame, fence) {
         const sessionId = frame.runtime_session_id;
         const activationId = frame.activation_id;
@@ -1233,7 +1590,7 @@ export class AgentServiceSandboxClient {
         const previousSessionId = this.activeSessionId;
         const changesActivation = previousSessionId !== null && (previousSessionId !== sessionId || session.activationId !== activationId);
         if (changesActivation) {
-            const stopped = await this.deactivateSession(previousSessionId);
+            const stopped = await this.deactivateSession(previousSessionId, previousSessionId !== sessionId);
             if (fence && !this.isCurrentLifecycleFence(fence))
                 return;
             if (!stopped) {
@@ -1419,7 +1776,7 @@ export class AgentServiceSandboxClient {
         }
         delete session.acceptedCommands[commandId];
         this.persist();
-        this.finishTurn({ agent_run_id: runId });
+        await this.finishTurn({ agent_run_id: runId });
     }
     /**
      * 幂等关闭一个 runtime session：终止其 runtime 子进程、删除 workspace/native state、
@@ -1429,15 +1786,16 @@ export class AgentServiceSandboxClient {
         const session = this.state.sessions[sessionId];
         if (session) {
             const runIds = this.runIdsForSession(sessionId);
-            session.activationId = null;
             this.activationContexts.delete(sessionId);
             this.sessionProfiles.delete(sessionId);
-            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
             for (const runId of runIds)
                 this.dispatcher.cancel(runId);
             if (!await this.dispatcher.waitForRuns(runIds, 10_000)) {
                 throw new Error(`runtime session ${sessionId} did not stop before close`);
             }
+            await this.terminateSessionWriters(session);
+            session.activationId = null;
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
             if (fence && !this.isCurrentLifecycleFence(fence))
                 return;
             if (this.activeSessionId === sessionId)
@@ -1478,7 +1836,7 @@ export class AgentServiceSandboxClient {
                 delete session.acceptedCommands[commandId];
                 this.persist();
             }
-            this.finishTurn({ agent_run_id: accepted.agentRunId });
+            await this.finishTurn({ agent_run_id: accepted.agentRunId });
         }
         catch (error) {
             this.log.error("failed to reconcile an interrupted accepted turn", {
@@ -1580,21 +1938,40 @@ export class AgentServiceSandboxClient {
             .filter(([, scope]) => scope.sessionId === sessionId)
             .map(([runId]) => runId);
     }
-    async deactivateSession(sessionId) {
+    async deactivateSession(sessionId, terminateWriters = false) {
         const session = this.state.sessions[sessionId];
         if (!session)
             return true;
         const runIds = this.runIdsForSession(sessionId);
-        session.activationId = null;
         this.activationContexts.delete(sessionId);
         this.sessionProfiles.delete(sessionId);
-        revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        if (terminateWriters) {
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        }
         if (this.activeSessionId === sessionId)
             this.activeSessionId = null;
         for (const runId of runIds)
             this.dispatcher.cancel(runId);
         this.persist();
-        return this.dispatcher.waitForRuns(runIds, 10_000);
+        const stopped = await this.dispatcher.waitForRuns(runIds, 10_000);
+        if (stopped && terminateWriters) {
+            await this.terminateSessionWriters(session);
+        }
+        session.activationId = null;
+        this.persist();
+        return stopped;
+    }
+    async terminateSessionWriters(session) {
+        const activationIds = new Set([
+            ...session.completedActivations,
+            ...(session.activationId ? [session.activationId] : []),
+            ...(session.pendingActivationCleanup?.activationId
+                ? [session.pendingActivationCleanup.activationId]
+                : []),
+        ]);
+        for (const activationId of activationIds) {
+            await quiesceRuntimeWriters(activationId);
+        }
     }
     sameTurnScope(left, right) {
         return left.sessionId === right.sessionId &&
@@ -1687,7 +2064,7 @@ export class AgentServiceSandboxClient {
             spool_frames: this.spoolFrameCount(),
         });
     }
-    async sendCommandAck(frame, status, error) {
+    async sendCommandAck(frame, status, error, retryable) {
         if (frame.sandbox_generation !== this.sandboxGeneration ||
             frame.connection_epoch !== this.connectionEpoch)
             return;
@@ -1695,6 +2072,7 @@ export class AgentServiceSandboxClient {
             command_frame_id: frame.frame_id,
             status,
             ...(error !== undefined ? { error } : {}),
+            ...(retryable !== undefined ? { retryable } : {}),
         });
     }
     async handleWorkspaceFileRead(frame) {