@tickernelz/paperclip-pro-adapter-utils 2026.1006.0 → 2026.1006.2

package/dist/workspace-restore-merge.js

@@ -1,9 +1,33 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { constants as fsConstants, promises as fs } from "node:fs";
 import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { createWorkspaceManifest, WorkspaceManifestMap, workspacePathMatcher } from "./workspace-manifest.js";
 import { shouldExcludePath } from "./exclude-patterns.js";
 import { resolvePaperclipInstanceRootForAdapter } from "./server-utils.js";
+const ownedDirectorySnapshots = new WeakMap();
+export async function disposeDirectorySnapshot(snapshot) {
+    if (!snapshot)
+        return;
+    if (snapshot.entries instanceof WorkspaceManifestMap) {
+        snapshot.entries.close();
+        const ownedDirectory = ownedDirectorySnapshots.get(snapshot);
+        ownedDirectorySnapshots.delete(snapshot);
+        if (ownedDirectory)
+            await fs.rm(ownedDirectory, { recursive: true, force: true });
+    }
+}
+function parseManifestEntry(value) {
+    const result = parseSnapshotEntry(JSON.parse(value));
+    if (!result)
+        throw new Error("Invalid workspace baseline entry");
+    return result;
+}
+/** Call only after the controller validates a persisted manifest's path and digest. */
+export function openDirectorySnapshot(value) {
+    return { exclude: value.exclude, entries: new WorkspaceManifestMap(value.entries, parseManifestEntry), ignoredPaths: value.ignoredPaths };
+}
 function isSafeSnapshotRelativePath(value) {
     if (!value || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)) {
         return false;
@@ -30,6 +54,11 @@ function parseSnapshotEntry(value) {
     return null;
 }
 export function serializeDirectorySnapshot(snapshot) {
+    if (snapshot.entries instanceof WorkspaceManifestMap)
+        return {
+            version: 2, exclude: [...snapshot.exclude], entries: snapshot.entries.manifest,
+            ...(snapshot.ignoredPaths ? { ignoredPaths: snapshot.ignoredPaths } : {}),
+        };
     return {
         version: 1,
         exclude: [...snapshot.exclude],
@@ -65,9 +94,13 @@ export function parseDirectorySnapshot(value) {
     };
 }
 export function directorySnapshotSha256(snapshot) {
-    return createHash("sha256")
-        .update(JSON.stringify(serializeDirectorySnapshot(snapshot)))
-        .digest("hex");
+    if (!(snapshot.entries instanceof WorkspaceManifestMap))
+        return createHash("sha256")
+            .update(JSON.stringify(serializeDirectorySnapshot(snapshot))).digest("hex");
+    const digest = createHash("sha256").update("workspace-baseline-v2\0").update(JSON.stringify(snapshot.exclude));
+    for (const entry of snapshot.entries)
+        digest.update(JSON.stringify(entry)).update("\0");
+    return digest.digest("hex");
 }
 async function hashFile(filePath) {
     return await new Promise((resolve, reject) => {
@@ -78,38 +111,25 @@ async function hashFile(filePath) {
         stream.on("end", () => resolve(hash.digest("hex")));
     });
 }
-async function walkDirectory(root, exclude, relative = "", out = new Map()) {
+async function* walkDirectory(root, exclude, ignored, relative = "") {
     const current = relative ? path.join(root, relative) : root;
-    const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
-    entries.sort((left, right) => left.name.localeCompare(right.name));
-    for (const entry of entries) {
+    for await (const entry of await fs.opendir(current)) {
         const nextRelative = relative ? path.posix.join(relative, entry.name) : entry.name;
-        if (shouldExcludePath(nextRelative, exclude))
+        if (shouldExcludePath(nextRelative, exclude) || ignored.matches(nextRelative))
             continue;
         const fullPath = path.join(root, nextRelative);
         const stats = await fs.lstat(fullPath);
-        if (!stats.isDirectory() && !stats.isSymbolicLink() && !stats.isFile()) {
-            continue;
-        }
         if (stats.isDirectory()) {
-            out.set(nextRelative, { kind: "dir" });
-            await walkDirectory(root, exclude, nextRelative, out);
-            continue;
+            yield [nextRelative, { kind: "dir" }];
+            yield* walkDirectory(root, exclude, ignored, nextRelative);
         }
-        if (stats.isSymbolicLink()) {
-            out.set(nextRelative, {
-                kind: "symlink",
-                target: await fs.readlink(fullPath),
-            });
-            continue;
+        else if (stats.isSymbolicLink()) {
+            yield [nextRelative, { kind: "symlink", target: await fs.readlink(fullPath) }];
+        }
+        else if (stats.isFile()) {
+            yield [nextRelative, { kind: "file", mode: stats.mode, hash: await hashFile(fullPath) }];
         }
-        out.set(nextRelative, {
-            kind: "file",
-            mode: stats.mode,
-            hash: await hashFile(fullPath),
-        });
     }
-    return out;
 }
 async function readSnapshotEntry(root, relative) {
     const fullPath = path.join(root, relative);
@@ -151,7 +171,69 @@ function entriesMatch(left, right) {
     }
     return false;
 }
-const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 30_000;
+const LOCK_DIAGNOSTIC_READ_TIMEOUT_MS = 100;
+const activeDirectoryMergeLocks = new Set();
+const MAX_LOCK_DIAGNOSTIC_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Evidence only: neither process age nor this module's holder set can prove
+ * that a lock in another process or PID namespace is safe to reclaim. */
+async function directoryMergeLockDiagnostics(lockDir, waitMs, ownerPath) {
+    const diagnostics = {
+        ownerState: "unknown",
+        knownLocalHolder: activeDirectoryMergeLocks.has(lockDir),
+        waitMs: Math.min(MAX_LOCK_DIAGNOSTIC_AGE_MS, Math.max(0, Math.floor(waitMs))),
+    };
+    const controller = new AbortController();
+    let timeout;
+    try {
+        // Abort is best effort: race the read as well so a stalled filesystem
+        // cannot keep the original lock timeout from reaching its caller.
+        const raw = await Promise.race([
+            fs.readFile(ownerPath, { encoding: "utf8", signal: controller.signal }),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => resolve(undefined), LOCK_DIAGNOSTIC_READ_TIMEOUT_MS);
+            }),
+        ]);
+        if (raw === undefined)
+            return diagnostics;
+        let owner;
+        try {
+            owner = JSON.parse(raw);
+        }
+        catch {
+            diagnostics.ownerState = "invalid";
+            return diagnostics;
+        }
+        if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) {
+            diagnostics.ownerState = "invalid";
+            return diagnostics;
+        }
+        const pid = owner.pid;
+        diagnostics.ownerSameProcess = pid === process.pid;
+        try {
+            process.kill(pid, 0);
+            diagnostics.ownerState = "alive";
+        }
+        catch (error) {
+            diagnostics.ownerState = error.code === "ESRCH" ? "dead" : "unknown";
+        }
+        const createdAt = typeof owner.createdAt === "string" ? Date.parse(owner.createdAt) : NaN;
+        const ageMs = Date.now() - createdAt;
+        if (Number.isFinite(ageMs) && ageMs >= 0) {
+            diagnostics.ownerAgeMs = Math.min(MAX_LOCK_DIAGNOSTIC_AGE_MS, Math.floor(ageMs));
+            if (pid === process.pid)
+                diagnostics.ownerPredatesProcess = ageMs > process.uptime() * 1000 + 1000;
+        }
+    }
+    catch (error) {
+        diagnostics.ownerState = error.code === "ENOENT" ? "missing" : "unknown";
+    }
+    finally {
+        clearTimeout(timeout);
+        controller.abort();
+    }
+    return diagnostics;
+}
 /**
  * The stable `code` a lock-timeout error carries, so a caller can identify it
  * without matching on the error message text (the message embeds the lock
@@ -163,8 +245,9 @@ export const WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE = "ERR_WORKSPACE_RESTORE_LOCK_T
  * `EACCES` and `EPERM` to a permission failure, the merge-lock timeout
  * (matched by {@link WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE}, never by the error
  * message text) to a lock-timeout failure, and every other error to a generic
- * failure. Never reads or returns `Error.message`, a filesystem path, or a
- * process id.
+ * failure. The known Daytona confinement diagnostic also identifies unsafe
+ * archives across plugin transports that retain only a message. Never returns
+ * raw messages, paths or process IDs.
  */
 export function classifyWorkspaceRestoreFailure(error) {
     const code = error && typeof error === "object" ? error.code : undefined;
@@ -172,6 +255,16 @@ export function classifyWorkspaceRestoreFailure(error) {
         return "restore_permission_denied";
     if (code === WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE)
         return "restore_lock_timeout";
+    const message = error instanceof Error ? error.message : "";
+    const archiveRefused = /Daytona syncOut refusing (?:tarball (?:with an unparseable entry listing|(?:link whose target|member that) escapes the extraction dir)|unparseable or ambiguous (?:sym|hard)link entry)/.test(message);
+    const outboundPathRefused = /Daytona sync source path (?:is not a confined absolute path|escapes the workspace remote dir):/.test(message);
+    // These are the fail-closed guard's own exit codes. Transport/command failures
+    // with other exit codes retain the existing transient failure policy.
+    const outboundGuardRefused = /Daytona outbound symlink-escape guard command failed \(exit (?:40|41|42|44|45)\)/.test(message);
+    if (code === "WORKSPACE_RESTORE_UNSAFE_ARCHIVE" ||
+        archiveRefused || outboundPathRefused || outboundGuardRefused) {
+        return "restore_unsafe_archive";
+    }
     return "restore_failed";
 }
 /**
@@ -188,67 +281,99 @@ export function describeWorkspaceRestoreFailure(code) {
             return "the restore could not write to the workspace (permission denied)";
         case "restore_lock_timeout":
             return "the restore timed out waiting for the workspace merge lock";
+        case "restore_unsafe_archive":
+            return "the archive contains an unsafe link or path; workspace repair is required";
         case "restore_failed":
             return "the restore failed";
     }
 }
-async function isLockStale(lockDir) {
-    try {
-        const raw = await fs.readFile(path.join(lockDir, "owner.json"), "utf8");
-        const owner = JSON.parse(raw);
-        const pid = typeof owner.pid === "number" && Number.isFinite(owner.pid) && owner.pid > 0 ? owner.pid : null;
-        if (pid === null) {
-            // Owner record is unparseable / missing pid — treat as stale.
-            return true;
-        }
-        try {
-            process.kill(pid, 0);
-            return false;
-        }
-        catch {
-            return true;
+async function acquireDirectoryMergeLock(lockDir, operation, waitMs = LOCK_WAIT_MS) {
+    const startedAt = performance.now();
+    const deadline = Date.now() + waitMs;
+    const databasePath = `${lockDir}.sqlite`;
+    const ownerPath = `${lockDir}.owner.json`;
+    async function waitForLock(diagnosticOwnerPath) {
+        if (Date.now() >= deadline) {
+            const timeoutError = new Error(`Timed out waiting for workspace restore lock at ${lockDir}`);
+            timeoutError.code = WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE;
+            // Keep the original timeout if the diagnostic read itself fails.
+            timeoutError.workspaceRestoreLock = await directoryMergeLockDiagnostics(lockDir, performance.now() - startedAt, diagnosticOwnerPath).catch(() => undefined);
+            if (operation && timeoutError.workspaceRestoreLock)
+                timeoutError.workspaceRestoreLock.operation = operation;
+            throw timeoutError;
         }
+        await new Promise((resolve) => setTimeout(resolve, 50));
     }
-    catch {
-        // owner.json is missing or unreadable. A live holder also passes through
-        // this exact state, briefly, between its own `fs.mkdir(lockDir)` and its
-        // `fs.writeFile(owner.json)` below. Reading "missing" as "stale" here would
-        // let a concurrent acquirer delete a live holder's lock directory during
-        // that window. Mirror the materializePaperclipSkillCopy lock pattern: fall
-        // back to the lock directory's own mtime, and only call it stale once the
-        // directory itself has outlived the stale threshold.
-        const stat = await fs.stat(lockDir).catch(() => null);
-        return !stat || Date.now() - stat.mtimeMs > LOCK_STALE_MS;
+    // SQLite's RESERVED file lock is the authority, including across processes
+    // and PID namespaces. It is released by the OS on a crash. The empty database
+    // is permanent: unlinking it would let contenders lock different inodes.
+    // node:sqlite is already required for workspace manifests; no native add-on
+    // or external flock command is needed on macOS, Linux, or Windows.
+    const databaseStat = await fs.lstat(databasePath).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (databaseStat && (!databaseStat.isFile() || databaseStat.isSymbolicLink() || databaseStat.nlink !== 1)) {
+        throw new Error("Directory merge lock database is not a plain, unshared file.");
     }
-}
-async function acquireDirectoryMergeLock(lockDir) {
-    const deadline = Date.now() + LOCK_STALE_MS;
-    while (true) {
+    // Let SQLite create and manage every descriptor for this inode. On POSIX,
+    // closing a raw fs.open descriptor could release another connection's locks.
+    // The parent is private (0700), including while a new file is chmodded.
+    const database = new DatabaseSync(databasePath, { allowExtension: false });
+    try {
+        await fs.chmod(databasePath, 0o600);
+        // Never block the event loop while another async operation holds the lock.
+        database.exec("PRAGMA busy_timeout=0;");
+        while (true) {
+            try {
+                database.exec("BEGIN IMMEDIATE;");
+                break;
+            }
+            catch (error) {
+                const code = error.errcode;
+                if (typeof code !== "number" || (code & 0xff) !== 5)
+                    throw error; // SQLITE_BUSY
+                await waitForLock(ownerPath);
+            }
+        }
+        // Old processes do not participate in the SQLite protocol. Never infer
+        // that a legacy owner is dead from PID existence, age, or missing metadata.
+        // Drain old writers before upgrading. A leftover legacy directory requires
+        // explicit offline cleanup; a live legacy holder can still release normally.
+        while (await fs.lstat(lockDir).then(() => true, (error) => {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }))
+            await waitForLock(path.join(lockDir, "owner.json"));
+        const owner = await fs.open(ownerPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | fsConstants.O_NOFOLLOW, 0o600);
         try {
-            await fs.mkdir(lockDir);
-            await fs.writeFile(path.join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
-            return async () => {
-                await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
-            };
+            await owner.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
         }
-        catch (error) {
-            const code = error && typeof error === "object" ? error.code : null;
-            if (code !== "EEXIST")
-                throw error;
-            // Stale-lock detection: if the owner PID is dead (SIGKILL / OOM / crash),
-            // the lockDir would otherwise persist forever and stall restores. Mirror
-            // the materializePaperclipSkillCopy lock pattern — remove and retry.
-            if (await isLockStale(lockDir)) {
-                await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
-                continue;
+        finally {
+            await owner.close();
+        }
+        activeDirectoryMergeLocks.add(lockDir);
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                // This sidecar is diagnostic only. A failed removal cannot retain
+                // ownership, and the next holder replaces it while holding the DB lock.
+                await fs.unlink(ownerPath).catch(() => undefined);
             }
-            if (Date.now() >= deadline) {
-                const timeoutError = new Error(`Timed out waiting for workspace restore lock at ${lockDir}`);
-                timeoutError.code = WORKSPACE_RESTORE_LOCK_TIMEOUT_CODE;
-                throw timeoutError;
+            finally {
+                activeDirectoryMergeLocks.delete(lockDir);
+                database.close();
             }
-            await new Promise((resolve) => setTimeout(resolve, 50));
-        }
+        };
+    }
+    catch (error) {
+        database.close();
+        throw error;
     }
 }
 const DIRECTORY_MERGE_LOCK_ROOT_MODE = 0o700;
@@ -316,13 +441,16 @@ async function resolveDirectoryMergeLockRoot(env = process.env) {
     }
     return lockRoot;
 }
-export async function withDirectoryMergeLock(targetDir, fn, env = process.env) {
+export async function withDirectoryMergeLock(targetDir, fn, env = process.env, diagnosticOperation, 
+// Test seam only: overrides how long acquisition waits before it reports a
+// timeout. Production callers must omit this and keep the real budget.
+waitMs = LOCK_WAIT_MS) {
     // Canonicalize before we hash or lock: a retargeted symlink must not let the
     // lock protect one directory while the caller mutates another.
     const canonicalTargetDir = await fs.realpath(targetDir);
     const lockRoot = await resolveDirectoryMergeLockRoot(env);
     const lockKey = createHash("sha256").update(canonicalTargetDir).digest("hex");
-    const releaseLock = await acquireDirectoryMergeLock(path.join(lockRoot, `${lockKey}.lock`));
+    const releaseLock = await acquireDirectoryMergeLock(path.join(lockRoot, `${lockKey}.lock`), diagnosticOperation, waitMs);
     try {
         return await fn(canonicalTargetDir);
     }
@@ -345,50 +473,190 @@ async function copySnapshotEntry(sourceDir, targetDir, relative, entry) {
         return;
     }
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    await fs.rm(targetPath, { recursive: true, force: true }).catch(() => undefined);
     if (entry.kind === "symlink") {
+        await fs.rm(targetPath, { recursive: true, force: true });
         await fs.symlink(entry.target, targetPath);
         return;
     }
-    await fs.copyFile(sourcePath, targetPath, fsConstants.COPYFILE_FICLONE).catch(async () => {
-        await fs.copyFile(sourcePath, targetPath);
-    });
-    await fs.chmod(targetPath, entry.mode);
+    // An interrupted restore must not leave a truncated current file. Keep the
+    // incoming tree until its owner records success; exact retries deduplicate.
+    const temporary = path.join(path.dirname(targetPath), `.paperclip-merge-${randomUUID()}`);
+    try {
+        await fs.copyFile(sourcePath, temporary, fsConstants.COPYFILE_FICLONE).catch(async () => {
+            await fs.copyFile(sourcePath, temporary);
+        });
+        await fs.chmod(temporary, entry.mode);
+        const file = await fs.open(temporary, "r");
+        try {
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        const existing = await fs.lstat(targetPath).catch(() => null);
+        if (existing?.isDirectory())
+            await fs.rm(targetPath, { recursive: true, force: true });
+        await fs.rename(temporary, targetPath);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
 }
 export async function captureDirectorySnapshot(rootDir, options = {}) {
     const exclude = [...new Set(options.exclude ?? [])];
-    return {
-        exclude,
-        entries: await walkDirectory(rootDir, exclude),
-    };
+    const ignored = workspacePathMatcher(options.ignoredPaths);
+    let writer = null;
+    try {
+        writer = options.diskBacked ? await createWorkspaceManifest("paperclip-workspace-baseline-") : null;
+        const memory = new Map();
+        for await (const [relative, entry] of walkDirectory(rootDir, exclude, ignored)) {
+            if (writer)
+                writer.add("baseline", relative, JSON.stringify(entry));
+            else
+                memory.set(relative, entry);
+        }
+        const manifest = writer?.paths("baseline");
+        writer?.close();
+        const snapshot = {
+            exclude, ignoredPaths: options.ignoredPaths,
+            entries: manifest ? new WorkspaceManifestMap(manifest, parseManifestEntry) : memory,
+        };
+        if (writer)
+            ownedDirectorySnapshots.set(snapshot, path.dirname(writer.filePath));
+        return snapshot;
+    }
+    catch (error) {
+        writer?.close(false);
+        if (writer)
+            await fs.rm(path.dirname(writer.filePath), { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        ignored.close();
+    }
 }
-export async function mergeDirectoryWithBaseline(input) {
-    const source = await captureDirectorySnapshot(input.sourceDir, { exclude: input.baseline.exclude });
-    await withDirectoryMergeLock(input.targetDir, async (canonicalTargetDir) => {
-        await input.beforeApply?.();
-        const current = await captureDirectorySnapshot(canonicalTargetDir, { exclude: input.baseline.exclude });
-        const deletedLeafEntries = [...input.baseline.entries.entries()]
-            .filter(([relative, entry]) => entry.kind !== "dir" && !source.entries.has(relative))
-            .sort(([left], [right]) => right.length - left.length);
-        for (const [relative, baselineEntry] of deletedLeafEntries) {
-            if (!entriesMatch(current.entries.get(relative), baselineEntry))
+/** A disk-backed subset for independent nested-repository merges. */
+export async function selectDirectorySnapshot(snapshot, options) {
+    const writer = await createWorkspaceManifest("paperclip-workspace-baseline-");
+    try {
+        for (const [relative, entry] of snapshot.entries) {
+            if (options.prefix && !relative.startsWith(options.prefix))
+                continue;
+            if (options.omit?.some((omit) => relative === omit || relative.startsWith(`${omit}/`)))
                 continue;
-            await fs.rm(path.join(canonicalTargetDir, relative), { recursive: true, force: true }).catch(() => undefined);
+            writer.add("baseline", options.prefix ? relative.slice(options.prefix.length) : relative, JSON.stringify(entry));
         }
-        const deletedDirs = [...input.baseline.entries.entries()]
-            .filter(([relative, entry]) => entry.kind === "dir" && !source.entries.has(relative))
-            .sort(([left], [right]) => right.length - left.length);
-        for (const [relative] of deletedDirs) {
-            await fs.rmdir(path.join(canonicalTargetDir, relative)).catch(() => undefined);
+        const result = { exclude: options.exclude, ignoredPaths: options.ignoredPaths,
+            entries: new WorkspaceManifestMap(writer.paths("baseline"), parseManifestEntry) };
+        writer.close();
+        ownedDirectorySnapshots.set(result, path.dirname(writer.filePath));
+        return result;
+    }
+    catch (error) {
+        writer.close(false);
+        await fs.rm(path.dirname(writer.filePath), { recursive: true, force: true });
+        throw error;
+    }
+}
+function orderedEntries(snapshot, reverse = false) {
+    if (snapshot.entries instanceof WorkspaceManifestMap)
+        return snapshot.entries.entries(reverse);
+    return [...snapshot.entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0) * (reverse ? -1 : 1));
+}
+export class DirectoryMergeConflict extends Error {
+    paths;
+    code = "DIRECTORY_MERGE_CONFLICT";
+    constructor(paths) {
+        super("Directory contents changed concurrently");
+        this.paths = paths;
+    }
+}
+/** Preflight the entire delta before writing. Identical replays are safe after
+ * an interrupted apply; unrelated edits are left alone. No history is retained. */
+export function directoryMergeConflicts(baseline, source, current) {
+    const same = (a, b) => (!a && !b) || entriesMatch(a, b);
+    const conflicts = new Set();
+    function* changedPaths() {
+        for (const [name] of baseline.entries)
+            yield name;
+        for (const [name] of source.entries)
+            if (!baseline.entries.has(name))
+                yield name;
+    }
+    for (const relative of changedPaths()) {
+        const before = baseline.entries.get(relative);
+        const incoming = source.entries.get(relative);
+        const present = current.entries.get(relative);
+        if (same(before, incoming) || same(incoming, present))
+            continue;
+        if (!same(before, present))
+            conflicts.add(relative);
+        // A parent removed/replaced by another writer must never be traversed.
+        for (let parent = path.posix.dirname(relative); parent !== "."; parent = path.posix.dirname(parent)) {
+            if (current.entries.get(parent)?.kind !== "dir" &&
+                !same(current.entries.get(parent), baseline.entries.get(parent)))
+                conflicts.add(parent);
         }
-        const changedSourceEntries = [...source.entries.entries()]
-            .filter(([relative, entry]) => !entriesMatch(input.baseline.entries.get(relative), entry))
-            .sort(([left], [right]) => left.localeCompare(right));
-        for (const [relative, entry] of changedSourceEntries) {
-            await copySnapshotEntry(input.sourceDir, canonicalTargetDir, relative, entry);
+    }
+    // Stream each current entry once. A replacement must not remove children
+    // omitted from the baseline, including excluded or newly created files.
+    for (const [child, entry] of current.entries) {
+        if (same(entry, baseline.entries.get(child)) || same(entry, source.entries.get(child)))
+            continue;
+        for (let parent = path.posix.dirname(child); parent !== "."; parent = path.posix.dirname(parent)) {
+            if (baseline.entries.get(parent)?.kind === "dir" && source.entries.get(parent)?.kind !== "dir") {
+                conflicts.add(child);
+                break;
+            }
         }
-        await input.afterApply?.();
-    });
+    }
+    return [...conflicts].sort();
+}
+export async function mergeDirectoryWithBaseline(input) {
+    const options = { exclude: input.baseline.exclude, ignoredPaths: input.baseline.ignoredPaths, diskBacked: true };
+    const source = input.snapshots?.source ?? await captureDirectorySnapshot(input.sourceDir, options);
+    try {
+        await withDirectoryMergeLock(input.targetDir, async (canonicalTargetDir) => {
+            await input.beforeApply?.();
+            // Strict preflight must see excluded children before a directory is
+            // replaced. The merge still applies only the filtered source/baseline.
+            const current = input.snapshots?.current ?? await captureDirectorySnapshot(canonicalTargetDir, input.conflictPolicy === "reject" ? { exclude: [], diskBacked: true } : options);
+            try {
+                if (input.conflictPolicy === "reject") {
+                    const conflicts = directoryMergeConflicts(input.baseline, source, current);
+                    if (conflicts.length)
+                        throw new DirectoryMergeConflict(conflicts);
+                }
+                for (const [relative, baselineEntry] of orderedEntries(input.baseline)) {
+                    if (baselineEntry.kind === "dir" || source.entries.has(relative))
+                        continue;
+                    if (!entriesMatch(current.entries.get(relative), baselineEntry))
+                        continue;
+                    await fs.rm(path.join(canonicalTargetDir, relative), { recursive: true, force: true });
+                }
+                // Reverse path order visits descendants before their parent directory.
+                for (const [relative, entry] of orderedEntries(input.baseline, true)) {
+                    if (entry.kind === "dir" && !source.entries.has(relative))
+                        await fs.rmdir(path.join(canonicalTargetDir, relative)).catch((error) => {
+                            if (error.code !== "ENOENT" && error.code !== "ENOTEMPTY" && error.code !== "ENOTDIR")
+                                throw error;
+                        });
+                }
+                for (const [relative, entry] of orderedEntries(source)) {
+                    if (!entriesMatch(input.baseline.entries.get(relative), entry) &&
+                        !(input.conflictPolicy === "reject" && entriesMatch(current.entries.get(relative), entry)))
+                        await copySnapshotEntry(input.sourceDir, canonicalTargetDir, relative, entry);
+                }
+                await input.afterApply?.();
+            }
+            finally {
+                await disposeDirectorySnapshot(current);
+            }
+        });
+    }
+    finally {
+        await disposeDirectorySnapshot(source);
+    }
 }
 export async function directoryEntryMatchesBaseline(rootDir, relative, baselineEntry) {
     return entriesMatch(await readSnapshotEntry(rootDir, relative), baselineEntry);