@ricsam/r5d-worker 0.0.78 → 0.0.80

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

@@ -2,10 +2,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { gitCredentialUsernameConfigKey, gitTransportSecurityArgs, workerGitProcessEnvironment } from "./git-process-environment.mjs";
 import { mirrorWorkingTree } from "./working-tree-mirror.mjs";
+import { assertManagedDirectoryPath } from "./workspace-mount-boundary.mjs";
 const WORKSPACE_GIT_BRANCH = "main";
 const MAX_WORKSPACE_GIT_DIFF_BYTES = 5 * 1024 * 1024;
 const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confirm-large-diff-v1";
 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_CHECKOUT_DURABILITY = "r5d/workspace-checkout-durability";
 const NON_RECURSIVE_GIT_CONFIG = [
   "-c",
   "submodule.recurse=false",
@@ -48,6 +52,640 @@ function revParse(workspacePath, revision) {
 function updateIntegratedWorkspaceHead(workspacePath, head) {
   git(workspacePath, ["update-ref", WORKSPACE_GIT_INTEGRATED_REF, head], "record integrated workspace head");
 }
+function fsyncDirectory(directoryPath) {
+  const descriptor = fs.openSync(directoryPath, fs.constants.O_RDONLY);
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function lstatIfExists(targetPath) {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function hydratedWorkspaceReceiptPath(workspacePath) {
+  return path.join(workspacePath, ".git", ...WORKSPACE_GIT_HYDRATED_RECEIPT.split("/"));
+}
+function workspaceCheckoutDurabilityPath(workspacePath) {
+  return path.join(workspacePath, ".git", ...WORKSPACE_GIT_CHECKOUT_DURABILITY.split("/"));
+}
+function normalizedWorkspaceMountPath(workspaceRelativePath) {
+  return workspaceRelativePath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+}
+function workspaceHydrationMountBasis(mount) {
+  return {
+    id: mount.id,
+    incarnationKey: mount.hydrationIncarnationKey,
+    sourcePath: path.resolve(mount.sourcePath),
+    durabilityRootPath: path.resolve(mount.durabilityRootPath),
+    workspaceRelativePath: normalizedWorkspaceMountPath(mount.workspaceRelativePath),
+    sourceMode: mount.sourceMode,
+    hydrateDeletionMode: mount.hydrateDeletionMode,
+    preserveLocalOnInitialOuterAbsence: mount.preserveLocalOnInitialOuterAbsence === true,
+    preserveLocalOnHydrationBasisChange: mount.preserveLocalOnHydrationBasisChange === true,
+    deleteWhenSourceMissing: mount.deleteWhenSourceMissing === true
+  };
+}
+function compareWorkspaceHydrationMountBasis(left, right) {
+  return left.id.localeCompare(right.id);
+}
+function workspaceHydrationReceipt(head, mounts) {
+  const bases = mounts.map(workspaceHydrationMountBasis).sort(compareWorkspaceHydrationMountBasis);
+  const ids = /* @__PURE__ */ new Set();
+  for (const basis of bases) {
+    if (ids.has(basis.id)) throw new Error(`Workspace hydration receipt mount id must be unique: ${basis.id}`);
+    ids.add(basis.id);
+  }
+  return { version: 2, head, mounts: bases };
+}
+function workspaceHydrationReceiptsEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function workspaceHydrationReceiptCoversMount(receipt, head, mount) {
+  if (!receipt || receipt.head !== head) return false;
+  const expected = workspaceHydrationMountBasis(mount);
+  const actual = receipt.mounts.find(({ id }) => id === expected.id);
+  return Boolean(actual && JSON.stringify(actual) === JSON.stringify(expected));
+}
+function workspaceHydrationReceiptMatchesMounts(receipt, head, mounts) {
+  return workspaceHydrationReceiptsEqual(receipt, workspaceHydrationReceipt(head, mounts));
+}
+function configuredWorkspaceHydrationBasisMounts(workspacePath, mounts, deferMountIds) {
+  const resolvedWorkspacePath = path.resolve(workspacePath);
+  return mounts.filter((mount) => {
+    if (deferMountIds?.has(mount.id)) return false;
+    if (mount.deleteWhenSourceMissing) return !fs.existsSync(mount.sourcePath);
+    const outerPath = path.join(resolvedWorkspacePath, ...normalizedWorkspaceMountPath(mount.workspaceRelativePath).split("/"));
+    return fs.existsSync(mount.sourcePath) || fs.existsSync(outerPath) || mount.sourceMode === "all";
+  });
+}
+function parseWorkspaceHydrationReceiptContent(workspacePath, receiptPath, content) {
+  const legacyHead = content.endsWith("\n") ? content.slice(0, -1) : "";
+  if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(legacyHead) && content === `${legacyHead}
+`) {
+    if (!tryGit(workspacePath, ["cat-file", "-e", `${legacyHead}^{commit}`])) {
+      throw new Error(`Workspace hydration receipt does not resolve to a local commit: ${receiptPath}`);
+    }
+    return { version: 2, head: legacyHead, mounts: [] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`Workspace hydration receipt contains an invalid object id or mount basis: ${receiptPath}`);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Workspace hydration receipt contains an invalid object id or mount basis: ${receiptPath}`);
+  }
+  const candidate = parsed;
+  if (candidate.version !== 2 || typeof candidate.head !== "string" || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(candidate.head)) {
+    throw new Error(`Workspace hydration receipt contains an invalid object id or mount basis: ${receiptPath}`);
+  }
+  if (!Array.isArray(candidate.mounts)) {
+    throw new Error(`Workspace hydration receipt contains an invalid mount basis: ${receiptPath}`);
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  const mounts = candidate.mounts.map((rawMount) => {
+    if (!rawMount || typeof rawMount !== "object") {
+      throw new Error(`Workspace hydration receipt contains an invalid mount basis: ${receiptPath}`);
+    }
+    const mount = rawMount;
+    const normalizedRelativePath = typeof mount.workspaceRelativePath === "string" ? normalizedWorkspaceMountPath(mount.workspaceRelativePath) : "";
+    const durabilityRelative = typeof mount.sourcePath === "string" && typeof mount.durabilityRootPath === "string" ? path.relative(mount.durabilityRootPath, mount.sourcePath) : "..";
+    if (typeof mount.id !== "string" || !mount.id || seenIds.has(mount.id) || typeof mount.incarnationKey !== "string" || !mount.incarnationKey || mount.incarnationKey.includes("\0") || typeof mount.sourcePath !== "string" || path.resolve(mount.sourcePath) !== mount.sourcePath || typeof mount.durabilityRootPath !== "string" || path.resolve(mount.durabilityRootPath) !== mount.durabilityRootPath || !durabilityRelative || durabilityRelative === ".." || durabilityRelative.startsWith(`..${path.sep}`) || path.isAbsolute(durabilityRelative) || typeof mount.workspaceRelativePath !== "string" || mount.workspaceRelativePath !== normalizedRelativePath || !normalizedRelativePath || normalizedRelativePath === "." || normalizedRelativePath.split("/").some((segment) => segment === ".." || segment === ".git") || mount.sourceMode !== "all" && mount.sourceMode !== "git" || mount.hydrateDeletionMode !== "all" && mount.hydrateDeletionMode !== "git" || typeof mount.preserveLocalOnInitialOuterAbsence !== "boolean" || typeof mount.preserveLocalOnHydrationBasisChange !== "boolean" || typeof mount.deleteWhenSourceMissing !== "boolean") {
+      throw new Error(`Workspace hydration receipt contains an invalid mount basis: ${receiptPath}`);
+    }
+    seenIds.add(mount.id);
+    return mount;
+  });
+  const receipt = {
+    version: 2,
+    head: candidate.head,
+    mounts: mounts.sort(compareWorkspaceHydrationMountBasis)
+  };
+  if (content !== `${JSON.stringify(receipt)}
+`) {
+    throw new Error(`Workspace hydration receipt contains a noncanonical mount basis: ${receiptPath}`);
+  }
+  if (!tryGit(workspacePath, ["cat-file", "-e", `${receipt.head}^{commit}`])) {
+    throw new Error(`Workspace hydration receipt does not resolve to a local commit: ${receiptPath}`);
+  }
+  return receipt;
+}
+function readHydratedWorkspaceReceipt(workspacePath) {
+  const receiptPath = hydratedWorkspaceReceiptPath(workspacePath);
+  const status = lstatIfExists(receiptPath);
+  if (!status) return null;
+  if (!status.isFile() || status.isSymbolicLink()) {
+    throw new Error(`Workspace hydration receipt is not a regular file: ${receiptPath}`);
+  }
+  const content = fs.readFileSync(receiptPath, "utf8");
+  return parseWorkspaceHydrationReceiptContent(workspacePath, receiptPath, content);
+}
+function workspaceGitHydrationIsCurrent(workspacePath, mounts) {
+  const resolvedWorkspacePath = path.resolve(workspacePath);
+  if (!fs.existsSync(path.join(resolvedWorkspacePath, ".git"))) return true;
+  if (mounts) validateMounts(resolvedWorkspacePath, mounts);
+  const head = revParse(resolvedWorkspacePath, "HEAD");
+  if (!workspaceCheckoutDurabilityIsCurrent(resolvedWorkspacePath)) return false;
+  if (head === null) return true;
+  const receipt = readHydratedWorkspaceReceipt(resolvedWorkspacePath);
+  return mounts ? workspaceHydrationReceiptMatchesMounts(receipt, head, configuredWorkspaceHydrationBasisMounts(resolvedWorkspacePath, mounts)) : receipt?.head === head;
+}
+function updateHydratedWorkspaceReceipt(workspacePath, receipt) {
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(receipt.head)) {
+    throw new Error(`Cannot record invalid fully hydrated workspace object id: ${receipt.head}`);
+  }
+  if (!tryGit(workspacePath, ["cat-file", "-e", `${receipt.head}^{commit}`])) {
+    throw new Error(`Cannot record workspace hydration receipt for a missing commit: ${receipt.head}`);
+  }
+  readHydratedWorkspaceReceipt(workspacePath);
+  const gitDirectory = path.join(workspacePath, ".git");
+  const gitDirectoryStatus = fs.lstatSync(gitDirectory);
+  if (!gitDirectoryStatus.isDirectory() || gitDirectoryStatus.isSymbolicLink()) {
+    throw new Error(`Workspace Git directory is not a regular directory: ${gitDirectory}`);
+  }
+  const receiptPath = hydratedWorkspaceReceiptPath(workspacePath);
+  const receiptDirectory = path.dirname(receiptPath);
+  const existingReceiptDirectory = lstatIfExists(receiptDirectory);
+  if (!existingReceiptDirectory) {
+    fs.mkdirSync(receiptDirectory, { recursive: false, mode: 448 });
+    fsyncDirectory(gitDirectory);
+  }
+  const receiptDirectoryStatus = fs.lstatSync(receiptDirectory);
+  if (!receiptDirectoryStatus.isDirectory() || receiptDirectoryStatus.isSymbolicLink()) {
+    throw new Error(`Workspace hydration receipt directory is not a regular directory: ${receiptDirectory}`);
+  }
+  const temporaryPath = path.join(receiptDirectory, `.workspace-hydrated-head.${process.pid}.${crypto.randomUUID()}.tmp`);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporaryPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 384);
+    fs.writeFileSync(descriptor, `${JSON.stringify(receipt)}
+`, "utf8");
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = void 0;
+    fs.renameSync(temporaryPath, receiptPath);
+    fsyncDirectory(receiptDirectory);
+  } catch (error) {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
+function hydrationTransactionPath(workspacePath) {
+  return path.join(workspacePath, ".git", ...WORKSPACE_GIT_HYDRATION_TRANSACTION.split("/"));
+}
+function workspacePrivateStateDirectory(workspacePath) {
+  const gitDirectory = path.join(workspacePath, ".git");
+  const gitDirectoryStatus = fs.lstatSync(gitDirectory);
+  if (!gitDirectoryStatus.isDirectory() || gitDirectoryStatus.isSymbolicLink()) {
+    throw new Error(`Workspace Git directory is not a regular directory: ${gitDirectory}`);
+  }
+  const stateDirectory = path.dirname(hydrationTransactionPath(workspacePath));
+  const existing = lstatIfExists(stateDirectory);
+  if (!existing) {
+    fs.mkdirSync(stateDirectory, { recursive: false, mode: 448 });
+    fsyncDirectory(gitDirectory);
+  } else if (!existing.isDirectory() || existing.isSymbolicLink()) {
+    throw new Error(`Workspace Git private state is not a regular directory: ${stateDirectory}`);
+  }
+  return stateDirectory;
+}
+function writePrivateFileDurably(filePath, content) {
+  const descriptor = fs.openSync(
+    filePath,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW,
+    384
+  );
+  try {
+    fs.writeFileSync(descriptor, content, "utf8");
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function fsyncTree(rootPath) {
+  const syncEntry = (entryPath) => {
+    const status = fs.lstatSync(entryPath);
+    if (status.isSymbolicLink()) return;
+    if (status.isDirectory()) {
+      for (const name of fs.readdirSync(entryPath)) syncEntry(path.join(entryPath, name));
+      fsyncDirectory(entryPath);
+      return;
+    }
+    if (!status.isFile()) return;
+    const descriptor = fs.openSync(entryPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+      fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  };
+  syncEntry(rootPath);
+}
+function parseWorkspaceCheckoutDurabilityRecord(workspacePath, recordPath, content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`Workspace checkout durability record is invalid: ${recordPath}`);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Workspace checkout durability record is invalid: ${recordPath}`);
+  }
+  const candidate = parsed;
+  if (candidate.version !== 1 || candidate.state !== "durable" && candidate.state !== "transition" || candidate.head !== null && (typeof candidate.head !== "string" || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(candidate.head))) {
+    throw new Error(`Workspace checkout durability record is invalid: ${recordPath}`);
+  }
+  const record = {
+    version: 1,
+    state: candidate.state,
+    head: candidate.head
+  };
+  if (content !== `${JSON.stringify(record)}
+`) {
+    throw new Error(`Workspace checkout durability record is noncanonical: ${recordPath}`);
+  }
+  if (record.head && !tryGit(workspacePath, ["cat-file", "-e", `${record.head}^{commit}`])) {
+    throw new Error(`Workspace checkout durability record names a missing commit: ${recordPath}`);
+  }
+  return record;
+}
+function readWorkspaceCheckoutDurabilityRecord(workspacePath) {
+  const recordPath = workspaceCheckoutDurabilityPath(workspacePath);
+  const status = lstatIfExists(recordPath);
+  if (!status) return null;
+  if (!status.isFile() || status.isSymbolicLink()) {
+    throw new Error(`Workspace checkout durability record is not a regular file: ${recordPath}`);
+  }
+  return parseWorkspaceCheckoutDurabilityRecord(workspacePath, recordPath, fs.readFileSync(recordPath, "utf8"));
+}
+function updateWorkspaceCheckoutDurabilityRecord(workspacePath, record) {
+  if (record.head && !tryGit(workspacePath, ["cat-file", "-e", `${record.head}^{commit}`])) {
+    throw new Error(`Cannot record workspace checkout durability for a missing commit: ${record.head}`);
+  }
+  readWorkspaceCheckoutDurabilityRecord(workspacePath);
+  const stateDirectory = workspacePrivateStateDirectory(workspacePath);
+  const recordPath = workspaceCheckoutDurabilityPath(workspacePath);
+  const temporaryPath = path.join(stateDirectory, `.workspace-checkout-durability.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    writePrivateFileDurably(temporaryPath, `${JSON.stringify(record)}
+`);
+    fs.renameSync(temporaryPath, recordPath);
+    fsyncDirectory(stateDirectory);
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
+function fsyncWorkspaceCheckoutTree(workspacePath) {
+  const status = fs.lstatSync(workspacePath);
+  if (!status.isDirectory() || status.isSymbolicLink()) {
+    throw new Error(`Workspace clone root is not a regular directory: ${workspacePath}`);
+  }
+  for (const name of fs.readdirSync(workspacePath)) {
+    if (name === ".git") continue;
+    fsyncTree(path.join(workspacePath, name));
+  }
+  fsyncDirectory(workspacePath);
+}
+function workspaceRebaseInProgress(workspacePath) {
+  const gitDirectory = path.join(workspacePath, ".git");
+  return fs.existsSync(path.join(gitDirectory, "rebase-merge")) || fs.existsSync(path.join(gitDirectory, "rebase-apply"));
+}
+function clearWorkspaceCheckoutTree(workspacePath) {
+  for (const name of fs.readdirSync(workspacePath)) {
+    if (name === ".git") continue;
+    fs.rmSync(path.join(workspacePath, name), { recursive: true, force: true });
+  }
+  fsyncDirectory(workspacePath);
+}
+function recoverWorkspaceCheckoutDurability(workspacePath) {
+  workspacePath = path.resolve(workspacePath);
+  const record = readWorkspaceCheckoutDurabilityRecord(workspacePath);
+  const observedHead = revParse(workspacePath, "HEAD");
+  if (record?.state === "durable" && record.head === observedHead) return;
+  let targetHead = record?.state === "transition" ? record.head : observedHead;
+  if (record?.state === "transition" && observedHead && observedHead !== record.head) {
+    const hydrationReceipt = readHydratedWorkspaceReceipt(workspacePath);
+    if (hydrationReceipt?.head === observedHead) {
+      targetHead = observedHead;
+    }
+  }
+  if (workspaceRebaseInProgress(workspacePath)) {
+    const abort = gitResult(workspacePath, ["rebase", "--abort"]);
+    if (abort.exitCode !== 0) {
+      throw new Error(`Abort interrupted workspace rebase: ${abort.stderr || abort.stdout || `git exited ${abort.exitCode}`}`);
+    }
+    if (record?.state !== "transition") targetHead = revParse(workspacePath, "HEAD");
+  }
+  clearWorkspaceCheckoutTree(workspacePath);
+  if (targetHead) {
+    git(workspacePath, ["reset", "--hard", targetHead], "reconstruct durable workspace checkout");
+    if (revParse(workspacePath, "HEAD") !== targetHead) {
+      throw new Error(`Workspace checkout reconstruction did not restore ${targetHead}`);
+    }
+  } else {
+    git(workspacePath, ["symbolic-ref", "HEAD", `refs/heads/${WORKSPACE_GIT_BRANCH}`], "restore unborn workspace HEAD");
+    git(workspacePath, ["update-ref", "-d", `refs/heads/${WORKSPACE_GIT_BRANCH}`], "remove interrupted workspace branch ref");
+    git(workspacePath, ["read-tree", "--empty"], "reconstruct unborn workspace checkout");
+    if (revParse(workspacePath, "HEAD") !== null) {
+      throw new Error("Workspace checkout reconstruction did not restore its unborn HEAD");
+    }
+  }
+  fsyncWorkspaceCheckoutTree(workspacePath);
+  updateWorkspaceCheckoutDurabilityRecord(workspacePath, { version: 1, state: "durable", head: targetHead });
+}
+function workspaceCheckoutDurabilityIsCurrent(workspacePath) {
+  const record = readWorkspaceCheckoutDurabilityRecord(workspacePath);
+  return Boolean(record?.state === "durable" && record.head === revParse(workspacePath, "HEAD"));
+}
+function beginWorkspaceCheckoutTransition(workspacePath) {
+  recoverWorkspaceCheckoutDurability(workspacePath);
+  const head = revParse(workspacePath, "HEAD");
+  updateWorkspaceCheckoutDurabilityRecord(workspacePath, { version: 1, state: "transition", head });
+}
+function completeWorkspaceCheckoutTransition(workspacePath) {
+  fsyncWorkspaceCheckoutTree(workspacePath);
+  updateWorkspaceCheckoutDurabilityRecord(workspacePath, {
+    version: 1,
+    state: "durable",
+    head: revParse(workspacePath, "HEAD")
+  });
+}
+function throwAfterWorkspaceCheckoutRecovery(workspacePath, error) {
+  try {
+    recoverWorkspaceCheckoutDurability(workspacePath);
+  } catch (recoveryError) {
+    throw new AggregateError(
+      [error, recoveryError],
+      `Workspace checkout mutation failed and its durable head could not be restored: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  throw error;
+}
+function runWorkspaceCheckoutTransition(workspacePath, mutate) {
+  beginWorkspaceCheckoutTransition(workspacePath);
+  try {
+    mutate();
+    completeWorkspaceCheckoutTransition(workspacePath);
+  } catch (error) {
+    throwAfterWorkspaceCheckoutRecovery(workspacePath, error);
+  }
+}
+function parseHydrationTransactionManifest(transactionPath) {
+  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}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`, { cause: error });
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+  }
+  const candidate = parsed;
+  if (candidate.version !== 2 || !Array.isArray(candidate.mounts)) {
+    throw new Error(`Workspace hydration transaction manifest 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 targetReceipt = parseReceipt(candidate.targetReceipt);
+  const receiptBefore = parseReceipt(candidate.receiptBefore);
+  const seenIds = /* @__PURE__ */ new Set();
+  const seenSnapshots = /* @__PURE__ */ new Set();
+  const mounts = candidate.mounts.map((rawMount) => {
+    if (!rawMount || typeof rawMount !== "object") {
+      throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+    }
+    const mount = rawMount;
+    if (typeof mount.id !== "string" || !mount.id || typeof mount.incarnationKey !== "string" || !mount.incarnationKey || mount.incarnationKey.includes("\0") || typeof mount.sourcePath !== "string" || path.resolve(mount.sourcePath) !== mount.sourcePath || typeof mount.durabilityRootPath !== "string" || path.resolve(mount.durabilityRootPath) !== mount.durabilityRootPath || typeof mount.workspaceRelativePath !== "string" || typeof mount.existed !== "boolean" || typeof mount.snapshotName !== "string" || !/^[0-9]+$/.test(mount.snapshotName) || seenIds.has(mount.id) || seenSnapshots.has(mount.snapshotName)) {
+      throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+    }
+    const relative = path.relative(mount.durabilityRootPath, mount.sourcePath);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error(`Workspace hydration transaction source escapes its durability root: ${mount.sourcePath}`);
+    }
+    seenIds.add(mount.id);
+    seenSnapshots.add(mount.snapshotName);
+    return mount;
+  });
+  return {
+    version: 2,
+    targetReceipt,
+    receiptBefore,
+    mounts
+  };
+}
+function removeHydrationTransaction(workspacePath) {
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  fs.rmSync(transactionPath, { recursive: true, force: true });
+  fsyncDirectory(path.dirname(transactionPath));
+}
+function hydrationTransactionCommitted(transactionPath) {
+  const markerPath = path.join(transactionPath, "committed");
+  const markerStatus = lstatIfExists(markerPath);
+  if (!markerStatus) return false;
+  if (!markerStatus.isFile() || markerStatus.isSymbolicLink() || fs.readFileSync(markerPath, "utf8") !== "committed\n") {
+    throw new Error(`Workspace hydration transaction commit marker is invalid: ${markerPath}`);
+  }
+  return true;
+}
+function restoreHydrationTransaction(workspacePath, manifest) {
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  for (const mount of manifest.mounts) {
+    assertManagedDirectoryPath({
+      trustedRoot: mount.durabilityRootPath,
+      candidate: mount.sourcePath,
+      label: `Workspace hydration recovery mount ${mount.id}`
+    });
+    if (!mount.existed) {
+      fs.rmSync(mount.sourcePath, { recursive: true, force: true });
+      continue;
+    }
+    const snapshotPath = path.join(transactionPath, "mounts", mount.snapshotName);
+    const snapshotStatus = fs.lstatSync(snapshotPath);
+    if (!snapshotStatus.isDirectory() || snapshotStatus.isSymbolicLink()) {
+      throw new Error(`Workspace hydration snapshot is not a regular directory: ${snapshotPath}`);
+    }
+    mirrorWorkingTree({ sourceRoot: snapshotPath, targetRoot: mount.sourcePath, sourceMode: "all", deletionMode: "all" });
+  }
+  fsyncHydratedWorkspaceMounts(
+    manifest.mounts.map((mount) => ({
+      ...mount,
+      hydrationIncarnationKey: mount.incarnationKey,
+      sourceMode: "all",
+      hydrateDeletionMode: "all"
+    }))
+  );
+}
+function recoverPendingHydrationTransaction(workspacePath) {
+  const stateDirectory = path.dirname(hydrationTransactionPath(workspacePath));
+  const stateStatus = lstatIfExists(stateDirectory);
+  if (!stateStatus) return;
+  if (!stateStatus.isDirectory() || stateStatus.isSymbolicLink()) {
+    throw new Error(`Workspace Git private state is not a regular directory: ${stateDirectory}`);
+  }
+  for (const name of fs.readdirSync(stateDirectory)) {
+    if (!name.startsWith(".workspace-hydration-transaction.") || !name.endsWith(".tmp")) continue;
+    fs.rmSync(path.join(stateDirectory, name), { recursive: true, force: true });
+    fsyncDirectory(stateDirectory);
+  }
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  const transactionStatus = lstatIfExists(transactionPath);
+  if (!transactionStatus) return;
+  if (!transactionStatus.isDirectory() || transactionStatus.isSymbolicLink()) {
+    throw new Error(`Workspace hydration transaction is not a regular directory: ${transactionPath}`);
+  }
+  const manifest = parseHydrationTransactionManifest(transactionPath);
+  if (hydrationTransactionCommitted(transactionPath)) {
+    const receipt2 = readHydratedWorkspaceReceipt(workspacePath);
+    if (manifest.targetReceipt && !workspaceHydrationReceiptsEqual(receipt2, manifest.targetReceipt)) {
+      updateHydratedWorkspaceReceipt(workspacePath, manifest.targetReceipt);
+    }
+    removeHydrationTransaction(workspacePath);
+    return;
+  }
+  const receipt = readHydratedWorkspaceReceipt(workspacePath);
+  if (manifest.targetReceipt && !workspaceHydrationReceiptsEqual(manifest.targetReceipt, manifest.receiptBefore) && workspaceHydrationReceiptsEqual(receipt, manifest.targetReceipt)) {
+    removeHydrationTransaction(workspacePath);
+    return;
+  }
+  restoreHydrationTransaction(workspacePath, manifest);
+  removeHydrationTransaction(workspacePath);
+}
+function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
+  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 });
+  try {
+    const snapshotRoot = path.join(stagingPath, "mounts");
+    fs.mkdirSync(snapshotRoot, { mode: 448 });
+    const manifest = {
+      version: 2,
+      targetReceipt,
+      receiptBefore: readHydratedWorkspaceReceipt(workspacePath),
+      mounts: mounts.map((mount, index) => {
+        const sourcePath = path.resolve(mount.sourcePath);
+        const durabilityRootPath = path.resolve(mount.durabilityRootPath);
+        assertManagedDirectoryPath({
+          trustedRoot: durabilityRootPath,
+          candidate: sourcePath,
+          label: `Workspace hydration snapshot mount ${mount.id}`
+        });
+        const sourceStatus = lstatIfExists(sourcePath);
+        if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
+          throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
+        }
+        const snapshotName = String(index);
+        const snapshotPath = path.join(snapshotRoot, snapshotName);
+        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 {
+          id: mount.id,
+          incarnationKey: mount.hydrationIncarnationKey,
+          sourcePath,
+          durabilityRootPath,
+          workspaceRelativePath: mount.workspaceRelativePath,
+          existed: Boolean(sourceStatus),
+          snapshotName
+        };
+      })
+    };
+    writePrivateFileDurably(path.join(stagingPath, "manifest.json"), `${JSON.stringify(manifest)}
+`);
+    fsyncTree(stagingPath);
+    fs.renameSync(stagingPath, transactionPath);
+    fsyncDirectory(stateDirectory);
+    return manifest;
+  } catch (error) {
+    fs.rmSync(stagingPath, { recursive: true, force: true });
+    fsyncDirectory(stateDirectory);
+    throw error;
+  }
+}
+function markHydrationTransactionDurable(workspacePath) {
+  const transactionPath = hydrationTransactionPath(workspacePath);
+  writePrivateFileDurably(path.join(transactionPath, "committed"), "committed\n");
+  fsyncDirectory(transactionPath);
+}
+function fsyncHydratedWorkspaceMount(mount) {
+  assertManagedDirectoryPath({
+    trustedRoot: mount.durabilityRootPath,
+    candidate: mount.sourcePath,
+    label: `Workspace mount ${mount.id} source`
+  });
+  const syncEntry = (entryPath, root) => {
+    const status = fs.lstatSync(entryPath);
+    if (status.isSymbolicLink()) return;
+    if (status.isDirectory()) {
+      for (const name of fs.readdirSync(entryPath)) {
+        if (root && name === ".git") continue;
+        syncEntry(path.join(entryPath, name), false);
+      }
+      fsyncDirectory(entryPath);
+      return;
+    }
+    if (!status.isFile()) return;
+    const descriptor = fs.openSync(entryPath, fs.constants.O_RDONLY);
+    try {
+      fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  };
+  if (fs.existsSync(mount.sourcePath)) syncEntry(mount.sourcePath, true);
+  const durabilityRoot = path.resolve(mount.durabilityRootPath);
+  let boundaryParent = path.dirname(path.resolve(mount.sourcePath));
+  while (true) {
+    if (fs.existsSync(boundaryParent)) {
+      const boundaryStatus = fs.lstatSync(boundaryParent);
+      if (!boundaryStatus.isDirectory() || boundaryStatus.isSymbolicLink()) {
+        throw new Error(`Workspace mount durability boundary is not a regular directory: ${boundaryParent}`);
+      }
+      fsyncDirectory(boundaryParent);
+    }
+    if (boundaryParent === durabilityRoot) break;
+    const nextParent = path.dirname(boundaryParent);
+    if (nextParent === boundaryParent) {
+      throw new Error(`Workspace mount ${mount.sourcePath} does not descend from durability root ${durabilityRoot}`);
+    }
+    boundaryParent = nextParent;
+  }
+}
+function fsyncHydratedWorkspaceMounts(mounts) {
+  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount);
+}
 function workspaceIsShallow(workspacePath) {
   return gitResult(workspacePath, ["rev-parse", "--is-shallow-repository"]).stdout === "true";
 }
