@botlearn-course/daemon 0.0.20-beta.9 → 0.0.21-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botlearn-course/daemon",
-  "version": "0.0.20-beta.9",
+  "version": "0.0.21-beta.1",
   "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");
-    }
-}