@botlearn-course/daemon 0.0.20-beta.13 → 0.0.20-beta.15

package/README.md

@@ -48,10 +48,10 @@ daemon，由 root-owned 固定 launcher 清空附加组后直接降权为 `user`
 课程任务或 workspace shell。
 
 veFaaS Origin 的托管 workspace 使用用户级 NAS backing image。root bootstrap 完成 NFS、marker、
-ext4、loop mount 和固定 3 GiB 校验后，daemon 才发送 `sandbox.ready`。RuntimeSession 使用稳定路径
+ext4、`fuse2fs` mount 和固定 3 GiB 校验后，daemon 才发送 `sandbox.ready`。RuntimeSession 使用稳定路径
 `/workspace/sessions/{runtime_session_id}/workspace`，Sandbox generation 只参与写入隔离。磁盘写满
 统一上报 `workspace_user_quota_exceeded`。pause 和 cleanup 进入 drain 后，daemon 先停止 runtime
-writer，再通过 root launcher 执行 ext4 sync、loop unmount、backing image 和 NFS parent fsync；完成后
+writer，再通过 root launcher 执行 ext4 sync、`fuse2fs` unmount、backing image 和 NFS parent fsync；完成后
 才发送 `sandbox.drained` 并退出。
 
 ## 支持的 runtime

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

@@ -3,6 +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(): 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;

package/dist/agent-service-sandbox.js

@@ -1,10 +1,7 @@
-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, WORKSPACE_SNAPSHOT_ATTESTATION_CAPABILITY, } from "./agent-service-ws-protocol.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";
 import { log as defaultLog, setOperationalLogSink, } from "./log.js";
 import { availableRunCapabilities, runtimeSupportsCourseSkills, } from "./runtime-capabilities.js";
 import { activationRuntimeEnv, runtimeChildEnv } from "./runtime-env.js";
