@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/core/transactional/file-checkpoint-backend.js

@@ -0,0 +1,278 @@
+import { cp, lstat, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { attestsWorkspaceMountIsolation } from '../capability/attestation.js';
+import { currentRecoveryResourceIdentity } from '../recovery/resource-identity.js';
+import { FILE_CHECKPOINT_DISABLED, FILE_CHECKPOINT_DURABLE_REQUIRED, FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, } from './backend-selector.js';
+import { cloneBareWorktreeCopy, computeGitMetadataFingerprint, copyGitIndexState, execGit, FILE_CHECKPOINT_CWD_OUTSIDE_ROOT, FILE_CHECKPOINT_GIT_METADATA_CHANGED, FILE_CHECKPOINT_PREPARE_FAILED, FILE_CHECKPOINT_SOURCE_CHANGED, removeAllGitRemotes, resolveExecutionCwdRelative, } from './file-checkpoint-git.js';
+import { removeDeadOwnerStaging, writeOwnerMarker } from './file-checkpoint-staging.js';
+import { cloneDirectoryTree, probeFileCloneStrategy } from './file-clone.js';
+import { buildFileTreeIndex, diffFileTreeIndices, FILE_CHECKPOINT_PREPARE_TIMEOUT, FILE_CHECKPOINT_QUOTA_EXCEEDED, FileCheckpointDiagnosticError, } from './file-tree.js';
+import { isDirtyWorktree, isGitWorktreeAvailable } from './git-worktree.js';
+import { readSnapshotNode } from './snapshot-node.js';
+export const FILE_CHECKPOINT_PROTECTED_PATH_CHANGED = 'file_checkpoint_protected_path_changed';
+function fileCheckpointIsolationReason(context) {
+    const attestation = context.boundaryAttestation;
+    const fresh = context.boundaryAttestationFresh === true;
+    const driverId = context.boundaryDriverId;
+    if (!attestation || !fresh || !driverId) {
+        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
+    }
+    if (attestation.driver !== driverId) {
+        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
+    }
+    if (!attestsWorkspaceMountIsolation(attestation)) {
+        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
+    }
+    return null;
+}
+async function probeDirtyGitFileCheckpoint(context) {
+    const signals = ['git_repository', 'dirty_git_worktree'];
+    if (!(await isGitWorktreeAvailable(context.repoRoot))) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            reason: 'git_worktree_unavailable',
+            signals: ['git_repository'],
+        };
+    }
+    if (!(await isDirtyWorktree(context.repoRoot, { ignoreRoots: context.dirtyIgnoreRoots }))) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            reason: 'clean_git_worktree',
+            signals: ['git_repository', 'clean_git_worktree'],
+        };
+    }
+    if (!context.fileCheckpoint.enabled) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            reason: FILE_CHECKPOINT_DISABLED,
+            signals,
+        };
+    }
+    if (!context.durableCheckpointEnabled) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            reason: FILE_CHECKPOINT_DURABLE_REQUIRED,
+            signals,
+        };
+    }
+    const isolationReason = fileCheckpointIsolationReason(context);
+    if (isolationReason) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            reason: isolationReason,
+            signals: [...signals, 'isolation_unavailable'],
+        };
+    }
+    const copyStrategy = await probeFileCloneStrategy();
+    return {
+        eligible: true,
+        backend: 'file_checkpoint',
+        signals: [...signals, 'dirty_git_file_checkpoint', copyStrategy],
+    };
+}
+async function protectedRootState(root) {
+    const node = await readSnapshotNode(root);
+    if (node.kind !== 'directory') {
+        return `${node.kind}:${node.kind === 'absent' ? '' : node.hash}`;
+    }
+    const index = await buildFileTreeIndex({ resourceRoot: root });
+    return `directory:${node.hash}:${index.treeHash}`;
+}
+function executionProtectedRoot(resourceRoot, executionRoot, protectedRoot) {
+    const relative = path.relative(path.resolve(resourceRoot), path.resolve(protectedRoot));
+    if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
+        return null;
+    }
+    return path.join(executionRoot, relative);
+}
+async function captureProtectedRootStates(resourceRoot, executionRoot, protectedRoots) {
+    const states = new Map();
+    for (const protectedRoot of protectedRoots) {
+        const executionPath = executionProtectedRoot(resourceRoot, executionRoot, protectedRoot);
+        if (executionPath) {
+            states.set(executionPath, await protectedRootState(executionPath));
+        }
+    }
+    return states;
+}
+async function directoryByteSize(root, deadlineMs) {
+    if (Date.now() > deadlineMs) {
+        throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_PREPARE_TIMEOUT, `workspace accounting exceeded deadlineMs=${deadlineMs}`);
+    }
+    const info = await lstat(root);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+        return info.size;
+    }
+    let total = 0;
+    for (const name of await readdir(root)) {
+        total += await directoryByteSize(path.join(root, name), deadlineMs);
+    }
+    return total;
+}
+async function copyGitMetadataDirectory(sourceRoot, destinationRoot) {
+    const gitDirRel = (await execGit(sourceRoot, ['rev-parse', '--git-dir'])).trim();
+    const sourceGitDir = path.isAbsolute(gitDirRel) ? gitDirRel : path.join(sourceRoot, gitDirRel);
+    const relativeGitDir = path.relative(path.resolve(sourceRoot), path.resolve(sourceGitDir));
+    const destinationGitDir = relativeGitDir && !relativeGitDir.startsWith('..')
+        ? path.join(destinationRoot, relativeGitDir)
+        : path.join(destinationRoot, '.git');
+    await cp(sourceGitDir, destinationGitDir, { recursive: true, force: true });
+}
+async function prepareDirtyGitSnapshot(context) {
+    const prepareStartedAt = Date.now();
+    const excludedRoots = context.dirtyIgnoreRoots ?? [];
+    const quotas = context.fileCheckpoint;
+    const deadlineMs = Date.now() + quotas.prepareTimeoutMs;
+    await removeDeadOwnerStaging(os.tmpdir());
+    const stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'belay-file-checkpoint-'));
+    await writeOwnerMarker(stagingRoot, {
+        version: 1,
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        resourceRoot: context.repoRoot,
+        backend: 'file_checkpoint',
+    });
+    const baselineRoot = path.join(stagingRoot, 'baseline');
+    const executionRoot = path.join(stagingRoot, 'execution');
+    try {
+        resolveExecutionCwdRelative(context.repoRoot, context.cwd);
+        const sourceGitMetadataFingerprint = await computeGitMetadataFingerprint(context.repoRoot);
+        await cloneBareWorktreeCopy(context.repoRoot, baselineRoot);
+        await removeAllGitRemotes(baselineRoot);
+        const baselineCopy = await cloneDirectoryTree(context.repoRoot, baselineRoot, {
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        await copyGitIndexState(context.repoRoot, baselineRoot);
+        const baselineIndex = await buildFileTreeIndex({
+            resourceRoot: baselineRoot,
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        const sourceIndex = await buildFileTreeIndex({
+            resourceRoot: context.repoRoot,
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        if (sourceIndex.treeHash !== baselineIndex.treeHash) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+        }
+        if ((await computeGitMetadataFingerprint(context.repoRoot)) !== sourceGitMetadataFingerprint) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+        }
+        await writeFile(path.join(stagingRoot, 'baseline-index.json'), `${JSON.stringify(baselineIndex)}\n`, 'utf8');
+        const executionCopy = await cloneDirectoryTree(baselineRoot, executionRoot, {
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        await copyGitMetadataDirectory(baselineRoot, executionRoot);
+        const gitMetadataFingerprint = await computeGitMetadataFingerprint(executionRoot);
+        const protectedRootStates = await captureProtectedRootStates(context.repoRoot, executionRoot, excludedRoots);
+        const workspaceBytes = await directoryByteSize(stagingRoot, deadlineMs);
+        if (workspaceBytes > quotas.maxWorkspaceBytes) {
+            throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_QUOTA_EXCEEDED, `snapshot workspaceBytes=${workspaceBytes} exceeds maxWorkspaceBytes=${quotas.maxWorkspaceBytes}`);
+        }
+        return {
+            stagingRoot,
+            baselineRoot,
+            executionRoot,
+            baselineIndex,
+            sourceGitMetadataFingerprint,
+            gitMetadataFingerprint,
+            copyStrategy: executionCopy.strategy === baselineCopy.strategy ? executionCopy.strategy : 'copy',
+            workspaceBytes,
+            prepareMs: Date.now() - prepareStartedAt,
+            protectedRootStates,
+        };
+    }
+    catch (error) {
+        await rm(stagingRoot, { recursive: true, force: true });
+        if (error instanceof FileCheckpointDiagnosticError) {
+            throw error;
+        }
+        if (error instanceof Error && error.message === FILE_CHECKPOINT_CWD_OUTSIDE_ROOT) {
+            throw error;
+        }
+        if (error instanceof Error && error.message === FILE_CHECKPOINT_SOURCE_CHANGED) {
+            throw error;
+        }
+        throw new Error(error instanceof Error ? error.message : FILE_CHECKPOINT_PREPARE_FAILED, {
+            cause: error,
+        });
+    }
+}
+export const fileCheckpointBackend = {
+    id: 'file_checkpoint',
+    probe: probeDirtyGitFileCheckpoint,
+    async prepare(context) {
+        const probe = await probeDirtyGitFileCheckpoint(context);
+        if (!probe.eligible) {
+            throw new Error(probe.reason ?? FILE_CHECKPOINT_PREPARE_FAILED);
+        }
+        const prepared = await prepareDirtyGitSnapshot(context);
+        const executionCwdRelative = resolveExecutionCwdRelative(context.repoRoot, context.cwd);
+        const resourceIdentity = await currentRecoveryResourceIdentity(context.repoRoot, 'git_repository');
+        return {
+            backend: 'file_checkpoint',
+            resourceRoot: context.repoRoot,
+            executionRoot: prepared.executionRoot,
+            baselineRoot: prepared.baselineRoot,
+            resourceKind: 'git_repository',
+            resourceIdentity,
+            baselineTreeHash: prepared.baselineIndex.treeHash,
+            excludedRoots: context.dirtyIgnoreRoots ?? [],
+            copyStrategy: prepared.copyStrategy,
+            snapshotFileCount: prepared.baselineIndex.fileCount,
+            snapshotSourceBytes: prepared.baselineIndex.totalFileBytes,
+            snapshotWorkspaceBytes: prepared.workspaceBytes,
+            snapshotPrepareMs: prepared.prepareMs,
+            executionCwdRelative,
+            async validateSourceState() {
+                const sourceIndex = await buildFileTreeIndex({
+                    resourceRoot: context.repoRoot,
+                    excludedRoots: context.dirtyIgnoreRoots ?? [],
+                    quotas: context.fileCheckpoint,
+                });
+                if (sourceIndex.treeHash !== prepared.baselineIndex.treeHash ||
+                    (await computeGitMetadataFingerprint(context.repoRoot)) !==
+                        prepared.sourceGitMetadataFingerprint) {
+                    throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+                }
+            },
+            async collectChanges() {
+                const afterFingerprint = await computeGitMetadataFingerprint(prepared.executionRoot);
+                if (afterFingerprint !== prepared.gitMetadataFingerprint) {
+                    throw new Error(FILE_CHECKPOINT_GIT_METADATA_CHANGED);
+                }
+                for (const [protectedRoot, before] of prepared.protectedRootStates) {
+                    if ((await protectedRootState(protectedRoot)) !== before) {
+                        throw new Error(FILE_CHECKPOINT_PROTECTED_PATH_CHANGED);
+                    }
+                }
+                const executionIndex = await buildFileTreeIndex({
+                    resourceRoot: prepared.executionRoot,
+                    excludedRoots: context.dirtyIgnoreRoots ?? [],
+                    quotas: context.fileCheckpoint,
+                });
+                const observed = diffFileTreeIndices(prepared.baselineIndex, executionIndex);
+                return observed.map((change) => ({
+                    relativePath: change.relativePath,
+                    kind: change.kind,
+                }));
+            },
+            async cleanup() {
+                await rm(prepared.stagingRoot, { recursive: true, force: true });
+            },
+        };
+    },
+};

package/dist/core/transactional/file-checkpoint-git.d.ts

@@ -0,0 +1,11 @@
+export declare const FILE_CHECKPOINT_GIT_METADATA_CHANGED = "file_checkpoint_git_metadata_changed";
+export declare const FILE_CHECKPOINT_SOURCE_CHANGED = "file_checkpoint_source_changed";
+export declare const FILE_CHECKPOINT_CWD_OUTSIDE_ROOT = "file_checkpoint_cwd_outside_root";
+export declare const FILE_CHECKPOINT_PREPARE_FAILED = "file_checkpoint_prepare_failed";
+export declare const FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED = "file_checkpoint_split_index_unsupported";
+export declare function execGit(repoRoot: string, args: string[]): Promise<string>;
+export declare function cloneBareWorktreeCopy(sourceRoot: string, destinationRoot: string): Promise<void>;
+export declare function removeAllGitRemotes(repoRoot: string): Promise<void>;
+export declare function copyGitIndexState(sourceRoot: string, destinationRoot: string): Promise<void>;
+export declare function computeGitMetadataFingerprint(repoRoot: string): Promise<string>;
+export declare function resolveExecutionCwdRelative(resourceRoot: string, cwd: string): string;

package/dist/core/transactional/file-checkpoint-git.js

@@ -0,0 +1,217 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFile, lstat, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalPath } from '../path-utils.js';
+export const FILE_CHECKPOINT_GIT_METADATA_CHANGED = 'file_checkpoint_git_metadata_changed';
+export const FILE_CHECKPOINT_SOURCE_CHANGED = 'file_checkpoint_source_changed';
+export const FILE_CHECKPOINT_CWD_OUTSIDE_ROOT = 'file_checkpoint_cwd_outside_root';
+export const FILE_CHECKPOINT_PREPARE_FAILED = 'file_checkpoint_prepare_failed';
+export const FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED = 'file_checkpoint_split_index_unsupported';
+export function execGit(repoRoot, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['-C', repoRoot, ...args], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+        child.stderr.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(Buffer.concat(stdout).toString('utf8'));
+                return;
+            }
+            reject(new Error(`git ${args.join(' ')} failed (${code}): ${Buffer.concat(stderr).toString('utf8').trim()}`));
+        });
+    });
+}
+async function resolveGitPath(repoRoot, gitPath) {
+    const trimmed = gitPath.trim();
+    if (path.isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return path.join(repoRoot, trimmed);
+}
+export async function cloneBareWorktreeCopy(sourceRoot, destinationRoot) {
+    await execGit(sourceRoot, [
+        'clone',
+        '--local',
+        '--no-hardlinks',
+        '--no-checkout',
+        sourceRoot,
+        destinationRoot,
+    ]);
+}
+export async function removeAllGitRemotes(repoRoot) {
+    const remotes = (await execGit(repoRoot, ['remote']))
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    for (const remote of remotes) {
+        await execGit(repoRoot, ['remote', 'remove', remote]);
+    }
+}
+export async function copyGitIndexState(sourceRoot, destinationRoot) {
+    const sourceIndex = await resolveGitPath(sourceRoot, await execGit(sourceRoot, ['rev-parse', '--git-path', 'index']));
+    const destinationIndex = await resolveGitPath(destinationRoot, await execGit(destinationRoot, ['rev-parse', '--git-path', 'index']));
+    await copyFile(sourceIndex, destinationIndex);
+    let sharedIndex;
+    try {
+        sharedIndex = (await execGit(sourceRoot, ['rev-parse', '--shared-index-path'])).trim();
+    }
+    catch {
+        return;
+    }
+    if (!sharedIndex) {
+        return;
+    }
+    const sourceShared = await resolveGitPath(sourceRoot, sharedIndex);
+    const destinationGitDir = await resolveGitPath(destinationRoot, await execGit(destinationRoot, ['rev-parse', '--git-dir']));
+    const destinationShared = path.join(destinationGitDir, path.basename(sourceShared));
+    try {
+        await copyFile(sourceShared, destinationShared);
+    }
+    catch (error) {
+        throw new Error(FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED, { cause: error });
+    }
+}
+async function readGitFile(gitDir, relativePath) {
+    try {
+        return await readFile(path.join(gitDir, relativePath));
+    }
+    catch {
+        return null;
+    }
+}
+async function readAbsoluteGitFile(absolutePath) {
+    try {
+        return await readFile(absolutePath);
+    }
+    catch {
+        return null;
+    }
+}
+function hashGitFileContent(hash, label, content) {
+    hash.update(label.replace(/\\/g, '/'));
+    hash.update('\0');
+    hash.update(content);
+    hash.update('\0');
+}
+async function hashResolvedGitPath(repoRoot, gitDir, gitPath, hash) {
+    try {
+        const resolved = await resolveGitPath(repoRoot, await execGit(repoRoot, ['rev-parse', '--git-path', gitPath]));
+        const relative = path.resolve(resolved).startsWith(path.resolve(gitDir))
+            ? path.relative(gitDir, resolved)
+            : resolved;
+        const content = typeof relative === 'string' && !relative.startsWith('..') && !path.isAbsolute(relative)
+            ? await readGitFile(gitDir, relative)
+            : await readAbsoluteGitFile(resolved);
+        if (content !== null) {
+            hashGitFileContent(hash, gitPath, content);
+        }
+    }
+    catch {
+        // optional git-path
+    }
+}
+async function hashGitTree(gitDir, relativeDir, hash) {
+    let names;
+    try {
+        names = await readdir(path.join(gitDir, relativeDir));
+    }
+    catch {
+        return;
+    }
+    for (const name of names.sort()) {
+        const relativePath = relativeDir ? path.join(relativeDir, name) : name;
+        const absolutePath = path.join(gitDir, relativePath);
+        let childNames = null;
+        try {
+            childNames = await readdir(absolutePath);
+        }
+        catch {
+            childNames = null;
+        }
+        if (childNames) {
+            await hashGitTree(gitDir, relativePath, hash);
+            continue;
+        }
+        const content = await readGitFile(gitDir, relativePath);
+        if (content !== null) {
+            hash.update(relativePath.replace(/\\/g, '/'));
+            hash.update('\0');
+            hash.update(content);
+            hash.update('\0');
+        }
+    }
+}
+export async function computeGitMetadataFingerprint(repoRoot) {
+    const gitDirRel = (await execGit(repoRoot, ['rev-parse', '--git-dir'])).trim();
+    const gitDir = path.isAbsolute(gitDirRel) ? gitDirRel : path.join(repoRoot, gitDirRel);
+    const hash = createHash('sha256');
+    for (const file of [
+        'HEAD',
+        'config',
+        'index',
+        'packed-refs',
+        'COMMIT_EDITMSG',
+        'MERGE_HEAD',
+        'CHERRY_PICK_HEAD',
+        'ORIG_HEAD',
+        'FETCH_HEAD',
+        'REBASE_HEAD',
+    ]) {
+        const content = await readGitFile(gitDir, file);
+        if (content !== null) {
+            hashGitFileContent(hash, file, content);
+        }
+    }
+    try {
+        const sharedIndex = (await execGit(repoRoot, ['rev-parse', '--shared-index-path'])).trim();
+        if (sharedIndex) {
+            const resolved = await resolveGitPath(repoRoot, sharedIndex);
+            const relative = path.relative(gitDir, resolved);
+            const content = relative && !relative.startsWith('..') && !path.isAbsolute(relative)
+                ? await readGitFile(gitDir, relative)
+                : await readAbsoluteGitFile(resolved);
+            if (content !== null) {
+                hashGitFileContent(hash, 'shared-index', content);
+            }
+        }
+    }
+    catch {
+        // no split index
+    }
+    for (const gitPath of ['commondir', 'gitdir']) {
+        await hashResolvedGitPath(repoRoot, gitDir, gitPath, hash);
+    }
+    try {
+        const rootGitPath = path.join(repoRoot, '.git');
+        const rootGitInfo = await lstat(rootGitPath);
+        if (rootGitInfo.isFile()) {
+            const content = await readAbsoluteGitFile(rootGitPath);
+            if (content !== null) {
+                hashGitFileContent(hash, '.git', content);
+            }
+        }
+    }
+    catch {
+        // not a linked worktree
+    }
+    await hashGitTree(gitDir, 'refs', hash);
+    return hash.digest('hex');
+}
+export function resolveExecutionCwdRelative(resourceRoot, cwd) {
+    const resolvedCwd = canonicalPath(cwd);
+    const resourceCanonical = canonicalPath(resourceRoot);
+    const relative = path.relative(resourceCanonical, resolvedCwd);
+    if (relative === '' || relative === '.') {
+        return '';
+    }
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(FILE_CHECKPOINT_CWD_OUTSIDE_ROOT);
+    }
+    return relative.split(path.sep).join('/');
+}

