@ricsam/r5d-worker 0.0.103 → 0.0.104

package/dist/cjs/main.cjs

@@ -3509,6 +3509,7 @@ async function startWorker(options) {
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
   let lastWorkspaceSyncMirrorObservationMs = 0;
+  let lastInventoriedMissingCheckouts;
   let sessionArtifactSyncRequestsInFlight = 0;
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
@@ -3566,8 +3567,15 @@ async function startWorker(options) {
     const primaryBranchName = primaryProjectBranch(project);
     const connection = projectConnection(project);
     const sourcePath = configuredProjectBranchPath(projectsRoot, project, branchName);
-    if (requireLocalBranch || hasProjectWorktree(sourcePath)) {
-      (0, import_project_worktrees.deleteLinkedProjectBranch)({ projectRoot, primaryBranchName, branchName });
+    const primaryPath = configuredProjectBranchPath(projectsRoot, project, primaryBranchName);
+    if (requireLocalBranch || import_node_fs.default.existsSync(sourcePath) && hasProjectWorktree(primaryPath)) {
+      const deleted = (0, import_project_worktrees.deleteLinkedProjectBranch)({ projectRoot, primaryBranchName, branchName });
+      if (deleted.movedAsidePath) {
+        process.stderr.write(
+          `[r5d-worker] set aside ${sourcePath}, which was not a linked worktree of ${project.projectPath}, at ${deleted.movedAsidePath}
+`
+        );
+      }
     }
     const planSourcePath = import_node_path.default.join(planRoot, project.projectId, ...branchName.split("/"));
     import_node_fs.default.rmSync(planSourcePath, { recursive: true, force: true });
@@ -3640,11 +3648,17 @@ async function startWorker(options) {
     if (branchName === primaryBranchName) {
       throw new Error(`Cannot hide preserve-only project branch ${project.projectId}/${branchName} because it is the active anchor`);
     }
-    (0, import_project_worktrees.deleteLinkedProjectBranch)({
+    const deleted = (0, import_project_worktrees.deleteLinkedProjectBranch)({
       projectRoot: configuredProjectRoot(projectsRoot, project),
       primaryBranchName,
       branchName
     });
+    if (deleted.movedAsidePath) {
+      process.stderr.write(
+        `[r5d-worker] set aside ${branchPath}, which was not a linked worktree of ${project.projectPath}, at ${deleted.movedAsidePath}
+`
+      );
+    }
     import_node_fs.default.rmSync(import_node_path.default.join(planRoot, project.projectId, ...branchName.split("/")), { recursive: true, force: true });
     readyProjectIds.delete(project.projectId);
     reconciledProjectConfigFingerprints.delete(project.projectId);
@@ -3813,6 +3827,40 @@ async function startWorker(options) {
     });
   };
   const projectBranchMountBusy = (projectId, branchName, branchPath) => !readyProjectIds.has(projectId) || projectBranchMountActivityBusy(projectId, branchName, branchPath);
+  const inventoryConfiguredProjectCheckouts = () => {
+    const inventory = { projects: [], missingCheckouts: [] };
+    for (const project of projectConfigById.values()) {
+      if (project.executionDisabled || !readyProjectIds.has(project.projectId) || project.branches.length === 0) {
+        inventory.projects.push(project);
+        continue;
+      }
+      const checkouts = (0, import_project_worktrees.inventoryProjectCheckouts)({
+        projectRoot: configuredProjectRoot(projectsRoot, project),
+        primaryBranchName: primaryProjectBranch(project),
+        branchNames: project.branches.map(({ branchName }) => branchName)
+      });
+      if (checkouts.missingCheckouts.length === 0) {
+        inventory.projects.push(project);
+        continue;
+      }
+      for (const missing of checkouts.missingCheckouts) inventory.missingCheckouts.push({ projectId: project.projectId, ...missing });
+      const linked = new Set(checkouts.linkedBranchNames);
+      inventory.projects.push({ ...project, branches: project.branches.filter(({ branchName }) => linked.has(branchName)) });
+    }
+    inventory.missingCheckouts.sort(
+      (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
+    );
+    return inventory;
+  };
+  const reportedMissingCheckouts = (inventory) => inventory.missingCheckouts.map(({ projectId, branchName, reason }) => ({ projectId, branchName, reason }));
+  const logMissingCheckouts = (inventory) => {
+    if (inventory.missingCheckouts.length === 0) return;
+    const described = inventory.missingCheckouts.map(({ checkoutPath, reason }) => `${checkoutPath} (${reason === "missing" ? "directory missing" : "not a linked worktree of the project"})`).join(", ");
+    process.stderr.write(
+      `[r5d-worker] skipping ${inventory.missingCheckouts.length} configured project checkout(s) this cycle: ${described}; delete the branch through the platform or reconnect this worker to recreate the checkout
+`
+    );
+  };
   const buildWorkspaceMounts = (projects = projectConfigById.values()) => {
     const mounts = [];
     const creatorLocalIncarnations = new Map(
@@ -4091,9 +4139,9 @@ async function startWorker(options) {
       (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
     );
   };
-  const captureProjectHeadsForWorkspacePublication = async () => {
+  const captureProjectHeadsForWorkspacePublication = async (projects = projectConfigById.values()) => {
     const heads = /* @__PURE__ */ new Map();
-    for (const project of projectConfigById.values()) {
+    for (const project of projects) {
       if (!readyProjectIds.has(project.projectId)) continue;
       for (const branch of project.branches) {
         const branchPath = configuredProjectBranchPath(projectsRoot, project, branch.branchName);
@@ -4103,9 +4151,9 @@ async function startWorker(options) {
     }
     return heads;
   };
-  const pushChangedProjectHeads = async (activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, suppressedMountIds = /* @__PURE__ */ new Set()) => {
+  const pushChangedProjectHeads = async (activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, suppressedMountIds = /* @__PURE__ */ new Set(), projects = projectConfigById.values()) => {
     const active = new Set(activeMountIds);
-    for (const project of projectConfigById.values()) {
+    for (const project of projects) {
       if (!readyProjectIds.has(project.projectId) || !(0, import_repository_transition_policy.repositoryMirrorWritesAllowed)(project)) continue;
       const changed = /* @__PURE__ */ new Map();
       for (const branch of project.branches) {
@@ -4205,7 +4253,7 @@ async function startWorker(options) {
   };
   const observeProjectHeadsBeforeOuterWorkspace = async (input) => {
     const observationStartedAt = Date.now();
-    const eligibleProjects = [...projectConfigById.values()].filter(
+    const eligibleProjects = [...input.projects ?? projectConfigById.values()].filter(
       (project) => !project.executionDisabled && readyProjectIds.has(project.projectId) && project.branches.length > 0
     );
     try {
@@ -4315,7 +4363,7 @@ async function startWorker(options) {
       }
     }
   };
-  const mapWorkspaceGitResult = async (attemptId, trigger, result) => {
+  const mapWorkspaceGitResult = async (attemptId, trigger, result, missingCheckouts) => {
     const activeProjectBranchPublications = (0, import_workspace_publication_evidence.activeProjectBranchPublicationEvidence)([...projectConfigById.values()], result.activeMountIds);
     return {
       type: "workspace_sync",
@@ -4333,6 +4381,7 @@ async function startWorker(options) {
       affectedPaths: result.affectedPaths,
       activeMountIds: result.activeMountIds,
       skippedMountIds: result.skippedMountIds,
+      ...missingCheckouts ? { missingCheckouts } : {},
       activeProjectBranchPublications,
       discardedPaths: [],
       localChangesDiscarded: false,
@@ -4360,6 +4409,7 @@ async function startWorker(options) {
       affectedPaths: [],
       discardedPaths: [],
       localChangesDiscarded: false,
+      ...lastInventoriedMissingCheckouts ? { missingCheckouts: lastInventoriedMissingCheckouts } : {},
       error: error instanceof Error ? error.message : String(error)
     };
   };
@@ -4368,7 +4418,11 @@ async function startWorker(options) {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
     }
-    const configuredMounts = buildWorkspaceMounts();
+    const checkoutInventory = inventoryConfiguredProjectCheckouts();
+    logMissingCheckouts(checkoutInventory);
+    const missingCheckouts = reportedMissingCheckouts(checkoutInventory);
+    lastInventoriedMissingCheckouts = missingCheckouts;
+    const configuredMounts = buildWorkspaceMounts(checkoutInventory.projects);
     if (input.resetToCanonical) {
       workspaceProjectionLedger.reset();
       const resetHasBusyLiveMount = configuredMounts.some(
@@ -4379,7 +4433,8 @@ async function startWorker(options) {
       }
       const observedProjectHeads2 = await observeProjectHeadsBeforeOuterWorkspace({
         allowNonFastForward: true,
-        failClosed: true
+        failClosed: true,
+        projects: checkoutInventory.projects
       });
       const reset = await (0, import_workspace_git_sync.resetWorkspaceGit)({
         workspacePath: workspaceShadowRoot,
@@ -4407,6 +4462,7 @@ async function startWorker(options) {
         affectedPaths: reset.discardedPaths,
         activeMountIds: reset.activeMountIds,
         skippedMountIds: reset.skippedMountIds,
+        missingCheckouts,
         discardedPaths: reset.discardedPaths,
         localChangesDiscarded: reset.discardedPaths.length > 0 || reset.startingHead !== reset.remoteHead
       };
@@ -4414,7 +4470,7 @@ async function startWorker(options) {
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
     const mounts = outerRemediation ? (0, import_workspace_git_sync.workspaceGitMountsForRemediation)(configuredMounts) : configuredMounts;
     if (outerRemediation) workspaceProjectionLedger.reset();
-    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
+    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false, projects: checkoutInventory.projects });
     const expectedMirrorHeads = /* @__PURE__ */ new Map();
     for (const bundle of observedProjectHeads) {
       for (const observation of bundle.observations) {
@@ -4426,7 +4482,7 @@ async function startWorker(options) {
         ({ projectId, observations }) => observations.filter(({ shouldMove }) => shouldMove).map(({ branchName }) => projectMountId(projectId, branchName))
       )
     );
-    const publicationHeads = outerRemediation ? /* @__PURE__ */ new Map() : await captureProjectHeadsForWorkspacePublication();
+    const publicationHeads = outerRemediation ? /* @__PURE__ */ new Map() : await captureProjectHeadsForWorkspacePublication(checkoutInventory.projects);
     const result = await (0, import_workspace_git_sync.synchronizeWorkspaceGit)({
       attemptId: input.attemptId,
       workerLabel: label,
@@ -4446,7 +4502,14 @@ async function startWorker(options) {
       advertisedRemoteHead: projectMirrorFetchSkippingEnabled && !outerRemediation ? advertisedWorkspaceHead : void 0,
       assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : async ({ activeMountIds, publishedHead }) => {
-        await pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, inboundMoveMountIds);
+        await pushChangedProjectHeads(
+          activeMountIds,
+          publishedHead,
+          publicationHeads,
+          expectedMirrorHeads,
+          inboundMoveMountIds,
+          checkoutInventory.projects
+        );
       },
       hydrationHooks: workspaceHydrationTransactionHooks
     });
@@ -4465,7 +4528,7 @@ async function startWorker(options) {
         result.localHead ?? result.remoteHead
       );
     }
-    const mapped = await mapWorkspaceGitResult(input.attemptId, input.trigger, result);
+    const mapped = await mapWorkspaceGitResult(input.attemptId, input.trigger, result, missingCheckouts);
     if (!outerRemediation) {
       workspaceProjectionLedger.recordCycle({ result: mapped, mounts, projectedMutationTokens: result.projectedMutationTokens });
     }

package/dist/cjs/package.json

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

package/dist/cjs/project-worktrees.cjs

@@ -28,10 +28,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var project_worktrees_exports = {};
 __export(project_worktrees_exports, {
+  PROJECT_REMOVED_CHECKOUTS_DIRECTORY: () => PROJECT_REMOVED_CHECKOUTS_DIRECTORY,
   PROJECT_WORKTREE_SNAPSHOT_PREFIX: () => PROJECT_WORKTREE_SNAPSHOT_PREFIX,
   ProjectBranchCreationRollbackIncompleteError: () => ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads: () => applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed: () => assertProjectMirrorHeadsPushed,
+  classifyProjectCheckout: () => classifyProjectCheckout,
   computeLocalProjectMirrorRefsTokens: () => computeLocalProjectMirrorRefsTokens,
   createLinkedProjectBranch: () => createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch: () => createOrRetryLinkedProjectBranch,
@@ -40,6 +42,7 @@ __export(project_worktrees_exports, {
   ensureProjectWorktrees: () => ensureProjectWorktrees,
   fastForwardProjectHeadsFromMirror: () => fastForwardProjectHeadsFromMirror,
   hasLinkedProjectWorktreeLayout: () => hasLinkedProjectWorktreeLayout,
+  inventoryProjectCheckouts: () => inventoryProjectCheckouts,
   observeProjectMirrorHeads: () => observeProjectMirrorHeads,
   projectBranchMayExistAfterCreateFailure: () => projectBranchMayExistAfterCreateFailure,
   projectOriginBranchName: () => projectOriginBranchName,
@@ -334,6 +337,8 @@ function normalizeSnapshotManifest(value) {
   if (record.state !== "building" && record.state !== "prepared" && record.state !== "restoring" && record.state !== "consumed") {
     throw new Error("Project worktree snapshot manifest has an invalid state");
   }
+  const scope = record.scope === void 0 ? "project" : record.scope;
+  if (scope !== "project" && scope !== "branches") throw new Error("Project worktree snapshot manifest has an invalid scope");
   if (!Number.isSafeInteger(record.ownerProcessId) || record.ownerProcessId <= 0) {
     throw new Error("Project worktree snapshot manifest has an invalid owner process");
   }
@@ -369,6 +374,7 @@ function normalizeSnapshotManifest(value) {
   return {
     version: PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION,
     state: record.state,
+    scope,
     ownerProcessId: record.ownerProcessId,
     ownerSessionId: record.ownerSessionId,
     projectRoot: record.projectRoot,
@@ -405,7 +411,7 @@ function writeSnapshotManifest(snapshotRoot, manifest) {
   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)) {
+  if (expected.scope !== actual.scope || 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");
   }
 }
@@ -472,7 +478,7 @@ function assertNoOutstandingSnapshotForProject(temporaryRoot, projectRoot) {
     }
   }
 }
-function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress) {
+function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress, scope = "project") {
   const resolvedProjectRoot = import_node_path.default.resolve(projectRoot);
   const resolvedTemporaryRoot = import_node_path.default.resolve(temporaryRoot ?? import_node_os.default.tmpdir());
   assertNoOutstandingSnapshotForProject(resolvedTemporaryRoot, resolvedProjectRoot);
@@ -493,6 +499,7 @@ function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress) {
     let manifest = writeSnapshotManifest(root, {
       version: PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION,
       state: "building",
+      scope,
       ownerProcessId: process.pid,
       ownerSessionId: PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID,
       projectRoot: resolvedProjectRoot,
@@ -599,7 +606,7 @@ function restoreProjectWorktreeSnapshot(snapshotRoot, manifest, onProgress) {
   const presentBranches = current.branches.filter(({ snapshotPresent }) => snapshotPresent);
   const destinationParent = import_node_path.default.dirname(current.projectRoot);
   import_node_fs.default.mkdirSync(destinationParent, { recursive: true });
-  const canMoveWholeSnapshot = presentBranches.length > 0 && (current.state === "restoring" || treesRootStat !== null && treesRootStat.dev === import_node_fs.default.lstatSync(destinationParent).dev);
+  const canMoveWholeSnapshot = current.scope === "project" && presentBranches.length > 0 && (current.state === "restoring" || treesRootStat !== null && treesRootStat.dev === import_node_fs.default.lstatSync(destinationParent).dev);
   if (canMoveWholeSnapshot) {
     if (current.state === "prepared") current = advanceSnapshotState(snapshotRoot, current, "restoring");
     onProgress?.({
@@ -690,8 +697,12 @@ function consumeAndRemoveProjectWorktreeSnapshot(snapshotRoot, manifest) {
   } catch {
   }
 }
-function persistReconciledProjectAndConsumeSnapshot(snapshot, afterProjectTreeFsync) {
-  fsyncTree(snapshot.manifest.projectRoot);
+function persistReconciledProjectAndConsumeSnapshot(snapshot, afterProjectTreeFsync, durabilityPaths) {
+  if (durabilityPaths) {
+    for (const durabilityPath of durabilityPaths) if (import_node_fs.default.existsSync(durabilityPath)) fsyncTree(durabilityPath);
+  } else {
+    fsyncTree(snapshot.manifest.projectRoot);
+  }
   fsyncManagedProjectRootEntry(snapshot.manifest.projectRoot);
   afterProjectTreeFsync?.();
   consumeAndRemoveProjectWorktreeSnapshot(snapshot.root, snapshot.manifest);
@@ -989,8 +1000,10 @@ async function reconcileLinkedLayout(input) {
   await configureRepository({ ...input, primaryPath });
   await tryGitAsync(primaryPath, ["worktree", "prune"]);
   await fetchProjectHeads({ ...input, primaryPath });
+  const primaryCommonDir = await commonGitDirectoryAsync(primaryPath);
+  if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
   const mirrorHeads = /* @__PURE__ */ new Map();
-  const mutatedBranches = /* @__PURE__ */ new Set();
+  const plan = [];
   for (const branch of input.branches) {
     const checkoutPath = branchPath(input.projectRoot, branch.branchName);
     const resolved = await seedForBranch({
@@ -1000,24 +1013,30 @@ async function reconcileLinkedLayout(input) {
       requireMirrorHead: input.exactMirrorBranches?.has(branch.branchName)
     });
     mirrorHeads.set(branch.branchName, resolved.mirrorHead);
-    if (branch.branchName === input.primaryBranchName || await commonGitDirectoryAsync(checkoutPath) === await commonGitDirectoryAsync(primaryPath)) {
-      const currentHead = await gitAsync(checkoutPath, ["rev-parse", "HEAD"], `resolve linked worktree head ${branch.branchName}`);
-      if (currentHead === resolved.seed) continue;
-      input.beforeDestructiveMutation();
-      mutatedBranches.add(branch.branchName);
-      await preserveHead(checkoutPath);
-      await gitAsync(checkoutPath, ["reset", "--hard", resolved.seed], `anchor linked worktree ${branch.branchName}`);
+    const linked = branch.branchName === input.primaryBranchName || gitDirectoryKind(checkoutPath) !== null && await commonGitDirectoryAsync(checkoutPath) === primaryCommonDir;
+    if (!linked) {
+      plan.push({ branchName: branch.branchName, checkoutPath, seed: resolved.seed, action: "recreate" });
       continue;
     }
-    input.beforeDestructiveMutation();
-    mutatedBranches.add(branch.branchName);
-    import_node_fs.default.rmSync(checkoutPath, { recursive: true, force: true });
-    await gitAsync(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 });
+    const currentHead = await gitAsync(checkoutPath, ["rev-parse", "HEAD"], `resolve linked worktree head ${branch.branchName}`);
+    plan.push({ branchName: branch.branchName, checkoutPath, seed: resolved.seed, action: currentHead === resolved.seed ? "keep" : "reset" });
+  }
+  const mutatedBranches = new Set(plan.filter(({ action }) => action !== "keep").map(({ branchName }) => branchName));
+  if (mutatedBranches.size > 0) input.beforeDestructiveMutation(mutatedBranches);
+  for (const entry of plan) {
+    if (entry.action === "keep") continue;
+    if (entry.action === "reset") {
+      await preserveHead(entry.checkoutPath);
+      await gitAsync(entry.checkoutPath, ["reset", "--hard", entry.seed], `anchor linked worktree ${entry.branchName}`);
+      continue;
+    }
+    import_node_fs.default.rmSync(entry.checkoutPath, { recursive: true, force: true });
+    await gitAsync(primaryPath, ["branch", "-f", entry.branchName, entry.seed], `anchor project branch ${entry.branchName}`);
+    import_node_fs.default.mkdirSync(import_node_path.default.dirname(entry.checkoutPath), { recursive: true });
     await gitAsync(
       primaryPath,
-      ["worktree", "add", "--force", checkoutPath, branch.branchName],
-      `create linked worktree ${branch.branchName}`
+      ["worktree", "add", "--force", entry.checkoutPath, entry.branchName],
+      `create linked worktree ${entry.branchName}`
     );
   }
   return { mirrorHeads, mutatedBranches };
@@ -1044,8 +1063,14 @@ async function ensureProjectWorktrees(input) {
   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, input.onSnapshotProgress);
+  const ensureSnapshot = (branchNames) => {
+    snapshot ??= snapshotBranchTrees(
+      projectRoot,
+      branchNames ? input.branches.filter(({ branchName }) => branchNames.has(branchName)) : input.branches,
+      snapshotStorageRoot,
+      input.onSnapshotProgress,
+      branchNames ? "branches" : "project"
+    );
     return snapshot;
   };
   try {
@@ -1097,7 +1122,21 @@ async function ensureProjectWorktrees(input) {
       });
     }
     states.sort((left, right) => left.branchName.localeCompare(right.branchName));
-    if (snapshot) persistReconciledProjectAndConsumeSnapshot(snapshot);
+    if (snapshot) {
+      const primaryGitDirectory = import_node_path.default.join(branchPath(projectRoot, input.primaryBranchName), ".git");
+      persistReconciledProjectAndConsumeSnapshot(
+        snapshot,
+        void 0,
+        snapshot.manifest.scope === "branches" ? [
+          ...snapshot.manifest.branches.map(({ branchName }) => branchPath(projectRoot, branchName)),
+          // Branch refs and worktree registrations moved in the shared
+          // administrative directory; objects are fsynced by git itself.
+          import_node_path.default.join(primaryGitDirectory, "refs"),
+          import_node_path.default.join(primaryGitDirectory, "packed-refs"),
+          import_node_path.default.join(primaryGitDirectory, "worktrees")
+        ] : void 0
+      );
+    }
     return states;
   } catch (error) {
     if (!snapshot) throw error;
@@ -1243,6 +1282,53 @@ function createOrRetryLinkedProjectBranch(input) {
   }
   return createLinkedProjectBranch(input);
 }
+function classifyProjectCheckout(input) {
+  const checkoutPath = branchPath(input.projectRoot, input.branchName);
+  let stat;
+  try {
+    stat = import_node_fs.default.lstatSync(checkoutPath);
+  } catch {
+    return "missing";
+  }
+  if (!stat.isDirectory()) return "not_a_worktree";
+  if (input.branchName === input.primaryBranchName) return gitDirectoryKind(checkoutPath) === "directory" ? "linked" : "not_a_worktree";
+  if (gitDirectoryKind(checkoutPath) !== "file") return "not_a_worktree";
+  const gitDirectory = perWorktreeGitDirectory(checkoutPath);
+  if (!gitDirectory) return "not_a_worktree";
+  let registry;
+  let registered;
+  try {
+    registry = import_node_fs.default.realpathSync(import_node_path.default.join(branchPath(input.projectRoot, input.primaryBranchName), ".git", "worktrees"));
+    registered = import_node_fs.default.realpathSync(gitDirectory);
+  } catch {
+    return "not_a_worktree";
+  }
+  const relative = import_node_path.default.relative(registry, registered);
+  if (!relative || relative === ".." || relative.startsWith(`..${import_node_path.default.sep}`) || import_node_path.default.isAbsolute(relative)) return "not_a_worktree";
+  return "linked";
+}
+function inventoryProjectCheckouts(input) {
+  const states = input.branchNames.map((branchName) => ({
+    branchName,
+    checkoutPath: branchPath(input.projectRoot, branchName),
+    state: classifyProjectCheckout({ ...input, branchName })
+  }));
+  const primaryLinked = states.some(({ branchName, state }) => branchName === input.primaryBranchName && state === "linked");
+  const inventory = { linkedBranchNames: [], missingCheckouts: [] };
+  for (const { branchName, checkoutPath, state } of states) {
+    if (primaryLinked && state === "linked") inventory.linkedBranchNames.push(branchName);
+    else inventory.missingCheckouts.push({ branchName, checkoutPath, reason: state === "linked" ? "not_a_worktree" : state });
+  }
+  return inventory;
+}
+const PROJECT_REMOVED_CHECKOUTS_DIRECTORY = ".r5d-removed";
+function moveProjectCheckoutAside(projectRoot, branchName, checkoutPath) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const target = import_node_path.default.join(projectRoot, PROJECT_REMOVED_CHECKOUTS_DIRECTORY, ...`${branchName}-${timestamp}`.split("/"));
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(target), { recursive: true });
+  import_node_fs.default.renameSync(checkoutPath, target);
+  return target;
+}
 function deleteLinkedProjectBranch(input) {
   (0, import_managed_paths.validateManagedBranchName)(input.primaryBranchName);
   (0, import_managed_paths.validateManagedBranchName)(input.branchName);
@@ -1251,15 +1337,18 @@ function deleteLinkedProjectBranch(input) {
   const checkoutPath = branchPath(input.projectRoot, input.branchName);
   const primaryCommonDir = commonGitDirectory(primaryPath);
   if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
+  let movedAsidePath;
   if (import_node_fs.default.existsSync(checkoutPath)) {
-    const checkoutCommonDir = commonGitDirectory(checkoutPath);
+    const checkoutCommonDir = import_node_fs.default.lstatSync(checkoutPath).isDirectory() ? commonGitDirectory(checkoutPath) : null;
     if (checkoutCommonDir !== primaryCommonDir) {
-      throw new Error(`Project branch path ${input.branchName} is not a linked worktree of the configured project`);
-    }
-    if (projectWorktreeOperationInProgress(checkoutPath)) {
-      throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
+      movedAsidePath = moveProjectCheckoutAside(input.projectRoot, input.branchName, checkoutPath);
+      tryGit(primaryPath, ["worktree", "prune"]);
+    } else {
+      if (projectWorktreeOperationInProgress(checkoutPath)) {
+        throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
+      }
+      git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
     }
-    git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
   } else {
     tryGit(primaryPath, ["worktree", "prune"]);
   }
@@ -1267,7 +1356,7 @@ function deleteLinkedProjectBranch(input) {
   if (tryGit(primaryPath, ["show-ref", "--verify", "--quiet", branchRef])) {
     git(primaryPath, ["branch", "-D", input.branchName], `delete project branch ${input.branchName}`);
   }
-  return { branchName: input.branchName };
+  return { branchName: input.branchName, ...movedAsidePath ? { movedAsidePath } : {} };
 }
 function removeProjectWorktrees(input) {
   const projectRoot = import_node_path.default.resolve(input.projectRoot);
@@ -1526,7 +1615,7 @@ const projectWorktreesTestHarness = {
   commandArgs: gitCommandArgs,
   configureRepository,
   createPreparedSnapshot(input) {
-    return { root: snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot).root };
+    return { root: snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot, void 0, input.scope).root };
   },
   consumeSnapshot(snapshotRoot) {
     const manifest = readSnapshotManifest(snapshotRoot);
@@ -1542,10 +1631,12 @@ const projectWorktreesTestHarness = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PROJECT_REMOVED_CHECKOUTS_DIRECTORY,
   PROJECT_WORKTREE_SNAPSHOT_PREFIX,
   ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
+  classifyProjectCheckout,
   computeLocalProjectMirrorRefsTokens,
   createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch,
@@ -1554,6 +1645,7 @@ const projectWorktreesTestHarness = {
   ensureProjectWorktrees,
   fastForwardProjectHeadsFromMirror,
   hasLinkedProjectWorktreeLayout,
+  inventoryProjectCheckouts,
   observeProjectMirrorHeads,
   projectBranchMayExistAfterCreateFailure,
   projectOriginBranchName,

package/dist/mjs/main.mjs

@@ -65,6 +65,7 @@ import {
   deleteLinkedProjectBranch,
   deleteProjectMirrorBranch,
   ensureProjectWorktrees,
+  inventoryProjectCheckouts,
   observeProjectMirrorHeads,
   projectBranchMayExistAfterCreateFailure,
   projectOriginBranchName,
@@ -3519,6 +3520,7 @@ async function startWorker(options) {
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
   let lastWorkspaceSyncMirrorObservationMs = 0;
+  let lastInventoriedMissingCheckouts;
   let sessionArtifactSyncRequestsInFlight = 0;
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
@@ -3576,8 +3578,15 @@ async function startWorker(options) {
     const primaryBranchName = primaryProjectBranch(project);
     const connection = projectConnection(project);
     const sourcePath = configuredProjectBranchPath(projectsRoot, project, branchName);
-    if (requireLocalBranch || hasProjectWorktree(sourcePath)) {
-      deleteLinkedProjectBranch({ projectRoot, primaryBranchName, branchName });
+    const primaryPath = configuredProjectBranchPath(projectsRoot, project, primaryBranchName);
+    if (requireLocalBranch || fs.existsSync(sourcePath) && hasProjectWorktree(primaryPath)) {
+      const deleted = deleteLinkedProjectBranch({ projectRoot, primaryBranchName, branchName });
+      if (deleted.movedAsidePath) {
+        process.stderr.write(
+          `[r5d-worker] set aside ${sourcePath}, which was not a linked worktree of ${project.projectPath}, at ${deleted.movedAsidePath}
+`
+        );
+      }
     }
     const planSourcePath = path.join(planRoot, project.projectId, ...branchName.split("/"));
     fs.rmSync(planSourcePath, { recursive: true, force: true });
@@ -3650,11 +3659,17 @@ async function startWorker(options) {
     if (branchName === primaryBranchName) {
       throw new Error(`Cannot hide preserve-only project branch ${project.projectId}/${branchName} because it is the active anchor`);
     }
-    deleteLinkedProjectBranch({
+    const deleted = deleteLinkedProjectBranch({
       projectRoot: configuredProjectRoot(projectsRoot, project),
       primaryBranchName,
       branchName
     });
+    if (deleted.movedAsidePath) {
+      process.stderr.write(
+        `[r5d-worker] set aside ${branchPath}, which was not a linked worktree of ${project.projectPath}, at ${deleted.movedAsidePath}
+`
+      );
+    }
     fs.rmSync(path.join(planRoot, project.projectId, ...branchName.split("/")), { recursive: true, force: true });
     readyProjectIds.delete(project.projectId);
     reconciledProjectConfigFingerprints.delete(project.projectId);
@@ -3823,6 +3838,40 @@ async function startWorker(options) {
     });
   };
   const projectBranchMountBusy = (projectId, branchName, branchPath) => !readyProjectIds.has(projectId) || projectBranchMountActivityBusy(projectId, branchName, branchPath);
+  const inventoryConfiguredProjectCheckouts = () => {
+    const inventory = { projects: [], missingCheckouts: [] };
+    for (const project of projectConfigById.values()) {
+      if (project.executionDisabled || !readyProjectIds.has(project.projectId) || project.branches.length === 0) {
+        inventory.projects.push(project);
+        continue;
+      }
+      const checkouts = inventoryProjectCheckouts({
+        projectRoot: configuredProjectRoot(projectsRoot, project),
+        primaryBranchName: primaryProjectBranch(project),
+        branchNames: project.branches.map(({ branchName }) => branchName)
+      });
+      if (checkouts.missingCheckouts.length === 0) {
+        inventory.projects.push(project);
+        continue;
+      }
+      for (const missing of checkouts.missingCheckouts) inventory.missingCheckouts.push({ projectId: project.projectId, ...missing });
+      const linked = new Set(checkouts.linkedBranchNames);
+      inventory.projects.push({ ...project, branches: project.branches.filter(({ branchName }) => linked.has(branchName)) });
+    }
+    inventory.missingCheckouts.sort(
+      (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
+    );
+    return inventory;
+  };
+  const reportedMissingCheckouts = (inventory) => inventory.missingCheckouts.map(({ projectId, branchName, reason }) => ({ projectId, branchName, reason }));
+  const logMissingCheckouts = (inventory) => {
+    if (inventory.missingCheckouts.length === 0) return;
+    const described = inventory.missingCheckouts.map(({ checkoutPath, reason }) => `${checkoutPath} (${reason === "missing" ? "directory missing" : "not a linked worktree of the project"})`).join(", ");
+    process.stderr.write(
+      `[r5d-worker] skipping ${inventory.missingCheckouts.length} configured project checkout(s) this cycle: ${described}; delete the branch through the platform or reconnect this worker to recreate the checkout
+`
+    );
+  };
   const buildWorkspaceMounts = (projects = projectConfigById.values()) => {
     const mounts = [];
     const creatorLocalIncarnations = new Map(
@@ -4101,9 +4150,9 @@ async function startWorker(options) {
       (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
     );
   };
-  const captureProjectHeadsForWorkspacePublication = async () => {
+  const captureProjectHeadsForWorkspacePublication = async (projects = projectConfigById.values()) => {
     const heads = /* @__PURE__ */ new Map();
-    for (const project of projectConfigById.values()) {
+    for (const project of projects) {
       if (!readyProjectIds.has(project.projectId)) continue;
       for (const branch of project.branches) {
         const branchPath = configuredProjectBranchPath(projectsRoot, project, branch.branchName);
@@ -4113,9 +4162,9 @@ async function startWorker(options) {
     }
     return heads;
   };
-  const pushChangedProjectHeads = async (activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, suppressedMountIds = /* @__PURE__ */ new Set()) => {
+  const pushChangedProjectHeads = async (activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, suppressedMountIds = /* @__PURE__ */ new Set(), projects = projectConfigById.values()) => {
     const active = new Set(activeMountIds);
-    for (const project of projectConfigById.values()) {
+    for (const project of projects) {
       if (!readyProjectIds.has(project.projectId) || !repositoryMirrorWritesAllowed(project)) continue;
       const changed = /* @__PURE__ */ new Map();
       for (const branch of project.branches) {
@@ -4215,7 +4264,7 @@ async function startWorker(options) {
   };
   const observeProjectHeadsBeforeOuterWorkspace = async (input) => {
     const observationStartedAt = Date.now();
-    const eligibleProjects = [...projectConfigById.values()].filter(
+    const eligibleProjects = [...input.projects ?? projectConfigById.values()].filter(
       (project) => !project.executionDisabled && readyProjectIds.has(project.projectId) && project.branches.length > 0
     );
     try {
@@ -4325,7 +4374,7 @@ async function startWorker(options) {
       }
     }
   };
-  const mapWorkspaceGitResult = async (attemptId, trigger, result) => {
+  const mapWorkspaceGitResult = async (attemptId, trigger, result, missingCheckouts) => {
     const activeProjectBranchPublications = activeProjectBranchPublicationEvidence([...projectConfigById.values()], result.activeMountIds);
     return {
       type: "workspace_sync",
@@ -4343,6 +4392,7 @@ async function startWorker(options) {
       affectedPaths: result.affectedPaths,
       activeMountIds: result.activeMountIds,
       skippedMountIds: result.skippedMountIds,
+      ...missingCheckouts ? { missingCheckouts } : {},
       activeProjectBranchPublications,
       discardedPaths: [],
       localChangesDiscarded: false,
@@ -4370,6 +4420,7 @@ async function startWorker(options) {
       affectedPaths: [],
       discardedPaths: [],
       localChangesDiscarded: false,
+      ...lastInventoriedMissingCheckouts ? { missingCheckouts: lastInventoriedMissingCheckouts } : {},
       error: error instanceof Error ? error.message : String(error)
     };
   };
@@ -4378,7 +4429,11 @@ async function startWorker(options) {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
     }
-    const configuredMounts = buildWorkspaceMounts();
+    const checkoutInventory = inventoryConfiguredProjectCheckouts();
+    logMissingCheckouts(checkoutInventory);
+    const missingCheckouts = reportedMissingCheckouts(checkoutInventory);
+    lastInventoriedMissingCheckouts = missingCheckouts;
+    const configuredMounts = buildWorkspaceMounts(checkoutInventory.projects);
     if (input.resetToCanonical) {
       workspaceProjectionLedger.reset();
       const resetHasBusyLiveMount = configuredMounts.some(
@@ -4389,7 +4444,8 @@ async function startWorker(options) {
       }
       const observedProjectHeads2 = await observeProjectHeadsBeforeOuterWorkspace({
         allowNonFastForward: true,
-        failClosed: true
+        failClosed: true,
+        projects: checkoutInventory.projects
       });
       const reset = await resetWorkspaceGit({
         workspacePath: workspaceShadowRoot,
@@ -4417,6 +4473,7 @@ async function startWorker(options) {
         affectedPaths: reset.discardedPaths,
         activeMountIds: reset.activeMountIds,
         skippedMountIds: reset.skippedMountIds,
+        missingCheckouts,
         discardedPaths: reset.discardedPaths,
         localChangesDiscarded: reset.discardedPaths.length > 0 || reset.startingHead !== reset.remoteHead
       };
@@ -4424,7 +4481,7 @@ async function startWorker(options) {
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
     const mounts = outerRemediation ? workspaceGitMountsForRemediation(configuredMounts) : configuredMounts;
     if (outerRemediation) workspaceProjectionLedger.reset();
-    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
+    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false, projects: checkoutInventory.projects });
     const expectedMirrorHeads = /* @__PURE__ */ new Map();
     for (const bundle of observedProjectHeads) {
       for (const observation of bundle.observations) {
@@ -4436,7 +4493,7 @@ async function startWorker(options) {
         ({ projectId, observations }) => observations.filter(({ shouldMove }) => shouldMove).map(({ branchName }) => projectMountId(projectId, branchName))
       )
     );
-    const publicationHeads = outerRemediation ? /* @__PURE__ */ new Map() : await captureProjectHeadsForWorkspacePublication();
+    const publicationHeads = outerRemediation ? /* @__PURE__ */ new Map() : await captureProjectHeadsForWorkspacePublication(checkoutInventory.projects);
     const result = await synchronizeWorkspaceGit({
       attemptId: input.attemptId,
       workerLabel: label,
@@ -4456,7 +4513,14 @@ async function startWorker(options) {
       advertisedRemoteHead: projectMirrorFetchSkippingEnabled && !outerRemediation ? advertisedWorkspaceHead : void 0,
       assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : async ({ activeMountIds, publishedHead }) => {
-        await pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, inboundMoveMountIds);
+        await pushChangedProjectHeads(
+          activeMountIds,
+          publishedHead,
+          publicationHeads,
+          expectedMirrorHeads,
+          inboundMoveMountIds,
+          checkoutInventory.projects
+        );
       },
       hydrationHooks: workspaceHydrationTransactionHooks
     });
@@ -4475,7 +4539,7 @@ async function startWorker(options) {
         result.localHead ?? result.remoteHead
       );
     }
-    const mapped = await mapWorkspaceGitResult(input.attemptId, input.trigger, result);
+    const mapped = await mapWorkspaceGitResult(input.attemptId, input.trigger, result, missingCheckouts);
     if (!outerRemediation) {
       workspaceProjectionLedger.recordCycle({ result: mapped, mounts, projectedMutationTokens: result.projectedMutationTokens });
     }

package/dist/mjs/package.json

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

package/dist/mjs/project-worktrees.mjs

@@ -287,6 +287,8 @@ function normalizeSnapshotManifest(value) {
   if (record.state !== "building" && record.state !== "prepared" && record.state !== "restoring" && record.state !== "consumed") {
     throw new Error("Project worktree snapshot manifest has an invalid state");
   }
+  const scope = record.scope === void 0 ? "project" : record.scope;
+  if (scope !== "project" && scope !== "branches") throw new Error("Project worktree snapshot manifest has an invalid scope");
   if (!Number.isSafeInteger(record.ownerProcessId) || record.ownerProcessId <= 0) {
     throw new Error("Project worktree snapshot manifest has an invalid owner process");
   }
@@ -322,6 +324,7 @@ function normalizeSnapshotManifest(value) {
   return {
     version: PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION,
     state: record.state,
+    scope,
     ownerProcessId: record.ownerProcessId,
     ownerSessionId: record.ownerSessionId,
     projectRoot: record.projectRoot,
@@ -358,7 +361,7 @@ function writeSnapshotManifest(snapshotRoot, manifest) {
   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)) {
+  if (expected.scope !== actual.scope || 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");
   }
 }
@@ -425,7 +428,7 @@ function assertNoOutstandingSnapshotForProject(temporaryRoot, projectRoot) {
     }
   }
 }
-function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress) {
+function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress, scope = "project") {
   const resolvedProjectRoot = path.resolve(projectRoot);
   const resolvedTemporaryRoot = path.resolve(temporaryRoot ?? os.tmpdir());
   assertNoOutstandingSnapshotForProject(resolvedTemporaryRoot, resolvedProjectRoot);
@@ -446,6 +449,7 @@ function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress) {
     let manifest = writeSnapshotManifest(root, {
       version: PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION,
       state: "building",
+      scope,
       ownerProcessId: process.pid,
       ownerSessionId: PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID,
       projectRoot: resolvedProjectRoot,
@@ -552,7 +556,7 @@ function restoreProjectWorktreeSnapshot(snapshotRoot, manifest, onProgress) {
   const presentBranches = current.branches.filter(({ snapshotPresent }) => snapshotPresent);
   const destinationParent = path.dirname(current.projectRoot);
   fs.mkdirSync(destinationParent, { recursive: true });
-  const canMoveWholeSnapshot = presentBranches.length > 0 && (current.state === "restoring" || treesRootStat !== null && treesRootStat.dev === fs.lstatSync(destinationParent).dev);
+  const canMoveWholeSnapshot = current.scope === "project" && presentBranches.length > 0 && (current.state === "restoring" || treesRootStat !== null && treesRootStat.dev === fs.lstatSync(destinationParent).dev);
   if (canMoveWholeSnapshot) {
     if (current.state === "prepared") current = advanceSnapshotState(snapshotRoot, current, "restoring");
     onProgress?.({
@@ -643,8 +647,12 @@ function consumeAndRemoveProjectWorktreeSnapshot(snapshotRoot, manifest) {
   } catch {
   }
 }
-function persistReconciledProjectAndConsumeSnapshot(snapshot, afterProjectTreeFsync) {
-  fsyncTree(snapshot.manifest.projectRoot);
+function persistReconciledProjectAndConsumeSnapshot(snapshot, afterProjectTreeFsync, durabilityPaths) {
+  if (durabilityPaths) {
+    for (const durabilityPath of durabilityPaths) if (fs.existsSync(durabilityPath)) fsyncTree(durabilityPath);
+  } else {
+    fsyncTree(snapshot.manifest.projectRoot);
+  }
   fsyncManagedProjectRootEntry(snapshot.manifest.projectRoot);
   afterProjectTreeFsync?.();
   consumeAndRemoveProjectWorktreeSnapshot(snapshot.root, snapshot.manifest);
@@ -942,8 +950,10 @@ async function reconcileLinkedLayout(input) {
   await configureRepository({ ...input, primaryPath });
   await tryGitAsync(primaryPath, ["worktree", "prune"]);
   await fetchProjectHeads({ ...input, primaryPath });
+  const primaryCommonDir = await commonGitDirectoryAsync(primaryPath);
+  if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
   const mirrorHeads = /* @__PURE__ */ new Map();
-  const mutatedBranches = /* @__PURE__ */ new Set();
+  const plan = [];
   for (const branch of input.branches) {
     const checkoutPath = branchPath(input.projectRoot, branch.branchName);
     const resolved = await seedForBranch({
@@ -953,24 +963,30 @@ async function reconcileLinkedLayout(input) {
       requireMirrorHead: input.exactMirrorBranches?.has(branch.branchName)
     });
     mirrorHeads.set(branch.branchName, resolved.mirrorHead);
-    if (branch.branchName === input.primaryBranchName || await commonGitDirectoryAsync(checkoutPath) === await commonGitDirectoryAsync(primaryPath)) {
-      const currentHead = await gitAsync(checkoutPath, ["rev-parse", "HEAD"], `resolve linked worktree head ${branch.branchName}`);
-      if (currentHead === resolved.seed) continue;
-      input.beforeDestructiveMutation();
-      mutatedBranches.add(branch.branchName);
-      await preserveHead(checkoutPath);
-      await gitAsync(checkoutPath, ["reset", "--hard", resolved.seed], `anchor linked worktree ${branch.branchName}`);
+    const linked = branch.branchName === input.primaryBranchName || gitDirectoryKind(checkoutPath) !== null && await commonGitDirectoryAsync(checkoutPath) === primaryCommonDir;
+    if (!linked) {
+      plan.push({ branchName: branch.branchName, checkoutPath, seed: resolved.seed, action: "recreate" });
       continue;
     }
-    input.beforeDestructiveMutation();
-    mutatedBranches.add(branch.branchName);
-    fs.rmSync(checkoutPath, { recursive: true, force: true });
-    await gitAsync(primaryPath, ["branch", "-f", branch.branchName, resolved.seed], `anchor project branch ${branch.branchName}`);
-    fs.mkdirSync(path.dirname(checkoutPath), { recursive: true });
+    const currentHead = await gitAsync(checkoutPath, ["rev-parse", "HEAD"], `resolve linked worktree head ${branch.branchName}`);
+    plan.push({ branchName: branch.branchName, checkoutPath, seed: resolved.seed, action: currentHead === resolved.seed ? "keep" : "reset" });
+  }
+  const mutatedBranches = new Set(plan.filter(({ action }) => action !== "keep").map(({ branchName }) => branchName));
+  if (mutatedBranches.size > 0) input.beforeDestructiveMutation(mutatedBranches);
+  for (const entry of plan) {
+    if (entry.action === "keep") continue;
+    if (entry.action === "reset") {
+      await preserveHead(entry.checkoutPath);
+      await gitAsync(entry.checkoutPath, ["reset", "--hard", entry.seed], `anchor linked worktree ${entry.branchName}`);
+      continue;
+    }
+    fs.rmSync(entry.checkoutPath, { recursive: true, force: true });
+    await gitAsync(primaryPath, ["branch", "-f", entry.branchName, entry.seed], `anchor project branch ${entry.branchName}`);
+    fs.mkdirSync(path.dirname(entry.checkoutPath), { recursive: true });
     await gitAsync(
       primaryPath,
-      ["worktree", "add", "--force", checkoutPath, branch.branchName],
-      `create linked worktree ${branch.branchName}`
+      ["worktree", "add", "--force", entry.checkoutPath, entry.branchName],
+      `create linked worktree ${entry.branchName}`
     );
   }
   return { mirrorHeads, mutatedBranches };
@@ -997,8 +1013,14 @@ async function ensureProjectWorktrees(input) {
   const snapshotStorageRoot = path.resolve(input.snapshotRoot ?? os.tmpdir());
   assertNoOutstandingSnapshotForProject(snapshotStorageRoot, projectRoot);
   let snapshot;
-  const ensureSnapshot = () => {
-    snapshot ??= snapshotBranchTrees(projectRoot, input.branches, snapshotStorageRoot, input.onSnapshotProgress);
+  const ensureSnapshot = (branchNames) => {
+    snapshot ??= snapshotBranchTrees(
+      projectRoot,
+      branchNames ? input.branches.filter(({ branchName }) => branchNames.has(branchName)) : input.branches,
+      snapshotStorageRoot,
+      input.onSnapshotProgress,
+      branchNames ? "branches" : "project"
+    );
     return snapshot;
   };
   try {
@@ -1050,7 +1072,21 @@ async function ensureProjectWorktrees(input) {
       });
     }
     states.sort((left, right) => left.branchName.localeCompare(right.branchName));
-    if (snapshot) persistReconciledProjectAndConsumeSnapshot(snapshot);
+    if (snapshot) {
+      const primaryGitDirectory = path.join(branchPath(projectRoot, input.primaryBranchName), ".git");
+      persistReconciledProjectAndConsumeSnapshot(
+        snapshot,
+        void 0,
+        snapshot.manifest.scope === "branches" ? [
+          ...snapshot.manifest.branches.map(({ branchName }) => branchPath(projectRoot, branchName)),
+          // Branch refs and worktree registrations moved in the shared
+          // administrative directory; objects are fsynced by git itself.
+          path.join(primaryGitDirectory, "refs"),
+          path.join(primaryGitDirectory, "packed-refs"),
+          path.join(primaryGitDirectory, "worktrees")
+        ] : void 0
+      );
+    }
     return states;
   } catch (error) {
     if (!snapshot) throw error;
@@ -1196,6 +1232,53 @@ function createOrRetryLinkedProjectBranch(input) {
   }
   return createLinkedProjectBranch(input);
 }
+function classifyProjectCheckout(input) {
+  const checkoutPath = branchPath(input.projectRoot, input.branchName);
+  let stat;
+  try {
+    stat = fs.lstatSync(checkoutPath);
+  } catch {
+    return "missing";
+  }
+  if (!stat.isDirectory()) return "not_a_worktree";
+  if (input.branchName === input.primaryBranchName) return gitDirectoryKind(checkoutPath) === "directory" ? "linked" : "not_a_worktree";
+  if (gitDirectoryKind(checkoutPath) !== "file") return "not_a_worktree";
+  const gitDirectory = perWorktreeGitDirectory(checkoutPath);
+  if (!gitDirectory) return "not_a_worktree";
+  let registry;
+  let registered;
+  try {
+    registry = fs.realpathSync(path.join(branchPath(input.projectRoot, input.primaryBranchName), ".git", "worktrees"));
+    registered = fs.realpathSync(gitDirectory);
+  } catch {
+    return "not_a_worktree";
+  }
+  const relative = path.relative(registry, registered);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return "not_a_worktree";
+  return "linked";
+}
+function inventoryProjectCheckouts(input) {
+  const states = input.branchNames.map((branchName) => ({
+    branchName,
+    checkoutPath: branchPath(input.projectRoot, branchName),
+    state: classifyProjectCheckout({ ...input, branchName })
+  }));
+  const primaryLinked = states.some(({ branchName, state }) => branchName === input.primaryBranchName && state === "linked");
+  const inventory = { linkedBranchNames: [], missingCheckouts: [] };
+  for (const { branchName, checkoutPath, state } of states) {
+    if (primaryLinked && state === "linked") inventory.linkedBranchNames.push(branchName);
+    else inventory.missingCheckouts.push({ branchName, checkoutPath, reason: state === "linked" ? "not_a_worktree" : state });
+  }
+  return inventory;
+}
+const PROJECT_REMOVED_CHECKOUTS_DIRECTORY = ".r5d-removed";
+function moveProjectCheckoutAside(projectRoot, branchName, checkoutPath) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const target = path.join(projectRoot, PROJECT_REMOVED_CHECKOUTS_DIRECTORY, ...`${branchName}-${timestamp}`.split("/"));
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.renameSync(checkoutPath, target);
+  return target;
+}
 function deleteLinkedProjectBranch(input) {
   validateManagedBranchName(input.primaryBranchName);
   validateManagedBranchName(input.branchName);
@@ -1204,15 +1287,18 @@ function deleteLinkedProjectBranch(input) {
   const checkoutPath = branchPath(input.projectRoot, input.branchName);
   const primaryCommonDir = commonGitDirectory(primaryPath);
   if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
+  let movedAsidePath;
   if (fs.existsSync(checkoutPath)) {
-    const checkoutCommonDir = commonGitDirectory(checkoutPath);
+    const checkoutCommonDir = fs.lstatSync(checkoutPath).isDirectory() ? commonGitDirectory(checkoutPath) : null;
     if (checkoutCommonDir !== primaryCommonDir) {
-      throw new Error(`Project branch path ${input.branchName} is not a linked worktree of the configured project`);
-    }
-    if (projectWorktreeOperationInProgress(checkoutPath)) {
-      throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
+      movedAsidePath = moveProjectCheckoutAside(input.projectRoot, input.branchName, checkoutPath);
+      tryGit(primaryPath, ["worktree", "prune"]);
+    } else {
+      if (projectWorktreeOperationInProgress(checkoutPath)) {
+        throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
+      }
+      git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
     }
-    git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
   } else {
     tryGit(primaryPath, ["worktree", "prune"]);
   }
@@ -1220,7 +1306,7 @@ function deleteLinkedProjectBranch(input) {
   if (tryGit(primaryPath, ["show-ref", "--verify", "--quiet", branchRef])) {
     git(primaryPath, ["branch", "-D", input.branchName], `delete project branch ${input.branchName}`);
   }
-  return { branchName: input.branchName };
+  return { branchName: input.branchName, ...movedAsidePath ? { movedAsidePath } : {} };
 }
 function removeProjectWorktrees(input) {
   const projectRoot = path.resolve(input.projectRoot);
@@ -1479,7 +1565,7 @@ const projectWorktreesTestHarness = {
   commandArgs: gitCommandArgs,
   configureRepository,
   createPreparedSnapshot(input) {
-    return { root: snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot).root };
+    return { root: snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot, void 0, input.scope).root };
   },
   consumeSnapshot(snapshotRoot) {
     const manifest = readSnapshotManifest(snapshotRoot);
@@ -1494,10 +1580,12 @@ const projectWorktreesTestHarness = {
   }
 };
 export {
+  PROJECT_REMOVED_CHECKOUTS_DIRECTORY,
   PROJECT_WORKTREE_SNAPSHOT_PREFIX,
   ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
+  classifyProjectCheckout,
   computeLocalProjectMirrorRefsTokens,
   createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch,
@@ -1506,6 +1594,7 @@ export {
   ensureProjectWorktrees,
   fastForwardProjectHeadsFromMirror,
   hasLinkedProjectWorktreeLayout,
+  inventoryProjectCheckouts,
   observeProjectMirrorHeads,
   projectBranchMayExistAfterCreateFailure,
   projectOriginBranchName,

package/dist/types/main.d.ts

@@ -93,6 +93,12 @@ type WorkspaceSyncResult = {
     affectedPaths: string[];
     activeMountIds?: string[];
     skippedMountIds?: string[];
+    /** Configured checkouts this cycle excluded because their directory is absent or is not a linked worktree of the project. */
+    missingCheckouts?: Array<{
+        projectId: string;
+        branchName: string;
+        reason: "missing" | "not_a_worktree";
+    }>;
     activeProjectBranchPublications?: Array<{
         branchId: string;
         projectId: string;

package/dist/types/project-worktrees.d.ts

@@ -1,9 +1,17 @@
 import { type ProjectMirrorMount, type ProjectMirrorRefsTokens } from "./project-mirror-refs-token";
 export declare const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 declare const PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION: 1;
+/**
+ * `project` snapshots cover every configured branch and restore by replacing
+ * the whole project root. `branches` snapshots cover only the checkouts one
+ * reconciliation rewrites and restore those paths individually, so a rollback
+ * never touches a checkout the transaction did not.
+ */
+type ProjectWorktreeSnapshotScope = "project" | "branches";
 type ProjectWorktreeSnapshotManifest = {
     version: typeof PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION;
     state: "building" | "prepared" | "restoring" | "consumed";
+    scope: ProjectWorktreeSnapshotScope;
     ownerProcessId: number;
     ownerSessionId: string;
     projectRoot: string;
@@ -157,12 +165,50 @@ export declare function createOrRetryLinkedProjectBranch(input: {
     branchPath: string;
     baseCommitHash: string;
 };
+export type ProjectCheckoutState = "linked" | "missing" | "not_a_worktree";
+export type ProjectCheckoutInventory = {
+    /** Branches whose checkout is this project's primary clone or one of its linked worktrees. */
+    linkedBranchNames: string[];
+    missingCheckouts: Array<{
+        branchName: string;
+        checkoutPath: string;
+        reason: Exclude<ProjectCheckoutState, "linked">;
+    }>;
+};
+/**
+ * Classify one configured branch checkout without spawning git, cheap enough
+ * to run for every configured branch on every sync cycle. The primary
+ * checkout is `linked` when its `.git` is a directory; another branch is
+ * `linked` when its `.git` pointer file resolves into that primary clone's
+ * `.git/worktrees` registry and the registered directory still exists.
+ * `missing` means the checkout path is absent. Everything else (a hydrated
+ * directory that never became a checkout, a foreign clone, a pointer to a
+ * pruned registration) is `not_a_worktree`.
+ */
+export declare function classifyProjectCheckout(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+    branchName: string;
+}): ProjectCheckoutState;
+/**
+ * Partition a ready project's configured branches into checkouts a sync cycle
+ * may use and checkouts it must skip. A primary clone that is not linked takes
+ * every branch with it: nothing can be observed or published through it.
+ */
+export declare function inventoryProjectCheckouts(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+    branchNames: readonly string[];
+}): ProjectCheckoutInventory;
+export declare const PROJECT_REMOVED_CHECKOUTS_DIRECTORY = ".r5d-removed";
 export declare function deleteLinkedProjectBranch(input: {
     projectRoot: string;
     primaryBranchName: string;
     branchName: string;
 }): {
     branchName: string;
+    /** Where a path that was not this project's linked worktree was set aside instead of being deleted. */
+    movedAsidePath?: string;
 };
 export declare function removeProjectWorktrees(input: {
     projectRoot: string;
@@ -290,6 +336,7 @@ export declare const projectWorktreesTestHarness: {
         projectRoot: string;
         branches: readonly ProjectWorktreeBranch[];
         temporaryRoot: string;
+        scope?: ProjectWorktreeSnapshotScope;
     }): {
         root: string;
     };

package/package.json

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