@ricsam/r5d-worker 0.0.101 → 0.0.104

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

@@ -27,8 +27,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/mjs/workspace-projection-ledger.mjs

@@ -0,0 +1,57 @@
+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;
+  }
+}
+export {
+  WorkspaceProjectionLedger
+};

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

@@ -0,0 +1,34 @@
+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;
+  }
+}
+export {
+  WorkspaceSyncCoalescer
+};

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;
@@ -185,6 +191,11 @@ type WorkerClientMessage = {
     requestId: string;
     result?: WorkerOperationResult;
     error?: string;
+} | {
+    /** Immediate receipt for a branch create/delete; `queuePosition` is 0 when it runs at once. */
+    type: "operation_queued";
+    requestId: string;
+    queuePosition: number;
 } | {
     type: "exec_result";
     requestId: string;
@@ -290,13 +301,18 @@ type WorkerServerMessage = {
     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`.
+     * Content-derived tokens naming ref state the server read from disk:
+     * `tokens` per canonical project repository, `mountTokens` per
+     * checked-out project branch (keyed by project id then branch name),
+     * and the current head of the hidden workspace repository. Replace-all:
+     * anything absent from a message has no advertised token and the
+     * corresponding fetch runs. Older servers send `tokens` only. See
+     * `project-mirror-fetch-policy.ts`.
      */
     type: "project_mirror_refs_tokens";
     tokens: Record<string, string>;
+    mountTokens?: Record<string, Record<string, string>>;
+    workspaceHead?: string;
 } | {
     type: "create_project_branch";
     requestId: string;
@@ -304,6 +320,8 @@ type WorkerServerMessage = {
     projectId: string;
     sourceBranch: string;
     targetBranch: string;
+    /** `carry` copies the source checkout's uncommitted changes; `clean` checks out its commit only. */
+    workingTree: "carry" | "clean";
 } | {
     type: "delete_project_branch";
     requestId: string;
@@ -618,14 +636,17 @@ export declare const workerPtyTestHarness: {
     removeEnvFiles: typeof removePtyEnvFiles;
     resolveEnvFileReferences: typeof resolvePtyEnvFileReferences;
     commandHasWorkspaceEffect: typeof workerCommandHasWorkspaceEffect;
+    targetProcessEnv: typeof targetProcessEnv;
     canonicalSyncTerminalHead: typeof canonicalSyncTerminalHead;
     ptyIsWorkspaceBusy: typeof workerPtyIsWorkspaceBusy;
     parseLinuxForegroundBusy: typeof parseLinuxPtyForegroundBusy;
 };
 export type WorkerBuiltInToolPaths = {
-    artifactsDir?: string;
-    plansDir?: string;
-    activePlanFile?: string;
+    rootDir?: string;
+    sessionId?: string;
+    projectId?: string;
+    branchName?: string;
+    activePlanId?: string;
 };
 export declare function isArtifactEnvPath(filePath: string): boolean;
 export declare function syncSessionArtifacts(input: {
@@ -638,11 +659,11 @@ export declare function prepareArtifactEnvForShell(input: {
     baseUrl: string;
     token: string;
     sessionId?: string;
-    artifactRoot: string;
+    rootDir: string;
 }): Promise<Record<string, string>>;
 export declare function preparePlanEnvForShell(input: {
     target: WorkerSessionTarget;
-    planRoot: string;
+    rootDir: string;
     activePlanId?: string;
 }): Record<string, string>;
 type ResolvedWorkerFilePath = {
@@ -943,8 +964,7 @@ export declare function prepareBuiltInToolPathsForTarget(input: {
     token: string;
     sessionId?: string;
     activePlanId?: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
     access: "read" | "write";
 }): Promise<WorkerBuiltInToolPaths | undefined>;
 export declare function readWorkerTextFile(branchPath: string, filePath: string, offset?: number, limit?: number, builtInPaths?: WorkerBuiltInToolPaths): WorkerReadFileResult;
@@ -960,8 +980,7 @@ declare function executeWriteFileOperation(input: {
     resolvedTarget: ResolvedWorkerSessionTarget;
     baseUrl: string;
     token: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
     assertAdmission: () => void;
 }): Promise<WorkerWriteFileResult>;
 declare function executeEditFileOperation(input: {
@@ -971,8 +990,7 @@ declare function executeEditFileOperation(input: {
     resolvedTarget: ResolvedWorkerSessionTarget;
     baseUrl: string;
     token: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
     assertAdmission: () => void;
 }): Promise<WorkerEditFileResult>;
 export declare function grepWorkerFiles(branchPath: string, input: {
@@ -992,14 +1010,14 @@ export declare function listWorkerDirectory(branchPath: string, inputPath?: stri
 export declare function listWorkerCodeDirectory(branchPath: string, inputPath: string): WorkerCodeListResult;
 export declare function readWorkerCodeFile(branchPath: string, inputPath: string): WorkerCodeReadResult;
 export declare function readWorkerImageFile(branchPath: string, filePath: string, builtInPaths?: WorkerBuiltInToolPaths): WorkerViewFileBytesResult;
+declare function targetProcessEnv(rootDir: string, target: WorkerSessionTarget): Record<string, string>;
 export declare function prepareShellEnvForTarget(input: {
     target: WorkerSessionTarget;
     baseUrl: string;
     token: string;
     sessionId?: string;
     activePlanId?: string;
-    artifactRoot: string;
-    planRoot: string;
+    rootDir: string;
 }): Promise<Record<string, string>>;
 declare function createNodePtyBridge(options: {
     file: string;

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

@@ -1,20 +1,28 @@
 /**
- * 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.
+ * Decides which part of a project's hidden mirror a periodic observation must
+ * fetch, from the tokens the server advertises and the tokens the worker's
+ * own mirror refs cover (both computed with `project-mirror-refs-token.ts`).
  *
- * 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.
+ * Skipping is fail-open: any missing or mismatched information fetches.
+ *
+ * There is deliberately no timed backstop refetch for matching tokens. The
+ * server recomputes every advertised token from the canonical repository on
+ * disk on each heartbeat sweep, so a matching token is a fresh statement that
+ * the fetch would transfer nothing, whoever moved the refs. The worker
+ * records the tokens it covers from its own refs after every fetch and lease
+ * push, with the same shared formula, so a skip can only be stale if the
+ * canonical repository moved after the sweep that produced the advertisement
+ * — which the next sweep corrects, exactly like a tip that lands mid-cycle —
+ * or if the formula itself were wrong, which the shared module and its locked
+ * vectors guard and a periodic blind fetch would only hide. A project or
+ * mount the server advertises no token for fetches every cycle, as before
+ * tokens existed.
  */
-export declare const PROJECT_MIRROR_FETCH_BACKSTOP_MS: number;
+/** Why a fetch runs. `fail_closed` is never decided here: reset and remediation observation bypasses the gate. */
+export type ProjectMirrorFetchReason = "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "fail_closed";
 export type ProjectMirrorFetchDecision = {
     fetch: true;
-    reason: "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "backstop_elapsed";
+    reason: ProjectMirrorFetchReason;
 } | {
     fetch: false;
     reason: "token_match";
@@ -22,8 +30,55 @@ export type ProjectMirrorFetchDecision = {
 export declare function projectMirrorFetchDecision(input: {
     advertisedToken: string | undefined;
     fetchedToken: string | undefined;
-    lastFetchAtMs: number | undefined;
-    nowMs: number;
     skippingEnabled: boolean;
-    backstopMs?: number;
 }): ProjectMirrorFetchDecision;
+export type ProjectMirrorObservationFetchPlan = 
+/** Fetch every canonical ref of the project, as observation always did before per-mount tokens. */
+{
+    scope: "project";
+    reason: ProjectMirrorFetchReason;
+}
+/** Fetch only the named mounts' branch heads and handoff refs. */
+ | {
+    scope: "mounts";
+    mounts: Array<{
+        branchName: string;
+        reason: ProjectMirrorFetchReason;
+    }>;
+}
+/** Every token the observation depends on matches; reuse the local refs. */
+ | {
+    scope: "none";
+};
+/**
+ * Plan one project's observation fetch. With per-mount tokens advertised for
+ * the project, each mount decides for itself and only changed mounts fetch;
+ * without them (an older server) the project token decides for the whole
+ * mirror.
+ */
+export declare function planProjectMirrorObservationFetch(input: {
+    branchNames: readonly string[];
+    advertisedProjectToken: string | undefined;
+    /** Per-mount tokens for this project, keyed by branch name; undefined when the server advertised none. */
+    advertisedMountTokens: ReadonlyMap<string, string> | undefined;
+    fetchedProjectToken: string | undefined;
+    fetchedMountTokens: ReadonlyMap<string, string>;
+    skippingEnabled: boolean;
+}): ProjectMirrorObservationFetchPlan;
+export type ProjectMirrorRefsTokensAdvertisement = {
+    /** One token per project id. */
+    projectTokens: Map<string, string>;
+    /** Per-mount tokens keyed by project id then branch name; a project is present only when the server advertised mount tokens for it. */
+    mountTokens: Map<string, Map<string, string>>;
+    /** Current head of the user's hidden workspace repository, when advertised. */
+    workspaceHead: string | undefined;
+};
+/**
+ * Read a `project_mirror_refs_tokens` message. Older servers send only
+ * `tokens`; malformed entries are dropped, which fails open into fetching.
+ */
+export declare function parseProjectMirrorRefsTokensMessage(message: {
+    tokens?: unknown;
+    mountTokens?: unknown;
+    workspaceHead?: unknown;
+}): ProjectMirrorRefsTokensAdvertisement;

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

@@ -1,15 +1,40 @@
+/** Canonical namespaces the token hashes; also the observation fetch's sources. */
+export declare const PROJECT_MIRROR_REFS_TOKEN_NAMESPACES: readonly ["refs/heads/", "refs/r5d/server-synced/"];
+/** Worker-local copy of a canonical `refs/heads/*` ref. */
 export declare const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
 export declare const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+/** `git for-each-ref` format both sides list refs with; see parseProjectMirrorRefListing. */
+export declare const PROJECT_MIRROR_REF_LISTING_FORMAT = "--format=%(objectname) %(refname)";
 export type ProjectMirrorRef = {
     refname: string;
     objectName: string;
 };
+/** One checked-out project branch, identified by its durable incarnation id. */
+export type ProjectMirrorMount = {
+    branchName: string;
+    branchId: string;
+};
+export type ProjectMirrorRefsTokens = {
+    /** Hash over every ref in the observed namespaces. */
+    project: string;
+    /** Hash over one mount's branch head plus its handoff refs, keyed by branch name. */
+    mounts: Map<string, 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;
+/**
+ * Parse `git for-each-ref` output produced with
+ * PROJECT_MIRROR_REF_LISTING_FORMAT. Malformed rows throw rather than being
+ * dropped: a caller that cannot trust its listing must not produce a token.
+ * With `namespaces`, rows outside them throw too.
+ */
+export declare function parseProjectMirrorRefListing(output: string, options?: {
+    namespaces?: readonly string[];
+}): ProjectMirrorRef[];
 /**
  * Rename locally fetched mirror refs into the namespaces the server hashes.
  * Rows outside the two observed namespaces are dropped; the caller lists only
@@ -17,3 +42,12 @@ export declare function hashProjectMirrorRefs(refs: readonly ProjectMirrorRef[])
  * it can only make tokens differ — which fails open into a fetch.
  */
 export declare function canonicalizeLocalProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): ProjectMirrorRef[];
+/** The canonical refs one mount's token covers: its branch head and its server-synced handoff refs. */
+export declare function projectMirrorMountRefs(refs: readonly ProjectMirrorRef[], mount: ProjectMirrorMount): ProjectMirrorRef[];
+/**
+ * Compute the project token and one token per mount from one canonical ref
+ * listing. A mount's token is the project formula applied to the mount's own
+ * refs, so a mount whose branch is the only ref of its project has the same
+ * token as the project.
+ */
+export declare function projectMirrorRefsTokens(refs: readonly ProjectMirrorRef[], mounts: readonly ProjectMirrorMount[]): ProjectMirrorRefsTokens;

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

@@ -1,8 +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;
@@ -124,10 +133,17 @@ export declare function ensureProjectWorktrees(input: {
     onSnapshotProgress?: (progress: ProjectWorktreeSnapshotProgress) => void;
 }): Promise<ProjectWorktreeState[]>;
 export declare function projectWorktreeOperationInProgress(checkoutPath: string): boolean;
+/**
+ * How a new linked worktree's working tree starts. `carry` materializes the
+ * source checkout's Git-visible working state, uncommitted changes included;
+ * `clean` checks out the source branch's current commit and nothing else.
+ */
+export type ProjectWorktreeWorkingTreeMode = "carry" | "clean";
 export declare function createLinkedProjectBranch(input: {
     projectRoot: string;
     sourceBranchName: string;
     branchName: string;
+    workingTree: ProjectWorktreeWorkingTreeMode;
 }): {
     branchPath: string;
     baseCommitHash: string;
@@ -143,17 +159,56 @@ export declare function createOrRetryLinkedProjectBranch(input: {
     primaryBranchName: string;
     sourceBranchName: string;
     branchName: string;
+    workingTree: ProjectWorktreeWorkingTreeMode;
     pendingRetry: boolean;
 }): {
     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;
@@ -225,19 +280,28 @@ export declare function observeProjectMirrorHeads(input: Omit<ProjectMirrorHeadU
     allowNonFastForward: boolean;
     branchIds?: ReadonlyMap<string, string>;
     refreshRemote?: boolean;
+    /**
+     * Fetch only these mounts' branch heads and handoff refs, because
+     * per-mount token gating found every other mount current. Undefined
+     * fetches the whole mirror; an empty set fetches nothing, exactly like
+     * `refreshRemote: false`.
+     */
+    fetchOnlyBranches?: ReadonlySet<string>;
 }): 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`.
+ * Compute the tokens the locally cached mirror state covers — the project
+ * token and one token per mount — from one listing of `refs/r5d/mirror/*` and
+ * `refs/r5d/server-synced/*`, with the formula shared with the server. After a
+ * fetch these name exactly the canonical state the fetch transferred; after a
+ * successful lease push (which updates `refs/r5d/mirror/*` above) they predict
+ * the server's next advertisement unless something else also moved the
+ * canonical repository, in which case the mismatch fails open into a fetch.
  */
-export declare function computeLocalProjectMirrorRefsToken(input: {
+export declare function computeLocalProjectMirrorRefsTokens(input: {
     projectRoot: string;
     primaryBranchName: string;
-}): Promise<string>;
+    mounts: readonly ProjectMirrorMount[];
+}): Promise<ProjectMirrorRefsTokens>;
 /** Apply only previously observed object ids; this function never refetches. */
 export declare function applyObservedProjectMirrorHeads(input: {
     projectRoot: string;
@@ -272,6 +336,7 @@ export declare const projectWorktreesTestHarness: {
         projectRoot: string;
         branches: readonly ProjectWorktreeBranch[];
         temporaryRoot: string;
+        scope?: ProjectWorktreeSnapshotScope;
     }): {
         root: string;
     };

package/dist/types/workspace-git-sync.d.ts

@@ -38,6 +38,14 @@ export type WorkspaceGitMount = {
     busy?: () => boolean;
     /** Monotonic/opaque visible-mutation token used to catch short writes that begin and end between busy checks. */
     mutationToken?: () => string;
+    /**
+     * The token a completed cycle observed when it last projected this mount.
+     * While the current token still equals it and the mount's hydration basis
+     * is the outer HEAD being projected, the outer subtree already carries the
+     * visible bytes and the mirror copy is skipped. This is a cross-cycle skip
+     * only; the per-cycle busy and token re-checks are unchanged.
+     */
+    lastProjectedMutationToken?: string;
     /** Activity-only fence used before checkout readiness is established on reconnect. */
     busyForRecovery?: () => boolean;
 };
@@ -86,8 +94,12 @@ export type WorkspaceGitSyncResult = {
     affectedPaths: string[];
     activeMountIds: string[];
     skippedMountIds: string[];
+    /** Token each active mount carried when this cycle projected it; recorded by the caller to skip unchanged mounts later. */
+    projectedMutationTokens?: Record<string, string>;
     /** Creator-local mounts whose first outer publication was measured against their source subtree. */
     initialPublicationMountIds?: string[];
+    /** Network fetches of the outer workspace head this cycle ran; zero when the advertised head proved them unnecessary. */
+    remoteHeadFetches?: number;
     conflictPaths?: string[];
     conflictSnapshotRefs?: {
         local: string;
@@ -150,9 +162,12 @@ export declare function ensureWorkspaceGitClone(input: {
         email: string;
     };
     preserveResolutionInProgress?: boolean;
+    /** Server-advertised head of the workspace remote; see resolveWorkspaceRemoteHead. */
+    advertisedRemoteHead?: string | null;
 }): Promise<{
     localHead: string | null;
     remoteHead: string | null;
+    remoteHeadFetched: boolean;
 }>;
 type ProjectedMountGitlinks = {
     mount: WorkspaceGitMount;
@@ -204,7 +219,7 @@ export declare function resetWorkspaceGit(input: {
  * such as a subtree a gitlink replaces (see `pathsReplacedByGitlinks`).
  */
 declare function diffSizeBytes(workspacePath: string, baseRevision: string | null, headRevision: string, limit: number, pathspecs?: readonly string[]): Promise<number>;
-export declare function synchronizeWorkspaceGit(input: {
+export type SynchronizeWorkspaceGitInput = {
     attemptId?: string;
     workerLabel: string;
     workspacePath: string;
@@ -224,6 +239,12 @@ export declare function synchronizeWorkspaceGit(input: {
     skipMountMirror?: boolean;
     /** Positive ancestry proof required before a remediation may integrate, publish, or hydrate. */
     requiredAncestorHeads?: readonly string[];
+    /**
+     * Head of the workspace remote as the server last read it from disk. Equal
+     * to the local remote-tracking ref, it lets the cycle skip its workspace
+     * head fetches; see resolveWorkspaceRemoteHead. Omit to always fetch.
+     */
+    advertisedRemoteHead?: string | null;
     /** Revalidate the worker/config/incident generation after every async boundary. */
     assertStillAdmitted?: () => void;
     /** Test seam for exercising an incident transition during asynchronous diff measurement. */
@@ -234,7 +255,8 @@ export declare function synchronizeWorkspaceGit(input: {
     }) => void | Promise<void>;
     /** Announces each synchronous hydration transaction of this cycle; see WorkspaceHydrationTransactionHooks. */
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
-}): Promise<WorkspaceGitSyncResult>;
+};
+export declare function synchronizeWorkspaceGit(input: SynchronizeWorkspaceGitInput): Promise<WorkspaceGitSyncResult>;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;
     workspaceCloneCommandArgs: typeof workspaceCloneCommandArgs;