@ricsam/r5d-worker 0.0.99 → 0.0.101

package/dist/cjs/main.cjs

@@ -97,9 +97,35 @@ function workerServerHeartbeatAction(input) {
   if (input.watchdogSweepDelayed || input.probeElapsedMs === void 0) return "start_probe";
   return input.probeElapsedMs >= input.timeoutMs ? "terminate" : "wait";
 }
+const WORKSPACE_HYDRATION_LEASE_OPERATION_PREFIX = "hydration:";
+function createWorkspaceHydrationLeaseHooks(send, options = {}) {
+  const yieldToEventLoop = options.yieldToEventLoop ?? (() => new Promise((resolve) => setImmediate(resolve)));
+  const log = options.log ?? ((line) => process.stdout.write(`${line}
+`));
+  const now = options.now ?? (() => performance.now());
+  const operationId = (context) => `${WORKSPACE_HYDRATION_LEASE_OPERATION_PREFIX}${context.transactionId}`;
+  const startedAtMs = /* @__PURE__ */ new Map();
+  return {
+    async beforeTransaction(context) {
+      send({ type: "heartbeat_lease", operationId: operationId(context), kind: "hydration", active: true });
+      startedAtMs.set(context.transactionId, now());
+      log(`[r5d-worker] hydrating ${context.mountIds.length} workspace mount(s) under hydration lease ${context.transactionId}`);
+      await yieldToEventLoop();
+    },
+    afterTransaction(context) {
+      const startedAt = startedAtMs.get(context.transactionId);
+      startedAtMs.delete(context.transactionId);
+      send({ type: "heartbeat_lease", operationId: operationId(context), kind: "hydration", active: false });
+      log(
+        `[r5d-worker] released hydration lease ${context.transactionId} after ${startedAt === void 0 ? "?" : Math.round(now() - startedAt)}ms`
+      );
+    }
+  };
+}
 const workerLifecycleTestHarness = {
   boundedWorkerLifecycleProgress,
-  workerServerHeartbeatAction
+  workerServerHeartbeatAction,
+  createWorkspaceHydrationLeaseHooks
 };
 class ProjectWorkspaceConfigurationDeferredError extends Error {
 }
@@ -4370,6 +4396,7 @@ async function startWorker(options) {
       error: error instanceof Error ? error.message : String(error)
     };
   };
+  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks((message) => sendWorkerMessageFromCurrentSource(ws, message));
   const performWorkspaceSync = async (input) => {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
@@ -4392,7 +4419,8 @@ async function startWorker(options) {
         credentialHelper: workspaceCredentialHelper,
         credentialUsername: workspaceCredentialUsername,
         gitIdentity: workspaceGitIdentity,
-        mounts: configuredMounts
+        mounts: configuredMounts,
+        hydrationHooks: workspaceHydrationTransactionHooks
       });
       await applyObservedProjectHeadsAfterInboundWorkspace(observedProjectHeads2, reset.activeMountIds, true);
       return {
@@ -4446,7 +4474,8 @@ async function startWorker(options) {
       assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : async ({ activeMountIds, publishedHead }) => {
         await pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, inboundMoveMountIds);
-      }
+      },
+      hydrationHooks: workspaceHydrationTransactionHooks
     });
     input.assertStillAdmitted?.();
     if (result.initialPublicationMountIds && result.initialPublicationMountIds.length > 0) {
@@ -5040,7 +5069,10 @@ async function startWorker(options) {
           sourcePath: recoverySourceOverrides.get(mount.id) ?? mount.sourcePath,
           busy: mount.busyForRecovery ?? mount.busy
         }));
