@ricsam/r5d-worker 0.0.94 → 0.0.95

package/dist/cjs/main.cjs

@@ -81,6 +81,7 @@ var import_repository_transition_policy = require("./repository-transition-polic
 var import_supervisor = require("./supervisor.cjs");
 var import_managed_paths = require("./managed-paths.cjs");
 var import_project_worktrees = require("./project-worktrees.cjs");
+var import_project_mirror_fetch_policy = require("./project-mirror-fetch-policy.cjs");
 var import_project_snapshot_recovery_runner = require("./project-snapshot-recovery-runner.cjs");
 var import_project_workspace_state = require("./project-workspace-state.cjs");
 var import_workspace_git_sync = require("./workspace-git-sync.cjs");
@@ -113,6 +114,7 @@ const DEFAULT_READ_MAX_BYTES = 5e4;
 const MAX_LINE_LENGTH = 2e3;
 const WORKSPACE_GIT_QUIET_MS = 5e3;
 const WORKSPACE_GIT_PERIODIC_MS = 6e4;
+const PROJECT_MIRROR_OBSERVE_CONCURRENCY = 6;
 const WORKSPACE_INCIDENT_CONFIG_REFRESH_TIMEOUT_MS = 6e4;
 const PTY_INPUT_BUSY_GRACE_MS = 3e3;
 const PTY_FOREGROUND_POLL_MS = 1e3;
@@ -1003,6 +1005,21 @@ function resolveWorkerFilePath(branchPath, inputPath, builtInPaths) {
 function canonicalProjectRemoteUrl(baseUrl, projectId) {
   return new URL(`/git/${projectId}.git`, baseUrl).toString();
 }
+async function mapWithConcurrencyLimit(items, limit, task) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+      while (true) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= items.length) return;
+        results[index] = await task(items[index], index);
+      }
+    })
+  );
+  return results;
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -3462,6 +3479,10 @@ async function startWorker(options) {
   const readyProjectIds = /* @__PURE__ */ new Set();
   const reconciledProjectConfigFingerprints = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
+  const advertisedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
+  const fetchedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
+  const lastProjectMirrorFetchAtMs = /* @__PURE__ */ new Map();
+  const projectMirrorFetchSkippingEnabled = process.env.R5D_PROJECT_MIRROR_FETCH_SKIP !== "0";
   const pendingMirrorDeletes = /* @__PURE__ */ new Map();
   let workspaceRemoteUrl = null;
   let workspaceCredentialHelper = null;
@@ -3479,6 +3500,7 @@ async function startWorker(options) {
   let automaticSyncInFlight = false;
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
+  let lastWorkspaceSyncMirrorObservationMs = 0;
   let sessionArtifactSyncRequestsInFlight = 0;
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
@@ -4104,6 +4126,17 @@ async function startWorker(options) {
       for (const result of results) {
         lastObservedProjectHeads.set(projectBranchKey(project.projectId, result.branchName), result.head);
       }
+      try {
+        fetchedProjectMirrorRefsTokens.set(
+          project.projectId,
+          await (0, import_project_worktrees.computeLocalProjectMirrorRefsToken)({
+            projectRoot: configuredProjectRoot(projectsRoot, project),
+            primaryBranchName: primaryProjectBranch(project)
+          })
+        );
+      } catch {
+        fetchedProjectMirrorRefsTokens.delete(project.projectId);
+      }
     }
     const publishedTombstoneIds = [
       ...new Set(
@@ -4129,6 +4162,7 @@ async function startWorker(options) {
           credentialHelper: deletion.credentialHelper,
           credentialUsername: deletion.credentialUsername
         });
+        fetchedProjectMirrorRefsTokens.delete(deletion.projectId);
       }
       if (deletion.tombstoneId && !deletion.projectDeleted) {
         projectWorkspaceState = projectWorkspaceStateStore.recordMirrorRefDeletion({
@@ -4139,42 +4173,101 @@ async function startWorker(options) {
       pendingMirrorDeletes.delete(key);
       if (deletion.projectDeleted && !projectConfigById.has(deletion.projectId) && ![...pendingMirrorDeletes.values()].some((pending) => pending.projectId === deletion.projectId)) {
         removeProjectCredentialStore(deletion.projectId);
+        advertisedProjectMirrorRefsTokens.delete(deletion.projectId);
+        fetchedProjectMirrorRefsTokens.delete(deletion.projectId);
+        lastProjectMirrorFetchAtMs.delete(deletion.projectId);
       }
       lastObservedProjectHeads.delete(key);
     }
   };
+  const observeSingleProjectMirrorBundle = async (project, options2) => {
+    const connection = projectConnection(project);
+    const projectRoot = configuredProjectRoot(projectsRoot, project);
+    const primaryBranchName = primaryProjectBranch(project);
+    if (options2.refreshRemote) {
+      const advertisedBeforeFetch = advertisedProjectMirrorRefsTokens.get(project.projectId);
+      const observations = await (0, import_project_worktrees.observeProjectMirrorHeads)({
+        projectRoot,
+        primaryBranchName,
+        branchNames: project.branches.map(({ branchName }) => branchName),
+        mirrorUrl: connection.mirrorUrl,
+        credentialHelper: connection.credentialHelper,
+        credentialUsername: connection.mirrorCredentialUsername,
+        allowNonFastForward: options2.allowNonFastForward,
+        branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId]))
+      });
+      if (advertisedBeforeFetch === void 0) fetchedProjectMirrorRefsTokens.delete(project.projectId);
+      else fetchedProjectMirrorRefsTokens.set(project.projectId, advertisedBeforeFetch);
+      lastProjectMirrorFetchAtMs.set(project.projectId, Date.now());
+      return { projectId: project.projectId, projectRoot, primaryBranchName, observations };
+    }
+    return {
+      projectId: project.projectId,
+      projectRoot,
+      primaryBranchName,
+      observations: await (0, import_project_worktrees.observeProjectMirrorHeads)({
+        projectRoot,
+        primaryBranchName,
+        branchNames: project.branches.map(({ branchName }) => branchName),
+        mirrorUrl: connection.mirrorUrl,
+        credentialHelper: connection.credentialHelper,
+        credentialUsername: connection.mirrorCredentialUsername,
+        allowNonFastForward: options2.allowNonFastForward,
+        branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId])),
+        refreshRemote: false
+      })
+    };
+  };
   const observeProjectHeadsBeforeOuterWorkspace = async (input) => {
-    const bundles = [];
-    for (const project of projectConfigById.values()) {
-      if (project.executionDisabled || !readyProjectIds.has(project.projectId) || project.branches.length === 0) continue;
-      try {
-        const connection = projectConnection(project);
-        const projectRoot = configuredProjectRoot(projectsRoot, project);
-        const primaryBranchName = primaryProjectBranch(project);
-        bundles.push({
-          projectId: project.projectId,
-          projectRoot,
-          primaryBranchName,
-          observations: await (0, import_project_worktrees.observeProjectMirrorHeads)({
-            projectRoot,
-            primaryBranchName,
-            branchNames: project.branches.map(({ branchName }) => branchName),
-            mirrorUrl: connection.mirrorUrl,
-            credentialHelper: connection.credentialHelper,
-            credentialUsername: connection.mirrorCredentialUsername,
-            allowNonFastForward: input.allowNonFastForward,
-            branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId]))
-          })
-        });
-      } catch (error) {
-        if (input.failClosed) throw error;
+    const observationStartedAt = Date.now();
+    const eligibleProjects = [...projectConfigById.values()].filter(
+      (project) => !project.executionDisabled && readyProjectIds.has(project.projectId) && project.branches.length > 0
+    );
+    try {
+      if (input.failClosed) {
+        const bundles2 = [];
+        for (const project of eligibleProjects) {
+          bundles2.push(await observeSingleProjectMirrorBundle(project, { allowNonFastForward: input.allowNonFastForward, refreshRemote: true }));
+        }
+        return bundles2;
+      }
+      let fetchedCount = 0;
+      const bundles = await mapWithConcurrencyLimit(
+        eligibleProjects,
+        PROJECT_MIRROR_OBSERVE_CONCURRENCY,
+        async (project) => {
+          try {
+            const decision = (0, import_project_mirror_fetch_policy.projectMirrorFetchDecision)({
+              advertisedToken: advertisedProjectMirrorRefsTokens.get(project.projectId),
+              fetchedToken: fetchedProjectMirrorRefsTokens.get(project.projectId),
+              lastFetchAtMs: lastProjectMirrorFetchAtMs.get(project.projectId),
+              nowMs: Date.now(),
+              skippingEnabled: projectMirrorFetchSkippingEnabled
+            });
+            if (decision.fetch) fetchedCount += 1;
+            return await observeSingleProjectMirrorBundle(project, {
+              allowNonFastForward: input.allowNonFastForward,
+              refreshRemote: decision.fetch
+            });
+          } catch (error) {
+            process.stderr.write(
+              `[r5d-worker] failed to observe project mirror heads before workspace update: ${error instanceof Error ? error.message : String(error)}
+`
+            );
+            return null;
+          }
+        }
+      );
+      if (fetchedCount > 0) {
         process.stderr.write(
-          `[r5d-worker] failed to observe project mirror heads before workspace update: ${error instanceof Error ? error.message : String(error)}
+          `[r5d-worker] project mirror observation fetched ${fetchedCount} of ${eligibleProjects.length} mirror(s)
 `
         );
       }
+      return bundles.filter((bundle) => bundle !== null);
+    } finally {
+      lastWorkspaceSyncMirrorObservationMs = Date.now() - observationStartedAt;
     }
-    return bundles;
   };
   const applyObservedProjectHeadsAfterInboundWorkspace = async (bundles, activeMountIds, requireObservedHeads, integratedWorkspaceHead) => {
     const active = new Set(activeMountIds);
@@ -4443,6 +4536,7 @@ async function startWorker(options) {
       result = await workspaceSyncSingleFlight.runExclusive(async () => {
         queueEnteredAt = Date.now();
         syncStartedAt = Date.now();
+        lastWorkspaceSyncMirrorObservationMs = 0;
         if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
           return await failedWorkspaceSyncResult(
             attemptId,
@@ -4527,7 +4621,9 @@ async function startWorker(options) {
       telemetry: {
         totalMs: finishedAt - requestedAt,
         queueMs: queueEnteredAt - requestedAt,
-        prepareMs: 0,
+        // Duration of the pre-outer mirror-head observation phase; near zero
+        // on a cycle whose token-gated observation skipped every fetch.
+        prepareMs: lastWorkspaceSyncMirrorObservationMs,
         synchronizeMs: finishedAt - syncStartedAt
       }
     };
@@ -5245,7 +5341,8 @@ async function startWorker(options) {
           workspaceIncidentConfigDeferralV1: true,
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
-          projectMirrorLeaseV1: true
+          projectMirrorLeaseV1: true,
+          projectMirrorRefsTokensV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -5283,6 +5380,17 @@ async function startWorker(options) {
       if (message.type === "connected") {
         return;
       }
+      if (message.type === "project_mirror_refs_tokens") {
+        advertisedProjectMirrorRefsTokens.clear();
+        if (message.tokens && typeof message.tokens === "object") {
+          for (const [projectId, token2] of Object.entries(message.tokens)) {
+            if (typeof token2 === "string" && /^[0-9a-f]{64}$/.test(token2)) {
+              advertisedProjectMirrorRefsTokens.set(projectId, token2);
+            }
+          }
+        }
+        return;
+      }
       if (message.type === "workspace_config") {
         const receiptGeneration = ++workspaceConfigurationReceiptGeneration;
         const refreshesDeferredConfiguration = deferredWorkspaceConfiguration !== null && activeWorkspaceIncidentId === null && message.deferWorkspaceSyncForIncidentId === void 0;

package/dist/cjs/package.json

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

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

@@ -0,0 +1,41 @@
+"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 project_mirror_fetch_policy_exports = {};
+__export(project_mirror_fetch_policy_exports, {
+  PROJECT_MIRROR_FETCH_BACKSTOP_MS: () => PROJECT_MIRROR_FETCH_BACKSTOP_MS,
+  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" };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROJECT_MIRROR_FETCH_BACKSTOP_MS,
+  projectMirrorFetchDecision
+});

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

@@ -0,0 +1,51 @@
+"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 project_mirror_refs_token_exports = {};
+__export(project_mirror_refs_token_exports, {
+  PROJECT_MIRROR_REF_PREFIX: () => PROJECT_MIRROR_REF_PREFIX,
+  PROJECT_SERVER_SYNCED_REF_PREFIX: () => PROJECT_SERVER_SYNCED_REF_PREFIX,
+  canonicalizeLocalProjectMirrorRefs: () => canonicalizeLocalProjectMirrorRefs,
+  hashProjectMirrorRefs: () => hashProjectMirrorRefs
+});
+module.exports = __toCommonJS(project_mirror_refs_token_exports);
+var import_node_crypto = require("node:crypto");
+const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
+const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+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 canonicalizeLocalProjectMirrorRefs(refs) {
+  const canonical = [];
+  for (const { refname, objectName } of refs) {
+    if (refname.startsWith(PROJECT_MIRROR_REF_PREFIX)) {
+      canonical.push({ refname: `refs/heads/${refname.slice(PROJECT_MIRROR_REF_PREFIX.length)}`, objectName });
+    } else if (refname.startsWith(PROJECT_SERVER_SYNCED_REF_PREFIX)) {
+      canonical.push({ refname, objectName });
+    }
+  }
+  return canonical;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROJECT_MIRROR_REF_PREFIX,
+  PROJECT_SERVER_SYNCED_REF_PREFIX,
+  canonicalizeLocalProjectMirrorRefs,
+  hashProjectMirrorRefs
+});

package/dist/cjs/project-worktrees.cjs

@@ -32,6 +32,7 @@ __export(project_worktrees_exports, {
   ProjectBranchCreationRollbackIncompleteError: () => ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads: () => applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed: () => assertProjectMirrorHeadsPushed,
+  computeLocalProjectMirrorRefsToken: () => computeLocalProjectMirrorRefsToken,
   createLinkedProjectBranch: () => createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch: () => createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch: () => deleteLinkedProjectBranch,
@@ -57,6 +58,7 @@ var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_git_process_environment = require("./git-process-environment.cjs");
 var import_managed_paths = require("./managed-paths.cjs");
+var import_project_mirror_refs_token = require("./project-mirror-refs-token.cjs");
 var import_working_tree_mirror = require("./working-tree-mirror.cjs");
 const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 const PROJECT_WORKTREE_SNAPSHOT_MANIFEST = "transaction.json";
@@ -1294,6 +1296,7 @@ ${deleted.stdout}`)) {
       `Delete hidden project mirror for ${input.branchName}: ${deleted.stderr || deleted.stdout || `git exited ${deleted.exitCode}`}`
     );
   }
+  await gitResultAsync(input.gitDirectory, ["update-ref", "-d", `refs/r5d/mirror/${input.branchName}`]);
 }
 async function pushProjectMirrorHeads(input) {
   const results = [];
@@ -1351,6 +1354,7 @@ async function pushProjectMirrorHeads(input) {
     if (pushed.exitCode !== 0) {
       throw new Error(`Push hidden project mirror for ${branchName}: ${pushed.stderr || pushed.stdout || `git exited ${pushed.exitCode}`}`);
     }
+    await gitAsync(checkoutPath, ["update-ref", `refs/r5d/mirror/${branchName}`, head], `record pushed mirror tip ${branchName}`);
     results.push({ branchName, head, pushed: true });
   }
   return results;
@@ -1363,21 +1367,23 @@ function assertProjectMirrorHeadsPushed(results) {
 }
 async function observeProjectMirrorHeads(input) {
   const primaryPath = branchPath(input.projectRoot, input.primaryBranchName);
-  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) {
+    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}`}`);
+  }
   const observations = [];
   for (const branchName of [...input.branchNames].sort()) {
     const checkoutPath = branchPath(input.projectRoot, branchName);
@@ -1423,6 +1429,24 @@ async function observeProjectMirrorHeads(input) {
   }
   return observations;
 }
