@ricsam/r5d-worker 0.0.79 → 0.0.81

package/README.md

@@ -7,7 +7,13 @@ r5d-worker start --label macos
 r5d-worker --version
 ```
 
-The worker uses the existing `r5dctl` config file and accepts `R5D_WORKER_TOKEN` or `R5D_API_KEY`. Project checkouts are managed under:
+Authorize the exact worker label before starting it:
+
+```sh
+r5dctl auth login --worker-label macos
+```
+
+The worker uses that label-bound credential from the existing `r5dctl` config file or `R5D_WORKER_TOKEN`. `R5D_API_KEY` remains an accepted legacy environment-variable name, but its value must still be the exact label-bound worker credential; a general API key or device credential cannot connect a worker. Project checkouts are managed under:
 
 ```text
 ~/.r5d/projects/<namespace>/<project>/<branch-name>

package/dist/cjs/main.cjs

@@ -629,7 +629,7 @@ function preparePlanEnvForShell(input) {
   import_node_fs.default.mkdirSync(plansDir, { recursive: true });
   return planEnv(input.planRoot, input.target, input.activePlanId);
 }
-async function verifyR5dctlAuth(baseUrl, token) {
+async function verifyR5dctlAuth(baseUrl, token, workerLabel) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
   try {
@@ -658,13 +658,16 @@ async function verifyR5dctlAuth(baseUrl, token) {
     throw new WorkerServerUnavailableError(`Server unavailable at ${baseUrl} (${response.status})${detail}`);
   }
   throw new Error(
-    `Authentication failed against ${baseUrl} (${response.status})${detail}. Run \`r5dctl auth login --base-url ${baseUrl}\` or pass --token/--api-key for this server.`
+    `Authentication failed against ${baseUrl} (${response.status})${detail}. Run \`r5dctl auth login --base-url ${baseUrl} --worker-label ${workerLabel}\` or pass that exact label-bound worker token.`
   );
 }
 function resolveCredentials(options, config) {
   const token = options.token ?? process.env.R5D_WORKER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
   if (!token) {
-    throw new Error("Authentication required. Run `r5dctl auth login` or set R5D_WORKER_TOKEN/R5D_API_KEY.");
+    const workerLabel = options.label ?? "<label>";
+    throw new Error(
+      `Authentication required. Run \`r5dctl auth login --worker-label ${workerLabel}\` or set R5D_WORKER_TOKEN to that label-bound token.`
+    );
   }
   return {
     baseUrl: normalizeBaseUrl(
@@ -3021,7 +3024,7 @@ async function startWorker(options) {
   process.stdout.write(`[r5d-worker] server: ${baseUrl}
 `);
   runGit(["--version"]);
-  await verifyR5dctlAuth(baseUrl, token);
+  await verifyR5dctlAuth(baseUrl, token, label);
   const initializedWorkspaceState = await workspaceSyncSingleFlight.runExclusive(() => {
     if (!startupProjectSnapshotRecoveryCompleted) {
       const snapshotRecovery = (0, import_project_worktrees.recoverStaleProjectWorktreeSnapshots)({

package/dist/cjs/package.json

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

package/dist/cjs/project-worktrees.cjs

@@ -389,6 +389,7 @@ function copyCheckoutTree(sourceRoot, targetRoot) {
     dereference: false,
     errorOnExist: true,
     force: false,
+    mode: import_node_fs.default.constants.COPYFILE_FICLONE,
     preserveTimestamps: true,
     verbatimSymlinks: true
   });
@@ -769,6 +770,7 @@ function reconcileLinkedLayout(input) {
   tryGit(primaryPath, ["worktree", "prune"]);
   fetchProjectHeads({ ...input, primaryPath });
   const mirrorHeads = /* @__PURE__ */ new Map();
+  const mutatedBranches = /* @__PURE__ */ new Set();
   for (const branch of input.branches) {
     const checkoutPath = branchPath(input.projectRoot, branch.branchName);
     const resolved = seedForBranch({
@@ -779,16 +781,22 @@ function reconcileLinkedLayout(input) {
     });
     mirrorHeads.set(branch.branchName, resolved.mirrorHead);
     if (branch.branchName === input.primaryBranchName || commonGitDirectory(checkoutPath) === commonGitDirectory(primaryPath)) {
+      const currentHead = git(checkoutPath, ["rev-parse", "HEAD"], `resolve linked worktree head ${branch.branchName}`);
+      if (currentHead === resolved.seed) continue;
+      input.beforeDestructiveMutation();
+      mutatedBranches.add(branch.branchName);
       preserveHead(checkoutPath);
       git(checkoutPath, ["reset", "--hard", resolved.seed], `anchor linked worktree ${branch.branchName}`);
       continue;
     }
+    input.beforeDestructiveMutation();
+    mutatedBranches.add(branch.branchName);
     import_node_fs.default.rmSync(checkoutPath, { recursive: true, force: true });
     git(primaryPath, ["branch", "-f", branch.branchName, resolved.seed], `anchor project branch ${branch.branchName}`);
     import_node_fs.default.mkdirSync(import_node_path.default.dirname(checkoutPath), { recursive: true });
     git(primaryPath, ["worktree", "add", "--force", checkoutPath, branch.branchName], `create linked worktree ${branch.branchName}`);
   }
-  return mirrorHeads;
+  return { mirrorHeads, mutatedBranches };
 }
 function aheadBehind(checkoutPath, branchName, primaryBranchName, defaultBranch) {
   const originBranchName = projectOriginBranchName({ branchName, primaryBranchName, defaultBranch });
@@ -805,7 +813,13 @@ function ensureProjectWorktrees(input) {
   if (!input.branches.some(({ branchName }) => branchName === input.primaryBranchName)) {
     throw new Error(`Primary project branch ${input.primaryBranchName} is missing from the workspace configuration`);
   }
-  const snapshot = snapshotBranchTrees(projectRoot, input.branches, input.snapshotRoot);
+  const snapshotStorageRoot = import_node_path.default.resolve(input.snapshotRoot ?? import_node_os.default.tmpdir());
+  assertNoOutstandingSnapshotForProject(snapshotStorageRoot, projectRoot);
+  let snapshot;
+  const ensureSnapshot = () => {
+    snapshot ??= snapshotBranchTrees(projectRoot, input.branches, snapshotStorageRoot);
+    return snapshot;
+  };
   try {
     import_node_fs.default.mkdirSync(projectRoot, { recursive: true });
     const linked = hasCompatibleLinkedProjectWorktreeLayout({
@@ -813,9 +827,27 @@ function ensureProjectWorktrees(input) {
       primaryBranchName: input.primaryBranchName,
       branches: input.branches
     });
-    const mirrorHeads = linked ? reconcileLinkedLayout({ ...input, projectRoot, defaultBranch }) : initializeLinkedLayout({ ...input, projectRoot, defaultBranch });
+    let mirrorHeads;
+    let mutatedBranches;
+    if (linked) {
+      ({ mirrorHeads, mutatedBranches } = reconcileLinkedLayout({
+        ...input,
+        projectRoot,
+        defaultBranch,
+        beforeDestructiveMutation: ensureSnapshot
+      }));
+    } else {
+      ensureSnapshot();
+      mirrorHeads = initializeLinkedLayout({ ...input, projectRoot, defaultBranch });
+      mutatedBranches = new Set(input.branches.map(({ branchName }) => branchName));
+    }
+    const preparedSnapshot = snapshot;
+    if (mutatedBranches.size > 0 && !preparedSnapshot) {
+      throw new Error("Project worktree mutation started without a prepared recovery snapshot");
+    }
     for (const branch of input.branches) {
-      const snapshotPath = snapshot.paths.get(branch.branchName);
+      if (!mutatedBranches.has(branch.branchName)) continue;
+      const snapshotPath = preparedSnapshot?.paths.get(branch.branchName);
       if (!snapshotPath) continue;
       (0, import_working_tree_mirror.mirrorWorkingTree)({
         sourceRoot: snapshotPath,
@@ -835,9 +867,10 @@ function ensureProjectWorktrees(input) {
         ...divergence
       };
     }).sort((left, right) => left.branchName.localeCompare(right.branchName));
-    persistReconciledProjectAndConsumeSnapshot(snapshot);
+    if (snapshot) persistReconciledProjectAndConsumeSnapshot(snapshot);
     return states;
   } catch (error) {
+    if (!snapshot) throw error;
     try {
       rollbackProjectWorktreeSnapshot(snapshot);
     } catch (recoveryError) {

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

@@ -264,7 +264,7 @@ function filesEqual(leftPath, rightPath, entry) {
     import_node_fs.default.closeSync(right);
   }
 }
-function copyRegularFile(sourcePath, targetPath, entry) {
+function copyRegularFile(sourcePath, targetPath, entry, durability) {
   const source = import_node_fs.default.openSync(sourcePath, import_node_fs.default.constants.O_RDONLY | import_node_fs.default.constants.O_NOFOLLOW);
   const temporaryPath = import_node_path.default.join(import_node_path.default.dirname(targetPath), `${MIRROR_TEMPORARY_FILE_PREFIX}${(0, import_node_crypto.randomUUID)()}.tmp`);
   let target;
@@ -290,7 +290,7 @@ function copyRegularFile(sourcePath, targetPath, entry) {
       offset += bytesRead;
     }
     import_node_fs.default.fchmodSync(target, entry.mode & 511);
-    import_node_fs.default.fsyncSync(target);
+    if (durability === "per_entry") import_node_fs.default.fsyncSync(target);
     const finalSourceStat = import_node_fs.default.fstatSync(source);
     if (!finalSourceStat.isFile() || finalSourceStat.size !== sourceStat.size || (finalSourceStat.mode & 511) !== (sourceStat.mode & 511) || finalSourceStat.mtimeMs !== sourceStat.mtimeMs || finalSourceStat.ctimeMs !== sourceStat.ctimeMs) {
       throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
@@ -298,11 +298,13 @@ function copyRegularFile(sourcePath, targetPath, entry) {
     import_node_fs.default.closeSync(target);
     target = void 0;
     import_node_fs.default.renameSync(temporaryPath, targetPath);
-    const parent = import_node_fs.default.openSync(import_node_path.default.dirname(targetPath), import_node_fs.default.constants.O_RDONLY);
-    try {
-      import_node_fs.default.fsyncSync(parent);
-    } finally {
-      import_node_fs.default.closeSync(parent);
+    if (durability === "per_entry") {
+      const parent = import_node_fs.default.openSync(import_node_path.default.dirname(targetPath), import_node_fs.default.constants.O_RDONLY);
+      try {
+        import_node_fs.default.fsyncSync(parent);
+      } finally {
+        import_node_fs.default.closeSync(parent);
+      }
     }
   } finally {
     if (target !== void 0) import_node_fs.default.closeSync(target);
@@ -310,7 +312,7 @@ function copyRegularFile(sourcePath, targetPath, entry) {
     import_node_fs.default.rmSync(temporaryPath, { force: true });
   }
 }
-function copyEntry(sourceRoot, targetRoot, relativePath, entry) {
+function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
   const targetPath = import_node_path.default.join(targetRoot, ...relativePath.split("/"));
   assertInside(targetRoot, targetPath);
   const parent = import_node_path.default.posix.dirname(relativePath);
@@ -353,12 +355,13 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry) {
     }
     const targetStat = target.kind === "entry" ? target.stat : null;
     if (targetStat && !targetStat.isFile()) removeEntry(targetRoot, relativePath);
-    copyRegularFile(sourcePath, targetPath, entry);
+    copyRegularFile(sourcePath, targetPath, entry, durability);
   }
 }
 function mirrorWorkingTree(input) {
   const sourceRoot = import_node_path.default.resolve(input.sourceRoot);
   const targetRoot = import_node_path.default.resolve(input.targetRoot);
+  const durability = input.durability ?? "per_entry";
   if (!inspectDirectoryRoot(targetRoot, { allowMissing: true, label: "Working-tree target root" })) {
     import_node_fs.default.mkdirSync(targetRoot, { recursive: true });
   }
@@ -371,7 +374,7 @@ function mirrorWorkingTree(input) {
   for (const [relativePath, entry] of [...desired.entries()].sort(
     ([left], [right]) => left.split("/").length - right.split("/").length || left.localeCompare(right)
   )) {
-    copyEntry(sourceRoot, targetRoot, relativePath, entry);
+    copyEntry(sourceRoot, targetRoot, relativePath, entry, durability);
   }
   return { paths: [...desired.keys()].filter((relativePath) => desired.get(relativePath)?.kind !== "directory").sort() };
 }

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

@@ -645,7 +645,16 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
         const snapshotPath = import_node_path.default.join(snapshotRoot, snapshotName);
         import_node_fs.default.mkdirSync(snapshotPath, { mode: 448 });
         if (sourceStatus) {
-          (0, import_working_tree_mirror.mirrorWorkingTree)({ sourceRoot: sourcePath, targetRoot: snapshotPath, sourceMode: "all", deletionMode: "all" });
+          (0, import_working_tree_mirror.mirrorWorkingTree)({
+            sourceRoot: sourcePath,
+            targetRoot: snapshotPath,
+            sourceMode: "all",
+            deletionMode: "all",
+            // This tree is still private and the source authority is untouched.
+            // The single recursive barrier below makes the complete snapshot
+            // durable before its directory entry is published or hydration starts.
+            durability: "deferred_private_staging"
+          });
         }
         return {
           id: mount.id,

package/dist/mjs/main.mjs

@@ -633,7 +633,7 @@ function preparePlanEnvForShell(input) {
   fs.mkdirSync(plansDir, { recursive: true });
   return planEnv(input.planRoot, input.target, input.activePlanId);
 }
-async function verifyR5dctlAuth(baseUrl, token) {
+async function verifyR5dctlAuth(baseUrl, token, workerLabel) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
   try {
@@ -662,13 +662,16 @@ async function verifyR5dctlAuth(baseUrl, token) {
     throw new WorkerServerUnavailableError(`Server unavailable at ${baseUrl} (${response.status})${detail}`);
   }
   throw new Error(
-    `Authentication failed against ${baseUrl} (${response.status})${detail}. Run \`r5dctl auth login --base-url ${baseUrl}\` or pass --token/--api-key for this server.`
+    `Authentication failed against ${baseUrl} (${response.status})${detail}. Run \`r5dctl auth login --base-url ${baseUrl} --worker-label ${workerLabel}\` or pass that exact label-bound worker token.`
   );
 }
 function resolveCredentials(options, config) {
   const token = options.token ?? process.env.R5D_WORKER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
   if (!token) {
-    throw new Error("Authentication required. Run `r5dctl auth login` or set R5D_WORKER_TOKEN/R5D_API_KEY.");
+    const workerLabel = options.label ?? "<label>";
+    throw new Error(
+      `Authentication required. Run \`r5dctl auth login --worker-label ${workerLabel}\` or set R5D_WORKER_TOKEN to that label-bound token.`
+    );
   }
   return {
     baseUrl: normalizeBaseUrl(
@@ -3025,7 +3028,7 @@ async function startWorker(options) {
   process.stdout.write(`[r5d-worker] server: ${baseUrl}
 `);
   runGit(["--version"]);
-  await verifyR5dctlAuth(baseUrl, token);
+  await verifyR5dctlAuth(baseUrl, token, label);
   const initializedWorkspaceState = await workspaceSyncSingleFlight.runExclusive(() => {
     if (!startupProjectSnapshotRecoveryCompleted) {
       const snapshotRecovery = recoverStaleProjectWorktreeSnapshots({

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.79",
+  "version": "0.0.81",
   "type": "module"
 }

package/dist/mjs/project-worktrees.mjs

@@ -336,6 +336,7 @@ function copyCheckoutTree(sourceRoot, targetRoot) {
     dereference: false,
     errorOnExist: true,
     force: false,
+    mode: fs.constants.COPYFILE_FICLONE,
     preserveTimestamps: true,
     verbatimSymlinks: true
   });
@@ -716,6 +717,7 @@ function reconcileLinkedLayout(input) {
   tryGit(primaryPath, ["worktree", "prune"]);
   fetchProjectHeads({ ...input, primaryPath });
   const mirrorHeads = /* @__PURE__ */ new Map();
+  const mutatedBranches = /* @__PURE__ */ new Set();
   for (const branch of input.branches) {
     const checkoutPath = branchPath(input.projectRoot, branch.branchName);
     const resolved = seedForBranch({
@@ -726,16 +728,22 @@ function reconcileLinkedLayout(input) {
     });
     mirrorHeads.set(branch.branchName, resolved.mirrorHead);
     if (branch.branchName === input.primaryBranchName || commonGitDirectory(checkoutPath) === commonGitDirectory(primaryPath)) {
+      const currentHead = git(checkoutPath, ["rev-parse", "HEAD"], `resolve linked worktree head ${branch.branchName}`);
+      if (currentHead === resolved.seed) continue;
+      input.beforeDestructiveMutation();
+      mutatedBranches.add(branch.branchName);
       preserveHead(checkoutPath);
       git(checkoutPath, ["reset", "--hard", resolved.seed], `anchor linked worktree ${branch.branchName}`);
       continue;
     }
+    input.beforeDestructiveMutation();
+    mutatedBranches.add(branch.branchName);
     fs.rmSync(checkoutPath, { recursive: true, force: true });
     git(primaryPath, ["branch", "-f", branch.branchName, resolved.seed], `anchor project branch ${branch.branchName}`);
     fs.mkdirSync(path.dirname(checkoutPath), { recursive: true });
     git(primaryPath, ["worktree", "add", "--force", checkoutPath, branch.branchName], `create linked worktree ${branch.branchName}`);
   }
-  return mirrorHeads;
+  return { mirrorHeads, mutatedBranches };
 }
 function aheadBehind(checkoutPath, branchName, primaryBranchName, defaultBranch) {
   const originBranchName = projectOriginBranchName({ branchName, primaryBranchName, defaultBranch });
@@ -752,7 +760,13 @@ function ensureProjectWorktrees(input) {
   if (!input.branches.some(({ branchName }) => branchName === input.primaryBranchName)) {
     throw new Error(`Primary project branch ${input.primaryBranchName} is missing from the workspace configuration`);
   }
-  const snapshot = snapshotBranchTrees(projectRoot, input.branches, input.snapshotRoot);
+  const snapshotStorageRoot = path.resolve(input.snapshotRoot ?? os.tmpdir());
+  assertNoOutstandingSnapshotForProject(snapshotStorageRoot, projectRoot);
+  let snapshot;
+  const ensureSnapshot = () => {
+    snapshot ??= snapshotBranchTrees(projectRoot, input.branches, snapshotStorageRoot);
+    return snapshot;
+  };
   try {
     fs.mkdirSync(projectRoot, { recursive: true });
     const linked = hasCompatibleLinkedProjectWorktreeLayout({
@@ -760,9 +774,27 @@ function ensureProjectWorktrees(input) {
       primaryBranchName: input.primaryBranchName,
       branches: input.branches
     });
-    const mirrorHeads = linked ? reconcileLinkedLayout({ ...input, projectRoot, defaultBranch }) : initializeLinkedLayout({ ...input, projectRoot, defaultBranch });
+    let mirrorHeads;
+    let mutatedBranches;
+    if (linked) {
+      ({ mirrorHeads, mutatedBranches } = reconcileLinkedLayout({
+        ...input,
+        projectRoot,
+        defaultBranch,
+        beforeDestructiveMutation: ensureSnapshot
+      }));
+    } else {
+      ensureSnapshot();
+      mirrorHeads = initializeLinkedLayout({ ...input, projectRoot, defaultBranch });
+      mutatedBranches = new Set(input.branches.map(({ branchName }) => branchName));
+    }
+    const preparedSnapshot = snapshot;
+    if (mutatedBranches.size > 0 && !preparedSnapshot) {
+      throw new Error("Project worktree mutation started without a prepared recovery snapshot");
+    }
     for (const branch of input.branches) {
-      const snapshotPath = snapshot.paths.get(branch.branchName);
+      if (!mutatedBranches.has(branch.branchName)) continue;
+      const snapshotPath = preparedSnapshot?.paths.get(branch.branchName);
       if (!snapshotPath) continue;
       mirrorWorkingTree({
         sourceRoot: snapshotPath,
@@ -782,9 +814,10 @@ function ensureProjectWorktrees(input) {
         ...divergence
       };
     }).sort((left, right) => left.branchName.localeCompare(right.branchName));
-    persistReconciledProjectAndConsumeSnapshot(snapshot);
+    if (snapshot) persistReconciledProjectAndConsumeSnapshot(snapshot);
     return states;
   } catch (error) {
+    if (!snapshot) throw error;
     try {
       rollbackProjectWorktreeSnapshot(snapshot);
     } catch (recoveryError) {

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

@@ -229,7 +229,7 @@ function filesEqual(leftPath, rightPath, entry) {
     fs.closeSync(right);
   }
 }
-function copyRegularFile(sourcePath, targetPath, entry) {
+function copyRegularFile(sourcePath, targetPath, entry, durability) {
   const source = fs.openSync(sourcePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
   const temporaryPath = path.join(path.dirname(targetPath), `${MIRROR_TEMPORARY_FILE_PREFIX}${randomUUID()}.tmp`);
   let target;
@@ -255,7 +255,7 @@ function copyRegularFile(sourcePath, targetPath, entry) {
       offset += bytesRead;
     }
     fs.fchmodSync(target, entry.mode & 511);
-    fs.fsyncSync(target);
+    if (durability === "per_entry") fs.fsyncSync(target);
     const finalSourceStat = fs.fstatSync(source);
     if (!finalSourceStat.isFile() || finalSourceStat.size !== sourceStat.size || (finalSourceStat.mode & 511) !== (sourceStat.mode & 511) || finalSourceStat.mtimeMs !== sourceStat.mtimeMs || finalSourceStat.ctimeMs !== sourceStat.ctimeMs) {
       throw new Error(`Working-tree source changed while it was being mirrored: ${sourcePath}`);
@@ -263,11 +263,13 @@ function copyRegularFile(sourcePath, targetPath, entry) {
     fs.closeSync(target);
     target = void 0;
     fs.renameSync(temporaryPath, targetPath);
-    const parent = fs.openSync(path.dirname(targetPath), fs.constants.O_RDONLY);
-    try {
-      fs.fsyncSync(parent);
-    } finally {
-      fs.closeSync(parent);
+    if (durability === "per_entry") {
+      const parent = fs.openSync(path.dirname(targetPath), fs.constants.O_RDONLY);
+      try {
+        fs.fsyncSync(parent);
+      } finally {
+        fs.closeSync(parent);
+      }
     }
   } finally {
     if (target !== void 0) fs.closeSync(target);
@@ -275,7 +277,7 @@ function copyRegularFile(sourcePath, targetPath, entry) {
     fs.rmSync(temporaryPath, { force: true });
   }
 }
-function copyEntry(sourceRoot, targetRoot, relativePath, entry) {
+function copyEntry(sourceRoot, targetRoot, relativePath, entry, durability) {
   const targetPath = path.join(targetRoot, ...relativePath.split("/"));
   assertInside(targetRoot, targetPath);
   const parent = path.posix.dirname(relativePath);
@@ -318,12 +320,13 @@ function copyEntry(sourceRoot, targetRoot, relativePath, entry) {
     }
     const targetStat = target.kind === "entry" ? target.stat : null;
     if (targetStat && !targetStat.isFile()) removeEntry(targetRoot, relativePath);
-    copyRegularFile(sourcePath, targetPath, entry);
+    copyRegularFile(sourcePath, targetPath, entry, durability);
   }
 }
 function mirrorWorkingTree(input) {
   const sourceRoot = path.resolve(input.sourceRoot);
   const targetRoot = path.resolve(input.targetRoot);
+  const durability = input.durability ?? "per_entry";
   if (!inspectDirectoryRoot(targetRoot, { allowMissing: true, label: "Working-tree target root" })) {
     fs.mkdirSync(targetRoot, { recursive: true });
   }
@@ -336,7 +339,7 @@ function mirrorWorkingTree(input) {
   for (const [relativePath, entry] of [...desired.entries()].sort(
     ([left], [right]) => left.split("/").length - right.split("/").length || left.localeCompare(right)
   )) {
-    copyEntry(sourceRoot, targetRoot, relativePath, entry);
+    copyEntry(sourceRoot, targetRoot, relativePath, entry, durability);
   }
   return { paths: [...desired.keys()].filter((relativePath) => desired.get(relativePath)?.kind !== "directory").sort() };
 }

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

@@ -600,7 +600,16 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
         const snapshotPath = path.join(snapshotRoot, snapshotName);
         fs.mkdirSync(snapshotPath, { mode: 448 });
         if (sourceStatus) {
-          mirrorWorkingTree({ sourceRoot: sourcePath, targetRoot: snapshotPath, sourceMode: "all", deletionMode: "all" });
+          mirrorWorkingTree({
+            sourceRoot: sourcePath,
+            targetRoot: snapshotPath,
+            sourceMode: "all",
+            deletionMode: "all",
+            // This tree is still private and the source authority is untouched.
+            // The single recursive barrier below makes the complete snapshot
+            // durable before its directory entry is published or hydration starts.
+            durability: "deferred_private_staging"
+          });
         }
         return {
           id: mount.id,

package/dist/types/working-tree-mirror.d.ts

@@ -1,5 +1,6 @@
 export type WorkingTreeSourceMode = "all" | "git";
 export type WorkingTreeDeletionMode = "all" | "git";
+export type WorkingTreeMirrorDurability = "per_entry" | "deferred_private_staging";
 type TreeEntry = {
     kind: "directory";
     mode: number;
@@ -25,6 +26,12 @@ export declare function mirrorWorkingTree(input: {
     targetRoot: string;
     sourceMode: WorkingTreeSourceMode;
     deletionMode: WorkingTreeDeletionMode;
+    /**
+     * Defer destination fsync only while building an unpublished private tree.
+     * The caller must durably fsync that complete tree before publishing it or
+     * mutating the source authority.
+     */
+    durability?: WorkingTreeMirrorDurability;
 }): {
     paths: string[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.79",
+  "version": "0.0.81",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",