package/dist/core/transactional/file-checkpoint-staging.d.ts

@@ -0,0 +1,13 @@
+export interface FileCheckpointOwnerMarker {
+    version: 1;
+    pid: number;
+    createdAt: string;
+    resourceRoot: string;
+    backend: 'file_checkpoint';
+}
+export declare function isOwnerProcessAlive(pid: number): boolean;
+export declare function writeOwnerMarker(stagingRoot: string, marker: FileCheckpointOwnerMarker): Promise<void>;
+export declare function readOwnerMarker(stagingRoot: string): Promise<FileCheckpointOwnerMarker | null>;
+/** Returns staging directories whose owner process is no longer alive. */
+export declare function collectDeadOwnerStaging(parentDir: string): Promise<string[]>;
+export declare function removeDeadOwnerStaging(parentDir: string): Promise<string[]>;

package/dist/core/transactional/file-checkpoint-staging.js

@@ -0,0 +1,54 @@
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export function isOwnerProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function writeOwnerMarker(stagingRoot, marker) {
+    await writeFile(path.join(stagingRoot, 'owner.json'), `${JSON.stringify(marker)}\n`, 'utf8');
+}
+export async function readOwnerMarker(stagingRoot) {
+    try {
+        const raw = await readFile(path.join(stagingRoot, 'owner.json'), 'utf8');
+        return JSON.parse(raw.trim());
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns staging directories whose owner process is no longer alive. */
+export async function collectDeadOwnerStaging(parentDir) {
+    let names;
+    try {
+        names = await readdir(parentDir);
+    }
+    catch {
+        return [];
+    }
+    const dead = [];
+    for (const name of names) {
+        if (!name.startsWith('belay-file-checkpoint-')) {
+            continue;
+        }
+        const stagingRoot = path.join(parentDir, name);
+        const marker = await readOwnerMarker(stagingRoot);
+        if (!marker) {
+            dead.push(stagingRoot);
+            continue;
+        }
+        if (!isOwnerProcessAlive(marker.pid)) {
+            dead.push(stagingRoot);
+        }
+    }
+    return dead;
+}
+export async function removeDeadOwnerStaging(parentDir) {
+    const dead = await collectDeadOwnerStaging(parentDir);
+    await Promise.all(dead.map((stagingRoot) => rm(stagingRoot, { recursive: true, force: true })));
+    return dead;
+}

package/dist/core/transactional/file-clone.d.ts

@@ -0,0 +1,15 @@
+import type { BelayFileCheckpointConfig } from '../config.js';
+import { buildFileTreeIndex } from './file-tree.js';
+export declare const FILE_CHECKPOINT_COPY_FAILED = "file_checkpoint_copy_failed";
+export type FileCloneStrategy = 'clonefile' | 'reflink' | 'copy';
+export interface FileCloneOptions {
+    excludedRoots?: string[];
+    quotas?: Pick<BelayFileCheckpointConfig, 'maxFiles' | 'maxSourceBytes' | 'maxWorkspaceBytes' | 'prepareTimeoutMs' | 'copyConcurrency'>;
+    deadlineMs?: number;
+}
+export interface FileCloneResult {
+    strategy: FileCloneStrategy;
+    sourceIndex: Awaited<ReturnType<typeof buildFileTreeIndex>>;
+}
+export declare function cloneDirectoryTree(sourceRoot: string, destinationRoot: string, options?: FileCloneOptions): Promise<FileCloneResult>;
+export declare function probeFileCloneStrategy(): Promise<FileCloneStrategy>;