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

package/dist/workspace.js

@@ -1,8 +1,5 @@
-import { chmodSync, constants, existsSync, mkdirSync, rmSync, } from "node:fs";
-import { promises as fs } from "node:fs";
-import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync, } from "node:fs";
 import path from "node:path";
-import { TextDecoder } from "node:util";
 import { daemonHome } from "./auth-store.js";
 /**
  * 每 run 隔离工作区（spec §4）：
@@ -53,27 +50,27 @@ export function runtimeSessionRootDir(runtimeSessionId, sandboxGeneration) {
     return path.join(daemonHome(), "agent-service-sessions", runtimeSessionId, `generation-${sandboxGeneration}`);
 }
 /**
- * per-session workspace（ADR-015 §7）：managed sandbox 使用稳定路径
- * `<root>/sessions/<runtime_session_id>/workspace`。该路径不含 generation，
+ * durable workspace：managed sandbox 使用稳定路径
+ * `<root>/sessions/<workspace_id>/workspace`。该路径不含 generation，
  * 因为 NAS image 跨 generation 重新挂载后必须解析到同一个目录。
  */
-export function runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration) {
-    assertSafeId(runtimeSessionId, "runtime_session_id");
+export function runtimeSessionWorkspaceDir(workspaceId, sandboxGeneration) {
+    assertSafeId(workspaceId, "workspace_id");
     if (!Number.isInteger(sandboxGeneration) || sandboxGeneration < 1) {
         throw new Error("unsafe sandbox_generation: expected a positive integer");
     }
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (managedRoot) {
-        return path.join(managedRoot, "sessions", runtimeSessionId, "workspace");
+        return path.join(managedRoot, "sessions", workspaceId, "workspace");
     }
-    return path.join(runtimeSessionRootDir(runtimeSessionId, sandboxGeneration), "workspace");
+    return path.join(runtimeSessionRootDir(workspaceId, sandboxGeneration), "workspace");
 }
-function managedRuntimeSessionParentDir(runtimeSessionId) {
-    assertSafeId(runtimeSessionId, "runtime_session_id");
+function managedWorkspaceParentDir(workspaceId) {
+    assertSafeId(workspaceId, "workspace_id");
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
     if (!managedRoot)
         return null;
-    return path.join(managedRoot, "sessions", runtimeSessionId);
+    return path.join(managedRoot, "sessions", workspaceId);
 }
 export function runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId) {
     assertSafeId(agentRunId, "agent_run_id");
@@ -92,555 +89,6 @@ function mkdirTolerant(dir, mode = 0o700) {
 function isMissingPathError(error) {
     return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
-export const WORKSPACE_COPY_POLICY_V1 = Object.freeze({
-    policyId: "WorkspaceCopyPolicyV1",
-    maxTotalEntries: 25_000,
-    maxFiles: 20_000,
-    maxSymlinks: 2_000,
-    maxBytes: 512 * 1024 * 1024,
-    maxDepth: 64,
-    maxRelativePathBytes: 4096,
-    maxDurationSeconds: 600,
-    markerName: ".botlearn-workspace-copy",
-});
-export class WorkspaceCopyError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
-}
-const fatalUtf8 = new TextDecoder("utf-8", { fatal: true });
-function workspaceCopyDeadline(startedAt) {
-    if (Date.now() - startedAt > WORKSPACE_COPY_POLICY_V1.maxDurationSeconds * 1000) {
-        throw new WorkspaceCopyError("workspace_migration_limit_exceeded");
-    }
-}
-function isReservedTopLevelName(name) {
-    return name === ".botlearn" || name.startsWith(".botlearn-");
-}
-function safeUtf8(buffer) {
-    try {
-        const value = fatalUtf8.decode(buffer);
-        if (value.includes("\0"))
-            throw new Error("nul");
-        return value;
-    }
-    catch {
-        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-    }
-}
-function relativeWorkspacePath(components) {
-    const value = components.join("/");
-    if (Buffer.byteLength(value, "utf8") > WORKSPACE_COPY_POLICY_V1.maxRelativePathBytes) {
-        throw new WorkspaceCopyError("workspace_migration_limit_exceeded");
-    }
-    if (components.length > WORKSPACE_COPY_POLICY_V1.maxDepth) {
-        throw new WorkspaceCopyError("workspace_migration_limit_exceeded");
-    }
-    return value;
-}
-function countEntry(counters, type, bytes = 0) {
-    if (type === "file") {
-        counters.fileCount += 1;
-        counters.totalBytes += bytes;
-    }
-    else if (type === "dir")
-        counters.directoryCount += 1;
-    else
-        counters.symlinkCount += 1;
-    const total = counters.fileCount + counters.directoryCount + counters.symlinkCount;
-    if (total > WORKSPACE_COPY_POLICY_V1.maxTotalEntries ||
-        counters.fileCount > WORKSPACE_COPY_POLICY_V1.maxFiles ||
-        counters.symlinkCount > WORKSPACE_COPY_POLICY_V1.maxSymlinks ||
-        counters.totalBytes > WORKSPACE_COPY_POLICY_V1.maxBytes) {
-        throw new WorkspaceCopyError("workspace_migration_limit_exceeded");
-    }
-}
-function uint32(value) {
-    const result = Buffer.allocUnsafe(4);
-    result.writeUInt32BE(value);
-    return result;
-}
-function uint64(value) {
-    const result = Buffer.allocUnsafe(8);
-    result.writeBigUInt64BE(BigInt(value));
-    return result;
-}
-function encodedString(value) {
-    const bytes = Buffer.from(value, "utf8");
-    return [uint32(bytes.length), bytes];
-}
-export function workspaceCopyManifestDigest(entries) {
-    const digest = createHash("sha256");
-    const sorted = [...entries].sort((left, right) => Buffer.compare(Buffer.from(left.relativePath, "utf8"), Buffer.from(right.relativePath, "utf8")));
-    for (const entry of sorted) {
-        for (const item of encodedString(entry.type))
-            digest.update(item);
-        for (const item of encodedString(entry.relativePath))
-            digest.update(item);
-        for (const item of encodedString(entry.modeTag))
-            digest.update(item);
-        if (entry.type === "file") {
-            digest.update(uint64(entry.byteSize ?? 0));
-            digest.update(entry.contentDigest ?? Buffer.alloc(32));
-        }
-        else if (entry.type === "link") {
-            for (const item of encodedString(entry.linkTarget ?? ""))
-                digest.update(item);
-        }
-    }
-    return digest.digest("hex");
-}
-function sameFileSnapshot(before, after) {
-    return before.dev === after.dev && before.ino === after.ino && before.size === after.size &&
-        before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs;
-}
-function directoryLookupPath(handle, fallbackPath) {
-    // Linux production sandboxes expose traversable /proc descriptors. Local
-    // non-Linux tests retain functional coverage through the original path, but
-    // those builds must not advertise workspace_copy_v1.
-    return process.platform === "linux" ? `/proc/self/fd/${handle.fd}` : fallbackPath;
-}
-function sourceTraversalSupported() {
-    return process.platform === "linux" &&
-        typeof constants.O_DIRECTORY === "number" &&
-        typeof constants.O_NOFOLLOW === "number";
-}
-export function workspaceCopyV1Supported() {
-    return sourceTraversalSupported();
-}
-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 COPY_STAGING_PATTERN = new RegExp(`^workspace\\.workspace-copy-${COPY_STAGING_SUFFIX}$`);
-async function childDirectories(root) {
-    try {
-        return (await fs.readdir(root, { withFileTypes: true }))
-            .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
-            .map((entry) => entry.name);
-    }
-    catch (error) {
-        if (isMissingPathError(error))
-            return [];
-        throw new WorkspaceCopyError("workspace_migration_io_failed");
-    }
-}
-/** Remove crash-left staging directories before advertising workspace_copy_v1. */
-export async function cleanupRuntimeSessionWorkspaceCopyStaging() {
-    const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
-    if (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 (COPY_STAGING_PATTERN.test(name)) {
-                    await fs.rm(path.join(sessionParent, name), { recursive: true, force: true });
-                }
-            }
-        }
-    }
-    const localRoot = path.join(daemonHome(), "agent-service-sessions");
-    for (const sessionName of await childDirectories(localRoot)) {
-        if (!SAFE_ID_PATTERN.test(sessionName))
-            continue;
-        const sessionParent = path.join(localRoot, sessionName);
-        for (const generationName of await childDirectories(sessionParent)) {
-            if (!/^generation-[1-9][0-9]*$/.test(generationName))
-                continue;
-            const generationParent = path.join(sessionParent, generationName);
-            for (const name of await childDirectories(generationParent)) {
-                if (COPY_STAGING_PATTERN.test(name)) {
-                    await fs.rm(path.join(generationParent, name), { recursive: true, force: true });
-                }
-            }
-        }
-    }
-}
-function assertFileBudget(counters, size) {
-    if (!Number.isSafeInteger(size) ||
-        size < 0 ||
-        counters.fileCount + 1 > WORKSPACE_COPY_POLICY_V1.maxFiles ||
-        counters.fileCount + counters.directoryCount + counters.symlinkCount + 1 >
-            WORKSPACE_COPY_POLICY_V1.maxTotalEntries ||
-        counters.totalBytes + size > WORKSPACE_COPY_POLICY_V1.maxBytes) {
-        throw new WorkspaceCopyError("workspace_migration_limit_exceeded");
-    }
-}
-async function copyRegularFile(sourcePath, targetPath, counters, startedAt) {
-    let sourceHandle;
-    let targetHandle;
-    try {
-        sourceHandle = await fs.open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
-        const before = await sourceHandle.stat();
-        if (!before.isFile())
-            throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-        assertFileBudget(counters, before.size);
-        const mode = (before.mode & 0o111) !== 0 ? 0o700 : 0o600;
-        targetHandle = await fs.open(targetPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, mode);
-        const contentDigest = createHash("sha256");
-        const buffer = Buffer.allocUnsafe(64 * 1024);
-        let offset = 0;
-        while (offset < before.size) {
-            workspaceCopyDeadline(startedAt);
-            const { bytesRead } = await sourceHandle.read(buffer, 0, Math.min(buffer.length, before.size - offset), offset);
-            if (bytesRead <= 0)
-                throw new WorkspaceCopyError("workspace_migration_io_failed");
-            const chunk = buffer.subarray(0, bytesRead);
-            let bytesWritten = 0;
-            while (bytesWritten < bytesRead) {
-                const write = await targetHandle.write(chunk, bytesWritten, bytesRead - bytesWritten, offset + bytesWritten);
-                if (write.bytesWritten <= 0) {
-                    throw new WorkspaceCopyError("workspace_migration_io_failed");
-                }
-                bytesWritten += write.bytesWritten;
-            }
-            contentDigest.update(chunk);
-            offset += bytesRead;
-            await new Promise((resolve) => setImmediate(resolve));
-        }
-        const after = await sourceHandle.stat();
-        if (!sameFileSnapshot(before, after)) {
-            throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-        }
-        await targetHandle.chmod(mode);
-        await targetHandle.sync();
-        return {
-            size: before.size,
-            digest: contentDigest.digest(),
-            modeTag: mode === 0o700 ? "file-0700" : "file-0600",
-        };
-    }
-    catch (error) {
-        if (error instanceof WorkspaceCopyError)
-            throw error;
-        throw new WorkspaceCopyError("workspace_migration_io_failed");
-    }
-    finally {
-        await targetHandle?.close().catch(() => undefined);
-        await sourceHandle?.close().catch(() => undefined);
-    }
-}
-async function validateSymbolicLink(sourceRootRealPath, sourceDirectoryPath, relativeParent, target) {
-    if (path.posix.isAbsolute(target) || path.isAbsolute(target) || target.includes("\0")) {
-        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-    }
-    const lexical = path.posix.normalize(path.posix.join(relativeParent, target));
-    if (lexical === ".." || lexical.startsWith("../")) {
-        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-    }
-    const top = lexical.split("/")[0] ?? "";
-    if (isReservedTopLevelName(top)) {
-        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-    }
-    try {
-        // Resolve the captured target text from the open parent directory, not by
-        // following the source symlink pathname again after readlink().
-        const resolved = await fs.realpath(path.join(sourceDirectoryPath, target));
-        if (resolved !== sourceRootRealPath &&
-            !resolved.startsWith(`${sourceRootRealPath}${path.sep}`)) {
-            throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-        }
-        const resolvedRelative = path.relative(sourceRootRealPath, resolved).split(path.sep).join("/");
-        if (isReservedTopLevelName(resolvedRelative.split("/")[0] ?? "")) {
-            throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-        }
-    }
-    catch (error) {
-        if (error instanceof WorkspaceCopyError)
-            throw error;
-        // Dangling links and cycles cannot be proven safe in V1.
-        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-    }
-}
-async function copyWorkspaceTree(sourceRoot, stagingRoot, startedAt) {
-    const entries = [];
-    const counters = {
-        fileCount: 0,
-        directoryCount: 0,
-        symlinkCount: 0,
-        totalBytes: 0,
-    };
-    let rootHandle;
-    try {
-        rootHandle = await fs.open(sourceRoot, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
-        const rootInfo = await rootHandle.stat();
-        if (!rootInfo.isDirectory()) {
-            throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-        }
-    }
-    catch (error) {
-        if (error instanceof WorkspaceCopyError)
-            throw error;
-        throw new WorkspaceCopyError("workspace_migration_source_unavailable");
-    }
-    const rootLookupPath = directoryLookupPath(rootHandle, sourceRoot);
-    const sourceRootRealPath = await fs.realpath(rootLookupPath);
-    const visit = async (sourceDirectory, sourceDirectoryPath, components, targetDir) => {
-        workspaceCopyDeadline(startedAt);
-        const sourceDirectoryLookup = directoryLookupPath(sourceDirectory, sourceDirectoryPath);
-        let children;
-        try {
-            children = await fs.readdir(sourceDirectoryLookup, {
-                encoding: "buffer",
-                withFileTypes: true,
-            });
-        }
-        catch {
-            throw new WorkspaceCopyError("workspace_migration_io_failed");
-        }
-        children.sort((left, right) => Buffer.compare(left.name, right.name));
-        for (const child of children) {
-            workspaceCopyDeadline(startedAt);
-            const name = safeUtf8(child.name);
-            if (components.length === 0 && isReservedTopLevelName(name))
-                continue;
-            const childComponents = [...components, name];
-            const relativePath = relativeWorkspacePath(childComponents);
-            const sourcePath = path.join(sourceDirectoryLookup, name);
-            const targetPath = path.join(targetDir, name);
-            let info;
-            try {
-                info = await fs.lstat(sourcePath);
-            }
-            catch {
-                throw new WorkspaceCopyError("workspace_migration_io_failed");
-            }
-            if (info.isDirectory() && !info.isSymbolicLink()) {
-                let childDirectory;
-                try {
-                    childDirectory = await fs.open(sourcePath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
-                    if (!(await childDirectory.stat()).isDirectory()) {
-                        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-                    }
-                    countEntry(counters, "dir");
-                    await fs.mkdir(targetPath, { mode: 0o700 });
-                    await fs.chmod(targetPath, 0o700);
-                    entries.push({ type: "dir", relativePath, modeTag: "dir-0700" });
-                    await visit(childDirectory, sourcePath, childComponents, targetPath);
-                }
-                catch (error) {
-                    if (error instanceof WorkspaceCopyError)
-                        throw error;
-                    throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-                }
-                finally {
-                    await childDirectory?.close().catch(() => undefined);
-                }
-            }
-            else if (info.isSymbolicLink()) {
-                let targetBuffer;
-                try {
-                    targetBuffer = await fs.readlink(sourcePath, { encoding: "buffer" });
-                }
-                catch {
-                    throw new WorkspaceCopyError("workspace_migration_io_failed");
-                }
-                const linkTarget = safeUtf8(targetBuffer);
-                await validateSymbolicLink(sourceRootRealPath, sourceDirectoryLookup, components.join("/"), linkTarget);
-                countEntry(counters, "link");
-                await fs.symlink(linkTarget, targetPath);
-                entries.push({ type: "link", relativePath, modeTag: "link", linkTarget });
-            }
-            else if (info.isFile()) {
-                const copied = await copyRegularFile(sourcePath, targetPath, counters, startedAt);
-                countEntry(counters, "file", copied.size);
-                entries.push({
-                    type: "file",
-                    relativePath,
-                    modeTag: copied.modeTag,
-                    byteSize: copied.size,
-                    contentDigest: copied.digest,
-                });
-            }
-            else {
-                throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-            }
-        }
-    };
-    try {
-        await visit(rootHandle, sourceRoot, [], stagingRoot);
-        return { entries, counters };
-    }
-    finally {
-        await rootHandle.close().catch(() => undefined);
-    }
-}
-async function manifestFromWorkspace(root, startedAt) {
-    const scratch = `${root}.manifest-${randomUUID()}`;
-    await fs.mkdir(scratch, { mode: 0o700 });
-    try {
-        return await copyWorkspaceTree(root, scratch, startedAt);
-    }
-    finally {
-        await fs.rm(scratch, { recursive: true, force: true });
-    }
-}
-function receiptMatchesRequest(receipt, request) {
-    return receipt.schema_version === "botlearn-workspace-copy-receipt/1" &&
-        receipt.policy_id === WORKSPACE_COPY_POLICY_V1.policyId &&
-        receipt.copy_id === request.copyId &&
-        receipt.source_runtime_session_id === request.sourceRuntimeSessionId &&
-        receipt.target_runtime_session_id === request.targetRuntimeSessionId &&
-        receipt.source_sandbox_id === request.sandboxId &&
-        receipt.source_generation === request.sandboxGeneration &&
-        Number.isSafeInteger(receipt.file_count) && receipt.file_count >= 0 &&
-        Number.isSafeInteger(receipt.directory_count) && receipt.directory_count >= 0 &&
-        Number.isSafeInteger(receipt.symlink_count) && receipt.symlink_count >= 0 &&
-        Number.isSafeInteger(receipt.total_bytes) && receipt.total_bytes >= 0 &&
-        /^[0-9a-f]{64}$/.test(receipt.manifest_digest);
-}
-async function readWorkspaceCopyMarker(markerPath) {
-    let marker;
-    try {
-        marker = await fs.open(markerPath, constants.O_RDONLY | constants.O_NOFOLLOW);
-        const info = await marker.stat();
-        if (!info.isFile() || info.size < 2 || info.size > 4096) {
-            throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-        }
-        return JSON.parse(await marker.readFile("utf8"));
-    }
-    catch (error) {
-        if (error instanceof WorkspaceCopyError)
-            throw error;
-        throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-    }
-    finally {
-        await marker?.close().catch(() => undefined);
-    }
-}
-/** Copy learner-owned files into a new Session and durably stage a content-free receipt. */
-export async function copyRuntimeSessionWorkspace(request) {
-    const startedAt = Date.now();
-    const { copyId, sourceRuntimeSessionId, targetRuntimeSessionId, sandboxId, sandboxGeneration, } = request;
-    assertSafeId(copyId, "copy_id");
-    assertSafeId(sourceRuntimeSessionId, "source_runtime_session_id");
-    assertSafeId(targetRuntimeSessionId, "target_runtime_session_id");
-    if (sourceRuntimeSessionId === targetRuntimeSessionId) {
-        throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-    }
-    const source = runtimeSessionWorkspaceDir(sourceRuntimeSessionId, sandboxGeneration);
-    const target = runtimeSessionWorkspaceDir(targetRuntimeSessionId, sandboxGeneration);
-    const markerPath = path.join(target, WORKSPACE_COPY_POLICY_V1.markerName);
-    try {
-        const sourceInfo = await fs.lstat(source);
-        if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink()) {
-            throw new WorkspaceCopyError("workspace_migration_source_unavailable");
-        }
-    }
-    catch (error) {
-        if (error instanceof WorkspaceCopyError)
-            throw error;
-        throw new WorkspaceCopyError("workspace_migration_source_unavailable");
-    }
-    if (existsSync(target)) {
-        const receipt = await readWorkspaceCopyMarker(markerPath);
-        if (!receiptMatchesRequest(receipt, request)) {
-            throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-        }
-        const staged = await manifestFromWorkspace(target, startedAt);
-        if (workspaceCopyManifestDigest(staged.entries) !== receipt.manifest_digest ||
-            staged.counters.fileCount !== receipt.file_count ||
-            staged.counters.directoryCount !== receipt.directory_count ||
-            staged.counters.symlinkCount !== receipt.symlink_count ||
-            staged.counters.totalBytes !== receipt.total_bytes) {
-            throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-        }
-        return { receipt, markerPath };
-    }
-    const targetParent = path.dirname(target);
-    await fs.mkdir(targetParent, { recursive: true, mode: 0o700 });
-    await fs.chmod(targetParent, 0o700);
-    const stagingPrefix = `${path.basename(target)}.workspace-copy-${copyId}-`;
-    for (const name of await fs.readdir(targetParent)) {
-        if (name.startsWith(stagingPrefix)) {
-            await fs.rm(path.join(targetParent, name), { recursive: true, force: true });
-        }
-    }
-    const staging = path.join(targetParent, `${stagingPrefix}${randomUUID()}`);
-    await fs.mkdir(staging, { mode: 0o700 });
-    try {
-        const sourceManifest = await copyWorkspaceTree(source, staging, startedAt);
-        const sourceDigest = workspaceCopyManifestDigest(sourceManifest.entries);
-        const stagedManifest = await manifestFromWorkspace(staging, startedAt);
-        const stagedDigest = workspaceCopyManifestDigest(stagedManifest.entries);
-        if (sourceDigest !== stagedDigest) {
-            throw new WorkspaceCopyError("workspace_migration_content_unsafe");
-        }
-        const receipt = {
-            schema_version: "botlearn-workspace-copy-receipt/1",
-            policy_id: WORKSPACE_COPY_POLICY_V1.policyId,
-            copy_id: copyId,
-            source_runtime_session_id: sourceRuntimeSessionId,
-            target_runtime_session_id: targetRuntimeSessionId,
-            source_sandbox_id: sandboxId,
-            source_generation: sandboxGeneration,
-            file_count: sourceManifest.counters.fileCount,
-            directory_count: sourceManifest.counters.directoryCount,
-            symlink_count: sourceManifest.counters.symlinkCount,
-            total_bytes: sourceManifest.counters.totalBytes,
-            manifest_digest: sourceDigest,
-        };
-        const stagingMarker = path.join(staging, WORKSPACE_COPY_POLICY_V1.markerName);
-        const marker = await fs.open(stagingMarker, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
-        try {
-            await marker.writeFile(JSON.stringify(receipt));
-            await marker.sync();
-        }
-        finally {
-            await marker.close();
-        }
-        const stagingHandle = await fs.open(staging, constants.O_RDONLY | constants.O_DIRECTORY);
-        try {
-            await stagingHandle.sync();
-        }
-        finally {
-            await stagingHandle.close();
-        }
-        workspaceCopyDeadline(startedAt);
-        if (existsSync(target)) {
-            throw new WorkspaceCopyError("workspace_migration_receipt_mismatch");
-        }
-        await fs.rename(staging, target);
-        await fs.chmod(target, 0o700);
-        const parentHandle = await fs.open(targetParent, constants.O_RDONLY | constants.O_DIRECTORY);
-        try {
-            await parentHandle.sync();
-        }
-        finally {
-            await parentHandle.close();
-        }
-        return { receipt, markerPath };
-    }
-    catch (error) {
-        await fs.rm(staging, { recursive: true, force: true });
-        if (error instanceof WorkspaceCopyError)
-            throw error;
-        throw new WorkspaceCopyError("workspace_migration_io_failed");
-    }
-}
-export async function finalizeRuntimeSessionWorkspaceCopy(markerPath) {
-    try {
-        await fs.unlink(markerPath);
-    }
-    catch (error) {
-        if (!isMissingPathError(error)) {
-            throw new WorkspaceCopyError("workspace_migration_io_failed");
-        }
-    }
-    let parentHandle;
-    try {
-        parentHandle = await fs.open(path.dirname(markerPath), constants.O_RDONLY | constants.O_DIRECTORY);
-        await parentHandle.sync();
-    }
-    catch {
-        throw new WorkspaceCopyError("workspace_migration_io_failed");
-    }
-    finally {
-        await parentHandle?.close().catch(() => undefined);
-    }
-}
 export function ensureRunWorkspace(agentRunId) {
     const rootDir = runRootDir(agentRunId);
     const workspaceDir = runWorkspaceDir(agentRunId);
@@ -652,11 +100,11 @@ export function ensureRunWorkspace(agentRunId) {
  * session.open 时创建 per-session 目录。managed workspace 默认保持 0700，只有当前
  * activation 会通过 exposeRuntimeSessionWorkspace() 临时开放给 runtime 组。
  */
-export function ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration) {
+export function ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration, workspaceId = runtimeSessionId) {
     const rootDir = runtimeSessionRootDir(runtimeSessionId, sandboxGeneration);
-    const workspaceDir = runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration);
+    const workspaceDir = runtimeSessionWorkspaceDir(workspaceId, sandboxGeneration);
     mkdirTolerant(rootDir);
-    const managedParent = managedRuntimeSessionParentDir(runtimeSessionId);
+    const managedParent = managedWorkspaceParentDir(workspaceId);
     if (managedParent)
         mkdirTolerant(managedParent, 0o700);
     mkdirTolerant(workspaceDir, 0o700);
@@ -667,22 +115,22 @@ export function ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGenerat
  * 0710，因此 runtime 只能穿过根目录，不能列举其他 session id；未激活 session
  * 的父目录与 workspace 始终为 0700。
  */
-export function exposeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
-    const managedParent = managedRuntimeSessionParentDir(runtimeSessionId);
+export function exposeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, workspaceId = runtimeSessionId) {
+    const managedParent = managedWorkspaceParentDir(workspaceId);
     if (!managedParent)
         return;
-    const { workspaceDir } = ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration);
+    const { workspaceDir } = ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration, workspaceId);
     // Parent is traverse-only for the runtime group: allowing group write here would let
     // the runtime replace the generation directory with a symlink before revoke/cleanup.
     chmodSync(managedParent, 0o710);
     chmodSync(workspaceDir, 0o770);
 }
 /** Revoke a managed workspace without deleting the session's durable local materialization. */
-export function revokeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration) {
-    const managedParent = managedRuntimeSessionParentDir(runtimeSessionId);
+export function revokeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, workspaceId = runtimeSessionId) {
+    const managedParent = managedWorkspaceParentDir(workspaceId);
     if (!managedParent)
         return;
-    const workspaceDir = runtimeSessionWorkspaceDir(runtimeSessionId, sandboxGeneration);
+    const workspaceDir = runtimeSessionWorkspaceDir(workspaceId, sandboxGeneration);
     // Revoke the leaf before the parent so a runtime loses access as early as possible.
     try {
         chmodSync(workspaceDir, 0o700);
@@ -701,22 +149,36 @@ export function revokeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneratio
             throw error;
     }
 }
