@ricsam/r5d-worker 0.0.101 → 0.0.103

package/dist/cjs/package.json

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

package/dist/cjs/project-mirror-fetch-policy.cjs

@@ -18,24 +18,65 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var project_mirror_fetch_policy_exports = {};
 __export(project_mirror_fetch_policy_exports, {
-  PROJECT_MIRROR_FETCH_BACKSTOP_MS: () => PROJECT_MIRROR_FETCH_BACKSTOP_MS,
+  parseProjectMirrorRefsTokensMessage: () => parseProjectMirrorRefsTokensMessage,
+  planProjectMirrorObservationFetch: () => planProjectMirrorObservationFetch,
   projectMirrorFetchDecision: () => projectMirrorFetchDecision
 });
 module.exports = __toCommonJS(project_mirror_fetch_policy_exports);
-const PROJECT_MIRROR_FETCH_BACKSTOP_MS = 10 * 6e4;
 function projectMirrorFetchDecision(input) {
   if (!input.skippingEnabled) return { fetch: true, reason: "skipping_disabled" };
   if (input.advertisedToken === void 0) return { fetch: true, reason: "no_advertised_token" };
   if (input.fetchedToken === void 0) return { fetch: true, reason: "never_fetched" };
   if (input.advertisedToken !== input.fetchedToken) return { fetch: true, reason: "token_changed" };
-  const backstopMs = input.backstopMs ?? PROJECT_MIRROR_FETCH_BACKSTOP_MS;
-  if (input.lastFetchAtMs === void 0 || input.nowMs - input.lastFetchAtMs >= backstopMs) {
-    return { fetch: true, reason: "backstop_elapsed" };
-  }
   return { fetch: false, reason: "token_match" };
 }
+function planProjectMirrorObservationFetch(input) {
+  if (!input.skippingEnabled) return { scope: "project", reason: "skipping_disabled" };
+  if (input.advertisedMountTokens === void 0) {
+    const decision = projectMirrorFetchDecision({
+      advertisedToken: input.advertisedProjectToken,
+      fetchedToken: input.fetchedProjectToken,
+      skippingEnabled: true
+    });
+    return decision.fetch ? { scope: "project", reason: decision.reason } : { scope: "none" };
+  }
+  const mounts = [];
+  for (const branchName of [...input.branchNames].sort()) {
+    const decision = projectMirrorFetchDecision({
+      advertisedToken: input.advertisedMountTokens.get(branchName),
+      fetchedToken: input.fetchedMountTokens.get(branchName),
+      skippingEnabled: true
+    });
+    if (decision.fetch) mounts.push({ branchName, reason: decision.reason });
+  }
+  return mounts.length === 0 ? { scope: "none" } : { scope: "mounts", mounts };
+}
+const TOKEN_RE = /^[0-9a-f]{64}$/;
+const GIT_OBJECT_NAME_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function parseProjectMirrorRefsTokensMessage(message) {
+  const projectTokens = /* @__PURE__ */ new Map();
+  if (message.tokens && typeof message.tokens === "object") {
+    for (const [projectId, token] of Object.entries(message.tokens)) {
+      if (typeof token === "string" && TOKEN_RE.test(token)) projectTokens.set(projectId, token);
+    }
+  }
+  const mountTokens = /* @__PURE__ */ new Map();
+  if (message.mountTokens && typeof message.mountTokens === "object") {
+    for (const [projectId, tokensByBranch] of Object.entries(message.mountTokens)) {
+      if (!tokensByBranch || typeof tokensByBranch !== "object") continue;
+      const perMount = /* @__PURE__ */ new Map();
+      for (const [branchName, token] of Object.entries(tokensByBranch)) {
+        if (typeof token === "string" && TOKEN_RE.test(token)) perMount.set(branchName, token);
+      }
+      mountTokens.set(projectId, perMount);
+    }
+  }
+  const workspaceHead = typeof message.workspaceHead === "string" && GIT_OBJECT_NAME_RE.test(message.workspaceHead) ? message.workspaceHead : void 0;
+  return { projectTokens, mountTokens, workspaceHead };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  PROJECT_MIRROR_FETCH_BACKSTOP_MS,
+  parseProjectMirrorRefsTokensMessage,
+  planProjectMirrorObservationFetch,
   projectMirrorFetchDecision
 });

