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

package/dist/workspace-restore.js

@@ -0,0 +1,333 @@
+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;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "WorkspaceRestoreError";
+    }
+}
+function fail(code) {
+    throw new WorkspaceRestoreError(code);
+}
+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);
+    if (!Number.isSafeInteger(options.requiredFreeBytes) ||
+        options.requiredFreeBytes < descriptor.expectedTotalBytes)
+        fail("workspace_restore_reservation_invalid");
+    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);
+    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 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;
+    }
+}

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

@@ -0,0 +1,34 @@
+import { type CanonicalWorkspaceEntrySet, type WorkspaceEntrySetLimits } from "./workspace-entry-set.js";
+export declare class WorkspaceSnapshotStagingError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(code: string, retryable?: boolean);
+}
+export interface StagedWorkspaceFile {
+    path: string;
+    stagingPath: string;
+    sizeBytes: number;
+    sha256: string;
+}
+export interface StagedWorkspaceSnapshot {
+    stagingDirectory: string;
+    entrySet: CanonicalWorkspaceEntrySet;
+    files: StagedWorkspaceFile[];
+}
+export interface WorkspaceSnapshotStagingOptions {
+    workspaceDirectory: string;
+    controlDirectory: string;
+    checkpointId: string;
+    limits: WorkspaceEntrySetLimits;
+    maxStabilityRetries: number;
+    quiescenceProof: WorkspaceQuiescenceProof;
+}
+export interface WorkspaceQuiescenceProof {
+    proofVersion: "workspace-quiescence-proof/1";
+    sandboxId: string;
+    sandboxGeneration: number;
+    runtimeSessionId: string;
+    checkpointId: string;
+    allWritersStopped: true;
+}
+export declare function stageWorkspaceSnapshot(options: WorkspaceSnapshotStagingOptions): StagedWorkspaceSnapshot;

package/dist/workspace-snapshot-staging.js