@@ -16,12 +13,9 @@ import { readWorkspaceFile, WorkspaceFileReadError } from "./workspace-file-read
 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,6 +35,23 @@ 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() {
+    return [
+        "workspace_writer_freeze_v1",
+        "workspace_snapshot_v2",
+        "workspace_nas_v1",
+    ];
+}
+/**
+ * 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");
+    }
+}
 const DISABLED_RUNTIME_LOG_POLICY = {
     enabled: false,
     maxEventBytes: 4096,
@@ -836,7 +847,8 @@ export class AgentServiceSandboxClient {
             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());
+                // NAS image 跨 generation 保留正文，只清掉本地 daemon 侧的 session 状态。
+                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration, true);
             }
             this.state.sessions = {};
             this.state.sandboxGeneration = frame.sandbox_generation;
@@ -872,11 +884,7 @@ export class AgentServiceSandboxClient {
             protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
             capabilities: [
                 WORKSPACE_FILE_READ_BINARY_CAPABILITY,
-                "workspace_writer_freeze_v1",
-                "workspace_snapshot_v2",
-                "workspace_restore_v1",
-                WORKSPACE_SNAPSHOT_ATTESTATION_CAPABILITY,
-                ...(nasWorkspaceEnabled() ? ["workspace_nas_v1"] : []),
+                ...workspaceDurabilityCapabilities(),
                 ...(workspaceCopyV1Supported() ? ["workspace_copy_v1"] : []),
             ],
             workspace_snapshot_policy: workspaceSnapshotPolicyCapability(),
@@ -1059,7 +1067,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;
+        assertWorkspaceRestoreAllowed(frame.payload.workspace_restore);
         const requestedCopyRecord = requestedCopy && typeof requestedCopy === "object"
             ? requestedCopy
             : undefined;
@@ -1080,11 +1088,7 @@ export class AgentServiceSandboxClient {
                     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)) {
+                    requestedCopySource.length < 1))) {
             throw new Error("invalid session.open payload");
         }
         if (session.courseRunId !== null && session.courseRunId !== courseRunId) {
@@ -1098,165 +1102,6 @@ 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;
@@ -1300,14 +1145,6 @@ 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;
@@ -1323,41 +1160,14 @@ export class AgentServiceSandboxClient {
         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);
+        // NAS 是唯一的 workspace 权威来源，所以 session.opened 不携带 snapshot 物化标记：
+        // 挂载证明只说明当前 generation 已挂上 NAS，不要求运行目录等于某个 committed revision。
         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,
-                }
-                : {}),
+            workspace_authority: "nas",
             ...(session.workspaceCopyReceipt !== null
                 ? { workspace_copy_receipt: session.workspaceCopyReceipt }
                 : {}),
@@ -1421,17 +1231,11 @@ 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_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)

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

@@ -1,7 +1,6 @@
 export declare const AGENT_SERVICE_WS_SCHEMA: "botlearn-agent-sandbox-ws/0.4";
 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_SNAPSHOT_ATTESTATION_CAPABILITY: "workspace_snapshot_attestation_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";

package/dist/agent-service-ws-protocol.js

@@ -2,7 +2,6 @@ import { randomUUID } from "node:crypto";
 export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.4";
 export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v4";
 export const WORKSPACE_FILE_READ_BINARY_CAPABILITY = "workspace_file_read_binary_v1";
-export const WORKSPACE_SNAPSHOT_ATTESTATION_CAPABILITY = "workspace_snapshot_attestation_v1";
 export const WORKSPACE_FILE_CHUNK_BYTES = 64 * 1024;
 export const WORKSPACE_FILE_CHUNK_HEADER_BYTES = 29;
 const WORKSPACE_FILE_CHUNK_MAGIC = Buffer.from("BLWF", "ascii");

package/dist/index.d.ts

@@ -12,11 +12,9 @@ export * from "./run-dispatcher.js";
 export * from "./run-queue.js";
 export * from "./workspace.js";
 export * from "./workspace-entry-set.js";
-export * from "./workspace-materialization.js";
 export * from "./workspace-snapshot-staging.js";
 export * from "./workspace-snapshot-policy.js";
 export * from "./workspace-snapshot-control.js";
-export * from "./workspace-restore.js";
 export * from "./transcript.js";
 export * from "./file-candidates.js";
 export * from "./doctor.js";

package/dist/index.js

@@ -12,11 +12,9 @@ export * from "./run-dispatcher.js";
 export * from "./run-queue.js";
 export * from "./workspace.js";
 export * from "./workspace-entry-set.js";
-export * from "./workspace-materialization.js";
 export * from "./workspace-snapshot-staging.js";
 export * from "./workspace-snapshot-policy.js";
 export * from "./workspace-snapshot-control.js";
-export * from "./workspace-restore.js";
 export * from "./transcript.js";
 export * from "./file-candidates.js";
 export * from "./doctor.js";

package/dist/workspace-filesystem.d.ts

@@ -12,7 +12,6 @@ export interface WorkspaceCapacityProbes {
     backingFileBytes(imagePath: string): bigint;
 }
 export declare function parseWorkspaceMountInfo(text: string): MountInfoEntry[];
-export declare function nasWorkspaceEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function workspaceFilesystemFlushCommand(env?: NodeJS.ProcessEnv): [string, string[]] | null;
 export declare function flushWorkspaceFilesystem(env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function isWorkspaceQuotaExceededError(error: unknown): boolean;

package/dist/workspace-filesystem.js

@@ -1,7 +1,6 @@
 import { execFile } from "node:child_process";
 import { readFileSync, statfsSync, statSync } from "node:fs";
 import { promisify } from "node:util";
-import { assertRuntimeWorkspaceQuota } from "./workspace-quota.js";
 export const WORKSPACE_IMAGE_FORMAT = "botlearn-workspace-image/1";
 export const WORKSPACE_IMAGE_LOGICAL_BYTES = 3 * 1024 * 1024 * 1024;
 const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
@@ -35,12 +34,7 @@ export function parseWorkspaceMountInfo(text) {
         };
     });
 }
-export function nasWorkspaceEnabled(env = process.env) {
-    return env.BOTLEARN_WORKSPACE_IMAGE_FORMAT !== undefined;
-}
 export function workspaceFilesystemFlushCommand(env = process.env) {
-    if (!nasWorkspaceEnabled(env))
-        return null;
     if (env.BOTLEARN_RUNTIME_LAUNCH_MODE === "direct-uid") {
         return [RUNTIME_LAUNCHER, ["--workspace-filesystem-flush"]];
     }
@@ -82,10 +76,6 @@ export function isWorkspaceQuotaExceededError(error) {
         || (candidate.cause !== undefined && isWorkspaceQuotaExceededError(candidate.cause));
 }
 export function assertWorkspaceFilesystem(workspaceRoot, env = process.env, mountInfo, capacityProbes) {
-    if (!nasWorkspaceEnabled(env)) {
-        assertRuntimeWorkspaceQuota(workspaceRoot);
-        return;
-    }
     if (env.BOTLEARN_WORKSPACE_IMAGE_FORMAT !== WORKSPACE_IMAGE_FORMAT
         || env.BOTLEARN_WORKSPACE_LOGICAL_BYTES !== String(WORKSPACE_IMAGE_LOGICAL_BYTES)
         || !/^[0-9a-f]{64}$/u.test(env.BOTLEARN_WORKSPACE_SCOPE_DIGEST ?? "")) {

package/dist/workspace-snapshot-control.js

@@ -1,7 +1,6 @@
 import { createReadStream, rmSync } from "node:fs";
 import path from "node:path";
 import { ensureDaemonHome } from "./auth-store.js";
-import { writeWorkspaceMaterializationMarker } from "./workspace-materialization.js";
 import { WORKSPACE_SNAPSHOT_POLICY_V1 } from "./workspace-snapshot-policy.js";
 import { stageWorkspaceSnapshot } from "./workspace-snapshot-staging.js";
 export class WorkspaceSnapshotControlError extends Error {
@@ -95,19 +94,6 @@ export async function checkpointWorkspace(options) {
             entry_set: entrySet,
         }, signal);
         if (proposal.unchanged) {
-            if (proposal.revision === 0 && proposal.snapshot_id === null) {
-                writeWorkspaceMaterializationMarker({
-                    schemaVersion: "agent-workspace-materialization/1",
-                    sandboxId: scope.sandboxId,
-                    sandboxGeneration: scope.sandboxGeneration,
-                    runtimeSessionId: scope.runtimeSessionId,
-                    workspaceContinuityState: "healthy",
-                    snapshotId: null,
-                    revision: 0,
-                    contentSha256: null,
-                    writtenAt: new Date().toISOString(),
-                });
-            }
             return {
                 revision: proposal.revision,
                 snapshotId: proposal.snapshot_id,
@@ -146,17 +132,6 @@ export async function checkpointWorkspace(options) {
             committed.content_sha256 === null) {
             throw new WorkspaceSnapshotControlError(committed.error_code || "workspace_snapshot_verification_failed", false);
         }
-        writeWorkspaceMaterializationMarker({
-            schemaVersion: "agent-workspace-materialization/1",
-            sandboxId: scope.sandboxId,
-            sandboxGeneration: scope.sandboxGeneration,
-            runtimeSessionId: scope.runtimeSessionId,
-            workspaceContinuityState: "healthy",
-            snapshotId: committed.snapshot_id,
-            revision: committed.revision,
-            contentSha256: committed.content_sha256,
-            writtenAt: new Date().toISOString(),
-        });
         return {
             revision: committed.revision,
             snapshotId: committed.snapshot_id,

package/dist/workspace-snapshot-policy.d.ts

@@ -20,5 +20,5 @@ export declare const WORKSPACE_SNAPSHOT_POLICY_V1: {
     readonly checkpointReservationBytes: number;
     readonly restorePageEntries: 25;
 };
-/** Wire representation validated exactly by Agent Service during the v0.3 handshake. */
+/** Wire representation validated exactly by Agent Service during the handshake. */
 export declare function workspaceSnapshotPolicyCapability(): Record<string, unknown>;