package/dist/cjs/project-mirror-refs-token.cjs

@@ -18,19 +18,38 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var project_mirror_refs_token_exports = {};
 __export(project_mirror_refs_token_exports, {
+  PROJECT_MIRROR_REFS_TOKEN_NAMESPACES: () => PROJECT_MIRROR_REFS_TOKEN_NAMESPACES,
+  PROJECT_MIRROR_REF_LISTING_FORMAT: () => PROJECT_MIRROR_REF_LISTING_FORMAT,
   PROJECT_MIRROR_REF_PREFIX: () => PROJECT_MIRROR_REF_PREFIX,
   PROJECT_SERVER_SYNCED_REF_PREFIX: () => PROJECT_SERVER_SYNCED_REF_PREFIX,
   canonicalizeLocalProjectMirrorRefs: () => canonicalizeLocalProjectMirrorRefs,
-  hashProjectMirrorRefs: () => hashProjectMirrorRefs
+  hashProjectMirrorRefs: () => hashProjectMirrorRefs,
+  parseProjectMirrorRefListing: () => parseProjectMirrorRefListing,
+  projectMirrorMountRefs: () => projectMirrorMountRefs,
+  projectMirrorRefsTokens: () => projectMirrorRefsTokens
 });
 module.exports = __toCommonJS(project_mirror_refs_token_exports);
 var import_node_crypto = require("node:crypto");
+const PROJECT_MIRROR_REFS_TOKEN_NAMESPACES = ["refs/heads/", "refs/r5d/server-synced/"];
 const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
 const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+const PROJECT_MIRROR_REF_LISTING_FORMAT = "--format=%(objectname) %(refname)";
+const GIT_OBJECT_NAME_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 function hashProjectMirrorRefs(refs) {
   const lines = refs.map(({ objectName, refname }) => `${objectName} ${refname}`).sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
   return (0, import_node_crypto.createHash)("sha256").update(lines.join("\n")).digest("hex");
 }
+function parseProjectMirrorRefListing(output, options = {}) {
+  return output.split(/\r?\n/).filter(Boolean).map((row) => {
+    const separator = row.indexOf(" ");
+    const objectName = separator < 0 ? "" : row.slice(0, separator);
+    const refname = separator < 0 ? "" : row.slice(separator + 1);
+    if (!GIT_OBJECT_NAME_RE.test(objectName) || refname.length === 0 || options.namespaces !== void 0 && !options.namespaces.some((prefix) => refname.startsWith(prefix))) {
+      throw new Error(`Invalid ref listing row: ${row}`);
+    }
+    return { refname, objectName };
+  });
+}
 function canonicalizeLocalProjectMirrorRefs(refs) {
   const canonical = [];
   for (const { refname, objectName } of refs) {
@@ -42,10 +61,25 @@ function canonicalizeLocalProjectMirrorRefs(refs) {
   }
   return canonical;
 }
+function projectMirrorMountRefs(refs, mount) {
+  const headRef = `refs/heads/${mount.branchName}`;
+  const handoffPrefix = `${PROJECT_SERVER_SYNCED_REF_PREFIX}${mount.branchId}/`;
+  return refs.filter(({ refname }) => refname === headRef || refname.startsWith(handoffPrefix));
+}
+function projectMirrorRefsTokens(refs, mounts) {
+  const mountTokens = /* @__PURE__ */ new Map();
+  for (const mount of mounts) mountTokens.set(mount.branchName, hashProjectMirrorRefs(projectMirrorMountRefs(refs, mount)));
+  return { project: hashProjectMirrorRefs(refs), mounts: mountTokens };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PROJECT_MIRROR_REFS_TOKEN_NAMESPACES,
+  PROJECT_MIRROR_REF_LISTING_FORMAT,
   PROJECT_MIRROR_REF_PREFIX,
   PROJECT_SERVER_SYNCED_REF_PREFIX,
   canonicalizeLocalProjectMirrorRefs,
-  hashProjectMirrorRefs
+  hashProjectMirrorRefs,
+  parseProjectMirrorRefListing,
+  projectMirrorMountRefs,
+  projectMirrorRefsTokens
 });

package/dist/cjs/project-worktrees.cjs