@@ -0,0 +1,241 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, rmSync, writeSync, } from "node:fs";
+import path from "node:path";
+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"]);
+const COPY_CHUNK_BYTES = 64 * 1024;
+export class WorkspaceSnapshotStagingError extends Error {
+    code;
+    retryable;
+    constructor(code, retryable = false) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "WorkspaceSnapshotStagingError";
+    }
+}
+function fail(code, retryable = false) {
+    throw new WorkspaceSnapshotStagingError(code, retryable);
+}
+function containsPath(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === "" || (!relative.startsWith(".." + path.sep) && relative !== "..");
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size &&
+        left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function decodeName(name) {
+    const decoded = name.toString("utf8");
+    if (!Buffer.from(decoded, "utf8").equals(name) || decoded.includes("\0")) {
+        fail("workspace_snapshot_invalid_utf8");
+    }
+    return decoded;
+}
+function excludedName(name) {
+    return name.startsWith(".") || EXCLUDED_NAMES.has(defaultCaseFold(name));
+}
+function normalizedMode(stats) {
+    return (stats.mode & 73n) !== 0n ? "0700" : "0600";
+}
+function assertSourceNode(stats, options) {
+    if (stats.dev !== options.rootDevice)
+        fail("workspace_snapshot_cross_device");
+    if (options.expected === "file") {
+        if (!stats.isFile())
+            fail("workspace_snapshot_unsupported_file_type");
+        if (stats.nlink !== 1n)
+            fail("workspace_snapshot_hard_link");
+    }
+    else if (!stats.isDirectory()) {
+        fail("workspace_snapshot_unsupported_file_type");
+    }
+}
+function copyStableFile(source, destination, options) {
+    const before = lstatSync(source, { bigint: true });
+    assertSourceNode(before, { rootDevice: options.rootDevice, expected: "file" });
+    if (before.size > BigInt(options.limits.maxFileBytes)) {
+        fail("workspace_snapshot_limit_exceeded");
+    }
+    const sourceHandle = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let destinationHandle = null;
+    try {
+        const opened = fstatSync(sourceHandle, { bigint: true });
+        assertSourceNode(opened, { rootDevice: options.rootDevice, expected: "file" });
+        if (!sameIdentity(before, opened))
+            fail("workspace_snapshot_source_changed", true);
+        destinationHandle = openSync(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL |
+            constants.O_NOFOLLOW, 0o600);
+        const hash = createHash("sha256");
+        const buffer = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
+        let copied = 0;
+        while (true) {
+            const bytesRead = readSync(sourceHandle, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+            let written = 0;
+            while (written < bytesRead) {
+                written += writeSync(destinationHandle, buffer, written, bytesRead - written, null);
+            }
+            copied += bytesRead;
+            if (copied > options.limits.maxFileBytes)
+                fail("workspace_snapshot_limit_exceeded");
+        }
+        const after = fstatSync(sourceHandle, { bigint: true });
+        if (!sameIdentity(opened, after) || BigInt(copied) !== after.size) {
+            fail("workspace_snapshot_source_changed", true);
+        }
+        fsyncSync(destinationHandle);
+        const mode = normalizedMode(after);
+        chmodSync(destination, mode === "0700" ? 0o700 : 0o600);
+        return { sizeBytes: copied, sha256: hash.digest("hex"), mode };
+    }
+    finally {
+        if (destinationHandle !== null)
+            closeSync(destinationHandle);
+        closeSync(sourceHandle);
+    }
+}
+function fsyncDirectory(directory) {
+    const handle = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        fsyncSync(handle);
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+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())
+            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 });
+            assertSourceNode(directoryBefore, {
+                rootDevice: rootStats.dev,
+                expected: "directory",
+            });
+            const children = readdirSync(sourceDirectory, {
+                withFileTypes: true,
+                encoding: "buffer",
+            }).sort((left, right) => Buffer.compare(left.name, right.name));
+            for (const child of children) {
+                const name = decodeName(child.name);
+                if (excludedName(name))
+                    continue;
+                const relativeSegments = [...segments, name];
+                if (relativeSegments.length > options.limits.maxDepth) {
+                    fail("workspace_snapshot_limit_exceeded");
+                }
+                const relativePath = relativeSegments.join("/");
+                const source = path.join(sourceDirectory, name);
+                const destination = path.join(destinationDirectory, name);
+                const stats = lstatSync(source, { bigint: true });
+                if (stats.isSymbolicLink())
+                    fail("workspace_snapshot_unsupported_file_type");
+                if (stats.isDirectory()) {
+                    assertSourceNode(stats, { rootDevice: rootStats.dev, expected: "directory" });
+                    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");
+                    }
+                    walk(source, destination, relativeSegments);
+                    continue;
+                }
+                const copied = copyStableFile(source, destination, {
+                    rootDevice: rootStats.dev,
+                    limits: options.limits,
+                });
+                fileCount += 1;
+                totalBytes += copied.sizeBytes;
+                if (fileCount > options.limits.maxFileCount ||
+                    totalBytes > options.limits.maxTotalBytes)
+                    fail("workspace_snapshot_limit_exceeded");
+                entries.push({
+                    type: "file",
+                    path: relativePath,
+                    mode: copied.mode,
+                    sizeBytes: copied.sizeBytes,
+                    sha256: copied.sha256,
+                });
+                files.push({
+                    path: relativePath,
+                    stagingPath: destination,
+                    sizeBytes: copied.sizeBytes,
+                    sha256: copied.sha256,
+                });
+                if (entries.length > options.limits.maxEntrySetBytes) {
+                    fail("workspace_snapshot_limit_exceeded");
+                }
+            }
+            const directoryAfter = lstatSync(sourceDirectory, { bigint: true });
+            if (!sameIdentity(directoryBefore, directoryAfter)) {
+                fail("workspace_snapshot_source_changed", true);
+            }
+            fsyncDirectory(destinationDirectory);
+        }
+        walk(paths.workspace, stagingDirectory, []);
+        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);
+        return { stagingDirectory, entrySet, files };
+    }
+    catch (error) {
+        rmSync(stagingDirectory, { recursive: true, force: true });
+        throw error;
+    }
+}
+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)
+        fail("workspace_snapshot_writer_isolation_unproven");
+    if (!Number.isSafeInteger(options.maxStabilityRetries) || options.maxStabilityRetries < 0) {
+        fail("workspace_snapshot_retry_limit_invalid");
+    }
+    const workspace = realpathSync(options.workspaceDirectory);
+    const requestedControl = path.resolve(options.controlDirectory);
+    if (containsPath(workspace, requestedControl)) {
+        fail("workspace_snapshot_control_path_invalid");
+    }
+    mkdirSync(options.controlDirectory, { recursive: true, mode: 0o700 });
+    chmodSync(options.controlDirectory, 0o700);
+    const control = realpathSync(options.controlDirectory);
+    if (containsPath(workspace, control))
+        fail("workspace_snapshot_control_path_invalid");
+    const checkpointRoot = path.join(control, "workspace-snapshot-staging", options.checkpointId);
+    mkdirSync(checkpointRoot, { recursive: true, mode: 0o700 });
+    chmodSync(checkpointRoot, 0o700);
+    let attempt = 0;
+    while (true) {
+        try {
+            return stageOnce(options, { workspace, checkpointRoot });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceSnapshotStagingError && error.retryable &&
+                attempt < options.maxStabilityRetries) {
+                attempt += 1;
+                continue;
+            }
+            throw error;
+        }
+    }
+}

