@ricsam/r5d-worker 0.0.45 → 0.0.47

package/dist/mjs/workspace-sync.mjs

@@ -9,12 +9,19 @@ const MAX_REPORTED_WORKSPACE_PATHS = 2e3;
 const MAX_REPORTED_WORKSPACE_STATUS_BYTES = 256 * 1024;
 const MAX_MIRROR_COMPARISON_CACHE_ENTRIES = 2e5;
 const MIRROR_COMPARE_BUFFER_BYTES = 64 * 1024;
+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();
 function gitArgs(input, args) {
-  return input.authHeader ? ["git", "-c", `http.extraHeader=${input.authHeader}`, ...args] : ["git", ...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];
+}
+function withoutSubmoduleRecursion(args) {
+  return args[0] === "fetch" || args[0] === "push" ? [args[0], "--no-recurse-submodules", ...args.slice(1)] : args[0] === "clone" ? ["clone", "--no-recurse-submodules", ...args.slice(1)] : args[0] === "checkout" || args[0] === "reset" || args[0] === "restore" ? [args[0], "--no-recurse-submodules", ...args.slice(1)] : args;
 }
 function runGitResult(input, cwd, args) {
-  const result = Bun.spawnSync(gitArgs(input, args), {
+  const result = Bun.spawnSync(gitArgs(input, withoutSubmoduleRecursion(args)), {
     cwd,
     stdout: "pipe",
     stderr: "pipe",
@@ -42,6 +49,35 @@ function tryGit(input, cwd, args) {
 function encodeWorkspaceBranch(branchName) {
   return encodeURIComponent(branchName);
 }
+function workspaceProjectsForSync(projects, trigger) {
+  if (trigger.canonicalCheckoutOnly) {
+    if (!trigger.projectId || !trigger.branchName) {
+      throw new Error("A canonical-checkout-only synchronization requires projectId and branchName");
+    }
+    const project = projects.find((candidate) => candidate.projectId === trigger.projectId);
+    const checkout = project?.canonicalCheckouts.find((candidate) => candidate.branchName === trigger.branchName);
+    if (!project || !project.branches.includes(trigger.branchName) || !checkout) {
+      throw new Error(`Canonical resolver checkout ${trigger.projectId}/${trigger.branchName} is not present in this worker manifest`);
+    }
+    return [
+      {
+        ...project,
+        branches: [trigger.branchName],
+        canonicalCheckouts: [checkout]
+      }
+    ];
+  }
+  return projects.flatMap((project) => {
+    const canonicalBranches = new Set(project.canonicalCheckouts.map((checkout) => checkout.branchName));
+    const branches = project.branches.filter((branchName) => !canonicalBranches.has(branchName));
+    return branches.length > 0 || project.canonicalCheckouts.length > 0 ? [
+      {
+        ...project,
+        branches
+      }
+    ] : [];
+  });
+}
 function workspaceProjectBranchRelativePath(projectId, branchName) {
   return path.posix.join("projects", projectId, "branches", encodeWorkspaceBranch(branchName));
 }
@@ -66,12 +102,30 @@ function listGitEligibleFiles(checkoutPath) {
   if (!fs.existsSync(path.join(checkoutPath, ".git"))) {
     return [];
   }
-  const result = Bun.spawnSync(["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."], {
-    cwd: checkoutPath,
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
-  });
+  const result = Bun.spawnSync(
+    [
+      "git",
+      "-c",
+      "submodule.recurse=false",
+      "-c",
+      "fetch.recurseSubmodules=false",
+      "-c",
+      "push.recurseSubmodules=false",
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "--",
+      "."
+    ],
+    {
+      cwd: checkoutPath,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }
+  );
   if (result.exitCode !== 0) {
     throw new Error(`inspect eligible project files: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
   }
@@ -84,13 +138,195 @@ function listGitEligibleFiles(checkoutPath) {
     }
   }).sort();
 }
+function runCheckoutGitRaw(checkoutPath, args, action) {
+  const result = Bun.spawnSync(
+    ["git", "-c", "submodule.recurse=false", "-c", "fetch.recurseSubmodules=false", "-c", "push.recurseSubmodules=false", ...args],
+    {
+      cwd: checkoutPath,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`${action}: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
+  }
+  return result.stdout.toString();
+}
+function stagedCheckoutPaths(checkoutPath) {
+  return runCheckoutGitRaw(
+    checkoutPath,
+    ["diff", "--cached", "--name-only", "--no-renames", "-z", "HEAD"],
+    "inspect staged canonical resolver paths"
+  ).split("\0").filter(Boolean).sort();
+}
+function parseGitIndexEntries(output) {
+  return output.split("\0").filter(Boolean).flatMap((entry) => {
+    const separator = entry.indexOf("	");
+    if (separator === -1) return [];
+    const [mode, objectId, stage] = entry.slice(0, separator).split(" ");
+    const filePath = entry.slice(separator + 1);
+    return mode && objectId && stage && filePath ? [{ mode, objectId, stage, filePath }] : [];
+  });
+}
+function indexEntriesForPath(checkoutPath, filePath) {
+  return parseGitIndexEntries(
+    runCheckoutGitRaw(
+      checkoutPath,
+      ["--literal-pathspecs", "ls-files", "--stage", "-z", "--", filePath],
+      `inspect canonical resolver index entry for ${JSON.stringify(filePath)}`
+    )
+  );
+}
+function checkoutIndexEntries(checkoutPath) {
+  return parseGitIndexEntries(runCheckoutGitRaw(checkoutPath, ["ls-files", "--stage", "-z", "--", "."], "inspect project Git index"));
+}
+function checkoutGitlinks(checkoutPath) {
+  const entries = checkoutIndexEntries(checkoutPath);
+  const unmergedPaths = [...new Set(entries.filter((entry) => entry.stage !== "0").map((entry) => entry.filePath))].sort();
+  if (unmergedPaths.length > 0) {
+    throw new Error(`Project checkout has unmerged Git index stages: ${JSON.stringify(unmergedPaths)}`);
+  }
+  return entries.filter((entry) => entry.mode === "160000").map(({ filePath, objectId }) => ({ filePath, objectId })).sort((left, right) => left.filePath.localeCompare(right.filePath));
+}
+function revisionGitlinks(checkoutPath, revision) {
+  const output = runCheckoutGitRaw(checkoutPath, ["ls-tree", "-r", "-z", revision, "--", "."], `inspect ${revision} project gitlinks`);
+  return output.split("\0").filter(Boolean).flatMap((entry) => {
+    const separator = entry.indexOf("	");
+    if (separator === -1) return [];
+    const [mode, type, objectId] = entry.slice(0, separator).split(" ");
+    const filePath = entry.slice(separator + 1);
+    return mode === "160000" && type === "commit" && objectId && filePath ? [{ filePath, objectId }] : [];
+  }).sort((left, right) => left.filePath.localeCompare(right.filePath));
+}
+function stagedDeletedGitlinkPaths(checkoutPath) {
+  const currentEntries = checkoutIndexEntries(checkoutPath);
+  return revisionGitlinks(checkoutPath, "HEAD").filter(
+    (entry) => !currentEntries.some((candidate) => candidate.filePath === entry.filePath || candidate.filePath.startsWith(`${entry.filePath}/`))
+  ).map((entry) => entry.filePath).sort();
+}
+function lstatOrNull(filePath) {
+  try {
+    return fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function worktreeDiffersFromIndex(checkoutPath, filePath) {
+  const result = Bun.spawnSync(
+    ["git", "--literal-pathspecs", "-c", "core.fileMode=true", "diff", "--quiet", "--no-ext-diff", "--", filePath],
+    {
+      cwd: checkoutPath,
+      stdout: "ignore",
+      stderr: "pipe",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }
+  );
+  if (result.exitCode === 0) return false;
+  if (result.exitCode === 1) return true;
+  throw new Error(
+    `compare canonical resolver index and worktree for ${JSON.stringify(filePath)}: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`
+  );
+}
+function indexEntryTypeMatchesWorktree(entry, stat) {
+  if (entry.mode === "120000") return stat.isSymbolicLink();
+  if (entry.mode !== "100644" && entry.mode !== "100755") return false;
+  if (!stat.isFile()) return false;
+  return entry.mode === "100755" === ((stat.mode & 73) !== 0);
+}
+function assertCanonicalCheckoutIndexMatchesWorktree(checkoutPath) {
+  checkoutGitlinks(checkoutPath);
+  const mismatchedPaths = [];
+  for (const filePath of stagedCheckoutPaths(checkoutPath)) {
+    const entries = indexEntriesForPath(checkoutPath, filePath);
+    const worktreeEntry = lstatOrNull(path.join(checkoutPath, ...filePath.split("/")));
+    if (entries.length === 0) {
+      if (worktreeEntry && !worktreeEntry.isDirectory()) mismatchedPaths.push(filePath);
+      continue;
+    }
+    if (entries.length === 1 && entries[0]?.stage === "0" && entries[0].mode === "160000") {
+      if (worktreeEntry && !worktreeEntry.isDirectory()) mismatchedPaths.push(filePath);
+      continue;
+    }
+    if (entries.length !== 1 || entries[0]?.stage !== "0" || !worktreeEntry || !indexEntryTypeMatchesWorktree(entries[0], worktreeEntry) || worktreeDiffersFromIndex(checkoutPath, filePath)) {
+      mismatchedPaths.push(filePath);
+    }
+  }
+  if (mismatchedPaths.length > 0) {
+    throw new Error(
+      `Canonical resolver checkout has staged Git index state that is not represented by its worktree: ${JSON.stringify(
+        mismatchedPaths
+      )}. Make the worktree match the index or unstage these paths before synchronizing.`
+    );
+  }
+}
+function checkoutGitSnapshot(checkoutPath) {
+  const gitPaths = Bun.spawnSync(
+    [
+      "git",
+      "-c",
+      "submodule.recurse=false",
+      "-c",
+      "fetch.recurseSubmodules=false",
+      "-c",
+      "push.recurseSubmodules=false",
+      "rev-parse",
+      "--git-path",
+      "index",
+      ...ACTIVE_GIT_LOCK_PATHS.flatMap((lock) => ["--git-path", lock])
+    ],
+    {
+      cwd: checkoutPath,
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }
+  );
+  if (gitPaths.exitCode !== 0) return null;
+  const [indexPath, ...lockPaths] = gitPaths.stdout.toString().trim().split(/\r?\n/).map((gitPath) => path.resolve(checkoutPath, gitPath));
+  if (!indexPath || lockPaths.length !== ACTIVE_GIT_LOCK_PATHS.length || lockPaths.some((lockPath) => fs.existsSync(lockPath))) {
+    return null;
+  }
+  const head = Bun.spawnSync(
+    [
+      "git",
+      "-c",
+      "submodule.recurse=false",
+      "-c",
+      "fetch.recurseSubmodules=false",
+      "-c",
+      "push.recurseSubmodules=false",
+      "rev-parse",
+      "--verify",
+      "HEAD"
+    ],
+    {
+      cwd: checkoutPath,
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    }
+  );
+  let indexSignature = "missing";
+  try {
+    const stat = fs.statSync(indexPath);
+    indexSignature = entrySignature(stat);
+  } catch {
+  }
+  if (lockPaths.some((lockPath) => fs.existsSync(lockPath))) return null;
+  return `${head.exitCode === 0 ? head.stdout.toString().trim() : "unborn"}\0${indexSignature}`;
+}
 function listShadowTrackedFiles(input, relativeRoot) {
   const normalizedRoot = relativeRoot.split(path.sep).join("/").replace(/^\/+|\/+$/g, "");
   const output = runGit(input, input.shadowRoot, ["ls-files", "-z", "--cached", "--", normalizedRoot], "list canonical workspace files");
   const prefix = `${normalizedRoot}/`;
   return output.split("\0").filter((entry) => entry.startsWith(prefix)).map((entry) => entry.slice(prefix.length)).filter(Boolean).sort();
 }
-function listFilesRecursively(root, filter) {
+function pathIsWithinOpaqueRoot(relativePath, opaqueRoots) {
+  return opaqueRoots.some((root) => relativePath === root || relativePath.startsWith(`${root}/`));
+}
+function listFilesRecursively(root, filter, opaqueRoots = []) {
   if (!fs.existsSync(root)) return [];
   const files = [];
   const visit = (current, relativeDir) => {
@@ -98,6 +334,7 @@ function listFilesRecursively(root, filter) {
       if (entry.name === ".git") continue;
       const relativePath = relativeDir ? path.posix.join(relativeDir, entry.name) : entry.name;
       const absolutePath = path.join(current, entry.name);
+      if (pathIsWithinOpaqueRoot(relativePath, opaqueRoots)) continue;
       if (entry.isDirectory()) {
         visit(absolutePath, relativePath);
       } else if (!filter || filter(relativePath)) {
@@ -108,14 +345,19 @@ function listFilesRecursively(root, filter) {
   visit(root, "");
   return files.sort();
 }
-function removeEmptyDirectories(root) {
+function removeEmptyDirectories(root, opaqueRoots = []) {
   if (!fs.existsSync(root)) return;
-  const visit = (current) => {
+  const visit = (current, relativeDir) => {
     let empty = true;
     for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
       const absolutePath = path.join(current, entry.name);
+      const relativePath = relativeDir ? path.posix.join(relativeDir, entry.name) : entry.name;
+      if (pathIsWithinOpaqueRoot(relativePath, opaqueRoots)) {
+        empty = false;
+        continue;
+      }
       if (entry.isDirectory()) {
-        if (!visit(absolutePath)) empty = false;
+        if (!visit(absolutePath, relativePath)) empty = false;
       } else {
         empty = false;
       }
@@ -123,7 +365,7 @@ function removeEmptyDirectories(root) {
     if (empty && current !== root) fs.rmdirSync(current);
     return empty;
   };
-  visit(root);
+  visit(root, "");
 }
 function copyEntry(sourceRoot, targetRoot, relativePath) {
   const sourcePath = path.resolve(sourceRoot, ...relativePath.split("/"));
@@ -193,39 +435,218 @@ function entriesEqual(sourcePath, targetPath) {
   }
   return equal;
 }
-function mirrorFileSet(sourceRoot, targetRoot, sourceFiles, targetFiles) {
+function mirrorFileSet(sourceRoot, targetRoot, sourceFiles, targetFiles, opaqueTargetRoots = [], opaqueSourceRoots = []) {
   fs.mkdirSync(targetRoot, { recursive: true });
   const sourceSet = new Set(sourceFiles);
   for (const relativePath of targetFiles) {
+    if (pathIsWithinOpaqueRoot(relativePath, opaqueTargetRoots)) continue;
     if (sourceSet.has(relativePath)) continue;
     const targetPath = path.resolve(targetRoot, ...relativePath.split("/"));
     assertInside(targetRoot, targetPath, "Workspace deletion path");
     fs.rmSync(targetPath, { recursive: true, force: true });
   }
   for (const relativePath of sourceFiles) {
+    if (pathIsWithinOpaqueRoot(relativePath, opaqueSourceRoots)) continue;
+    if (pathIsWithinOpaqueRoot(relativePath, opaqueTargetRoots)) continue;
     const sourcePath = path.resolve(sourceRoot, ...relativePath.split("/"));
-    if (!fs.existsSync(sourcePath)) continue;
-    const stat = fs.lstatSync(sourcePath);
+    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);
   }
-  removeEmptyDirectories(targetRoot);
+  removeEmptyDirectories(targetRoot, opaqueTargetRoots);
+}
+function indexPathsUnderCheckoutPath(checkoutPath, filePath) {
+  return runCheckoutGitRaw(
+    checkoutPath,
+    ["--literal-pathspecs", "ls-files", "-z", "--", filePath],
+    `inspect index paths beneath ${JSON.stringify(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)}`
+    );
+  }
+  runCheckoutGitRaw(
+    checkoutPath,
+    ["--literal-pathspecs", "update-index", "--add", "--cacheinfo", "160000", gitlink.objectId, gitlink.filePath],
+    `record gitlink ${JSON.stringify(gitlink.filePath)}`
+  );
+}
+function removeCheckoutIndexPath(checkoutPath, filePath) {
+  runCheckoutGitRaw(
+    checkoutPath,
+    ["--literal-pathspecs", "update-index", "--force-remove", "--", filePath],
+    `remove gitlink ${JSON.stringify(filePath)}`
+  );
+}
+function shadowProjectGitlinks(input, relativeRoot) {
+  const prefix = `${relativeRoot}/`;
+  const entries = parseGitIndexEntries(
+    runGit(input, input.shadowRoot, ["--literal-pathspecs", "ls-files", "--stage", "-z", "--", relativeRoot], "inspect workspace gitlinks")
+  );
+  const unmergedPaths = [...new Set(entries.filter((entry) => entry.stage !== "0").map((entry) => entry.filePath))].sort();
+  if (unmergedPaths.length > 0) {
+    throw new Error(`Canonical workspace has unmerged Git index stages: ${JSON.stringify(unmergedPaths)}`);
+  }
+  return entries.filter((entry) => entry.mode === "160000" && entry.filePath.startsWith(prefix)).map((entry) => ({ filePath: entry.filePath.slice(prefix.length), objectId: entry.objectId })).sort((left, right) => left.filePath.localeCompare(right.filePath));
+}
+function replaceShadowIndexPathWithGitlink(input, relativeRoot, gitlink) {
+  const workspacePath = path.posix.join(relativeRoot, gitlink.filePath);
+  const existingPaths = runGit(
+    input,
+    input.shadowRoot,
+    ["--literal-pathspecs", "ls-files", "-z", "--", workspacePath],
+    `inspect workspace index beneath gitlink ${JSON.stringify(workspacePath)}`
+  ).split("\0").filter(Boolean);
+  for (const indexPath of existingPaths) {
+    runGit(
+      input,
+      input.shadowRoot,
+      ["--literal-pathspecs", "update-index", "--force-remove", "--", indexPath],
+      `remove workspace index entry beneath gitlink ${JSON.stringify(workspacePath)}`
+    );
+  }
+  const placeholderPath = path.join(input.shadowRoot, ...workspacePath.split("/"));
+  fs.rmSync(placeholderPath, { recursive: true, force: true });
+  fs.mkdirSync(placeholderPath, { recursive: true });
+  runGit(
+    input,
+    input.shadowRoot,
+    ["--literal-pathspecs", "update-index", "--add", "--cacheinfo", "160000", gitlink.objectId, workspacePath],
+    `record workspace gitlink ${JSON.stringify(workspacePath)}`
+  );
+}
+function mirrorVisibleGitlinksToShadow(input, relativeRoot, visibleGitlinks) {
+  const desiredByPath = new Map(visibleGitlinks.map((entry) => [entry.filePath, entry]));
+  for (const current of shadowProjectGitlinks(input, relativeRoot)) {
+    if (desiredByPath.has(current.filePath)) continue;
+    const workspacePath = path.posix.join(relativeRoot, current.filePath);
+    runGit(
+      input,
+      input.shadowRoot,
+      ["--literal-pathspecs", "update-index", "--force-remove", "--", workspacePath],
+      `remove deleted workspace gitlink ${JSON.stringify(workspacePath)}`
+    );
+    fs.rmSync(path.join(input.shadowRoot, ...workspacePath.split("/")), { recursive: true, force: true });
+  }
+  for (const gitlink of visibleGitlinks) replaceShadowIndexPathWithGitlink(input, relativeRoot, gitlink);
+}
+function mirrorShadowGitlinksToVisible(desired, visibleRoot) {
+  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) {
+    const visiblePath = path.join(visibleRoot, ...gitlink.filePath.split("/"));
+    const existing = lstatOrNull(visiblePath);
+    if (existing && !existing.isDirectory()) fs.rmSync(visiblePath, { recursive: true, force: true });
+    fs.mkdirSync(visiblePath, { recursive: true });
+    replaceCheckoutIndexPathWithGitlink(visibleRoot, gitlink);
+  }
+}
+function assertSafeVisibleGitlinkTransitions(visibleRoot, currentGitlinks, desiredGitlinks, shadowFiles) {
+  const desiredGitlinkPaths = new Set(desiredGitlinks.map((entry) => entry.filePath));
+  for (const current of currentGitlinks) {
+    if (desiredGitlinkPaths.has(current.filePath)) continue;
+    const becomesOrdinaryPath = shadowFiles.some(
+      (filePath) => filePath === current.filePath || filePath.startsWith(`${current.filePath}/`)
+    );
+    if (!becomesOrdinaryPath) continue;
+    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) {
+      continue;
+    }
+    throw new Error(
+      `Cannot replace initialized or nonempty gitlink ${JSON.stringify(
+        current.filePath
+      )} with ordinary workspace content without deleting submodule data`
+    );
+  }
+}
+function restoreShadowProjectSnapshot(input, relativeRoot) {
+  const shadowRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
+  const headFiles = runGitResult(input, input.shadowRoot, ["ls-tree", "-r", "--name-only", "-z", "HEAD", "--", relativeRoot]);
+  if (headFiles.exitCode === 0 && headFiles.stdout) {
+    runGit(
+      input,
+      input.shadowRoot,
+      ["restore", "--source=HEAD", "--staged", "--worktree", "--", relativeRoot],
+      "restore deferred checkout scan"
+    );
+    runGit(input, input.shadowRoot, ["clean", "-fd", "--", relativeRoot], "clean deferred checkout scan");
+    return;
+  }
+  runGitResult(input, input.shadowRoot, ["--literal-pathspecs", "rm", "-r", "-f", "--cached", "--ignore-unmatch", "--", relativeRoot]);
+  fs.rmSync(shadowRoot, { recursive: true, force: true });
 }
 function mirrorVisibleProjectToShadow(input, manifest, branchName) {
   const visibleRoot = visibleProjectBranchPath(input.projectsRoot, manifest, branchName);
-  if (!fs.existsSync(path.join(visibleRoot, ".git"))) return;
-  const shadowRoot = path.join(input.shadowRoot, ...workspaceProjectBranchRelativePath(manifest.projectId, branchName).split("/"));
-  mirrorFileSet(visibleRoot, shadowRoot, listGitEligibleFiles(visibleRoot), listFilesRecursively(shadowRoot));
+  if (!fs.existsSync(path.join(visibleRoot, ".git"))) return { entries: [], opaqueRoots: [] };
+  const isCanonicalCheckout = manifest.canonicalCheckouts?.some((checkout) => checkout.branchName === branchName);
+  if (isCanonicalCheckout) {
+    assertCanonicalCheckoutIndexMatchesWorktree(visibleRoot);
+  }
+  const beforeSnapshot = checkoutGitSnapshot(visibleRoot);
+  if (!beforeSnapshot) return { entries: [], opaqueRoots: [] };
+  const visibleGitlinks = checkoutGitlinks(visibleRoot);
+  const visibleIndexEntries = checkoutIndexEntries(visibleRoot).filter((entry) => entry.stage === "0");
+  const indexedGitlinkPaths = new Set(visibleGitlinks.map((entry) => entry.filePath));
+  const stagedDeletedGitlinkRoots = stagedDeletedGitlinkPaths(visibleRoot);
+  const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, branchName);
+  const shadowGitlinkRoots = shadowProjectGitlinks(input, relativeRoot).filter(
+    (entry) => !indexedGitlinkPaths.has(entry.filePath) && !visibleIndexEntries.some(
+      (candidate) => candidate.mode !== "160000" && (candidate.filePath === entry.filePath || candidate.filePath.startsWith(`${entry.filePath}/`))
+    )
+  ).map((entry) => entry.filePath);
+  const visibleGitlinkRoots = [.../* @__PURE__ */ new Set([...indexedGitlinkPaths, ...stagedDeletedGitlinkRoots, ...shadowGitlinkRoots])].sort();
+  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) {
+    restoreShadowProjectSnapshot(input, relativeRoot);
+    return { entries: [], opaqueRoots: [] };
+  }
+  return {
+    entries: visibleGitlinks.map((entry) => ({
+      filePath: path.posix.join(relativeRoot, entry.filePath),
+      objectId: entry.objectId
+    })),
+    opaqueRoots: visibleGitlinkRoots.map((filePath) => path.posix.join(relativeRoot, filePath))
+  };
 }
-function mirrorShadowProjectToVisible(input, manifest, branchName) {
+function mirrorShadowProjectToVisible(input, manifest, branchName, additionalOpaqueRoots = []) {
   const visibleRoot = visibleProjectBranchPath(input.projectsRoot, manifest, branchName);
   if (!fs.existsSync(path.join(visibleRoot, ".git"))) return;
+  checkoutGitlinks(visibleRoot);
   const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, branchName);
   const shadowRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
   const shadowFiles = listShadowTrackedFiles(input, relativeRoot);
-  mirrorFileSet(shadowRoot, visibleRoot, shadowFiles, listGitEligibleFiles(visibleRoot));
+  const desiredGitlinks = shadowProjectGitlinks(input, relativeRoot);
+  const desiredGitlinkPaths = new Set(desiredGitlinks.map((entry) => entry.filePath));
+  const visibleGitlinks = checkoutGitlinks(visibleRoot);
+  const protectedGitlinkRoots = [
+    .../* @__PURE__ */ new Set([...visibleGitlinks.map((entry) => entry.filePath), ...stagedDeletedGitlinkPaths(visibleRoot), ...additionalOpaqueRoots])
+  ].sort();
+  assertSafeVisibleGitlinkTransitions(
+    visibleRoot,
+    protectedGitlinkRoots.map((filePath) => ({ filePath, objectId: "" })),
+    desiredGitlinks,
+    shadowFiles
+  );
+  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);
 }
 function mirrorLocalPlansToShadow(input, manifest, branchName) {
   const sourceRoot = localPlansBranchPath(input.plansRoot, manifest.projectId, branchName);
@@ -246,60 +667,130 @@ function mirrorShadowPlansToLocal(input, manifest, branchName) {
     listFilesRecursively(targetRoot, planFilter)
   );
 }
-function pruneDirectoryChildren(root, allowedNames) {
-  if (!fs.existsSync(root)) return;
-  for (const entry of fs.readdirSync(root)) {
-    if (allowedNames.has(entry)) continue;
-    const target = path.resolve(root, entry);
-    assertInside(root, target, "Workspace manifest prune path");
-    fs.rmSync(target, { recursive: true, force: true });
-  }
-}
-function pruneShadowToManifest(input) {
-  const projectIds = new Set(input.projects.map((project) => project.projectId));
-  const projectsRoot = path.join(input.shadowRoot, "projects");
-  const plansRoot = path.join(input.shadowRoot, "plans");
-  pruneDirectoryChildren(projectsRoot, projectIds);
-  pruneDirectoryChildren(plansRoot, projectIds);
-  for (const manifest of input.projects) {
-    const encodedBranches = new Set(manifest.branches.map(encodeWorkspaceBranch));
-    pruneDirectoryChildren(path.join(projectsRoot, manifest.projectId, "branches"), encodedBranches);
-    pruneDirectoryChildren(path.join(plansRoot, manifest.projectId), encodedBranches);
-  }
+function mergeGitlinkProjection(target, source) {
+  target.entries.push(...source.entries);
+  target.opaqueRoots.push(...source.opaqueRoots);
 }
 function mirrorVisibleWorkspaceToShadow(input, excludedCheckouts = /* @__PURE__ */ new Set()) {
-  pruneShadowToManifest(input);
+  const projection = { entries: [], opaqueRoots: [] };
   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;
-      mirrorVisibleProjectToShadow(input, manifest, branchName);
-      mirrorLocalPlansToShadow(input, manifest, branchName);
+      mergeGitlinkProjection(projection, mirrorVisibleProjectToShadow(input, manifest, branchName));
+      if (!input.trigger.canonicalCheckoutOnly) mirrorLocalPlansToShadow(input, manifest, branchName);
     }
   }
+  projection.opaqueRoots = [...new Set(projection.opaqueRoots)].sort();
+  return projection;
 }
 function reconcileNewVisibleCheckouts(input) {
+  const projection = { entries: [], opaqueRoots: [] };
   for (const target of input.newVisibleCheckouts ?? []) {
     const manifest = input.projects.find((project) => project.projectId === target.projectId);
     if (!manifest || !manifest.branches.includes(target.branchName)) continue;
     const projectRoot = workspaceProjectBranchRelativePath(target.projectId, target.branchName);
-    if (listShadowTrackedFiles(input, projectRoot).length > 0) {
+    if (input.trigger.canonicalCheckoutOnly) {
+      mergeGitlinkProjection(projection, mirrorVisibleProjectToShadow(input, manifest, target.branchName));
+    } else if (listShadowTrackedFiles(input, projectRoot).length > 0 || restoreShadowRootFromRemote(input, projectRoot)) {
       mirrorShadowProjectToVisible(input, manifest, target.branchName);
     } else {
-      mirrorVisibleProjectToShadow(input, manifest, target.branchName);
+      mergeGitlinkProjection(projection, mirrorVisibleProjectToShadow(input, manifest, target.branchName));
     }
+    if (input.trigger.canonicalCheckoutOnly) continue;
     const plansRoot = workspacePlansRelativePath(target.projectId, target.branchName);
-    if (listShadowTrackedFiles(input, plansRoot).length > 0) {
+    if (listShadowTrackedFiles(input, plansRoot).length > 0 || restoreShadowRootFromRemote(input, plansRoot)) {
       mirrorShadowPlansToLocal(input, manifest, target.branchName);
     } else {
       mirrorLocalPlansToShadow(input, manifest, target.branchName);
     }
   }
+  projection.opaqueRoots = [...new Set(projection.opaqueRoots)].sort();
+  return projection;
 }
-function mirrorShadowWorkspaceToVisible(input) {
+function mirrorShadowWorkspaceToVisible(input, opaqueWorkspaceRoots = []) {
   for (const manifest of [...input.projects].sort((left, right) => left.projectId.localeCompare(right.projectId))) {
     for (const branchName of [...new Set(manifest.branches)].sort()) {
-      mirrorShadowProjectToVisible(input, manifest, branchName);
-      mirrorShadowPlansToLocal(input, manifest, branchName);
+      const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, 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);
+    }
+  }
+}
+function forceStageCanonicalCheckoutFiles(input, preservedGitlinks = [], opaqueRoots = []) {
+  for (const manifest of input.projects) {
+    for (const checkout of manifest.canonicalCheckouts ?? []) {
+      if (!manifest.branches.includes(checkout.branchName)) continue;
+      const relativeRoot = workspaceProjectBranchRelativePath(manifest.projectId, checkout.branchName);
+      const absoluteRoot = path.join(input.shadowRoot, ...relativeRoot.split("/"));
+      if (!fs.existsSync(absoluteRoot)) continue;
+      const scopedOpaqueRoots = opaqueRoots.filter((root) => root.startsWith(`${relativeRoot}/`)).map((root) => root.slice(relativeRoot.length + 1));
+      runGit(
+        input,
+        input.shadowRoot,
+        [
+          "add",
+          "-f",
+          "-A",
+          "--",
+          `:(literal)${relativeRoot}`,
+          ...scopedOpaqueRoots.map((root) => `:(exclude,literal)${path.posix.join(relativeRoot, root)}`)
+        ],
+        `force-stage canonical resolver checkout ${manifest.projectId}/${checkout.branchName}`
+      );
+    }
+  }
+  for (const gitlink of preservedGitlinks) {
+    replaceShadowIndexPathWithGitlink(input, "", gitlink);
+  }
+  const preservedPaths = new Set(preservedGitlinks.map((entry) => entry.filePath));
+  for (const opaqueRoot of opaqueRoots) {
+    if (preservedPaths.has(opaqueRoot)) continue;
+    runGit(
+      input,
+      input.shadowRoot,
+      ["--literal-pathspecs", "update-index", "--force-remove", "--", opaqueRoot],
+      `remove explicitly deleted workspace gitlink ${JSON.stringify(opaqueRoot)}`
+    );
+  }
+}
+function canonicalCheckoutRelativeRoots(input) {
+  const roots = /* @__PURE__ */ new Set();
+  for (const manifest of input.projects) {
+    for (const checkout of manifest.canonicalCheckouts) {
+      roots.add(workspaceProjectBranchRelativePath(manifest.projectId, checkout.branchName));
+    }
+  }
+  return [...roots].sort();
+}
+function restoreUnscopedCanonicalCheckoutSubtrees(input) {
+  if (input.trigger.canonicalCheckoutOnly) return;
+  const remoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+  const emptyTree = emptyTreeHash(input);
+  for (const relativeRoot of canonicalCheckoutRelativeRoots(input)) {
+    const remoteTree = remoteHead ? workspaceSubtreeTreeHashAtRevision(input, remoteHead, relativeRoot) : emptyTree;
+    if (remoteTree === emptyTree) {
+      runGitResult(input, input.shadowRoot, ["--literal-pathspecs", "rm", "-r", "-f", "--cached", "--ignore-unmatch", "--", relativeRoot]);
+      fs.rmSync(path.join(input.shadowRoot, ...relativeRoot.split("/")), { recursive: true, force: true });
+      continue;
+    }
+    runGit(
+      input,
+      input.shadowRoot,
+      ["--literal-pathspecs", "restore", `--source=${remoteHead}`, "--staged", "--worktree", "--", relativeRoot],
+      `restore excluded canonical resolver subtree ${relativeRoot}`
+    );
+  }
+}
+function assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, revision) {
+  if (input.trigger.canonicalCheckoutOnly) return;
+  const remoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+  const emptyTree = emptyTreeHash(input);
+  for (const relativeRoot of canonicalCheckoutRelativeRoots(input)) {
+    const candidateTree = workspaceSubtreeTreeHashAtRevision(input, revision, relativeRoot);
+    const remoteTree = remoteHead ? workspaceSubtreeTreeHashAtRevision(input, remoteHead, relativeRoot) : emptyTree;
+    if (candidateTree !== remoteTree) {
+      throw new Error(`Generic workspace synchronization cannot publish canonical resolver subtree ${relativeRoot}`);
     }
   }
 }
@@ -332,14 +823,165 @@ function revParse(input, revision) {
   const result = runGitResult(input, input.shadowRoot, ["rev-parse", "--verify", revision]);
   return result.exitCode === 0 ? result.stdout : null;
 }
+function emptyTreeHash(input) {
+  const result = Bun.spawnSync(gitArgs(input, ["mktree"]), {
+    cwd: input.shadowRoot,
+    stdin: Buffer.alloc(0),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(`create empty workspace tree: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
+  }
+  return result.stdout.toString().trim();
+}
+function workspaceSubtreeTreeHashAtRevision(input, revision, relativeRoot) {
+  const rootType = runGitResult(input, input.shadowRoot, ["cat-file", "-t", revision]);
+  if (rootType.exitCode !== 0 || rootType.stdout !== "commit" && rootType.stdout !== "tree") {
+    throw new Error(`Cannot inspect canonical resolver subtree at invalid workspace revision ${revision}`);
+  }
+  let treeHash = rootType.stdout === "commit" ? runGit(input, input.shadowRoot, ["rev-parse", "--verify", `${revision}^{tree}`], "resolve workspace root tree") : revision;
+  for (const segment of relativeRoot.split("/")) {
+    const entry = runGitResult(input, input.shadowRoot, ["--literal-pathspecs", "ls-tree", "-z", treeHash, "--", segment]);
+    if (entry.exitCode !== 0) {
+      throw new Error(`Inspect canonical resolver workspace path ${relativeRoot}: ${entry.stderr || entry.stdout}`);
+    }
+    if (!entry.stdout) return emptyTreeHash(input);
+    const separator = entry.stdout.indexOf("	");
+    const [mode, type, objectId] = separator === -1 ? [] : entry.stdout.slice(0, separator).split(" ");
+    const entryName = separator === -1 ? "" : entry.stdout.slice(separator + 1).replace(/\0+$/, "");
+    if (!mode || type !== "tree" || !objectId || entryName !== segment) {
+      throw new Error(`Canonical resolver workspace path ${relativeRoot} contains a non-tree component ${segment}`);
+    }
+    treeHash = objectId;
+  }
+  return treeHash;
+}
+function canonicalCheckoutTreeHashAtRevision(input, revision) {
+  if (!input.trigger.canonicalCheckoutOnly || !input.trigger.projectId || !input.trigger.branchName) {
+    throw new Error("Canonical checkout tree hashing requires an exact canonical-checkout-only trigger");
+  }
+  return workspaceSubtreeTreeHashAtRevision(
+    input,
+    revision,
+    workspaceProjectBranchRelativePath(input.trigger.projectId, input.trigger.branchName)
+  );
+}
+function sampleCanonicalCheckoutTree(input) {
+  if (!input.trigger.canonicalCheckoutOnly) return void 0;
+  const stagedWorkspaceTree = runGit(input, input.shadowRoot, ["write-tree"], "write canonical resolver workspace tree");
+  return canonicalCheckoutTreeHashAtRevision(input, stagedWorkspaceTree);
+}
+function assertPublishedCanonicalCheckoutTree(input, revision, sampledTreeHash) {
+  if (!input.trigger.canonicalCheckoutOnly) return;
+  if (!sampledTreeHash) throw new Error("Canonical resolver synchronization did not capture a staged subtree tree hash");
+  const publishedTreeHash = canonicalCheckoutTreeHashAtRevision(input, revision);
+  if (publishedTreeHash !== sampledTreeHash) {
+    throw new Error(`Canonical resolver subtree changed while synchronizing: sampled ${sampledTreeHash}, published ${publishedTreeHash}`);
+  }
+}
 function gitStatus(input) {
   return runGit(input, input.shadowRoot, ["status", "--porcelain=v1", "--untracked-files=all"], "read workspace status");
 }
-function stagedPaths(input) {
-  return runGit(input, input.shadowRoot, ["diff", "--cached", "--name-only", "-z"], "list workspace changes").split("\0").filter(Boolean).sort();
+function resetUncommittedShadowSnapshot(input) {
+  if (!gitStatus(input)) return;
+  if (tryGit(input, input.shadowRoot, ["rev-parse", "--verify", "HEAD"])) {
+    runGit(input, input.shadowRoot, ["reset", "--hard", "HEAD"], "reset interrupted workspace snapshot");
+  } else {
+    runGit(input, input.shadowRoot, ["read-tree", "--empty"], "reset interrupted unborn workspace snapshot");
+  }
+  runGit(input, input.shadowRoot, ["clean", "-fd"], "clean interrupted workspace snapshot");
+}
+function fastForwardCleanShadowForNewCheckouts(input) {
+  if (!input.newVisibleCheckouts?.length) return;
+  runGit(input, input.shadowRoot, ["add", "-A"], "stage existing workspace changes before checkout hydration");
+  if (gitStatus(input)) return;
+  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;
+  runGit(input, input.shadowRoot, ["reset", "--hard", remoteHead], "fast-forward before checkout hydration");
+}
+function restoreShadowRootFromRemote(input, relativeRoot) {
+  const remoteRevision = `origin/${WORKSPACE_BRANCH}`;
+  const remoteFiles = runGitResult(input, input.shadowRoot, ["ls-tree", "-r", "--name-only", "-z", remoteRevision, "--", relativeRoot]);
+  if (remoteFiles.exitCode !== 0 || !remoteFiles.stdout) return false;
+  runGit(
+    input,
+    input.shadowRoot,
+    ["restore", `--source=${remoteRevision}`, "--staged", "--worktree", "--", relativeRoot],
+    `hydrate ${relativeRoot} from canonical workspace`
+  );
+  return true;
+}
+function candidateBaseRevision(input) {
+  const localHead = revParse(input, "HEAD");
+  if (!localHead) return null;
+  const remoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+  if (!remoteHead) {
+    const emptyTree = Bun.spawnSync(gitArgs(input, ["mktree"]), {
+      cwd: input.shadowRoot,
+      stdin: Buffer.alloc(0),
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+    });
+    if (emptyTree.exitCode !== 0) {
+      throw new Error(
+        `create empty workspace comparison tree: ${emptyTree.stderr.toString().trim() || `git exited ${emptyTree.exitCode}`}`
+      );
+    }
+    return emptyTree.stdout.toString().trim();
+  }
+  const mergeBase = runGitResult(input, input.shadowRoot, ["merge-base", localHead, remoteHead]);
+  return mergeBase.exitCode === 0 && mergeBase.stdout ? mergeBase.stdout : remoteHead;
 }
-async function stagedDiffSizeBytes(input) {
-  const subprocess = Bun.spawn(gitArgs(input, ["diff", "--cached", "--binary", "--no-ext-diff"]), {
+function stagedPaths(input, baseRevision) {
+  return runGit(
+    input,
+    input.shadowRoot,
+    ["diff", "--cached", "--name-only", "-z", ...baseRevision ? [baseRevision] : []],
+    "list workspace changes"
+  ).split("\0").filter(Boolean).sort();
+}
+function stagedDeletedPaths(input, baseRevision) {
+  return runGit(
+    input,
+    input.shadowRoot,
+    ["diff", "--cached", "--diff-filter=D", "--name-only", "-z", ...baseRevision ? [baseRevision] : []],
+    "list workspace deletions"
+  ).split("\0").filter(Boolean).sort();
+}
+function managedCheckoutRoot(filePath) {
+  const projectMatch = /^projects\/([^/]+)\/branches\/([^/]+)\//.exec(filePath);
+  return projectMatch ? `projects/${projectMatch[1]}/branches/${projectMatch[2]}` : null;
+}
+function revisionTrackedFileCount(input, revision, relativeRoot) {
+  if (!revision) return 0;
+  const result = runGitResult(input, input.shadowRoot, ["ls-tree", "-r", "--name-only", "-z", revision, "--", relativeRoot]);
+  if (result.exitCode !== 0) return 0;
+  return result.stdout.split("\0").filter(Boolean).length;
+}
+function destructiveCheckoutReductions(input, baseRevision) {
+  const authoritativeRoot = input.trigger.canonicalCheckoutOnly && input.trigger.projectId && input.trigger.branchName ? workspaceProjectBranchRelativePath(input.trigger.projectId, input.trigger.branchName) : null;
+  const roots = new Set(
+    stagedDeletedPaths(input, baseRevision).map(managedCheckoutRoot).filter((root) => Boolean(root) && root !== authoritativeRoot)
+  );
+  const destructive = [];
+  for (const root of roots) {
+    const trackedBefore = revisionTrackedFileCount(input, baseRevision, root);
+    if (trackedBefore === 0) continue;
+    const trackedAfter = listShadowTrackedFiles(input, root).length;
+    const removedRatio = (trackedBefore - trackedAfter) / trackedBefore;
+    if (trackedAfter === 0 || trackedBefore >= DESTRUCTIVE_CHECKOUT_MIN_TRACKED_FILES && removedRatio >= DESTRUCTIVE_CHECKOUT_REMOVAL_RATIO) {
+      destructive.push({ root, trackedBefore, trackedAfter });
+    }
+  }
+  return destructive.sort((left, right) => left.root.localeCompare(right.root));
+}
+async function stagedDiffSizeBytes(input, baseRevision) {
+  const subprocess = Bun.spawn(gitArgs(input, ["diff", "--cached", "--binary", "--no-ext-diff", ...baseRevision ? [baseRevision] : []]), {
     cwd: input.shadowRoot,
     stdout: "pipe",
     stderr: "pipe",
@@ -399,14 +1041,14 @@ function isNonFastForward(result) {
 ${result.stderr}`.toLowerCase();
   return output.includes("non-fast-forward") || output.includes("fetch first") || output.includes("[rejected]");
 }
-function resetShadowToRemote(input) {
+function resetShadowToRemote(input, opaqueWorkspaceRoots = []) {
   runGit(input, input.shadowRoot, ["fetch", "origin", "--prune"], "fetch canonical workspace before reset");
   const remoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
   if (!remoteHead) return null;
   runGitResult(input, input.shadowRoot, ["rebase", "--abort"]);
   runGit(input, input.shadowRoot, ["reset", "--hard", `origin/${WORKSPACE_BRANCH}`], "reset workspace to canonical state");
   runGit(input, input.shadowRoot, ["clean", "-fd"], "clean reset workspace");
-  mirrorShadowWorkspaceToVisible(input);
+  if (!input.trigger.canonicalCheckoutOnly) mirrorShadowWorkspaceToVisible(input, opaqueWorkspaceRoots);
   return remoteHead;
 }
 function baseResult(input, startingHead) {
@@ -426,12 +1068,17 @@ function baseResult(input, startingHead) {
   };
 }
 async function synchronizeWorkspace(rawInput) {
-  const input = { ...rawInput, attemptId: rawInput.attemptId ?? crypto.randomUUID() };
+  let input = { ...rawInput, attemptId: rawInput.attemptId ?? crypto.randomUUID() };
   try {
+    input = { ...input, projects: workspaceProjectsForSync(input.projects, input.trigger) };
+    let mirroredGitlinkProjection = { entries: [], opaqueRoots: [] };
     ensureShadowWorkspace(input);
     const remoteHeadAtStart = revParse(input, `origin/${WORKSPACE_BRANCH}`);
     const result = baseResult(input, remoteHeadAtStart);
     if (input.resetToCanonical) {
+      if (input.trigger.canonicalCheckoutOnly) {
+        throw new Error("A canonical-checkout-only synchronization cannot reset the authoritative resolver checkout");
+      }
       const publishedHead = resetShadowToRemote(input);
       return {
         ...result,
@@ -441,29 +1088,53 @@ async function synchronizeWorkspace(rawInput) {
         gitStatus: gitStatus(input)
       };
     }
+    if (!input.skipVisibleMirror) resetUncommittedShadowSnapshot(input);
+    restoreUnscopedCanonicalCheckoutSubtrees(input);
     if (!input.skipVisibleMirror) {
       const newCheckoutKeys = new Set((input.newVisibleCheckouts ?? []).map((target) => `${target.projectId}\0${target.branchName}`));
-      mirrorVisibleWorkspaceToShadow(input, newCheckoutKeys);
-      reconcileNewVisibleCheckouts(input);
+      mirroredGitlinkProjection = mirrorVisibleWorkspaceToShadow(input, newCheckoutKeys);
+      fastForwardCleanShadowForNewCheckouts(input);
+      mergeGitlinkProjection(mirroredGitlinkProjection, reconcileNewVisibleCheckouts(input));
+      mirroredGitlinkProjection.opaqueRoots = [...new Set(mirroredGitlinkProjection.opaqueRoots)].sort();
     }
-    runGit(input, input.shadowRoot, ["add", "-A"], "stage workspace changes");
-    const paths = stagedPaths(input);
-    const diffSizeBytes = await stagedDiffSizeBytes(input);
+    const stagePathspecs = mirroredGitlinkProjection.opaqueRoots.flatMap((root) => [`:(exclude,literal)${root}`]);
+    runGit(input, input.shadowRoot, ["add", "-A", "--", ".", ...stagePathspecs], "stage workspace changes");
+    forceStageCanonicalCheckoutFiles(input, mirroredGitlinkProjection.entries, mirroredGitlinkProjection.opaqueRoots);
+    const sampledCanonicalCheckoutTreeHash = sampleCanonicalCheckoutTree(input);
+    const stagedWorkingPaths = stagedPaths(input);
+    const baseRevision = candidateBaseRevision(input);
+    const paths = stagedPaths(input, baseRevision);
+    const diffSizeBytes = await stagedDiffSizeBytes(input, baseRevision);
     const statusBeforeCommit = reportedStatus(gitStatus(input));
     const observed = {
       ...result,
       diffSizeBytes,
       gitStatus: statusBeforeCommit,
       affectedPaths: reportedPaths(paths),
-      affectedProjects: affectedProjects(paths)
+      affectedProjects: affectedProjects(paths),
+      ...sampledCanonicalCheckoutTreeHash ? { sampledCanonicalCheckoutTreeHash } : {}
     };
-    if (paths.length > 0 && diffSizeBytes > MAX_WORKSPACE_SYNC_DIFF_BYTES && !input.confirmedLargeDiff) {
-      return { ...observed, outcome: "large_diff_blocked" };
+    const destructiveReductions = destructiveCheckoutReductions(input, baseRevision);
+    if (destructiveReductions.length > 0 && !input.confirmedLargeDiff) {
+      const summary = destructiveReductions.map(({ root, trackedBefore, trackedAfter }) => `${root} (${trackedBefore} -> ${trackedAfter} tracked files)`).join(", ");
+      return {
+        ...observed,
+        outcome: "large_diff_blocked",
+        error: `Workspace safety guard blocked a destructive checkout reduction: ${summary}`
+      };
+    }
+    if (paths.length > 0 && diffSizeBytes > MAX_WORKSPACE_SYNC_DIFF_BYTES && !input.confirmedLargeDiff && !input.trigger.canonicalCheckoutOnly) {
+      return {
+        ...observed,
+        outcome: "large_diff_blocked",
+        error: `Workspace safety guard blocked a ${diffSizeBytes}-byte diff above the ${MAX_WORKSPACE_SYNC_DIFF_BYTES}-byte automatic publication limit.`
+      };
     }
-    if (paths.length > 0) {
+    if (stagedWorkingPaths.length > 0) {
       runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit workspace changes");
     }
     const candidateHead = revParse(input, "HEAD");
+    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) {
@@ -472,7 +1143,8 @@ async function synchronizeWorkspace(rawInput) {
       if (currentRemoteHead && localHead !== currentRemoteHead) {
         runGit(input, input.shadowRoot, ["reset", "--hard", `origin/${WORKSPACE_BRANCH}`], "update workspace from canonical state");
         runGit(input, input.shadowRoot, ["clean", "-fd"], "clean updated workspace");
-        mirrorShadowWorkspaceToVisible(input);
+        assertPublishedCanonicalCheckoutTree(input, currentRemoteHead, sampledCanonicalCheckoutTreeHash);
+        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
         return {
           ...observed,
           outcome: "updated",
@@ -481,7 +1153,13 @@ async function synchronizeWorkspace(rawInput) {
           gitStatus: gitStatus(input)
         };
       }
-      if (input.skipVisibleMirror) mirrorShadowWorkspaceToVisible(input);
+      const authoritativeHead = currentRemoteHead ?? localHead;
+      if (authoritativeHead) {
+        assertPublishedCanonicalCheckoutTree(input, authoritativeHead, sampledCanonicalCheckoutTreeHash);
+      }
+      if (input.skipVisibleMirror) {
+        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
+      }
       return {
         ...observed,
         outcome: "no_change",
@@ -495,7 +1173,8 @@ async function synchronizeWorkspace(rawInput) {
       const push = runGitResult(input, input.shadowRoot, ["push", "origin", `HEAD:refs/heads/${WORKSPACE_BRANCH}`]);
       if (push.exitCode === 0) {
         const publishedHead = revParse(input, "HEAD") ?? candidateHead;
-        mirrorShadowWorkspaceToVisible(input);
+        if (publishedHead) assertPublishedCanonicalCheckoutTree(input, publishedHead, sampledCanonicalCheckoutTreeHash);
+        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
         return {
           ...observed,
           outcome: "published",
@@ -521,7 +1200,7 @@ async function synchronizeWorkspace(rawInput) {
       if (rebase.exitCode !== 0) {
         const conflicted = runGitResult(input, input.shadowRoot, ["diff", "--name-only", "--diff-filter=U", "-z"]);
         const discardedPaths = reportedPaths([.../* @__PURE__ */ new Set([...paths, ...conflicted.stdout.split("\0").filter(Boolean)])].sort());
-        const publishedHead = resetShadowToRemote(input);
+        const publishedHead = resetShadowToRemote(input, mirroredGitlinkProjection.opaqueRoots);
         return {
           ...observed,
           outcome: "conflict_reset",
@@ -533,6 +1212,8 @@ async function synchronizeWorkspace(rawInput) {
           gitStatus: gitStatus(input)
         };
       }
+      assertPublishedCanonicalCheckoutTree(input, "HEAD", sampledCanonicalCheckoutTreeHash);
+      assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, "HEAD");
     }
     return {
       ...observed,
@@ -551,10 +1232,27 @@ async function synchronizeWorkspace(rawInput) {
     };
   }
 }
-function calculateWorkspaceDiffFingerprint(input) {
+function calculateWorkspaceDiffFingerprint(rawInput) {
+  const input = {
+    ...rawInput,
+    projects: workspaceProjectsForSync(rawInput.projects, rawInput.trigger)
+  };
   ensureShadowWorkspace(input);
-  if (!input.skipVisibleMirror) mirrorVisibleWorkspaceToShadow(input);
-  runGit(input, input.shadowRoot, ["add", "-A"], "stage workspace fingerprint");
+  let gitlinkProjection = { entries: [], opaqueRoots: [] };
+  if (!input.skipVisibleMirror) {
+    resetUncommittedShadowSnapshot(input);
+    restoreUnscopedCanonicalCheckoutSubtrees(input);
+    gitlinkProjection = mirrorVisibleWorkspaceToShadow(input);
+  } else {
+    restoreUnscopedCanonicalCheckoutSubtrees(input);
+  }
+  runGit(
+    input,
+    input.shadowRoot,
+    ["add", "-A", "--", ".", ...gitlinkProjection.opaqueRoots.map((root) => `:(exclude,literal)${root}`)],
+    "stage workspace fingerprint"
+  );
+  forceStageCanonicalCheckoutFiles(input, gitlinkProjection.entries, gitlinkProjection.opaqueRoots);
   const stagedTree = runGit(input, input.shadowRoot, ["write-tree"], "write workspace fingerprint tree");
   const headTree = revParse(input, "HEAD^{tree}");
   const localHead = revParse(input, "HEAD");
@@ -566,27 +1264,25 @@ function calculateWorkspaceDiffFingerprint(input) {
 }
 class WorkspaceSyncSingleFlight {
   queue = Promise.resolve();
-  run(input) {
-    const queued = this.queue.then(
-      () => synchronizeWorkspace(input),
-      () => synchronizeWorkspace(input)
-    );
+  enqueue(task) {
+    const queued = this.queue.then(task, task);
     this.queue = queued.then(
       () => void 0,
       () => void 0
     );
     return queued;
   }
+  run(input) {
+    return this.enqueue(() => synchronizeWorkspace(input));
+  }
+  runPrepared(prepare) {
+    return this.enqueue(() => synchronizeWorkspace(prepare()));
+  }
   fingerprint(input) {
-    const queued = this.queue.then(
-      () => calculateWorkspaceDiffFingerprint(input),
-      () => calculateWorkspaceDiffFingerprint(input)
-    );
-    this.queue = queued.then(
-      () => void 0,
-      () => void 0
-    );
-    return queued;
+    return this.enqueue(() => calculateWorkspaceDiffFingerprint(input));
+  }
+  fingerprintPrepared(prepare) {
+    return this.enqueue(() => calculateWorkspaceDiffFingerprint(prepare()));
   }
   afterCurrent() {
     return this.queue;
@@ -597,6 +1293,7 @@ export {
   WORKSPACE_BRANCH,
   WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
   WorkspaceSyncSingleFlight,
+  assertCanonicalCheckoutIndexMatchesWorktree,
   calculateWorkspaceDiffFingerprint,
   encodeWorkspaceBranch,
   mirrorShadowWorkspaceToVisible,
@@ -604,5 +1301,6 @@ export {
   synchronizeWorkspace,
   visibleProjectBranchPath,
   workspacePlansRelativePath,
-  workspaceProjectBranchRelativePath
+  workspaceProjectBranchRelativePath,
+  workspaceProjectsForSync
 };