@@ -32,7 +32,7 @@ __export(project_worktrees_exports, {
   ProjectBranchCreationRollbackIncompleteError: () => ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads: () => applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed: () => assertProjectMirrorHeadsPushed,
-  computeLocalProjectMirrorRefsToken: () => computeLocalProjectMirrorRefsToken,
+  computeLocalProjectMirrorRefsTokens: () => computeLocalProjectMirrorRefsTokens,
   createLinkedProjectBranch: () => createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch: () => createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch: () => deleteLinkedProjectBranch,
@@ -1174,8 +1174,12 @@ function createLinkedProjectBranch(input) {
     );
     configureProjectBranchTracking(targetPath, input.branchName, input.branchName);
     assertNoSymlinkBranchPathComponents(input.projectRoot, targetPath);
-    git(targetPath, ["read-tree", sourceHead], `initialize linked worktree index ${input.branchName}`);
-    (0, import_working_tree_mirror.mirrorWorkingTree)({ sourceRoot: sourcePath, targetRoot: targetPath, sourceMode: "git", deletionMode: "git" });
+    if (input.workingTree === "carry") {
+      git(targetPath, ["read-tree", sourceHead], `initialize linked worktree index ${input.branchName}`);
+      (0, import_working_tree_mirror.mirrorWorkingTree)({ sourceRoot: sourcePath, targetRoot: targetPath, sourceMode: "git", deletionMode: "git" });
+    } else {
+      git(targetPath, ["reset", "--hard", sourceHead], `check out linked worktree ${input.branchName}`);
+    }
     return { branchPath: targetPath, baseCommitHash: sourceHead };
   } catch (error) {
     if (branchCreated) {
@@ -1365,24 +1369,46 @@ function assertProjectMirrorHeadsPushed(results) {
     throw new Error(`Hidden project mirror publication skipped ${skipped.branchName}${skipped.reason ? ` (${skipped.reason})` : ""}`);
   }
 }
+const PROJECT_MIRROR_FETCH_REFSPECS = ["+refs/heads/*:refs/r5d/mirror/*", "+refs/r5d/server-synced/*:refs/r5d/server-synced/*"];
+function projectMirrorMountFetchRefspecs(branchName, branchId) {
+  (0, import_managed_paths.validateManagedBranchName)(branchName);
+  if (branchId !== void 0 && !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(branchId)) throw new Error(`Invalid branch id for ${branchName}`);
+  return [
+    `+refs/heads/${branchName}:refs/r5d/mirror/${branchName}`,
+    branchId === void 0 ? "+refs/r5d/server-synced/*:refs/r5d/server-synced/*" : `+refs/r5d/server-synced/${branchId}/*:refs/r5d/server-synced/${branchId}/*`
+  ];
+}
+async function fetchProjectMirrorRefs(input) {
+  const fetch = (refspecs) => gitResultAsync(
+    input.primaryPath,
+    [
+      ...(0, import_git_process_environment.gitTransportSecurityArgs)(input.mirrorUrl, input.credentialHelper, input.credentialUsername),
+      "fetch",
+      "--no-recurse-submodules",
+      "--prune",
+      input.mirrorUrl,
+      ...refspecs
+    ],
+    PROJECT_GIT_TRANSPORT_TIMEOUT_MS
+  );
+  if (input.fetchOnlyBranches && input.fetchOnlyBranches.size > 0) {
+    const refspecs = [...input.fetchOnlyBranches].sort().flatMap((branchName) => projectMirrorMountFetchRefspecs(branchName, input.branchIds?.get(branchName)));
+    const scoped = await fetch(refspecs);
+    if (scoped.exitCode === 0) return;
+    if (!/(couldn't find remote ref|no such ref)/i.test(`${scoped.stderr}
+${scoped.stdout}`)) {
+      throw new Error(`Refresh project head mirror: ${scoped.stderr || scoped.stdout || `git exited ${scoped.exitCode}`}`);
+    }
+  }
+  const whole = await fetch(PROJECT_MIRROR_FETCH_REFSPECS);
+  if (whole.exitCode !== 0) {
+    throw new Error(`Refresh project head mirror: ${whole.stderr || whole.stdout || `git exited ${whole.exitCode}`}`);
+  }
+}
 async function observeProjectMirrorHeads(input) {
   const primaryPath = branchPath(input.projectRoot, input.primaryBranchName);
-  if (input.refreshRemote !== false) {
-    const fetch = await gitResultAsync(
-      primaryPath,
-      [
-        ...(0, import_git_process_environment.gitTransportSecurityArgs)(input.mirrorUrl, input.credentialHelper, input.credentialUsername),
-        "fetch",
-        "--no-recurse-submodules",
-        "--prune",
-        input.mirrorUrl,
-        "+refs/heads/*:refs/r5d/mirror/*",
-        "+refs/r5d/server-synced/*:refs/r5d/server-synced/*"
-      ],
-      PROJECT_GIT_TRANSPORT_TIMEOUT_MS
-    );
-    if (fetch.exitCode !== 0)
-      throw new Error(`Refresh project head mirror: ${fetch.stderr || fetch.stdout || `git exited ${fetch.exitCode}`}`);
+  if (input.refreshRemote !== false && !(input.fetchOnlyBranches && input.fetchOnlyBranches.size === 0)) {
+    await fetchProjectMirrorRefs({ ...input, primaryPath });
   }
   const observations = [];
   for (const branchName of [...input.branchNames].sort()) {
@@ -1429,23 +1455,14 @@ async function observeProjectMirrorHeads(input) {
   }
   return observations;
 }
-async function computeLocalProjectMirrorRefsToken(input) {
+async function computeLocalProjectMirrorRefsTokens(input) {
   const primaryPath = branchPath(input.projectRoot, input.primaryBranchName);
   const rows = await gitAsync(
     primaryPath,
-    ["for-each-ref", "--format=%(objectname) %(refname)", import_project_mirror_refs_token.PROJECT_MIRROR_REF_PREFIX, import_project_mirror_refs_token.PROJECT_SERVER_SYNCED_REF_PREFIX],
+    ["for-each-ref", import_project_mirror_refs_token.PROJECT_MIRROR_REF_LISTING_FORMAT, import_project_mirror_refs_token.PROJECT_MIRROR_REF_PREFIX, import_project_mirror_refs_token.PROJECT_SERVER_SYNCED_REF_PREFIX],
     "list cached project mirror refs"
   );
-  const refs = rows.split(/\r?\n/).filter(Boolean).map((row) => {
-    const separator = row.indexOf(" ");
-    const objectName = separator < 0 ? "" : row.slice(0, separator);
-    const refname = separator < 0 ? "" : row.slice(separator + 1);
-    if (!/^[0-9a-f]{40,64}$/.test(objectName) || refname.length === 0) {
-      throw new Error(`Invalid cached mirror ref listing row: ${row}`);
-    }
-    return { refname, objectName };
-  });
-  return (0, import_project_mirror_refs_token.hashProjectMirrorRefs)((0, import_project_mirror_refs_token.canonicalizeLocalProjectMirrorRefs)(refs));
+  return (0, import_project_mirror_refs_token.projectMirrorRefsTokens)((0, import_project_mirror_refs_token.canonicalizeLocalProjectMirrorRefs)((0, import_project_mirror_refs_token.parseProjectMirrorRefListing)(rows)), input.mounts);
 }
 async function applyObservedProjectMirrorHeads(input) {
   const results = [];
@@ -1529,7 +1546,7 @@ const projectWorktreesTestHarness = {
   ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
-  computeLocalProjectMirrorRefsToken,
+  computeLocalProjectMirrorRefsTokens,
   createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch,

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

@@ -1389,6 +1389,19 @@ ${result.stdout}`;
   }
   return revParse(workspacePath, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`);
 }
+async function resolveWorkspaceRemoteHead(workspacePath, input) {
+  const advertised = input.advertisedRemoteHead;
+  if (advertised && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(advertised)) {
+    const tracked = await revParseAsync(workspacePath, `refs/remotes/origin/${WORKSPACE_GIT_BRANCH}`);
+    if (tracked === advertised && await tryGitAsync(workspacePath, ["cat-file", "-e", `${tracked}^{commit}`])) {
+      return { head: tracked, fetched: false };
+    }
+  }
+  return {
+    head: await fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername),
+    fetched: true
+  };
+}
 async function ensureWorkspaceGitClone(input) {
   const workspacePath = import_node_path.default.resolve(input.workspacePath);
   const workspaceParent = import_node_path.default.dirname(workspacePath);
@@ -1436,7 +1449,8 @@ async function ensureWorkspaceGitClone(input) {
   if (!await revParseAsync(workspacePath, WORKSPACE_GIT_INTEGRATED_REF) && previousRemoteHead && localHeadBeforeFetch && await tryGitAsync(workspacePath, ["merge-base", "--is-ancestor", previousRemoteHead, localHeadBeforeFetch])) {
     await updateIntegratedWorkspaceHead(workspacePath, previousRemoteHead);
   }
-  const remoteHead = await fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername);
+  const resolvedRemoteHead = await resolveWorkspaceRemoteHead(workspacePath, input);
+  const remoteHead = resolvedRemoteHead.head;
   let localHead = await revParseAsync(workspacePath, "HEAD");
   if (!localHead && remoteHead) {
     await runWorkspaceCheckoutTransition(workspacePath, async () => {
@@ -1457,7 +1471,7 @@ async function ensureWorkspaceGitClone(input) {
     await updateIntegratedWorkspaceHead(workspacePath, remoteHead);
     localHead = remoteHead;
   }
-  return { localHead, remoteHead };
+  return { localHead, remoteHead, remoteHeadFetched: resolvedRemoteHead.fetched };
 }
 function activeMounts(mounts) {
   const active = [];
@@ -2106,6 +2120,11 @@ async function synchronizeWithFetchedHead(input) {
   return rebased.ok ? { kind: "ready", updated: false, rebased: true } : { kind: "conflict", conflictPaths: rebased.conflictPaths, refs: rebased.refs, error: rebased.error };
 }
 async function synchronizeWorkspaceGit(input) {
+  const remoteHeadFetches = { count: 0 };
+  const result = await runWorkspaceGitSynchronization(input, remoteHeadFetches);
+  return { ...result, remoteHeadFetches: remoteHeadFetches.count };
+}
+async function runWorkspaceGitSynchronization(input, remoteHeadFetches) {
   const workspacePath = import_node_path.default.resolve(input.workspacePath);
   const attemptId = input.attemptId ?? crypto.randomUUID();
   const maxDiffBytes = input.maxDiffBytes ?? MAX_WORKSPACE_GIT_DIFF_BYTES;
@@ -2114,6 +2133,7 @@ async function synchronizeWorkspaceGit(input) {
   const requiredAncestorHeads = requiredWorkspaceAncestorHeads(input.requiredAncestorHeads);
   const preserveResolutionInProgress = input.skipMountMirror === true;
   const initial = await ensureWorkspaceGitClone({ ...input, workspacePath, preserveResolutionInProgress });
+  if (initial.remoteHeadFetched) remoteHeadFetches.count += 1;
   assertWorkspaceRemediationAncestry({
     workspacePath,
     currentHead: initial.localHead,
@@ -2161,11 +2181,22 @@ async function synchronizeWorkspaceGit(input) {
   const classifyMounts = (activeCandidates, additionalSkippedIds = []) => {
     refreshCycleSkippedMounts();
     const skippedIds = /* @__PURE__ */ new Set([...cycleSkippedMountIds, ...projectionSkippedIds, ...additionalSkippedIds]);
+    const activeMountIds = [...new Set(activeCandidates.filter(({ id }) => !skippedIds.has(id)).map(({ id }) => id))].sort();
     return {
-      activeMountIds: [...new Set(activeCandidates.filter(({ id }) => !skippedIds.has(id)).map(({ id }) => id))].sort(),
-      skippedMountIds: [...skippedIds].sort()
+      activeMountIds,
+      skippedMountIds: [...skippedIds].sort(),
+      // An active mount's token is unchanged since capture (a moved token
+      // lands it in cycleSkippedMountIds above), so this is the token its
+      // projected bytes belong to.
+      projectedMutationTokens: Object.fromEntries(
+        activeMountIds.flatMap((id) => {
+          const token = projectionMutationTokens.get(id);
+          return token === void 0 ? [] : [[id, token]];
+        })
+      )
     };
   };
+  const mountProjectionIsCurrent = (mount) => mount.lastProjectedMutationToken !== void 0 && !mount.deleteWhenSourceMissing && mount.preserveLocalOnHydrationBasisChange !== true && projectionBasisHead !== null && workspaceHydrationReceiptMountBasisHead(projectionBasisReceipt, mount) === projectionBasisHead && projectionMutationTokens.get(mount.id) === mount.lastProjectedMutationToken && mount.mutationToken?.() === mount.lastProjectedMutationToken;
   if (!input.skipMountMirror) {
     const mergeProjectionEnabled = process.env.R5D_WORKSPACE_MERGE_PROJECTION !== "0";
     const mergeSupport = mergeProjectionEnabled ? (0, import_workspace_merge_projection.workspaceMergeProjectionSupport)() : { supported: false, error: "Workspace merge projection is disabled by R5D_WORKSPACE_MERGE_PROJECTION=0" };
@@ -2304,6 +2335,7 @@ async function synchronizeWorkspaceGit(input) {
     }
   };
   const projectedFastMounts = [];
+  const currentProjectionMounts = [];
   if (!input.skipMountMirror) {
     beginWorkspaceCheckoutTransition(workspacePath);
     try {
@@ -2315,6 +2347,10 @@ async function synchronizeWorkspaceGit(input) {
           cycleSkippedMountIds.add(mount.id);
           continue;
         }
+        if (mountProjectionIsCurrent(mount)) {
+          currentProjectionMounts.push(mount);
+          continue;
+        }
         projectedGitlinks.push(...mirrorMountsToWorkspace(workspacePath, [mount]));
         projectedFastMounts.push(mount);
         await yieldToWorkerEventLoop();
@@ -2348,7 +2384,7 @@ async function synchronizeWorkspaceGit(input) {
     const targetProjectionReceipt = receiptWithMountsAtHead(
       projectionBasisReceipt,
       projectedHead,
-      projectedFastMounts,
+      [...projectedFastMounts, ...currentProjectionMounts],
       allProjectionReceiptMounts
     );
     const currentProjectionReceipt = await readHydratedWorkspaceReceiptAsync(workspacePath);
@@ -2361,7 +2397,9 @@ async function synchronizeWorkspaceGit(input) {
     }
     await completeWorkspaceCheckoutTransition(workspacePath);
   }
-  let remoteHead = await fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername);
+  const prePublishRemoteHead = await resolveWorkspaceRemoteHead(workspacePath, input);
+  if (prePublishRemoteHead.fetched) remoteHeadFetches.count += 1;
+  let remoteHead = prePublishRemoteHead.head;
   let rebaseCount = 0;
   let updated = false;
   for (let pushAttempt = 0; pushAttempt < maxPushAttempts; pushAttempt += 1) {
@@ -2518,6 +2556,7 @@ ${push.stdout}`)) {
       throw new Error(`Push workspace main: ${push.stderr || push.stdout || `git exited ${push.exitCode}`}`);
     }
     remoteHead = await fetchWorkspaceHead(workspacePath, input.remoteUrl, input.credentialHelper, input.credentialUsername);
+    remoteHeadFetches.count += 1;
   }
   throw new Error(`Workspace push did not converge after ${maxPushAttempts} attempts`);
 }

package/dist/cjs/workspace-mutation-gate.cjs

@@ -50,8 +50,43 @@ class WorkspaceMutationGate {
       release();
     }
   }
+  /** A worktree create/delete lease; see the branch lane in the class comment. */
+  acquireBranchMutation() {
+    return new Promise((resolve) => {
+      this.waiters.push({ kind: "branch", resolve });
+      this.drain();
+    });
+  }
+  async runBranchMutation(operation) {
+    const release = await this.acquireBranchMutation();
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+  /**
+   * Operations a branch mutation requested now would wait for: the running
+   * sync, if any, plus branch mutations queued behind it. Zero means it runs
+   * at once. Ordinary waiters are not counted because the branch lane admits
+   * ahead of them.
+   */
+  branchMutationQueuePosition() {
+    if (!this.syncActive) return 0;
+    return 1 + this.waiters.filter((waiter) => waiter.kind === "branch").length;
+  }
   drain() {
     if (this.syncActive || this.waiters.length === 0) return;
+    for (let index = 0; index < this.waiters.length; ) {
+      const waiter = this.waiters[index];
+      if (waiter?.kind !== "branch") {
+        index += 1;
+        continue;
+      }
+      this.waiters.splice(index, 1);
+      this.activeMutations += 1;
+      waiter.resolve(this.releaseMutation());
+    }
     const first = this.waiters[0];
     if (first?.kind === "sync") {
       if (this.activeMutations > 0) return;

package/dist/cjs/workspace-projection-ledger.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var workspace_projection_ledger_exports = {};
+__export(workspace_projection_ledger_exports, {
+  WorkspaceProjectionLedger: () => WorkspaceProjectionLedger
+});
+module.exports = __toCommonJS(workspace_projection_ledger_exports);
+const RETAINED_OUTCOMES = /* @__PURE__ */ new Set(["no_change", "updated", "published", "large_diff_blocked"]);
+class WorkspaceProjectionLedger {
+  projectedTokens = /* @__PURE__ */ new Map();
+  lastCycle = null;
+  static recordKey(mount) {
+    return `${mount.hydrationIncarnationKey}\0${mount.id}`;
+  }
+  get lastCycleResult() {
+    return this.lastCycle;
+  }
+  lastProjectedToken(mount) {
+    return this.projectedTokens.get(WorkspaceProjectionLedger.recordKey(mount));
+  }
+  /**
+   * Record a completed cycle. `projectedMutationTokens` names the token each
+   * active mount carried when the cycle projected it; a mount absent from it
+   * keeps its earlier record. Any outcome that leaves the outer clone without
+   * a trustworthy projection clears the ledger.
+   */
+  recordCycle(input) {
+    if (!RETAINED_OUTCOMES.has(input.result.outcome)) {
+      this.reset();
+      return;
+    }
+    const mountsById = new Map(input.mounts.map((mount) => [mount.id, mount]));
+    for (const [mountId, token] of Object.entries(input.projectedMutationTokens ?? {})) {
+      const mount = mountsById.get(mountId);
+      if (mount) this.projectedTokens.set(WorkspaceProjectionLedger.recordKey(mount), token);
+    }
+    this.lastCycle = input.result;
+  }
+  reset() {
+    this.projectedTokens.clear();
+    this.lastCycle = null;
+  }
+  /**
+   * The previous cycle's result when every request targets a configured
+   * mount and no mount's token moved since its recorded projection. A request
+   * without a target (a workspace-rooted command may touch any checkout), a
+   * mount without a token (a pending deletion), or pending deletion work all
+   * require a real cycle.
+   */
+  answerFromLastCycle(input) {
+    if (!this.lastCycle || input.pendingDeletions || input.targetMountIds.length === 0) return null;
+    const mountIds = new Set(input.mounts.map(({ id }) => id));
+    if (!input.targetMountIds.every((mountId) => mountId !== null && mountIds.has(mountId))) return null;
+    for (const mount of input.mounts) {
+      if (!mount.mutationToken) return null;
+      const recorded = this.projectedTokens.get(WorkspaceProjectionLedger.recordKey(mount));
+      if (recorded === void 0 || recorded !== mount.mutationToken()) return null;
+    }
+    return this.lastCycle;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WorkspaceProjectionLedger
+});

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

@@ -0,0 +1,58 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var workspace_sync_coalescer_exports = {};
+__export(workspace_sync_coalescer_exports, {
+  WorkspaceSyncCoalescer: () => WorkspaceSyncCoalescer
+});
+module.exports = __toCommonJS(workspace_sync_coalescer_exports);
+class WorkspaceSyncCoalescer {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  pendingBatch = null;
+  batchesStarted = 0;
+  /** Requests attached to the batch that has not started yet. */
+  get queuedRequestCount() {
+    return this.pendingBatch?.requests.length ?? 0;
+  }
+  /** Batches whose body has been entered, whether or not they ran a cycle. */
+  get startedBatchCount() {
+    return this.batchesStarted;
+  }
+  request(request) {
+    const queued = this.pendingBatch;
+    if (queued) {
+      queued.requests.push(request);
+      return queued.settlement;
+    }
+    const batch = { requests: [request], settlement: Promise.resolve() };
+    this.pendingBatch = batch;
+    batch.settlement = this.options.runExclusive(async () => {
+      if (this.pendingBatch === batch) this.pendingBatch = null;
+      this.batchesStarted += 1;
+      return await this.options.runBatch(batch.requests);
+    });
+    return batch.settlement;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WorkspaceSyncCoalescer
+});