@ricsam/r5d-worker 0.0.57 → 0.0.59

package/dist/mjs/workspace-sync.mjs

@@ -5,8 +5,8 @@ import { managedBranchPath } from "./managed-paths.mjs";
 import { WorkspaceMutationGate } from "./workspace-mutation-gate.mjs";
 const WORKSPACE_BRANCH = "main";
 const WORKSPACE_INTENT_REF_PREFIX = "refs/r5d/workspace-intents/";
+const WORKSPACE_PUBLICATION_REF_PREFIX = "refs/r5d/workspace-publications/";
 const MAX_WORKSPACE_SYNC_DIFF_BYTES = 5 * 1024 * 1024;
-const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5e3;
 const MAX_REPORTED_WORKSPACE_PATHS = 2e3;
 const MAX_REPORTED_WORKSPACE_STATUS_BYTES = 256 * 1024;
 const MAX_MIRROR_COMPARISON_CACHE_ENTRIES = 2e5;
@@ -911,7 +911,7 @@ function hydrateProjectFromShadowOptimistically(input, relativeRoot, visibleRoot
     expectedCheckoutSnapshot = checkoutGitSnapshot(visibleRoot);
     return expectedCheckoutSnapshot !== null;
   };
-  let currentGitlinks = new Map(checkoutGitlinks(visibleRoot).map((entry) => [entry.filePath, entry]));
+  const currentGitlinks = new Map(checkoutGitlinks(visibleRoot).map((entry) => [entry.filePath, entry]));
   const changedPaths = [.../* @__PURE__ */ new Set([...preimage.keys(), ...desired.keys()])].filter(
     (filePath) => !hydrationEntriesEqual(preimage.get(filePath), desired.get(filePath))
   );
@@ -1533,6 +1533,33 @@ function resetUncommittedShadowSnapshot(input) {
   }
   runGit(input, input.shadowRoot, ["clean", "-fd"], "clean interrupted workspace snapshot");
 }