@@ -60,7 +698,22 @@ function validateMounts(workspacePath, mounts) {
   const paths = [];
   for (const mount of mounts) {
     if (!mount.id || ids.has(mount.id)) throw new Error(`Workspace mount id must be unique: ${mount.id}`);
+    if (!mount.hydrationIncarnationKey || mount.hydrationIncarnationKey.includes("\0")) {
+      throw new Error(`Workspace mount hydration incarnation is invalid: ${mount.id}`);
+    }
     ids.add(mount.id);
+    const sourcePath = path.resolve(mount.sourcePath);
+    const durabilityRoot = path.resolve(mount.durabilityRootPath);
+    const durabilityRelative = path.relative(durabilityRoot, sourcePath);
+    const durabilityRootStatus = fs.lstatSync(durabilityRoot);
+    if (!durabilityRootStatus.isDirectory() || durabilityRootStatus.isSymbolicLink() || !durabilityRelative || durabilityRelative === ".." || durabilityRelative.startsWith(`..${path.sep}`) || path.isAbsolute(durabilityRelative)) {
+      throw new Error(`Workspace mount source escapes its durability root: ${mount.sourcePath}`);
+    }
+    assertManagedDirectoryPath({
+      trustedRoot: durabilityRoot,
+      candidate: sourcePath,
+      label: `Workspace mount ${mount.id} source`
+    });
     const normalized = mount.workspaceRelativePath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
     if (!normalized || normalized === "." || normalized.split("/").some((segment) => segment === ".." || segment === ".git")) {
       throw new Error(`Invalid workspace mount path: ${mount.workspaceRelativePath}`);
@@ -107,6 +760,8 @@ function configureWorkspaceRepository(input) {
   if (!name || !email) throw new Error("Workspace Git identity must include name and email");
   git(input.workspacePath, ["config", "--local", "user.name", name], "configure workspace Git user name");
   git(input.workspacePath, ["config", "--local", "user.email", email], "configure workspace Git user email");
+  git(input.workspacePath, ["config", "--local", "core.fsync", "committed"], "configure durable workspace commits");
+  git(input.workspacePath, ["config", "--local", "core.fsyncMethod", "fsync"], "configure workspace fsync method");
 }
 function fetchWorkspaceHead(workspacePath, remoteUrl, credentialHelper, credentialUsername) {
   const result = gitResult(workspacePath, [
@@ -130,7 +785,24 @@ ${result.stdout}`;
 }
 function ensureWorkspaceGitClone(input) {
   const workspacePath = path.resolve(input.workspacePath);
+  const workspaceParent = path.dirname(workspacePath);
+  const parentStatus = fs.lstatSync(workspaceParent);
+  if (!parentStatus.isDirectory() || parentStatus.isSymbolicLink()) {
+    throw new Error(`Workspace clone parent is not a regular directory: ${workspaceParent}`);
+  }
+  const workspaceStatus = lstatIfExists(workspacePath);
+  if (workspaceStatus) {
+    if (!workspaceStatus.isDirectory() || workspaceStatus.isSymbolicLink()) {
+      throw new Error(`Workspace clone root is not a regular directory: ${workspacePath}`);
+    }
+  }
   const gitPath = path.join(workspacePath, ".git");
+  const gitStatus = lstatIfExists(gitPath);
+  if (gitStatus) {
+    if (!gitStatus.isDirectory() || gitStatus.isSymbolicLink()) {
+      throw new Error(`Workspace clone Git metadata is not a regular directory: ${gitPath}`);
+    }
+  }
   if (!fs.existsSync(gitPath)) {
     fs.rmSync(workspacePath, { recursive: true, force: true });
     fs.mkdirSync(path.dirname(workspacePath), { recursive: true });
@@ -152,6 +824,7 @@ function ensureWorkspaceGitClone(input) {
     }
   }
   configureWorkspaceRepository({ ...input, workspacePath });
+  recoverWorkspaceCheckoutDurability(workspacePath);
   const previousRemoteHead = revParse(workspacePath, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`);
   const localHeadBeforeFetch = revParse(workspacePath, "HEAD");
   if (!revParse(workspacePath, WORKSPACE_GIT_INTEGRATED_REF) && previousRemoteHead && localHeadBeforeFetch && tryGit(workspacePath, ["merge-base", "--is-ancestor", previousRemoteHead, localHeadBeforeFetch])) {
@@ -160,17 +833,21 @@ function ensureWorkspaceGitClone(input) {
   const remoteHead = fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername);
   let localHead = revParse(workspacePath, "HEAD");
   if (!localHead && remoteHead) {
-    git(
-      workspacePath,
-      ["checkout", "--no-recurse-submodules", "-B", WORKSPACE_GIT_BRANCH, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`],
-      "check out workspace main"
-    );
+    runWorkspaceCheckoutTransition(workspacePath, () => {
+      git(
+        workspacePath,
+        ["checkout", "--no-recurse-submodules", "-B", WORKSPACE_GIT_BRANCH, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`],
+        "check out workspace main"
+      );
+    });
     localHead = remoteHead;
   }
   if (localHead && remoteHead && localHead === remoteHead) {
     updateIntegratedWorkspaceHead(workspacePath, remoteHead);
   } else if (localHead && remoteHead && workspaceIsShallow(workspacePath) && !tryGit(workspacePath, ["merge-base", localHead, remoteHead]) && revParse(workspacePath, WORKSPACE_GIT_INTEGRATED_REF) === localHead && workspaceIsClean(workspacePath)) {
-    git(workspacePath, ["reset", "--hard", remoteHead], "advance workspace across retained history boundary");
+    runWorkspaceCheckoutTransition(workspacePath, () => {
+      git(workspacePath, ["reset", "--hard", remoteHead], "advance workspace across retained history boundary");
+    });
     updateIntegratedWorkspaceHead(workspacePath, remoteHead);
     localHead = remoteHead;
   }
@@ -190,6 +867,16 @@ function activeMounts(mounts) {
 }
 function mirrorMountsToWorkspace(workspacePath, mounts) {
   for (const mount of mounts) {
+    assertManagedDirectoryPath({
+      trustedRoot: mount.durabilityRootPath,
+      candidate: mount.sourcePath,
+      label: `Workspace mount ${mount.id} source`
+    });
+    assertManagedDirectoryPath({
+      trustedRoot: workspacePath,
+      candidate: path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/")),
+      label: `Workspace mount ${mount.id} outer target`
+    });
     mirrorWorkingTree({
       sourceRoot: mount.sourcePath,
       targetRoot: path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/")),
@@ -201,6 +888,11 @@ function mirrorMountsToWorkspace(workspacePath, mounts) {
 function removeWorkspaceMounts(workspacePath, mounts) {
   for (const mount of mounts) {
     const targetPath = path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+    assertManagedDirectoryPath({
+      trustedRoot: workspacePath,
+      candidate: targetPath,
+      label: `Workspace mount ${mount.id} outer target`
+    });
     const relative = path.relative(path.resolve(workspacePath), path.resolve(targetPath));
     if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
       throw new Error(`Workspace mount escapes the workspace clone: ${mount.workspaceRelativePath}`);
@@ -208,9 +900,45 @@ function removeWorkspaceMounts(workspacePath, mounts) {
     fs.rmSync(targetPath, { recursive: true, force: true });
   }
 }
-function hydrateWorkspaceGitMounts(workspacePath, mounts) {
+function restoreDeferredWorkspaceMountsFromHead(workspacePath, mounts) {
+  const head = revParse(workspacePath, "HEAD");
   for (const mount of mounts) {
+    const normalized = normalizedWorkspaceMountPath(mount.workspaceRelativePath);
+    const targetPath = path.join(workspacePath, ...normalized.split("/"));
+    assertManagedDirectoryPath({
+      trustedRoot: workspacePath,
+      candidate: targetPath,
+      label: `Deferred workspace mount ${mount.id} outer target`
+    });
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    if (head && tryGit(workspacePath, ["cat-file", "-e", `${head}:${normalized}`])) {
+      git(
+        workspacePath,
+        ["checkout", "--no-recurse-submodules", head, "--", `:(literal)${normalized}`],
+        `restore deferred workspace mount ${mount.id} from its integration basis`
+      );
+    }
+  }
+}
+function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
+  const hydratedMountIds = [];
+  const skippedMountIds = [];
+  for (const mount of mounts) {
+    if (!options.ignoreBusy && mount.busy?.()) {
+      skippedMountIds.push(mount.id);
+      continue;
+    }
     const sourceRoot = path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+    assertManagedDirectoryPath({
+      trustedRoot: workspacePath,
+      candidate: sourceRoot,
+      label: `Workspace mount ${mount.id} outer source`
+    });
+    assertManagedDirectoryPath({
+      trustedRoot: mount.durabilityRootPath,
+      candidate: mount.sourcePath,
+      label: `Workspace mount ${mount.id} hydration target`
+    });
     if (!fs.existsSync(sourceRoot)) {
       if (mount.hydrateDeletionMode === "all") {
         fs.rmSync(mount.sourcePath, { recursive: true, force: true });
@@ -227,37 +955,167 @@ function hydrateWorkspaceGitMounts(workspacePath, mounts) {
           fs.rmSync(emptyRoot, { recursive: true, force: true });
         }
       }
+      hydratedMountIds.push(mount.id);
       continue;
     }
+    const targetExists = fs.existsSync(mount.sourcePath);
     mirrorWorkingTree({
       sourceRoot,
       targetRoot: mount.sourcePath,
       sourceMode: "all",
-      deletionMode: mount.hydrateDeletionMode
+      // A missing checkout has no Git index to define git-only deletions. Its
+      // newly created directory is empty, so all-mode is equivalent and lets
+      // bootstrap hydration preserve the fetched tree before Git initializes.
+      deletionMode: targetExists ? mount.hydrateDeletionMode : "all"
     });
+    hydratedMountIds.push(mount.id);
+  }
+  return { hydratedMountIds: hydratedMountIds.sort(), skippedMountIds: skippedMountIds.sort() };
+}
+function hydrateWorkspaceGitMountsTransactionally(input) {
+  const workspacePath = path.resolve(input.workspacePath);
+  const mountIds = input.mounts.map(({ id }) => id).sort();
+  const requiredIds = (input.requiredMounts ?? input.mounts).map(({ id }) => id).sort();
+  if (mountIds.length !== requiredIds.length || mountIds.some((id, index) => id !== requiredIds[index])) {
+    return { hydratedMountIds: [], skippedMountIds: requiredIds };
+  }
+  const busyMountIds = input.ignoreBusy ? [] : (input.durabilityMounts ?? input.mounts).filter((mount) => mount.busy?.()).map(({ id }) => id).sort();
+  if (busyMountIds.length > 0) {
+    return { hydratedMountIds: [], skippedMountIds: busyMountIds };
+  }
+  if (input.recordCurrentHead && !workspaceCheckoutDurabilityIsCurrent(workspacePath)) {
+    throw new Error("Workspace checkout is not durably materialized at its current HEAD");
+  }
+  const targetHead = input.recordCurrentHead ? revParse(workspacePath, "HEAD") : null;
+  const targetReceipt = targetHead ? workspaceHydrationReceipt(targetHead, input.receiptMounts ?? input.durabilityMounts ?? input.mounts) : null;
+  const manifest = beginHydrationTransaction(workspacePath, input.mounts, targetReceipt);
+  try {
+    const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, input.mounts, { ignoreBusy: true });
+    if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== requiredIds.length || hydration.hydratedMountIds.some((id, index) => id !== requiredIds[index])) {
+      throw new Error("Workspace hydration did not include every required mount");
+    }
+    fsyncHydratedWorkspaceMounts(input.durabilityMounts ?? input.mounts);
+    markHydrationTransactionDurable(workspacePath);
+    if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
+    removeHydrationTransaction(workspacePath);
+    return hydration;
+  } catch (error) {
+    const transactionPath = hydrationTransactionPath(workspacePath);
+    if (lstatIfExists(transactionPath) && hydrationTransactionCommitted(transactionPath)) {
+      throw error;
+    }
+    try {
+      restoreHydrationTransaction(workspacePath, manifest);
+      removeHydrationTransaction(workspacePath);
+    } catch (restoreError) {
+      throw new AggregateError(
+        [error, restoreError],
+        `Workspace hydration failed and its durable snapshot could not be restored: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    throw error;
+  }
+}
+function hydrateWorkspaceGitMounts(workspacePath, mounts, options = {}) {
+  const gitDirectory = path.join(path.resolve(workspacePath), ".git");
+  if (!fs.existsSync(gitDirectory)) {
+    return hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options);
+  }
+  recoverWorkspaceCheckoutDurability(path.resolve(workspacePath));
+  return hydrateWorkspaceGitMountsTransactionally({
+    workspacePath,
+    mounts,
+    ignoreBusy: options.ignoreBusy
+  });
+}
+function recoverWorkspaceGitHydration(workspacePath, mounts, options = {}) {
+  workspacePath = path.resolve(workspacePath);
+  validateMounts(workspacePath, mounts);
+  recoverWorkspaceCheckoutDurability(workspacePath);
+  recoverPendingHydrationTransaction(workspacePath);
+  const currentHead = revParse(workspacePath, "HEAD");
+  if (!currentHead) return;
+  const currentReceipt = readHydratedWorkspaceReceipt(workspacePath);
+  const outerHeadContainsMount = (mount) => tryGit(workspacePath, ["cat-file", "-e", `HEAD:${normalizedWorkspaceMountPath(mount.workspaceRelativePath)}`]);
+  const configuredBasisMounts = configuredWorkspaceHydrationBasisMounts(workspacePath, mounts, options.deferMountIds);
+  const uncoveredBasisMounts = configuredBasisMounts.filter(
+    (mount) => !workspaceHydrationReceiptCoversMount(currentReceipt, currentHead, mount)
+  );
+  if (workspaceHydrationReceiptMatchesMounts(currentReceipt, currentHead, configuredBasisMounts)) return;
+  const busyMountIds = options.ignoreBusy ? [] : uncoveredBasisMounts.filter((mount) => mount.busy?.()).map(({ id }) => id);
+  if (busyMountIds.length > 0) {
+    throw new Error(
+      `Workspace HEAD ${currentHead} has not been fully hydrated; busy mounts must finish before projection: ${busyMountIds.join(", ")}`
+    );
+  }
+  const hydrationTargets = uncoveredBasisMounts.filter(
+    (mount) => !mount.deleteWhenSourceMissing && !(mount.preserveLocalOnHydrationBasisChange === true && currentReceipt?.head === currentHead) && (outerHeadContainsMount(mount) || mount.preserveLocalOnInitialOuterAbsence !== true)
+  );
+  const hydration = hydrateWorkspaceGitMountsTransactionally({
+    workspacePath,
+    mounts: hydrationTargets,
+    durabilityMounts: uncoveredBasisMounts,
+    receiptMounts: configuredBasisMounts,
+    requiredMounts: hydrationTargets,
+    ignoreBusy: options.ignoreBusy,
+    recordCurrentHead: true
+  });
+  if (hydration.skippedMountIds.length > 0) {
+    throw new Error(
+      `Workspace HEAD ${currentHead} has not been fully hydrated; busy mounts must finish before projection: ${hydration.skippedMountIds.join(", ")}`
+    );
   }
 }
 function resetWorkspaceGit(input) {
   const workspacePath = path.resolve(input.workspacePath);
   validateMounts(workspacePath, input.mounts);
   const initial = ensureWorkspaceGitClone({ ...input, workspacePath });
+  recoverPendingHydrationTransaction(workspacePath);
   const status = gitResult(workspacePath, ["status", "--porcelain=v1", "-z"]);
   const discardedPaths = status.exitCode === 0 ? status.stdout.split("\0").filter(Boolean).map((entry) => entry.slice(3)).sort() : [];
   const remoteHead = fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername);
   if (remoteHead) {
-    git(workspacePath, ["checkout", "--no-recurse-submodules", "-B", WORKSPACE_GIT_BRANCH, remoteHead], "reset workspace main");
-    git(workspacePath, ["clean", "-fd", "--", "."], "remove untracked workspace changes");
+    runWorkspaceCheckoutTransition(workspacePath, () => {
+      git(workspacePath, ["checkout", "--no-recurse-submodules", "-B", WORKSPACE_GIT_BRANCH, remoteHead], "reset workspace main");
+      git(workspacePath, ["clean", "-fd", "--", "."], "remove untracked workspace changes");
+    });
   } else if (revParse(workspacePath, "HEAD")) {
-    git(workspacePath, ["rm", "-rf", "--ignore-unmatch", "--", "."], "clear unborn workspace tree");
-    git(workspacePath, ["commit", "--allow-empty", "-m", JSON.stringify({ type: "workspace_reset" })], "record empty workspace reset");
+    runWorkspaceCheckoutTransition(workspacePath, () => {
+      git(workspacePath, ["rm", "-rf", "--ignore-unmatch", "--", "."], "clear unborn workspace tree");
+      git(workspacePath, ["commit", "--allow-empty", "-m", JSON.stringify({ type: "workspace_reset" })], "record empty workspace reset");
+    });
   }
   const selected = activeMounts(input.mounts);
-  hydrateWorkspaceGitMounts(workspacePath, selected.active);
+  const requiredLiveMountsBeforeHydration = input.mounts.filter(({ sourcePath }) => fs.existsSync(sourcePath));
+  const bootstrapMounts = selected.skipped.filter((mount) => {
+    if (mount.deleteWhenSourceMissing || fs.existsSync(mount.sourcePath) || mount.busy?.()) return false;
+    const outerPath = path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+    return fs.existsSync(outerPath);
+  });
+  const hydrationMounts = [...selected.active, ...bootstrapMounts];
+  const requiredLiveMounts = [
+    ...new Map([...requiredLiveMountsBeforeHydration, ...bootstrapMounts].map((mount) => [mount.id, mount])).values()
+  ];
+  const hydration = hydrateWorkspaceGitMountsTransactionally({
+    workspacePath,
+    mounts: hydrationMounts,
+    durabilityMounts: [...requiredLiveMounts, ...selected.tombstones],
+    receiptMounts: input.mounts,
+    requiredMounts: requiredLiveMounts,
+    recordCurrentHead: true
+  });
+  const requiredLiveIds = requiredLiveMounts.map(({ id }) => id).sort();
+  const resetHead = revParse(workspacePath, "HEAD");
+  if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== requiredLiveIds.length || hydration.hydratedMountIds.some((id, index) => id !== requiredLiveIds[index]) || resetHead && !workspaceHydrationReceiptMatchesMounts(readHydratedWorkspaceReceipt(workspacePath), resetHead, input.mounts)) {
+    throw new Error("Workspace reset could not durably hydrate every live mount; remediation remains active");
+  }
   return {
     startingHead: initial.localHead,
     localHead: revParse(workspacePath, "HEAD"),
     remoteHead,
-    discardedPaths
+    discardedPaths,
+    activeMountIds: hydration.hydratedMountIds,
+    skippedMountIds: [.../* @__PURE__ */ new Set([...selected.skipped.map(({ id }) => id), ...hydration.skippedMountIds])].sort()
   };
 }
 function stagedPaths(workspacePath) {
@@ -322,17 +1180,22 @@ function snapshotConflict(input) {
 }
 function rebaseWorkspace(input) {
   const remoteRevision = `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`;
+  beginWorkspaceCheckoutTransition(input.workspacePath);
   const rebase = gitResult(
     input.workspacePath,
     input.truncatedHistoryBase ? ["rebase", "--onto", remoteRevision, input.truncatedHistoryBase] : ["rebase", remoteRevision]
   );
-  if (rebase.exitCode === 0) return { ok: true };
+  if (rebase.exitCode === 0) {
+    completeWorkspaceCheckoutTransition(input.workspacePath);
+    return { ok: true };
+  }
   const conflicts = conflictPaths(input.workspacePath);
   const refs = snapshotConflict(input);
   const abort = gitResult(input.workspacePath, ["rebase", "--abort"]);
   if (abort.exitCode !== 0) {
     throw new Error(`Abort workspace rebase: ${abort.stderr || abort.stdout || `git exited ${abort.exitCode}`}`);
   }
+  completeWorkspaceCheckoutTransition(input.workspacePath);
   return {
     ok: false,
     conflictPaths: conflicts,
@@ -342,26 +1205,31 @@ function rebaseWorkspace(input) {
 }
 function synchronizeWithFetchedHead(input) {
   const localHead = revParse(input.workspacePath, "HEAD");
-  if (!input.remoteHead) return { kind: "ready", updated: false, rebased: false };
+  const remoteHead = input.remoteHead;
+  if (!remoteHead) return { kind: "ready", updated: false, rebased: false };
   if (!localHead) {
-    git(
-      input.workspacePath,
-      ["checkout", "--no-recurse-submodules", "-B", WORKSPACE_GIT_BRANCH, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`],
-      "check out fetched workspace main"
-    );
+    runWorkspaceCheckoutTransition(input.workspacePath, () => {
+      git(
+        input.workspacePath,
+        ["checkout", "--no-recurse-submodules", "-B", WORKSPACE_GIT_BRANCH, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`],
+        "check out fetched workspace main"
+      );
+    });
     return { kind: "ready", updated: true, rebased: false };
   }
-  if (localHead === input.remoteHead) {
-    updateIntegratedWorkspaceHead(input.workspacePath, input.remoteHead);
+  if (localHead === remoteHead) {
+    updateIntegratedWorkspaceHead(input.workspacePath, remoteHead);
     return { kind: "ready", updated: false, rebased: false };
   }
-  if (tryGit(input.workspacePath, ["merge-base", "--is-ancestor", localHead, input.remoteHead])) {
-    git(input.workspacePath, ["reset", "--hard", input.remoteHead], "fast-forward workspace main");
-    updateIntegratedWorkspaceHead(input.workspacePath, input.remoteHead);
+  if (tryGit(input.workspacePath, ["merge-base", "--is-ancestor", localHead, remoteHead])) {
+    runWorkspaceCheckoutTransition(input.workspacePath, () => {
+      git(input.workspacePath, ["reset", "--hard", remoteHead], "fast-forward workspace main");
+    });
+    updateIntegratedWorkspaceHead(input.workspacePath, remoteHead);
     return { kind: "ready", updated: true, rebased: false };
   }
-  if (tryGit(input.workspacePath, ["merge-base", "--is-ancestor", input.remoteHead, localHead])) {
-    updateIntegratedWorkspaceHead(input.workspacePath, input.remoteHead);
+  if (tryGit(input.workspacePath, ["merge-base", "--is-ancestor", remoteHead, localHead])) {
+    updateIntegratedWorkspaceHead(input.workspacePath, remoteHead);
     return { kind: "ready", updated: false, rebased: false };
   }
   const integratedHead = revParse(input.workspacePath, WORKSPACE_GIT_INTEGRATED_REF);
@@ -374,11 +1242,11 @@ function synchronizeWithFetchedHead(input) {
   const rebased = rebaseWorkspace({
     workspacePath: input.workspacePath,
     localHead,
-    remoteHead: input.remoteHead,
+    remoteHead,
     attemptId: input.attemptId,
     truncatedHistoryBase
   });
-  if (rebased.ok) updateIntegratedWorkspaceHead(input.workspacePath, input.remoteHead);
+  if (rebased.ok) updateIntegratedWorkspaceHead(input.workspacePath, remoteHead);
   return rebased.ok ? { kind: "ready", updated: false, rebased: true } : { kind: "conflict", conflictPaths: rebased.conflictPaths, refs: rebased.refs, error: rebased.error };
 }
 async function synchronizeWorkspaceGit(input) {
@@ -387,25 +1255,131 @@ async function synchronizeWorkspaceGit(input) {
   const maxDiffBytes = input.maxDiffBytes ?? MAX_WORKSPACE_GIT_DIFF_BYTES;
   const maxPushAttempts = Math.max(1, input.maxPushAttempts ?? 4);
   validateMounts(workspacePath, input.mounts);
+  const busyLiveMountIds = input.skipMountMirror ? [] : input.mounts.filter((mount) => !(mount.deleteWhenSourceMissing && !fs.existsSync(mount.sourcePath)) && mount.busy?.()).map(({ id }) => id).sort();
+  if (busyLiveMountIds.length > 0) {
+    const cloneExists = fs.existsSync(path.join(workspacePath, ".git"));
+    const localHead = cloneExists ? revParse(workspacePath, "HEAD") : null;
+    const remoteHead2 = cloneExists ? revParse(workspacePath, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`) : null;
+    return {
+      outcome: "no_change",
+      startingHead: localHead,
+      localHead,
+      remoteHead: remoteHead2,
+      publishedHead: remoteHead2,
+      rebaseCount: 0,
+      diffSizeBytes: 0,
+      affectedPaths: [],
+      activeMountIds: [],
+      skippedMountIds: input.mounts.map(({ id }) => id).sort()
+    };
+  }
   const initial = ensureWorkspaceGitClone({ ...input, workspacePath });
   const startingHead = initial.localHead;
+  const receiptBeforeInitialHydration = readHydratedWorkspaceReceipt(workspacePath);
+  const deferredMountIds = /* @__PURE__ */ new Set();
+  if (initial.localHead && initial.remoteHead && initial.remoteHead !== initial.localHead && receiptBeforeInitialHydration?.head === initial.localHead) {
+    for (const mount of input.mounts) {
+      if (!mount.deleteWhenSourceMissing && mount.preserveLocalOnInitialOuterAbsence !== true && mount.preserveLocalOnHydrationBasisChange !== true && !workspaceHydrationReceiptCoversMount(receiptBeforeInitialHydration, initial.localHead, mount)) {
+        deferredMountIds.add(mount.id);
+      }
+    }
+  }
+  recoverWorkspaceGitHydration(workspacePath, input.mounts, {
+    ...deferredMountIds.size > 0 ? { deferMountIds: deferredMountIds } : {}
+  });
+  const receiptRequiredLiveMounts = input.mounts.filter(({ sourcePath }) => fs.existsSync(sourcePath));
   const selected = activeMounts(input.mounts);
+  const projectedActiveMounts = selected.active.filter(({ id }) => !deferredMountIds.has(id));
+  const projectedTombstones = selected.tombstones.filter(({ id }) => !deferredMountIds.has(id));
+  const projectionBasisHead = revParse(workspacePath, "HEAD");
+  const projectionBasisReceipt = readHydratedWorkspaceReceipt(workspacePath);
+  const projectionReceiptMounts = configuredWorkspaceHydrationBasisMounts(workspacePath, input.mounts).filter(
+    (mount) => !deferredMountIds.has(mount.id) && Boolean(projectionBasisHead && workspaceHydrationReceiptCoversMount(projectionBasisReceipt, projectionBasisHead, mount))
+  );
+  const completedMountSelection = (requireCurrentHeadReceipt = false) => {
+    const currentHeadBeforeHydration = revParse(workspacePath, "HEAD");
+    const completionReceiptMounts = configuredWorkspaceHydrationBasisMounts(workspacePath, input.mounts);
+    if (currentHeadBeforeHydration && workspaceHydrationReceiptMatchesMounts(
+      readHydratedWorkspaceReceipt(workspacePath),
+      currentHeadBeforeHydration,
+      completionReceiptMounts
+    )) {
+      const lateBusyIds = selected.active.filter((mount) => mount.busy?.()).map(({ id }) => id);
+      const lateBusy = new Set(lateBusyIds);
+      return {
+        activeMountIds: [...selected.active.filter(({ id }) => !lateBusy.has(id)), ...selected.tombstones].map(({ id }) => id).sort(),
+        skippedMountIds: [.../* @__PURE__ */ new Set([...selected.skipped.map(({ id }) => id), ...lateBusyIds])].sort()
+      };
+    }
+    const currentReceiptBeforeHydration = readHydratedWorkspaceReceipt(workspacePath);
+    const mountIsAlreadyCovered = (mount) => Boolean(
+      currentHeadBeforeHydration && workspaceHydrationReceiptCoversMount(currentReceiptBeforeHydration, currentHeadBeforeHydration, mount)
+    );
+    const uncoveredCompletionMounts = selected.active.filter((mount) => !mountIsAlreadyCovered(mount));
+    const uncoveredRequiredLiveMounts = receiptRequiredLiveMounts.filter((mount) => !mountIsAlreadyCovered(mount));
+    const uncoveredCompletionBasisMounts = completionReceiptMounts.filter((mount) => !mountIsAlreadyCovered(mount));
+    const hydration = hydrateWorkspaceGitMountsTransactionally({
+      workspacePath,
+      mounts: uncoveredCompletionMounts,
+      durabilityMounts: uncoveredCompletionBasisMounts,
+      receiptMounts: completionReceiptMounts,
+      requiredMounts: uncoveredRequiredLiveMounts,
+      recordCurrentHead: true
+    });
+    if (requireCurrentHeadReceipt) {
+      const currentHead = revParse(workspacePath, "HEAD");
+      if (currentHead && !workspaceHydrationReceiptMatchesMounts(readHydratedWorkspaceReceipt(workspacePath), currentHead, completionReceiptMounts)) {
+        throw new Error(`Workspace inbound integration ${currentHead} could not be fully hydrated before publication continued`);
+      }
+    }
+    return {
+      activeMountIds: [...selected.active, ...selected.tombstones].map(({ id }) => id).sort(),
+      skippedMountIds: [.../* @__PURE__ */ new Set([...selected.skipped.map(({ id }) => id), ...hydration.skippedMountIds])].sort()
+    };
+  };
+  let newlyStagedPaths = [];
+  const stageAndCommitWorkspace = () => {
+    git(workspacePath, ["add", "-A", "--", "."], "stage workspace working trees");
+    newlyStagedPaths = stagedPaths(workspacePath);
+    if (newlyStagedPaths.length > 0) {
+      git(
+        workspacePath,
+        [
+          "commit",
+          "-m",
+          JSON.stringify({ type: "workspace_sync", worker: input.workerLabel, attemptId, detail: input.commitDetail ?? null })
+        ],
+        "commit workspace working trees"
+      );
+    }
+  };
   if (!input.skipMountMirror) {
-    mirrorMountsToWorkspace(workspacePath, selected.active);
-    removeWorkspaceMounts(workspacePath, selected.tombstones);
+    beginWorkspaceCheckoutTransition(workspacePath);
+    try {
+      mirrorMountsToWorkspace(workspacePath, projectedActiveMounts);
+      removeWorkspaceMounts(workspacePath, projectedTombstones);
+      restoreDeferredWorkspaceMountsFromHead(
+        workspacePath,
+        input.mounts.filter(({ id }) => deferredMountIds.has(id))
+      );
+      stageAndCommitWorkspace();
+      fsyncWorkspaceCheckoutTree(workspacePath);
+    } catch (error) {
+      throwAfterWorkspaceCheckoutRecovery(workspacePath, error);
+    }
+  } else {
+    stageAndCommitWorkspace();
+    if (newlyStagedPaths.length > 0) completeWorkspaceCheckoutTransition(workspacePath);
   }
-  git(workspacePath, ["add", "-A", "--", "."], "stage workspace working trees");
-  const newlyStagedPaths = stagedPaths(workspacePath);
-  if (newlyStagedPaths.length > 0) {
-    git(
-      workspacePath,
-      [
-        "commit",
-        "-m",
-        JSON.stringify({ type: "workspace_sync", worker: input.workerLabel, attemptId, detail: input.commitDetail ?? null })
-      ],
-      "commit workspace working trees"
-    );
+  if (!input.skipMountMirror) {
+    const projectedHead = revParse(workspacePath, "HEAD");
+    if (!projectedHead) throw new Error("Workspace projection did not retain a local HEAD");
+    const targetProjectionReceipt = workspaceHydrationReceipt(projectedHead, projectionReceiptMounts);
+    if (!workspaceHydrationReceiptsEqual(readHydratedWorkspaceReceipt(workspacePath), targetProjectionReceipt)) {
+      fsyncHydratedWorkspaceMounts([...projectedActiveMounts, ...projectedTombstones]);
+      updateHydratedWorkspaceReceipt(workspacePath, targetProjectionReceipt);
+    }
+    completeWorkspaceCheckoutTransition(workspacePath);
   }
   let remoteHead = fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername);
   let rebaseCount = 0;
@@ -423,8 +1397,8 @@ async function synchronizeWorkspaceGit(input) {
         rebaseCount: rebaseCount + 1,
         diffSizeBytes: 0,
         affectedPaths: [.../* @__PURE__ */ new Set([...newlyStagedPaths, ...reconciled.conflictPaths])].sort(),
-        activeMountIds: [...selected.active, ...selected.tombstones].map(({ id }) => id).sort(),
-        skippedMountIds: selected.skipped.map(({ id }) => id).sort(),
+        activeMountIds: [...projectedActiveMounts, ...projectedTombstones].map(({ id }) => id).sort(),
+        skippedMountIds: [.../* @__PURE__ */ new Set([...selected.skipped.map(({ id }) => id), ...deferredMountIds])].sort(),
         conflictPaths: reconciled.conflictPaths,
         conflictSnapshotRefs: reconciled.refs,
         error: reconciled.error
@@ -432,6 +1406,7 @@ async function synchronizeWorkspaceGit(input) {
     }
     updated ||= reconciled.updated;
     if (reconciled.rebased) rebaseCount += 1;
+    if (reconciled.updated || reconciled.rebased) completedMountSelection(true);
     const localHead = revParse(workspacePath, "HEAD");
     if (!localHead) {
       return {
@@ -465,11 +1440,11 @@ async function synchronizeWorkspaceGit(input) {
       };
     }
     if (localHead === remoteHead) {
+      const completedMounts = completedMountSelection(Boolean(input.skipMountMirror));
       await input.afterWorkspacePublished?.({
         publishedHead: localHead,
-        activeMountIds: [...selected.active, ...selected.tombstones].map(({ id }) => id).sort()
+        activeMountIds: completedMounts.activeMountIds
       });
-      if (!input.skipMountHydration) hydrateWorkspaceGitMounts(workspacePath, selected.active);
       return {
         outcome: updated ? "updated" : "no_change",
         startingHead,
@@ -479,8 +1454,7 @@ async function synchronizeWorkspaceGit(input) {
         rebaseCount,
         diffSizeBytes: size,
         affectedPaths: paths,
-        activeMountIds: [...selected.active, ...selected.tombstones].map(({ id }) => id).sort(),
-        skippedMountIds: selected.skipped.map(({ id }) => id).sort()
+        ...completedMounts
       };
     }
     const pushArgs = [
@@ -493,11 +1467,11 @@ async function synchronizeWorkspaceGit(input) {
     const push = gitResult(workspacePath, pushArgs);
     if (push.exitCode === 0) {
       updateIntegratedWorkspaceHead(workspacePath, localHead);
+      const completedMounts = completedMountSelection(Boolean(input.skipMountMirror));
       await input.afterWorkspacePublished?.({
         publishedHead: localHead,
-        activeMountIds: [...selected.active, ...selected.tombstones].map(({ id }) => id).sort()
+        activeMountIds: completedMounts.activeMountIds
       });
-      if (!input.skipMountHydration) hydrateWorkspaceGitMounts(workspacePath, selected.active);
       return {
         outcome: "pushed",
         startingHead,
@@ -507,8 +1481,7 @@ async function synchronizeWorkspaceGit(input) {
         rebaseCount,
         diffSizeBytes: size,
         affectedPaths: paths,
-        activeMountIds: [...selected.active, ...selected.tombstones].map(({ id }) => id).sort(),
-        skippedMountIds: selected.skipped.map(({ id }) => id).sort()
+        ...completedMounts
       };
     }
     if (!/(non-fast-forward|fetch first|rejected|failed to push some refs)/i.test(`${push.stderr}
@@ -529,10 +1502,15 @@ const workspaceGitSyncTestHarness = {
 export {
   MAX_WORKSPACE_GIT_DIFF_BYTES,
   WORKSPACE_GIT_BRANCH,
+  WORKSPACE_GIT_CHECKOUT_DURABILITY,
   WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION,
+  WORKSPACE_GIT_HYDRATED_RECEIPT,
+  WORKSPACE_GIT_HYDRATION_TRANSACTION,
   ensureWorkspaceGitClone,
   hydrateWorkspaceGitMounts,
+  recoverWorkspaceGitHydration,
   resetWorkspaceGit,
   synchronizeWorkspaceGit,
+  workspaceGitHydrationIsCurrent,
   workspaceGitSyncTestHarness
 };