-/** session.close 时删除 workspace 与本地 session 物化状态（transcripts 等）。幂等。 */
-export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, preserveManagedWorkspace = false) {
-    // 校验路径段安全后删除本地物化状态；generation 换代可保留 NAS 正文。
+/** session.close 时删除本地 Session 状态；Workspace 由独立生命周期拥有。 */
+export function removeRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, preserveManagedWorkspace = false, workspaceId = runtimeSessionId) {
     runtimeSessionRootDir(runtimeSessionId, sandboxGeneration);
-    rmSync(path.join(daemonHome(), "agent-service-sessions", runtimeSessionId), {
-        recursive: true,
-        force: true,
-    });
+    const localSessionRoot = path.join(daemonHome(), "agent-service-sessions", runtimeSessionId);
     const managedRoot = process.env.BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT?.trim();
+    if (!managedRoot && preserveManagedWorkspace && workspaceId === runtimeSessionId) {
+        // Local development historically stored the Workspace below the Session generation.
+        // Keep that directory for the backfilled Workspace identity and remove only
+        // Session-owned transcripts from every generation.
+        if (existsSync(localSessionRoot)) {
+            for (const generation of readdirSync(localSessionRoot, { withFileTypes: true })) {
+                if (!generation.isDirectory())
+                    continue;
+                rmSync(path.join(localSessionRoot, generation.name, "transcripts"), {
+                    recursive: true,
+                    force: true,
+                });
+            }
+        }
+    }
+    else {
+        rmSync(localSessionRoot, { recursive: true, force: true });
+    }
     if (managedRoot && !preserveManagedWorkspace) {
-        const sessionRoot = path.join(managedRoot, "sessions", runtimeSessionId);
+        const sessionRoot = path.join(managedRoot, "sessions", workspaceId);
         rmSync(sessionRoot, { recursive: true, force: true });
     }
 }
-export function ensureRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, agentRunId) {
-    const { rootDir, workspaceDir } = ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration);
+export function ensureRuntimeSessionWorkspace(runtimeSessionId, sandboxGeneration, agentRunId, workspaceId = runtimeSessionId) {
+    const { rootDir, workspaceDir } = ensureRuntimeSessionDirectories(runtimeSessionId, sandboxGeneration, workspaceId);
     const transcriptFile = runtimeSessionTranscriptPath(runtimeSessionId, sandboxGeneration, agentRunId);
     mkdirTolerant(path.dirname(transcriptFile));
     return { rootDir, workspaceDir, transcriptFile };