package/dist/workspace-snapshot-policy.js

@@ -1,4 +1,6 @@
-import { RUNTIME_WORKSPACE_INODE_QUOTA, RUNTIME_WORKSPACE_QUOTA_BYTES, } from "./workspace-quota.js";
+/** runtime 目录配额；与 Course Service 的 WorkspaceSnapshotPolicyV1 逐字段一致。 */
+const RUNTIME_WORKSPACE_QUOTA_BYTES = 512 * 1024 * 1024;
+const RUNTIME_WORKSPACE_INODE_QUOTA = 2_000;
 /**
  * Protocol limits frozen with Course Service's WorkspaceSnapshotPolicyV1.
  * Deployment may enable the capability, but must never override these values.
@@ -21,7 +23,7 @@ export const WORKSPACE_SNAPSHOT_POLICY_V1 = {
     checkpointReservationBytes: 512 * 1024 * 1024,
     restorePageEntries: 25,
 };
-/** Wire representation validated exactly by Agent Service during the v0.3 handshake. */
+/** Wire representation validated exactly by Agent Service during the handshake. */
 export function workspaceSnapshotPolicyCapability() {
     return {
         policy_id: WORKSPACE_SNAPSHOT_POLICY_V1.policyId,

package/dist/workspace.d.ts

@@ -20,9 +20,9 @@ export declare function runtimeProfileDir(agentRunId: string): string;
 export declare function runtimeProfileRunRootDir(agentRunId: string): string;
 export declare function runtimeSessionRootDir(runtimeSessionId: string, sandboxGeneration: number): string;
 /**
- * per-session workspace（ADR-015 §7）：NAS managed sandbox 使用稳定路径
- * `<root>/sessions/<runtime_session_id>/workspace`；旧 provider 保留 generation 路径。
- * 两种路径都由 daemon 在 session.open 时创建。
+ * per-session workspace（ADR-015 §7）：managed sandbox 使用稳定路径
+ * `<root>/sessions/<runtime_session_id>/workspace`。该路径不含 generation，
+ * 因为 NAS image 跨 generation 重新挂载后必须解析到同一个目录。
  */
 export declare function runtimeSessionWorkspaceDir(runtimeSessionId: string, sandboxGeneration: number): string;
 export declare function runtimeSessionTranscriptPath(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): string;

package/dist/workspace.js

@@ -4,7 +4,6 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { TextDecoder } from "node:util";
 import { daemonHome } from "./auth-store.js";
-import { nasWorkspaceEnabled } from "./workspace-filesystem.js";
 /**
  * 每 run 隔离工作区（spec §4）：
  *
@@ -54,9 +53,9 @@ export function runtimeSessionRootDir(runtimeSessionId, sandboxGeneration) {
     return path.join(daemonHome(), "agent-service-sessions", runtimeSessionId, `generation-${sandboxGeneration}`);
 }
 /**
- * per-session workspace（ADR-015 §7）：NAS managed sandbox 使用稳定路径
- * `<root>/sessions/<runtime_session_id>/workspace`；旧 provider 保留 generation 路径。
- * 两种路径都由 daemon 在 session.open 时创建。
+ * per-session workspace（ADR-015 §7）：managed sandbox 使用稳定路径
+ * `<root>/sessions/<runtime_session_id>/workspace`。该路径不含 generation，
+ * 因为 NAS image 跨 generation 重新挂载后必须解析到同一个目录。
  */
 export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration) {
     assertSafeId(runtimeSessionId, "runtime_session_id");
@@ -65,10 +64,7 @@ export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration)
     }
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
-        if (nasWorkspaceEnabled()) {
-            return path.join(managedRoot, "sessions", runtimeSessionId, "workspace");
-        }
-        return path.join(managedRoot, runtimeSessionId, `generation-${sandboxGeneration}`);
+        return path.join(managedRoot, "sessions", runtimeSessionId, "workspace");
     }
     return path.join(runtimeSessionRootDir(runtimeSessionId, sandboxGeneration), "workspace");
 }