package/dist/workspace.d.ts

@@ -26,6 +26,61 @@ export declare function runtimeSessionRootDir(runtimeSessionId: string, sandboxG
  */
 export declare function runtimeSessionWorkspaceDir(runtimeSessionId: string, sandboxGeneration: number): string;
 export declare function runtimeSessionTranscriptPath(runtimeSessionId: string, sandboxGeneration: number, agentRunId: string): string;
+export declare const WORKSPACE_COPY_POLICY_V1: Readonly<{
+    policyId: "WorkspaceCopyPolicyV1";
+    maxTotalEntries: 25000;
+    maxFiles: 20000;
+    maxSymlinks: 2000;
+    maxBytes: number;
+    maxDepth: 64;
+    maxRelativePathBytes: 4096;
+    maxDurationSeconds: 600;
+    markerName: ".botlearn-workspace-copy";
+}>;
+export type WorkspaceCopyErrorCode = "workspace_migration_source_unavailable" | "workspace_migration_content_unsafe" | "workspace_migration_limit_exceeded" | "workspace_migration_io_failed" | "workspace_migration_receipt_mismatch";
+export declare class WorkspaceCopyError extends Error {
+    readonly code: WorkspaceCopyErrorCode;
+    constructor(code: WorkspaceCopyErrorCode);
+}
+export interface WorkspaceCopyReceiptV1 {
+    schema_version: "botlearn-workspace-copy-receipt/1";
+    policy_id: "WorkspaceCopyPolicyV1";
+    copy_id: string;
+    source_runtime_session_id: string;
+    target_runtime_session_id: string;
+    source_sandbox_id: string;
+    source_generation: number;
+    file_count: number;
+    directory_count: number;
+    symlink_count: number;
+    total_bytes: number;
+    manifest_digest: string;
+}
+export interface WorkspaceCopyResult {
+    receipt: WorkspaceCopyReceiptV1;
+    markerPath: string;
+}
+interface ManifestEntry {
+    type: "file" | "dir" | "link";
+    relativePath: string;
+    modeTag: "file-0600" | "file-0700" | "dir-0700" | "link";
+    byteSize?: number;
+    contentDigest?: Buffer;
+    linkTarget?: string;
+}
+export declare function workspaceCopyManifestDigest(entries: ManifestEntry[]): string;
+export declare function workspaceCopyV1Supported(): boolean;
+/** Remove crash-left staging directories before advertising workspace_copy_v1. */
+export declare function cleanupRuntimeSessionWorkspaceCopyStaging(): Promise<void>;
+/** Copy learner-owned files into a new Session and durably stage a content-free receipt. */
+export declare function copyRuntimeSessionWorkspace(request: {
+    copyId: string;
+    sourceRuntimeSessionId: string;
+    targetRuntimeSessionId: string;
+    sandboxId: string;
+    sandboxGeneration: number;
+}): Promise<WorkspaceCopyResult>;
+export declare function finalizeRuntimeSessionWorkspaceCopy(markerPath: string): Promise<void>;
 export declare function ensureRunWorkspace(agentRunId: string): {
     rootDir: string;
     workspaceDir: string;
@@ -53,3 +108,4 @@ export declare function ensureRuntimeSessionWorkspace(runtimeSessionId: string,
     workspaceDir: string;
     transcriptFile: string;
 };
+export {};