+async function computeLocalProjectMirrorRefsToken(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],
+    "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));
+}
 async function applyObservedProjectMirrorHeads(input) {
   const results = [];
   for (const observation of [...input.observations].sort((left, right) => left.branchName.localeCompare(right.branchName))) {
@@ -1505,6 +1529,7 @@ const projectWorktreesTestHarness = {
   ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
+  computeLocalProjectMirrorRefsToken,
   createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch,

package/dist/mjs/main.mjs

@@ -58,6 +58,7 @@ import { assertDisjointManagedRoots, managedProjectRoot, validateManagedBranchNa
 import {
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
+  computeLocalProjectMirrorRefsToken,
   createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch,
   deleteProjectMirrorBranch,
@@ -70,6 +71,7 @@ import {
   pushProjectMirrorHeads,
   removeProjectWorktrees
 } from "./project-worktrees.mjs";
+import { projectMirrorFetchDecision } from "./project-mirror-fetch-policy.mjs";
 import {
   PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND,
   recoverProjectSnapshotsInChild,
@@ -119,6 +121,7 @@ const DEFAULT_READ_MAX_BYTES = 5e4;
 const MAX_LINE_LENGTH = 2e3;
 const WORKSPACE_GIT_QUIET_MS = 5e3;
 const WORKSPACE_GIT_PERIODIC_MS = 6e4;
+const PROJECT_MIRROR_OBSERVE_CONCURRENCY = 6;
 const WORKSPACE_INCIDENT_CONFIG_REFRESH_TIMEOUT_MS = 6e4;
 const PTY_INPUT_BUSY_GRACE_MS = 3e3;
 const PTY_FOREGROUND_POLL_MS = 1e3;
@@ -1009,6 +1012,21 @@ function resolveWorkerFilePath(branchPath, inputPath, builtInPaths) {
 function canonicalProjectRemoteUrl(baseUrl, projectId) {
   return new URL(`/git/${projectId}.git`, baseUrl).toString();
 }
+async function mapWithConcurrencyLimit(items, limit, task) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+      while (true) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= items.length) return;
+        results[index] = await task(items[index], index);
+      }
+    })
+  );
+  return results;
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -3468,6 +3486,10 @@ async function startWorker(options) {
   const readyProjectIds = /* @__PURE__ */ new Set();
   const reconciledProjectConfigFingerprints = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
+  const advertisedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
+  const fetchedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
+  const lastProjectMirrorFetchAtMs = /* @__PURE__ */ new Map();
+  const projectMirrorFetchSkippingEnabled = process.env.R5D_PROJECT_MIRROR_FETCH_SKIP !== "0";
   const pendingMirrorDeletes = /* @__PURE__ */ new Map();
   let workspaceRemoteUrl = null;
   let workspaceCredentialHelper = null;
@@ -3485,6 +3507,7 @@ async function startWorker(options) {
   let automaticSyncInFlight = false;
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
+  let lastWorkspaceSyncMirrorObservationMs = 0;
   let sessionArtifactSyncRequestsInFlight = 0;
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
@@ -4110,6 +4133,17 @@ async function startWorker(options) {
       for (const result of results) {
         lastObservedProjectHeads.set(projectBranchKey(project.projectId, result.branchName), result.head);
       }
+      try {
+        fetchedProjectMirrorRefsTokens.set(
+          project.projectId,
+          await computeLocalProjectMirrorRefsToken({
+            projectRoot: configuredProjectRoot(projectsRoot, project),
+            primaryBranchName: primaryProjectBranch(project)
+          })
+        );
+      } catch {
+        fetchedProjectMirrorRefsTokens.delete(project.projectId);
+      }
     }
     const publishedTombstoneIds = [
       ...new Set(
@@ -4135,6 +4169,7 @@ async function startWorker(options) {
           credentialHelper: deletion.credentialHelper,
           credentialUsername: deletion.credentialUsername
         });
+        fetchedProjectMirrorRefsTokens.delete(deletion.projectId);
       }
       if (deletion.tombstoneId && !deletion.projectDeleted) {
         projectWorkspaceState = projectWorkspaceStateStore.recordMirrorRefDeletion({
@@ -4145,42 +4180,101 @@ async function startWorker(options) {
       pendingMirrorDeletes.delete(key);
       if (deletion.projectDeleted && !projectConfigById.has(deletion.projectId) && ![...pendingMirrorDeletes.values()].some((pending) => pending.projectId === deletion.projectId)) {
         removeProjectCredentialStore(deletion.projectId);
+        advertisedProjectMirrorRefsTokens.delete(deletion.projectId);
+        fetchedProjectMirrorRefsTokens.delete(deletion.projectId);
+        lastProjectMirrorFetchAtMs.delete(deletion.projectId);
       }
       lastObservedProjectHeads.delete(key);
     }
   };
+  const observeSingleProjectMirrorBundle = async (project, options2) => {
+    const connection = projectConnection(project);
+    const projectRoot = configuredProjectRoot(projectsRoot, project);
+    const primaryBranchName = primaryProjectBranch(project);
+    if (options2.refreshRemote) {
+      const advertisedBeforeFetch = advertisedProjectMirrorRefsTokens.get(project.projectId);
+      const observations = await observeProjectMirrorHeads({
+        projectRoot,
+        primaryBranchName,
+        branchNames: project.branches.map(({ branchName }) => branchName),
+        mirrorUrl: connection.mirrorUrl,
+        credentialHelper: connection.credentialHelper,
+        credentialUsername: connection.mirrorCredentialUsername,
+        allowNonFastForward: options2.allowNonFastForward,
+        branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId]))
+      });
+      if (advertisedBeforeFetch === void 0) fetchedProjectMirrorRefsTokens.delete(project.projectId);
+      else fetchedProjectMirrorRefsTokens.set(project.projectId, advertisedBeforeFetch);
+      lastProjectMirrorFetchAtMs.set(project.projectId, Date.now());
+      return { projectId: project.projectId, projectRoot, primaryBranchName, observations };
+    }
+    return {
+      projectId: project.projectId,
+      projectRoot,
+      primaryBranchName,
+      observations: await observeProjectMirrorHeads({
+        projectRoot,
+        primaryBranchName,
+        branchNames: project.branches.map(({ branchName }) => branchName),
+        mirrorUrl: connection.mirrorUrl,
+        credentialHelper: connection.credentialHelper,
+        credentialUsername: connection.mirrorCredentialUsername,
+        allowNonFastForward: options2.allowNonFastForward,
+        branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId])),
+        refreshRemote: false
+      })
+    };
+  };
   const observeProjectHeadsBeforeOuterWorkspace = async (input) => {
-    const bundles = [];
-    for (const project of projectConfigById.values()) {
-      if (project.executionDisabled || !readyProjectIds.has(project.projectId) || project.branches.length === 0) continue;
-      try {
-        const connection = projectConnection(project);
-        const projectRoot = configuredProjectRoot(projectsRoot, project);
-        const primaryBranchName = primaryProjectBranch(project);
-        bundles.push({
-          projectId: project.projectId,
-          projectRoot,
-          primaryBranchName,
-          observations: await observeProjectMirrorHeads({
-            projectRoot,
-            primaryBranchName,
-            branchNames: project.branches.map(({ branchName }) => branchName),
-            mirrorUrl: connection.mirrorUrl,
-            credentialHelper: connection.credentialHelper,
-            credentialUsername: connection.mirrorCredentialUsername,
-            allowNonFastForward: input.allowNonFastForward,
-            branchIds: new Map(project.branches.map(({ branchId, branchName }) => [branchName, branchId]))
-          })
-        });
-      } catch (error) {
-        if (input.failClosed) throw error;
+    const observationStartedAt = Date.now();
+    const eligibleProjects = [...projectConfigById.values()].filter(
+      (project) => !project.executionDisabled && readyProjectIds.has(project.projectId) && project.branches.length > 0
+    );
+    try {
+      if (input.failClosed) {
+        const bundles2 = [];
+        for (const project of eligibleProjects) {
+          bundles2.push(await observeSingleProjectMirrorBundle(project, { allowNonFastForward: input.allowNonFastForward, refreshRemote: true }));
+        }
+        return bundles2;
+      }
+      let fetchedCount = 0;
+      const bundles = await mapWithConcurrencyLimit(
+        eligibleProjects,
+        PROJECT_MIRROR_OBSERVE_CONCURRENCY,
+        async (project) => {
+          try {
+            const decision = projectMirrorFetchDecision({
+              advertisedToken: advertisedProjectMirrorRefsTokens.get(project.projectId),
+              fetchedToken: fetchedProjectMirrorRefsTokens.get(project.projectId),
+              lastFetchAtMs: lastProjectMirrorFetchAtMs.get(project.projectId),
+              nowMs: Date.now(),
+              skippingEnabled: projectMirrorFetchSkippingEnabled
+            });
+            if (decision.fetch) fetchedCount += 1;
+            return await observeSingleProjectMirrorBundle(project, {
+              allowNonFastForward: input.allowNonFastForward,
+              refreshRemote: decision.fetch
+            });
+          } catch (error) {
+            process.stderr.write(
+              `[r5d-worker] failed to observe project mirror heads before workspace update: ${error instanceof Error ? error.message : String(error)}
+`
+            );
+            return null;
+          }
+        }
+      );
+      if (fetchedCount > 0) {
         process.stderr.write(
-          `[r5d-worker] failed to observe project mirror heads before workspace update: ${error instanceof Error ? error.message : String(error)}
+          `[r5d-worker] project mirror observation fetched ${fetchedCount} of ${eligibleProjects.length} mirror(s)
 `
         );
       }
+      return bundles.filter((bundle) => bundle !== null);
+    } finally {
+      lastWorkspaceSyncMirrorObservationMs = Date.now() - observationStartedAt;
     }
-    return bundles;
   };
   const applyObservedProjectHeadsAfterInboundWorkspace = async (bundles, activeMountIds, requireObservedHeads, integratedWorkspaceHead) => {
     const active = new Set(activeMountIds);
@@ -4449,6 +4543,7 @@ async function startWorker(options) {
       result = await workspaceSyncSingleFlight.runExclusive(async () => {
         queueEnteredAt = Date.now();
         syncStartedAt = Date.now();
+        lastWorkspaceSyncMirrorObservationMs = 0;
         if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
           return await failedWorkspaceSyncResult(
             attemptId,
@@ -4533,7 +4628,9 @@ async function startWorker(options) {
       telemetry: {
         totalMs: finishedAt - requestedAt,
         queueMs: queueEnteredAt - requestedAt,
-        prepareMs: 0,
+        // Duration of the pre-outer mirror-head observation phase; near zero
+        // on a cycle whose token-gated observation skipped every fetch.
+        prepareMs: lastWorkspaceSyncMirrorObservationMs,
         synchronizeMs: finishedAt - syncStartedAt
       }
     };
@@ -5251,7 +5348,8 @@ async function startWorker(options) {
           workspaceIncidentConfigDeferralV1: true,
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
-          projectMirrorLeaseV1: true
+          projectMirrorLeaseV1: true,
+          projectMirrorRefsTokensV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -5289,6 +5387,17 @@ async function startWorker(options) {
       if (message.type === "connected") {
         return;
       }
+      if (message.type === "project_mirror_refs_tokens") {
+        advertisedProjectMirrorRefsTokens.clear();
+        if (message.tokens && typeof message.tokens === "object") {
+          for (const [projectId, token2] of Object.entries(message.tokens)) {
+            if (typeof token2 === "string" && /^[0-9a-f]{64}$/.test(token2)) {
+              advertisedProjectMirrorRefsTokens.set(projectId, token2);
+            }
+          }
+        }
+        return;
+      }
       if (message.type === "workspace_config") {
         const receiptGeneration = ++workspaceConfigurationReceiptGeneration;
         const refreshesDeferredConfiguration = deferredWorkspaceConfiguration !== null && activeWorkspaceIncidentId === null && message.deferWorkspaceSyncForIncidentId === void 0;

package/dist/mjs/package.json

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

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

@@ -0,0 +1,16 @@
+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" };
+}
+export {
+  PROJECT_MIRROR_FETCH_BACKSTOP_MS,
+  projectMirrorFetchDecision
+};

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

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
+const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+function hashProjectMirrorRefs(refs) {
+  const lines = refs.map(({ objectName, refname }) => `${objectName} ${refname}`).sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+  return createHash("sha256").update(lines.join("\n")).digest("hex");
+}
+function canonicalizeLocalProjectMirrorRefs(refs) {
+  const canonical = [];
+  for (const { refname, objectName } of refs) {
+    if (refname.startsWith(PROJECT_MIRROR_REF_PREFIX)) {
+      canonical.push({ refname: `refs/heads/${refname.slice(PROJECT_MIRROR_REF_PREFIX.length)}`, objectName });
+    } else if (refname.startsWith(PROJECT_SERVER_SYNCED_REF_PREFIX)) {
+      canonical.push({ refname, objectName });
+    }
+  }
+  return canonical;
+}
+export {
+  PROJECT_MIRROR_REF_PREFIX,
+  PROJECT_SERVER_SYNCED_REF_PREFIX,
+  canonicalizeLocalProjectMirrorRefs,
+  hashProjectMirrorRefs
+};

package/dist/mjs/project-worktrees.mjs

@@ -4,6 +4,12 @@ import os from "node:os";
 import path from "node:path";
 import { gitCredentialUsernameConfigKey, gitTransportSecurityArgs, workerGitProcessEnvironment } from "./git-process-environment.mjs";
 import { validateManagedBranchName } from "./managed-paths.mjs";
+import {
+  canonicalizeLocalProjectMirrorRefs,
+  hashProjectMirrorRefs,
+  PROJECT_MIRROR_REF_PREFIX,
+  PROJECT_SERVER_SYNCED_REF_PREFIX
+} from "./project-mirror-refs-token.mjs";
 import { mirrorWorkingTree } from "./working-tree-mirror.mjs";
 const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 const PROJECT_WORKTREE_SNAPSHOT_MANIFEST = "transaction.json";
@@ -1241,6 +1247,7 @@ ${deleted.stdout}`)) {
       `Delete hidden project mirror for ${input.branchName}: ${deleted.stderr || deleted.stdout || `git exited ${deleted.exitCode}`}`
     );
   }
+  await gitResultAsync(input.gitDirectory, ["update-ref", "-d", `refs/r5d/mirror/${input.branchName}`]);
 }
 async function pushProjectMirrorHeads(input) {
   const results = [];
@@ -1298,6 +1305,7 @@ async function pushProjectMirrorHeads(input) {
     if (pushed.exitCode !== 0) {
       throw new Error(`Push hidden project mirror for ${branchName}: ${pushed.stderr || pushed.stdout || `git exited ${pushed.exitCode}`}`);
     }
+    await gitAsync(checkoutPath, ["update-ref", `refs/r5d/mirror/${branchName}`, head], `record pushed mirror tip ${branchName}`);
     results.push({ branchName, head, pushed: true });
   }
   return results;
@@ -1310,21 +1318,23 @@ function assertProjectMirrorHeadsPushed(results) {
 }
 async function observeProjectMirrorHeads(input) {
   const primaryPath = branchPath(input.projectRoot, input.primaryBranchName);
-  const fetch = await gitResultAsync(
-    primaryPath,
-    [
-      ...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) {
+    const fetch = await gitResultAsync(
+      primaryPath,
+      [
+        ...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}`}`);
+  }
   const observations = [];
   for (const branchName of [...input.branchNames].sort()) {
     const checkoutPath = branchPath(input.projectRoot, branchName);
@@ -1370,6 +1380,24 @@ async function observeProjectMirrorHeads(input) {
   }
   return observations;
 }
+async function computeLocalProjectMirrorRefsToken(input) {
+  const primaryPath = branchPath(input.projectRoot, input.primaryBranchName);
+  const rows = await gitAsync(
+    primaryPath,
+    ["for-each-ref", "--format=%(objectname) %(refname)", PROJECT_MIRROR_REF_PREFIX, 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 hashProjectMirrorRefs(canonicalizeLocalProjectMirrorRefs(refs));
+}
 async function applyObservedProjectMirrorHeads(input) {
   const results = [];
   for (const observation of [...input.observations].sort((left, right) => left.branchName.localeCompare(right.branchName))) {
@@ -1451,6 +1479,7 @@ export {
   ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads,
   assertProjectMirrorHeadsPushed,
+  computeLocalProjectMirrorRefsToken,
   createLinkedProjectBranch,
   createOrRetryLinkedProjectBranch,
   deleteLinkedProjectBranch,

package/dist/types/main.d.ts

@@ -125,6 +125,15 @@ type WorkerServerMessage = {
     confirmationReason?: string;
     resetToCanonical?: boolean;
     requiredAncestorHeads?: string[];
+} | {
+    /**
+     * Content-derived tokens naming each canonical project repository's
+     * observable ref state, keyed by project id. Replace-all: projects
+     * absent from a message have no advertised token and observation falls
+     * back to fetching. See `project-mirror-fetch-policy.ts`.
+     */
+    type: "project_mirror_refs_tokens";
+    tokens: Record<string, string>;
 } | {
     type: "create_project_branch";
     requestId: string;

package/dist/types/project-mirror-fetch-policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Decides whether a periodic observation must fetch a project's hidden mirror
+ * or may reuse the locally cached mirror refs. The server advertises a
+ * content-derived token per project (hash of the exact ref namespaces the
+ * observation fetch would transfer); when the advertised token equals the
+ * token the local refs already cover, the fetch would be a no-op.
+ *
+ * Skipping is fail-open: any missing or mismatched information fetches. The
+ * backstop bounds the damage of a server-side token bug (for example a token
+ * computed against the wrong repository path) to one interval; every
+ * git-transport writer is observed by the server's on-disk recompute, so the
+ * backstop is insurance against bugs, not against known unobserved writers.
+ */
+export declare const PROJECT_MIRROR_FETCH_BACKSTOP_MS: number;
+export type ProjectMirrorFetchDecision = {
+    fetch: true;
+    reason: "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "backstop_elapsed";
+} | {
+    fetch: false;
+    reason: "token_match";
+};
+export declare function projectMirrorFetchDecision(input: {
+    advertisedToken: string | undefined;
+    fetchedToken: string | undefined;
+    lastFetchAtMs: number | undefined;
+    nowMs: number;
+    skippingEnabled: boolean;
+    backstopMs?: number;
+}): ProjectMirrorFetchDecision;

package/dist/types/project-mirror-refs-token.d.ts

@@ -0,0 +1,19 @@
+export declare const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
+export declare const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+export type ProjectMirrorRef = {
+    refname: string;
+    objectName: string;
+};
+/**
+ * Hash a ref listing into a mirror-refs token. Both sides sort here rather
+ * than trusting git's listing order: renaming `refs/r5d/mirror/*` back to
+ * `refs/heads/*` changes sort neighborhoods.
+ */
+export declare function hashProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): string;
+/**
+ * Rename locally fetched mirror refs into the namespaces the server hashes.
+ * Rows outside the two observed namespaces are dropped; the caller lists only
+ * those namespaces, so a dropped row means an unexpected listing, and dropping
+ * it can only make tokens differ — which fails open into a fetch.
+ */
+export declare function canonicalizeLocalProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): ProjectMirrorRef[];

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

@@ -212,11 +212,32 @@ export type ProjectMirrorHeadObservation = {
  * Fetch and pin the exact hidden-mirror tips that may be applied after a
  * causally later outer-workspace fetch and hydration. Observation deliberately
  * does not mutate a live branch or its index.
+ *
+ * With `refreshRemote: false` the network fetch is skipped and the tips come
+ * from the locally cached `refs/r5d/mirror/*` / `refs/r5d/server-synced/*`
+ * refs of an earlier fetch. That is safe in the stale direction (a newer
+ * mirror tip waits for a later cycle, exactly like a tip that lands mid-cycle
+ * today) and in the fresh direction (hidden-mirror publication is tree-first,
+ * so any locally cached tip's covering outer tree was published before the
+ * fetch that cached it, hence before this cycle's outer fetch).
  */
 export declare function observeProjectMirrorHeads(input: Omit<ProjectMirrorHeadUpdateInput, "branchMutationAllowed"> & {
     allowNonFastForward: boolean;
     branchIds?: ReadonlyMap<string, string>;
+    refreshRemote?: boolean;
 }): Promise<ProjectMirrorHeadObservation[]>;
+/**
+ * Compute the mirror-refs token for the locally cached mirror state — the
+ * token the server will advertise once it hashes the same refs. After a
+ * successful lease push (which updates `refs/r5d/mirror/*` above), this
+ * matches the server's next advertisement unless something else also moved
+ * the canonical repository, in which case the mismatch fails open into a
+ * fetch. Formula twin: `server/git/project-mirror-refs-token.ts`.
+ */
+export declare function computeLocalProjectMirrorRefsToken(input: {
+    projectRoot: string;
+    primaryBranchName: string;
+}): Promise<string>;
 /** Apply only previously observed object ids; this function never refetches. */
 export declare function applyObservedProjectMirrorHeads(input: {
     projectRoot: string;

package/package.json

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