@ricsam/r5d-worker 0.0.55 → 0.0.56

package/dist/mjs/workspace-sync.mjs

@@ -15,6 +15,8 @@ const DESTRUCTIVE_CHECKOUT_MIN_TRACKED_FILES = 20;
 const DESTRUCTIVE_CHECKOUT_REMOVAL_RATIO = 0.8;
 const ACTIVE_GIT_LOCK_PATHS = ["index.lock", "HEAD.lock", "packed-refs.lock", "shallow.lock"];
 const mirrorComparisonCache = /* @__PURE__ */ new Map();
+const gitObjectFormatCache = /* @__PURE__ */ new Map();
+const hydrationEntryCache = /* @__PURE__ */ new Map();
 function gitArgs(input, args) {
   const configArgs = ["-c", "submodule.recurse=false", "-c", "fetch.recurseSubmodules=false", "-c", "push.recurseSubmodules=false"];
   return input.authHeader ? ["git", ...configArgs, "-c", `http.extraHeader=${input.authHeader}`, ...args] : ["git", ...configArgs, ...args];
@@ -219,6 +221,127 @@ function lstatOrNull(filePath) {
     throw error;
   }
 }
+const UNSTABLE_VISIBLE_ENTRY = /* @__PURE__ */ Symbol("unstable-visible-entry");
+function hydrationEntriesEqual(left, right) {
+  if (!left || !right || left.kind !== right.kind || left.objectId !== right.objectId) return left === right;
+  return left.kind === "gitlink" || right.kind === "blob" && left.mode === right.mode;
+}
+function gitObjectFormat(input) {
+  const cached = gitObjectFormatCache.get(input.shadowRoot);
+  if (cached) return cached;
+  const format = runGit(input, input.shadowRoot, ["rev-parse", "--show-object-format"], "inspect workspace object format");
+  if (format !== "sha1" && format !== "sha256") throw new Error(`Unsupported Git object format ${JSON.stringify(format)}`);
+  gitObjectFormatCache.set(input.shadowRoot, format);
+  return format;
+}
+function hashGitBlobBuffer(input, content) {
+  return createHash(gitObjectFormat(input)).update(`blob ${content.byteLength}\0`).update(content).digest("hex");
+}
+function hashGitBlobFile(input, filePath, size) {
+  const hash = createHash(gitObjectFormat(input));
+  hash.update(`blob ${size}\0`);
+  const file = fs.openSync(filePath, "r");
+  const buffer = Buffer.allocUnsafe(Math.min(MIRROR_COMPARE_BUFFER_BYTES, Math.max(1, size)));
+  try {
+    let offset = 0;
+    while (offset < size) {
+      const bytesRead = fs.readSync(file, buffer, 0, Math.min(buffer.length, size - offset), offset);
+      if (bytesRead === 0) return null;
+      hash.update(buffer.subarray(0, bytesRead));
+      offset += bytesRead;
+    }
+    return hash.digest("hex");
+  } finally {
+    fs.closeSync(file);
+  }
+}
+function filesystemHydrationEntry(input, filePath) {
+  const before = lstatOrNull(filePath);
+  if (!before) return void 0;
+  if (!before.isFile() && !before.isSymbolicLink()) return UNSTABLE_VISIBLE_ENTRY;
+  const objectFormat = gitObjectFormat(input);
+  const signature = entrySignature(before);
+  const cached = hydrationEntryCache.get(filePath);
+  if (cached?.signature === signature && cached.objectFormat === objectFormat) return cached.entry;
+  let objectId = null;
+  if (before.isSymbolicLink()) {
+    try {
+      objectId = hashGitBlobBuffer(input, Buffer.from(fs.readlinkSync(filePath)));
+    } catch {
+      return UNSTABLE_VISIBLE_ENTRY;
+    }
+  } else {
+    try {
+      objectId = hashGitBlobFile(input, filePath, before.size);
+    } catch {
+      return UNSTABLE_VISIBLE_ENTRY;
+    }
+  }
+  const after = lstatOrNull(filePath);
+  if (!objectId || !after || entrySignature(before) !== entrySignature(after)) return UNSTABLE_VISIBLE_ENTRY;
+  const entry = {
+    kind: "blob",
+    mode: before.isSymbolicLink() ? "120000" : (before.mode & 73) !== 0 ? "100755" : "100644",
+    objectId
+  };
+  if (hydrationEntryCache.size >= MAX_MIRROR_COMPARISON_CACHE_ENTRIES) hydrationEntryCache.clear();
+  hydrationEntryCache.set(filePath, { signature, objectFormat, entry });
+  return entry;
+}
+function projectVisibleHydrationEntry(input, visibleRoot, filePath, gitlinks) {
+  if (!hasSafeDirectoryAncestors(visibleRoot, filePath, input.projectsRoot)) return UNSTABLE_VISIBLE_ENTRY;
+  const gitlink = gitlinks.get(filePath);
+  if (gitlink) {
+    const target = lstatOrNull(path.join(visibleRoot, ...filePath.split("/")));
+    if (target && !target.isDirectory()) return UNSTABLE_VISIBLE_ENTRY;
+    return { kind: "gitlink", objectId: gitlink.objectId };
+  }
+  return filesystemHydrationEntry(input, path.join(visibleRoot, ...filePath.split("/")));
+}
+function revisionHydrationPreimage(input, revision, relativeRoot) {
+  const result = runGitResult(input, input.shadowRoot, ["--literal-pathspecs", "ls-tree", "-r", "-z", revision, "--", relativeRoot]);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Inspect workspace hydration baseline ${revision}:${relativeRoot}: ${result.stderr || `git exited ${result.exitCode}`}`
+    );
+  }
+  if (!result.stdout) return /* @__PURE__ */ new Map();
+  const prefix = `${relativeRoot}/`;
+  const preimage = /* @__PURE__ */ new Map();
+  for (const serialized of result.stdout.split("\0").filter(Boolean)) {
+    const separator = serialized.indexOf("	");
+    if (separator === -1) continue;
+    const [mode, type, objectId] = serialized.slice(0, separator).split(" ");
+    const workspacePath = serialized.slice(separator + 1);
+    if (!objectId || !workspacePath.startsWith(prefix)) continue;
+    const filePath = workspacePath.slice(prefix.length);
+    if (mode === "160000" && type === "commit") {
+      preimage.set(filePath, { kind: "gitlink", objectId });
+    } else if ((mode === "100644" || mode === "100755" || mode === "120000") && type === "blob") {
+      preimage.set(filePath, { kind: "blob", mode, objectId });
+    }
+  }
+  return preimage;
+}
+function indexHydrationPreimage(input, relativeRoot) {
+  const prefix = `${relativeRoot}/`;
+  const entries = parseGitIndexEntries(
+    runGit(input, input.shadowRoot, ["--literal-pathspecs", "ls-files", "--stage", "-z", "--", relativeRoot], "inspect hydrated workspace")
+  );
+  const unmergedPaths = entries.filter((entry) => entry.stage !== "0").map((entry) => entry.filePath);
+  if (unmergedPaths.length > 0) throw new Error(`Canonical workspace has unmerged Git index stages: ${JSON.stringify(unmergedPaths)}`);
+  const preimage = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.filePath.startsWith(prefix)) continue;
+    const filePath = entry.filePath.slice(prefix.length);
+    if (entry.mode === "160000") {
+      preimage.set(filePath, { kind: "gitlink", objectId: entry.objectId });
+    } else if (entry.mode === "100644" || entry.mode === "100755" || entry.mode === "120000") {
+      preimage.set(filePath, { kind: "blob", mode: entry.mode, objectId: entry.objectId });
+    }
+  }
+  return preimage;
+}
 function worktreeDiffersFromIndex(checkoutPath, filePath) {
   const result = Bun.spawnSync(
     ["git", "--literal-pathspecs", "-c", "core.fileMode=true", "diff", "--quiet", "--no-ext-diff", "--", filePath],
@@ -373,11 +496,17 @@ function removeEmptyDirectories(root, opaqueRoots = []) {
   };
   visit(root, "");
 }
-function copyEntry(sourceRoot, targetRoot, relativePath) {
+function copyEntry(sourceRoot, targetRoot, relativePath, trustedRoots = {}) {
   const sourcePath = path.resolve(sourceRoot, ...relativePath.split("/"));
   const targetPath = path.resolve(targetRoot, ...relativePath.split("/"));
   assertInside(sourceRoot, sourcePath, "Workspace source path");
   assertInside(targetRoot, targetPath, "Workspace target path");
+  if (!hasSafeDirectoryAncestors(sourceRoot, relativePath, trustedRoots.source ?? sourceRoot)) {
+    throw new Error(`Workspace source path has a symlink or non-directory ancestor: ${relativePath}`);
+  }
+  if (!hasSafeDirectoryAncestors(targetRoot, relativePath, trustedRoots.target ?? targetRoot)) {
+    throw new Error(`Workspace target path has a symlink or non-directory ancestor: ${relativePath}`);
+  }
   const stat = fs.lstatSync(sourcePath);
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
   fs.rmSync(targetPath, { recursive: true, force: true });
@@ -390,6 +519,22 @@ function copyEntry(sourceRoot, targetRoot, relativePath) {
     fs.chmodSync(targetPath, stat.mode);
   }
 }
+function hasSafeDirectoryAncestors(root, relativePath, trustedRoot = root) {
+  const resolvedTrustedRoot = path.resolve(trustedRoot);
+  const trustedRootStat = lstatOrNull(resolvedTrustedRoot);
+  if (trustedRootStat && (!trustedRootStat.isDirectory() || trustedRootStat.isSymbolicLink())) return false;
+  const resolvedRoot = path.resolve(root);
+  const targetParent = path.dirname(path.resolve(resolvedRoot, ...relativePath.split("/")));
+  const relativeParent = path.relative(resolvedTrustedRoot, targetParent);
+  if (relativeParent === ".." || relativeParent.startsWith(`..${path.sep}`) || path.isAbsolute(relativeParent)) return false;
+  let current = resolvedTrustedRoot;
+  for (const segment of relativeParent.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    const stat = lstatOrNull(current);
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) return false;
+  }
+  return true;
+}
 function entrySignature(stat) {
   return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
 }
@@ -441,7 +586,10 @@ function entriesEqual(sourcePath, targetPath) {
   }
   return equal;
 }
-function mirrorFileSet(sourceRoot, targetRoot, sourceFiles, targetFiles, opaqueTargetRoots = [], opaqueSourceRoots = []) {
+function mirrorFileSet(sourceRoot, targetRoot, sourceFiles, targetFiles, opaqueTargetRoots = [], opaqueSourceRoots = [], trustedRoots = {}) {
+  if (!hasSafeDirectoryAncestors(targetRoot, ".r5d-mirror-root", trustedRoots.target ?? targetRoot)) {
+    throw new Error(`Workspace target root has a symlink or non-directory ancestor: ${targetRoot}`);
+  }
   fs.mkdirSync(targetRoot, { recursive: true });
   const sourceSet = new Set(sourceFiles);
   for (const relativePath of targetFiles) {
@@ -449,18 +597,27 @@ function mirrorFileSet(sourceRoot, targetRoot, sourceFiles, targetFiles, opaqueT
     if (sourceSet.has(relativePath)) continue;
     const targetPath = path.resolve(targetRoot, ...relativePath.split("/"));
     assertInside(targetRoot, targetPath, "Workspace deletion path");
+    if (!hasSafeDirectoryAncestors(targetRoot, relativePath, trustedRoots.target ?? targetRoot)) {
+      throw new Error(`Workspace deletion path has a symlink or non-directory ancestor: ${relativePath}`);
+    }
     fs.rmSync(targetPath, { recursive: true, force: true });
   }
   for (const relativePath of sourceFiles) {
     if (pathIsWithinOpaqueRoot(relativePath, opaqueSourceRoots)) continue;
     if (pathIsWithinOpaqueRoot(relativePath, opaqueTargetRoots)) continue;
+    if (!hasSafeDirectoryAncestors(sourceRoot, relativePath, trustedRoots.source ?? sourceRoot)) {
+      throw new Error(`Workspace source path has a symlink or non-directory ancestor: ${relativePath}`);
+    }
+    if (!hasSafeDirectoryAncestors(targetRoot, relativePath, trustedRoots.target ?? targetRoot)) {
+      throw new Error(`Workspace target path has a symlink or non-directory ancestor: ${relativePath}`);
+    }
     const sourcePath = path.resolve(sourceRoot, ...relativePath.split("/"));
     const stat = lstatOrNull(sourcePath);
     if (!stat) continue;
     if (!stat.isFile() && !stat.isSymbolicLink()) continue;
     const targetPath = path.resolve(targetRoot, ...relativePath.split("/"));
     if (entriesEqual(sourcePath, targetPath)) continue;
-    copyEntry(sourceRoot, targetRoot, relativePath);
+    copyEntry(sourceRoot, targetRoot, relativePath, trustedRoots);
   }
   removeEmptyDirectories(targetRoot, opaqueTargetRoots);
 }
@@ -472,18 +629,37 @@ function indexPathsUnderCheckoutPath(checkoutPath, filePath) {
   ).split("\0").filter(Boolean);
 }
 function replaceCheckoutIndexPathWithGitlink(checkoutPath, gitlink) {
-  for (const indexPath of indexPathsUnderCheckoutPath(checkoutPath, gitlink.filePath)) {
-    runCheckoutGitRaw(
-      checkoutPath,
-      ["--literal-pathspecs", "update-index", "--force-remove", "--", indexPath],
-      `remove index entry beneath gitlink ${JSON.stringify(gitlink.filePath)}`
+  const zeroObjectId = "0".repeat(gitlink.objectId.length);
+  const records = [
+    ...indexPathsUnderCheckoutPath(checkoutPath, gitlink.filePath).map((indexPath) => `0 ${zeroObjectId}	${indexPath}`),
+    `160000 ${gitlink.objectId}	${gitlink.filePath}`
+  ];
+  const result = Bun.spawnSync(
+    [
+      "git",
+      "-c",
+      "submodule.recurse=false",
+      "-c",
+      "fetch.recurseSubmodules=false",
+      "-c",
+      "push.recurseSubmodules=false",
+      "update-index",
+      "-z",
+      "--index-info"
+    ],
+    {
+      cwd: checkoutPath,
+      stdin: Buffer.from(`${records.join("\0")}\0`),
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `record gitlink ${JSON.stringify(gitlink.filePath)}: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`
     );
   }
-  runCheckoutGitRaw(
-    checkoutPath,
-    ["--literal-pathspecs", "update-index", "--add", "--cacheinfo", "160000", gitlink.objectId, gitlink.filePath],
-    `record gitlink ${JSON.stringify(gitlink.filePath)}`
-  );
 }
 function removeCheckoutIndexPath(checkoutPath, filePath) {
   runCheckoutGitRaw(
@@ -544,12 +720,15 @@ function mirrorVisibleGitlinksToShadow(input, relativeRoot, visibleGitlinks) {
   }
   for (const gitlink of visibleGitlinks) replaceShadowIndexPathWithGitlink(input, relativeRoot, gitlink);
 }
-function mirrorShadowGitlinksToVisible(desired, visibleRoot) {
+function mirrorShadowGitlinksToVisible(desired, visibleRoot, trustedRoot) {
   const desiredByPath = new Map(desired.map((entry) => [entry.filePath, entry]));
   for (const current of checkoutGitlinks(visibleRoot)) {
     if (!desiredByPath.has(current.filePath)) removeCheckoutIndexPath(visibleRoot, current.filePath);
   }
   for (const gitlink of desired) {
+    if (!hasSafeDirectoryAncestors(visibleRoot, gitlink.filePath, trustedRoot)) {
+      throw new Error(`Visible gitlink path has a symlink or non-directory ancestor: ${gitlink.filePath}`);
+    }
     const visiblePath = path.join(visibleRoot, ...gitlink.filePath.split("/"));
     const existing = lstatOrNull(visiblePath);
     if (existing && !existing.isDirectory()) fs.rmSync(visiblePath, { recursive: true, force: true });
@@ -557,7 +736,7 @@ function mirrorShadowGitlinksToVisible(desired, visibleRoot) {
     replaceCheckoutIndexPathWithGitlink(visibleRoot, gitlink);
   }
 }
-function assertSafeVisibleGitlinkTransitions(visibleRoot, currentGitlinks, desiredGitlinks, shadowFiles) {
+function assertSafeVisibleGitlinkTransitions(visibleRoot, trustedRoot, currentGitlinks, desiredGitlinks, shadowFiles) {
   const desiredGitlinkPaths = new Set(desiredGitlinks.map((entry) => entry.filePath));
   for (const current of currentGitlinks) {
     if (desiredGitlinkPaths.has(current.filePath)) continue;
@@ -565,6 +744,9 @@ function assertSafeVisibleGitlinkTransitions(visibleRoot, currentGitlinks, desir
       (filePath) => filePath === current.filePath || filePath.startsWith(`${current.filePath}/`)
     );
     if (!becomesOrdinaryPath) continue;
+    if (!hasSafeDirectoryAncestors(visibleRoot, current.filePath, trustedRoot)) {
+      throw new Error(`Visible gitlink path has a symlink or non-directory ancestor: ${current.filePath}`);
+    }
     const existing = lstatOrNull(path.join(visibleRoot, ...current.filePath.split("/")));
     if (!existing) continue;
     if (existing.isDirectory() && fs.readdirSync(path.join(visibleRoot, ...current.filePath.split("/"))).length === 0) {
@@ -593,15 +775,46 @@ function restoreShadowProjectSnapshot(input, relativeRoot) {
   runGitResult(input, input.shadowRoot, ["--literal-pathspecs", "rm", "-r", "-f", "--cached", "--ignore-unmatch", "--", relativeRoot]);
   fs.rmSync(shadowRoot, { recursive: true, force: true });
 }
+function copiedHydrationPreimage(input, shadowRoot, ordinaryFiles, gitlinks = []) {
+  const preimage = new Map(
+    gitlinks.map((entry) => [entry.filePath, { kind: "gitlink", objectId: entry.objectId }])
+  );
+  for (const filePath of ordinaryFiles) {
+    const entry = filesystemHydrationEntry(input, path.join(shadowRoot, ...filePath.split("/")));
+    if (!entry || entry === UNSTABLE_VISIBLE_ENTRY) return null;
+    preimage.set(filePath, entry);
+  }
+  return preimage;
+}
+function visibleProjectMatchesCopiedPreimage(input, visibleRoot, ordinaryFiles, gitlinks, preimage, opaqueRoots) {
+  const currentFiles = listGitEligibleFiles(visibleRoot).filter((filePath) => !pathIsWithinOpaqueRoot(filePath, opaqueRoots));
+  if (currentFiles.length !== ordinaryFiles.length || currentFiles.some((filePath, index) => filePath !== ordinaryFiles[index]))
+    return false;
+  const currentGitlinks = checkoutGitlinks(visibleRoot);
+  if (currentGitlinks.length !== gitlinks.length || currentGitlinks.some((entry, index) => entry.filePath !== gitlinks[index]?.filePath || entry.objectId !== gitlinks[index]?.objectId)) {
+    return false;
+  }
+  const currentGitlinksByPath = new Map(currentGitlinks.map((entry) => [entry.filePath, entry]));
+  return ordinaryFiles.every((filePath) => {
+    const current = projectVisibleHydrationEntry(input, visibleRoot, filePath, currentGitlinksByPath);
+    return current !== UNSTABLE_VISIBLE_ENTRY && hydrationEntriesEqual(current, preimage.get(filePath));
+  });
+}
 function mirrorVisibleProjectToShadow(input, manifest, branchName) {
   const visibleRoot = visibleProjectBranchPath(input.projectsRoot, manifest, branchName);
-  if (!fs.existsSync(path.join(visibleRoot, ".git"))) return { entries: [], opaqueRoots: [] };
+  const unavailableProjection = () => ({
+    entries: [],
+    opaqueRoots: [],
+    visiblePreimages: /* @__PURE__ */ new Map([[visibleRoot, null]])
+  });
+  if (!hasSafeDirectoryAncestors(visibleRoot, ".r5d-project-scan", input.projectsRoot)) return unavailableProjection();
+  if (!fs.existsSync(path.join(visibleRoot, ".git"))) return unavailableProjection();
   const isCanonicalCheckout = manifest.canonicalCheckouts?.some((checkout) => checkout.branchName === branchName);
   if (isCanonicalCheckout) {
     assertCanonicalCheckoutIndexMatchesWorktree(visibleRoot);
   }
   const beforeSnapshot = checkoutGitSnapshot(visibleRoot);
-  if (!beforeSnapshot) return { entries: [], opaqueRoots: [] };
+  if (!beforeSnapshot) return unavailableProjection();
   const visibleGitlinks = checkoutGitlinks(visibleRoot);
   const visibleIndexEntries = checkoutIndexEntries(visibleRoot).filter((entry) => entry.stage === "0");
   const indexedGitlinkPaths = new Set(visibleGitlinks.map((entry) => entry.filePath));
@@ -616,21 +829,142 @@ function mirrorVisibleProjectToShadow(input, manifest, branchName) {
   const visibleFiles = listGitEligibleFiles(visibleRoot).filter((filePath) => !pathIsWithinOpaqueRoot(filePath, visibleGitlinkRoots));
   const shadowRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
   mirrorVisibleGitlinksToShadow(input, relativeRoot, visibleGitlinks);
-  mirrorFileSet(visibleRoot, shadowRoot, visibleFiles, listFilesRecursively(shadowRoot), visibleGitlinkRoots, visibleGitlinkRoots);
-  if (checkoutGitSnapshot(visibleRoot) !== beforeSnapshot) {
+  mirrorFileSet(visibleRoot, shadowRoot, visibleFiles, listFilesRecursively(shadowRoot), visibleGitlinkRoots, visibleGitlinkRoots, {
+    source: input.projectsRoot,
+    target: input.shadowRoot
+  });
+  const hydrationPreimage = copiedHydrationPreimage(input, shadowRoot, visibleFiles, visibleGitlinks);
+  if (!hydrationPreimage || checkoutGitSnapshot(visibleRoot) !== beforeSnapshot || !visibleProjectMatchesCopiedPreimage(input, visibleRoot, visibleFiles, visibleGitlinks, hydrationPreimage, visibleGitlinkRoots)) {
     restoreShadowProjectSnapshot(input, relativeRoot);
-    return { entries: [], opaqueRoots: [] };
+    return { entries: [], opaqueRoots: [], visiblePreimages: /* @__PURE__ */ new Map([[visibleRoot, null]]) };
   }
   return {
     entries: visibleGitlinks.map((entry) => ({
       filePath: path.posix.join(relativeRoot, entry.filePath),
       objectId: entry.objectId
     })),
-    opaqueRoots: visibleGitlinkRoots.map((filePath) => path.posix.join(relativeRoot, filePath))
+    opaqueRoots: visibleGitlinkRoots.map((filePath) => path.posix.join(relativeRoot, filePath)),
+    visiblePreimages: /* @__PURE__ */ new Map([[visibleRoot, hydrationPreimage]])
   };
 }
-function mirrorShadowProjectToVisible(input, manifest, branchName, additionalOpaqueRoots = []) {
+function pathDepth(filePath) {
+  return filePath.split("/").length;
+}
+function pathsOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+function removeVisibleBlob(visibleRoot, filePath, trustedRoot) {
+  if (!hasSafeDirectoryAncestors(visibleRoot, filePath, trustedRoot)) return false;
+  const absolutePath = path.join(visibleRoot, ...filePath.split("/"));
+  const stat = lstatOrNull(absolutePath);
+  if (!stat || !stat.isFile() && !stat.isSymbolicLink()) return false;
+  fs.rmSync(absolutePath, { force: true });
+  return true;
+}
+function removeEmptyVisibleAncestors(visibleRoot, filePath, trustedRoot, opaqueRoots = []) {
+  if (!hasSafeDirectoryAncestors(visibleRoot, filePath, trustedRoot)) return;
+  const resolvedRoot = path.resolve(visibleRoot);
+  let current = path.dirname(path.join(resolvedRoot, ...filePath.split("/")));
+  while (current !== resolvedRoot) {
+    const relative = path.relative(resolvedRoot, current).split(path.sep).join("/");
+    if (!relative || pathIsWithinOpaqueRoot(relative, opaqueRoots)) return;
+    const stat = lstatOrNull(current);
+    if (!stat) {
+      current = path.dirname(current);
+      continue;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink() || fs.readdirSync(current).length > 0) return;
+    try {
+      fs.rmdirSync(current);
+    } catch (error) {
+      if (error.code === "ENOTEMPTY" || error.code === "ENOENT") return;
+      throw error;
+    }
+    current = path.dirname(current);
+  }
+}
+function copyShadowBlobToVisible(shadowRoot, visibleRoot, filePath, trustedRoot) {
+  if (!hasSafeDirectoryAncestors(visibleRoot, filePath, trustedRoot)) return false;
+  const targetPath = path.join(visibleRoot, ...filePath.split("/"));
+  const existing = lstatOrNull(targetPath);
+  if (existing?.isDirectory()) {
+    if (fs.readdirSync(targetPath).length > 0) return false;
+    fs.rmdirSync(targetPath);
+  } else if (existing) {
+    fs.rmSync(targetPath, { force: true });
+  }
+  try {
+    copyEntry(shadowRoot, visibleRoot, filePath, { target: trustedRoot });
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST" || error.code === "ENOTDIR") return false;
+    throw error;
+  }
+}
+function hydrateProjectFromShadowOptimistically(input, relativeRoot, visibleRoot, preimage, opaqueVisibleGitlinks) {
+  const shadowRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
+  const desired = indexHydrationPreimage(input, relativeRoot);
+  let expectedCheckoutSnapshot = checkoutGitSnapshot(visibleRoot);
+  if (!expectedCheckoutSnapshot) return;
+  const checkoutIndexIsStable = () => checkoutGitSnapshot(visibleRoot) === expectedCheckoutSnapshot;
+  const refreshCheckoutSnapshot = () => {
+    expectedCheckoutSnapshot = checkoutGitSnapshot(visibleRoot);
+    return expectedCheckoutSnapshot !== null;
+  };
+  let currentGitlinks = new Map(checkoutGitlinks(visibleRoot).map((entry) => [entry.filePath, entry]));
+  const changedPaths = [.../* @__PURE__ */ new Set([...preimage.keys(), ...desired.keys()])].filter(
+    (filePath) => !hydrationEntriesEqual(preimage.get(filePath), desired.get(filePath))
+  );
+  for (const filePath of changedPaths.filter((candidate) => !desired.has(candidate)).sort((left, right) => pathDepth(right) - pathDepth(left) || left.localeCompare(right))) {
+    const current = projectVisibleHydrationEntry(input, visibleRoot, filePath, currentGitlinks);
+    if (current === UNSTABLE_VISIBLE_ENTRY || !hydrationEntriesEqual(current, preimage.get(filePath))) continue;
+    const expected = preimage.get(filePath);
+    if (expected?.kind === "gitlink") {
+      if (!checkoutIndexIsStable()) return;
+      removeCheckoutIndexPath(visibleRoot, filePath);
+      if (!refreshCheckoutSnapshot()) return;
+      currentGitlinks.delete(filePath);
+    } else if (removeVisibleBlob(visibleRoot, filePath, input.projectsRoot)) {
+      removeEmptyVisibleAncestors(visibleRoot, filePath, input.projectsRoot, opaqueVisibleGitlinks);
+    }
+  }
+  for (const filePath of changedPaths.filter((candidate) => desired.has(candidate)).sort((left, right) => pathDepth(left) - pathDepth(right) || left.localeCompare(right))) {
+    const wanted = desired.get(filePath);
+    if (!wanted) continue;
+    const current = projectVisibleHydrationEntry(input, visibleRoot, filePath, currentGitlinks);
+    if (current === UNSTABLE_VISIBLE_ENTRY || hydrationEntriesEqual(current, wanted)) continue;
+    if (!hydrationEntriesEqual(current, preimage.get(filePath))) continue;
+    if (wanted.kind === "gitlink") {
+      if (!hasSafeDirectoryAncestors(visibleRoot, filePath, input.projectsRoot) || !checkoutIndexIsStable()) return;
+      const targetPath = path.join(visibleRoot, ...filePath.split("/"));
+      const existing = lstatOrNull(targetPath);
+      if (existing && !existing.isDirectory()) fs.rmSync(targetPath, { force: true });
+      fs.mkdirSync(targetPath, { recursive: true });
+      replaceCheckoutIndexPathWithGitlink(visibleRoot, { filePath, objectId: wanted.objectId });
+      if (!refreshCheckoutSnapshot()) return;
+      currentGitlinks.set(filePath, { filePath, objectId: wanted.objectId });
+      continue;
+    }
+    const expected = preimage.get(filePath);
+    if (expected?.kind === "gitlink") {
+      if (!hasSafeDirectoryAncestors(visibleRoot, filePath, input.projectsRoot) || !checkoutIndexIsStable()) return;
+      const targetPath = path.join(visibleRoot, ...filePath.split("/"));
+      const existing = lstatOrNull(targetPath);
+      if (existing?.isDirectory() && fs.readdirSync(targetPath).length > 0) continue;
+      removeCheckoutIndexPath(visibleRoot, filePath);
+      if (!refreshCheckoutSnapshot()) return;
+      currentGitlinks.delete(filePath);
+    }
+    copyShadowBlobToVisible(shadowRoot, visibleRoot, filePath, input.projectsRoot);
+  }
+}
+function mirrorShadowProjectToVisible(input, manifest, branchName, additionalOpaqueRoots = [], hydrationPreimage) {
   const visibleRoot = visibleProjectBranchPath(input.projectsRoot, manifest, branchName);
+  if (hydrationPreimage === null) return;
+  if (!hasSafeDirectoryAncestors(visibleRoot, ".r5d-project-hydration", input.projectsRoot)) {
+    if (hydrationPreimage) return;
+    throw new Error(`Visible project root has a symlink or non-directory ancestor: ${visibleRoot}`);
+  }
   if (!fs.existsSync(path.join(visibleRoot, ".git"))) return;
   checkoutGitlinks(visibleRoot);
   const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, branchName);
@@ -644,6 +978,7 @@ function mirrorShadowProjectToVisible(input, manifest, branchName, additionalOpa
   ].sort();
   assertSafeVisibleGitlinkTransitions(
     visibleRoot,
+    input.projectsRoot,
     protectedGitlinkRoots.map((filePath) => ({ filePath, objectId: "" })),
     desiredGitlinks,
     shadowFiles
@@ -651,77 +986,166 @@ function mirrorShadowProjectToVisible(input, manifest, branchName, additionalOpa
   const opaqueVisibleGitlinks = protectedGitlinkRoots.filter(
     (filePath) => desiredGitlinkPaths.has(filePath) || !shadowFiles.some((shadowFile) => shadowFile === filePath || shadowFile.startsWith(`${filePath}/`))
   );
-  mirrorFileSet(shadowRoot, visibleRoot, shadowFiles, listGitEligibleFiles(visibleRoot), opaqueVisibleGitlinks);
-  mirrorShadowGitlinksToVisible(desiredGitlinks, visibleRoot);
+  if (hydrationPreimage) {
+    hydrateProjectFromShadowOptimistically(input, relativeRoot, visibleRoot, hydrationPreimage, opaqueVisibleGitlinks);
+    return;
+  }
+  mirrorFileSet(shadowRoot, visibleRoot, shadowFiles, listGitEligibleFiles(visibleRoot), opaqueVisibleGitlinks, [], {
+    source: input.shadowRoot,
+    target: input.projectsRoot
+  });
+  mirrorShadowGitlinksToVisible(desiredGitlinks, visibleRoot, input.projectsRoot);
+}
+function visibleRegularRootMatchesCopiedPreimage(input, visibleRoot, files, preimage, filter) {
+  const currentFiles = listFilesRecursively(visibleRoot, filter);
+  if (currentFiles.length !== files.length || currentFiles.some((filePath, index) => filePath !== files[index])) return false;
+  return files.every((filePath) => {
+    const current = hasSafeDirectoryAncestors(visibleRoot, filePath, input.plansRoot) ? filesystemHydrationEntry(input, path.join(visibleRoot, ...filePath.split("/"))) : UNSTABLE_VISIBLE_ENTRY;
+    return current !== UNSTABLE_VISIBLE_ENTRY && hydrationEntriesEqual(current, preimage.get(filePath));
+  });
+}
+function mirrorRegularRootToShadowWithPreimage(input, sourceRoot, targetRoot, relativeRoot, filter) {
+  if (!hasSafeDirectoryAncestors(sourceRoot, ".r5d-plan-scan", input.plansRoot)) return null;
+  if (!fs.existsSync(sourceRoot)) return /* @__PURE__ */ new Map();
+  const sourceFiles = listFilesRecursively(sourceRoot, filter);
+  mirrorFileSet(sourceRoot, targetRoot, sourceFiles, listFilesRecursively(targetRoot, filter), [], [], {
+    source: input.plansRoot,
+    target: input.shadowRoot
+  });
+  const preimage = copiedHydrationPreimage(input, targetRoot, sourceFiles);
+  if (!preimage || !visibleRegularRootMatchesCopiedPreimage(input, sourceRoot, sourceFiles, preimage, filter)) {
+    restoreShadowProjectSnapshot(input, relativeRoot);
+    return null;
+  }
+  return preimage;
+}
+function hydrateRegularRootOptimistically(input, relativeRoot, targetRoot, preimage, filter) {
+  const sourceRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
+  if (!hasSafeDirectoryAncestors(targetRoot, ".r5d-plan-hydration", input.plansRoot)) return;
+  const desired = indexHydrationPreimage(input, relativeRoot);
+  for (const [filePath, entry] of desired) {
+    if (entry.kind === "gitlink" || filter && !filter(filePath)) desired.delete(filePath);
+  }
+  const changedPaths = [.../* @__PURE__ */ new Set([...preimage.keys(), ...desired.keys()])].filter(
+    (filePath) => !hydrationEntriesEqual(preimage.get(filePath), desired.get(filePath))
+  );
+  for (const filePath of changedPaths.filter((candidate) => !desired.has(candidate)).sort((left, right) => pathDepth(right) - pathDepth(left) || left.localeCompare(right))) {
+    const current = hasSafeDirectoryAncestors(targetRoot, filePath, input.plansRoot) ? filesystemHydrationEntry(input, path.join(targetRoot, ...filePath.split("/"))) : UNSTABLE_VISIBLE_ENTRY;
+    if (current !== UNSTABLE_VISIBLE_ENTRY && hydrationEntriesEqual(current, preimage.get(filePath))) {
+      if (removeVisibleBlob(targetRoot, filePath, input.plansRoot)) {
+        removeEmptyVisibleAncestors(targetRoot, filePath, input.plansRoot);
+      }
+    }
+  }
+  for (const filePath of changedPaths.filter((candidate) => desired.has(candidate)).sort((left, right) => pathDepth(left) - pathDepth(right) || left.localeCompare(right))) {
+    const current = hasSafeDirectoryAncestors(targetRoot, filePath, input.plansRoot) ? filesystemHydrationEntry(input, path.join(targetRoot, ...filePath.split("/"))) : UNSTABLE_VISIBLE_ENTRY;
+    const wanted = desired.get(filePath);
+    if (!wanted || current === UNSTABLE_VISIBLE_ENTRY || hydrationEntriesEqual(current, wanted)) continue;
+    if (!hydrationEntriesEqual(current, preimage.get(filePath))) continue;
+    copyShadowBlobToVisible(sourceRoot, targetRoot, filePath, input.plansRoot);
+  }
 }
 function mirrorLocalPlansToShadow(input, manifest, branchName) {
   const sourceRoot = localPlansBranchPath(input.plansRoot, manifest.projectId, branchName);
-  if (!fs.existsSync(sourceRoot)) return;
-  const targetRoot = path.join(input.shadowRoot, ...workspacePlansRelativePath(manifest.projectId, branchName).split("/"));
+  const relativeRoot = workspacePlansRelativePath(manifest.projectId, branchName);
+  const targetRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
   const planFilter = (relativePath) => relativePath.endsWith(".plan.md");
-  mirrorFileSet(sourceRoot, targetRoot, listFilesRecursively(sourceRoot, planFilter), listFilesRecursively(targetRoot));
+  return mirrorRegularRootToShadowWithPreimage(input, sourceRoot, targetRoot, relativeRoot, planFilter);
 }
-function mirrorShadowPlansToLocal(input, manifest, branchName) {
+function mirrorShadowPlansToLocal(input, manifest, branchName, hydrationPreimage) {
+  if (hydrationPreimage === null) return;
   const relativeRoot = workspacePlansRelativePath(manifest.projectId, branchName);
   const sourceRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
   const targetRoot = localPlansBranchPath(input.plansRoot, manifest.projectId, branchName);
   const planFilter = (relativePath) => relativePath.endsWith(".plan.md");
+  if (hydrationPreimage) {
+    hydrateRegularRootOptimistically(input, relativeRoot, targetRoot, hydrationPreimage, planFilter);
+    return;
+  }
+  if (!hasSafeDirectoryAncestors(targetRoot, ".r5d-plan-hydration", input.plansRoot)) {
+    throw new Error(`Visible plan root has a symlink or non-directory ancestor: ${targetRoot}`);
+  }
   mirrorFileSet(
     sourceRoot,
     targetRoot,
     listShadowTrackedFiles(input, relativeRoot).filter(planFilter),
-    listFilesRecursively(targetRoot, planFilter)
+    listFilesRecursively(targetRoot, planFilter),
+    [],
+    [],
+    { source: input.shadowRoot, target: input.plansRoot }
   );
 }
 function mirrorLocalWorkspacePlansToShadow(input) {
-  if (input.trigger.canonicalCheckoutOnly) return;
+  if (input.trigger.canonicalCheckoutOnly) return /* @__PURE__ */ new Map();
   const sourceRoot = localWorkspacePlansPath(input.plansRoot);
-  if (!fs.existsSync(sourceRoot)) return;
-  const targetRoot = path.join(input.shadowRoot, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH);
+  const relativeRoot = WORKSPACE_NATIVE_PLANS_RELATIVE_PATH;
+  const targetRoot = path.join(input.shadowRoot, relativeRoot);
   const planFilter = (relativePath) => relativePath.endsWith(".plan.md");
-  mirrorFileSet(sourceRoot, targetRoot, listFilesRecursively(sourceRoot, planFilter), listFilesRecursively(targetRoot, planFilter));
+  return mirrorRegularRootToShadowWithPreimage(input, sourceRoot, targetRoot, relativeRoot, planFilter);
 }
-function mirrorShadowWorkspacePlansToLocal(input) {
+function mirrorShadowWorkspacePlansToLocal(input, hydrationPreimage) {
   if (input.trigger.canonicalCheckoutOnly) return;
+  if (hydrationPreimage === null) return;
   const sourceRoot = path.join(input.shadowRoot, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH);
   const targetRoot = localWorkspacePlansPath(input.plansRoot);
   const planFilter = (relativePath) => relativePath.endsWith(".plan.md");
+  if (hydrationPreimage) {
+    hydrateRegularRootOptimistically(input, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH, targetRoot, hydrationPreimage, planFilter);
+    return;
+  }
+  if (!hasSafeDirectoryAncestors(targetRoot, ".r5d-plan-hydration", input.plansRoot)) {
+    throw new Error(`Visible workspace-plan root has a symlink or non-directory ancestor: ${targetRoot}`);
+  }
   mirrorFileSet(
     sourceRoot,
     targetRoot,
     listShadowTrackedFiles(input, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH).filter(planFilter),
-    listFilesRecursively(targetRoot, planFilter)
+    listFilesRecursively(targetRoot, planFilter),
+    [],
+    [],
+    { source: input.shadowRoot, target: input.plansRoot }
   );
 }
-function reconcileWorkspaceNativePlans(input) {
+function reconcileWorkspaceNativePlans(input, projection) {
   if (input.trigger.canonicalCheckoutOnly) return;
+  const localRoot = localWorkspacePlansPath(input.plansRoot);
+  projection.visiblePreimages ??= /* @__PURE__ */ new Map();
+  projection.visiblePreimages.set(localRoot, /* @__PURE__ */ new Map());
   if (fs.existsSync(localWorkspacePlansPath(input.plansRoot))) {
-    mirrorLocalWorkspacePlansToShadow(input);
+    projection.visiblePreimages.set(localRoot, mirrorLocalWorkspacePlansToShadow(input));
     return;
   }
   if (listShadowTrackedFiles(input, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH).length > 0 || restoreShadowRootFromRemote(input, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH)) {
-    mirrorShadowWorkspacePlansToLocal(input);
+    mirrorShadowWorkspacePlansToLocal(input, /* @__PURE__ */ new Map());
+    projection.visiblePreimages.set(localRoot, indexHydrationPreimage(input, WORKSPACE_NATIVE_PLANS_RELATIVE_PATH));
   }
 }
 function mergeGitlinkProjection(target, source) {
   target.entries.push(...source.entries);
   target.opaqueRoots.push(...source.opaqueRoots);
+  if (source.visiblePreimages) {
+    target.visiblePreimages ??= /* @__PURE__ */ new Map();
+    for (const [visibleRoot, preimage] of source.visiblePreimages) target.visiblePreimages.set(visibleRoot, preimage);
+  }
 }
 function mirrorVisibleWorkspaceToShadow(input, excludedCheckouts = /* @__PURE__ */ new Set()) {
-  const projection = { entries: [], opaqueRoots: [] };
-  reconcileWorkspaceNativePlans(input);
+  const projection = { entries: [], opaqueRoots: [], visiblePreimages: /* @__PURE__ */ new Map() };
+  reconcileWorkspaceNativePlans(input, projection);
   for (const manifest of [...input.projects].sort((left, right) => left.projectId.localeCompare(right.projectId))) {
     for (const branchName of [...new Set(manifest.branches)].sort()) {
       if (excludedCheckouts.has(`${manifest.projectId}\0${branchName}`)) continue;
       mergeGitlinkProjection(projection, mirrorVisibleProjectToShadow(input, manifest, branchName));
-      if (!input.trigger.canonicalCheckoutOnly) mirrorLocalPlansToShadow(input, manifest, branchName);
+      if (!input.trigger.canonicalCheckoutOnly) {
+        const localPlansRoot = localPlansBranchPath(input.plansRoot, manifest.projectId, branchName);
+        projection.visiblePreimages?.set(localPlansRoot, mirrorLocalPlansToShadow(input, manifest, branchName));
+      }
     }
   }
   projection.opaqueRoots = [...new Set(projection.opaqueRoots)].sort();
   return projection;
 }
 function reconcileNewVisibleCheckouts(input) {
-  const projection = { entries: [], opaqueRoots: [] };
+  const projection = { entries: [], opaqueRoots: [], visiblePreimages: /* @__PURE__ */ new Map() };
   for (const target of input.newVisibleCheckouts ?? []) {
     const manifest = input.projects.find((project) => project.projectId === target.projectId);
     if (!manifest || !manifest.branches.includes(target.branchName)) continue;
@@ -730,6 +1154,10 @@ function reconcileNewVisibleCheckouts(input) {
       mergeGitlinkProjection(projection, mirrorVisibleProjectToShadow(input, manifest, target.branchName));
     } else if (listShadowTrackedFiles(input, projectRoot).length > 0 || restoreShadowRootFromRemote(input, projectRoot)) {
       mirrorShadowProjectToVisible(input, manifest, target.branchName);
+      projection.visiblePreimages?.set(
+        visibleProjectBranchPath(input.projectsRoot, manifest, target.branchName),
+        indexHydrationPreimage(input, projectRoot)
+      );
     } else {
       mergeGitlinkProjection(projection, mirrorVisibleProjectToShadow(input, manifest, target.branchName));
     }
@@ -737,23 +1165,194 @@ function reconcileNewVisibleCheckouts(input) {
     const plansRoot = workspacePlansRelativePath(target.projectId, target.branchName);
     if (listShadowTrackedFiles(input, plansRoot).length > 0 || restoreShadowRootFromRemote(input, plansRoot)) {
       mirrorShadowPlansToLocal(input, manifest, target.branchName);
+      projection.visiblePreimages?.set(
+        localPlansBranchPath(input.plansRoot, manifest.projectId, target.branchName),
+        indexHydrationPreimage(input, plansRoot)
+      );
     } else {
-      mirrorLocalPlansToShadow(input, manifest, target.branchName);
+      projection.visiblePreimages?.set(
+        localPlansBranchPath(input.plansRoot, manifest.projectId, target.branchName),
+        mirrorLocalPlansToShadow(input, manifest, target.branchName)
+      );
     }
   }
   projection.opaqueRoots = [...new Set(projection.opaqueRoots)].sort();
   return projection;
 }
-function mirrorShadowWorkspaceToVisible(input, opaqueWorkspaceRoots = []) {
-  mirrorShadowWorkspacePlansToLocal(input);
+function mirrorShadowWorkspaceToVisible(input, opaqueWorkspaceRoots = [], hydrationPreimages) {
+  mirrorShadowWorkspacePlansToLocal(input, hydrationPreimages?.get(localWorkspacePlansPath(input.plansRoot)));
   for (const manifest of [...input.projects].sort((left, right) => left.projectId.localeCompare(right.projectId))) {
     for (const branchName of [...new Set(manifest.branches)].sort()) {
       const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, branchName);
+      const visibleRoot = visibleProjectBranchPath(input.projectsRoot, manifest, branchName);
       const opaqueProjectRoots = opaqueWorkspaceRoots.filter((root) => root.startsWith(`${relativeRoot}/`)).map((root) => root.slice(relativeRoot.length + 1));
-      mirrorShadowProjectToVisible(input, manifest, branchName, opaqueProjectRoots);
-      if (!input.trigger.canonicalCheckoutOnly) mirrorShadowPlansToLocal(input, manifest, branchName);
+      mirrorShadowProjectToVisible(input, manifest, branchName, opaqueProjectRoots, hydrationPreimages?.get(visibleRoot));
+      if (!input.trigger.canonicalCheckoutOnly) {
+        const localPlansRoot = localPlansBranchPath(input.plansRoot, manifest.projectId, branchName);
+        mirrorShadowPlansToLocal(input, manifest, branchName, hydrationPreimages?.get(localPlansRoot));
+      }
+    }
+  }
+}
+function hydrationPreimagesFromShadowRevision(input, revision) {
+  const preimages = /* @__PURE__ */ new Map();
+  const fromRevision = (relativeRoot) => revision ? revisionHydrationPreimage(input, revision, relativeRoot) : /* @__PURE__ */ new Map();
+  if (!input.trigger.canonicalCheckoutOnly) {
+    preimages.set(localWorkspacePlansPath(input.plansRoot), fromRevision(WORKSPACE_NATIVE_PLANS_RELATIVE_PATH));
+  }
+  for (const manifest of input.projects) {
+    for (const branchName of manifest.branches) {
+      preimages.set(
+        visibleProjectBranchPath(input.projectsRoot, manifest, branchName),
+        fromRevision(workspaceProjectBranchRelativePath(manifest.projectId, branchName))
+      );
+      if (!input.trigger.canonicalCheckoutOnly) {
+        preimages.set(
+          localPlansBranchPath(input.plansRoot, manifest.projectId, branchName),
+          fromRevision(workspacePlansRelativePath(manifest.projectId, branchName))
+        );
+      }
+    }
+  }
+  return preimages;
+}
+function visibleHydrationConflictPaths(input, preimages, desiredRevision) {
+  const conflicts = [];
+  const inspectRegularRoot = (visibleRoot, relativeRoot, filter) => {
+    const preimage = preimages.get(visibleRoot);
+    if (!preimage) return;
+    const desired = revisionHydrationPreimage(input, desiredRevision, relativeRoot);
+    for (const [filePath, entry] of desired) {
+      if (entry.kind === "gitlink" || filter && !filter(filePath)) desired.delete(filePath);
+    }
+    const changedPaths = [.../* @__PURE__ */ new Set([...preimage.keys(), ...desired.keys()])].filter(
+      (filePath) => !hydrationEntriesEqual(preimage.get(filePath), desired.get(filePath))
+    );
+    if (changedPaths.length === 0) return;
+    if (!hasSafeDirectoryAncestors(visibleRoot, ".r5d-hydration-scan", input.plansRoot)) {
+      conflicts.push(...changedPaths.map((filePath) => path.posix.join(relativeRoot, filePath)));
+      return;
+    }
+    const affectsChangedTree = (filePath) => changedPaths.some((changedPath) => pathsOverlap(filePath, changedPath));
+    const currentEntries = /* @__PURE__ */ new Map();
+    const unstablePaths = /* @__PURE__ */ new Set();
+    for (const filePath of listFilesRecursively(visibleRoot).filter(affectsChangedTree)) {
+      const current = hasSafeDirectoryAncestors(visibleRoot, filePath, input.plansRoot) ? filesystemHydrationEntry(input, path.join(visibleRoot, ...filePath.split("/"))) : UNSTABLE_VISIBLE_ENTRY;
+      if (current === UNSTABLE_VISIBLE_ENTRY || !current) unstablePaths.add(filePath);
+      else currentEntries.set(filePath, current);
     }
+    for (const filePath of /* @__PURE__ */ new Set([...changedPaths, ...currentEntries.keys(), ...unstablePaths])) {
+      if (!affectsChangedTree(filePath)) continue;
+      const current = unstablePaths.has(filePath) ? UNSTABLE_VISIBLE_ENTRY : currentEntries.get(filePath);
+      if (current === UNSTABLE_VISIBLE_ENTRY || !hydrationEntriesEqual(current, preimage.get(filePath)) && !hydrationEntriesEqual(current, desired.get(filePath))) {
+        conflicts.push(path.posix.join(relativeRoot, filePath));
+      }
+    }
+  };
+  if (!input.trigger.canonicalCheckoutOnly) {
+    inspectRegularRoot(
+      localWorkspacePlansPath(input.plansRoot),
+      WORKSPACE_NATIVE_PLANS_RELATIVE_PATH,
+      (filePath) => filePath.endsWith(".plan.md")
+    );
   }
+  for (const manifest of input.projects) {
+    for (const branchName of manifest.branches) {
+      const visibleRoot = visibleProjectBranchPath(input.projectsRoot, manifest, branchName);
+      const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, branchName);
+      const preimage = preimages.get(visibleRoot);
+      if (preimage && fs.existsSync(path.join(visibleRoot, ".git"))) {
+        const desired = revisionHydrationPreimage(input, desiredRevision, relativeRoot);
+        const changedPaths = [.../* @__PURE__ */ new Set([...preimage.keys(), ...desired.keys()])].filter(
+          (filePath) => !hydrationEntriesEqual(preimage.get(filePath), desired.get(filePath))
+        );
+        if (!hasSafeDirectoryAncestors(visibleRoot, ".r5d-hydration-scan", input.projectsRoot)) {
+          conflicts.push(...changedPaths.map((filePath) => path.posix.join(relativeRoot, filePath)));
+          continue;
+        }
+        const affectsChangedTree = (filePath) => changedPaths.some((changedPath) => pathsOverlap(filePath, changedPath));
+        const currentGitlinks = new Map(checkoutGitlinks(visibleRoot).map((entry) => [entry.filePath, entry]));
+        const residualOpaqueGitlinks = [...preimage].filter(
+          ([filePath, entry]) => entry.kind === "gitlink" && !desired.has(filePath) && ![...desired.keys()].some((desiredPath) => desiredPath.startsWith(`${filePath}/`))
+        ).map(([filePath]) => filePath);
+        const opaqueRoots = [.../* @__PURE__ */ new Set([...currentGitlinks.keys(), ...residualOpaqueGitlinks])];
+        const currentEntries = /* @__PURE__ */ new Map();
+        const unstablePaths = /* @__PURE__ */ new Set();
+        for (const filePath of [...currentGitlinks.keys()].filter(affectsChangedTree)) {
+          const current = projectVisibleHydrationEntry(input, visibleRoot, filePath, currentGitlinks);
+          if (current === UNSTABLE_VISIBLE_ENTRY || !current) unstablePaths.add(filePath);
+          else currentEntries.set(filePath, current);
+        }
+        for (const filePath of listGitEligibleFiles(visibleRoot).filter(
+          (candidate) => affectsChangedTree(candidate) && !pathIsWithinOpaqueRoot(candidate, opaqueRoots)
+        )) {
+          const current = projectVisibleHydrationEntry(input, visibleRoot, filePath, currentGitlinks);
+          if (current === UNSTABLE_VISIBLE_ENTRY || !current) unstablePaths.add(filePath);
+          else currentEntries.set(filePath, current);
+        }
+        for (const filePath of /* @__PURE__ */ new Set([...changedPaths, ...currentEntries.keys(), ...unstablePaths])) {
+          if (!affectsChangedTree(filePath)) continue;
+          const current = unstablePaths.has(filePath) ? UNSTABLE_VISIBLE_ENTRY : currentEntries.get(filePath);
+          if (current === UNSTABLE_VISIBLE_ENTRY || !hydrationEntriesEqual(current, preimage.get(filePath)) && !hydrationEntriesEqual(current, desired.get(filePath))) {
+            conflicts.push(path.posix.join(relativeRoot, filePath));
+          }
+        }
+      }
+      if (!input.trigger.canonicalCheckoutOnly) {
+        inspectRegularRoot(
+          localPlansBranchPath(input.plansRoot, manifest.projectId, branchName),
+          workspacePlansRelativePath(manifest.projectId, branchName),
+          (filePath) => filePath.endsWith(".plan.md")
+        );
+      }
+    }
+  }
+  return [...new Set(conflicts)].sort();
+}
+function unavailableHydrationConflictPaths(input, preimages, baselineRevision, desiredRevision) {
+  const conflicts = [];
+  const inspectRoot = (visibleRoot, relativeRoot, filter) => {
+    if (preimages.get(visibleRoot) !== null) return;
+    const baseline = revisionHydrationPreimage(input, baselineRevision, relativeRoot);
+    const desired = revisionHydrationPreimage(input, desiredRevision, relativeRoot);
+    for (const filePath of /* @__PURE__ */ new Set([...baseline.keys(), ...desired.keys()])) {
+      if (filter && !filter(filePath)) continue;
+      if (!hydrationEntriesEqual(baseline.get(filePath), desired.get(filePath))) {
+        conflicts.push(path.posix.join(relativeRoot, filePath));
+      }
+    }
+  };
+  if (!input.trigger.canonicalCheckoutOnly) {
+    inspectRoot(
+      localWorkspacePlansPath(input.plansRoot),
+      WORKSPACE_NATIVE_PLANS_RELATIVE_PATH,
+      (filePath) => filePath.endsWith(".plan.md")
+    );
+  }
+  for (const manifest of input.projects) {
+    for (const branchName of manifest.branches) {
+      inspectRoot(
+        visibleProjectBranchPath(input.projectsRoot, manifest, branchName),
+        workspaceProjectBranchRelativePath(manifest.projectId, branchName)
+      );
+      if (!input.trigger.canonicalCheckoutOnly) {
+        inspectRoot(
+          localPlansBranchPath(input.plansRoot, manifest.projectId, branchName),
+          workspacePlansRelativePath(manifest.projectId, branchName),
+          (filePath) => filePath.endsWith(".plan.md")
+        );
+      }
+    }
+  }
+  return [...new Set(conflicts)].sort();
+}
+function hydrationConflictPaths(input, preimages, baselineRevision, desiredRevision) {
+  return [
+    .../* @__PURE__ */ new Set([
+      ...visibleHydrationConflictPaths(input, preimages, desiredRevision),
+      ...unavailableHydrationConflictPaths(input, preimages, baselineRevision, desiredRevision)
+    ])
+  ].sort();
 }
 function forceStageCanonicalCheckoutFiles(input, preservedGitlinks = [], opaqueRoots = []) {
   for (const manifest of input.projects) {
@@ -834,7 +1433,9 @@ function assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, revision) {
 }
 function ensureShadowWorkspace(input) {
   fs.mkdirSync(path.dirname(input.shadowRoot), { recursive: true });
+  let created = false;
   if (!fs.existsSync(path.join(input.shadowRoot, ".git"))) {
+    created = true;
     fs.rmSync(input.shadowRoot, { recursive: true, force: true });
     const clone = runGitResult(input, path.dirname(input.shadowRoot), ["clone", "--origin", "origin", input.remoteUrl, input.shadowRoot]);
     if (clone.exitCode !== 0) {
@@ -856,6 +1457,7 @@ function ensureShadowWorkspace(input) {
   } else if (!hasHead) {
     runGit(input, input.shadowRoot, ["checkout", "--orphan", WORKSPACE_BRANCH], "create canonical workspace branch");
   }
+  return created;
 }
 function revParse(input, revision) {
   const result = runGitResult(input, input.shadowRoot, ["rev-parse", "--verify", revision]);
@@ -932,14 +1534,15 @@ function resetUncommittedShadowSnapshot(input) {
   runGit(input, input.shadowRoot, ["clean", "-fd"], "clean interrupted workspace snapshot");
 }
 function fastForwardCleanShadowForNewCheckouts(input) {
-  if (!input.newVisibleCheckouts?.length) return;
+  if (!input.newVisibleCheckouts?.length) return null;
   runGit(input, input.shadowRoot, ["add", "-A"], "stage existing workspace changes before checkout hydration");
-  if (gitStatus(input)) return;
+  if (gitStatus(input)) return null;
   const localHead = revParse(input, "HEAD");
   const remoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
-  if (!localHead || !remoteHead || localHead === remoteHead) return;
-  if (!tryGit(input, input.shadowRoot, ["merge-base", "--is-ancestor", localHead, remoteHead])) return;
+  if (!localHead || !remoteHead || localHead === remoteHead) return null;
+  if (!tryGit(input, input.shadowRoot, ["merge-base", "--is-ancestor", localHead, remoteHead])) return null;
   runGit(input, input.shadowRoot, ["reset", "--hard", remoteHead], "fast-forward before checkout hydration");
+  return localHead;
 }
 function restoreShadowRootFromRemote(input, relativeRoot) {
   const remoteRevision = `origin/${WORKSPACE_BRANCH}`;
@@ -1136,12 +1739,12 @@ function convergeRedundantInboundCandidate(input, result) {
   );
   if (stagedTree !== remoteTree) return null;
   const localHead = revParse(input, "HEAD");
+  if (localHead === remoteHead) return null;
   runGit(input, input.shadowRoot, ["reset", "--hard", remoteHead], "converge redundant inbound workspace candidate");
   runGit(input, input.shadowRoot, ["clean", "-fd"], "clean redundant inbound workspace candidate");
-  mirrorShadowWorkspaceToVisible(input);
   return {
     ...result,
-    outcome: localHead === remoteHead ? "no_change" : "updated",
+    outcome: "updated",
     publishedHead: remoteHead,
     diffSizeBytes: 0,
     gitStatus: gitStatus(input),
@@ -1153,10 +1756,13 @@ async function synchronizeWorkspace(rawInput) {
   let input = { ...rawInput, attemptId: rawInput.attemptId ?? crypto.randomUUID() };
   try {
     input = { ...input, projects: workspaceProjectsForSync(input.projects, input.trigger) };
-    let mirroredGitlinkProjection = { entries: [], opaqueRoots: [] };
-    ensureShadowWorkspace(input);
+    let mirroredGitlinkProjection = { entries: [], opaqueRoots: [], visiblePreimages: /* @__PURE__ */ new Map() };
+    let fastForwardedFromHead = null;
+    const shadowWasCreated = ensureShadowWorkspace(input);
+    let hydrationPreimages = input.skipVisibleMirror ? hydrationPreimagesFromShadowRevision(input, shadowWasCreated ? null : revParse(input, "HEAD")) : /* @__PURE__ */ new Map();
     const remoteHeadAtStart = revParse(input, `origin/${WORKSPACE_BRANCH}`);
     const result = baseResult(input, remoteHeadAtStart);
+    const inboundConflictsAtStart = input.skipVisibleMirror && remoteHeadAtStart ? visibleHydrationConflictPaths(input, hydrationPreimages, `origin/${WORKSPACE_BRANCH}`) : [];
     if (input.resetToCanonical) {
       if (input.trigger.canonicalCheckoutOnly) {
         throw new Error("A canonical-checkout-only synchronization cannot reset the authoritative resolver checkout");
@@ -1175,9 +1781,10 @@ async function synchronizeWorkspace(rawInput) {
     if (!input.skipVisibleMirror) {
       const newCheckoutKeys = new Set((input.newVisibleCheckouts ?? []).map((target) => `${target.projectId}\0${target.branchName}`));
       mirroredGitlinkProjection = mirrorVisibleWorkspaceToShadow(input, newCheckoutKeys);
-      fastForwardCleanShadowForNewCheckouts(input);
+      fastForwardedFromHead = fastForwardCleanShadowForNewCheckouts(input);
       mergeGitlinkProjection(mirroredGitlinkProjection, reconcileNewVisibleCheckouts(input));
       mirroredGitlinkProjection.opaqueRoots = [...new Set(mirroredGitlinkProjection.opaqueRoots)].sort();
+      hydrationPreimages = mirroredGitlinkProjection.visiblePreimages ?? hydrationPreimages;
     }
     const stagePathspecs = mirroredGitlinkProjection.opaqueRoots.flatMap((root) => [`:(exclude,literal)${root}`]);
     runGit(input, input.shadowRoot, ["add", "-A", "--", ".", ...stagePathspecs], "stage workspace changes");
@@ -1218,9 +1825,22 @@ async function synchronizeWorkspace(rawInput) {
       runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit workspace changes");
     }
     let candidateHead = revParse(input, "HEAD");
+    const candidateHeadBeforeRebase = candidateHead;
     if (candidateHead) assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, candidateHead);
     const hasRemoteMain = Boolean(revParse(input, `origin/${WORKSPACE_BRANCH}`));
     const hasUnpushedCommit = candidateHead ? !hasRemoteMain || !tryGit(input, input.shadowRoot, ["merge-base", "--is-ancestor", candidateHead, `origin/${WORKSPACE_BRANCH}`]) : false;
+    if (hasUnpushedCommit && inboundConflictsAtStart.length > 0) {
+      const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...inboundConflictsAtStart])].sort();
+      return {
+        ...observed,
+        outcome: "failed",
+        candidateHead: candidateHead ?? void 0,
+        affectedProjects: affectedProjects(conflictPaths),
+        affectedPaths: reportedPaths(conflictPaths),
+        error: "Inbound workspace update overlaps local visible changes; the old-base candidate was preserved for reconciliation.",
+        gitStatus: gitStatus(input)
+      };
+    }
     if (!hasUnpushedCommit) {
       const localHead = revParse(input, "HEAD");
       const currentRemoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
@@ -1228,7 +1848,23 @@ async function synchronizeWorkspace(rawInput) {
         runGit(input, input.shadowRoot, ["reset", "--hard", `origin/${WORKSPACE_BRANCH}`], "update workspace from canonical state");
         runGit(input, input.shadowRoot, ["clean", "-fd"], "clean updated workspace");
         assertPublishedCanonicalCheckoutTree(input, currentRemoteHead, sampledCanonicalCheckoutTreeHash);
-        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
+        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
+        const inboundConflicts = input.trigger.canonicalCheckoutOnly ? [] : localHead ? hydrationConflictPaths(input, hydrationPreimages, localHead, currentRemoteHead) : visibleHydrationConflictPaths(input, hydrationPreimages, currentRemoteHead);
+        if (inboundConflicts.length > 0 && localHead) {
+          runGit(input, input.shadowRoot, ["reset", "--hard", localHead], "preserve old workspace base after inbound conflict");
+          runGit(input, input.shadowRoot, ["clean", "-fd"], "clean preserved old workspace base");
+          const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...inboundConflicts])].sort();
+          return {
+            ...observed,
+            outcome: "failed",
+            candidateHead: candidateHead ?? void 0,
+            publishedHead: currentRemoteHead,
+            affectedProjects: affectedProjects(conflictPaths),
+            affectedPaths: reportedPaths(conflictPaths),
+            error: "Inbound workspace update overlaps local visible changes; disjoint updates were hydrated and the old base was preserved for reconciliation.",
+            gitStatus: gitStatus(input)
+          };
+        }
         return {
           ...observed,
           outcome: "updated",
@@ -1240,9 +1876,27 @@ async function synchronizeWorkspace(rawInput) {
       const authoritativeHead = currentRemoteHead ?? localHead;
       if (authoritativeHead) {
         assertPublishedCanonicalCheckoutTree(input, authoritativeHead, sampledCanonicalCheckoutTreeHash);
-      }
-      if (input.skipVisibleMirror) {
-        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
+        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
+        const hydrationConflicts2 = input.trigger.canonicalCheckoutOnly ? [] : fastForwardedFromHead ? hydrationConflictPaths(input, hydrationPreimages, fastForwardedFromHead, authoritativeHead) : visibleHydrationConflictPaths(input, hydrationPreimages, authoritativeHead);
+        if (hydrationConflicts2.length > 0 && fastForwardedFromHead) {
+          runGit(
+            input,
+            input.shadowRoot,
+            ["reset", "--hard", fastForwardedFromHead],
+            "preserve old workspace base after new-checkout fast-forward conflict"
+          );
+          runGit(input, input.shadowRoot, ["clean", "-fd"], "clean preserved new-checkout workspace base");
+          return {
+            ...observed,
+            outcome: "failed",
+            candidateHead: candidateHead ?? void 0,
+            publishedHead: currentRemoteHead ?? void 0,
+            affectedProjects: affectedProjects(hydrationConflicts2),
+            affectedPaths: reportedPaths(hydrationConflicts2),
+            error: "Workspace fast-forward for a new checkout overlaps local visible changes; compatible updates were hydrated and the old base was preserved for reconciliation.",
+            gitStatus: gitStatus(input)
+          };
+        }
       }
       return {
         ...observed,
@@ -1259,7 +1913,7 @@ async function synchronizeWorkspace(rawInput) {
       rebaseCount += 1;
       if (rebase.exitCode !== 0) {
         const conflicted = runGitResult(input, input.shadowRoot, ["diff", "--name-only", "--diff-filter=U", "-z"]);
-        const conflictPaths = reportedPaths([.../* @__PURE__ */ new Set([...paths, ...conflicted.stdout.split("\0").filter(Boolean)])].sort());
+        const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...conflicted.stdout.split("\0").filter(Boolean)])].sort();
         runGit(input, input.shadowRoot, ["rebase", "--abort"], "preserve workspace candidate after rebase conflict");
         return {
           ...observed,
@@ -1267,7 +1921,8 @@ async function synchronizeWorkspace(rawInput) {
           expectedHead,
           candidateHead: candidateHead ?? void 0,
           rebaseCount,
-          affectedPaths: conflictPaths,
+          affectedProjects: affectedProjects(conflictPaths),
+          affectedPaths: reportedPaths(conflictPaths),
           error: `Workspace candidate conflicts with canonical head ${expectedHead}; local changes were preserved for reconciliation.`,
           gitStatus: gitStatus(input)
         };
@@ -1285,6 +1940,30 @@ async function synchronizeWorkspace(rawInput) {
         gitStatus: gitStatus(input)
       };
     }
+    assertPublishedCanonicalCheckoutTree(input, candidateHead, sampledCanonicalCheckoutTreeHash);
+    mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
+    const hydrationConflicts = input.trigger.canonicalCheckoutOnly ? [] : candidateHeadBeforeRebase ? hydrationConflictPaths(input, hydrationPreimages, candidateHeadBeforeRebase, "HEAD") : visibleHydrationConflictPaths(input, hydrationPreimages, "HEAD");
+    if (hydrationConflicts.length > 0 && candidateHeadBeforeRebase) {
+      runGit(
+        input,
+        input.shadowRoot,
+        ["reset", "--hard", candidateHeadBeforeRebase],
+        "preserve old-base workspace candidate after hydration conflict"
+      );
+      runGit(input, input.shadowRoot, ["clean", "-fd"], "clean old-base workspace candidate");
+      const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...hydrationConflicts])].sort();
+      return {
+        ...observed,
+        outcome: "failed",
+        expectedHead,
+        candidateHead,
+        rebaseCount,
+        affectedProjects: affectedProjects(conflictPaths),
+        affectedPaths: reportedPaths(conflictPaths),
+        error: "Workspace changed while its candidate was reconciling; visible changes and the old-base candidate were preserved.",
+        gitStatus: gitStatus(input)
+      };
+    }
     const upload = uploadWorkspaceCandidate(input, candidateHead);
     if (upload.exitCode !== 0) {
       return {
@@ -1297,8 +1976,6 @@ async function synchronizeWorkspace(rawInput) {
         gitStatus: gitStatus(input)
       };
     }
-    assertPublishedCanonicalCheckoutTree(input, candidateHead, sampledCanonicalCheckoutTreeHash);
-    mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
     return {
       ...observed,
       outcome: "candidate_ready",