+function activeWorkspaceRebase(input) {
+  for (const name of ["rebase-merge", "rebase-apply"]) {
+    const resolved = runGitResult(input, input.shadowRoot, ["rev-parse", "--git-path", name]);
+    if (resolved.exitCode !== 0 || !resolved.stdout) continue;
+    const gitPath = path.isAbsolute(resolved.stdout) ? resolved.stdout : path.resolve(input.shadowRoot, resolved.stdout);
+    if (fs.existsSync(gitPath)) return name;
+  }
+  return null;
+}
+function remediationRebaseInProgressResult(input, result) {
+  if (input.trigger.type !== "remediation" && input.trigger.type !== "remediation_confirm") return null;
+  const rebaseKind = activeWorkspaceRebase(input);
+  if (!rebaseKind) return null;
+  const conflictPaths = runGitResult(input, input.shadowRoot, ["diff", "--name-only", "--diff-filter=U", "-z"]).stdout.split("\0").filter(Boolean).sort();
+  const status = reportedStatus(gitStatus(input));
+  return {
+    ...result,
+    outcome: "conflict_blocked",
+    expectedHead: revParse(input, `origin/${WORKSPACE_BRANCH}`),
+    candidateHead: revParse(input, "ORIG_HEAD") ?? revParse(input, "HEAD") ?? void 0,
+    rebaseCount: 1,
+    gitStatus: status,
+    affectedProjects: affectedProjects(conflictPaths),
+    affectedPaths: reportedPaths(conflictPaths),
+    error: `Workspace conflict remediation has an in-progress ${rebaseKind}; the index and worktree were preserved until the resolver completes or aborts it.`
+  };
+}
 function fastForwardCleanShadowForNewCheckouts(input) {
   if (!input.newVisibleCheckouts?.length) return null;
   runGit(input, input.shadowRoot, ["add", "-A"], "stage existing workspace changes before checkout hydration");
@@ -1678,9 +1705,12 @@ function commitMessage(input) {
   });
 }
 function assertWorkspaceQuarantineRef(quarantineRef) {
-  const suffix = quarantineRef.slice(WORKSPACE_INTENT_REF_PREFIX.length);
-  if (!quarantineRef.startsWith(WORKSPACE_INTENT_REF_PREFIX) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(suffix)) {
-    throw new Error(`Workspace candidate ref must be below ${WORKSPACE_INTENT_REF_PREFIX}`);
+  const prefix = quarantineRef.startsWith(WORKSPACE_PUBLICATION_REF_PREFIX) ? WORKSPACE_PUBLICATION_REF_PREFIX : WORKSPACE_INTENT_REF_PREFIX;
+  const suffix = quarantineRef.slice(prefix.length);
+  if (!quarantineRef.startsWith(prefix) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(suffix)) {
+    throw new Error(
+      `Workspace candidate ref must be below ${WORKSPACE_PUBLICATION_REF_PREFIX} or ${WORKSPACE_INTENT_REF_PREFIX}`
+    );
   }
   const result = Bun.spawnSync(["git", "check-ref-format", quarantineRef], {
     stdout: "pipe",
@@ -1752,17 +1782,105 @@ function convergeRedundantInboundCandidate(input, result) {
     affectedPaths: []
   };
 }
+function preserveWorkspaceConflictCandidate(input, observed, options) {
+  try {
+    if (!options.baseRevision) throw new Error("the preserved workspace does not have an old-base commit");
+    runGit(input, input.shadowRoot, ["reset", "--hard", options.baseRevision], "restore old-base workspace conflict candidate");
+    runGit(input, input.shadowRoot, ["clean", "-fd"], "clean old-base workspace conflict candidate");
+    if (!options.preserveShadowCandidate) {
+      const projection = mirrorVisibleWorkspaceToShadow(input);
+      restoreUnscopedCanonicalCheckoutSubtrees(input);
+      const stagePathspecs = projection.opaqueRoots.flatMap((root) => [`:(exclude,literal)${root}`]);
+      runGit(input, input.shadowRoot, ["add", "-A", "--", ".", ...stagePathspecs], "stage preserved workspace conflict candidate");
+      forceStageCanonicalCheckoutFiles(input, projection.entries, projection.opaqueRoots);
+      if (stagedPaths(input).length > 0) {
+        runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit preserved workspace conflict candidate");
+      }
+    }
+    const candidateHead = revParse(input, "HEAD");
+    if (!candidateHead) throw new Error("the preserved workspace conflict candidate does not have a commit");
+    assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, candidateHead);
+    const upload = uploadWorkspaceCandidate(input, candidateHead);
+    if (upload.exitCode !== 0) {
+      throw new Error(upload.stderr || upload.stdout || "workspace conflict candidate upload failed");
+    }
+    const conflictPaths = [...new Set(options.conflictPaths)].sort();
+    return {
+      ...observed,
+      outcome: "conflict_blocked",
+      expectedHead: options.expectedHead,
+      candidateHead,
+      quarantineRef: input.quarantineRef,
+      ...options.publishedHead ? { publishedHead: options.publishedHead } : {},
+      rebaseCount: options.rebaseCount ?? 0,
+      affectedProjects: affectedProjects(conflictPaths),
+      affectedPaths: reportedPaths(conflictPaths),
+      error: options.error,
+      gitStatus: gitStatus(input)
+    };
+  } catch (error) {
+    return {
+      ...observed,
+      outcome: "failed",
+      rebaseCount: options.rebaseCount ?? 0,
+      affectedProjects: affectedProjects(options.conflictPaths),
+      affectedPaths: reportedPaths(options.conflictPaths),
+      error: `Workspace synchronization found a conflict but could not preserve a durable candidate: ${error instanceof Error ? error.message : String(error)}`,
+      gitStatus: gitStatus(input)
+    };
+  }
+}
+function preserveLargeDiffCandidate(input, observed, error) {
+  try {
+    if (stagedPaths(input).length > 0) {
+      runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit blocked workspace candidate");
+    }
+    const candidateHead = revParse(input, "HEAD");
+    if (!candidateHead) throw new Error("the blocked workspace candidate does not have a commit");
+    assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, candidateHead);
+    const upload = uploadWorkspaceCandidate(input, candidateHead);
+    if (upload.exitCode !== 0) {
+      throw new Error(upload.stderr || upload.stdout || "blocked workspace candidate upload failed");
+    }
+    return {
+      ...observed,
+      outcome: "large_diff_blocked",
+      expectedHead: revParse(input, `origin/${WORKSPACE_BRANCH}`),
+      candidateHead,
+      quarantineRef: input.quarantineRef,
+      error,
+      gitStatus: gitStatus(input)
+    };
+  } catch (candidateError) {
+    return {
+      ...observed,
+      outcome: "failed",
+      error: `Workspace safety guard blocked publication but could not preserve a durable candidate: ${candidateError instanceof Error ? candidateError.message : String(candidateError)}`,
+      gitStatus: gitStatus(input)
+    };
+  }
+}
 async function synchronizeWorkspace(rawInput) {
   let input = { ...rawInput, attemptId: rawInput.attemptId ?? crypto.randomUUID() };
   try {
     input = { ...input, projects: workspaceProjectsForSync(input.projects, input.trigger) };
+    const isCanonicalRemediationSync = input.skipVisibleMirror === true && (input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm");
     let mirroredGitlinkProjection = { entries: [], opaqueRoots: [], visiblePreimages: /* @__PURE__ */ new Map() };
     let fastForwardedFromHead = null;
     const shadowWasCreated = ensureShadowWorkspace(input);
     let hydrationPreimages = input.skipVisibleMirror ? hydrationPreimagesFromShadowRevision(input, shadowWasCreated ? null : revParse(input, "HEAD")) : /* @__PURE__ */ new Map();
     const remoteHeadAtStart = revParse(input, `origin/${WORKSPACE_BRANCH}`);
     const result = baseResult(input, remoteHeadAtStart);
-    const inboundConflictsAtStart = input.skipVisibleMirror && remoteHeadAtStart ? visibleHydrationConflictPaths(input, hydrationPreimages, `origin/${WORKSPACE_BRANCH}`) : [];
+    if (input.expectedCanonicalHead !== void 0 && remoteHeadAtStart !== input.expectedCanonicalHead) {
+      return {
+        ...result,
+        outcome: "failed",
+        expectedHead: input.expectedCanonicalHead,
+        publishedHead: remoteHeadAtStart ?? void 0,
+        error: `canonical_head_advanced: expected ${input.expectedCanonicalHead ?? "unborn"}, fetched ${remoteHeadAtStart ?? "unborn"}`
+      };
+    }
+    const inboundConflictsAtStart = input.skipVisibleMirror && !isCanonicalRemediationSync && remoteHeadAtStart ? visibleHydrationConflictPaths(input, hydrationPreimages, `origin/${WORKSPACE_BRANCH}`) : [];
     if (input.resetToCanonical) {
       if (input.trigger.canonicalCheckoutOnly) {
         throw new Error("A canonical-checkout-only synchronization cannot reset the authoritative resolver checkout");
@@ -1776,6 +1894,8 @@ async function synchronizeWorkspace(rawInput) {
         gitStatus: gitStatus(input)
       };
     }
+    const inProgressRemediation = remediationRebaseInProgressResult(input, result);
+    if (inProgressRemediation) return inProgressRemediation;
     if (!input.skipVisibleMirror) resetUncommittedShadowSnapshot(input);
     restoreUnscopedCanonicalCheckoutSubtrees(input);
     if (!input.skipVisibleMirror) {
@@ -1808,18 +1928,18 @@ async function synchronizeWorkspace(rawInput) {
     const destructiveReductions = destructiveCheckoutReductions(input, baseRevision);
     if (destructiveReductions.length > 0 && !input.confirmedLargeDiff) {
       const summary = destructiveReductions.map(({ root, trackedBefore, trackedAfter }) => `${root} (${trackedBefore} -> ${trackedAfter} tracked files)`).join(", ");
-      return {
-        ...observed,
-        outcome: "large_diff_blocked",
-        error: `Workspace safety guard blocked a destructive checkout reduction: ${summary}`
-      };
+      return preserveLargeDiffCandidate(
+        input,
+        observed,
+        `Workspace safety guard blocked a destructive checkout reduction: ${summary}`
+      );
     }
     if (paths.length > 0 && diffSizeBytes > MAX_WORKSPACE_SYNC_DIFF_BYTES && !input.confirmedLargeDiff && !input.trigger.canonicalCheckoutOnly) {
-      return {
-        ...observed,
-        outcome: "large_diff_blocked",
-        error: `Workspace safety guard blocked a ${diffSizeBytes}-byte diff above the ${MAX_WORKSPACE_SYNC_DIFF_BYTES}-byte automatic publication limit.`
-      };
+      return preserveLargeDiffCandidate(
+        input,
+        observed,
+        `Workspace safety guard blocked a ${diffSizeBytes}-byte diff above the ${MAX_WORKSPACE_SYNC_DIFF_BYTES}-byte automatic publication limit.`
+      );
     }
     if (stagedWorkingPaths.length > 0) {
       runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit workspace changes");
@@ -1831,15 +1951,12 @@ async function synchronizeWorkspace(rawInput) {
     const hasUnpushedCommit = candidateHead ? !hasRemoteMain || !tryGit(input, input.shadowRoot, ["merge-base", "--is-ancestor", candidateHead, `origin/${WORKSPACE_BRANCH}`]) : false;
     if (hasUnpushedCommit && inboundConflictsAtStart.length > 0) {
       const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...inboundConflictsAtStart])].sort();
-      return {
-        ...observed,
-        outcome: "failed",
-        candidateHead: candidateHead ?? void 0,
-        affectedProjects: affectedProjects(conflictPaths),
-        affectedPaths: reportedPaths(conflictPaths),
-        error: "Inbound workspace update overlaps local visible changes; the old-base candidate was preserved for reconciliation.",
-        gitStatus: gitStatus(input)
-      };
+      return preserveWorkspaceConflictCandidate(input, observed, {
+        baseRevision: candidateHead,
+        expectedHead: revParse(input, `origin/${WORKSPACE_BRANCH}`),
+        conflictPaths,
+        error: "Inbound workspace update overlaps local visible changes; the old-base candidate was preserved for reconciliation."
+      });
     }
     if (!hasUnpushedCommit) {
       const localHead = revParse(input, "HEAD");
@@ -1848,22 +1965,21 @@ async function synchronizeWorkspace(rawInput) {
         runGit(input, input.shadowRoot, ["reset", "--hard", `origin/${WORKSPACE_BRANCH}`], "update workspace from canonical state");
         runGit(input, input.shadowRoot, ["clean", "-fd"], "clean updated workspace");
         assertPublishedCanonicalCheckoutTree(input, currentRemoteHead, sampledCanonicalCheckoutTreeHash);
-        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
-        const inboundConflicts = input.trigger.canonicalCheckoutOnly ? [] : localHead ? hydrationConflictPaths(input, hydrationPreimages, localHead, currentRemoteHead) : visibleHydrationConflictPaths(input, hydrationPreimages, currentRemoteHead);
+        if (!isCanonicalRemediationSync) {
+          mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
+        }
+        const inboundConflicts = input.trigger.canonicalCheckoutOnly || isCanonicalRemediationSync ? [] : localHead ? hydrationConflictPaths(input, hydrationPreimages, localHead, currentRemoteHead) : visibleHydrationConflictPaths(input, hydrationPreimages, currentRemoteHead);
         if (inboundConflicts.length > 0 && localHead) {
           runGit(input, input.shadowRoot, ["reset", "--hard", localHead], "preserve old workspace base after inbound conflict");
           runGit(input, input.shadowRoot, ["clean", "-fd"], "clean preserved old workspace base");
           const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...inboundConflicts])].sort();
-          return {
-            ...observed,
-            outcome: "failed",
-            candidateHead: candidateHead ?? void 0,
+          return preserveWorkspaceConflictCandidate(input, observed, {
+            baseRevision: localHead,
+            expectedHead: currentRemoteHead,
             publishedHead: currentRemoteHead,
-            affectedProjects: affectedProjects(conflictPaths),
-            affectedPaths: reportedPaths(conflictPaths),
-            error: "Inbound workspace update overlaps local visible changes; disjoint updates were hydrated and the old base was preserved for reconciliation.",
-            gitStatus: gitStatus(input)
-          };
+            conflictPaths,
+            error: "Inbound workspace update overlaps local visible changes; disjoint updates were hydrated and the old base was preserved for reconciliation."
+          });
         }
         return {
           ...observed,
@@ -1876,8 +1992,10 @@ async function synchronizeWorkspace(rawInput) {
       const authoritativeHead = currentRemoteHead ?? localHead;
       if (authoritativeHead) {
         assertPublishedCanonicalCheckoutTree(input, authoritativeHead, sampledCanonicalCheckoutTreeHash);
-        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
-        const hydrationConflicts2 = input.trigger.canonicalCheckoutOnly ? [] : fastForwardedFromHead ? hydrationConflictPaths(input, hydrationPreimages, fastForwardedFromHead, authoritativeHead) : visibleHydrationConflictPaths(input, hydrationPreimages, authoritativeHead);
+        if (!isCanonicalRemediationSync) {
+          mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
+        }
+        const hydrationConflicts2 = input.trigger.canonicalCheckoutOnly || isCanonicalRemediationSync ? [] : fastForwardedFromHead ? hydrationConflictPaths(input, hydrationPreimages, fastForwardedFromHead, authoritativeHead) : visibleHydrationConflictPaths(input, hydrationPreimages, authoritativeHead);
         if (hydrationConflicts2.length > 0 && fastForwardedFromHead) {
           runGit(
             input,
@@ -1886,16 +2004,13 @@ async function synchronizeWorkspace(rawInput) {
             "preserve old workspace base after new-checkout fast-forward conflict"
           );
           runGit(input, input.shadowRoot, ["clean", "-fd"], "clean preserved new-checkout workspace base");
-          return {
-            ...observed,
-            outcome: "failed",
-            candidateHead: candidateHead ?? void 0,
+          return preserveWorkspaceConflictCandidate(input, observed, {
+            baseRevision: fastForwardedFromHead,
+            expectedHead: currentRemoteHead,
             publishedHead: currentRemoteHead ?? void 0,
-            affectedProjects: affectedProjects(hydrationConflicts2),
-            affectedPaths: reportedPaths(hydrationConflicts2),
-            error: "Workspace fast-forward for a new checkout overlaps local visible changes; compatible updates were hydrated and the old base was preserved for reconciliation.",
-            gitStatus: gitStatus(input)
-          };
+            conflictPaths: hydrationConflicts2,
+            error: "Workspace fast-forward for a new checkout overlaps local visible changes; compatible updates were hydrated and the old base was preserved for reconciliation."
+          });
         }
       }
       return {
@@ -1915,17 +2030,14 @@ async function synchronizeWorkspace(rawInput) {
         const conflicted = runGitResult(input, input.shadowRoot, ["diff", "--name-only", "--diff-filter=U", "-z"]);
         const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...conflicted.stdout.split("\0").filter(Boolean)])].sort();
         runGit(input, input.shadowRoot, ["rebase", "--abort"], "preserve workspace candidate after rebase conflict");
-        return {
-          ...observed,
-          outcome: "failed",
+        return preserveWorkspaceConflictCandidate(input, observed, {
+          baseRevision: candidateHead,
           expectedHead,
-          candidateHead: candidateHead ?? void 0,
           rebaseCount,
-          affectedProjects: affectedProjects(conflictPaths),
-          affectedPaths: reportedPaths(conflictPaths),
-          error: `Workspace candidate conflicts with canonical head ${expectedHead}; local changes were preserved for reconciliation.`,
-          gitStatus: gitStatus(input)
-        };
+          preserveShadowCandidate: isCanonicalRemediationSync,
+          conflictPaths,
+          error: `Workspace candidate conflicts with canonical head ${expectedHead}; local changes were preserved for reconciliation.`
+        });
       }
       candidateHead = revParse(input, "HEAD");
       assertPublishedCanonicalCheckoutTree(input, "HEAD", sampledCanonicalCheckoutTreeHash);
@@ -1941,8 +2053,10 @@ async function synchronizeWorkspace(rawInput) {
       };
     }
     assertPublishedCanonicalCheckoutTree(input, candidateHead, sampledCanonicalCheckoutTreeHash);
-    mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
-    const hydrationConflicts = input.trigger.canonicalCheckoutOnly ? [] : candidateHeadBeforeRebase ? hydrationConflictPaths(input, hydrationPreimages, candidateHeadBeforeRebase, "HEAD") : visibleHydrationConflictPaths(input, hydrationPreimages, "HEAD");
+    if (!isCanonicalRemediationSync) {
+      mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots, hydrationPreimages);
+    }
+    const hydrationConflicts = input.trigger.canonicalCheckoutOnly || isCanonicalRemediationSync ? [] : candidateHeadBeforeRebase ? hydrationConflictPaths(input, hydrationPreimages, candidateHeadBeforeRebase, "HEAD") : visibleHydrationConflictPaths(input, hydrationPreimages, "HEAD");
     if (hydrationConflicts.length > 0 && candidateHeadBeforeRebase) {
       runGit(
         input,
@@ -1952,17 +2066,13 @@ async function synchronizeWorkspace(rawInput) {
       );
       runGit(input, input.shadowRoot, ["clean", "-fd"], "clean old-base workspace candidate");
       const conflictPaths = [.../* @__PURE__ */ new Set([...paths, ...hydrationConflicts])].sort();
-      return {
-        ...observed,
-        outcome: "failed",
+      return preserveWorkspaceConflictCandidate(input, observed, {
+        baseRevision: candidateHeadBeforeRebase,
         expectedHead,
-        candidateHead,
         rebaseCount,
-        affectedProjects: affectedProjects(conflictPaths),
-        affectedPaths: reportedPaths(conflictPaths),
-        error: "Workspace changed while its candidate was reconciling; visible changes and the old-base candidate were preserved.",
-        gitStatus: gitStatus(input)
-      };
+        conflictPaths,
+        error: "Workspace changed while its candidate was reconciling; visible changes and the old-base candidate were preserved."
+      });
     }
     const upload = uploadWorkspaceCandidate(input, candidateHead);
     if (upload.exitCode !== 0) {
@@ -1994,6 +2104,79 @@ async function synchronizeWorkspace(rawInput) {
     };
   }
 }
+async function convergeWorkspaceHead(rawInput, options) {
+  const input = {
+    ...rawInput,
+    projects: workspaceProjectsForSync(rawInput.projects, rawInput.trigger)
+  };
+  if (input.trigger.canonicalCheckoutOnly) {
+    throw new Error("Ordinary inbound convergence cannot target a canonical resolver checkout");
+  }
+  ensureShadowWorkspace(input);
+  const fetchedLocalHead = revParse(input, "HEAD");
+  const fetchedCanonicalHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+  if (!options.hydrateVisible) {
+    return {
+      localHead: fetchedLocalHead,
+      canonicalHead: fetchedCanonicalHead,
+      localChanges: false,
+      hydrated: false,
+      hydrationConflicts: []
+    };
+  }
+  resetUncommittedShadowSnapshot(input);
+  restoreUnscopedCanonicalCheckoutSubtrees(input);
+  const localHead = fetchedLocalHead;
+  const canonicalHead = fetchedCanonicalHead;
+  const projection = mirrorVisibleWorkspaceToShadow(input);
+  runGit(
+    input,
+    input.shadowRoot,
+    ["add", "-A", "--", ".", ...projection.opaqueRoots.map((root) => `:(exclude,literal)${root}`)],
+    "stage inbound workspace observation"
+  );
+  forceStageCanonicalCheckoutFiles(input, projection.entries, projection.opaqueRoots);
+  const stagedTree = runGit(input, input.shadowRoot, ["write-tree"], "write inbound workspace observation tree");
+  const headTree = localHead ? revParse(input, `${localHead}^{tree}`) : null;
+  const localChanges = stagedTree !== headTree;
+  if (!options.hydrateVisible || localChanges || !canonicalHead || localHead === canonicalHead) {
+    resetUncommittedShadowSnapshot(input);
+    return { localHead, canonicalHead, localChanges, hydrated: false, hydrationConflicts: [] };
+  }
+  const preimages = projection.visiblePreimages ?? hydrationPreimagesFromShadowRevision(input, localHead);
+  const hydrationConflicts = localHead ? hydrationConflictPaths(input, preimages, localHead, canonicalHead) : [];
+  if (hydrationConflicts.length > 0) {
+    resetUncommittedShadowSnapshot(input);
+    return { localHead, canonicalHead, localChanges: true, hydrated: false, hydrationConflicts };
+  }
+  runGit(input, input.shadowRoot, ["reset", "--hard", canonicalHead], "fast-forward workspace to available canonical head");
+  runGit(input, input.shadowRoot, ["clean", "-fd"], "clean fast-forwarded workspace");
+  mirrorShadowWorkspaceToVisible(input, projection.opaqueRoots, preimages);
+  return { localHead: canonicalHead, canonicalHead, localChanges: false, hydrated: true, hydrationConflicts: [] };
+}
+function calculateWorkspaceLocalDiffFingerprint(rawInput) {
+  const input = {
+    ...rawInput,
+    projects: workspaceProjectsForSync(rawInput.projects, rawInput.trigger)
+  };
+  if (!fs.existsSync(path.join(input.shadowRoot, ".git"))) {
+    throw new Error("Cannot inspect local workspace changes before first bootstrap");
+  }
+  resetUncommittedShadowSnapshot(input);
+  restoreUnscopedCanonicalCheckoutSubtrees(input);
+  const projection = mirrorVisibleWorkspaceToShadow(input);
+  runGit(
+    input,
+    input.shadowRoot,
+    ["add", "-A", "--", ".", ...projection.opaqueRoots.map((root) => `:(exclude,literal)${root}`)],
+    "stage local workspace fingerprint"
+  );
+  forceStageCanonicalCheckoutFiles(input, projection.entries, projection.opaqueRoots);
+  const stagedTree = runGit(input, input.shadowRoot, ["write-tree"], "write local workspace fingerprint tree");
+  const headTree = revParse(input, "HEAD^{tree}");
+  resetUncommittedShadowSnapshot(input);
+  return stagedTree === headTree ? createHash("sha256").update("").digest("hex") : createHash("sha256").update(stagedTree).digest("hex");
+}
 function calculateWorkspaceDiffFingerprint(rawInput) {
   const input = {
     ...rawInput,
@@ -2047,6 +2230,9 @@ class WorkspaceSyncSingleFlight {
   fingerprintPrepared(prepare) {
     return this.enqueue(() => calculateWorkspaceDiffFingerprint(prepare()));
   }
+  runExclusive(operation) {
+    return this.enqueue(operation);
+  }
   runMutation(operation) {
     return this.mutationGate.runMutation(operation);
   }
@@ -2062,11 +2248,13 @@ export {
   WORKSPACE_BRANCH,
   WORKSPACE_INTENT_REF_PREFIX,
   WORKSPACE_NATIVE_PLANS_RELATIVE_PATH,
-  WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
+  WORKSPACE_PUBLICATION_REF_PREFIX,
   WorkspaceSyncSingleFlight,
   assertCanonicalCheckoutIndexMatchesWorktree,
   assertWorkspaceQuarantineRef,
   calculateWorkspaceDiffFingerprint,
+  calculateWorkspaceLocalDiffFingerprint,
+  convergeWorkspaceHead,
   encodeWorkspaceBranch,
   mirrorShadowWorkspaceToVisible,
   mirrorVisibleWorkspaceToShadow,

package/dist/types/workspace-convergence.d.ts

@@ -0,0 +1,102 @@
+export declare const WORKSPACE_CHECKPOINT_QUIET_MS = 5000;
+export declare const WORKSPACE_IDLE_SAFETY_SCAN_MS = 60000;
+export type WorkspaceCheckpointState = "idle" | "scheduled" | "preparing" | "submitting" | "blocked";
+export type WorkspaceConvergenceSnapshot = {
+    localHead: string | null;
+    desiredCanonicalHead: string | null;
+    dirtyGeneration: number;
+    publishedGeneration: number;
+    checkpointState: WorkspaceCheckpointState;
+};
+export type ExplicitWorkspaceCheckpoint<TTrigger> = {
+    requestId: string;
+    trigger: TTrigger;
+};
+export type WorkspaceManifestRevisionToken = {
+    sequence: number;
+    revision: string;
+};
+export type WorkspaceWriterLease = () => void;
+/**
+ * Makes checkpoint admission atomic with command startup. Once a checkpoint
+ * lease is admitted, later writers wait; once a writer lease is admitted, a
+ * checkpoint must defer. Writer acquisition increments synchronously before
+ * its promise resolves, covering asynchronous environment setup and spawn.
+ */
+export declare class WorkspaceFilesystemWriterGate {
+    private activeWriters;
+    private checkpointActive;
+    private readonly waitingWriters;
+    private readonly waitingCheckpoints;
+    acquireWriter(): Promise<WorkspaceWriterLease>;
+    tryAcquireCheckpoint(): WorkspaceWriterLease | null;
+    acquireCheckpoint(): Promise<WorkspaceWriterLease>;
+    private checkpointRelease;
+    private writerRelease;
+    private drain;
+}
+export declare function processWorkspaceFilesystemWriterGate(): WorkspaceFilesystemWriterGate;
+export declare class WorkspaceManifestRevisionFence {
+    private sequence;
+    private requestedRevision;
+    private completedRevision;
+    begin(revision: string): WorkspaceManifestRevisionToken;
+    isCurrent(token: WorkspaceManifestRevisionToken): boolean;
+    complete(token: WorkspaceManifestRevisionToken): boolean;
+    readyRevision(): string | null;
+}
+export declare function workspaceCheckpointTelemetry(input: {
+    requestedAt: number;
+    prepareStartedAt: number;
+    synchronizeStartedAt: number;
+    finishedAt: number;
+}): {
+    totalMs: number;
+    queueMs: number;
+    prepareMs: number;
+    synchronizeMs: number;
+};
+export declare function workspaceCheckpointIncidentAction(requestId: string | undefined): "defer_automatic" | "request_terminal_authority";
+export declare class ExplicitWorkspaceCheckpointQueue<TTrigger> {
+    private scheduled;
+    private readonly queued;
+    schedule(checkpoint: ExplicitWorkspaceCheckpoint<TTrigger>, pendingRequestId?: string): boolean;
+    hasScheduled(): boolean;
+    consumeScheduled(requestId: string): void;
+    enqueue(checkpoint: ExplicitWorkspaceCheckpoint<TTrigger>, pendingRequestId?: string): void;
+    next(): ExplicitWorkspaceCheckpoint<TTrigger> | undefined;
+}
+type PersistedWorkspaceConvergenceState = Omit<WorkspaceConvergenceSnapshot, "checkpointState">;
+export declare function readWorkspaceConvergenceState(statePath: string): PersistedWorkspaceConvergenceState;
+export declare class WorkspaceConvergenceState {
+    private readonly statePath;
+    private state;
+    private checkpointState;
+    constructor(statePath: string);
+    snapshot(): WorkspaceConvergenceSnapshot;
+    setLocalHead(localHead: string | null): void;
+    observeCanonicalHead(canonicalHead: string | null): boolean;
+    markDirty(): number;
+    schedule(): void;
+    beginPreparing(): void;
+    beginSubmitting(): void;
+    defer(): void;
+    block(): void;
+    releaseBlock(): void;
+    observeIncidentState(blocked: boolean): void;
+    resetTransientCheckpointState(): void;
+    complete(input: {
+        generation: number;
+        canonicalHead: string | null;
+        published: boolean;
+    }): void;
+    private persist;
+}
+export declare function processWorkspaceConvergenceState(statePath: string): WorkspaceConvergenceState;
+export declare function waitForWorkspaceCheckpointOnShutdown(input: {
+    snapshot: () => WorkspaceConvergenceSnapshot;
+    forceCheckpoint: () => void;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<"settled" | "blocked" | "timed_out">;
+export {};

package/dist/types/workspace-incident-state.d.ts

@@ -2,7 +2,21 @@ export type WorkspaceIncidentUpdate = {
     incidentId: string | null;
     status: "remediating" | "waiting_for_worker" | "resolved" | "confirmed" | "reset" | null;
 };
+/**
+ * WebSocket writes are ordered, but independent server handlers can decide an
+ * incident state under the user lock and write their messages after releasing
+ * it. Remember terminal incident IDs so a delayed checkpoint response cannot
+ * resurrect a barrier that this connection has already observed as terminal.
+ */
+export declare class WorkspaceIncidentOrderingFence {
+    private readonly historyLimit;
+    private readonly terminalIncidentIds;
+    private readonly terminalIncidentOrder;
+    constructor(historyLimit?: number);
+    observe(update: WorkspaceIncidentUpdate): void;
+    permitsBlockedResponse(incidentId: string | null | undefined): boolean;
+}
 export declare function applyWorkspaceIncidentUpdate(currentIncidentId: string | null, update: WorkspaceIncidentUpdate): string | null;
 export declare function releasePendingWorkspaceHead(previousIncidentId: string | null, currentIncidentId: string | null, terminalIncidentId?: string | null): {
-    syncHead: string | null;
+    fetchAuthoritativeHead: boolean;
 };

package/dist/types/workspace-manifest-admission.d.ts

@@ -0,0 +1,27 @@
+import type { WorkspaceFilesystemWriterGate, WorkspaceWriterLease } from "./workspace-convergence";
+export type WorkspaceManifestCheckout = {
+    projectId: string;
+    projectPath: string;
+    checkoutPathSegments: [namespace: string, project: string];
+    branches: string[];
+};
+export type WorkspaceManifestAdmission = {
+    firstBootstrap: boolean;
+    missingCheckouts: Array<{
+        projectId: string;
+        branchName: string;
+    }>;
+    migratedProjectIds: string[];
+    requiresVisibleLease: boolean;
+};
+/**
+ * Inspects only the paths that make manifest acknowledgement mutate existing
+ * visible state. Missing checkouts are reported as target-specific pending
+ * work and hydrated opportunistically; they must not delay unrelated targets.
+ */
+export declare function inspectWorkspaceManifestAdmission(input: {
+    projectsRoot: string;
+    workspaceShadowRoot: string;
+    projects: WorkspaceManifestCheckout[];
+}): WorkspaceManifestAdmission;
+export declare function acquireWorkspaceManifestVisibleLease(gate: WorkspaceFilesystemWriterGate, admission: WorkspaceManifestAdmission): Promise<WorkspaceWriterLease | undefined>;