@ricsam/r5d-worker 0.0.78 → 0.0.79

package/dist/mjs/project-worktrees.mjs

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -6,9 +6,26 @@ import { gitCredentialUsernameConfigKey, gitTransportSecurityArgs, workerGitProc
 import { validateManagedBranchName } from "./managed-paths.mjs";
 import { mirrorWorkingTree } from "./working-tree-mirror.mjs";
 const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
+const PROJECT_WORKTREE_SNAPSHOT_MANIFEST = "transaction.json";
+const PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION = 1;
+const MAX_PROJECT_WORKTREE_SNAPSHOT_MANIFEST_BYTES = 64 * 1024;
+const PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID = randomUUID();
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PROJECT_WORKTREE_SNAPSHOT_NAME = new RegExp(
   `^${PROJECT_WORKTREE_SNAPSHOT_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([1-9]\\d*)-([A-Za-z0-9]{6})$`
 );
+class ProjectBranchCreationRollbackIncompleteError extends Error {
+  branchMayExist = true;
+  cleanupFailures;
+  constructor(branchName, cleanupFailures, cause) {
+    super(`Project branch ${branchName} may still exist after incomplete rollback: ${cleanupFailures.join("; ")}`, { cause });
+    this.name = "ProjectBranchCreationRollbackIncompleteError";
+    this.cleanupFailures = [...cleanupFailures];
+  }
+}
+function projectBranchMayExistAfterCreateFailure(error) {
+  return error instanceof ProjectBranchCreationRollbackIncompleteError || typeof error === "object" && error !== null && "branchMayExist" in error && error.branchMayExist === true;
+}
 function projectWorktreeConfigurationFingerprint(input) {
   return createHash("sha256").update(
     JSON.stringify({
@@ -17,7 +34,12 @@ function projectWorktreeConfigurationFingerprint(input) {
       repoHttpUrl: input.repoHttpUrl,
       repoAuthHeader: input.repoAuthHeader,
       defaultBranch: input.defaultBranch,
-      branches: [...input.branches].sort((left, right) => left.branchName.localeCompare(right.branchName)).map(({ branchName, sourceBranchName, baseCommitHash }) => ({
+      repositoryTransitionId: input.repositoryTransitionId ?? null,
+      executionDisabled: input.executionDisabled ?? false,
+      mirrorWritesDisabled: input.mirrorWritesDisabled ?? false,
+      preserveOnlyBranches: [...input.preserveOnlyBranches ?? []].sort((left, right) => left.branchName.localeCompare(right.branchName)).map(({ branchId, branchName }) => ({ branchId: branchId ?? null, branchName })),
+      branches: [...input.branches].sort((left, right) => left.branchName.localeCompare(right.branchName)).map(({ branchId, branchName, sourceBranchName, baseCommitHash }) => ({
+        branchId: branchId ?? null,
         branchName,
         sourceBranchName: sourceBranchName ?? null,
         baseCommitHash
@@ -67,6 +89,27 @@ function branchPath(projectRoot, branchName) {
   }
   return result;
 }
+function assertNoSymlinkBranchPathComponents(projectRoot, branchPath2) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const resolvedBranchPath = path.resolve(branchPath2);
+  const relative = path.relative(resolvedRoot, resolvedBranchPath);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Branch path escapes its project root: ${branchPath2}`);
+  }
+  let current = resolvedRoot;
+  for (const component of ["", ...relative.split(path.sep).filter(Boolean)]) {
+    if (component) current = path.join(current, component);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Project branch path contains a symbolic link: ${current}`);
+      }
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT" || code === "ENOTDIR") return;
+      throw error;
+    }
+  }
+}
 function assertNonOverlappingBranches(branches) {
   const names = branches.map(({ branchName }) => branchName).sort();
   if (new Set(names).size !== names.length) throw new Error("Project worktree branch names must be unique");
@@ -119,26 +162,309 @@ function hasCompatibleLinkedProjectWorktreeLayout(input) {
     return kind === null || kind === "file" && commonGitDirectory(checkoutPath) === primaryCommonDir;
   });
 }
-function createProjectWorktreeSnapshotRoot() {
-  return fs.mkdtempSync(path.join(os.tmpdir(), `${PROJECT_WORKTREE_SNAPSHOT_PREFIX}${process.pid}-`));
+function fsyncDirectory(directory) {
+  const descriptor = fs.openSync(directory, "r");
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function fsyncTree(targetPath) {
+  const stat = fs.lstatSync(targetPath);
+  if (stat.isSymbolicLink()) return;
+  if (stat.isDirectory()) {
+    for (const entry of fs.readdirSync(targetPath).sort()) fsyncTree(path.join(targetPath, entry));
+    fsyncDirectory(targetPath);
+    return;
+  }
+  if (!stat.isFile()) return;
+  const descriptor = fs.openSync(targetPath, "r");
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function fsyncDirectoryChain(directory, root) {
+  const resolvedDirectory = path.resolve(directory);
+  const resolvedRoot = path.resolve(root);
+  const relative = path.relative(resolvedRoot, resolvedDirectory);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Directory is outside its durability root: ${resolvedDirectory}`);
+  }
+  let current = resolvedDirectory;
+  while (true) {
+    assertRealDirectory(current, "Durability path");
+    fsyncDirectory(current);
+    if (current === resolvedRoot) break;
+    current = path.dirname(current);
+  }
+}
+function removeSnapshotStorage(snapshotRoot) {
+  const storageRoot = path.dirname(path.resolve(snapshotRoot));
+  fs.rmSync(snapshotRoot, { recursive: true, force: true });
+  fsyncDirectory(storageRoot);
+}
+function fsyncManagedProjectRootEntry(projectRoot) {
+  fsyncDirectoryChain(projectRoot, path.dirname(path.dirname(projectRoot)));
+}
+function createProjectWorktreeSnapshotRoot(temporaryRoot = os.tmpdir()) {
+  const resolvedTemporaryRoot = path.resolve(temporaryRoot);
+  const storageRootExisted = fs.existsSync(resolvedTemporaryRoot);
+  fs.mkdirSync(resolvedTemporaryRoot, { recursive: true, mode: 448 });
+  assertRealDirectory(resolvedTemporaryRoot, "Project worktree snapshot storage root");
+  if (!storageRootExisted) fsyncDirectory(path.dirname(resolvedTemporaryRoot));
+  fsyncDirectory(resolvedTemporaryRoot);
+  const snapshotRoot = fs.mkdtempSync(path.join(resolvedTemporaryRoot, `${PROJECT_WORKTREE_SNAPSHOT_PREFIX}${process.pid}-`));
+  fsyncDirectory(snapshotRoot);
+  fsyncDirectory(resolvedTemporaryRoot);
+  return snapshotRoot;
+}
+function snapshotManifestPath(snapshotRoot) {
+  return path.join(snapshotRoot, PROJECT_WORKTREE_SNAPSHOT_MANIFEST);
+}
+function assertRealDirectory(directory, label) {
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`${label} must be a real directory`);
+}
+function normalizeSnapshotManifest(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Project worktree snapshot manifest must be an object");
+  }
+  const record = value;
+  if (record.version !== PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION) {
+    throw new Error("Unsupported project worktree snapshot manifest version");
+  }
+  if (record.state !== "building" && record.state !== "prepared" && record.state !== "consumed") {
+    throw new Error("Project worktree snapshot manifest has an invalid state");
+  }
+  if (!Number.isSafeInteger(record.ownerProcessId) || record.ownerProcessId <= 0) {
+    throw new Error("Project worktree snapshot manifest has an invalid owner process");
+  }
+  if (typeof record.ownerSessionId !== "string" || !UUID_PATTERN.test(record.ownerSessionId)) {
+    throw new Error("Project worktree snapshot manifest has an invalid owner session");
+  }
+  if (typeof record.projectRoot !== "string" || !path.isAbsolute(record.projectRoot) || path.resolve(record.projectRoot) !== record.projectRoot) {
+    throw new Error("Project worktree snapshot manifest has an invalid project root");
+  }
+  if (typeof record.createdAt !== "string" || !Number.isFinite(Date.parse(record.createdAt))) {
+    throw new Error("Project worktree snapshot manifest has an invalid creation time");
+  }
+  if (!Array.isArray(record.branches)) throw new Error("Project worktree snapshot manifest has invalid branches");
+  const branches = record.branches.map((value2) => {
+    if (typeof value2 !== "object" || value2 === null || Array.isArray(value2)) {
+      throw new Error("Project worktree snapshot manifest has an invalid branch");
+    }
+    const branch = value2;
+    if (typeof branch.branchName !== "string" || typeof branch.snapshotPresent !== "boolean") {
+      throw new Error("Project worktree snapshot manifest has an invalid branch");
+    }
+    validateManagedBranchName(branch.branchName);
+    return { branchName: branch.branchName, snapshotPresent: branch.snapshotPresent };
+  });
+  const names = branches.map(({ branchName }) => branchName).sort();
+  if (new Set(names).size !== names.length) throw new Error("Project worktree snapshot branch names must be unique");
+  for (let index = 0; index < names.length; index += 1) {
+    const name = names[index];
+    if (names.slice(index + 1).some((candidate) => candidate.startsWith(`${name}/`))) {
+      throw new Error("Project worktree snapshot branch paths overlap");
+    }
+  }
+  return {
+    version: PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION,
+    state: record.state,
+    ownerProcessId: record.ownerProcessId,
+    ownerSessionId: record.ownerSessionId,
+    projectRoot: record.projectRoot,
+    branches,
+    createdAt: record.createdAt
+  };
+}
+function readSnapshotManifest(snapshotRoot) {
+  assertRealDirectory(snapshotRoot, "Project worktree snapshot root");
+  const manifestPath = snapshotManifestPath(snapshotRoot);
+  const stat = fs.lstatSync(manifestPath);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Project worktree snapshot manifest must be a regular file");
+  if (stat.size > MAX_PROJECT_WORKTREE_SNAPSHOT_MANIFEST_BYTES) throw new Error("Project worktree snapshot manifest is too large");
+  return normalizeSnapshotManifest(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
+}
+function writeSnapshotManifest(snapshotRoot, manifest) {
+  assertRealDirectory(snapshotRoot, "Project worktree snapshot root");
+  const normalized = normalizeSnapshotManifest(manifest);
+  const temporaryPath = path.join(snapshotRoot, `.${PROJECT_WORKTREE_SNAPSHOT_MANIFEST}.${process.pid}.${randomUUID()}.tmp`);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporaryPath, "wx", 384);
+    fs.writeFileSync(descriptor, `${JSON.stringify(normalized, null, 2)}
+`, "utf8");
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = void 0;
+    fs.renameSync(temporaryPath, snapshotManifestPath(snapshotRoot));
+    fsyncDirectory(snapshotRoot);
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+    fs.rmSync(temporaryPath, { force: true });
+  }
+  return readSnapshotManifest(snapshotRoot);
+}
+function assertSameSnapshotIdentity(expected, actual) {
+  if (expected.ownerProcessId !== actual.ownerProcessId || expected.ownerSessionId !== actual.ownerSessionId || expected.projectRoot !== actual.projectRoot || expected.createdAt !== actual.createdAt || JSON.stringify(expected.branches) !== JSON.stringify(actual.branches)) {
+    throw new Error("Project worktree snapshot identity changed");
+  }
+}
+function advanceSnapshotState(snapshotRoot, expected, state) {
+  const current = readSnapshotManifest(snapshotRoot);
+  assertSameSnapshotIdentity(expected, current);
+  const allowed = current.state === "building" && state === "prepared" || current.state === "prepared" && state === "consumed" || current.state === state;
+  if (!allowed) throw new Error(`Project worktree snapshot cannot advance from ${current.state} to ${state}`);
+  return current.state === state ? current : writeSnapshotManifest(snapshotRoot, { ...current, state });
+}
+function fullSnapshotPath(snapshotRoot, branchName) {
+  validateManagedBranchName(branchName);
+  return path.join(snapshotRoot, "trees", ...branchName.split("/"));
 }
-function snapshotBranchTrees(projectRoot, branches) {
-  const root = createProjectWorktreeSnapshotRoot();
+function copyCheckoutTree(sourceRoot, targetRoot) {
+  const sourceStat = fs.lstatSync(sourceRoot);
+  if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink()) {
+    throw new Error(`Project checkout snapshot source must be a real directory: ${sourceRoot}`);
+  }
+  fs.mkdirSync(path.dirname(targetRoot), { recursive: true });
+  fs.cpSync(sourceRoot, targetRoot, {
+    recursive: true,
+    dereference: false,
+    errorOnExist: true,
+    force: false,
+    preserveTimestamps: true,
+    verbatimSymlinks: true
+  });
+}
+function assertNoOutstandingSnapshotForProject(temporaryRoot, projectRoot) {
+  let entries;
+  try {
+    assertRealDirectory(temporaryRoot, "Project worktree snapshot storage root");
+    entries = fs.readdirSync(temporaryRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || !PROJECT_WORKTREE_SNAPSHOT_NAME.test(entry.name)) continue;
+    let manifest;
+    try {
+      manifest = readSnapshotManifest(path.join(temporaryRoot, entry.name));
+    } catch (error) {
+      throw new Error(`Project checkout snapshot state is unreadable at ${path.join(temporaryRoot, entry.name)}`, { cause: error });
+    }
+    if (manifest.projectRoot === projectRoot && manifest.state !== "consumed") {
+      throw new Error(`Project checkout has an unfinished recovery snapshot at ${path.join(temporaryRoot, entry.name)}`);
+    }
+  }
+}
+function snapshotBranchTrees(projectRoot, branches, temporaryRoot) {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const resolvedTemporaryRoot = path.resolve(temporaryRoot ?? os.tmpdir());
+  assertNoOutstandingSnapshotForProject(resolvedTemporaryRoot, resolvedProjectRoot);
+  const root = createProjectWorktreeSnapshotRoot(resolvedTemporaryRoot);
   const paths = /* @__PURE__ */ new Map();
   try {
-    for (const { branchName } of branches) {
-      const checkoutPath = branchPath(projectRoot, branchName);
-      if (!fs.existsSync(checkoutPath)) continue;
-      const snapshotPath = path.join(root, ...branchName.split("/"));
-      mirrorWorkingTree({ sourceRoot: checkoutPath, targetRoot: snapshotPath, sourceMode: "all", deletionMode: "all" });
+    const branchSnapshots = branches.map(({ branchName }) => {
+      const checkoutPath = branchPath(resolvedProjectRoot, branchName);
+      let snapshotPresent = false;
+      try {
+        fs.lstatSync(checkoutPath);
+        snapshotPresent = true;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      return { branchName, snapshotPresent };
+    });
+    let manifest = writeSnapshotManifest(root, {
+      version: PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION,
+      state: "building",
+      ownerProcessId: process.pid,
+      ownerSessionId: PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID,
+      projectRoot: resolvedProjectRoot,
+      branches: branchSnapshots,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    for (const { branchName, snapshotPresent } of branchSnapshots) {
+      if (!snapshotPresent) continue;
+      const snapshotPath = fullSnapshotPath(root, branchName);
+      copyCheckoutTree(branchPath(resolvedProjectRoot, branchName), snapshotPath);
       paths.set(branchName, snapshotPath);
     }
-    return { root, paths };
+    const treesRoot = path.join(root, "trees");
+    if (fs.existsSync(treesRoot)) fsyncTree(treesRoot);
+    manifest = advanceSnapshotState(root, manifest, "prepared");
+    return { root, manifest, paths };
   } catch (error) {
-    fs.rmSync(root, { recursive: true, force: true });
+    removeSnapshotStorage(root);
     throw error;
   }
 }
+function restoreProjectWorktreeSnapshot(snapshotRoot, manifest) {
+  const current = readSnapshotManifest(snapshotRoot);
+  assertSameSnapshotIdentity(manifest, current);
+  if (current.state !== "prepared") throw new Error(`Project worktree snapshot is ${current.state}, not prepared`);
+  for (const { branchName, snapshotPresent } of current.branches) {
+    const targetPath = branchPath(current.projectRoot, branchName);
+    assertNoSymlinkBranchPathComponents(current.projectRoot, targetPath);
+    if (!snapshotPresent) continue;
+    const sourcePath = fullSnapshotPath(snapshotRoot, branchName);
+    const stat = fs.lstatSync(sourcePath);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error(`Project worktree snapshot branch must be a real directory: ${branchName}`);
+    }
+  }
+  for (const { branchName } of [...current.branches].sort((left, right) => right.branchName.length - left.branchName.length)) {
+    const targetPath = branchPath(current.projectRoot, branchName);
+    const targetParent = path.dirname(targetPath);
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    if (fs.existsSync(targetParent)) fsyncDirectoryChain(targetParent, current.projectRoot);
+  }
+  for (const { branchName, snapshotPresent } of current.branches) {
+    if (!snapshotPresent) continue;
+    const targetPath = branchPath(current.projectRoot, branchName);
+    copyCheckoutTree(fullSnapshotPath(snapshotRoot, branchName), targetPath);
+    fsyncTree(targetPath);
+    fsyncDirectoryChain(path.dirname(targetPath), current.projectRoot);
+  }
+  fs.mkdirSync(current.projectRoot, { recursive: true });
+  fsyncManagedProjectRootEntry(current.projectRoot);
+}
+function consumeAndRemoveProjectWorktreeSnapshot(snapshotRoot, manifest) {
+  const consumed = advanceSnapshotState(snapshotRoot, manifest, "consumed");
+  try {
+    assertSameSnapshotIdentity(manifest, consumed);
+    removeSnapshotStorage(snapshotRoot);
+  } catch {
+  }
+}
+function persistReconciledProjectAndConsumeSnapshot(snapshot, afterProjectTreeFsync) {
+  fsyncTree(snapshot.manifest.projectRoot);
+  fsyncManagedProjectRootEntry(snapshot.manifest.projectRoot);
+  afterProjectTreeFsync?.();
+  consumeAndRemoveProjectWorktreeSnapshot(snapshot.root, snapshot.manifest);
+}
+function rollbackProjectWorktreeSnapshot(snapshot) {
+  const current = readSnapshotManifest(snapshot.root);
+  assertSameSnapshotIdentity(snapshot.manifest, current);
+  if (current.state === "prepared") {
+    restoreProjectWorktreeSnapshot(snapshot.root, current);
+    consumeAndRemoveProjectWorktreeSnapshot(snapshot.root, current);
+    return;
+  }
+  if (current.state === "consumed") {
+    try {
+      removeSnapshotStorage(snapshot.root);
+    } catch {
+    }
+    return;
+  }
+  throw new Error(`Project worktree snapshot is unexpectedly ${current.state}`);
+}
 function isProcessAlive(processId) {
   try {
     process.kill(processId, 0);
@@ -147,35 +473,105 @@ function isProcessAlive(processId) {
     return error.code !== "ESRCH";
   }
 }
-function cleanupStaleProjectWorktreeSnapshots(input = {}) {
+function isPathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function assertNoSymlinkPathComponents(root, candidate) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedCandidate = path.resolve(candidate);
+  if (!isPathInside(resolvedRoot, resolvedCandidate)) throw new Error("Project worktree snapshot target escapes the projects root");
+  let current = resolvedRoot;
+  for (const component of ["", ...path.relative(resolvedRoot, resolvedCandidate).split(path.sep).filter(Boolean)]) {
+    if (component) current = path.join(current, component);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Project worktree snapshot target contains a symbolic link: ${current}`);
+      }
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT" || code === "ENOTDIR") return;
+      throw error;
+    }
+  }
+}
+function recoverStaleProjectWorktreeSnapshots(input) {
   const temporaryRoot = path.resolve(input.temporaryRoot ?? os.tmpdir());
+  const projectsRoot = path.resolve(input.projectsRoot);
   const processAlive = input.processAlive ?? isProcessAlive;
+  const currentProcessId = input.currentProcessId ?? process.pid;
+  const currentOwnerSessionId = input.currentOwnerSessionId ?? PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID;
+  if (!Number.isSafeInteger(currentProcessId) || currentProcessId <= 0) throw new Error("Current snapshot recovery process ID is invalid");
+  if (!UUID_PATTERN.test(currentOwnerSessionId)) throw new Error("Current snapshot recovery owner session is invalid");
+  const restored = [];
   const removed = [];
   const failed = [];
   let entries;
   try {
+    assertRealDirectory(temporaryRoot, "Project worktree snapshot storage root");
     entries = fs.readdirSync(temporaryRoot, { withFileTypes: true });
   } catch (error) {
-    if (error.code === "ENOENT") return { removed, failed };
-    return { removed, failed: [{ path: temporaryRoot, error: error instanceof Error ? error.message : String(error) }] };
+    if (error.code === "ENOENT") return { restored, removed, failed };
+    return { restored, removed, failed: [{ path: temporaryRoot, error: error instanceof Error ? error.message : String(error) }] };
   }
   for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
     const match = PROJECT_WORKTREE_SNAPSHOT_NAME.exec(entry.name);
     if (!match) continue;
     const ownerProcessId = Number(match[1]);
-    if (!Number.isSafeInteger(ownerProcessId) || processAlive(ownerProcessId)) continue;
+    if (!Number.isSafeInteger(ownerProcessId)) continue;
     const candidate = path.join(temporaryRoot, entry.name);
     try {
       const stat = fs.lstatSync(candidate);
       if (!stat.isDirectory() || stat.isSymbolicLink()) continue;
-      fs.rmSync(candidate, { recursive: true, force: true });
-      removed.push(candidate);
+      const manifest = readSnapshotManifest(candidate);
+      if (manifest.ownerProcessId !== ownerProcessId) {
+        throw new Error("Project worktree snapshot owner does not match its directory name");
+      }
+      if (!isPathInside(projectsRoot, manifest.projectRoot)) {
+        throw new Error("Project worktree snapshot target is outside the configured projects root");
+      }
+      assertNoSymlinkPathComponents(projectsRoot, manifest.projectRoot);
+      const ownedByThisProcessSession = manifest.ownerProcessId === currentProcessId && manifest.ownerSessionId === currentOwnerSessionId;
+      if (ownedByThisProcessSession || ownerProcessId !== currentProcessId && processAlive(ownerProcessId)) continue;
+      if (manifest.state === "prepared") {
+        restoreProjectWorktreeSnapshot(candidate, manifest);
+        const consumed = advanceSnapshotState(candidate, manifest, "consumed");
+        removeSnapshotStorage(candidate);
+        assertSameSnapshotIdentity(manifest, consumed);
+        restored.push(candidate);
+      } else {
+        removeSnapshotStorage(candidate);
+        removed.push(candidate);
+      }
     } catch (error) {
-      if (error.code === "ENOENT") continue;
+      if (ownerProcessId !== currentProcessId && processAlive(ownerProcessId)) continue;
+      if (error.code === "ENOENT") {
+        try {
+          fs.lstatSync(candidate);
+        } catch (candidateError) {
+          if (candidateError.code === "ENOENT") continue;
+        }
+      }
       failed.push({ path: candidate, error: error instanceof Error ? error.message : String(error) });
     }
   }
-  return { removed, failed };
+  return { restored, removed, failed };
+}
+function projectOriginBranchName(input) {
+  validateManagedBranchName(input.branchName);
+  validateManagedBranchName(input.primaryBranchName);
+  validateManagedBranchName(input.defaultBranch);
+  return input.branchName === input.primaryBranchName ? input.defaultBranch : input.branchName;
+}
+function configureProjectBranchTracking(checkoutPath, branchName, originBranchName) {
+  validateManagedBranchName(branchName);
+  validateManagedBranchName(originBranchName);
+  git(checkoutPath, ["config", "--local", `branch.${branchName}.remote`, "origin"], `configure origin for ${branchName}`);
+  git(
+    checkoutPath,
+    ["config", "--local", `branch.${branchName}.merge`, `refs/heads/${originBranchName}`],
+    `configure upstream branch for ${branchName}`
+  );
 }
 function configureRepository(input) {
   if (tryGit(input.primaryPath, ["remote", "get-url", "origin"])) {
@@ -207,6 +603,17 @@ function configureRepository(input) {
     git(input.primaryPath, ["config", "--local", "user.name", name], "configure project Git user name");
     git(input.primaryPath, ["config", "--local", "user.email", email], "configure project Git user email");
   }
+  if (input.primaryBranchName && input.defaultBranch && input.branches) {
+    git(input.primaryPath, ["config", "--local", "push.default", "upstream"], "configure project push mapping");
+    for (const { branchName } of input.branches) {
+      const originBranchName = projectOriginBranchName({
+        branchName,
+        primaryBranchName: input.primaryBranchName,
+        defaultBranch: input.defaultBranch
+      });
+      configureProjectBranchTracking(input.primaryPath, branchName, originBranchName);
+    }
+  }
 }
 function fetchProjectHeads(input) {
   const originFetch = gitResult(input.primaryPath, [
@@ -256,6 +663,9 @@ function ensureCommitAvailable(input) {
 function seedForBranch(input) {
   const mirrorRef = `refs/r5d/mirror/${input.branch.branchName}`;
   const mirrorHead = tryGit(input.primaryPath, ["show-ref", "--verify", "--quiet", mirrorRef]) ? git(input.primaryPath, ["rev-parse", mirrorRef], "resolve project mirror head") : null;
+  if (input.requireMirrorHead && !mirrorHead) {
+    throw new Error(`Exact hidden project mirror head is missing for ${input.branch.branchName}`);
+  }
   const seed = mirrorHead ?? input.branch.baseCommitHash;
   ensureCommitAvailable({ ...input, commitHash: seed });
   return { seed, mirrorHead };
@@ -277,7 +687,12 @@ function initializeLinkedLayout(input) {
   const seeds = /* @__PURE__ */ new Map();
   const mirrorHeads = /* @__PURE__ */ new Map();
   for (const branch of input.branches) {
-    const resolved = seedForBranch({ ...input, primaryPath, branch });
+    const resolved = seedForBranch({
+      ...input,
+      primaryPath,
+      branch,
+      requireMirrorHead: input.exactMirrorBranches?.has(branch.branchName)
+    });
     seeds.set(branch.branchName, resolved.seed);
     mirrorHeads.set(branch.branchName, resolved.mirrorHead);
   }
@@ -303,7 +718,12 @@ function reconcileLinkedLayout(input) {
   const mirrorHeads = /* @__PURE__ */ new Map();
   for (const branch of input.branches) {
     const checkoutPath = branchPath(input.projectRoot, branch.branchName);
-    const resolved = seedForBranch({ ...input, primaryPath, branch });
+    const resolved = seedForBranch({
+      ...input,
+      primaryPath,
+      branch,
+      requireMirrorHead: input.exactMirrorBranches?.has(branch.branchName)
+    });
     mirrorHeads.set(branch.branchName, resolved.mirrorHead);
     if (branch.branchName === input.primaryBranchName || commonGitDirectory(checkoutPath) === commonGitDirectory(primaryPath)) {
       preserveHead(checkoutPath);
@@ -317,8 +737,9 @@ function reconcileLinkedLayout(input) {
   }
   return mirrorHeads;
 }
-function aheadBehind(checkoutPath, branchName) {
-  const originRef = `refs/remotes/origin/${branchName}`;
+function aheadBehind(checkoutPath, branchName, primaryBranchName, defaultBranch) {
+  const originBranchName = projectOriginBranchName({ branchName, primaryBranchName, defaultBranch });
+  const originRef = `refs/remotes/origin/${originBranchName}`;
   if (!tryGit(checkoutPath, ["show-ref", "--verify", "--quiet", originRef])) return { ahead: null, behind: null };
   const output = git(checkoutPath, ["rev-list", "--left-right", "--count", `${originRef}...HEAD`], "measure project origin divergence");
   const [behind, ahead] = output.split(/\s+/).map(Number);
@@ -326,11 +747,12 @@ function aheadBehind(checkoutPath, branchName) {
 }
 function ensureProjectWorktrees(input) {
   const projectRoot = path.resolve(input.projectRoot);
+  const defaultBranch = input.defaultBranch ?? input.primaryBranchName;
   assertNonOverlappingBranches(input.branches);
   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);
+  const snapshot = snapshotBranchTrees(projectRoot, input.branches, input.snapshotRoot);
   try {
     fs.mkdirSync(projectRoot, { recursive: true });
     const linked = hasCompatibleLinkedProjectWorktreeLayout({
@@ -338,7 +760,7 @@ function ensureProjectWorktrees(input) {
       primaryBranchName: input.primaryBranchName,
       branches: input.branches
     });
-    const mirrorHeads = linked ? reconcileLinkedLayout({ ...input, projectRoot }) : initializeLinkedLayout({ ...input, projectRoot });
+    const mirrorHeads = linked ? reconcileLinkedLayout({ ...input, projectRoot, defaultBranch }) : initializeLinkedLayout({ ...input, projectRoot, defaultBranch });
     for (const branch of input.branches) {
       const snapshotPath = snapshot.paths.get(branch.branchName);
       if (!snapshotPath) continue;
@@ -349,9 +771,9 @@ function ensureProjectWorktrees(input) {
         deletionMode: "git"
       });
     }
-    return input.branches.map((branch) => {
+    const states = input.branches.map((branch) => {
       const checkoutPath = branchPath(projectRoot, branch.branchName);
-      const divergence = aheadBehind(checkoutPath, branch.branchName);
+      const divergence = aheadBehind(checkoutPath, branch.branchName, input.primaryBranchName, defaultBranch);
       return {
         branchName: branch.branchName,
         branchPath: checkoutPath,
@@ -360,8 +782,18 @@ function ensureProjectWorktrees(input) {
         ...divergence
       };
     }).sort((left, right) => left.branchName.localeCompare(right.branchName));
-  } finally {
-    fs.rmSync(snapshot.root, { recursive: true, force: true });
+    persistReconciledProjectAndConsumeSnapshot(snapshot);
+    return states;
+  } catch (error) {
+    try {
+      rollbackProjectWorktreeSnapshot(snapshot);
+    } catch (recoveryError) {
+      throw new Error(
+        `Project worktree reconciliation failed and its snapshot could not be fully restored; recovery state is retained at ${snapshot.root}`,
+        { cause: new AggregateError([error, recoveryError]) }
+      );
+    }
+    throw error;
   }
 }
 function projectWorktreeOperationInProgress(checkoutPath) {
@@ -379,6 +811,8 @@ function createLinkedProjectBranch(input) {
   if (input.sourceBranchName === input.branchName) throw new Error("Source and target branch names must differ");
   const sourcePath = branchPath(input.projectRoot, input.sourceBranchName);
   const targetPath = branchPath(input.projectRoot, input.branchName);
+  assertNoSymlinkBranchPathComponents(input.projectRoot, sourcePath);
+  assertNoSymlinkBranchPathComponents(input.projectRoot, targetPath);
   if (!commonGitDirectory(sourcePath)) throw new Error(`Source worktree ${input.sourceBranchName} is unavailable`);
   if (projectWorktreeOperationInProgress(sourcePath)) {
     throw new Error(`Source worktree ${input.sourceBranchName} has an in-progress Git operation`);
@@ -394,25 +828,84 @@ function createLinkedProjectBranch(input) {
   });
   if (overlappingWorktree) throw new Error(`Project branch folder overlaps linked worktree ${overlappingWorktree}`);
   const sourceHead = git(sourcePath, ["rev-parse", "HEAD"], "resolve source branch head");
-  const snapshotRoot = createProjectWorktreeSnapshotRoot();
+  let branchCreated = false;
   try {
-    mirrorWorkingTree({ sourceRoot: sourcePath, targetRoot: snapshotRoot, sourceMode: "git", deletionMode: "all" });
     git(sourcePath, ["branch", input.branchName, sourceHead], `create project branch ${input.branchName}`);
+    branchCreated = true;
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    try {
-      git(sourcePath, ["worktree", "add", "--force", targetPath, input.branchName], `create linked worktree ${input.branchName}`);
-      mirrorWorkingTree({ sourceRoot: snapshotRoot, targetRoot: targetPath, sourceMode: "all", deletionMode: "git" });
-    } catch (error) {
-      fs.rmSync(targetPath, { recursive: true, force: true });
-      tryGit(sourcePath, ["worktree", "prune"]);
-      tryGit(sourcePath, ["branch", "-D", input.branchName]);
-      throw error;
-    }
+    assertNoSymlinkBranchPathComponents(input.projectRoot, targetPath);
+    git(
+      sourcePath,
+      ["worktree", "add", "--force", "--no-checkout", targetPath, input.branchName],
+      `create linked worktree ${input.branchName}`
+    );
+    configureProjectBranchTracking(targetPath, input.branchName, input.branchName);
+    assertNoSymlinkBranchPathComponents(input.projectRoot, targetPath);
+    git(targetPath, ["read-tree", sourceHead], `initialize linked worktree index ${input.branchName}`);
+    mirrorWorkingTree({ sourceRoot: sourcePath, targetRoot: targetPath, sourceMode: "git", deletionMode: "git" });
     return { branchPath: targetPath, baseCommitHash: sourceHead };
-  } finally {
-    fs.rmSync(snapshotRoot, { recursive: true, force: true });
+  } catch (error) {
+    if (branchCreated) {
+      let removeError;
+      try {
+        fs.rmSync(targetPath, { recursive: true, force: true });
+      } catch (cleanupError) {
+        removeError = cleanupError;
+      }
+      const prune = gitResult(sourcePath, ["worktree", "prune"]);
+      const deleteBranch = gitResult(sourcePath, ["branch", "-D", input.branchName]);
+      const cleanupFailures = [];
+      try {
+        fs.lstatSync(targetPath);
+        cleanupFailures.push(`target path remains at ${targetPath}`);
+      } catch (verificationError) {
+        const code = verificationError.code;
+        if (code !== "ENOENT" && code !== "ENOTDIR") {
+          cleanupFailures.push(
+            `could not verify target removal${removeError ? ` after ${removeError instanceof Error ? removeError.message : String(removeError)}` : ""}: ${verificationError instanceof Error ? verificationError.message : String(verificationError)}`
+          );
+        }
+      }
+      const worktrees = gitResult(sourcePath, ["worktree", "list", "--porcelain"]);
+      if (worktrees.exitCode !== 0) {
+        cleanupFailures.push(
+          `could not verify linked-worktree removal: ${worktrees.stderr || worktrees.stdout || `git exited ${worktrees.exitCode}`}`
+        );
+      } else {
+        const targetRegistered = worktrees.stdout.split(/\r?\n/).some((line) => line.startsWith("worktree ") && path.resolve(line.slice("worktree ".length)) === path.resolve(targetPath));
+        if (targetRegistered) {
+          cleanupFailures.push(
+            `linked worktree remains registered at ${targetPath}${prune.exitCode === 0 ? "" : ` (${prune.stderr || prune.stdout || `git exited ${prune.exitCode}`})`}`
+          );
+        }
+      }
+      const branchRef = gitResult(sourcePath, ["show-ref", "--verify", "--quiet", `refs/heads/${input.branchName}`]);
+      if (branchRef.exitCode === 0) {
+        cleanupFailures.push(
+          `branch ref remains${deleteBranch.exitCode === 0 ? "" : ` (${deleteBranch.stderr || deleteBranch.stdout || `git exited ${deleteBranch.exitCode}`})`}`
+        );
+      } else if (branchRef.exitCode !== 1) {
+        cleanupFailures.push(
+          `could not verify branch ref removal: ${branchRef.stderr || branchRef.stdout || `git exited ${branchRef.exitCode}`}`
+        );
+      }
+      if (cleanupFailures.length > 0) {
+        throw new ProjectBranchCreationRollbackIncompleteError(input.branchName, cleanupFailures, error);
+      }
+    }
+    throw error;
   }
 }
+function createOrRetryLinkedProjectBranch(input) {
+  if (input.pendingRetry) {
+    deleteLinkedProjectBranch({
+      projectRoot: input.projectRoot,
+      primaryBranchName: input.primaryBranchName,
+      branchName: input.branchName
+    });
+  }
+  return createLinkedProjectBranch(input);
+}
 function deleteLinkedProjectBranch(input) {
   validateManagedBranchName(input.primaryBranchName);
   validateManagedBranchName(input.branchName);
@@ -472,7 +965,13 @@ function pushProjectMirrorHeads(input) {
   for (const branchName of [...input.branchNames].sort()) {
     if (input.onlyBranches && !input.onlyBranches.has(branchName)) continue;
     const checkoutPath = branchPath(input.projectRoot, branchName);
-    const head = git(checkoutPath, ["rev-parse", "HEAD"], `resolve mirror head for ${branchName}`);
+    const head = input.publicationHeads ? input.publicationHeads.get(branchName) : git(checkoutPath, ["rev-parse", "HEAD"], `resolve mirror head for ${branchName}`);
+    if (!head || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(head)) {
+      throw new Error(`Missing exact publication head for project branch ${branchName}`);
+    }
+    if (!tryGit(checkoutPath, ["cat-file", "-e", `${head}^{commit}`])) {
+      throw new Error(`Exact publication head ${head} is unavailable for project branch ${branchName}`);
+    }
     if (projectWorktreeOperationInProgress(checkoutPath)) {
       results.push({ branchName, head, pushed: false, reason: "git_operation_in_progress" });
       continue;
@@ -484,7 +983,7 @@ function pushProjectMirrorHeads(input) {
         "push",
         "--no-recurse-submodules",
         input.mirrorUrl,
-        `+HEAD:refs/heads/${branchName}`
+        `+${head}:refs/heads/${branchName}`
       ],
       `push hidden project mirror for ${branchName}`
     );
@@ -492,7 +991,13 @@ function pushProjectMirrorHeads(input) {
   }
   return results;
 }
-function fastForwardProjectHeadsFromMirror(input) {
+function assertProjectMirrorHeadsPushed(results) {
+  const skipped = results.find((result) => !result.pushed);
+  if (skipped) {
+    throw new Error(`Hidden project mirror publication skipped ${skipped.branchName}${skipped.reason ? ` (${skipped.reason})` : ""}`);
+  }
+}
+function observeProjectMirrorHeads(input) {
   const primaryPath = branchPath(input.projectRoot, input.primaryBranchName);
   const fetch = gitResult(primaryPath, [
     ...gitTransportSecurityArgs(input.mirrorUrl, input.credentialHelper, input.credentialUsername),
@@ -509,30 +1014,102 @@ function fastForwardProjectHeadsFromMirror(input) {
     const previousHead = git(checkoutPath, ["rev-parse", "HEAD"], `resolve local project head ${branchName}`);
     const mirrorRef = `refs/r5d/mirror/${branchName}`;
     const mirrorHead = tryGit(primaryPath, ["show-ref", "--verify", "--quiet", mirrorRef]) ? git(primaryPath, ["rev-parse", mirrorRef], `resolve refreshed mirror head ${branchName}`) : null;
-    if (!mirrorHead || mirrorHead === previousHead || projectWorktreeOperationInProgress(checkoutPath) || !tryGit(checkoutPath, ["merge-base", "--is-ancestor", previousHead, mirrorHead])) {
-      return { branchName, previousHead, mirrorHead, fastForwarded: false };
+    const shouldMove = Boolean(
+      mirrorHead && mirrorHead !== previousHead && (input.allowNonFastForward || tryGit(checkoutPath, ["merge-base", "--is-ancestor", previousHead, mirrorHead]))
+    );
+    return {
+      branchName,
+      previousHead,
+      mirrorHead,
+      mode: input.allowNonFastForward ? "reseed" : "fast_forward",
+      shouldMove
+    };
+  });
+}
+function applyObservedProjectMirrorHeads(input) {
+  return [...input.observations].sort((left, right) => left.branchName.localeCompare(right.branchName)).map((observation) => {
+    const { branchName, mirrorHead } = observation;
+    const checkoutPath = branchPath(input.projectRoot, branchName);
+    const currentHead = git(checkoutPath, ["rev-parse", "HEAD"], `resolve local project head ${branchName}`);
+    if (!observation.shouldMove || !mirrorHead || currentHead === mirrorHead || currentHead !== observation.previousHead) {
+      return { branchName, previousHead: currentHead, mirrorHead, moved: false };
+    }
+    if (!tryGit(checkoutPath, ["cat-file", "-e", `${mirrorHead}^{commit}`])) {
+      throw new Error(`Observed hidden mirror head is no longer available for ${branchName}: ${mirrorHead}`);
     }
-    git(checkoutPath, ["update-ref", `refs/heads/${branchName}`, mirrorHead, previousHead], `fast-forward project branch ${branchName}`);
-    git(checkoutPath, ["reset", "--mixed", mirrorHead], `refresh project index ${branchName}`);
-    return { branchName, previousHead, mirrorHead, fastForwarded: true };
+    const mutationAllowed = () => !projectWorktreeOperationInProgress(checkoutPath) && input.branchMutationAllowed?.(branchName, checkoutPath) !== false;
+    if (!mutationAllowed()) {
+      return { branchName, previousHead: currentHead, mirrorHead, moved: false };
+    }
+    if (observation.mode === "reseed") {
+      preserveHead(checkoutPath);
+      if (!mutationAllowed()) return { branchName, previousHead: currentHead, mirrorHead, moved: false };
+    }
+    const action = observation.mode === "reseed" ? "reseed" : "fast-forward";
+    git(checkoutPath, ["read-tree", "--reset", mirrorHead], `${action} project index ${branchName}`);
+    git(checkoutPath, ["update-ref", `refs/heads/${branchName}`, mirrorHead, currentHead], `${action} project branch ${branchName}`);
+    return { branchName, previousHead: currentHead, mirrorHead, moved: true };
+  });
+}
+function updateProjectHeadsFromMirror(input) {
+  const observations = observeProjectMirrorHeads(input);
+  return applyObservedProjectMirrorHeads({
+    projectRoot: input.projectRoot,
+    primaryBranchName: input.primaryBranchName,
+    observations,
+    branchMutationAllowed: input.branchMutationAllowed
   });
 }
+function fastForwardProjectHeadsFromMirror(input) {
+  return updateProjectHeadsFromMirror({ ...input, allowNonFastForward: false }).map(({ moved, ...state }) => ({
+    ...state,
+    fastForwarded: moved
+  }));
+}
+function reseedProjectHeadsFromMirror(input) {
+  return updateProjectHeadsFromMirror({ ...input, allowNonFastForward: true }).map(({ moved, ...state }) => ({
+    ...state,
+    reseeded: moved
+  }));
+}
 const projectWorktreesTestHarness = {
   commandArgs: gitCommandArgs,
-  configureRepository
+  configureRepository,
+  createPreparedSnapshot(input) {
+    return { root: snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot).root };
+  },
+  consumeSnapshot(snapshotRoot) {
+    const manifest = readSnapshotManifest(snapshotRoot);
+    advanceSnapshotState(snapshotRoot, manifest, "consumed");
+  },
+  persistProjectAndConsumeSnapshot(snapshotRoot, afterProjectTreeFsync) {
+    const manifest = readSnapshotManifest(snapshotRoot);
+    persistReconciledProjectAndConsumeSnapshot({ root: snapshotRoot, manifest, paths: /* @__PURE__ */ new Map() }, afterProjectTreeFsync);
+  },
+  snapshotState(snapshotRoot) {
+    return readSnapshotManifest(snapshotRoot).state;
+  }
 };
 export {
   PROJECT_WORKTREE_SNAPSHOT_PREFIX,
-  cleanupStaleProjectWorktreeSnapshots,
+  ProjectBranchCreationRollbackIncompleteError,
+  applyObservedProjectMirrorHeads,
+  assertProjectMirrorHeadsPushed,
   createLinkedProjectBranch,
+  createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch,
   deleteProjectMirrorBranch,
   ensureProjectWorktrees,
   fastForwardProjectHeadsFromMirror,
   hasLinkedProjectWorktreeLayout,
+  observeProjectMirrorHeads,
+  projectBranchMayExistAfterCreateFailure,
+  projectOriginBranchName,
   projectWorktreeConfigurationFingerprint,
   projectWorktreeOperationInProgress,
   projectWorktreesTestHarness,
   pushProjectMirrorHeads,
-  removeProjectWorktrees
+  recoverStaleProjectWorktreeSnapshots,
+  removeProjectWorktrees,
+  reseedProjectHeadsFromMirror
 };