@ricsam/r5d-worker 0.0.58 → 0.0.59

package/dist/mjs/main.mjs

@@ -13,13 +13,27 @@ import {
 } from "./heartbeat.mjs";
 import { terminateProcessTree } from "./process-tree.mjs";
 import { openWorkerPortForwardRelay } from "./port-forward-client.mjs";
-import { applyWorkspaceIncidentUpdate, releasePendingWorkspaceHead } from "./workspace-incident-state.mjs";
+import {
+  applyWorkspaceIncidentUpdate,
+  releasePendingWorkspaceHead,
+  WorkspaceIncidentOrderingFence
+} from "./workspace-incident-state.mjs";
 import { acquireWorkspaceCommandMutation, runWorkspaceCommand } from "./workspace-command-sync-policy.mjs";
 import {
-  RecentWorkspaceSyncProofCache,
-  readShadowWorkspaceCanonicalHead,
-  workspaceSyncScopeKey
-} from "./workspace-sync-fast-path.mjs";
+  WORKSPACE_CHECKPOINT_QUIET_MS,
+  WORKSPACE_IDLE_SAFETY_SCAN_MS,
+  ExplicitWorkspaceCheckpointQueue,
+  WorkspaceManifestRevisionFence,
+  processWorkspaceConvergenceState,
+  processWorkspaceFilesystemWriterGate,
+  waitForWorkspaceCheckpointOnShutdown,
+  workspaceCheckpointIncidentAction,
+  workspaceCheckpointTelemetry
+} from "./workspace-convergence.mjs";
+import {
+  acquireWorkspaceManifestVisibleLease,
+  inspectWorkspaceManifestAdmission
+} from "./workspace-manifest-admission.mjs";
 import {
   isRetryableWorkerServerStatus,
   superviseWorkerRuntime,
@@ -30,15 +44,11 @@ import {
 } from "./supervisor.mjs";
 import { managedProjectRoot, migrateLegacyProjectRoots, validateManagedBranchName } from "./managed-paths.mjs";
 import {
-  WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
   WorkspaceSyncSingleFlight,
-  calculateWorkspaceDiffFingerprint,
+  convergeWorkspaceHead,
   synchronizeWorkspace,
   workspaceProjectsForSync
 } from "./workspace-sync.mjs";
-function workspaceSyncFastPathTelemetry(decision) {
-  return decision.hit ? { hit: true, reason: decision.reason, proofAgeMs: decision.proofAgeMs } : { hit: false, reason: decision.reason };
-}
 class WorkerServerUnavailableError extends Error {
   name = "WorkerServerUnavailableError";
 }
@@ -54,6 +64,7 @@ const cancelledProcessRuns = /* @__PURE__ */ new Set();
 const activePtys = /* @__PURE__ */ new Map();
 let currentWorkerSocket = null;
 const workspaceSyncSingleFlight = new WorkspaceSyncSingleFlight();
+const workspaceFilesystemWriters = processWorkspaceFilesystemWriterGate();
 let githubCredential = null;
 let visibleGitIdentity = null;
 function defaultConfigPath() {
@@ -2268,6 +2279,7 @@ async function openPty(input) {
     onExit: (event) => {
       input.releaseWorkspaceMutation?.();
       activePtys.delete(input.message.ptyId);
+      input.onTerminal?.();
       sendWorkerMessage(input.ws, {
         type: "pty_exit",
         ptyId: input.message.ptyId,
@@ -2278,6 +2290,7 @@ async function openPty(input) {
     onError: (error) => {
       input.releaseWorkspaceMutation?.();
       activePtys.delete(input.message.ptyId);
+      input.onTerminal?.();
       sendWorkerMessage(input.ws, {
         type: "pty_error",
         requestId: input.message.requestId,
@@ -2369,15 +2382,25 @@ async function startWorker(options) {
   const pendingManifestCheckouts = /* @__PURE__ */ new Map();
   let workspaceRemoteUrl = null;
   let activeWorkspaceIncidentId = null;
-  let previousPeriodicFingerprint = null;
-  let periodicWorkspaceScan;
-  let periodicWorkspaceScanInFlight = false;
+  const workspaceIncidentOrdering = new WorkspaceIncidentOrderingFence();
+  const workspaceConvergence = processWorkspaceConvergenceState(path.join(syncRoot, "workspace-convergence.json"));
+  const workspaceManifestRevision = new WorkspaceManifestRevisionFence();
+  let workspaceReady = false;
+  let workspaceCheckpointTimer;
+  let workspaceSafetyScan;
+  let workspaceManifestHydrationTimer;
+  let workspaceManifestHydrationInFlight = false;
+  let workspaceSafetyScanInFlight = false;
+  let workspaceHeadConvergenceInFlight = false;
+  let pendingWorkspaceHead;
+  let pendingCheckpoint;
+  const explicitWorkspaceCheckpoints = new ExplicitWorkspaceCheckpointQueue();
   let terminalReplayTimer;
   let workspaceSyncRequestsInFlight = 0;
   let sessionArtifactSyncRequestsInFlight = 0;
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
-  const recentWorkspaceSyncProof = new RecentWorkspaceSyncProofCache();
+  let shutdownAfterClose = false;
   const workspaceSyncInput = (trigger, overrides = {}) => {
     if (!workspaceRemoteUrl) throw new Error("Worker workspace manifest has not been received");
     const projects = workspaceProjectsForSync([...manifestByProjectId.values()], trigger);
@@ -2403,21 +2426,175 @@ async function startWorker(options) {
       );
     }
   };
-  const requestWorkspaceSync = (trigger, fingerprint) => {
+  const sendWorkspaceReady = () => {
+    const manifestRevision = workspaceManifestRevision.readyRevision();
+    if (!workspaceReady || !manifestRevision) return;
     try {
       ws.send(
         JSON.stringify({
-          type: "workspace_sync_requested",
-          observationId: crypto.randomUUID(),
+          type: "workspace_ready",
+          manifestRevision,
+          pendingCheckouts: [...pendingManifestCheckouts.values()].sort(
+            (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
+          ),
+          ...workspaceConvergence.snapshot()
+        })
+      );
+    } catch (error) {
+      process.stderr.write(
+        `[r5d-worker] failed to send workspace readiness: ${error instanceof Error ? error.message : String(error)}
+`
+      );
+    }
+  };
+  const workerHasActiveWriter = () => activeProcesses.size > 0 || activePtys.size > 0 || cliUpdateInProgress;
+  const targetMayMutateVisibleWorkspace = (target) => target.type === "project" || target.rootProfile === "visible_projects";
+  const armWorkspaceCheckpoint = (trigger, options2 = { delayMs: WORKSPACE_CHECKPOINT_QUIET_MS }) => {
+    workspaceConvergence.schedule();
+    if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) return;
+    sendWorkspaceReady();
+    if (options2.requestId && !explicitWorkspaceCheckpoints.schedule({ requestId: options2.requestId, trigger }, pendingCheckpoint?.requestId)) {
+      return;
+    }
+    if (!options2.requestId && explicitWorkspaceCheckpoints.hasScheduled()) return;
+    if (workspaceCheckpointTimer) clearTimeout(workspaceCheckpointTimer);
+    workspaceCheckpointTimer = setTimeout(() => {
+      workspaceCheckpointTimer = void 0;
+      if (options2.requestId) explicitWorkspaceCheckpoints.consumeScheduled(options2.requestId);
+      if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) return;
+      if (!workspaceReady || !workspaceRemoteUrl) {
+        armWorkspaceCheckpoint(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+        return;
+      }
+      if (activeWorkspaceIncidentId) {
+        workspaceConvergence.block();
+        sendWorkspaceReady();
+        if (workspaceCheckpointIncidentAction(options2.requestId) === "defer_automatic") return;
+        if (pendingCheckpoint) {
+          explicitWorkspaceCheckpoints.enqueue({ requestId: options2.requestId, trigger }, pendingCheckpoint.requestId);
+          return;
+        }
+        const snapshot2 = workspaceConvergence.snapshot();
+        pendingCheckpoint = {
+          requestId: options2.requestId,
           trigger,
-          ...fingerprint ? { fingerprint } : {}
+          dirtyGeneration: snapshot2.dirtyGeneration,
+          explicit: true,
+          admissionHeld: false,
+          workInFlight: false,
+          requestedAt: Date.now(),
+          releaseCheckpointAdmission: () => {
+          }
+        };
+        try {
+          ws.send(
+            JSON.stringify({
+              type: "workspace_checkpoint_request",
+              requestId: options2.requestId,
+              trigger,
+              dirtyGeneration: snapshot2.dirtyGeneration,
+              localHead: snapshot2.localHead,
+              desiredCanonicalHead: snapshot2.desiredCanonicalHead
+            })
+          );
+        } catch (error) {
+          pendingCheckpoint = void 0;
+          workspaceConvergence.defer();
+          process.stderr.write(
+            `[r5d-worker] failed to request blocked workspace checkpoint authority: ${error instanceof Error ? error.message : String(error)}
+`
+          );
+          armWorkspaceCheckpoint(trigger, { delayMs: 1e3, requestId: options2.requestId });
+        }
+        return;
+      }
+      if (pendingCheckpoint || workerHasActiveWriter()) {
+        armWorkspaceCheckpoint(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+        return;
+      }
+      const releaseCheckpointAdmission = workspaceFilesystemWriters.tryAcquireCheckpoint();
+      if (!releaseCheckpointAdmission) {
+        armWorkspaceCheckpoint(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+        return;
+      }
+      const snapshot = workspaceConvergence.snapshot();
+      const requestId = options2.requestId ?? crypto.randomUUID();
+      pendingCheckpoint = {
+        requestId,
+        trigger,
+        dirtyGeneration: snapshot.dirtyGeneration,
+        explicit: options2.requestId !== void 0,
+        admissionHeld: true,
+        workInFlight: false,
+        requestedAt: Date.now(),
+        releaseCheckpointAdmission
+      };
+      try {
+        ws.send(
+          JSON.stringify({
+            type: "workspace_checkpoint_request",
+            requestId,
+            trigger,
+            dirtyGeneration: snapshot.dirtyGeneration,
+            localHead: snapshot.localHead,
+            desiredCanonicalHead: snapshot.desiredCanonicalHead
+          })
+        );
+      } catch (error) {
+        releaseCheckpointAdmission();
+        pendingCheckpoint = void 0;
+        workspaceConvergence.defer();
+        process.stderr.write(
+          `[r5d-worker] failed to request workspace checkpoint: ${error instanceof Error ? error.message : String(error)}
+`
+        );
+        armWorkspaceCheckpoint(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+      }
+    }, Math.max(0, options2.delayMs));
+    workspaceCheckpointTimer.unref();
+  };
+  const markWorkspaceDirty = (trigger, force = false) => {
+    workspaceConvergence.markDirty();
+    armWorkspaceCheckpoint(trigger, { delayMs: force ? 0 : WORKSPACE_CHECKPOINT_QUIET_MS });
+  };
+  const convergeAvailableWorkspaceHead = async () => {
+    if (pendingWorkspaceHead === void 0 || !workspaceReady || !workspaceRemoteUrl || activeWorkspaceIncidentId || workspaceHeadConvergenceInFlight) {
+      return;
+    }
+    const advertisedHead = pendingWorkspaceHead;
+    pendingWorkspaceHead = void 0;
+    workspaceConvergence.observeCanonicalHead(advertisedHead);
+    workspaceHeadConvergenceInFlight = true;
+    let releaseVisibleHydration = null;
+    try {
+      const snapshot = workspaceConvergence.snapshot();
+      const mayHydrateVisible = !workerHasActiveWriter() && !pendingCheckpoint && snapshot.dirtyGeneration === snapshot.publishedGeneration;
+      releaseVisibleHydration = mayHydrateVisible ? workspaceFilesystemWriters.tryAcquireCheckpoint() : null;
+      const hydrateVisible = releaseVisibleHydration !== null;
+      const converged = await workspaceSyncSingleFlight.runExclusive(
+        () => convergeWorkspaceHead(workspaceSyncInput({ type: "inbound_head", detail: advertisedHead ?? "unborn" }), {
+          hydrateVisible
         })
       );
+      workspaceConvergence.observeCanonicalHead(converged.canonicalHead);
+      if (converged.hydrated) workspaceConvergence.setLocalHead(converged.localHead);
+      if (hydrateVisible && converged.localChanges) {
+        markWorkspaceDirty({ type: "periodic", detail: "inbound overlap retained for next checkpoint" });
+      }
+      sendWorkspaceReady();
     } catch (error) {
+      pendingWorkspaceHead = advertisedHead;
       process.stderr.write(
-        `[r5d-worker] failed to send workspace sync observation on its current connection: ${error instanceof Error ? error.message : String(error)}
+        `[r5d-worker] failed to fetch available workspace head: ${error instanceof Error ? error.message : String(error)}
 `
       );
+    } finally {
+      releaseVisibleHydration?.();
+      workspaceHeadConvergenceInFlight = false;
+      heartbeatBusyGrace = grantWorkerHeartbeatBusyGrace(lastServerHeartbeatAt, heartbeatBusyGrace);
+      if (pendingWorkspaceHead !== void 0) {
+        setTimeout(() => void convergeAvailableWorkspaceHead(), 1e3).unref();
+      }
     }
   };
   const manifestCheckoutKey = (projectId, branchName) => `${projectId}\0${branchName}`;
@@ -2469,13 +2646,58 @@ async function startWorker(options) {
     }
     return created;
   };
-  const runRequestedWorkspaceSync = async (authority, trigger, overrides = {}, authoritativeCanonicalHead, allowRecentNoChangeFastPath) => {
+  const schedulePendingManifestCheckoutHydration = (delayMs = 0) => {
+    if (workspaceManifestHydrationTimer || workspaceManifestHydrationInFlight || pendingManifestCheckouts.size === 0 || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    workspaceManifestHydrationTimer = setTimeout(() => {
+      workspaceManifestHydrationTimer = void 0;
+      if (!workspaceReady || !workspaceRemoteUrl || activeWorkspaceIncidentId || pendingCheckpoint || pendingManifestCheckouts.size === 0 || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+        if (pendingManifestCheckouts.size > 0 && currentWorkerSocket === ws && ws.readyState === WebSocket.OPEN) {
+          schedulePendingManifestCheckoutHydration(1e3);
+        }
+        return;
+      }
+      const releaseHydration = workspaceFilesystemWriters.tryAcquireCheckpoint();
+      if (!releaseHydration) {
+        schedulePendingManifestCheckoutHydration(1e3);
+        return;
+      }
+      workspaceManifestHydrationInFlight = true;
+      void workspaceSyncSingleFlight.runExclusive(async () => {
+        if (!workspaceReady || activeWorkspaceIncidentId || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+          return;
+        }
+        const targets = [...pendingManifestCheckouts.values()];
+        ensureVisibleWorkspaceCheckouts(targets, { strictCanonicalRevalidation: true });
+        for (const target of targets) {
+          const manifest = manifestByProjectId.get(target.projectId);
+          if (!manifest || !manifest.branches.includes(target.branchName)) continue;
+          const branchPath = path.join(projectRootFor(projectsRoot, target.projectId, manifestByProjectId), target.branchName);
+          if (hasNormalVisibleGitDir(branchPath)) {
+            pendingManifestCheckouts.delete(manifestCheckoutKey(target.projectId, target.branchName));
+          }
+        }
+      }).then(() => sendWorkspaceReady()).catch((error) => {
+        process.stderr.write(
+          `[r5d-worker] pending manifest checkout hydration failed: ${error instanceof Error ? error.message : String(error)}
+`
+        );
+      }).finally(() => {
+        releaseHydration();
+        workspaceManifestHydrationInFlight = false;
+        heartbeatBusyGrace = grantWorkerHeartbeatBusyGrace(lastServerHeartbeatAt, heartbeatBusyGrace);
+        if (pendingManifestCheckouts.size > 0) schedulePendingManifestCheckoutHydration(1e3);
+      });
+    }, Math.max(0, delayMs));
+    workspaceManifestHydrationTimer.unref();
+  };
+  const runRequestedWorkspaceSync = async (authority, trigger, overrides = {}) => {
     const requestedAt = Date.now();
     let queueEnteredAt = requestedAt;
     let prepareStartedAt = requestedAt;
     let synchronizeStartedAt = requestedAt;
     let synchronizeFinishedAt = requestedAt;
-    let fastPathDecision = { hit: false, reason: "no_recent_proof" };
     workspaceSyncRequestsInFlight += 1;
     try {
       let pendingTargets = [];
@@ -2484,48 +2706,12 @@ async function startWorker(options) {
         const shouldEnsureCheckouts = !overrides.skipVisibleMirror && !overrides.resetToCanonical;
         const syncProjects = workspaceProjectsForSync([...manifestByProjectId.values()], trigger);
         if (!workspaceRemoteUrl) throw new Error("Worker workspace manifest has not been received");
-        const scopeKey = workspaceSyncScopeKey(workspaceRemoteUrl, syncProjects);
         const allowedCheckoutKeys = new Set(
           syncProjects.flatMap((project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName)))
         );
         const scopedPendingTargets = [...pendingManifestCheckouts.values()].filter(
           (target) => allowedCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
         );
-        const workerBusy = activeProcesses.size > 0 || activePtys.size > 0 || cliUpdateInProgress;
-        fastPathDecision = recentWorkspaceSyncProof.evaluate({
-          trigger,
-          allowRecentNoChangeFastPath,
-          canonicalHead: authoritativeCanonicalHead,
-          scopeKey,
-          nowMs: Date.now(),
-          skipVisibleMirror: overrides.skipVisibleMirror,
-          resetToCanonical: overrides.resetToCanonical,
-          incidentActive: activeWorkspaceIncidentId !== null,
-          workerBusy,
-          pendingCheckouts: scopedPendingTargets.length > 0 || Boolean(overrides.newVisibleCheckouts?.length)
-        });
-        if (fastPathDecision.hit) {
-          prepareStartedAt = queueEnteredAt;
-          synchronizeStartedAt = queueEnteredAt;
-          synchronizeFinishedAt = queueEnteredAt;
-          return {
-            type: "workspace_sync",
-            attemptId: overrides.attemptId ?? crypto.randomUUID(),
-            workerLabel: label,
-            trigger,
-            outcome: "no_change",
-            startingHead: fastPathDecision.canonicalHead,
-            expectedHead: fastPathDecision.canonicalHead,
-            publishedHead: fastPathDecision.canonicalHead,
-            rebaseCount: 0,
-            diffSizeBytes: 0,
-            gitStatus: "",
-            affectedProjects: [],
-            affectedPaths: [],
-            discardedPaths: [],
-            localChangesDiscarded: false
-          };
-        }
         prepareStartedAt = Date.now();
         let checkoutTargets = [];
         if (shouldEnsureCheckouts) {
@@ -2551,24 +2737,12 @@ async function startWorker(options) {
           ...newVisibleCheckouts.length > 0 ? { newVisibleCheckouts } : {}
         });
         synchronizeStartedAt = Date.now();
-        recentWorkspaceSyncProof.invalidate();
-        const observationGeneration = recentWorkspaceSyncProof.beginObservation();
-        const workerWasBusyDuringObservation = workerBusy;
         let synchronized;
         try {
           synchronized = await synchronizeWorkspace(input);
         } finally {
           synchronizeFinishedAt = Date.now();
         }
-        if ((synchronized.outcome === "no_change" || synchronized.outcome === "updated") && pendingTargets.length === 0) {
-          recentWorkspaceSyncProof.recordStable({
-            observationGeneration,
-            canonicalHead: synchronized.publishedHead ?? null,
-            scopeKey,
-            observedAtMs: synchronizeFinishedAt,
-            workerBusy: workerWasBusyDuringObservation || activeProcesses.size > 0 || activePtys.size > 0 || cliUpdateInProgress || activeWorkspaceIncidentId !== null
-          });
-        }
         return synchronized;
       });
       const completedAt = Date.now();
@@ -2578,8 +2752,7 @@ async function startWorker(options) {
           totalMs: completedAt - requestedAt,
           queueMs: queueEnteredAt - requestedAt,
           prepareMs: synchronizeStartedAt - prepareStartedAt,
-          synchronizeMs: synchronizeFinishedAt - synchronizeStartedAt,
-          fastPath: workspaceSyncFastPathTelemetry(fastPathDecision)
+          synchronizeMs: synchronizeFinishedAt - synchronizeStartedAt
         }
       };
       if (resultWithTelemetry.outcome === "no_change" || resultWithTelemetry.outcome === "published" || resultWithTelemetry.outcome === "updated" || resultWithTelemetry.outcome === "conflict_reset") {
@@ -2588,7 +2761,6 @@ async function startWorker(options) {
           if (pendingManifestCheckouts.get(key) === target) pendingManifestCheckouts.delete(key);
         }
       }
-      previousPeriodicFingerprint = null;
       sendWorkspaceSyncResult(authority, resultWithTelemetry);
       return resultWithTelemetry;
     } catch (error) {
@@ -2611,12 +2783,10 @@ async function startWorker(options) {
           totalMs: completedAt - requestedAt,
           queueMs: queueEnteredAt - requestedAt,
           prepareMs: Math.max(0, synchronizeStartedAt - prepareStartedAt),
-          synchronizeMs: Math.max(0, synchronizeFinishedAt - synchronizeStartedAt),
-          fastPath: workspaceSyncFastPathTelemetry(fastPathDecision)
+          synchronizeMs: Math.max(0, synchronizeFinishedAt - synchronizeStartedAt)
         },
         error: error instanceof Error ? error.message : String(error)
       };
-      previousPeriodicFingerprint = null;
       sendWorkspaceSyncResult(authority, result);
       return result;
     } finally {
@@ -2632,6 +2802,24 @@ async function startWorker(options) {
   let heartbeatBusyGrace = null;
   let heartbeatTimedOut = false;
   let heartbeatWatchdog;
+  const handleGracefulShutdown = () => {
+    if (shutdownAfterClose) return;
+    shutdownAfterClose = true;
+    void waitForWorkspaceCheckpointOnShutdown({
+      snapshot: () => workspaceConvergence.snapshot(),
+      forceCheckpoint: () => armWorkspaceCheckpoint({ type: "manual", detail: "graceful worker shutdown" }, { delayMs: 0 })
+    }).then((outcome) => {
+      process.stdout.write(`[r5d-worker] graceful workspace checkpoint ${outcome}
+`);
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        ws.close(1e3, "Worker shutting down");
+      } else {
+        process.exit(0);
+      }
+    });
+  };
+  process.on("SIGTERM", handleGracefulShutdown);
+  process.on("SIGINT", handleGracefulShutdown);
   const stopHeartbeatWatchdog = () => {
     if (heartbeatWatchdog) {
       clearInterval(heartbeatWatchdog);
@@ -2662,7 +2850,8 @@ async function startWorker(options) {
           updateClis: true,
           canonicalResolverCheckout: true,
           browserPortForwarding: true,
-          globalWorkspaceSyncLeaseV1: true
+          globalWorkspaceSyncLeaseV1: true,
+          eventualWorkspaceSyncV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -2689,100 +2878,123 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "workspace_manifest") {
-        recentWorkspaceSyncProof.invalidate();
-        await workspaceSyncSingleFlight.runMutation(() => {
-          configureGitHubAuth(message.githubCredential);
-          visibleGitIdentity = message.gitIdentity;
-          workspaceRemoteUrl = message.workspaceRemoteUrl;
-          const previousCheckoutKeys = new Set(
-            allManifestCheckouts().map(({ projectId, branchName }) => manifestCheckoutKey(projectId, branchName))
-          );
-          const migratedProjectIds = migrateLegacyProjectRoots(projectsRoot, message.projects);
-          manifestByProjectId.clear();
-          for (const project of message.projects) manifestByProjectId.set(project.projectId, project);
-          const currentCheckouts = allManifestCheckouts();
-          const currentCheckoutKeys = new Set(
-            currentCheckouts.map(({ projectId, branchName }) => manifestCheckoutKey(projectId, branchName))
-          );
-          for (const key of pendingManifestCheckouts.keys()) {
-            if (!currentCheckoutKeys.has(key)) pendingManifestCheckouts.delete(key);
-          }
-          for (const checkout of currentCheckouts) {
-            const key = manifestCheckoutKey(checkout.projectId, checkout.branchName);
-            if (previousCheckoutKeys.has(key)) continue;
-            const branchPath = path.join(projectRootFor(projectsRoot, checkout.projectId, manifestByProjectId), checkout.branchName);
-            if (!hasNormalVisibleGitDir(branchPath)) pendingManifestCheckouts.set(key, checkout);
-          }
-          previousPeriodicFingerprint = null;
-          process.stdout.write(
-            `[r5d-worker] workspace manifest: ${message.projects.length} projects${migratedProjectIds.length > 0 ? `; migrated ${migratedProjectIds.length} project checkout root(s)` : ""}
-`
-          );
+        const revisionToken = workspaceManifestRevision.begin(message.revision);
+        workspaceReady = false;
+        const manifestAdmission = inspectWorkspaceManifestAdmission({
+          projectsRoot,
+          workspaceShadowRoot,
+          projects: message.projects
         });
-        if (!periodicWorkspaceScan) {
-          const emptyFingerprint = createHash("sha256").update("").digest("hex");
-          periodicWorkspaceScan = setInterval(() => {
-            if (!workspaceRemoteUrl || activeWorkspaceIncidentId || cliUpdateInProgress || periodicWorkspaceScanInFlight) return;
-            periodicWorkspaceScanInFlight = true;
-            void (async () => {
-              const genericCheckoutKeys = new Set(
-                workspaceProjectsForSync([...manifestByProjectId.values()], { type: "periodic" }).flatMap(
-                  (project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName))
-                )
-              );
-              const hasPendingGenericCheckout = [...pendingManifestCheckouts.values()].some(
-                (target) => genericCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
+        const releaseManifestHydration = await acquireWorkspaceManifestVisibleLease(
+          workspaceFilesystemWriters,
+          manifestAdmission
+        );
+        let completed = false;
+        try {
+          completed = await workspaceSyncSingleFlight.runExclusive(async () => {
+            if (!workspaceManifestRevision.isCurrent(revisionToken)) return false;
+            const firstBootstrap = manifestAdmission.firstBootstrap;
+            configureGitHubAuth(message.githubCredential);
+            visibleGitIdentity = message.gitIdentity;
+            workspaceRemoteUrl = message.workspaceRemoteUrl;
+            const migratedProjectIds = releaseManifestHydration ? migrateLegacyProjectRoots(projectsRoot, message.projects) : [];
+            manifestByProjectId.clear();
+            for (const project of message.projects) manifestByProjectId.set(project.projectId, project);
+            const currentCheckouts = allManifestCheckouts();
+            const currentCheckoutKeys = new Set(
+              currentCheckouts.map(({ projectId, branchName }) => manifestCheckoutKey(projectId, branchName))
+            );
+            for (const key of pendingManifestCheckouts.keys()) {
+              if (!currentCheckoutKeys.has(key)) pendingManifestCheckouts.delete(key);
+            }
+            for (const checkout of currentCheckouts) {
+              const key = manifestCheckoutKey(checkout.projectId, checkout.branchName);
+              const branchPath = path.join(
+                projectRootFor(projectsRoot, checkout.projectId, manifestByProjectId),
+                checkout.branchName
               );
-              if (hasPendingGenericCheckout) {
-                recentWorkspaceSyncProof.invalidate();
-                previousPeriodicFingerprint = null;
-                requestWorkspaceSync({
-                  type: "periodic",
-                  detail: "workspace manifest additions"
-                });
-                return;
+              if (!hasNormalVisibleGitDir(branchPath)) pendingManifestCheckouts.set(key, checkout);
+            }
+            if (!workspaceManifestRevision.isCurrent(revisionToken)) return false;
+            const created = releaseManifestHydration ? ensureVisibleWorkspaceCheckouts(currentCheckouts, { strictCanonicalRevalidation: true }) : [];
+            if (!workspaceManifestRevision.isCurrent(revisionToken)) return false;
+            const bootstrapped = await convergeWorkspaceHead(
+              workspaceSyncInput({ type: "connect" }, { newVisibleCheckouts: created }),
+              {
+                // An existing checkout becomes routable after a fetch. Its
+                // visible tree converges asynchronously; first bootstrap alone
+                // must materialize the canonical snapshot before readiness.
+                // Re-check the incident immediately before convergence so a
+                // concurrently delivered fence forces fetch-only behavior.
+                hydrateVisible: firstBootstrap && !activeWorkspaceIncidentId
               }
-              const observation = await workspaceSyncSingleFlight.runExclusive(() => {
-                const observationGeneration = recentWorkspaceSyncProof.beginObservation();
-                const input = workspaceSyncInput({ type: "periodic" });
-                const workerBusy = activeProcesses.size > 0 || activePtys.size > 0 || cliUpdateInProgress;
-                return {
-                  observationGeneration,
-                  scopeKey: workspaceSyncScopeKey(input.remoteUrl, input.projects),
-                  fingerprint: calculateWorkspaceDiffFingerprint(input),
-                  canonicalHead: readShadowWorkspaceCanonicalHead(workspaceShadowRoot),
-                  workerBusy
-                };
-              });
-              if (observation.fingerprint === emptyFingerprint) {
-                recentWorkspaceSyncProof.recordStable({
-                  observationGeneration: observation.observationGeneration,
-                  canonicalHead: observation.canonicalHead,
-                  scopeKey: observation.scopeKey,
-                  observedAtMs: Date.now(),
-                  workerBusy: observation.workerBusy || activeProcesses.size > 0 || activePtys.size > 0 || cliUpdateInProgress
-                });
-                previousPeriodicFingerprint = null;
-                return;
+            );
+            if (!workspaceManifestRevision.isCurrent(revisionToken)) return false;
+            workspaceConvergence.setLocalHead(bootstrapped.localHead);
+            workspaceConvergence.observeCanonicalHead(bootstrapped.canonicalHead);
+            for (const checkout of currentCheckouts) {
+              const manifest = manifestByProjectId.get(checkout.projectId);
+              if (!manifest) continue;
+              const branchPath = path.join(projectRootFor(projectsRoot, checkout.projectId, manifestByProjectId), checkout.branchName);
+              if (hasNormalVisibleGitDir(branchPath)) {
+                pendingManifestCheckouts.delete(manifestCheckoutKey(checkout.projectId, checkout.branchName));
               }
-              recentWorkspaceSyncProof.invalidate();
-              if (previousPeriodicFingerprint !== observation.fingerprint) {
-                previousPeriodicFingerprint = observation.fingerprint;
-                return;
+            }
+            process.stdout.write(
+              `[r5d-worker] workspace manifest: ${message.projects.length} projects${migratedProjectIds.length > 0 ? `; migrated ${migratedProjectIds.length} project checkout root(s)` : ""}
+`
+            );
+            return true;
+          });
+        } finally {
+          releaseManifestHydration?.();
+        }
+        if (!completed || !workspaceManifestRevision.complete(revisionToken)) return;
+        workspaceReady = true;
+        sendWorkspaceReady();
+        schedulePendingManifestCheckoutHydration();
+        if (!workspaceSafetyScan) {
+          workspaceSafetyScan = setInterval(() => {
+            if (!workspaceReady || !workspaceRemoteUrl || activeWorkspaceIncidentId || pendingCheckpoint || workspaceSafetyScanInFlight) {
+              return;
+            }
+            workspaceSafetyScanInFlight = true;
+            void (async () => {
+              const before = workspaceConvergence.snapshot();
+              const mayHydrateVisible = !workerHasActiveWriter() && before.dirtyGeneration === before.publishedGeneration;
+              const releaseVisibleHydration = mayHydrateVisible ? workspaceFilesystemWriters.tryAcquireCheckpoint() : null;
+              const hydrateVisible = releaseVisibleHydration !== null;
+              try {
+                const converged = await workspaceSyncSingleFlight.runExclusive(
+                  () => convergeWorkspaceHead(workspaceSyncInput({ type: "periodic", detail: "idle convergence scan" }), {
+                    hydrateVisible
+                  })
+                );
+                workspaceConvergence.observeCanonicalHead(converged.canonicalHead);
+                if (converged.hydrated) workspaceConvergence.setLocalHead(converged.localHead);
+                if (converged.localChanges && hydrateVisible) {
+                  markWorkspaceDirty({ type: "periodic", detail: "idle safety scan" });
+                }
+                sendWorkspaceReady();
+              } finally {
+                releaseVisibleHydration?.();
               }
-              previousPeriodicFingerprint = null;
-              requestWorkspaceSync({ type: "periodic" }, observation.fingerprint);
             })().catch((error) => {
               process.stderr.write(
-                `[r5d-worker] periodic workspace synchronization failed: ${error instanceof Error ? error.message : String(error)}
+                `[r5d-worker] idle workspace safety scan failed: ${error instanceof Error ? error.message : String(error)}
 `
               );
             }).finally(() => {
-              periodicWorkspaceScanInFlight = false;
+              workspaceSafetyScanInFlight = false;
               heartbeatBusyGrace = grantWorkerHeartbeatBusyGrace(lastServerHeartbeatAt, heartbeatBusyGrace);
             });
-          }, WORKSPACE_PERIODIC_SCAN_INTERVAL_MS);
-          periodicWorkspaceScan.unref();
+          }, WORKSPACE_IDLE_SAFETY_SCAN_MS);
+          workspaceSafetyScan.unref();
+        }
+        pendingWorkspaceHead = workspaceConvergence.snapshot().desiredCanonicalHead;
+        void convergeAvailableWorkspaceHead();
+        if (workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+          armWorkspaceCheckpoint({ type: "periodic", detail: "resume dirty generation after reconnect" }, { delayMs: 0 });
         }
         return;
       }
@@ -2802,12 +3014,189 @@ async function startWorker(options) {
             confirmationReason: message.confirmationReason,
             resetToCanonical: message.resetToCanonical,
             skipVisibleMirror: message.skipVisibleMirror
-          },
-          message.canonicalHead,
-          message.allowRecentNoChangeFastPath
+          }
         );
         return;
       }
+      if (message.type === "workspace_head_available") {
+        workspaceConvergence.observeCanonicalHead(message.canonicalHead);
+        pendingWorkspaceHead = message.canonicalHead;
+        sendWorkspaceReady();
+        void convergeAvailableWorkspaceHead();
+        return;
+      }
+      if (message.type === "workspace_checkpoint_now") {
+        armWorkspaceCheckpoint(message.trigger, { delayMs: 0, requestId: message.requestId });
+        return;
+      }
+      if (message.type === "workspace_checkpoint_authority") {
+        const checkpoint = pendingCheckpoint;
+        if (!checkpoint || checkpoint.requestId !== message.requestId) {
+          process.stderr.write(`[r5d-worker] ignoring checkpoint authority for unknown request ${message.requestId}
+`);
+          return;
+        }
+        if (message.status !== "granted") {
+          checkpoint.releaseCheckpointAdmission();
+          pendingCheckpoint = void 0;
+          workspaceConvergence.observeCanonicalHead(message.canonicalHead);
+          const applyBlockedResponse = message.status === "blocked" && workspaceIncidentOrdering.permitsBlockedResponse(message.incidentId);
+          if (applyBlockedResponse) {
+            workspaceConvergence.block();
+            if (message.incidentId) activeWorkspaceIncidentId = message.incidentId;
+          } else {
+            workspaceConvergence.resetTransientCheckpointState();
+            workspaceConvergence.observeIncidentState(Boolean(activeWorkspaceIncidentId));
+            if (message.status === "busy") {
+              armWorkspaceCheckpoint(checkpoint.trigger, {
+                delayMs: message.retryAfterMs ?? 1e3,
+                requestId: checkpoint.requestId
+              });
+            } else if (!activeWorkspaceIncidentId) {
+              const explicit = explicitWorkspaceCheckpoints.next();
+              if (explicit) {
+                armWorkspaceCheckpoint(explicit.trigger, { delayMs: 0, requestId: explicit.requestId });
+              } else if (workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+                armWorkspaceCheckpoint(checkpoint.trigger, { delayMs: 0 });
+              }
+            }
+          }
+          sendWorkspaceReady();
+          return;
+        }
+        checkpoint.attemptId = message.attemptId;
+        checkpoint.authorityToken = message.authorityToken;
+        checkpoint.workInFlight = true;
+        pendingCheckpoint = checkpoint;
+        if (!checkpoint.admissionHeld) {
+          const releaseCheckpointAdmission = await workspaceFilesystemWriters.acquireCheckpoint();
+          if (currentWorkerSocket !== ws || pendingCheckpoint?.requestId !== checkpoint.requestId || pendingCheckpoint.attemptId !== message.attemptId) {
+            releaseCheckpointAdmission();
+            checkpoint.workInFlight = false;
+            workspaceConvergence.resetTransientCheckpointState();
+            return;
+          }
+          checkpoint.admissionHeld = true;
+          checkpoint.releaseCheckpointAdmission = releaseCheckpointAdmission;
+        }
+        workspaceConvergence.beginPreparing();
+        sendWorkspaceReady();
+        let prepareStartedAt = Date.now();
+        let synchronizeStartedAt = prepareStartedAt;
+        let synchronizeStarted = false;
+        let result;
+        try {
+          result = await workspaceSyncSingleFlight.runExclusive(async () => {
+            prepareStartedAt = Date.now();
+            const pendingTargets = [...pendingManifestCheckouts.values()];
+            const createdCheckouts = ensureVisibleWorkspaceCheckouts(pendingTargets, { strictCanonicalRevalidation: true });
+            synchronizeStartedAt = Date.now();
+            synchronizeStarted = true;
+            const prepared = await synchronizeWorkspace(
+              workspaceSyncInput(checkpoint.trigger, {
+                attemptId: message.attemptId,
+                quarantineRef: message.quarantineRef,
+                expectedCanonicalHead: message.expectedHead,
+                newVisibleCheckouts: [...createdCheckouts, ...pendingTargets]
+              })
+            );
+            for (const target of pendingTargets) {
+              pendingManifestCheckouts.delete(manifestCheckoutKey(target.projectId, target.branchName));
+            }
+            return prepared.outcome === "updated" ? { ...prepared, outcome: "no_change" } : prepared;
+          });
+        } catch (error) {
+          if (!synchronizeStarted) synchronizeStartedAt = Date.now();
+          result = {
+            type: "workspace_sync",
+            attemptId: message.attemptId,
+            workerLabel: label,
+            trigger: checkpoint.trigger,
+            outcome: "failed",
+            startingHead: message.expectedHead,
+            expectedHead: message.expectedHead,
+            rebaseCount: 0,
+            diffSizeBytes: 0,
+            gitStatus: "",
+            affectedProjects: [],
+            affectedPaths: [],
+            discardedPaths: [],
+            localChangesDiscarded: false,
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+        const finishedAt = Date.now();
+        result = {
+          ...result,
+          dirtyGeneration: checkpoint.dirtyGeneration,
+          telemetry: workspaceCheckpointTelemetry({
+            requestedAt: checkpoint.requestedAt,
+            prepareStartedAt,
+            synchronizeStartedAt,
+            finishedAt
+          })
+        };
+        workspaceConvergence.beginSubmitting();
+        sendWorkspaceReady();
+        try {
+          ws.send(
+            JSON.stringify({
+              type: "workspace_checkpoint_result",
+              requestId: checkpoint.requestId,
+              attemptId: message.attemptId,
+              authorityToken: message.authorityToken,
+              dirtyGeneration: checkpoint.dirtyGeneration,
+              result
+            })
+          );
+        } catch (error) {
+          workspaceConvergence.resetTransientCheckpointState();
+          throw error;
+        } finally {
+          checkpoint.workInFlight = false;
+          checkpoint.releaseCheckpointAdmission();
+          if (currentWorkerSocket !== ws) workspaceConvergence.resetTransientCheckpointState();
+        }
+        return;
+      }
+      if (message.type === "workspace_checkpoint_completed") {
+        const checkpoint = pendingCheckpoint;
+        if (!checkpoint || checkpoint.requestId !== message.requestId || checkpoint.attemptId !== message.attemptId) {
+          process.stderr.write(`[r5d-worker] ignoring completion for unknown checkpoint ${message.requestId}
+`);
+          return;
+        }
+        pendingCheckpoint = void 0;
+        workspaceConvergence.observeCanonicalHead(message.canonicalHead);
+        if (message.status === "published" || message.status === "no_change") {
+          workspaceConvergence.complete({
+            generation: Math.min(message.publishedGeneration ?? checkpoint.dirtyGeneration, checkpoint.dirtyGeneration),
+            canonicalHead: message.canonicalHead,
+            published: true
+          });
+        } else if (message.status === "blocked" && workspaceIncidentOrdering.permitsBlockedResponse(message.incidentId)) {
+          workspaceConvergence.block();
+          if (message.incidentId) activeWorkspaceIncidentId = message.incidentId;
+        } else {
+          workspaceConvergence.resetTransientCheckpointState();
+          workspaceConvergence.observeIncidentState(Boolean(activeWorkspaceIncidentId));
+        }
+        sendWorkspaceReady();
+        const explicit = message.status === "retry" && checkpoint.explicit ? { requestId: checkpoint.requestId, trigger: checkpoint.trigger } : explicitWorkspaceCheckpoints.next();
+        if (explicit) {
+          armWorkspaceCheckpoint(explicit.trigger, {
+            delayMs: message.retryAfterMs ?? 0,
+            requestId: explicit.requestId
+          });
+        } else if (message.status === "retry" || message.status === "failed" || workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+          armWorkspaceCheckpoint(checkpoint.trigger, { delayMs: message.retryAfterMs ?? 1e3 });
+        }
+        if (message.canonicalHead !== workspaceConvergence.snapshot().localHead) {
+          pendingWorkspaceHead = message.canonicalHead;
+          void convergeAvailableWorkspaceHead();
+        }
+        return;
+      }
       if (message.type === "sync_session_artifacts") {
         sessionArtifactSyncRequestsInFlight += 1;
         try {
@@ -2835,18 +3224,27 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "workspace_incident_updated") {
-        recentWorkspaceSyncProof.invalidate();
+        workspaceIncidentOrdering.observe(message);
         const previousIncidentId = activeWorkspaceIncidentId;
         activeWorkspaceIncidentId = applyWorkspaceIncidentUpdate(activeWorkspaceIncidentId, message);
-        previousPeriodicFingerprint = null;
         const releasedHead = releasePendingWorkspaceHead(
           previousIncidentId,
           activeWorkspaceIncidentId,
           message.status === "resolved" || message.status === "confirmed" || message.status === "reset" ? message.incidentId : null
         );
-        if (releasedHead.syncHead) {
-          requestWorkspaceSync({ type: "inbound_head", detail: releasedHead.syncHead });
+        workspaceConvergence.observeIncidentState(Boolean(activeWorkspaceIncidentId));
+        if (releasedHead.fetchAuthoritativeHead) {
+          pendingWorkspaceHead = workspaceConvergence.snapshot().desiredCanonicalHead;
+          void convergeAvailableWorkspaceHead();
+        }
+        const explicit = !activeWorkspaceIncidentId ? explicitWorkspaceCheckpoints.next() : void 0;
+        if (explicit) {
+          armWorkspaceCheckpoint(explicit.trigger, { delayMs: 0, requestId: explicit.requestId });
+        } else if (!activeWorkspaceIncidentId && workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+          armWorkspaceCheckpoint({ type: "periodic", detail: "resume after workspace incident" }, { delayMs: 0 });
         }
+        if (!activeWorkspaceIncidentId) schedulePendingManifestCheckoutHydration();
+        sendWorkspaceReady();
         return;
       }
       if (message.type === "exec_terminal_ack") {
@@ -2882,7 +3280,6 @@ async function startWorker(options) {
           return;
         }
         cliUpdateInProgress = true;
-        recentWorkspaceSyncProof.invalidate();
         try {
           const result = await installCliUpdate(message);
           sendWorkerMessage(ws, {
@@ -2945,9 +3342,10 @@ async function startWorker(options) {
           });
           return;
         }
-        recentWorkspaceSyncProof.invalidate();
+        const releaseWorkspaceWriter = targetMayMutateVisibleWorkspace(message.target) ? await workspaceFilesystemWriters.acquireWriter() : void 0;
         const releaseWorkspaceMutation = await acquireWorkspaceCommandMutation(message.target, workspaceSyncSingleFlight);
-        let leaseTransferred = false;
+        let mutationLeaseTransferred = false;
+        let writerLeaseTransferred = false;
         try {
           const resolvedTarget = resolveMessageTarget(message.target);
           process.stdout.write(`[r5d-worker] pty ${message.ptyId}: ${describeWorkerSessionTarget(message.target)}
@@ -2957,9 +3355,19 @@ async function startWorker(options) {
             message,
             resolvedTarget,
             planRoot,
-            ...releaseWorkspaceMutation ? { releaseWorkspaceMutation } : {}
+            ...releaseWorkspaceMutation ? { releaseWorkspaceMutation } : {},
+            ...targetMayMutateVisibleWorkspace(message.target) ? {
+              onTerminal: () => {
+                markWorkspaceDirty(
+                  { type: "process_terminal", detail: `pty ${message.ptyId} completed` },
+                  true
+                );
+                releaseWorkspaceWriter?.();
+              }
+            } : {}
           });
-          leaseTransferred = releaseWorkspaceMutation !== void 0;
+          mutationLeaseTransferred = releaseWorkspaceMutation !== void 0;
+          writerLeaseTransferred = releaseWorkspaceWriter !== void 0;
         } catch (error) {
           sendWorkerMessage(ws, {
             type: "pty_error",
@@ -2968,12 +3376,16 @@ async function startWorker(options) {
             error: error instanceof Error ? error.message : String(error)
           });
         } finally {
-          if (!leaseTransferred) releaseWorkspaceMutation?.();
+          if (!mutationLeaseTransferred) releaseWorkspaceMutation?.();
+          if (!writerLeaseTransferred) releaseWorkspaceWriter?.();
         }
         return;
       }
       if (message.type === "pty_input") {
-        recentWorkspaceSyncProof.invalidate();
+        const activePty = activePtys.get(message.ptyId);
+        if (activePty && targetMayMutateVisibleWorkspace(activePty.target)) {
+          markWorkspaceDirty({ type: "shell_inline", detail: `pty ${message.ptyId}` });
+        }
         writePty(ws, message);
         return;
       }
@@ -2982,8 +3394,11 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "pty_close") {
-        recentWorkspaceSyncProof.invalidate();
+        const activePty = activePtys.get(message.ptyId);
         closePty(message);
+        if (activePty && targetMayMutateVisibleWorkspace(activePty.target)) {
+          armWorkspaceCheckpoint({ type: "process_terminal", detail: `pty ${message.ptyId} closed` }, { delayMs: 0 });
+        }
         return;
       }
       if (message.type === "exec") {
@@ -2997,27 +3412,37 @@ async function startWorker(options) {
           });
           return;
         }
-        recentWorkspaceSyncProof.invalidate();
-        let result;
+        const releaseWorkspaceWriter = targetMayMutateVisibleWorkspace(message.target) ? await workspaceFilesystemWriters.acquireWriter() : void 0;
         try {
-          const runCommand = async () => {
-            const resolvedTarget = resolveMessageTarget(message.target);
-            process.stdout.write(`[r5d-worker] exec ${message.runId}: ${message.argv.join(" ")}
+          let result;
+          try {
+            const runCommand = async () => {
+              const resolvedTarget = resolveMessageTarget(message.target);
+              process.stdout.write(`[r5d-worker] exec ${message.runId}: ${message.argv.join(" ")}
 `);
-            return await executeCommand({ message, resolvedTarget, baseUrl, token, artifactRoot, planRoot });
-          };
-          result = await runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
-        } catch (error) {
-          result = {
-            type: "exec_result",
-            requestId: message.requestId,
-            stdout: "",
-            stderr: "",
-            exitCode: 1,
-            error: error instanceof Error ? error.message : String(error)
-          };
+              return await executeCommand({ message, resolvedTarget, baseUrl, token, artifactRoot, planRoot });
+            };
+            result = await runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
+          } catch (error) {
+            result = {
+              type: "exec_result",
+              requestId: message.requestId,
+              stdout: "",
+              stderr: "",
+              exitCode: 1,
+              error: error instanceof Error ? error.message : String(error)
+            };
+          }
+          ws.send(JSON.stringify(result));
+          if (targetMayMutateVisibleWorkspace(message.target)) {
+            markWorkspaceDirty(
+              { type: "shell_inline", sessionId: message.sessionId, processRunId: message.runId, detail: "foreground command completed" },
+              true
+            );
+          }
+        } finally {
+          releaseWorkspaceWriter?.();
         }
-        ws.send(JSON.stringify(result));
         return;
       }
       if (message.type === "exec_start") {
@@ -3030,25 +3455,40 @@ async function startWorker(options) {
           });
           return;
         }
-        recentWorkspaceSyncProof.invalidate();
         sendWorkerMessage(ws, {
           type: "exec_accepted",
           requestId: message.requestId,
           runId: message.runId
         });
         const runCommand = async () => {
-          const resolvedTarget = resolveMessageTarget(message.target);
-          process.stdout.write(`[r5d-worker] exec_start ${message.runId}: ${message.argv.join(" ")}
+          const releaseWorkspaceWriter = targetMayMutateVisibleWorkspace(message.target) ? await workspaceFilesystemWriters.acquireWriter() : void 0;
+          try {
+            const resolvedTarget = resolveMessageTarget(message.target);
+            process.stdout.write(`[r5d-worker] exec_start ${message.runId}: ${message.argv.join(" ")}
 `);
-          await executeStreamingCommand({
-            ws,
-            message,
-            resolvedTarget,
-            baseUrl,
-            token,
-            artifactRoot,
-            planRoot
-          });
+            await executeStreamingCommand({
+              ws,
+              message,
+              resolvedTarget,
+              baseUrl,
+              token,
+              artifactRoot,
+              planRoot
+            });
+          } finally {
+            if (targetMayMutateVisibleWorkspace(message.target)) {
+              markWorkspaceDirty(
+                {
+                  type: "process_terminal",
+                  sessionId: message.sessionId,
+                  processRunId: message.runId,
+                  detail: "process completed"
+                },
+                true
+              );
+            }
+            releaseWorkspaceWriter?.();
+          }
         };
         const execution = runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
         void execution.catch((error) => {
@@ -3062,34 +3502,46 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "read" || message.type === "write" || message.type === "edit" || message.type === "grep" || message.type === "find" || message.type === "ls" || message.type === "view_file_bytes") {
-        if (message.type === "write" || message.type === "edit") recentWorkspaceSyncProof.invalidate();
+        const releaseWorkspaceWriter = (message.type === "write" || message.type === "edit") && targetMayMutateVisibleWorkspace(message.target) ? await workspaceFilesystemWriters.acquireWriter() : void 0;
         try {
-          const result = await workspaceSyncSingleFlight.runMutation(async () => {
-            const resolvedTarget = resolveMessageTarget(message.target);
-            return await executeOperation({
-              message,
-              resolvedTarget,
-              baseUrl,
-              token,
-              artifactRoot,
-              planRoot
+          try {
+            const result = await workspaceSyncSingleFlight.runMutation(async () => {
+              const resolvedTarget = resolveMessageTarget(message.target);
+              return await executeOperation({
+                message,
+                resolvedTarget,
+                baseUrl,
+                token,
+                artifactRoot,
+                planRoot
+              });
             });
-          });
-          ws.send(
-            JSON.stringify({
-              type: "operation_result",
-              requestId: message.requestId,
-              result
-            })
-          );
-        } catch (error) {
-          ws.send(
-            JSON.stringify({
-              type: "operation_result",
-              requestId: message.requestId,
-              error: error instanceof Error ? error.message : String(error)
-            })
-          );
+            ws.send(
+              JSON.stringify({
+                type: "operation_result",
+                requestId: message.requestId,
+                result
+              })
+            );
+            if ((message.type === "write" || message.type === "edit") && targetMayMutateVisibleWorkspace(message.target)) {
+              markWorkspaceDirty({
+                type: message.type,
+                sessionId: message.sessionId,
+                toolCallId: message.requestId,
+                ...message.target.type === "project" ? { projectId: message.target.projectId, branchName: message.target.branchName } : {}
+              });
+            }
+          } catch (error) {
+            ws.send(
+              JSON.stringify({
+                type: "operation_result",
+                requestId: message.requestId,
+                error: error instanceof Error ? error.message : String(error)
+              })
+            );
+          }
+        } finally {
+          releaseWorkspaceWriter?.();
         }
         return;
       }
@@ -3111,11 +3563,24 @@ async function startWorker(options) {
     });
   });
   ws.addEventListener("close", (event) => {
-    recentWorkspaceSyncProof.invalidate();
+    process.off("SIGTERM", handleGracefulShutdown);
+    process.off("SIGINT", handleGracefulShutdown);
     stopHeartbeatWatchdog();
-    if (periodicWorkspaceScan) {
-      clearInterval(periodicWorkspaceScan);
-      periodicWorkspaceScan = void 0;
+    if (workspaceCheckpointTimer) {
+      clearTimeout(workspaceCheckpointTimer);
+      workspaceCheckpointTimer = void 0;
+    }
+    if (!pendingCheckpoint?.workInFlight) {
+      pendingCheckpoint?.releaseCheckpointAdmission();
+      workspaceConvergence.resetTransientCheckpointState();
+    }
+    if (workspaceSafetyScan) {
+      clearInterval(workspaceSafetyScan);
+      workspaceSafetyScan = void 0;
+    }
+    if (workspaceManifestHydrationTimer) {
+      clearTimeout(workspaceManifestHydrationTimer);
+      workspaceManifestHydrationTimer = void 0;
     }
     if (terminalReplayTimer) {
       clearInterval(terminalReplayTimer);
@@ -3131,6 +3596,9 @@ async function startWorker(options) {
     if (reloadAfterClose) {
       process.exit(WORKER_RELOAD_EXIT_CODE);
     }
+    if (shutdownAfterClose) {
+      process.exit(0);
+    }
     if (activeProcesses.size > 0 || pendingProcessTerminals.size > 0) {
       process.stderr.write(
         `[r5d-worker] ${activeProcesses.size} process(es) active and ${pendingProcessTerminals.size} terminal report(s) pending; reconnecting in ${WORKER_RECONNECT_DELAY_MS}ms