@ricsam/r5d-worker 0.0.132 → 0.0.133

package/dist/mjs/workspace-git-sync.mjs

@@ -6,15 +6,30 @@ import {
   workspaceMergeProjectionSupport
 } from "./workspace-merge-projection.mjs";
 import { workspaceFilesystemExecutor } from "./workspace-filesystem-executor.mjs";
+import { gitBlobHash, gitObjectHashAlgorithmFor } from "./git-blob-hash.mjs";
 import {
+  applyWorkingTreeMirror,
   captureWorkingTreeMirrorPlan,
   fsyncWorkingTreePaths,
   inspectWorkingTree,
+  inspectWorkingTreePath,
   mirrorWorkingTree,
   normalizeWorkingTreeRelativePath,
+  planPreparedWorkingTreeMirror,
   planWorkingTreeMirror,
-  restoreWorkingTreeMirrorScope
+  prepareWorkingTreeMirror,
+  restoreWorkingTreeMirrorScope,
+  rollbackWorkingTreeMirrorJournal,
+  workingTreeDisplacedRetentionDirectory,
+  WorkingTreeTargetChangedError
 } from "./working-tree-mirror.mjs";
+import {
+  decideWorkspaceHydrationMerge,
+  readHydrationBinaryPaths,
+  describeHydrationSkipPaths,
+  parseWorkspaceSubtreeChanges
+} from "./workspace-hydration-merge.mjs";
+import { WorkspaceHydrationPreBlobLedger } from "./workspace-hydration-ledger.mjs";
 import { assertManagedDirectoryPath } from "./workspace-mount-boundary.mjs";
 const WORKSPACE_GIT_BRANCH = "main";
 const MAX_WORKSPACE_GIT_DIFF_BYTES = 5 * 1024 * 1024;
@@ -22,7 +37,36 @@ const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confirm-large-diff-v
 const WORKSPACE_GIT_INTEGRATED_REF = "refs/r5d/workspace-local/integrated";
 const WORKSPACE_GIT_HYDRATED_RECEIPT = "r5d/workspace-hydrated-head";
 const WORKSPACE_GIT_HYDRATION_TRANSACTION = "r5d/workspace-hydration-transaction";
+const WORKSPACE_GIT_HYDRATION_RECOVERIES = "r5d/workspace-hydration-recoveries";
+const WORKSPACE_GIT_HYDRATION_PRESERVED_BASES = "r5d/workspace-hydration-preserved-bases";
 const WORKSPACE_GIT_CHECKOUT_DURABILITY = "r5d/workspace-checkout-durability";