@@ -77,9 +73,7 @@ function managedRuntimeSessionParentDir(runtimeSessionId) {
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (!managedRoot)
         return null;
-    return nasWorkspaceEnabled()
-        ? path.join(managedRoot, "sessions", runtimeSessionId)
-        : path.join(managedRoot, runtimeSessionId);
+    return path.join(managedRoot, "sessions", runtimeSessionId);
 }
 export function runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId) {
     assertSafeId(agentRunId, "agent_run_id");
@@ -218,8 +212,7 @@ export function workspaceCopyV1Supported() {
 }
 const COPY_STAGING_SUFFIX = "[A-Za-z0-9][A-Za-z0-9_-]{0,127}-[0-9a-f]{8}-[0-9a-f]{4}-" +
     "[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
-const MANAGED_COPY_STAGING_PATTERN = new RegExp(`^generation-[1-9][0-9]*\\.workspace-copy-${COPY_STAGING_SUFFIX}$`);
-const LOCAL_COPY_STAGING_PATTERN = new RegExp(`^workspace\\.workspace-copy-${COPY_STAGING_SUFFIX}$`);
+const COPY_STAGING_PATTERN = new RegExp(`^workspace\\.workspace-copy-${COPY_STAGING_SUFFIX}$`);
 async function childDirectories(root) {
     try {
         return (await fs.readdir(root, { withFileTypes: true }))
@@ -236,16 +229,13 @@ async function childDirectories(root) {
 export async function cleanupRuntimeSessionWorkspaceCopyStaging() {
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
-        const sessionRoot = nasWorkspaceEnabled()
-            ? path.join(managedRoot, "sessions")
-            : managedRoot;
+        const sessionRoot = path.join(managedRoot, "sessions");
         for (const sessionName of await childDirectories(sessionRoot)) {
             if (!SAFE_ID_PATTERN.test(sessionName))
                 continue;
             const sessionParent = path.join(sessionRoot, sessionName);
             for (const name of await childDirectories(sessionParent)) {
-                if (MANAGED_COPY_STAGING_PATTERN.test(name)
-                    || LOCAL_COPY_STAGING_PATTERN.test(name)) {
+                if (COPY_STAGING_PATTERN.test(name)) {
                     await fs.rm(path.join(sessionParent, name), { recursive: true, force: true });
                 }
             }
@@ -261,7 +251,7 @@ export async function cleanupRuntimeSessionWorkspaceCopyStaging() {
                 continue;
             const generationParent = path.join(sessionParent, generationName);
             for (const name of await childDirectories(generationParent)) {
-                if (LOCAL_COPY_STAGING_PATTERN.test(name)) {
+                if (COPY_STAGING_PATTERN.test(name)) {
                     await fs.rm(path.join(generationParent, name), { recursive: true, force: true });
                 }
             }
@@ -721,9 +711,7 @@ export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneratio
     });
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot && !preserveManagedWorkspace) {
-        const sessionRoot = nasWorkspaceEnabled()
-            ? path.join(managedRoot, "sessions", runtimeSessionId)
-            : path.join(managedRoot, runtimeSessionId);
+        const sessionRoot = path.join(managedRoot, "sessions", runtimeSessionId);
         rmSync(sessionRoot, { recursive: true, force: true });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botlearn-course/daemon",
-  "version": "0.0.20-beta.13",
+  "version": "0.0.20-beta.15",
   "description": "Lightweight BotLearn Course daemon: run course tasks on your own machine with your own agent runtime (BYOA).",
   "type": "module",
   "bin": {

package/dist/workspace-materialization.d.ts

@@ -1,16 +0,0 @@
-export declare const WORKSPACE_MATERIALIZATION_SCHEMA: "agent-workspace-materialization/1";
-export interface WorkspaceMaterializationMarker {
-    schemaVersion: typeof WORKSPACE_MATERIALIZATION_SCHEMA;
-    sandboxId: string;
-    sandboxGeneration: number;
-    runtimeSessionId: string;
-    workspaceContinuityState: "healthy" | "degraded";
-    snapshotId: string | null;
-    revision: number;
-    contentSha256: string | null;
-    writtenAt: string;
-}
-export declare function workspaceMaterializationMarkerPath(sandboxId: string, runtimeSessionId: string): string;
-export declare function writeWorkspaceMaterializationMarker(marker: WorkspaceMaterializationMarker): void;
-export declare function readWorkspaceMaterializationMarker(sandboxId: string, runtimeSessionId: string): WorkspaceMaterializationMarker | null;
-export declare function removeWorkspaceMaterializationMarker(sandboxId: string, runtimeSessionId: string): boolean;

package/dist/workspace-materialization.js

@@ -1,136 +0,0 @@
-import { randomBytes } from "node:crypto";
-import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
-import path from "node:path";
-import { ensureDaemonHome } from "./auth-store.js";
-export const WORKSPACE_MATERIALIZATION_SCHEMA = "agent-workspace-materialization/1";
-const UUID = /^[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 SHA256 = /^[0-9a-f]{64}$/;
-function assertUuid(value, label) {
-    if (!UUID.test(value))
-        throw new Error(label + " must be a UUID");
-}
-function markerDirectory(sandboxId) {
-    assertUuid(sandboxId, "sandboxId");
-    return path.join(ensureDaemonHome(), "agent-service-sandboxes", sandboxId, "workspace-materializations");
-}
-export function workspaceMaterializationMarkerPath(sandboxId, runtimeSessionId) {
-    assertUuid(runtimeSessionId, "runtimeSessionId");
-    return path.join(markerDirectory(sandboxId), runtimeSessionId + ".json");
-}
-function validateMarker(raw) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error("workspace materialization marker must be an object");
-    }
-    const marker = raw;
-    const expectedKeys = [
-        "schemaVersion",
-        "sandboxId",
-        "sandboxGeneration",
-        "runtimeSessionId",
-        "workspaceContinuityState",
-        "snapshotId",
-        "revision",
-        "contentSha256",
-        "writtenAt",
-    ].sort();
-    if (Object.keys(marker).sort().some((key, index) => key !== expectedKeys[index]) ||
-        Object.keys(marker).length !== expectedKeys.length)
-        throw new Error("workspace materialization marker fields are invalid");
-    if (marker.schemaVersion !== WORKSPACE_MATERIALIZATION_SCHEMA) {
-        throw new Error("workspace materialization marker schema is unsupported");
-    }
-    if (typeof marker.sandboxId !== "string")
-        throw new Error("sandboxId is required");
-    if (typeof marker.runtimeSessionId !== "string") {
-        throw new Error("runtimeSessionId is required");
-    }
-    assertUuid(marker.sandboxId, "sandboxId");
-    assertUuid(marker.runtimeSessionId, "runtimeSessionId");
-    if (!Number.isSafeInteger(marker.sandboxGeneration) ||
-        marker.sandboxGeneration < 1 ||
-        !Number.isSafeInteger(marker.revision) ||
-        marker.revision < 0 ||
-        typeof marker.writtenAt !== "string" ||
-        Number.isNaN(Date.parse(marker.writtenAt)))
-        throw new Error("workspace materialization marker values are invalid");
-    if (marker.workspaceContinuityState !== "healthy" &&
-        marker.workspaceContinuityState !== "degraded")
-        throw new Error("workspace materialization continuity is invalid");
-    if (marker.snapshotId !== null) {
-        if (typeof marker.snapshotId !== "string")
-            throw new Error("snapshotId is invalid");
-        assertUuid(marker.snapshotId, "snapshotId");
-    }
-    const revisionZero = marker.revision === 0;
-    if (revisionZero !== (marker.snapshotId === null) ||
-        revisionZero !== (marker.contentSha256 === null) ||
-        (!revisionZero &&
-            (typeof marker.contentSha256 !== "string" || !SHA256.test(marker.contentSha256)))) {
-        throw new Error("workspace materialization marker pointer is inconsistent");
-    }
-    return marker;
-}
-export function writeWorkspaceMaterializationMarker(marker) {
-    validateMarker(marker);
-    const directory = markerDirectory(marker.sandboxId);
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    try {
-        chmodSync(directory, 0o700);
-    }
-    catch {
-        // Windows best effort.
-    }
-    const target = workspaceMaterializationMarkerPath(marker.sandboxId, marker.runtimeSessionId);
-    const staging = target + ".tmp-" + process.pid + "-" + randomBytes(4).toString("hex");
-    try {
-        writeFileSync(staging, JSON.stringify(marker), { encoding: "utf8", mode: 0o600 });
-        const file = openSync(staging, "r");
-        try {
-            fsyncSync(file);
-        }
-        finally {
-            closeSync(file);
-        }
-        renameSync(staging, target);
-        try {
-            chmodSync(target, 0o600);
-        }
-        catch {
-            // Windows best effort.
-        }
-        try {
-            const parent = openSync(directory, "r");
-            try {
-                fsyncSync(parent);
-            }
-            finally {
-                closeSync(parent);
-            }
-        }
-        catch {
-            // Some platforms cannot fsync a directory.
-        }
-    }
-    catch (error) {
-        try {
-            unlinkSync(staging);
-        }
-        catch {
-            // Staging may not have been created.
-        }
-        throw error;
-    }
-}
-export function readWorkspaceMaterializationMarker(sandboxId, runtimeSessionId) {
-    const file = workspaceMaterializationMarkerPath(sandboxId, runtimeSessionId);
-    if (!existsSync(file))
-        return null;
-    return validateMarker(JSON.parse(readFileSync(file, "utf8")));
-}
-export function removeWorkspaceMaterializationMarker(sandboxId, runtimeSessionId) {
-    const file = workspaceMaterializationMarkerPath(sandboxId, runtimeSessionId);
-    if (!existsSync(file))
-        return false;
-    unlinkSync(file);
-    return true;
-}

package/dist/workspace-quota.d.ts

@@ -1,4 +0,0 @@
-export declare const RUNTIME_WORKSPACE_QUOTA_BYTES: number;
-export declare const RUNTIME_WORKSPACE_INODE_QUOTA = 2000;
-export declare function assertRuntimeWorkspaceQuota(workspaceRoot: string): void;
-export declare function applyRuntimeWorkspaceQuota(runtimeSessionId: string, sandboxGeneration: number): Promise<void>;

package/dist/workspace-quota.js

@@ -1,42 +0,0 @@
-import { execFile } from "node:child_process";
-import { readFileSync, statfsSync, statSync } from "node:fs";
-import { promisify } from "node:util";
-export const RUNTIME_WORKSPACE_QUOTA_BYTES = 512 * 1024 * 1024;
-export const RUNTIME_WORKSPACE_INODE_QUOTA = 2_000;
-const WORKSPACE_BACKING_BYTES = 3 * 1024 * 1024 * 1024;
-const QUOTA_MARKER = "/var/lib/botlearn-runtime/workspace-quota.ready";
-const RUNTIME_LAUNCHER = "/opt/botlearn/bin/botlearn-runtime-launcher";
-const execFileAsync = promisify(execFile);
-export function assertRuntimeWorkspaceQuota(workspaceRoot) {
-    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
-        return;
-    }
-    if (process.env.BOTLEARN_RUNTIME_WORKSPACE_QUOTA_BYTES !== String(RUNTIME_WORKSPACE_QUOTA_BYTES) ||
-        process.env.BOTLEARN_RUNTIME_WORKSPACE_INODE_QUOTA !== String(RUNTIME_WORKSPACE_INODE_QUOTA)) {
-        throw new Error("workspace_runtime_quota_unverified");
-    }
-    const filesystem = statfsSync(workspaceRoot, { bigint: true });
-    const marker = statSync(QUOTA_MARKER);
-    if (filesystem.blocks * filesystem.bsize < BigInt(WORKSPACE_BACKING_BYTES) ||
-        marker.uid !== 0 || (marker.mode & 0o777) !== 0o600 ||
-        readFileSync(QUOTA_MARKER, "utf8") !== "workspace-filesystem-quota/1\n") {
-        throw new Error("workspace_runtime_quota_probe_failed");
-    }
-}
-export async function applyRuntimeWorkspaceQuota(runtimeSessionId, sandboxGeneration) {
-    if (process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1" || process.env.NODE_ENV === "test") {
-        return;
-    }
-    const args = ["--workspace-quota-apply", runtimeSessionId, String(sandboxGeneration)];
-    if (process.env.BOTLEARN_RUNTIME_LAUNCH_MODE === "sudo") {
-        await execFileAsync("/usr/bin/sudo", ["-n", "--", RUNTIME_LAUNCHER, ...args], {
-            timeout: 10_000,
-        });
-        return;
-    }
-    if (process.env.BOTLEARN_RUNTIME_LAUNCH_MODE === "direct-uid") {
-        await execFileAsync(RUNTIME_LAUNCHER, args, { timeout: 10_000 });
-        return;
-    }
-    throw new Error("workspace_runtime_quota_helper_unavailable");
-}

package/dist/workspace-restore.d.ts

@@ -1,42 +0,0 @@
-import { type WorkspaceEntry, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
-export declare class WorkspaceRestoreError extends Error {
-    readonly code: string;
-    readonly retryable: boolean;
-    constructor(code: string, retryable?: boolean);
-}
-export interface WorkspaceRestoreDescriptor {
-    sandboxId: string;
-    sandboxGeneration: number;
-    runtimeSessionId: string;
-    continuityState: "healthy" | "degraded";
-    continuityErrorCode: string | null;
-    snapshotId: string | null;
-    revision: number;
-    contentSha256: string | null;
-    expectedFileCount: number;
-    expectedEntryCount: number;
-    expectedTotalBytes: number;
-}
-export interface WorkspaceRestoreOptions {
-    workspaceDirectory: string;
-    controlDirectory: string;
-    descriptor: WorkspaceRestoreDescriptor;
-    entrySet: unknown;
-    limits: WorkspaceEntrySetLimits;
-    requiredFreeBytes: number;
-    downloadFile(entry: WorkspaceEntry, partPath: string): Promise<void>;
-}
-export interface WorkspaceRestoreCapacityOptions {
-    workspaceDirectory: string;
-    descriptor: WorkspaceRestoreDescriptor;
-    requiredFreeBytes: number;
-    entryCopies?: 1 | 2;
-}
-export declare function workspaceRestoreJournalPath(controlDirectory: string, runtimeSessionId: string): string;
-export declare function recoverWorkspaceRestoreSwap(options: {
-    workspaceDirectory: string;
-    controlDirectory: string;
-    descriptor: WorkspaceRestoreDescriptor;
-}): boolean;
-export declare function restoreWorkspaceSnapshot(options: WorkspaceRestoreOptions): Promise<void>;
-export declare function assertWorkspaceRestoreCapacity(options: WorkspaceRestoreCapacityOptions): void;

package/dist/workspace-restore.js

@@ -1,347 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statfsSync, unlinkSync, writeFileSync, } from "node:fs";
-import path from "node:path";
-import { validateWorkspaceEntrySet, } from "./workspace-entry-set.js";
-import { WORKSPACE_MATERIALIZATION_SCHEMA, writeWorkspaceMaterializationMarker, } from "./workspace-materialization.js";
-const UUID = /^[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 SHA256 = /^[0-9a-f]{64}$/;
-const RESTORE_JOURNAL_SCHEMA = "agent-workspace-restore-journal/1";
-const COPY_CHUNK_BYTES = 64 * 1024;
-export class WorkspaceRestoreError extends Error {
-    code;
-    retryable;
-    constructor(code, retryable = false) {
-        super(code);
-        this.code = code;
-        this.retryable = retryable;
-        this.name = "WorkspaceRestoreError";
-    }
-}
-function fail(code) {
-    throw new WorkspaceRestoreError(code, code === "workspace_restore_unavailable" ||
-        code === "workspace_restore_disk_pressure" ||
-        code === "workspace_restore_inode_pressure");
-}
-function assertUuid(value, label) {
-    if (!UUID.test(value))
-        fail(`workspace_restore_${label}_invalid`);
-}
-function hasExactKeys(value, expected) {
-    const actual = Object.keys(value).sort();
-    const sortedExpected = [...expected].sort();
-    return actual.length === sortedExpected.length &&
-        actual.every((key, index) => key === sortedExpected[index]);
-}
-function containsPath(parent, candidate) {
-    const relative = path.relative(parent, candidate);
-    return relative === "" || (!relative.startsWith(".." + path.sep) && relative !== "..");
-}
-function validJournalSwapName(value, prefix) {
-    return typeof value === "string" && value.startsWith(prefix) &&
-        UUID.test(value.slice(prefix.length));
-}
-function assertControlPath(workspaceDirectory, controlDirectory) {
-    if (containsPath(path.resolve(workspaceDirectory), path.resolve(controlDirectory))) {
-        fail("workspace_restore_control_path_invalid");
-    }
-}
-function assertDescriptor(descriptor) {
-    assertUuid(descriptor.sandboxId, "sandbox_id");
-    assertUuid(descriptor.runtimeSessionId, "session_id");
-    if (!Number.isSafeInteger(descriptor.sandboxGeneration) ||
-        descriptor.sandboxGeneration < 1 ||
-        !Number.isSafeInteger(descriptor.revision) ||
-        descriptor.revision < 0 ||
-        !Number.isSafeInteger(descriptor.expectedFileCount) ||
-        descriptor.expectedFileCount < 0 ||
-        !Number.isSafeInteger(descriptor.expectedEntryCount) ||
-        descriptor.expectedEntryCount < 0 ||
-        !Number.isSafeInteger(descriptor.expectedTotalBytes) ||
-        descriptor.expectedTotalBytes < 0 ||
-        (descriptor.continuityState !== "healthy" && descriptor.continuityState !== "degraded") ||
-        (descriptor.continuityState === "degraded" && !descriptor.continuityErrorCode) ||
-        (descriptor.continuityState === "healthy" && descriptor.continuityErrorCode !== null))
-        fail("workspace_restore_descriptor_invalid");
-    const revisionZero = descriptor.revision === 0;
-    if (revisionZero !== (descriptor.snapshotId === null) ||
-        revisionZero !== (descriptor.contentSha256 === null) ||
-        (!revisionZero &&
-            (!UUID.test(descriptor.snapshotId) || !SHA256.test(descriptor.contentSha256))) ||
-        (revisionZero &&
-            (descriptor.expectedFileCount !== 0 || descriptor.expectedEntryCount !== 0 ||
-                descriptor.expectedTotalBytes !== 0)))
-        fail("workspace_restore_descriptor_invalid");
-}
-export function workspaceRestoreJournalPath(controlDirectory, runtimeSessionId) {
-    assertUuid(runtimeSessionId, "session_id");
-    return path.join(controlDirectory, "workspace-restore-journals", `${runtimeSessionId}.json`);
-}
-function writeJournal(file, journal) {
-    const directory = path.dirname(file);
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    chmodSync(directory, 0o700);
-    const staging = `${file}.tmp-${process.pid}-${randomUUID()}`;
-    try {
-        writeFileSync(staging, JSON.stringify(journal), { encoding: "utf8", mode: 0o600 });
-        const handle = openSync(staging, constants.O_RDONLY | constants.O_NOFOLLOW);
-        try {
-            fsyncSync(handle);
-        }
-        finally {
-            closeSync(handle);
-        }
-        renameSync(staging, file);
-        fsyncDirectory(directory);
-    }
-    catch (error) {
-        try {
-            unlinkSync(staging);
-        }
-        catch {
-            // The atomic staging file may not have been created.
-        }
-        throw error;
-    }
-}
-function parseJournal(raw, descriptor) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        fail("workspace_restore_journal_invalid");
-    }
-    const value = raw;
-    if (!hasExactKeys(value, [
-        "schemaVersion",
-        "sandboxId",
-        "sandboxGeneration",
-        "runtimeSessionId",
-        "stagingName",
-        "backupName",
-        "hadWorkspace",
-        "phase",
-        "marker",
-    ]))
-        fail("workspace_restore_journal_invalid");
-    const namePrefix = `.botlearn-restore-${descriptor.runtimeSessionId}-`;
-    const backupPrefix = `.botlearn-backup-${descriptor.runtimeSessionId}-`;
-    if (value.schemaVersion !== RESTORE_JOURNAL_SCHEMA ||
-        value.sandboxId !== descriptor.sandboxId ||
-        value.sandboxGeneration !== descriptor.sandboxGeneration ||
-        value.runtimeSessionId !== descriptor.runtimeSessionId ||
-        !validJournalSwapName(value.stagingName, namePrefix) ||
-        !validJournalSwapName(value.backupName, backupPrefix) ||
-        typeof value.hadWorkspace !== "boolean" ||
-        !["prepared", "old_moved", "new_moved"].includes(String(value.phase)))
-        fail("workspace_restore_journal_invalid");
-    const marker = value.marker;
-    if (!marker || marker.schemaVersion !== WORKSPACE_MATERIALIZATION_SCHEMA ||
-        marker.sandboxId !== descriptor.sandboxId ||
-        marker.sandboxGeneration !== descriptor.sandboxGeneration ||
-        marker.runtimeSessionId !== descriptor.runtimeSessionId ||
-        marker.workspaceContinuityState !== descriptor.continuityState ||
-        marker.snapshotId !== descriptor.snapshotId || marker.revision !== descriptor.revision ||
-        marker.contentSha256 !== descriptor.contentSha256)
-        fail("workspace_restore_journal_invalid");
-    return value;
-}
-function fsyncDirectory(directory) {
-    const handle = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
-    try {
-        fsyncSync(handle);
-    }
-    finally {
-        closeSync(handle);
-    }
-}
-function verifyDownloadedFile(file, expected) {
-    const handle = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
-    try {
-        const stats = fstatSync(handle, { bigint: true });
-        if (!stats.isFile() || stats.nlink !== 1n || stats.size !== BigInt(expected.expectedSize)) {
-            fail("workspace_restore_integrity_failed");
-        }
-        const hash = createHash("sha256");
-        const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
-        let total = 0;
-        while (true) {
-            const bytesRead = readSync(handle, buffer, 0, buffer.length, null);
-            if (bytesRead === 0)
-                break;
-            total += bytesRead;
-            hash.update(buffer.subarray(0, bytesRead));
-        }
-        if (total !== expected.expectedSize || hash.digest("hex") !== expected.expectedSha256) {
-            fail("workspace_restore_integrity_failed");
-        }
-        fsyncSync(handle);
-    }
-    finally {
-        closeSync(handle);
-    }
-}
-function markerFromDescriptor(descriptor) {
-    return {
-        schemaVersion: WORKSPACE_MATERIALIZATION_SCHEMA,
-        sandboxId: descriptor.sandboxId,
-        sandboxGeneration: descriptor.sandboxGeneration,
-        runtimeSessionId: descriptor.runtimeSessionId,
-        workspaceContinuityState: descriptor.continuityState,
-        snapshotId: descriptor.snapshotId,
-        revision: descriptor.revision,
-        contentSha256: descriptor.contentSha256,
-        writtenAt: new Date().toISOString(),
-    };
-}
-export function recoverWorkspaceRestoreSwap(options) {
-    assertDescriptor(options.descriptor);
-    assertControlPath(options.workspaceDirectory, options.controlDirectory);
-    const journalFile = workspaceRestoreJournalPath(options.controlDirectory, options.descriptor.runtimeSessionId);
-    if (!existsSync(journalFile))
-        return false;
-    const journal = parseJournal(JSON.parse(readFileSync(journalFile, "utf8")), options.descriptor);
-    const parent = path.dirname(options.workspaceDirectory);
-    const staging = path.join(parent, journal.stagingName);
-    const backup = path.join(parent, journal.backupName);
-    const workspaceExists = existsSync(options.workspaceDirectory);
-    const stagingExists = existsSync(staging);
-    const backupExists = existsSync(backup);
-    if (journal.phase === "new_moved" ||
-        (journal.phase === "old_moved" && workspaceExists && !stagingExists)) {
-        if (!workspaceExists)
-            fail("workspace_restore_journal_invalid");
-        writeWorkspaceMaterializationMarker(journal.marker);
-        if (backupExists)
-            rmSync(backup, { recursive: true, force: true });
-        unlinkSync(journalFile);
-        fsyncDirectory(path.dirname(journalFile));
-        fsyncDirectory(parent);
-        return true;
-    }
-    if (!stagingExists)
-        fail("workspace_restore_journal_invalid");
-    if (!workspaceExists && backupExists)
-        renameSync(backup, options.workspaceDirectory);
-    else if (!workspaceExists && journal.hadWorkspace)
-        fail("workspace_restore_journal_invalid");
-    else if (workspaceExists && backupExists)
-        fail("workspace_restore_journal_invalid");
-    rmSync(staging, { recursive: true, force: true });
-    unlinkSync(journalFile);
-    fsyncDirectory(path.dirname(journalFile));
-    fsyncDirectory(parent);
-    return true;
-}
-export async function restoreWorkspaceSnapshot(options) {
-    const descriptor = options.descriptor;
-    assertDescriptor(descriptor);
-    assertControlPath(options.workspaceDirectory, options.controlDirectory);
-    assertWorkspaceRestoreCapacity(options);
-    recoverWorkspaceRestoreSwap({
-        workspaceDirectory: options.workspaceDirectory,
-        controlDirectory: options.controlDirectory,
-        descriptor,
-    });
-    const canonical = validateWorkspaceEntrySet(options.entrySet, options.limits);
-    if (canonical.entries.length !== descriptor.expectedEntryCount ||
-        canonical.fileCount !== descriptor.expectedFileCount ||
-        canonical.totalBytes !== descriptor.expectedTotalBytes ||
-        (descriptor.revision > 0 && canonical.contentSha256 !== descriptor.contentSha256))
-        fail("workspace_restore_integrity_failed");
-    const parent = path.dirname(options.workspaceDirectory);
-    const nonce = randomUUID();
-    const stagingName = `.botlearn-restore-${descriptor.runtimeSessionId}-${nonce}`;
-    const backupName = `.botlearn-backup-${descriptor.runtimeSessionId}-${nonce}`;
-    const staging = path.join(parent, stagingName);
-    const backup = path.join(parent, backupName);
-    mkdirSync(staging, { mode: 0o700 });
-    chmodSync(staging, 0o700);
-    let journalWritten = false;
-    try {
-        for (const entry of canonical.entries) {
-            const destination = path.join(staging, ...entry.path.split("/"));
-            if (entry.type === "directory") {
-                mkdirSync(destination, { recursive: true, mode: 0o700 });
-                chmodSync(destination, 0o700);
-                continue;
-            }
-            mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
-            const part = `${destination}.part`;
-            await options.downloadFile(entry, part);
-            verifyDownloadedFile(part, {
-                expectedSize: entry.sizeBytes,
-                expectedSha256: entry.sha256,
-            });
-            chmodSync(part, entry.mode === "0700" ? 0o700 : 0o600);
-            renameSync(part, destination);
-        }
-        const directories = new Set([staging]);
-        for (const entry of canonical.entries) {
-            let directory = entry.type === "directory"
-                ? path.join(staging, ...entry.path.split("/"))
-                : path.dirname(path.join(staging, ...entry.path.split("/")));
-            while (directory.startsWith(staging)) {
-                directories.add(directory);
-                if (directory === staging)
-                    break;
-                directory = path.dirname(directory);
-            }
-        }
-        for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
-            fsyncDirectory(directory);
-        }
-        const journalFile = workspaceRestoreJournalPath(options.controlDirectory, descriptor.runtimeSessionId);
-        const journal = {
-            schemaVersion: RESTORE_JOURNAL_SCHEMA,
-            sandboxId: descriptor.sandboxId,
-            sandboxGeneration: descriptor.sandboxGeneration,
-            runtimeSessionId: descriptor.runtimeSessionId,
-            stagingName,
-            backupName,
-            hadWorkspace: existsSync(options.workspaceDirectory),
-            phase: "prepared",
-            marker: markerFromDescriptor(descriptor),
-        };
-        writeJournal(journalFile, journal);
-        journalWritten = true;
-        if (journal.hadWorkspace)
-            renameSync(options.workspaceDirectory, backup);
-        journal.phase = "old_moved";
-        writeJournal(journalFile, journal);
-        renameSync(staging, options.workspaceDirectory);
-        fsyncDirectory(parent);
-        journal.phase = "new_moved";
-        writeJournal(journalFile, journal);
-        writeWorkspaceMaterializationMarker(journal.marker);
-        if (journal.hadWorkspace)
-            rmSync(backup, { recursive: true, force: true });
-        unlinkSync(journalFile);
-        fsyncDirectory(path.dirname(journalFile));
-        fsyncDirectory(parent);
-    }
-    catch (error) {
-        if (!journalWritten)
-            rmSync(staging, { recursive: true, force: true });
-        throw error;
-    }
-}
-export function assertWorkspaceRestoreCapacity(options) {
-    const { descriptor } = options;
-    assertDescriptor(descriptor);
-    if (!Number.isSafeInteger(options.requiredFreeBytes) ||
-        options.requiredFreeBytes < descriptor.expectedTotalBytes)
-        fail("workspace_restore_reservation_invalid");
-    const parent = path.dirname(options.workspaceDirectory);
-    mkdirSync(parent, { recursive: true, mode: 0o700 });
-    if (existsSync(options.workspaceDirectory)) {
-        const current = lstatSync(options.workspaceDirectory, { bigint: true });
-        if (!current.isDirectory() || current.isSymbolicLink()) {
-            fail("workspace_restore_existing_workspace_invalid");
-        }
-    }
-    const filesystem = statfsSync(parent, { bigint: true });
-    if (filesystem.bavail * filesystem.bsize < BigInt(options.requiredFreeBytes)) {
-        fail("workspace_restore_disk_pressure");
-    }
-    const entryCopies = options.entryCopies ?? 1;
-    if (filesystem.ffree < BigInt(descriptor.expectedEntryCount * entryCopies + 16)) {
-        fail("workspace_restore_inode_pressure");
-    }
-}