-        await (0, import_workspace_git_sync.recoverWorkspaceGitHydration)(workspaceShadowRoot, recoveryMounts, { preserveStaleBases: true });
+        await (0, import_workspace_git_sync.recoverWorkspaceGitHydration)(workspaceShadowRoot, recoveryMounts, {
+          preserveStaleBases: true,
+          hydrationHooks: workspaceHydrationTransactionHooks
+        });
         for (const project of message.projects) {
           for (const { branchName } of project.preserveOnlyBranches) {
             if (stillPendingCreatedBranches.has((0, import_workspace_automatic_sync_policy.pendingCreatedBranchKey)(project.projectId, branchName))) {
@@ -5084,7 +5116,7 @@ async function startWorker(options) {
           // layouts can be marked ready. No process can resolve an unready
           // target, and preserving the fetched outer tree here prevents clean
           // checkout initialization from erasing synchronized dirt.
-          { ignoreBusy: true }
+          { ignoreBusy: true, hydrationHooks: workspaceHydrationTransactionHooks }
         );
         await ensureConfiguredProjects((progress) => {
           sendLifecycleProgress({ phase: "configuring", operationId: configurationOperationId, ...progress });

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.99",
+  "version": "0.0.101",
   "type": "commonjs"
 }

package/dist/cjs/working-tree-mirror.cjs

@@ -44,6 +44,16 @@ var import_node_crypto = require("node:crypto");
 var import_git_process_environment = require("./git-process-environment.cjs");
 const HFS_IGNORED_CODE_POINTS = /[\u200c-\u200f\u202a-\u202e\u206a-\u206f\ufeff]/gu;
 const MIRROR_TEMPORARY_FILE_PREFIX = ".r5d-working-tree-mirror-";
+const OBJECT_ID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u;
+const GITLINK_STALE_HEADS_FILE = "gitlink-heads.json";
+const NON_RECURSIVE_GIT_CONFIG = [
+  "-c",
+  "submodule.recurse=false",
+  "-c",
+  "fetch.recurseSubmodules=false",
+  "-c",
+  "push.recurseSubmodules=false"
+];
 function isPortableGitMetadataSegment(segment) {
   const hfsFolded = segment.replace(HFS_IGNORED_CODE_POINTS, "").toLowerCase();
   if (hfsFolded === ".git") return true;
@@ -119,42 +129,145 @@ function inspectDirectoryRoot(root, options) {
   }
   return true;
 }
-function gitEligibleRoots(root) {
-  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: root,
-      stdout: "pipe",
-      stderr: "pipe",
-      env: (0, import_git_process_environment.workerGitProcessEnvironment)()
-    }
-  );
+function lstatIfExists(targetPath) {
+  try {
+    return import_node_fs.default.lstatSync(targetPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function nulRecords(content) {
+  const records = [];
+  let start = 0;
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] !== 0) continue;
+    if (index > start) records.push(content.subarray(start, index));
+    start = index + 1;
+  }
+  if (start < content.length) records.push(content.subarray(start));
+  return records;
+}
+function gitOutput(cwd, args, action, options = {}) {
+  const result = Bun.spawnSync(["git", ...NON_RECURSIVE_GIT_CONFIG, ...args], {
+    cwd,
+    ...options.stdin ? { stdin: options.stdin } : {},
+    stdout: "pipe",
+    stderr: "pipe",
+    env: options.environment ?? (0, import_git_process_environment.workerGitProcessEnvironment)()
+  });
   if (result.exitCode !== 0) {
-    throw new Error(`Inspect Git working tree: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
+    throw new Error(`${action}: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
   }
-  return result.stdout.toString().split("\0").flatMap((entry) => {
-    const normalized = normalizeRelativePath(entry);
-    return normalized ? [normalized] : [];
-  }).sort();
+  return Buffer.from(result.stdout);
 }
-function addEntry(entries, root, relativePath, recurseDirectories) {
+function listGitCheckout(root) {
+  const output = gitOutput(
+    root,
+    ["ls-files", "-z", "-t", "--stage", "--cached", "--others", "--exclude-standard", "--", "."],
+    "Inspect Git working tree"
+  );
+  const roots = /* @__PURE__ */ new Map();
+  const indexRecords = [];
+  for (const record of nulRecords(output)) {
+    const text = record.toString();
+    const other = /^\? (.*)$/su.exec(text);
+    if (other) {
+      const normalized2 = normalizeRelativePath(other[1]);
+      if (normalized2 && !roots.has(normalized2)) roots.set(normalized2, other[1].endsWith("/"));
+      continue;
+    }
+    const staged = /^[A-Z] ([0-7]{6}) ([0-9a-f]{40,64}) ([0-3])\t(.*)$/su.exec(text);
+    if (!staged) continue;
+    const normalized = normalizeRelativePath(staged[4]);
+    if (!normalized) continue;
+    indexRecords.push({ mode: staged[1], objectId: staged[2], stage: Number(staged[3]), relativePath: normalized });
+    if (!roots.has(normalized)) roots.set(normalized, false);
+  }
+  return {
+    roots: [...roots].map(([relativePath, nestedRepository]) => ({ relativePath, nestedRepository })).sort((left, right) => left.relativePath < right.relativePath ? -1 : left.relativePath > right.relativePath ? 1 : 0),
+    indexRecords
+  };
+}
+function populatedCheckoutHead(root, absolutePath) {
+  if (!lstatIfExists(import_node_path.default.join(absolutePath, ".git"))) return null;
+  const result = Bun.spawnSync(["git", ...NON_RECURSIVE_GIT_CONFIG, "rev-parse", "--verify", "HEAD^{commit}"], {
+    cwd: absolutePath,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...(0, import_git_process_environment.workerGitProcessEnvironment)(), GIT_CEILING_DIRECTORIES: root }
+  });
+  if (result.exitCode !== 0) return null;
+  const head = result.stdout.toString().trim();
+  return OBJECT_ID_PATTERN.test(head) ? head : null;
+}
+function checkoutGitDirectory(root) {
+  const dotGit = import_node_path.default.join(root, ".git");
+  const status = lstatIfExists(dotGit);
+  if (!status) return null;
+  if (status.isDirectory()) return dotGit;
+  if (!status.isFile()) return null;
+  const match = /^gitdir:[ \t]*(.+?)\s*$/u.exec(import_node_fs.default.readFileSync(dotGit, "utf8").split(/\r?\n/u)[0] ?? "");
+  return match ? import_node_path.default.resolve(root, match[1]) : null;
+}
+function gitlinkStaleHeadsPath(root) {
+  const gitDirectory = checkoutGitDirectory(root);
+  return gitDirectory ? import_node_path.default.join(gitDirectory, "r5d", GITLINK_STALE_HEADS_FILE) : null;
+}
+function readGitlinkStaleHeads(root) {
+  const heads = /* @__PURE__ */ new Map();
+  const markerPath = gitlinkStaleHeadsPath(root);
+  if (!markerPath || !lstatIfExists(markerPath)?.isFile()) return heads;
+  let parsed;
+  try {
+    parsed = JSON.parse(import_node_fs.default.readFileSync(markerPath, "utf8"));
+  } catch {
+    return heads;
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.version !== 1) return heads;
+  const recorded = parsed.heads;
+  if (!recorded || typeof recorded !== "object") return heads;
+  for (const [relativePath, objectId] of Object.entries(recorded)) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (normalized && typeof objectId === "string" && OBJECT_ID_PATTERN.test(objectId)) heads.set(normalized, objectId);
+  }
+  return heads;
+}
+function writeGitlinkStaleHeads(root, heads) {
+  const markerPath = gitlinkStaleHeadsPath(root);
+  if (!markerPath) return;
+  const directory = import_node_path.default.dirname(markerPath);
+  if (heads.size === 0) {
+    if (!lstatIfExists(markerPath)) return;
+    import_node_fs.default.rmSync(markerPath, { force: true });
+    fsyncPath(directory, import_node_fs.default.constants.O_RDONLY);
+    return;
+  }
+  const directoryStatus = lstatIfExists(directory);
+  if (!directoryStatus) import_node_fs.default.mkdirSync(directory, { mode: 448 });
+  else if (!directoryStatus.isDirectory() || directoryStatus.isSymbolicLink()) {
+    throw new Error(`Checkout private state is not a regular directory: ${directory}`);
+  }
+  const temporaryPath = import_node_path.default.join(directory, `.${GITLINK_STALE_HEADS_FILE}.${(0, import_node_crypto.randomUUID)()}.tmp`);
+  const descriptor = import_node_fs.default.openSync(temporaryPath, import_node_fs.default.constants.O_WRONLY | import_node_fs.default.constants.O_CREAT | import_node_fs.default.constants.O_EXCL, 384);
+  try {
+    import_node_fs.default.writeFileSync(descriptor, `${JSON.stringify({ version: 1, heads: Object.fromEntries([...heads].sort()) })}
+`);
+    import_node_fs.default.fsyncSync(descriptor);
+  } finally {
+    import_node_fs.default.closeSync(descriptor);
+  }
+  import_node_fs.default.renameSync(temporaryPath, markerPath);
+  fsyncPath(directory, import_node_fs.default.constants.O_RDONLY);
+}
+function addEntry(entries, root, relativePath, recurseDirectories, gitlinks) {
   const normalized = normalizeRelativePath(relativePath);
   if (!normalized || entries.has(normalized)) return;
+  const gitlink = gitlinks?.get(normalized);
+  if (gitlink !== void 0) {
+    entries.set(normalized, { kind: "gitlink", objectId: gitlink });
+    return;
+  }
   const inspected = inspectRelativePathWithoutFollowingAncestors(root, normalized);
   if (inspected.kind !== "entry") return;
   const { absolutePath, stat } = inspected;
@@ -173,7 +286,7 @@ function addEntry(entries, root, relativePath, recurseDirectories) {
   entries.set(normalized, { kind: "directory", mode: stat.mode });
   if (!recurseDirectories) return;
   for (const child of import_node_fs.default.readdirSync(absolutePath).sort()) {
-    addEntry(entries, root, import_node_path.default.posix.join(normalized, child), true);
+    addEntry(entries, root, import_node_path.default.posix.join(normalized, child), true, gitlinks);
   }
 }
 function addParentDirectories(entries, root) {
@@ -191,57 +304,59 @@ function addParentDirectories(entries, root) {
     }
   }
 }
-function gitlinkPaths(root) {
-  const result = Bun.spawnSync(
-    [
-      "git",
-      "-c",
-      "submodule.recurse=false",
-      "-c",
-      "fetch.recurseSubmodules=false",
-      "-c",
-      "push.recurseSubmodules=false",
-      "ls-files",
-      "-z",
-      "--stage",
-      "--",
-      "."
-    ],
-    {
-      cwd: root,
-      stdout: "pipe",
-      stderr: "pipe",
-      env: (0, import_git_process_environment.workerGitProcessEnvironment)()
+function inspectGitWorkingTree(root) {
+  const entries = /* @__PURE__ */ new Map();
+  const listing = listGitCheckout(root);
+  const indexGitlinks = /* @__PURE__ */ new Map();
+  for (const record of listing.indexRecords) {
+    if (record.mode === "160000" && !indexGitlinks.has(record.relativePath)) indexGitlinks.set(record.relativePath, record.objectId);
+  }
+  const submodules = /* @__PURE__ */ new Map();
+  let staleHeads = null;
+  for (const { relativePath, nestedRepository } of listing.roots) {
+    if (entries.has(relativePath)) continue;
+    const indexObjectId = indexGitlinks.get(relativePath);
+    if (indexObjectId === void 0 && !nestedRepository) {
+      addEntry(entries, root, relativePath, true);
+      continue;
     }
-  );
-  if (result.exitCode !== 0) {
-    throw new Error(`Inspect Git index gitlinks: ${result.stderr.toString().trim() || `git exited ${result.exitCode}`}`);
-  }
-  const gitlinks = /* @__PURE__ */ new Set();
-  for (const record of result.stdout.toString().split("\0")) {
-    const match = /^160000 [0-9a-f]+ [0-3]\t(.+)$/su.exec(record);
-    if (!match) continue;
-    const normalized = normalizeRelativePath(match[1]);
-    if (normalized) gitlinks.add(normalized);
+    const inspected = inspectRelativePathWithoutFollowingAncestors(root, relativePath);
+    if (inspected.kind !== "entry") continue;
+    if (!inspected.stat.isDirectory() || inspected.stat.isSymbolicLink()) {
+      addEntry(entries, root, relativePath, true);
+      continue;
+    }
+    const head = populatedCheckoutHead(root, inspected.absolutePath);
+    submodules.set(relativePath, head);
+    let objectId = indexObjectId ?? head;
+    if (head && indexObjectId !== void 0 && head !== indexObjectId) {
+      staleHeads ??= readGitlinkStaleHeads(root);
+      objectId = staleHeads.get(relativePath) === head ? indexObjectId : head;
+    }
+    if (objectId) entries.set(relativePath, { kind: "gitlink", objectId });
   }
-  return gitlinks;
+  addParentDirectories(entries, root);
+  return { entries, indexRecords: listing.indexRecords, submodules };
 }
-function directoryIsEmpty(root, relativePath) {
-  const inspected = inspectRelativePathWithoutFollowingAncestors(root, relativePath);
-  return inspected.kind === "entry" && inspected.stat.isDirectory() && import_node_fs.default.readdirSync(inspected.absolutePath).length === 0;
+function normalizedGitlinks(gitlinks) {
+  const normalized = /* @__PURE__ */ new Map();
+  for (const [relativePath, objectId] of gitlinks ?? []) {
+    const relative = normalizeRelativePath(relativePath);
+    if (!relative) throw new Error(`Invalid working-tree gitlink path: ${relativePath}`);
+    if (!OBJECT_ID_PATTERN.test(objectId)) throw new Error(`Invalid working-tree gitlink object id for ${relativePath}: ${objectId}`);
+    normalized.set(relative, objectId);
+  }
+  return normalized;
 }
 function inspectWorkingTree(root, mode, options = {}) {
   const entries = /* @__PURE__ */ new Map();
   root = import_node_path.default.resolve(root);
   if (!inspectDirectoryRoot(root, { allowMissing: true, label: "Working-tree root" })) return entries;
-  if (mode === "all") {
-    for (const child of import_node_fs.default.readdirSync(root).sort()) addEntry(entries, root, child, true);
-  } else {
-    const omittedGitlinks = options.omitUnpopulatedGitlinks ? gitlinkPaths(root) : null;
-    for (const relativePath of gitEligibleRoots(root)) {
-      if (omittedGitlinks?.has(relativePath) && directoryIsEmpty(root, relativePath)) continue;
-      addEntry(entries, root, relativePath, true);
-    }
+  if (mode === "git") return inspectGitWorkingTree(root).entries;
+  const gitlinks = normalizedGitlinks(options.gitlinks);
+  for (const child of import_node_fs.default.readdirSync(root).sort()) addEntry(entries, root, child, true, gitlinks);
+  for (const [relativePath, objectId] of gitlinks) {
+    if (entries.get(relativePath)?.kind !== "gitlink") entries.set(relativePath, { kind: "gitlink", objectId });
   }
   addParentDirectories(entries, root);
   return entries;
@@ -391,6 +506,9 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
     }
     return;
   }
+  if (entry.kind === "gitlink") {
+    throw new Error(`Working-tree gitlink cannot be copied as content: ${relativePath}`);
+  }
   if (!source.stat.isFile() || source.stat.isSymbolicLink() || source.stat.size !== entry.size) {
     throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
   }
@@ -404,6 +522,110 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
     copyRegularFile(sourcePath, targetPath, entry, durability);
   }
 }
+function inspectMirrorTarget(targetRoot, deletionMode) {
+  if (deletionMode !== "git") return { existing: inspectWorkingTree(targetRoot, "all"), git: null };
+  const inspection = inspectGitWorkingTree(targetRoot);
+  const occupied = /* @__PURE__ */ new Set();
+  for (const relativePath of inspection.submodules.keys()) {
+    const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (inspected.kind === "entry" && inspected.stat.isDirectory() && import_node_fs.default.readdirSync(inspected.absolutePath).length > 0) {
+      occupied.add(relativePath);
+    }
+  }
+  return { existing: inspection.entries, git: { indexRecords: inspection.indexRecords, submodules: inspection.submodules, occupied } };
+}
+function shieldedDesiredPaths(desired, git) {
+  const shielded = /* @__PURE__ */ new Set();
+  if (git.submodules.size === 0) return shielded;
+  const roots = new Set(git.submodules.keys());
+  for (const [relativePath, entry] of desired) {
+    if (hasAncestorIn(relativePath, roots)) {
+      shielded.add(relativePath);
+      continue;
+    }
+    if (!roots.has(relativePath) || entry.kind === "gitlink") continue;
+    if (entry.kind === "directory" || git.occupied.has(relativePath)) shielded.add(relativePath);
+  }
+  return shielded;
+}
+function directoryShieldsSubmodule(relativePath, entry, git) {
+  if (!git || entry.kind !== "directory") return false;
+  const prefix = `${relativePath}/`;
+  for (const root of git.submodules.keys()) if (root.startsWith(prefix)) return true;
+  return false;
+}
+function planIndexChanges(desired, shielded, git) {
+  const removed = [];
+  const written = [];
+  const desiredGitlinks = /* @__PURE__ */ new Map();
+  for (const [relativePath, entry] of desired) {
+    if (entry.kind === "gitlink" && !shielded.has(relativePath)) desiredGitlinks.set(relativePath, entry.objectId);
+  }
+  const desiredGitlinkRoots = new Set(desiredGitlinks.keys());
+  const currentGitlinks = /* @__PURE__ */ new Map();
+  for (const record of git.indexRecords) {
+    const desiredObjectId = desiredGitlinks.get(record.relativePath);
+    if (record.mode === "160000") {
+      if (record.stage === 0) currentGitlinks.set(record.relativePath, record.objectId);
+      if (desiredObjectId !== void 0) {
+        if (desiredObjectId !== record.objectId) removed.push(record);
+        continue;
+      }
+      const desiredEntry = desired.get(record.relativePath);
+      if (desiredEntry?.kind !== "directory" && desiredEntry?.kind !== "gitlink" && !git.occupied.has(record.relativePath)) {
+        removed.push(record);
+      }
+      continue;
+    }
+    if (desiredObjectId !== void 0 || hasAncestorIn(record.relativePath, desiredGitlinkRoots)) removed.push(record);
+  }
+  for (const [relativePath, objectId] of desiredGitlinks) {
+    if (currentGitlinks.get(relativePath) !== objectId) written.push({ relativePath, objectId });
+  }
+  return { removed, written };
+}
+function indexInfoRecord(record) {
+  const stage = record.stage === 0 ? "" : ` ${record.stage}`;
+  return Buffer.concat([Buffer.from(`${record.mode} ${record.objectId}${stage}	`), Buffer.from(record.relativePath), Buffer.from([0])]);
+}
+function updateIndex(targetRoot, changes) {
+  if (changes.drop.length === 0 && changes.put.length === 0) return;
+  const feed = Buffer.concat([
+    ...changes.drop.map(
+      ({ relativePath, objectId }) => indexInfoRecord({ mode: "0", objectId: "0".repeat(objectId.length), stage: 0, relativePath })
+    ),
+    ...changes.put.map(indexInfoRecord)
+  ]);
+  gitOutput(
+    targetRoot,
+    ["-c", "core.fsync=index", "-c", "core.fsyncMethod=fsync", "update-index", "-z", "--index-info"],
+    "Update Git working-tree index",
+    { stdin: feed }
+  );
+  const gitDirectory = checkoutGitDirectory(targetRoot);
+  if (!gitDirectory) return;
+  const indexPath = import_node_path.default.join(gitDirectory, "index");
+  if (lstatIfExists(indexPath)?.isFile()) fsyncPath(indexPath, import_node_fs.default.constants.O_RDONLY | import_node_fs.default.constants.O_NOFOLLOW);
+  fsyncPath(gitDirectory, import_node_fs.default.constants.O_RDONLY);
+}
+function recordGitlinkStaleHeads(targetRoot, desired, shielded, git) {
+  const heads = readGitlinkStaleHeads(targetRoot);
+  let changed = false;
+  for (const [relativePath, head] of git.submodules) {
+    const entry = desired.get(relativePath);
+    const next = entry?.kind === "gitlink" && !shielded.has(relativePath) && head && head !== entry.objectId ? head : null;
+    if ((heads.get(relativePath) ?? null) === next) continue;
+    if (next) heads.set(relativePath, next);
+    else heads.delete(relativePath);
+    changed = true;
+  }
+  for (const relativePath of [...heads.keys()]) {
+    if (git.submodules.has(relativePath)) continue;
+    heads.delete(relativePath);
+    changed = true;
+  }
+  if (changed) writeGitlinkStaleHeads(targetRoot, heads);
+}
 function mirrorWorkingTree(input) {
   const sourceRoot = import_node_path.default.resolve(input.sourceRoot);
   const targetRoot = import_node_path.default.resolve(input.targetRoot);
@@ -412,19 +634,34 @@ function mirrorWorkingTree(input) {
     import_node_fs.default.mkdirSync(targetRoot, { recursive: true });
   }
   inspectDirectoryRoot(targetRoot, { allowMissing: false, label: "Working-tree target root" });
-  const desired = inspectWorkingTree(sourceRoot, input.sourceMode);
-  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all", {
-    omitUnpopulatedGitlinks: input.deletionMode === "git"
-  });
-  for (const relativePath of [...existing.keys()].sort((left, right) => right.split("/").length - left.split("/").length)) {
-    if (!desired.has(relativePath)) removeEntry(targetRoot, relativePath);
-  }
-  for (const [relativePath, entry] of [...desired.entries()].sort(
-    ([left], [right]) => left.split("/").length - right.split("/").length || left.localeCompare(right)
-  )) {
+  const desired = inspectWorkingTree(sourceRoot, input.sourceMode, { gitlinks: input.sourceGitlinks });
+  const target = inspectMirrorTarget(targetRoot, input.deletionMode);
+  const shielded = target.git ? shieldedDesiredPaths(desired, target.git) : /* @__PURE__ */ new Set();
+  const index = target.git ? planIndexChanges(desired, shielded, target.git) : null;
+  for (const relativePath of [...target.existing.keys()].sort(deepestFirst)) {
+    if (desired.has(relativePath)) continue;
+    const entry = target.existing.get(relativePath);
+    if (entry.kind === "gitlink" || directoryShieldsSubmodule(relativePath, entry, target.git)) continue;
+    removeEntry(targetRoot, relativePath);
+  }
+  const gitlinks = [];
+  for (const [relativePath, entry] of [...desired.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+    if (shielded.has(relativePath)) continue;
+    if (entry.kind === "gitlink") {
+      ensureDirectory(targetRoot, relativePath, 493);
+      gitlinks.push({ relativePath, objectId: entry.objectId });
+      continue;
+    }
     copyEntry(sourceRoot, targetRoot, relativePath, entry, durability);
   }
-  return { paths: [...desired.keys()].filter((relativePath) => desired.get(relativePath)?.kind !== "directory").sort() };
+  if (index && target.git) {
+    updateIndex(targetRoot, { drop: index.removed, put: index.written.map((gitlink) => ({ mode: "160000", stage: 0, ...gitlink })) });
+    recordGitlinkStaleHeads(targetRoot, desired, shielded, target.git);
+  }
+  return {
+    paths: [...desired.keys()].filter((relativePath) => !shielded.has(relativePath) && desired.get(relativePath)?.kind !== "directory").sort(),
+    gitlinks
+  };
 }
 function normalizeWorkingTreeRelativePath(value) {
   return normalizeRelativePath(value);
@@ -464,23 +701,25 @@ function fsyncPath(targetPath, flags) {
 function planWorkingTreeMirror(input) {
   const sourceRoot = import_node_path.default.resolve(input.sourceRoot);
   const targetRoot = import_node_path.default.resolve(input.targetRoot);
-  const desired = inspectWorkingTree(sourceRoot, input.sourceMode);
-  const existing = inspectWorkingTree(targetRoot, input.deletionMode === "git" ? "git" : "all", {
-    omitUnpopulatedGitlinks: input.deletionMode === "git"
-  });
+  const inspectedDesired = inspectWorkingTree(sourceRoot, input.sourceMode, { gitlinks: input.sourceGitlinks });
+  const target = inspectMirrorTarget(targetRoot, input.deletionMode);
+  const shielded = target.git ? shieldedDesiredPaths(inspectedDesired, target.git) : /* @__PURE__ */ new Set();
+  const desired = new Map([...inspectedDesired].filter(([relativePath]) => !shielded.has(relativePath)));
   const replaced = /* @__PURE__ */ new Map();
   const absent = [];
-  for (const [relativePath, entry] of existing) {
-    if (!desired.has(relativePath)) replaced.set(relativePath, entry);
+  for (const [relativePath, entry] of target.existing) {
+    if (inspectedDesired.has(relativePath) || entry.kind === "gitlink") continue;
+    if (directoryShieldsSubmodule(relativePath, entry, target.git)) continue;
+    replaced.set(relativePath, entry);
   }
   for (const [relativePath, entry] of desired) {
-    const target = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
-    if (target.kind !== "entry") {
+    const targetEntry = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (targetEntry.kind !== "entry") {
       absent.push(relativePath);
       continue;
     }
-    const { absolutePath, stat } = target;
-    if (entry.kind === "directory") {
+    const { absolutePath, stat } = targetEntry;
+    if (entry.kind === "directory" || entry.kind === "gitlink") {
       if (stat.isDirectory()) continue;
     } else if (entry.kind === "symlink") {
       if (stat.isSymbolicLink() && import_node_fs.default.readlinkSync(absolutePath) === entry.target) continue;
@@ -500,7 +739,8 @@ function planWorkingTreeMirror(input) {
   return {
     desired,
     replaced,
-    absent: absent.filter((relativePath) => !hasAncestorIn(relativePath, replacedDirectories)).sort(shallowestFirst)
+    absent: absent.filter((relativePath) => !hasAncestorIn(relativePath, replacedDirectories)).sort(shallowestFirst),
+    index: target.git ? planIndexChanges(inspectedDesired, shielded, target.git) : { removed: [], written: [] }
   };
 }
 function captureWorkingTreeMirrorPlan(input) {
@@ -513,6 +753,7 @@ function captureWorkingTreeMirrorPlan(input) {
   }
   const trees = [];
   for (const [relativePath, entry] of [...input.plan.replaced.entries()].sort(([left], [right]) => shallowestFirst(left, right))) {
+    if (entry.kind === "gitlink") continue;
     if (entry.kind !== "directory") {
       copyEntry(targetRoot, snapshotRoot, relativePath, entry, durability);
       continue;
@@ -531,7 +772,12 @@ function captureWorkingTreeMirrorPlan(input) {
     });
     trees.push(relativePath);
   }
-  return { absent: [...input.plan.absent].sort(shallowestFirst), trees: trees.sort(shallowestFirst) };
+  const { index } = input.plan;
+  return {
+    absent: [...input.plan.absent].sort(shallowestFirst),
+    trees: trees.sort(shallowestFirst),
+    ...index.removed.length > 0 || index.written.length > 0 ? { index } : {}
+  };
 }
 function restoreWorkingTreeMirrorScope(input) {
   const snapshotRoot = import_node_path.default.resolve(input.snapshotRoot);
@@ -556,6 +802,7 @@ function restoreWorkingTreeMirrorScope(input) {
   const touched = /* @__PURE__ */ new Set();
   for (const relativePath of [...absent].sort(deepestFirst)) {
     const inspected = inspectRelativePathWithoutFollowingAncestors(targetRoot, relativePath);
+    if (inspected.kind === "entry" && inspected.stat.isDirectory() && lstatIfExists(import_node_path.default.join(inspected.absolutePath, ".git"))) continue;
     if (inspected.kind === "entry") import_node_fs.default.rmSync(inspected.absolutePath, { recursive: true, force: true });
     touched.add(relativePath);
   }
@@ -593,7 +840,7 @@ function restoreWorkingTreeMirrorScope(input) {
     if (current.kind === "entry" && !current.stat.isDirectory()) {
       import_node_fs.default.rmSync(current.absolutePath, { recursive: true, force: true });
     }
-    ensureDirectory(targetRoot, relativePath, entry.mode);
+    ensureDirectory(targetRoot, relativePath, entry.kind === "directory" ? entry.mode : 493);
     mirrorWorkingTree({
       sourceRoot: import_node_path.default.join(snapshotRoot, ...relativePath.split("/")),
       targetRoot: import_node_path.default.join(targetRoot, ...relativePath.split("/")),
@@ -601,6 +848,7 @@ function restoreWorkingTreeMirrorScope(input) {
       deletionMode: "all"
     });
   }
+  if (input.scope.index) updateIndex(targetRoot, { drop: input.scope.index.written, put: input.scope.index.removed });
   return { paths: [...touched].sort(shallowestFirst) };
 }
 function fsyncWorkingTreePaths(root, relativePaths) {