+const WORKSPACE_MERGE_HYDRATION_SWITCH = "R5D_MERGE_HYDRATION";
+function workspaceMergeHydrationEnabled() {
+  return process.env[WORKSPACE_MERGE_HYDRATION_SWITCH] !== "0";
+}
+const hydrationPreBlobLedgers = /* @__PURE__ */ new Map();
+function hydrationPreBlobLedger(workspacePath) {
+  const key = path.resolve(workspacePath);
+  let ledger = hydrationPreBlobLedgers.get(key);
+  if (!ledger) {
+    ledger = new WorkspaceHydrationPreBlobLedger();
+    hydrationPreBlobLedgers.set(key, ledger);
+  }
+  return ledger;
+}
+class WorkspaceHydrationRecoveryRequiredError extends Error {
+  constructor(hydrationRecovery, options) {
+    super(
+      `Interrupted guarded workspace hydration ${hydrationRecovery.transactionId} requires explicit preservation recovery; visible files and the prior receipt are preserved, and snapshots remain at ${hydrationRecovery.transactionPath} (mounts: ${hydrationRecovery.mounts.map(({ id }) => id).join(", ")})${hydrationRecovery.mounts.some(({ retainedPaths }) => retainedPaths?.length) ? `; displaced entries retained at ${hydrationRecovery.mounts.flatMap(({ retainedPaths }) => retainedPaths ?? []).join(", ")}` : ""}`,
+      options
+    );
+    this.hydrationRecovery = hydrationRecovery;
+    this.name = "WorkspaceHydrationRecoveryRequiredError";
+  }
+  hydrationRecovery;
+  code = "hydration_recovery_required";
+}
+const HYDRATION_TRANSACTION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 function workspaceGitMountData(mount) {
   return {
     id: mount.id,
@@ -878,9 +922,8 @@ async function runWorkspaceCheckoutTransition(workspacePath, mutate) {
     await throwAfterWorkspaceCheckoutRecovery(workspacePath, error);
   }
 }
-function parseHydrationTransactionManifest(transactionPath) {
+function parseHydrationTransactionManifest(transactionPath, workspacePath = path.resolve(transactionPath, "..", "..", ".."), options = {}) {
   const manifestPath = path.join(transactionPath, "manifest.json");
-  const workspacePath = path.resolve(transactionPath, "..", "..", "..");
   const status = fs.lstatSync(manifestPath);
   if (!status.isFile() || status.isSymbolicLink()) {
     throw new Error(`Workspace hydration transaction manifest is not a regular file: ${manifestPath}`);
@@ -895,22 +938,26 @@ function parseHydrationTransactionManifest(transactionPath) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const candidate = parsed;
-  if (candidate.version !== 2 && candidate.version !== 3 && candidate.version !== 4 || !Array.isArray(candidate.mounts)) {
+  if (candidate.version !== 2 && candidate.version !== 3 && candidate.version !== 4 && candidate.version !== 5 || !Array.isArray(candidate.mounts) || candidate.preservedMounts !== void 0 && (candidate.version !== 5 || !Array.isArray(candidate.preservedMounts))) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
+  if (candidate.version === 5 && (typeof candidate.transactionId !== "string" || !HYDRATION_TRANSACTION_ID.test(candidate.transactionId))) {
+    throw new Error(`Workspace hydration transaction identity is invalid: ${manifestPath}`);
+  }
   const parseReceipt = (rawReceipt) => {
     if (rawReceipt === null) return null;
     if (!rawReceipt || typeof rawReceipt !== "object") {
       throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
     }
-    return parseWorkspaceHydrationReceiptContent(workspacePath, manifestPath, `${JSON.stringify(rawReceipt)}
-`);
+    const content = `${JSON.stringify(rawReceipt)}
+`;
+    return options.verifyReceiptCommits === false ? parseWorkspaceHydrationReceiptContentUnverified(manifestPath, content).receipt : parseWorkspaceHydrationReceiptContent(workspacePath, manifestPath, content);
   };
   const targetReceipt = parseReceipt(candidate.targetReceipt);
   const receiptBefore = parseReceipt(candidate.receiptBefore);
   const parseScope = (rawScope, existed) => {
     if (rawScope === void 0) return void 0;
-    if (candidate.version !== 4 || !existed || !rawScope || typeof rawScope !== "object") {
+    if (candidate.version !== 4 && candidate.version !== 5 || !existed || !rawScope || typeof rawScope !== "object") {
       throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
     }
     const parsePaths = (rawPaths) => {
@@ -929,7 +976,7 @@ function parseHydrationTransactionManifest(transactionPath) {
   };
   const seenIds = /* @__PURE__ */ new Set();
   const seenSnapshots = /* @__PURE__ */ new Set();
-  const mounts = candidate.mounts.map((rawMount) => {
+  const parsedMounts = [...candidate.mounts, ...candidate.preservedMounts ?? []].map((rawMount) => {
     if (!rawMount || typeof rawMount !== "object") {
       throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
     }
@@ -944,6 +991,9 @@ function parseHydrationTransactionManifest(transactionPath) {
     seenIds.add(mount.id);
     seenSnapshots.add(mount.snapshotName);
     const scope = parseScope(rawMount.scope, mount.existed);
+    if (candidate.version === 5 && mount.recovery !== "snapshot" && mount.recovery !== "guarded" || candidate.version !== 5 && mount.recovery !== void 0 || mount.recovery === "guarded" && (!mount.existed || !scope)) {
+      throw new Error(`Workspace hydration recovery policy is invalid: ${manifestPath}`);
+    }
     return {
       id: mount.id,
       incarnationKey: mount.incarnationKey,
@@ -952,16 +1002,22 @@ function parseHydrationTransactionManifest(transactionPath) {
       workspaceRelativePath: mount.workspaceRelativePath,
       existed: mount.existed,
       snapshotName: mount.snapshotName,
-      ...scope ? { scope } : {}
+      ...scope ? { scope } : {},
+      ...candidate.version === 5 ? { recovery: mount.recovery } : {}
     };
   });
   return {
-    version: candidate.version === 4 ? 4 : 3,
+    version: candidate.version === 5 ? 5 : candidate.version === 4 ? 4 : 3,
+    ...candidate.version === 5 ? { transactionId: candidate.transactionId } : {},
     targetReceipt,
     receiptBefore,
-    mounts
+    mounts: parsedMounts.slice(0, candidate.mounts.length),
+    ...candidate.preservedMounts !== void 0 ? { preservedMounts: parsedMounts.slice(candidate.mounts.length) } : {}
   };
 }
+function hydrationEvidenceMounts(manifest) {
+  return [...manifest.mounts, ...manifest.preservedMounts ?? []];
+}
 function removeHydrationTransaction(workspacePath) {
   const transactionPath = hydrationTransactionPath(workspacePath);
   fs.rmSync(transactionPath, { recursive: true, force: true });
@@ -976,7 +1032,303 @@ function hydrationTransactionCommitted(transactionPath) {
   }
   return true;
 }
+function hydrationRetainedEvidence(mount) {
+  if (!lstatIfExists(mount.sourcePath)) return null;
+  assertManagedDirectoryPath({
+    trustedRoot: mount.durabilityRootPath,
+    candidate: mount.sourcePath,
+    label: `Hydration evidence mount ${mount.id}`
+  });
+  const dotGit = path.join(mount.sourcePath, ".git");
+  if (lstatIfExists(dotGit)?.isSymbolicLink()) throw new Error(`Hydration evidence Git directory is a symlink: ${dotGit}`);
+  const directory = workingTreeDisplacedRetentionDirectory(mount.sourcePath);
+  if (!directory) return null;
+  assertManagedDirectoryPath({
+    trustedRoot: mount.durabilityRootPath,
+    candidate: directory,
+    label: `Hydration retained evidence ${mount.id}`
+  });
+  if (!lstatIfExists(directory)) return null;
+  return {
+    directory,
+    paths: fs.readdirSync(directory).sort().map((name) => path.join(directory, name))
+  };
+}
+function fsyncHydrationRetainedEvidence(mount) {
+  const evidence = hydrationRetainedEvidence(mount);
+  if (!evidence || evidence.paths.length === 0) return;
+  fsyncTree(evidence.directory);
+  for (let directory = path.dirname(evidence.directory); ; directory = path.dirname(directory)) {
+    fsyncDirectory(directory);
+    if (directory === path.resolve(mount.durabilityRootPath)) break;
+  }
+}
+function readHydrationArchivedEvidence(transactionPath, manifest) {
+  const recordPath = path.join(transactionPath, "retained-evidence.json");
+  const status = lstatIfExists(recordPath);
+  if (!status) return [];
+  if (!status.isFile() || status.isSymbolicLink()) throw new Error(`Invalid hydration retained-evidence record: ${recordPath}`);
+  const record = JSON.parse(fs.readFileSync(recordPath, "utf8"));
+  if (record.version !== 1 || !Array.isArray(record.entries)) throw new Error(`Invalid hydration retained-evidence record: ${recordPath}`);
+  const seen = /* @__PURE__ */ new Set();
+  return record.entries.map((raw) => {
+    if (!raw || typeof raw !== "object") throw new Error(`Invalid hydration retained-evidence entry: ${recordPath}`);
+    const entry = raw;
+    const mount = hydrationEvidenceMounts(manifest).find(({ id }) => id === entry.mountId);
+    const parts = typeof entry.archiveRelativePath === "string" ? entry.archiveRelativePath.split("/") : [];
+    const sourceRelative = typeof entry.sourcePath === "string" && mount ? path.relative(mount.durabilityRootPath, entry.sourcePath) : "";
+    if (!mount || typeof entry.sourcePath !== "string" || path.resolve(entry.sourcePath) !== entry.sourcePath || !sourceRelative || sourceRelative === ".." || sourceRelative.startsWith(`..${path.sep}`) || path.isAbsolute(sourceRelative) || parts.length !== 4 || parts[0] !== "displaced" || !HYDRATION_TRANSACTION_ID.test(parts[1]) || parts[2] !== mount.snapshotName || !parts[3] || parts[3] === "." || parts[3] === ".." || parts[3].includes("\\") || seen.has(entry.archiveRelativePath)) {
+      throw new Error(`Invalid hydration retained-evidence entry: ${recordPath}`);
+    }
+    const archivedPath = path.join(transactionPath, ...parts);
+    assertManagedDirectoryPath({
+      trustedRoot: transactionPath,
+      candidate: path.dirname(archivedPath),
+      label: "Archived hydration evidence"
+    });
+    if (!lstatIfExists(archivedPath)) throw new Error(`Archived hydration evidence is missing: ${archivedPath}`);
+    seen.add(entry.archiveRelativePath);
+    return { mountId: entry.mountId, sourcePath: entry.sourcePath, archiveRelativePath: entry.archiveRelativePath };
+  });
+}
+function captureHydrationRetainedEvidence(transactionPath, manifest) {
+  const entries = readHydrationArchivedEvidence(transactionPath, manifest);
+  const captureId = crypto.randomUUID();
+  let captured = false;
+  for (const mount of hydrationEvidenceMounts(manifest)) {
+    const evidence = hydrationRetainedEvidence(mount);
+    if (!evidence || evidence.paths.length === 0) continue;
+    fsyncHydrationRetainedEvidence(mount);
+    const relativeDirectory = `displaced/${captureId}/${mount.snapshotName}`;
+    const destinationDirectory = path.join(transactionPath, relativeDirectory);
+    assertManagedDirectoryPath({ trustedRoot: transactionPath, candidate: destinationDirectory, label: "Hydration evidence capture" });
+    fs.mkdirSync(destinationDirectory, { recursive: true, mode: 448 });
+    for (const sourcePath of evidence.paths) {
+      const archiveRelativePath = `${relativeDirectory}/${path.basename(sourcePath)}`;
+      fs.cpSync(sourcePath, path.join(transactionPath, archiveRelativePath), {
+        recursive: true,
+        dereference: false,
+        verbatimSymlinks: true,
+        errorOnExist: true,
+        force: false,
+        preserveTimestamps: true
+      });
+      entries.push({ mountId: mount.id, sourcePath, archiveRelativePath });
+      captured = true;
+    }
+  }
+  if (captured) {
+    fsyncTree(path.join(transactionPath, "displaced"));
+    const temporaryPath = path.join(transactionPath, `.retained-evidence.${crypto.randomUUID()}.tmp`);
+    writePrivateFileDurably(temporaryPath, `${JSON.stringify({ version: 1, entries })}
+`);
+    fs.renameSync(temporaryPath, path.join(transactionPath, "retained-evidence.json"));
+    fsyncDirectory(transactionPath);
+  }
+  return entries;
+}
+function hydrationRecoveryRequiredError(workspacePath, manifest, cause) {
+  if (manifest.version !== 5 || !manifest.transactionId) throw new Error("Guarded hydration lacks a durable transaction identity");
+  return new WorkspaceHydrationRecoveryRequiredError(
+    {
+      transactionId: manifest.transactionId,
+      transactionPath: hydrationTransactionPath(workspacePath),
+      mounts: hydrationEvidenceMounts(manifest).map(({ id, incarnationKey, sourcePath, durabilityRootPath, workspaceRelativePath }) => {
+        const retainedPaths = hydrationRetainedEvidence({ id, sourcePath, durabilityRootPath })?.paths;
+        return {
+          id,
+          incarnationKey,
+          sourcePath,
+          durabilityRootPath,
+          workspaceRelativePath,
+          ...retainedPaths?.length ? { retainedPaths } : {}
+        };
+      }),
+      receiptBefore: manifest.receiptBefore
+    },
+    cause === void 0 ? void 0 : { cause }
+  );
+}
+function runHydrationRecoveryInspectJob(input) {
+  const workspacePath = path.resolve(input.workspacePath);
+  const workspaceStatus = lstatIfExists(workspacePath);
+  if (!workspaceStatus) return null;
+  if (!workspaceStatus.isDirectory() || workspaceStatus.isSymbolicLink())
+    throw new Error(`Invalid workspace hydration root: ${workspacePath}`);
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  assertManagedDirectoryPath({
+    trustedRoot: workspacePath,
+    candidate: transactionPath,
+    label: "Workspace hydration transaction inspection"
+  });
+  const status = lstatIfExists(transactionPath);
+  if (!status) return null;
+  if (!status.isDirectory() || status.isSymbolicLink()) throw new Error(`Invalid workspace hydration transaction: ${transactionPath}`);
+  const manifest = parseHydrationTransactionManifest(transactionPath);
+  if (hydrationTransactionCommitted(transactionPath) || !manifest.mounts.some(({ recovery }) => recovery === "guarded")) return null;
+  return hydrationRecoveryRequiredError(workspacePath, manifest).hydrationRecovery;
+}
+function readPreservedHydrationBases(workspacePath) {
+  const recordPath = path.join(workspacePath, ".git", ...WORKSPACE_GIT_HYDRATION_PRESERVED_BASES.split("/"));
+  const status = lstatIfExists(recordPath);
+  if (!status) return null;
+  if (!status.isFile() || status.isSymbolicLink()) throw new Error(`Preserved hydration bases are not a regular file: ${recordPath}`);
+  return parseWorkspaceHydrationReceiptContentUnverified(recordPath, fs.readFileSync(recordPath, "utf8")).receipt;
+}
+async function readPreservedHydrationBasesAsync(workspacePath) {
+  const recordPath = path.join(workspacePath, ".git", ...WORKSPACE_GIT_HYDRATION_PRESERVED_BASES.split("/"));
+  let status;
+  try {
+    status = await fs.promises.lstat(recordPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  if (!status.isFile() || status.isSymbolicLink()) throw new Error(`Preserved hydration bases are not a regular file: ${recordPath}`);
+  return parseWorkspaceHydrationReceiptContentUnverified(recordPath, await fs.promises.readFile(recordPath, "utf8")).receipt;
+}
+function preserveHydrationBases(workspacePath, manifest) {
+  const current = readHydratedWorkspaceReceipt(workspacePath);
+  if (!workspaceHydrationReceiptsEqual(current, manifest.receiptBefore)) {
+    throw new Error(`Hydration receipt changed before preservation of transaction ${manifest.transactionId}`);
+  }
+  const previous = readPreservedHydrationBases(workspacePath);
+  const affectedIds = new Set(hydrationEvidenceMounts(manifest).map(({ id }) => id));
+  const mounts = (current?.mounts ?? []).filter(
+    (entry) => affectedIds.has(entry.id) || previous?.mounts.some(
+      (preserved) => workspaceHydrationReceiptsEqual({ version: 3, mounts: [entry] }, { version: 3, mounts: [preserved] })
+    )
+  );
+  const recordPath = path.join(workspacePath, ".git", ...WORKSPACE_GIT_HYDRATION_PRESERVED_BASES.split("/"));
+  const temporaryPath = `${recordPath}.${crypto.randomUUID()}.tmp`;
+  writePrivateFileDurably(temporaryPath, `${JSON.stringify({ version: 3, mounts })}
+`);
+  fs.renameSync(temporaryPath, recordPath);
+  fsyncDirectory(path.dirname(recordPath));
+}
+function runHydrationPreserveInterruptedJob(input) {
+  const workspacePath = path.resolve(input.workspacePath);
+  if (!HYDRATION_TRANSACTION_ID.test(input.expectedTransactionId)) throw new Error("Invalid hydration recovery transaction identity");
+  const stateDirectory = workspacePrivateStateDirectory(workspacePath);
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  const archivesPath = path.join(workspacePath, ".git", ...WORKSPACE_GIT_HYDRATION_RECOVERIES.split("/"));
+  const archivePath = path.join(archivesPath, input.expectedTransactionId);
+  assertManagedDirectoryPath({ trustedRoot: stateDirectory, candidate: archivesPath, label: "Workspace hydration archives" });
+  const pending = lstatIfExists(transactionPath);
+  if (!pending) {
+    assertManagedDirectoryPath({ trustedRoot: stateDirectory, candidate: archivePath, label: "Workspace hydration archive" });
+    if (!lstatIfExists(archivePath))
+      throw new Error(`No pending or preserved hydration transaction matches ${input.expectedTransactionId}`);
+    const archived = parseHydrationTransactionManifest(archivePath, workspacePath, { verifyReceiptCommits: false });
+    const markerPath2 = path.join(archivePath, "preserved.json");
+    const markerStatus = fs.lstatSync(markerPath2);
+    if (!markerStatus.isFile() || markerStatus.isSymbolicLink()) throw new Error(`Invalid hydration preservation record: ${markerPath2}`);
+    const marker = JSON.parse(fs.readFileSync(markerPath2, "utf8"));
+    if (archived.version !== 5 || archived.transactionId !== input.expectedTransactionId || marker.version !== 1 || marker.transactionId !== archived.transactionId) {
+      throw new Error(`Hydration archive identity does not match ${input.expectedTransactionId}`);
+    }
+    const retainedEntries2 = readHydrationArchivedEvidence(archivePath, archived).map(({ mountId, sourcePath, archiveRelativePath }) => ({
+      mountId,
+      sourcePath,
+      archivePath: path.join(archivePath, archiveRelativePath)
+    }));
+    fsyncDirectory(archivePath);
+    fsyncDirectory(archivesPath);
+    fsyncDirectory(stateDirectory);
+    return {
+      transactionId: archived.transactionId,
+      archivePath,
+      receiptBefore: archived.receiptBefore,
+      preservedMountIds: hydrationEvidenceMounts(archived).map(({ id }) => id).sort(),
+      alreadyPreserved: true,
+      ...retainedEntries2.length > 0 ? { retainedEntries: retainedEntries2 } : {}
+    };
+  }
+  if (!pending.isDirectory() || pending.isSymbolicLink()) throw new Error(`Invalid workspace hydration transaction: ${transactionPath}`);
+  const manifest = parseHydrationTransactionManifest(transactionPath);
+  if (manifest.version !== 5 || manifest.transactionId !== input.expectedTransactionId) {
+    throw new Error(
+      `Stale hydration recovery transaction identity: expected ${input.expectedTransactionId}, pending ${manifest.transactionId ?? "legacy transaction"}`
+    );
+  }
+  if (hydrationTransactionCommitted(transactionPath))
+    throw new Error(`Hydration transaction ${manifest.transactionId} is committed; ordinary recovery must finish its receipt`);
+  if (!manifest.mounts.some(({ recovery }) => recovery === "guarded"))
+    throw new Error(`Hydration transaction ${manifest.transactionId} has no interrupted guarded mounts`);
+  if (lstatIfExists(archivePath))
+    throw new Error(`Hydration archive already exists while transaction ${manifest.transactionId} is pending`);
+  if (!workspaceHydrationReceiptsEqual(readHydratedWorkspaceReceipt(workspacePath), manifest.receiptBefore)) {
+    throw new Error(`Hydration receipt changed before preservation of transaction ${manifest.transactionId}`);
+  }
+  for (const mount of hydrationEvidenceMounts(manifest)) {
+    assertManagedDirectoryPath({
+      trustedRoot: mount.durabilityRootPath,
+      candidate: mount.sourcePath,
+      label: `Hydration preservation mount ${mount.id}`
+    });
+    const source = lstatIfExists(mount.sourcePath);
+    if (mount.existed && !source) throw new Error(`Hydration preservation mount ${mount.id} is missing: ${mount.sourcePath}`);
+    const snapshotPath = path.join(transactionPath, "mounts", mount.snapshotName);
+    assertManagedDirectoryPath({
+      trustedRoot: transactionPath,
+      candidate: snapshotPath,
+      label: `Hydration preservation snapshot ${mount.id}`
+    });
+    if (!lstatIfExists(snapshotPath)) throw new Error(`Hydration preservation snapshot ${mount.id} is missing`);
+    const basis = manifest.receiptBefore?.mounts.find((entry) => entry.id === mount.id);
+    if (!basis || basis.incarnationKey !== mount.incarnationKey || basis.sourcePath !== mount.sourcePath || basis.durabilityRootPath !== mount.durabilityRootPath || basis.workspaceRelativePath !== mount.workspaceRelativePath) {
+      throw new Error(
+        `Hydration preservation mount ${mount.id} has no matching prior receipt basis; manual salvage is required. The transaction and all snapshots remain at ${transactionPath}`
+      );
+    }
+  }
+  for (const mount of hydrationEvidenceMounts(manifest)) {
+    fsyncHydratedWorkspaceMount({ ...mount, hydrationIncarnationKey: mount.incarnationKey, sourceMode: "all", hydrateDeletionMode: "all" });
+  }
+  const retainedEntries = captureHydrationRetainedEvidence(transactionPath, manifest).map(
+    ({ mountId, sourcePath, archiveRelativePath }) => ({
+      mountId,
+      sourcePath,
+      archivePath: path.join(archivePath, archiveRelativePath)
+    })
+  );
+  fsyncTree(transactionPath);
+  preserveHydrationBases(workspacePath, manifest);
+  repairWorkspaceBasisRefs(workspacePath, manifest.receiptBefore);
+  const markerPath = path.join(transactionPath, "preserved.json");
+  const markerContent = `${JSON.stringify({ version: 1, transactionId: manifest.transactionId })}
+`;
+  const existingMarker = lstatIfExists(markerPath);
+  if (existingMarker) {
+    if (!existingMarker.isFile() || existingMarker.isSymbolicLink() || fs.readFileSync(markerPath, "utf8") !== markerContent) {
+      throw new Error(`Invalid hydration preservation record: ${markerPath}`);
+    }
+  } else {
+    const markerTemporaryPath = path.join(transactionPath, `.preserved.${crypto.randomUUID()}.tmp`);
+    writePrivateFileDurably(markerTemporaryPath, markerContent);
+    fs.renameSync(markerTemporaryPath, markerPath);
+  }
+  fsyncDirectory(transactionPath);
+  if (!lstatIfExists(archivesPath)) {
+    fs.mkdirSync(archivesPath, { mode: 448 });
+    fsyncDirectory(stateDirectory);
+  }
+  fs.renameSync(transactionPath, archivePath);
+  fsyncDirectory(archivesPath);
+  fsyncDirectory(stateDirectory);
+  return {
+    transactionId: manifest.transactionId,
+    archivePath,
+    receiptBefore: manifest.receiptBefore,
+    preservedMountIds: hydrationEvidenceMounts(manifest).map(({ id }) => id).sort(),
+    alreadyPreserved: false,
+    ...retainedEntries.length > 0 ? { retainedEntries } : {}
+  };
+}
 function restoreHydrationTransaction(workspacePath, manifest) {
+  if (manifest.mounts.some(({ recovery }) => recovery === "guarded")) {
+    throw hydrationRecoveryRequiredError(workspacePath, manifest);
+  }
   const transactionPath = hydrationTransactionPath(workspacePath);
   const durabilityScopes = /* @__PURE__ */ new Map();
   for (const mount of manifest.mounts) {
@@ -1039,25 +1391,132 @@ function recoverPendingHydrationTransaction(workspacePath) {
     return;
   }
   const receipt = readHydratedWorkspaceReceipt(workspacePath);
-  if (manifest.targetReceipt && !workspaceHydrationReceiptsEqual(manifest.targetReceipt, manifest.receiptBefore) && workspaceHydrationReceiptsEqual(receipt, manifest.targetReceipt)) {
+  if (manifest.version !== 5 && manifest.targetReceipt && !workspaceHydrationReceiptsEqual(manifest.targetReceipt, manifest.receiptBefore) && workspaceHydrationReceiptsEqual(receipt, manifest.targetReceipt)) {
     removeHydrationTransaction(workspacePath);
     return;
   }
   restoreHydrationTransaction(workspacePath, manifest);
   removeHydrationTransaction(workspacePath);
 }
-function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
+function gitOutputSync(cwd, args, action, input) {
+  const result = Bun.spawnSync(gitCommandArgs(args), {
+    cwd,
+    ...input ? { stdin: input } : {},
+    stdout: "pipe",
+    stderr: "pipe",
+    env: workerGitProcessEnvironment()
+  });
+  if (result.exitCode !== 0) throw new Error(`${action}: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
+  return Buffer.from(result.stdout);
+}
+function workspaceSubtreeChanges(workspacePath, projectedCommit, head, workspaceRelativePath) {
+  const normalized = normalizedWorkspaceMountPath(workspaceRelativePath);
+  const names = [`${projectedCommit}:${normalized}`, `${head}:${normalized}`];
+  const resolved = resolveGitObjectsSync(workspacePath, names);
+  const emptyTree = emptyTreeHash(workspacePath);
+  const subtree = (name) => {
+    const object = resolved.get(name);
+    return object?.type === "tree" ? object.objectId : emptyTree;
+  };
+  const base = subtree(names[0]);
+  const theirs = subtree(names[1]);
+  if (base === theirs) return parseWorkspaceSubtreeChanges(Buffer.alloc(0));
+  return parseWorkspaceSubtreeChanges(
+    gitOutputSync(
+      workspacePath,
+      ["diff-tree", "-r", "-z", "--no-renames", "--raw", base, theirs],
+      "compare projected and hydration subtrees"
+    )
+  );
+}
+function resolveGitObjectsSync(workspacePath, names) {
+  const resolved = /* @__PURE__ */ new Map();
+  const unique = [...new Set(names)];
+  if (unique.length === 0) return resolved;
+  const output = gitOutputSync(
+    workspacePath,
+    ["cat-file", "--batch-check"],
+    "resolve workspace objects",
+    Buffer.from(`${unique.join("\n")}
+`)
+  );
+  const lines = output.toString().split("\n").filter((line) => line.length > 0);
+  if (lines.length !== unique.length) {
+    throw new Error(`Resolve workspace objects: expected ${unique.length} results, received ${lines.length}`);
+  }
+  unique.forEach((name, index) => {
+    const match = /^([0-9a-f]{40,64}) (\S+) \d+$/.exec(lines[index]);
+    resolved.set(name, match ? { objectId: match[1], type: match[2] } : null);
+  });
+  return resolved;
+}
+function readWorkspaceBlobs(workspacePath, objectIds) {
+  const blobs = /* @__PURE__ */ new Map();
+  const unique = [...new Set(objectIds)];
+  if (unique.length === 0) return blobs;
+  const output = gitOutputSync(
+    workspacePath,
+    ["cat-file", "--batch"],
+    "read projected workspace blobs",
+    Buffer.from(`${unique.join("\n")}
+`)
+  );
+  let offset = 0;
+  while (offset < output.length) {
+    const newline = output.indexOf(10, offset);
+    if (newline < 0) break;
+    const header = output.subarray(offset, newline).toString();
+    offset = newline + 1;
+    const match = /^([0-9a-f]{40,64}) (\S+) (\d+)$/u.exec(header);
+    if (!match) {
+      if (/ missing$/u.test(header)) continue;
+      throw new Error(`Unexpected cat-file record while reading projected blobs: ${header}`);
+    }
+    const size = Number(match[3]);
+    if (match[2] === "blob") blobs.set(match[1], Buffer.from(output.subarray(offset, offset + size)));
+    offset += size + 1;
+  }
+  return blobs;
+}
+function revertReceiptMounts(target, before, mountIds) {
+  if (!target || mountIds.size === 0) return target;
+  const beforeById = new Map(before?.mounts.map((entry) => [entry.id, entry]) ?? []);
+  const mounts = target.mounts.flatMap((entry) => {
+    if (!mountIds.has(entry.id)) return [entry];
+    const previous = beforeById.get(entry.id);
+    return previous ? [previous] : [];
+  }).sort(compareWorkspaceHydrationMountBasis);
+  return { version: 3, mounts };
+}
+function rewriteHydrationTransactionManifest(workspacePath, manifest) {
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  const temporaryPath = path.join(transactionPath, `.manifest.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    writePrivateFileDurably(temporaryPath, `${JSON.stringify(manifest)}
+`);
+    fs.renameSync(temporaryPath, path.join(transactionPath, "manifest.json"));
+    fsyncDirectory(transactionPath);
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
+function beginHydrationTransaction(workspacePath, mounts, targetReceipt, mergeBases) {
   recoverPendingHydrationTransaction(workspacePath);
   const stateDirectory = workspacePrivateStateDirectory(workspacePath);
   const transactionPath = hydrationTransactionPath(workspacePath);
   const stagingPath = path.join(stateDirectory, `.workspace-hydration-transaction.${process.pid}.${crypto.randomUUID()}.tmp`);
   fs.mkdirSync(stagingPath, { mode: 448 });
   const durabilityScopes = /* @__PURE__ */ new Map();
+  const mergePlans = /* @__PURE__ */ new Map();
+  const skippedMounts = [];
   try {
     const snapshotRoot = path.join(stagingPath, "mounts");
     fs.mkdirSync(snapshotRoot, { mode: 448 });
     const receiptBefore = readHydratedWorkspaceReceipt(workspacePath);
-    const manifestMounts = mounts.map((mount, index) => {
+    const head = mergeBases && Object.keys(mergeBases).length > 0 ? revParse(workspacePath, "HEAD") : null;
+    const manifestMounts = [];
+    for (const mount of mounts) {
       const sourcePath = path.resolve(mount.sourcePath);
       const durabilityRootPath = path.resolve(mount.durabilityRootPath);
       assertManagedDirectoryPath({
@@ -1069,45 +1528,89 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
       if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
         throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
       }
-      const snapshotName = String(index);
+      const snapshotName = String(manifestMounts.length);
       const snapshotPath = path.join(snapshotRoot, snapshotName);
-      fs.mkdirSync(snapshotPath, { mode: 448 });
       let scope;
-      if (sourceStatus && mount.hydrateDeletionMode === "git") {
+      const basis = mergeBases?.[mount.id];
+      if (sourceStatus && mount.hydrateDeletionMode === "git" && basis && head) {
         const outerPath = workspaceMountOuterPath(workspacePath, mount);
         assertManagedDirectoryPath({
           trustedRoot: workspacePath,
           candidate: outerPath,
           label: `Workspace mount ${mount.id} outer source`
         });
-        const plan = planWorkingTreeMirror({
+        const prepared = prepareWorkingTreeMirror({
           sourceRoot: outerPath,
           targetRoot: sourcePath,
           sourceMode: "all",
           deletionMode: "git",
           sourceGitlinks: outerSubtreeGitlinks(workspacePath, mount)
         });
+        const decision = decideWorkspaceHydrationMerge({
+          prepared,
+          changes: workspaceSubtreeChanges(workspacePath, basis.projectedCommit, head, mount.workspaceRelativePath),
+          projectedFiles: basis.projectedFiles,
+          ...basis.readAtMs === void 0 ? {} : { readAtMs: basis.readAtMs },
+          readBaseBlobs: (objectIds) => readWorkspaceBlobs(workspacePath, objectIds),
+          readBinaryPaths: (relativePaths) => readHydrationBinaryPaths({ checkoutRoot: prepared.targetRoot, outerRoot: prepared.sourceRoot, relativePaths })
+        });
+        if (decision.kind !== "apply") {
+          skippedMounts.push({
+            mountId: mount.id,
+            reason: decision.kind === "conflict" ? "hydration_merge_conflict" : "hydration_target_changed",
+            paths: decision.paths
+          });
+          continue;
+        }
+        fs.mkdirSync(snapshotPath, { mode: 448 });
+        const plan = planPreparedWorkingTreeMirror(prepared, { selection: decision.selection, overrides: decision.overrides });
         scope = captureWorkingTreeMirrorPlan({
           plan,
           targetRoot: sourcePath,
           snapshotRoot: snapshotPath,
-          // Same private-staging deferral as the complete snapshot below.
           durability: "deferred_private_staging"
         });
-        durabilityScopes.set(mount.id, [...plan.desired.keys()]);
-      } else if (sourceStatus) {
-        mirrorWorkingTree({
-          sourceRoot: sourcePath,
-          targetRoot: snapshotPath,
+        durabilityScopes.set(mount.id, [.../* @__PURE__ */ new Set([...plan.desired.keys(), ...decision.selection.remove])]);
+        mergePlans.set(mount.id, { prepared, decision, plan, snapshotPath: path.join(transactionPath, "mounts", snapshotName), basis });
+      } else if (sourceStatus && mount.hydrateDeletionMode === "git") {
+        fs.mkdirSync(snapshotPath, { mode: 448 });
+        const outerPath = workspaceMountOuterPath(workspacePath, mount);
+        assertManagedDirectoryPath({
+          trustedRoot: workspacePath,
+          candidate: outerPath,
+          label: `Workspace mount ${mount.id} outer source`
+        });
+        const plan = planWorkingTreeMirror({
+          sourceRoot: outerPath,
+          targetRoot: sourcePath,
           sourceMode: "all",
-          deletionMode: "all",
-          // This tree is still private and the source authority is untouched.
-          // The single recursive barrier below makes the complete snapshot
-          // durable before its directory entry is published or hydration starts.
+          deletionMode: "git",
+          sourceGitlinks: outerSubtreeGitlinks(workspacePath, mount)
+        });
+        scope = captureWorkingTreeMirrorPlan({
+          plan,
+          targetRoot: sourcePath,
+          snapshotRoot: snapshotPath,
+          // Same private-staging deferral as the complete snapshot below.
           durability: "deferred_private_staging"
         });
+        durabilityScopes.set(mount.id, [...plan.desired.keys()]);
+      } else {
+        fs.mkdirSync(snapshotPath, { mode: 448 });
+        if (sourceStatus) {
+          mirrorWorkingTree({
+            sourceRoot: sourcePath,
+            targetRoot: snapshotPath,
+            sourceMode: "all",
+            deletionMode: "all",
+            // This tree is still private and the source authority is untouched.
+            // The single recursive barrier below makes the complete snapshot
+            // durable before its directory entry is published or hydration starts.
+            durability: "deferred_private_staging"
+          });
+        }
       }
-      return {
+      manifestMounts.push({
         id: mount.id,
         incarnationKey: mount.hydrationIncarnationKey,
         sourcePath,
@@ -1115,23 +1618,27 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
         workspaceRelativePath: mount.workspaceRelativePath,
         existed: Boolean(sourceStatus),
         snapshotName,
-        ...scope ? { scope } : {}
-      };
-    });
+        ...scope ? { scope } : {},
+        recovery: mergePlans.has(mount.id) ? "guarded" : "snapshot"
+      });
+    }
+    const effectiveTargetReceipt = revertReceiptMounts(targetReceipt, receiptBefore, new Set(skippedMounts.map(({ mountId }) => mountId)));
+    const guarded = mergePlans.size > 0;
     const manifest = {
-      // Older workers reject version 4, so a scoped snapshot can never be
-      // replayed as a complete copy after a downgrade.
-      version: manifestMounts.some((mount) => mount.scope) ? 4 : 3,
-      targetReceipt,
+      // Older workers reject guarded transactions rather than replaying them
+      // through an unguarded snapshot restore after a downgrade.
+      version: guarded ? 5 : manifestMounts.some((mount) => mount.scope) ? 4 : 3,
+      ...guarded ? { transactionId: crypto.randomUUID() } : {},
+      targetReceipt: effectiveTargetReceipt,
       receiptBefore,
-      mounts: manifestMounts
+      mounts: guarded ? manifestMounts : manifestMounts.map(({ recovery: _recovery, ...mount }) => mount)
     };
     writePrivateFileDurably(path.join(stagingPath, "manifest.json"), `${JSON.stringify(manifest)}
 `);
     fsyncTree(stagingPath);
     fs.renameSync(stagingPath, transactionPath);
     fsyncDirectory(stateDirectory);
-    return { manifest, durabilityScopes };
+    return { manifest, durabilityScopes, mergePlans, skippedMounts, targetReceipt: effectiveTargetReceipt };
   } catch (error) {
     fs.rmSync(stagingPath, { recursive: true, force: true });
     fsyncDirectory(stateDirectory);
@@ -1140,7 +1647,9 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
 }
 function markHydrationTransactionDurable(workspacePath) {
   const transactionPath = hydrationTransactionPath(workspacePath);
-  writePrivateFileDurably(path.join(transactionPath, "committed"), "committed\n");
+  const temporaryPath = path.join(transactionPath, `.committed.${crypto.randomUUID()}.tmp`);
+  writePrivateFileDurably(temporaryPath, "committed\n");
+  fs.renameSync(temporaryPath, path.join(transactionPath, "committed"));
   fsyncDirectory(transactionPath);
 }
 function gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus) {
@@ -1292,6 +1801,22 @@ async function configureWorkspaceRepository(input) {
     "configure durable workspace commits and references"
   );
   await gitAsync(input.workspacePath, ["config", "--local", "core.fsyncMethod", "fsync"], "configure workspace fsync method");
+  const attributesPath = path.join(input.workspacePath, ".git", "info", "attributes");
+  const attributes = [
+    "# r5d workspace clone: checkout bytes are carried verbatim; no conversion or filter may change what projection reads or hydration writes.",
+    "* -text -eol -filter -ident -working-tree-encoding",
+    ""
+  ].join("\n");
+  let currentAttributes = null;
+  try {
+    currentAttributes = await fs.promises.readFile(attributesPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (currentAttributes !== attributes) {
+    await fs.promises.mkdir(path.dirname(attributesPath), { recursive: true });
+    await fs.promises.writeFile(attributesPath, attributes, "utf8");
+  }
 }
 async function configureExistingWorkspaceGitForRemediation(input) {
   const workspacePath = path.resolve(input.workspacePath);
@@ -1423,7 +1948,7 @@ function activeMounts(mounts) {
   }
   return { active, tombstones, skipped };
 }
-function mirrorMountsToWorkspace(workspacePath, mounts) {
+function mirrorMountsToWorkspace(workspacePath, mounts, projectedFiles) {
   const projected = [];
   for (const mount of mounts) {
     assertManagedDirectoryPath({
@@ -1440,7 +1965,8 @@ function mirrorMountsToWorkspace(workspacePath, mounts) {
       sourceRoot: mount.sourcePath,
       targetRoot: path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/")),
       sourceMode: mount.sourceMode,
-      deletionMode: "all"
+      deletionMode: "all",
+      ...projectedFiles ? { projected: projectedFiles } : {}
     });
     projected.push({ mount, gitlinks: mirrored.gitlinks });
   }
@@ -1551,11 +2077,60 @@ function outerSubtreeGitlinks(workspacePath, mount) {
 function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
   const hydratedMountIds = [];
   const skippedMountIds = [];
+  const mergeSkips = [];
+  const rollbackScopes = /* @__PURE__ */ new Map();
+  const preBlobs = {};
   for (const mount of mounts) {
     if (!options.ignoreBusy && mount.busy?.()) {
       skippedMountIds.push(mount.id);
       continue;
     }
+    const mergePlan = options.mergePlans?.get(mount.id);
+    if (mergePlan) {
+      const journal = { entries: [] };
+      const runtimeJournal = { journal, snapshotPath: mergePlan.snapshotPath };
+      options.journals?.set(mount.id, runtimeJournal);
+      try {
+        applyWorkingTreeMirror(mergePlan.prepared, {
+          selection: mergePlan.decision.selection,
+          guards: {
+            expectations: mergePlan.decision.expectations,
+            overrides: mergePlan.decision.overrides,
+            preBlobs: mergePlan.decision.preBlobs,
+            journal
+          }
+        });
+      } catch (error) {
+        if (!(error instanceof WorkingTreeTargetChangedError)) throw error;
+        const rolledBack = rollbackWorkingTreeMirrorJournal({
+          journal,
+          targetRoot: mount.sourcePath,
+          snapshotRoot: mergePlan.snapshotPath
+        });
+        runtimeJournal.rolledBack = rolledBack;
+        const retainedPaths = [
+          ...new Set([...error.retained, ...rolledBack.retained ?? []].map(({ path: retainedPath }) => retainedPath))
+        ].sort();
+        if (retainedPaths.length > 0) {
+          process.stderr.write(
+            `[r5d-worker] hydration preserved displaced writer entries for mount ${mount.id}: ${retainedPaths.join(", ")}
+`
+          );
+        }
+        options.onMergeRollback?.(mount, rolledBack);
+        mergeSkips.push({
+          mountId: mount.id,
+          reason: "hydration_target_changed",
+          paths: [.../* @__PURE__ */ new Set([error.relativePath, ...rolledBack.abandoned])].sort(),
+          ...retainedPaths.length > 0 ? { retainedPaths } : {}
+        });
+        rollbackScopes.set(mount.id, rolledBack.paths);
+        continue;
+      }
+      hydratedMountIds.push(mount.id);
+      preBlobs[mount.id] = Object.fromEntries(mergePlan.decision.preBlobs);
+      continue;
+    }
     const sourceRoot = workspaceMountOuterPath(workspacePath, mount);
     assertManagedDirectoryPath({
       trustedRoot: workspacePath,
@@ -1601,7 +2176,7 @@ function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
     });
     hydratedMountIds.push(mount.id);
   }
-  return { hydratedMountIds: hydratedMountIds.sort(), skippedMountIds: skippedMountIds.sort() };
+  return { hydratedMountIds: hydratedMountIds.sort(), skippedMountIds: skippedMountIds.sort(), mergeSkips, rollbackScopes, preBlobs };
 }
 async function selectMountsWithUnchangedOuterSubtree(workspacePath, receipt, head, mounts) {
   const candidates = mounts.flatMap((mount) => {
@@ -1661,7 +2236,7 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
   };
   const noopCandidate = computeSelection();
   if (noopCandidate.hydrationMounts.length === 0 && noopCandidate.advancedDurabilityMounts.length === 0 && noopCandidate.targetReceipt && lstatIfExists(hydrationTransactionPath(workspacePath)) === null && workspaceHydrationReceiptsEqual(receiptBeforeTransaction, noopCandidate.targetReceipt) && await hydratedWorkspaceReceiptFileIsV3(workspacePath) && await workspaceBasisRefsAreCurrentAsync(workspacePath, noopCandidate.targetReceipt)) {
-    return { hydratedMountIds: [], skippedMountIds: noopCandidate.skippedMountIds };
+    return { hydratedMountIds: [], skippedMountIds: noopCandidate.skippedMountIds, mergeSkips: [] };
   }
   const hooks = input.hydrationHooks;
   const context = {
@@ -1676,13 +2251,30 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
     const heldMountIds = [...new Set([...hydrationMounts, ...advancedDurabilityMounts].map(({ id }) => id))];
     const releaseHold = hooks?.holdMounts(heldMountIds, `hydration transaction ${context.transactionId}`);
     try {
+      const mergeBases = {};
+      for (const mount of hydrationMounts) {
+        const basis = input.mergeBases?.get(mount.id);
+        if (basis) mergeBases[mount.id] = basis;
+      }
       const hydration = await workspaceFilesystemExecutor().run("hydration_transaction", {
         workspacePath,
         hydrationMounts: hydrationMounts.map(workspaceGitMountData),
         advancedDurabilityMounts: advancedDurabilityMounts.map(workspaceGitMountData),
-        targetReceipt
+        targetReceipt,
+        ...Object.keys(mergeBases).length > 0 ? { mergeBases } : {}
       });
-      return { hydratedMountIds: hydration.hydratedMountIds, skippedMountIds: selection.skippedMountIds };
+      const ledger = hydrationPreBlobLedger(workspacePath);
+      for (const mount of hydrationMounts) {
+        if (!hydration.hydratedMountIds.includes(mount.id)) continue;
+        const preBlobs = mergeBases[mount.id] ? hydration.hydratedPreBlobs[mount.id] : void 0;
+        if (preBlobs) ledger.record(mount, preBlobs);
+        else ledger.clearMount(mount);
+      }
+      return {
+        hydratedMountIds: hydration.hydratedMountIds,
+        skippedMountIds: [.../* @__PURE__ */ new Set([...selection.skippedMountIds, ...hydration.skippedMounts.map(({ mountId }) => mountId)])].sort(),
+        mergeSkips: hydration.skippedMounts
+      };
     } finally {
       releaseHold?.();
     }
@@ -1692,28 +2284,90 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
 }
 function runHydrationTransactionJob(input) {
   const workspacePath = path.resolve(input.workspacePath);
-  const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = input;
-  const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
+  const { hydrationMounts, advancedDurabilityMounts } = input;
+  const begun = beginHydrationTransaction(workspacePath, hydrationMounts, input.targetReceipt, input.mergeBases);
+  const { durabilityScopes, mergePlans, skippedMounts } = begun;
+  let manifest = begun.manifest;
+  let targetReceipt = begun.targetReceipt;
+  const skippedIds = new Set(skippedMounts.map(({ mountId }) => mountId));
+  const journals = /* @__PURE__ */ new Map();
+  const excludeRolledBackMount = (mount, rollback) => {
+    const settledMount = manifest.mounts.find(({ id }) => id === mount.id);
+    if (!settledMount) return;
+    fsyncHydratedWorkspaceMount(mount, rollback.paths);
+    fsyncHydrationRetainedEvidence(mount);
+    if (rollback.retained?.length) {
+      process.stderr.write(
+        `[r5d-worker] hydration rollback retained writer entries for mount ${mount.id}: ${rollback.retained.map(({ path: retainedPath }) => retainedPath).join(", ")}
+`
+      );
+    }
+    const nextReceipt = revertReceiptMounts(targetReceipt, manifest.receiptBefore, /* @__PURE__ */ new Set([mount.id]));
+    const nextManifest = {
+      ...manifest,
+      targetReceipt: nextReceipt,
+      mounts: manifest.mounts.filter(({ id }) => id !== mount.id),
+      preservedMounts: [...manifest.preservedMounts ?? [], settledMount]
+    };
+    rewriteHydrationTransactionManifest(workspacePath, nextManifest);
+    manifest = nextManifest;
+    targetReceipt = nextReceipt;
+  };
   try {
-    const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
-    const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
+    const activeMounts2 = hydrationMounts.filter(({ id }) => !skippedIds.has(id));
+    const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, activeMounts2, {
+      ignoreBusy: true,
+      mergePlans,
+      journals,
+      onMergeRollback: excludeRolledBackMount
+    });
+    if (hydration.mergeSkips.length > 0) {
+      for (const skip of hydration.mergeSkips) {
+        skippedMounts.push(skip);
+        skippedIds.add(skip.mountId);
+      }
+    }
+    const expectedHydratedIds = activeMounts2.map(({ id }) => id).filter((id) => !skippedIds.has(id)).sort();
     if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
       throw new Error("Workspace hydration did not include every required mount");
     }
-    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
+    fsyncHydratedWorkspaceMounts(
+      advancedDurabilityMounts.filter(({ id }) => !skippedIds.has(id)),
+      durabilityScopes
+    );
     markHydrationTransactionDurable(workspacePath);
     if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
     removeHydrationTransaction(workspacePath);
-    return { hydratedMountIds: hydration.hydratedMountIds };
+    return { hydratedMountIds: hydration.hydratedMountIds, skippedMounts, hydratedPreBlobs: hydration.preBlobs };
   } catch (error) {
     const transactionPath = hydrationTransactionPath(workspacePath);
     if (lstatIfExists(transactionPath) && hydrationTransactionCommitted(transactionPath)) {
       throw error;
     }
     try {
+      for (const [mountId, mergePlan] of mergePlans) {
+        const mount = hydrationMounts.find(({ id }) => id === mountId);
+        if (!mount || !manifest.mounts.some(({ id }) => id === mountId)) continue;
+        const runtimeJournal = journals.get(mountId);
+        const rolledBack = runtimeJournal ? runtimeJournal.rolledBack ?? rollbackWorkingTreeMirrorJournal({
+          journal: runtimeJournal.journal,
+          targetRoot: mount.sourcePath,
+          snapshotRoot: mergePlan.snapshotPath
+        }) : { paths: [], abandoned: [] };
+        if (runtimeJournal) runtimeJournal.rolledBack = rolledBack;
+        excludeRolledBackMount(mount, rolledBack);
+      }
       restoreHydrationTransaction(workspacePath, manifest);
       removeHydrationTransaction(workspacePath);
     } catch (restoreError) {
+      const pendingManifest = parseHydrationTransactionManifest(transactionPath);
+      if (pendingManifest.mounts.some(({ recovery }) => recovery === "guarded")) {
+        throw hydrationRecoveryRequiredError(
+          workspacePath,
+          pendingManifest,
+          new AggregateError([error, restoreError], "Guarded hydration rollback did not settle")
+        );
+      }
       throw new AggregateError(
         [error, restoreError],
         `Workspace hydration failed and its durable snapshot could not be restored: ${error instanceof Error ? error.message : String(error)}`
@@ -1775,6 +2429,7 @@ async function recoverWorkspaceGitHydration(workspacePath, mounts, options = {})
   });
   const currentHead = await revParseAsync(workspacePath, "HEAD");
   const currentReceipt = await readHydratedWorkspaceReceiptAsync(workspacePath);
+  const preservedBases = await readPreservedHydrationBasesAsync(workspacePath);
   if (!currentHead) return;
   const outerHeadContainsMount = (mount) => tryGitAsync(workspacePath, ["cat-file", "-e", `HEAD:${normalizedWorkspaceMountPath(mount.workspaceRelativePath)}`]);
   const configuredBasisMounts = configuredWorkspaceHydrationBasisMounts(workspacePath, mounts, options.deferMountIds);
@@ -1784,7 +2439,7 @@ async function recoverWorkspaceGitHydration(workspacePath, mounts, options = {})
   if (workspaceHydrationReceiptMatchesMounts(currentReceipt, currentHead, configuredBasisMounts)) return;
   const busyMountIds = new Set(options.ignoreBusy ? [] : uncoveredBasisMounts.filter((mount) => mount.busy?.()).map(({ id }) => id));
   const recoveryMounts = uncoveredBasisMounts.filter(
-    (mount) => workspaceHydrationReceiptMountBasisHead(currentReceipt, mount) === null || !options.preserveStaleBases && !busyMountIds.has(mount.id)
+    (mount) => workspaceHydrationReceiptMountBasisHead(currentReceipt, mount) === null || !options.preserveStaleBases && !busyMountIds.has(mount.id) && workspaceHydrationReceiptMountBasisHead(preservedBases, mount) !== workspaceHydrationReceiptMountBasisHead(currentReceipt, mount)
   );
   const idleBasislessMounts = recoveryMounts.filter((mount) => !busyMountIds.has(mount.id));
   const hydrationTargets = [];
@@ -1814,6 +2469,7 @@ async function resetWorkspaceGit(input) {
   if (busyResetMountIds.length > 0) {
     throw new Error(`Workspace reset cannot run while mounts are busy: ${busyResetMountIds.sort().join(", ")}`);
   }
+  hydrationPreBlobLedger(workspacePath).clear();
   const initial = await ensureWorkspaceGitClone({ ...input, workspacePath });
   await workspaceFilesystemExecutor().run("hydration_recovery", { workspacePath, preserveResolutionInProgress: false });
   const status = gitResult(workspacePath, ["status", "--porcelain=v1", "-z"]);
@@ -2157,6 +2813,24 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
   const mergedProjectionMounts = [];
   const projectionSkippedIds = /* @__PURE__ */ new Set();
   let projectionWarning;
+  const projectedMountFiles = /* @__PURE__ */ new Map();
+  const mergedProjectionBases = /* @__PURE__ */ new Map();
+  const projectedMountBases = /* @__PURE__ */ new Map();
+  const mountSkipReasons = {};
+  const staleRewriteLedger = hydrationPreBlobLedger(workspacePath);
+  const staleRewriteBlobsFor = (mount) => {
+    const preBlobs = staleRewriteLedger.preBlobs(mount);
+    return preBlobs.size > 0 ? Object.fromEntries(preBlobs) : void 0;
+  };
+  const recordStaleRewrite = (mount, paths) => {
+    projectionSkippedIds.add(mount.id);
+    mountSkipReasons[mount.id] = { reason: "stale_rewrite_detected", paths: [...paths] };
+    const holders = mount.describeHolders?.();
+    process.stderr.write(
+      `[r5d-worker] stale rewrite detected in mount ${mount.id}: ${describeHydrationSkipPaths(mount.sourcePath, paths)} hold exactly the bytes the last hydration replaced; the mount stays pinned at its recorded basis until they change${holders ? `; holders: ${holders}` : ""}
+`
+    );
+  };
   const refreshCycleSkippedMounts = (mounts = input.mounts) => {
     for (const mount of mounts) {
       const projectionToken = projectionMutationTokens.get(mount.id);
@@ -2179,7 +2853,8 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
           const token = projectionMutationTokens.get(id);
           return token === void 0 ? [] : [[id, token]];
         })
-      )
+      ),
+      ...Object.keys(mountSkipReasons).length > 0 ? { mountSkipReasons: { ...mountSkipReasons } } : {}
     };
   };
   const mountProjectionIsCurrent = (mount) => mount.lastProjectedMutationToken !== void 0 && !mount.deleteWhenSourceMissing && mount.preserveLocalOnHydrationBasisChange !== true && projectionBasisHead !== null && workspaceHydrationReceiptMountBasisHead(projectionBasisReceipt, mount) === projectionBasisHead && projectionMutationTokens.get(mount.id) === mount.lastProjectedMutationToken && mount.mutationToken?.() === mount.lastProjectedMutationToken;
@@ -2209,6 +2884,7 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
       const releaseMergeHold = input.hydrationHooks?.holdMounts([mount.id], `merge projection of mount ${mount.id}`);
       let merged;
       try {
+        const staleRewriteBlobs = staleRewriteBlobsFor(mount);
         merged = await workspaceFilesystemExecutor().run("projection_merge", {
           workspacePath,
           mount: {
@@ -2219,11 +2895,22 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
           },
           basisHead,
           currentHead: projectionBasisHead,
-          attemptId
+          attemptId,
+          ...staleRewriteBlobs ? { staleRewriteBlobs } : {}
         });
       } finally {
         releaseMergeHold?.();
       }
+      if (merged.staleRewriteCleared.length > 0) staleRewriteLedger.forget(mount, merged.staleRewriteCleared);
+      if (merged.kind === "stale_rewrite") {
+        recordStaleRewrite(mount, merged.paths);
+        continue;
+      }
+      mergedProjectionBases.set(mount.id, {
+        projectedCommit: merged.oursCommit,
+        projectedFiles: merged.projectedFiles,
+        readAtMs: merged.readAtMs
+      });
       if (merged.kind === "conflict") {
         const refs = snapshotConflict({ workspacePath, attemptId, localHead: merged.oursCommit, remoteHead: projectionBasisHead });
         return {
@@ -2276,17 +2963,44 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
       currentHeadBeforeHydration,
       uncoveredCompletionMounts
     ) : /* @__PURE__ */ new Set();
+    const hydrationMounts = uncoveredCompletionMounts.filter(({ id }) => !unchangedMountIds.has(id));
+    const mergeBases = /* @__PURE__ */ new Map();
+    if (workspaceMergeHydrationEnabled()) {
+      for (const mount of hydrationMounts) {
+        const basis = projectedMountBases.get(mount.id);
+        if (basis) mergeBases.set(mount.id, basis);
+      }
+    }
     const hydration = await hydrateWorkspaceGitMountsTransactionally({
       workspacePath,
-      mounts: uncoveredCompletionMounts.filter(({ id }) => !unchangedMountIds.has(id)),
+      mounts: hydrationMounts,
       durabilityMounts: uncoveredCompletionBasisMounts.filter(({ id }) => !unchangedMountIds.has(id)),
       carryMounts: uncoveredCompletionMounts.filter(({ id }) => unchangedMountIds.has(id)),
       receiptMounts: completionReceiptMounts,
       requiredMounts: uncoveredRequiredLiveMounts.filter(({ id }) => !unchangedMountIds.has(id)),
       recordCurrentHead: true,
-      hydrationHooks: input.hydrationHooks
+      hydrationHooks: input.hydrationHooks,
+      ...mergeBases.size > 0 ? { mergeBases } : {}
     });
     for (const id of hydration.skippedMountIds) cycleSkippedMountIds.add(id);
+    if (currentHeadBeforeHydration) {
+      for (const id of hydration.hydratedMountIds) {
+        if (mergeBases.has(id)) projectedMountBases.set(id, { projectedCommit: currentHeadBeforeHydration, projectedFiles: null });
+      }
+    }
+    for (const skip of hydration.mergeSkips) {
+      const mount = hydrationMounts.find(({ id }) => id === skip.mountId);
+      const basis = mount ? workspaceHydrationReceiptMountBasisHead(currentReceiptBeforeHydration, mount) : null;
+      mountSkipReasons[skip.mountId] = {
+        reason: skip.reason,
+        paths: skip.paths,
+        ...skip.retainedPaths?.length ? { retainedPaths: skip.retainedPaths } : {}
+      };
+      process.stderr.write(
+        `[r5d-worker] merge hydration pinned mount ${skip.mountId} at ${basis ?? "its recorded basis"} (${skip.reason}): ${skip.reason === "hydration_merge_conflict" ? "writes that landed after the projection read conflict with the inbound change at" : "the checkout changed while it was being hydrated at"} ${describeHydrationSkipPaths(mount?.sourcePath ?? skip.mountId, skip.paths)}; the next projection merges it from that basis${skip.retainedPaths?.length ? `; displaced writer entries preserved at ${skip.retainedPaths.join(", ")}` : ""}
+`
+      );
+    }
     refreshCycleSkippedMounts(completionReceiptMounts);
     if (requireCurrentHeadReceipt) {
       const currentHead = await revParseAsync(workspacePath, "HEAD");
@@ -2327,10 +3041,11 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
   };
   const projectedFastMounts = [];
   const currentProjectionMounts = [];
+  const selectedActiveIdSet = new Set(selected.active.map(({ id }) => id));
   if (!input.skipMountMirror) {
     await beginWorkspaceCheckoutTransition(workspacePath);
     try {
-      const selectedActiveIds = new Set(selected.active.map(({ id }) => id));
+      const selectedActiveIds = selectedActiveIdSet;
       const fastActiveMounts = fastProjectionMounts.filter(({ id }) => selectedActiveIds.has(id));
       const fastTombstones = fastProjectionMounts.filter(({ id }) => !selectedActiveIds.has(id));
       for (const mount of fastActiveMounts) {
@@ -2343,15 +3058,27 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
           continue;
         }
         const releaseMirrorHold = input.hydrationHooks?.holdMounts([mount.id], `projection of mount ${mount.id}`);
+        let staleRewritePaths;
         try {
+          const staleRewriteBlobs = staleRewriteBlobsFor(mount);
           const mirrored = await workspaceFilesystemExecutor().run("projection_mirror", {
             workspacePath,
-            mount: workspaceGitMountData(mount)
+            mount: workspaceGitMountData(mount),
+            ...staleRewriteBlobs ? { staleRewriteBlobs } : {}
           });
-          projectedGitlinks.push({ mount, gitlinks: mirrored.gitlinks });
+          staleRewritePaths = mirrored.staleRewritePaths;
+          if (mirrored.staleRewriteCleared.length > 0) staleRewriteLedger.forget(mount, mirrored.staleRewriteCleared);
+          if (staleRewritePaths.length === 0) {
+            projectedGitlinks.push({ mount, gitlinks: mirrored.gitlinks });
+            projectedMountFiles.set(mount.id, { files: mirrored.projectedFiles, readAtMs: mirrored.readAtMs });
+          }
         } finally {
           releaseMirrorHold?.();
         }
+        if (staleRewritePaths.length > 0) {
+          recordStaleRewrite(mount, staleRewritePaths);
+          continue;
+        }
         projectedFastMounts.push(mount);
       }
       await workspaceFilesystemExecutor().run("projection_outer_apply", {
@@ -2378,6 +3105,18 @@ async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
   if (!input.skipMountMirror) {
     const projectedHead = await revParseAsync(workspacePath, "HEAD");
     if (!projectedHead) throw new Error("Workspace projection did not retain a local HEAD");
+    for (const mount of projectedFastMounts) {
+      if (!selectedActiveIdSet.has(mount.id)) continue;
+      const read = projectedMountFiles.get(mount.id);
+      projectedMountBases.set(mount.id, {
+        projectedCommit: projectedHead,
+        projectedFiles: read?.files ?? null,
+        ...read ? { readAtMs: read.readAtMs } : {}
+      });
+    }
+    for (const mount of currentProjectionMounts)
+      projectedMountBases.set(mount.id, { projectedCommit: projectedHead, projectedFiles: null });
+    for (const [mountId, basis] of mergedProjectionBases) projectedMountBases.set(mountId, basis);
     const targetProjectionReceipt = receiptWithMountsAtHead(
       projectionBasisReceipt,
       projectedHead,
@@ -2557,9 +3296,52 @@ ${push.stdout}`)) {
   }
   throw new Error(`Workspace push did not converge after ${maxPushAttempts} attempts`);
 }
+function detectStaleRewrites(workspacePath, mount, staleRewriteBlobs) {
+  const outerRoot = workspaceMountOuterPath(workspacePath, mount);
+  const stale = [];
+  const cleared = [];
+  for (const [relativePath, blob] of Object.entries(staleRewriteBlobs)) {
+    const algorithm = gitObjectHashAlgorithmFor(blob);
+    if (!algorithm) continue;
+    const source = inspectWorkingTreePath(mount.sourcePath, relativePath);
+    if (source.kind !== "entry" || !source.stat.isFile()) {
+      cleared.push(relativePath);
+      continue;
+    }
+    const content = fs.readFileSync(source.absolutePath);
+    const outer = inspectWorkingTreePath(outerRoot, relativePath);
+    const outerEqual = outer.kind === "entry" && outer.stat.isFile() && fs.readFileSync(outer.absolutePath).equals(content);
+    if (gitBlobHash(content, algorithm) !== blob) {
+      if (!outerEqual) cleared.push(relativePath);
+      continue;
+    }
+    if (outerEqual) {
+      cleared.push(relativePath);
+      continue;
+    }
+    stale.push(relativePath);
+  }
+  return { stale: stale.sort(), cleared: cleared.sort() };
+}
 function runProjectionMirrorJob(input) {
-  const projected = mirrorMountsToWorkspace(path.resolve(input.workspacePath), [input.mount]);
-  return { gitlinks: projected[0]?.gitlinks ?? [] };
+  const workspacePath = path.resolve(input.workspacePath);
+  let staleRewriteCleared = [];
+  if (input.staleRewriteBlobs) {
+    const detected = detectStaleRewrites(workspacePath, input.mount, input.staleRewriteBlobs);
+    staleRewriteCleared = detected.cleared;
+    if (detected.stale.length > 0) {
+      return { gitlinks: [], projectedFiles: {}, readAtMs: Date.now(), staleRewritePaths: detected.stale, staleRewriteCleared };
+    }
+  }
+  const projectedFiles = /* @__PURE__ */ new Map();
+  const projected = mirrorMountsToWorkspace(workspacePath, [input.mount], projectedFiles);
+  return {
+    gitlinks: projected[0]?.gitlinks ?? [],
+    projectedFiles: Object.fromEntries(projectedFiles),
+    readAtMs: Date.now(),
+    staleRewritePaths: [],
+    staleRewriteCleared
+  };
 }
 function runProjectionOuterApplyJob(input) {
   const workspacePath = path.resolve(input.workspacePath);
@@ -2577,11 +3359,16 @@ function runProjectionReceiptJob(input) {
   return null;
 }
 const workspaceGitSyncTestHarness = {
+  beginHydrationTransaction,
   commandArgs: gitCommandArgs,
   workspaceCloneCommandArgs,
   configureWorkspaceRepository,
   mirrorMountsToWorkspace,
-  hydrateMountsFromWorkspace: hydrateWorkspaceGitMounts
+  hydrateMountsFromWorkspace: hydrateWorkspaceGitMounts,
+  hydrationPreBlobLedger,
+  resetHydrationPreBlobLedgers() {
+    hydrationPreBlobLedgers.clear();
+  }
 };
 export {
   MAX_WORKSPACE_GIT_DIFF_BYTES,
@@ -2589,7 +3376,10 @@ export {
   WORKSPACE_GIT_CHECKOUT_DURABILITY,
   WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION,
   WORKSPACE_GIT_HYDRATED_RECEIPT,
+  WORKSPACE_GIT_HYDRATION_RECOVERIES,
   WORKSPACE_GIT_HYDRATION_TRANSACTION,
+  WORKSPACE_MERGE_HYDRATION_SWITCH,
+  WorkspaceHydrationRecoveryRequiredError,
   WorkspaceRemediationAncestryError,
   configureExistingWorkspaceGitForRemediation,
   ensureWorkspaceGitClone,
@@ -2599,7 +3389,9 @@ export {
   runCheckoutDurabilityRecoveryJob,
   runCheckoutTransitionBeginJob,
   runCheckoutTransitionCompleteJob,
+  runHydrationPreserveInterruptedJob,
   runHydrationRawJob,
+  runHydrationRecoveryInspectJob,
   runHydrationRecoveryJob,
   runHydrationTransactionJob,
   runOuterCheckoutFsyncJob,