@botlearn-course/daemon 0.0.20-beta.14 → 0.0.20-beta.16

package/dist/agent-service-sandbox.d.ts

@@ -3,8 +3,13 @@ import type { WorkspaceScanMeasurement } from "./file-candidates.js";
 import { type RuntimeSkillProviderFactory } from "./runtime-skills.js";
 import { type PersistentSessionExecution, type PreparedPersistentTurn, type RunReportingClient } from "./run-dispatcher.js";
 import type { CourseRuntime, CourseRuntimeProfile, RunEvent, RunEventReceipt, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
-export declare function workspaceDurabilityCapabilities(usesNasWorkspace?: boolean): string[];
-export declare function assertWorkspaceRestoreAllowed(requestedRestore: unknown, usesNasWorkspace?: boolean): void;
+export declare function workspaceDurabilityCapabilities(): string[];
+/**
+ * NAS 是运行时 workspace 的唯一持久事实来源，committed snapshot 只供前端查看。
+ * 任何 restore payload 都意味着对端仍在下发已删除的 S3 回写指令，必须 fail closed，
+ * 否则可能用落后的派生快照覆盖 NAS 中较新的内容。
+ */
+export declare function assertWorkspaceRestoreAllowed(requestedRestore: unknown): void;
 export interface AgentServiceSandboxOptions {
     wsUrl: string;
     sandboxId: string;
@@ -99,8 +104,8 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private handleTurnStart;
     private handleTurnCancel;
     /**
-     * 幂等关闭一个 runtime session：终止其 runtime 子进程、删除 workspace/native state、
-     * 清空本地状态分片，并回 session.closed。未知 session 直接回 closed。
+     * 幂等关闭一个 runtime session：终止其 runtime 子进程并清空 session-local state。
+     * Durable Workspace 由独立身份拥有，关闭执行上下文不会删除学员文件。
      */
     private closeSession;
     private reconcileInterruptedCommand;

package/dist/agent-service-sandbox.js

@@ -1,7 +1,4 @@
-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 { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 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";
@@ -11,17 +8,14 @@ import { activationRuntimeEnv, runtimeChildEnv } from "./runtime-env.js";
 import { redactSecretString } from "./redaction.js";
 import { parseRuntimeSkillProviderGrantSet, prepareRuntimeSkillProvider, RuntimeSkillProviderError, } from "./runtime-skills.js";
 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 { ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, runtimeSessionWorkspaceDir, } 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 { WorkspaceEntrySetError, } from "./workspace-entry-set.js";
+import { workspaceSnapshotPolicyCapability, } from "./workspace-snapshot-policy.js";
+import { assertWorkspaceFilesystem, flushWorkspaceFilesystem, } from "./workspace-filesystem.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;
@@ -41,15 +35,21 @@ function agentServiceHttpBase(wsUrl) {
 }
 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;
-export function workspaceDurabilityCapabilities(usesNasWorkspace = nasWorkspaceEnabled()) {
+export function workspaceDurabilityCapabilities() {
     return [
         "workspace_writer_freeze_v1",
         "workspace_snapshot_v2",
-        ...(usesNasWorkspace ? ["workspace_nas_v1"] : ["workspace_restore_v1"]),
+        "workspace_nas_v1",
+        "workspace_identity_v1",
     ];
 }
-export function assertWorkspaceRestoreAllowed(requestedRestore, usesNasWorkspace = nasWorkspaceEnabled()) {
-    if (usesNasWorkspace && requestedRestore !== null && requestedRestore !== undefined) {
+/**
+ * NAS 是运行时 workspace 的唯一持久事实来源，committed snapshot 只供前端查看。
+ * 任何 restore payload 都意味着对端仍在下发已删除的 S3 回写指令，必须 fail closed，
+ * 否则可能用落后的派生快照覆盖 NAS 中较新的内容。
+ */
+export function assertWorkspaceRestoreAllowed(requestedRestore) {
+    if (requestedRestore !== null && requestedRestore !== undefined) {
         throw new Error("workspace_restore_forbidden_for_nas");
     }
 }
@@ -243,8 +243,8 @@ function sandboxStatePath(sandboxId) {
 function emptySessionState() {
     return {
         courseRunId: null,
+        workspaceId: null,
         workspaceRef: null,
-        workspaceCopyReceipt: null,
         runtimeId: null,
         nativeSessionId: null,
         contextRevision: 0,
@@ -262,8 +262,8 @@ function normalizeSessionState(value) {
         return base;
     return {
         courseRunId: typeof value.courseRunId === "string" ? value.courseRunId : null,
+        workspaceId: typeof value.workspaceId === "string" ? value.workspaceId : null,
         workspaceRef: typeof value.workspaceRef === "string" ? value.workspaceRef : null,
-        workspaceCopyReceipt: (value.workspaceCopyReceipt && typeof value.workspaceCopyReceipt === "object") ? value.workspaceCopyReceipt : null,
         runtimeId: typeof value.runtimeId === "string" ? value.runtimeId : null,
         nativeSessionId: typeof value.nativeSessionId === "string" ? value.nativeSessionId : null,
         contextRevision: Number(value.contextRevision ?? 0),
@@ -434,10 +434,10 @@ export class AgentServiceSandboxClient {
         if (!activation || activation.activationId !== scope.activationId) {
             throw new Error("managed turn activation context is unavailable");
         }
-        const prepared = ensureRuntimeSessionWorkspace(scope.sessionId, this.sandboxGeneration, payload.agent_run_id);
+        const prepared = ensureRuntimeSessionWorkspace(scope.sessionId, this.sandboxGeneration, payload.agent_run_id, session.workspaceId ?? scope.sessionId);
         // ensureRuntimeSessionWorkspace creates missing paths with the closed-by-default
         // mode; re-expose only after the activation fence above has been checked.
-        exposeRuntimeSessionWorkspace(scope.sessionId, this.sandboxGeneration);
+        exposeRuntimeSessionWorkspace(scope.sessionId, this.sandboxGeneration, session.workspaceId ?? scope.sessionId);
         this.currentTurnSessionId = scope.sessionId;
         const runtimeEnv = runtimeChildEnv(process.env);
         delete runtimeEnv.DEEPSEEK_API_KEY;
@@ -536,6 +536,26 @@ export class AgentServiceSandboxClient {
             // there is no safe monotonic ordering from which to infer that an old replay died.
             session.completedActivations.push(pending.activationId);
         }
+        const cleanupFrame = createSandboxFrame({
+            type: "activation.cleaned",
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            runtimeSessionId: sessionId,
+            agentRunId: pending.agentRunId,
+            workerAttempt: pending.workerAttempt,
+            activationId: pending.activationId,
+        });
+        session.spool.push(cleanupFrame);
+        try {
+            this.enforceSpoolLimit();
+        }
+        catch (error) {
+            session.spool.pop();
+            this.persist();
+            throw error;
+        }
         const commandId = `run:${pending.agentRunId}:${pending.workerAttempt}`;
         if (!session.completedCommands.includes(commandId)) {
             session.completedCommands.push(commandId);
@@ -547,6 +567,8 @@ export class AgentServiceSandboxClient {
         if (this.currentTurnSessionId === sessionId)
             this.currentTurnSessionId = null;
         this.persist();
+        if (this.runtimeLogHandshakeReady)
+            await this.sendFrame(cleanupFrame);
     }
     async recoverPendingActivationCleanups() {
         for (const sessionId of Object.keys(this.state.sessions)) {
@@ -600,7 +622,7 @@ export class AgentServiceSandboxClient {
         this.dispatcher.cancelAll();
         for (const [sessionId, session] of Object.entries(this.state.sessions)) {
             session.activationId = null;
-            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration, session.workspaceId ?? sessionId);
         }
         this.activationContexts.clear();
         this.sessionProfiles.clear();
@@ -831,9 +853,6 @@ export class AgentServiceSandboxClient {
         }
     }
     async handleHello(frame) {
-        // A reconnect can race a copy that started on the previous socket. Wait for
-        // the serialized lifecycle attempt to converge before deleting crash-left
-        // staging and advertising capability on the new connection.
         await this.lifecycleChain;
         if (frame.sandbox_id !== this.options.sandboxId) {
             throw new SandboxClosedError(4403, "sandbox_mismatch");
@@ -846,9 +865,10 @@ export class AgentServiceSandboxClient {
             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, nasWorkspaceEnabled());
+            for (const [sessionId, session] of Object.entries(this.state.sessions)) {
+                revokeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration, session.workspaceId ?? sessionId);
+                // NAS image 跨 generation 保留正文，只清掉本地 daemon 侧的 session 状态。
+                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration, true);
             }
             this.state.sessions = {};
             this.state.sandboxGeneration = frame.sandbox_generation;
@@ -876,7 +896,6 @@ export class AgentServiceSandboxClient {
             : LEGACY_EVENT_ACK_WINDOW;
         this.maxUnackedEvents = Math.min(MAX_EVENT_ACK_WINDOW, ackWindow);
         this.runtimeLogPolicy = runtimeLogPolicy(frame.payload.runtime_log_policy);
-        await cleanupRuntimeSessionWorkspaceCopyStaging();
         this.persist();
         assertWorkspaceFilesystem(process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT ?? "");
         assertWorkspaceWriterFreezeSupported();
@@ -885,7 +904,6 @@ export class AgentServiceSandboxClient {
             capabilities: [
                 WORKSPACE_FILE_READ_BINARY_CAPABILITY,
                 ...workspaceDurabilityCapabilities(),
-                ...(workspaceCopyV1Supported() ? ["workspace_copy_v1"] : []),
             ],
             workspace_snapshot_policy: workspaceSnapshotPolicyCapability(),
             daemon_version: this.options.daemonVersion,
@@ -1065,315 +1083,54 @@ export class AgentServiceSandboxClient {
         const sessionId = frame.runtime_session_id;
         const session = this.state.sessions[sessionId] ?? emptySessionState();
         const courseRunId = frame.payload.course_run_id;
+        // Mixed-version reconciliation may replay a pre-Workspace-identity session.open.
+        // Its physical directory was keyed by RuntimeSession id, which is the exact backfill
+        // identity used by the database migration.
+        const requestedWorkspaceId = typeof frame.payload.workspace_id === "string"
+            ? frame.payload.workspace_id
+            : session.workspaceId ?? sessionId;
         const requestedWorkspaceRef = frame.payload.workspace_ref;
-        const requestedCopy = frame.payload.workspace_copy;
-        const requestedRestore = frame.payload.workspace_restore;
-        assertWorkspaceRestoreAllowed(requestedRestore);
-        const requestedCopyRecord = requestedCopy && typeof requestedCopy === "object"
-            ? requestedCopy
-            : undefined;
-        const copyId = requestedCopyRecord
-            ? requestedCopyRecord.copy_id
-            : undefined;
-        const requestedCopySource = requestedCopyRecord
-            ? requestedCopyRecord.source_runtime_session_id
-            : undefined;
+        assertWorkspaceRestoreAllowed(frame.payload.workspace_restore);
         if (typeof courseRunId !== "string" ||
             courseRunId.length < 1 ||
+            requestedWorkspaceId.length < 1 ||
             (requestedWorkspaceRef !== null &&
                 requestedWorkspaceRef !== undefined &&
-                (typeof requestedWorkspaceRef !== "string" || requestedWorkspaceRef.length < 1)) ||
-            (requestedCopy !== null &&
-                requestedCopy !== undefined &&
-                (typeof requestedCopy !== "object" ||
-                    typeof copyId !== "string" ||
-                    copyId.length < 1 ||
-                    typeof requestedCopySource !== "string" ||
-                    requestedCopySource.length < 1))
-            || (requestedRestore !== null && requestedRestore !== undefined &&
-                (typeof requestedRestore !== "object" || Array.isArray(requestedRestore)))
-            || (requestedCopy !== null && requestedCopy !== undefined &&
-                requestedRestore !== null && requestedRestore !== undefined)) {
+                (typeof requestedWorkspaceRef !== "string" || requestedWorkspaceRef.length < 1))) {
             throw new Error("invalid session.open payload");
         }
         if (session.courseRunId !== null && session.courseRunId !== courseRunId) {
             throw new Error("runtime session course_run_id cannot be rebound");
         }
+        if (session.workspaceId !== null && session.workspaceId !== requestedWorkspaceId) {
+            throw new Error("runtime session workspace_id cannot be rebound");
+        }
         if (session.workspaceRef !== null &&
             typeof requestedWorkspaceRef === "string" &&
             session.workspaceRef !== requestedWorkspaceRef) {
             throw new Error("runtime session workspace_ref cannot be rebound");
         }
         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;
-                    if (receipt.copy_id !== copyId ||
-                        receipt.source_runtime_session_id !== requestedCopySource ||
-                        receipt.target_runtime_session_id !== sessionId ||
-                        receipt.source_sandbox_id !== this.options.sandboxId ||
-                        receipt.source_generation !== this.sandboxGeneration) {
-                        throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-                    }
-                    markerPath = path.join(runtimeSessionWorkspaceDir(sessionId, this.sandboxGeneration), WORKSPACE_COPY_POLICY_V1.markerName);
-                }
-                else if (!isNewSession) {
-                    throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-                }
-            }
-            if (isNewSession && typeof requestedCopySource === "string" && typeof copyId === "string") {
-                const sourceSession = this.state.sessions[requestedCopySource];
-                if (!sourceSession ||
-                    sourceSession.courseRunId === null ||
-                    this.activeSessionId === requestedCopySource ||
-                    this.currentTurnSessionId === requestedCopySource) {
-                    throw new WorkspaceCopyError("workspace_migration_source_unavailable");
-                }
-                revokeRuntimeSessionWorkspace(requestedCopySource, this.sandboxGeneration);
-                const copied = await copyRuntimeSessionWorkspace({
-                    copyId,
-                    sourceRuntimeSessionId: requestedCopySource,
-                    targetRuntimeSessionId: sessionId,
-                    sandboxId: this.options.sandboxId,
-                    sandboxGeneration: this.sandboxGeneration,
-                });
-                session.workspaceCopyReceipt = copied.receipt;
-                markerPath = copied.markerPath;
-            }
-        }
-        catch (error) {
-            if (error instanceof WorkspaceCopyError) {
-                await this.sendSessionFrame("session.open_failed", sessionId, {
-                    error_code: error.code,
-                });
-                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.workspaceId = requestedWorkspaceId;
         session.workspaceRef = session.workspaceRef ?? (typeof requestedWorkspaceRef === "string"
             ? requestedWorkspaceRef
             : `ws_${sessionId.replaceAll("-", "")}_g${this.sandboxGeneration}`);
         // 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);
-        }
-        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;
+        if (isNewSession || session.activationId === null) {
+            ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration, requestedWorkspaceId);
         }
         this.state.sessions[sessionId] = session;
         this.persist();
-        const usesNasWorkspace = nasWorkspaceEnabled();
-        const materialization = usesNasWorkspace
-            ? null
-            : readWorkspaceMaterializationMarker(this.options.sandboxId, sessionId);
+        // NAS 是唯一的 workspace 权威来源，所以 session.opened 不携带 snapshot 物化标记：
+        // 挂载证明只说明当前 generation 已挂上 NAS，不要求运行目录等于某个 committed revision。
         await this.sendSessionFrame("session.opened", sessionId, {
+            workspace_id: session.workspaceId,
             workspace_ref: session.workspaceRef,
             native_session_id: session.nativeSessionId,
-            workspace_authority: usesNasWorkspace ? "nas" : "snapshot",
-            ...(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 }
-                : {}),
+            workspace_authority: "nas",
         });
     }
     async handleWorkspaceCheckpoint(frame) {
@@ -1393,8 +1150,6 @@ export class AgentServiceSandboxClient {
                 "sandbox_pause",
                 "sandbox_cleanup",
                 "generation_rotation",
-                "initial_migration",
-                "live_workspace_copy",
                 "maintenance_repair",
             ].includes(String(sourceKind)) ||
             !Number.isSafeInteger(baseRevision) ||
@@ -1422,7 +1177,7 @@ export class AgentServiceSandboxClient {
             await checkpointWorkspace({
                 wsUrl: this.options.wsUrl,
                 reconnectToken: controlToken,
-                workspaceDirectory: runtimeSessionWorkspaceDir(sessionId, this.sandboxGeneration),
+                workspaceDirectory: runtimeSessionWorkspaceDir(session.workspaceId ?? sessionId, this.sandboxGeneration),
                 scope: {
                     checkpointId,
                     baseRevision,
@@ -1434,17 +1189,12 @@ export class AgentServiceSandboxClient {
                 freezeProof,
             });
             checkpointCommitted = true;
-            const marker = readWorkspaceMaterializationMarker(this.options.sandboxId, sessionId);
-            if (!marker)
-                throw new Error("workspace checkpoint marker missing");
+            // committed revision 只是派生投影，不改变运行目录，所以这里不上报物化标记。
             await this.sendSessionFrame("session.opened", sessionId, {
+                workspace_id: session.workspaceId,
                 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,
+                workspace_authority: "nas",
             });
             await this.sendCommandAck(frame, "ok");
             if (!lifecycleCheckpoint)
@@ -1539,7 +1289,7 @@ export class AgentServiceSandboxClient {
             if (required.length === 0)
                 return [];
             if (!availableCapabilities) {
-                const workspace = ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration);
+                const workspace = ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration, session.workspaceId ?? sessionId);
                 availableCapabilities = new Set(availableRunCapabilities({
                     agent_run_id: "activation-probe",
                     course_run_id: session.courseRunId ?? "",
@@ -1622,7 +1372,7 @@ export class AgentServiceSandboxClient {
         session.runtimeId = runtimeId;
         session.contextRevision = contextRevision;
         session.activationId = activationId;
-        exposeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        exposeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration, session.workspaceId ?? sessionId);
         this.activationContexts.set(sessionId, {
             activationId,
             runtimeEnv,
@@ -1793,8 +1543,8 @@ export class AgentServiceSandboxClient {
         await this.finishTurn({ agent_run_id: runId });
     }
     /**
-     * 幂等关闭一个 runtime session：终止其 runtime 子进程、删除 workspace/native state、
-     * 清空本地状态分片，并回 session.closed。未知 session 直接回 closed。
+     * 幂等关闭一个 runtime session：终止其 runtime 子进程并清空 session-local state。
+     * Durable Workspace 由独立身份拥有，关闭执行上下文不会删除学员文件。
      */
     async closeSession(sessionId, reason, sourceFrame, fence) {
         const session = this.state.sessions[sessionId];
@@ -1809,7 +1559,11 @@ export class AgentServiceSandboxClient {
             }
             await this.terminateSessionWriters(session);
             session.activationId = null;
-            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+            const workspaceId = session.workspaceId ?? sessionId;
+            const sharedWorkspaceIsOpen = Object.entries(this.state.sessions).some(([otherSessionId, other]) => otherSessionId !== sessionId && (other.workspaceId ?? otherSessionId) === workspaceId);
+            if (!sharedWorkspaceIsOpen) {
+                revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration, workspaceId);
+            }
             if (fence && !this.isCurrentLifecycleFence(fence))
                 return;
             if (this.activeSessionId === sessionId)
@@ -1818,7 +1572,7 @@ export class AgentServiceSandboxClient {
                 this.currentTurnSessionId = null;
             for (const runId of runIds)
                 this.turnScopes.delete(runId);
-            removeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+            removeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration, true, workspaceId);
             delete this.state.sessions[sessionId];
             this.persist();
         }
@@ -1960,7 +1714,7 @@ export class AgentServiceSandboxClient {
         this.activationContexts.delete(sessionId);
         this.sessionProfiles.delete(sessionId);
         if (terminateWriters) {
-            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration, session.workspaceId ?? sessionId);
         }
         if (this.activeSessionId === sessionId)
             this.activeSessionId = null;
@@ -2122,7 +1876,7 @@ export class AgentServiceSandboxClient {
         }
         this.workspaceFileReadInFlight = true;
         try {
-            const result = await readWorkspaceFile(runtimeSessionWorkspaceDir(sessionId, this.sandboxGeneration), relativePath, {
+            const result = await readWorkspaceFile(runtimeSessionWorkspaceDir(this.state.sessions[sessionId]?.workspaceId ?? sessionId, this.sandboxGeneration), relativePath, {
                 maxBytes: maxBytes,
                 expectedSizeBytes: expectedSizeBytes,
                 expectedSha256,

package/dist/agent-service-ws-protocol.d.ts

@@ -3,7 +3,7 @@ export declare const AGENT_SERVICE_WS_SUBPROTOCOL: "botlearn-agent-sandbox.v4";
 export declare const WORKSPACE_FILE_READ_BINARY_CAPABILITY: "workspace_file_read_binary_v1";
 export declare const WORKSPACE_FILE_CHUNK_BYTES: number;
 export declare const WORKSPACE_FILE_CHUNK_HEADER_BYTES = 29;
-export type SandboxFrameType = "sandbox.hello" | "sandbox.sync" | "session.open" | "session.activate" | "turn.start" | "turn.cancel" | "session.close" | "sandbox.drain" | "sandbox.shutdown" | "event.ack" | "auth.rotate" | "workspace.file.read" | "workspace.checkpoint" | "workspace.thaw" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.open_failed" | "session.closed" | "turn.event" | "turn.file.report" | "workspace.file.result" | "sandbox.drained" | "sandbox.log" | "pong" | "protocol.error";
+export type SandboxFrameType = "sandbox.hello" | "sandbox.sync" | "session.open" | "session.activate" | "turn.start" | "turn.cancel" | "session.close" | "sandbox.drain" | "sandbox.shutdown" | "event.ack" | "auth.rotate" | "workspace.file.read" | "workspace.checkpoint" | "workspace.thaw" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.open_failed" | "session.closed" | "activation.cleaned" | "turn.event" | "turn.file.report" | "workspace.file.result" | "sandbox.drained" | "sandbox.log" | "pong" | "protocol.error";
 export declare class UnsupportedSandboxProtocolError extends Error {
     readonly schemaVersion: unknown;
     constructor(schemaVersion: unknown);