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

package/dist/workspace-snapshot-staging.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, } from "node:fs";
+import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, } from "node:fs";
 import path from "node:path";
+import { isWorkspaceWriterFreezeProof, } from "./runtime-quiescence.js";
 import { defaultCaseFold, validateWorkspaceEntrySet, WORKSPACE_ENTRY_SET_SCHEMA, } from "./workspace-entry-set.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 EXCLUDED_NAMES = new Set(["node_modules"]);
@@ -107,30 +108,52 @@ function fsyncDirectory(directory) {
         closeSync(handle);
     }
 }
+function descriptorPath(handle, fallback) {
+    if (existsSync("/proc/self/fd")) {
+        const value = path.join("/proc/self/fd", String(handle));
+        if (!existsSync(value))
+            fail("workspace_snapshot_fd_traversal_unavailable");
+        return value;
+    }
+    // Darwin has no procfs open-file path that supports relative child lookup. It is used
+    // only by local tests/BYOA; managed durable sandboxes are Linux and fail closed above.
+    return fallback;
+}
 function stageOnce(options, paths) {
     const stagingDirectory = path.join(paths.checkpointRoot, randomUUID());
     mkdirSync(stagingDirectory, { mode: 0o700 });
     chmodSync(stagingDirectory, 0o700);
     try {
-        const rootStats = lstatSync(paths.workspace, { bigint: true });
-        if (!rootStats.isDirectory())
+        const rootHandle = openSync(paths.workspace, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        const rootStats = fstatSync(rootHandle, { bigint: true });
+        if (!rootStats.isDirectory()) {
+            closeSync(rootHandle);
             fail("workspace_snapshot_root_invalid");
+        }
         const entries = [];
         const files = [];
         let fileCount = 0;
         let totalBytes = 0;
-        function walk(sourceDirectory, destinationDirectory, segments) {
-            const directoryBefore = lstatSync(sourceDirectory, { bigint: true });
+        let estimatedEntrySetBytes = Buffer.byteLength('{"schemaVersion":"agent-workspace-entry-set/1","entries":[]}', "utf8");
+        function appendEntry(entry) {
+            estimatedEntrySetBytes += Buffer.byteLength(JSON.stringify(entry), "utf8") + 1;
+            if (estimatedEntrySetBytes > options.limits.maxEntrySetBytes) {
+                fail("workspace_snapshot_limit_exceeded");
+            }
+            entries.push(entry);
+        }
+        function walk(sourceHandle, sourceFallback, destinationDirectory, segments) {
+            const directoryBefore = fstatSync(sourceHandle, { bigint: true });
             assertSourceNode(directoryBefore, {
                 rootDevice: rootStats.dev,
                 expected: "directory",
             });
+            const sourceDirectory = descriptorPath(sourceHandle, sourceFallback);
             const children = readdirSync(sourceDirectory, {
-                withFileTypes: true,
                 encoding: "buffer",
-            }).sort((left, right) => Buffer.compare(left.name, right.name));
+            }).sort((left, right) => Buffer.compare(left, right));
             for (const child of children) {
-                const name = decodeName(child.name);
+                const name = decodeName(child);
                 if (excludedName(name))
                     continue;
                 const relativeSegments = [...segments, name];
@@ -145,13 +168,21 @@ function stageOnce(options, paths) {
                     fail("workspace_snapshot_unsupported_file_type");
                 if (stats.isDirectory()) {
                     assertSourceNode(stats, { rootDevice: rootStats.dev, expected: "directory" });
+                    const childHandle = openSync(source, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+                    const openedDirectory = fstatSync(childHandle, { bigint: true });
+                    if (!sameIdentity(stats, openedDirectory)) {
+                        closeSync(childHandle);
+                        fail("workspace_snapshot_source_changed", true);
+                    }
                     mkdirSync(destination, { mode: 0o700 });
                     chmodSync(destination, 0o700);
-                    entries.push({ type: "directory", path: relativePath, mode: "0700" });
-                    if (entries.length > options.limits.maxEntrySetBytes) {
-                        fail("workspace_snapshot_limit_exceeded");
+                    appendEntry({ type: "directory", path: relativePath, mode: "0700" });
+                    try {
+                        walk(childHandle, source, destination, relativeSegments);
+                    }
+                    finally {
+                        closeSync(childHandle);
                     }
-                    walk(source, destination, relativeSegments);
                     continue;
                 }
                 const copied = copyStableFile(source, destination, {
@@ -163,7 +194,7 @@ function stageOnce(options, paths) {
                 if (fileCount > options.limits.maxFileCount ||
                     totalBytes > options.limits.maxTotalBytes)
                     fail("workspace_snapshot_limit_exceeded");
-                entries.push({
+                appendEntry({
                     type: "file",
                     path: relativePath,
                     mode: copied.mode,
@@ -176,17 +207,19 @@ function stageOnce(options, paths) {
                     sizeBytes: copied.sizeBytes,
                     sha256: copied.sha256,
                 });
-                if (entries.length > options.limits.maxEntrySetBytes) {
-                    fail("workspace_snapshot_limit_exceeded");
-                }
             }
-            const directoryAfter = lstatSync(sourceDirectory, { bigint: true });
+            const directoryAfter = fstatSync(sourceHandle, { bigint: true });
             if (!sameIdentity(directoryBefore, directoryAfter)) {
                 fail("workspace_snapshot_source_changed", true);
             }
             fsyncDirectory(destinationDirectory);
         }
-        walk(paths.workspace, stagingDirectory, []);
+        try {
+            walk(rootHandle, paths.workspace, stagingDirectory, []);
+        }
+        finally {
+            closeSync(rootHandle);
+        }
         entries.sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
         files.sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
         const entrySet = validateWorkspaceEntrySet({ schemaVersion: WORKSPACE_ENTRY_SET_SCHEMA, entries }, options.limits);
@@ -200,13 +233,14 @@ function stageOnce(options, paths) {
 export function stageWorkspaceSnapshot(options) {
     if (!UUID.test(options.checkpointId))
         fail("workspace_snapshot_checkpoint_invalid");
-    if (options.quiescenceProof.proofVersion !== "workspace-quiescence-proof/1" ||
-        !UUID.test(options.quiescenceProof.sandboxId) ||
-        !UUID.test(options.quiescenceProof.runtimeSessionId) ||
-        options.quiescenceProof.checkpointId !== options.checkpointId ||
-        !Number.isSafeInteger(options.quiescenceProof.sandboxGeneration) ||
-        options.quiescenceProof.sandboxGeneration < 1 ||
-        options.quiescenceProof.allWritersStopped !== true)
+    if (!isWorkspaceWriterFreezeProof(options.freezeProof) ||
+        options.freezeProof.proofVersion !== "workspace-writer-freeze-proof/1" ||
+        !UUID.test(options.freezeProof.sandboxId) ||
+        !UUID.test(options.freezeProof.runtimeSessionId) ||
+        options.freezeProof.checkpointId !== options.checkpointId ||
+        !Number.isSafeInteger(options.freezeProof.sandboxGeneration) ||
+        options.freezeProof.sandboxGeneration < 1 ||
+        options.freezeProof.allWritersFrozen !== true)
         fail("workspace_snapshot_writer_isolation_unproven");
     if (!Number.isSafeInteger(options.maxStabilityRetries) || options.maxStabilityRetries < 0) {
         fail("workspace_snapshot_retry_limit_invalid");

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）：managed sandbox 下为
- * `<BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT>/<runtime_session_id>/generation-<sandbox_generation>`，
- * 由 daemon 在 session.open 时创建。
+ * per-session workspace（ADR-015 §7）：NAS managed sandbox 使用稳定路径
+ * `<root>/sessions/<runtime_session_id>/workspace`；旧 provider 保留 generation 路径。
+ * 两种路径都由 daemon 在 session.open 时创建。
  */
 export declare function runtimeSessionWorkspaceDir(runtimeSessionId: string, sandboxGeneration: number): string;
 export declare function runtimeSessionTranscriptPath(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): string;
@@ -102,7 +102,7 @@ export declare function exposeRuntimeSessionWorkspace(runtimeSessionId: string,
 /** Revoke a managed workspace without deleting the session's durable local materialization. */
 export declare function revokeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
 /** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
-export declare function removeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number): void;
+export declare function removeRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number, preserveManagedWorkspace?: boolean): void;
 export declare function ensureRuntimeSessionWorkspace(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): {
     rootDir: string;
     workspaceDir: string;

package/dist/workspace.js

@@ -4,6 +4,7 @@ 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）：
  *
@@ -53,9 +54,9 @@ export function runtimeSessionRootDir(runtimeSessionId, sandboxGeneration) {
     return path.join(daemonHome(), "agent-service-sessions", runtimeSessionId, `generation-${sandboxGeneration}`);
 }
 /**
- * per-session workspace（ADR-015 §7）：managed sandbox 下为
- * `<BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT>/<runtime_session_id>/generation-<sandbox_generation>`，
- * 由 daemon 在 session.open 时创建。
+ * per-session workspace（ADR-015 §7）：NAS managed sandbox 使用稳定路径
+ * `<root>/sessions/<runtime_session_id>/workspace`；旧 provider 保留 generation 路径。
+ * 两种路径都由 daemon 在 session.open 时创建。
  */
 export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration) {
     assertSafeId(runtimeSessionId, "runtime_session_id");
@@ -64,6 +65,9 @@ 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(runtimeSessionRootDir(runtimeSessionId, sandboxGeneration), "workspace");
@@ -71,7 +75,11 @@ export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration)
 function managedRuntimeSessionParentDir(runtimeSessionId) {
     assertSafeId(runtimeSessionId, "runtime_session_id");
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
-    return managedRoot ? path.join(managedRoot, runtimeSessionId) : null;
+    if (!managedRoot)
+        return null;
+    return nasWorkspaceEnabled()
+        ? path.join(managedRoot, "sessions", runtimeSessionId)
+        : path.join(managedRoot, runtimeSessionId);
 }
 export function runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId) {
     assertSafeId(agentRunId, "agent_run_id");
@@ -228,12 +236,16 @@ async function childDirectories(root) {
 export async function cleanupRuntimeSessionWorkspaceCopyStaging() {
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
-        for (const sessionName of await childDirectories(managedRoot)) {
+        const sessionRoot = nasWorkspaceEnabled()
+            ? path.join(managedRoot, "sessions")
+            : managedRoot;
+        for (const sessionName of await childDirectories(sessionRoot)) {
             if (!SAFE_ID_PATTERN.test(sessionName))
                 continue;
-            const sessionParent = path.join(managedRoot, sessionName);
+            const sessionParent = path.join(sessionRoot, sessionName);
             for (const name of await childDirectories(sessionParent)) {
-                if (MANAGED_COPY_STAGING_PATTERN.test(name)) {
+                if (MANAGED_COPY_STAGING_PATTERN.test(name)
+                    || LOCAL_COPY_STAGING_PATTERN.test(name)) {
                     await fs.rm(path.join(sessionParent, name), { recursive: true, force: true });
                 }
             }
@@ -700,16 +712,19 @@ export function revokeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneratio
     }
 }
 /** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
-export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
-    // 校验路径段安全后按 session 整体删除（含全部 generation 与 transcripts）。
+export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, preserveManagedWorkspace = false) {
+    // 校验路径段安全后删除本地物化状态；generation 换代可保留 NAS 正文。
     runtimeSessionRootDir(runtimeSessionId, sandboxGeneration);
     rmSync(path.join(daemonHome(), "agent-service-sessions", runtimeSessionId), {
         recursive: true,
         force: true,
     });
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
-    if (managedRoot) {
-        rmSync(path.join(managedRoot, runtimeSessionId), { recursive: true, force: true });
+    if (managedRoot && !preserveManagedWorkspace) {
+        const sessionRoot = nasWorkspaceEnabled()
+            ? path.join(managedRoot, "sessions", runtimeSessionId)
+            : path.join(managedRoot, runtimeSessionId);
+        rmSync(sessionRoot, { recursive: true, force: true });
     }
 }
 export function ensureRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, agentRunId) {

package/package.json

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