@ricsam/r5d-worker 0.0.58 → 0.0.60

package/dist/mjs/main.mjs

@@ -13,13 +13,19 @@ 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_PUBLICATION_QUIET_MS,
+  WORKSPACE_IDLE_SAFETY_SCAN_MS,
+  ExplicitWorkspacePublicationQueue,
+  WorkspaceManifestRevisionFence,
+  processWorkspaceConvergenceState,
+  waitForWorkspacePublicationOnShutdown,
+  workspacePublicationIncidentAction,
+  workspacePublicationTelemetry
+} from "./workspace-convergence.mjs";
+import { inspectWorkspaceManifestFilesystem } from "./workspace-manifest-admission.mjs";
 import {
   isRetryableWorkerServerStatus,
   superviseWorkerRuntime,
@@ -30,15 +36,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";
 }
@@ -775,25 +777,13 @@ function fallbackInternalRemoteUrl(baseUrl, projectId) {
 }
 function visibleCheckoutRemoteFor(input) {
   const canonicalCheckout = input.manifest?.canonicalCheckouts?.find((checkout) => checkout.branchName === input.branchName);
-  const isCanonicalManifestBranch = Boolean(canonicalCheckout);
-  const usesCanonicalRemote = isCanonicalManifestBranch || !input.manifest?.repoHttpUrl;
-  if (usesCanonicalRemote) {
-    return {
-      remoteUrl: fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
-      authHeader: `Authorization: Bearer ${input.token}`,
-      persistAuth: false,
-      reconcileExistingOrigin: isCanonicalManifestBranch,
-      requireRemoteBranch: isCanonicalManifestBranch,
-      requiredBaseCommit: canonicalCheckout?.scaffoldCommitHash ?? null
-    };
-  }
   return {
-    remoteUrl: input.manifest?.repoHttpUrl ?? fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
-    authHeader: input.manifest?.repoAuthHeader ?? null,
-    persistAuth: true,
-    reconcileExistingOrigin: Boolean(input.manifest?.repoHttpUrl),
-    requireRemoteBranch: false,
-    requiredBaseCommit: null
+    remoteUrl: fallbackInternalRemoteUrl(input.baseUrl, input.projectId),
+    authHeader: `Authorization: Bearer ${input.token}`,
+    persistAuth: false,
+    reconcileExistingOrigin: true,
+    requireRemoteBranch: true,
+    requiredBaseCommit: canonicalCheckout?.scaffoldCommitHash ?? null
   };
 }
 function gitExtraHeaderUrlForRemote(remoteUrl) {
@@ -1014,9 +1004,11 @@ function checkoutVisibleBranch(input) {
 }
 function migrateExistingCheckoutToRequiredRemote(input) {
   if (originRemoteUrl(input.branchPath) === input.remoteUrl) return;
-  if (hasWorktreeChanges(input.branchPath)) {
+  const dirtyWorkingTree = hasWorktreeChanges(input.branchPath);
+  if (dirtyWorkingTree && input.requiredBaseCommit) {
     throw new Error(`Cannot migrate dirty checkout for ${input.branchName} to its canonical remote`);
   }
+  const preserveWorkingTree = dirtyWorkingTree;
   runGit(
     visibleCheckoutFetchArgs("--no-tags", input.remoteUrl, `+refs/heads/${input.branchName}:refs/remotes/origin/${input.branchName}`),
     {
@@ -1031,11 +1023,12 @@ function migrateExistingCheckoutToRequiredRemote(input) {
   if (input.requiredBaseCommit && (!tryGit(["cat-file", "-e", `${input.requiredBaseCommit}^{commit}`], { cwd: input.branchPath }) || !tryGit(["merge-base", "--is-ancestor", input.requiredBaseCommit, canonicalRemoteRef], { cwd: input.branchPath }))) {
     throw new Error(`Canonical branch ${input.branchName} is not derived from required scaffold ${input.requiredBaseCommit}`);
   }
+  ensureOriginRemote(input.branchPath, input.remoteUrl);
+  if (preserveWorkingTree) return;
   if (tryGit(["rev-parse", "--verify", "HEAD"], { cwd: input.branchPath })) {
     const previousHead = runGit(["rev-parse", "HEAD"], { cwd: input.branchPath });
     runGit(["update-ref", `refs/r5d/pre-canonical-checkout/${previousHead}`, previousHead], { cwd: input.branchPath });
   }
-  ensureOriginRemote(input.branchPath, input.remoteUrl);
   runGit(["checkout", "--no-recurse-submodules", "-B", input.branchName, `origin/${input.branchName}`], {
     cwd: input.branchPath
   });
@@ -1128,7 +1121,7 @@ function ensureVisibleGitCheckout(input) {
   configureVisibleGitIdentity(branchPath, visibleGitIdentity, runGit);
   return branchPath;
 }
-function ensureBranchWorkspace(input) {
+function ensureBranchWorktree(input) {
   const defaultBranch = input.manifest?.defaultBranch || "main";
   const remote = visibleCheckoutRemoteFor(input);
   return {
@@ -1161,7 +1154,7 @@ function resolveWorkerSessionTarget(input) {
   }
   const manifest = input.manifestByProjectId.get(input.target.projectId);
   const projectRoot = projectRootFor(input.projectsRoot, input.target.projectId, input.manifestByProjectId);
-  const workspace = ensureBranchWorkspace({
+  const worktree = ensureBranchWorktree({
     projectId: input.target.projectId,
     baseUrl: input.baseUrl,
     token: input.token,
@@ -1170,7 +1163,7 @@ function resolveWorkerSessionTarget(input) {
     branchName: input.target.branchName,
     manifest
   });
-  return { target: input.target, rootPath: workspace.branchPath, manifest };
+  return { target: input.target, rootPath: worktree.branchPath, manifest };
 }
 function workspaceSyncCheckoutTargets(input) {
   const selected = /* @__PURE__ */ new Map();
@@ -2268,6 +2261,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 +2272,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 +2364,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 workspacePublicationTimer;
+  let workspaceSafetyScan;
+  let workspaceManifestHydrationTimer;
+  let workspaceManifestHydrationInFlight = false;
+  let workspaceSafetyScanInFlight = false;
+  let workspaceHeadConvergenceInFlight = false;
+  let pendingWorkspaceHead;
+  let pendingPublication;
+  const explicitWorkspacePublications = new ExplicitWorkspacePublicationQueue();
   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 +2408,160 @@ 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 targetMayMutateVisibleWorkspace = (target) => target.type === "project" || target.rootProfile === "visible_projects";
+  const armWorkspacePublication = (trigger, options2 = { delayMs: WORKSPACE_PUBLICATION_QUIET_MS }) => {
+    workspaceConvergence.schedule();
+    if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) return;
+    sendWorkspaceReady();
+    if (options2.requestId && !explicitWorkspacePublications.schedule({ requestId: options2.requestId, trigger }, pendingPublication?.requestId)) {
+      return;
+    }
+    if (!options2.requestId && explicitWorkspacePublications.hasScheduled()) return;
+    if (workspacePublicationTimer) clearTimeout(workspacePublicationTimer);
+    workspacePublicationTimer = setTimeout(
+      () => {
+        workspacePublicationTimer = void 0;
+        if (options2.requestId) explicitWorkspacePublications.consumeScheduled(options2.requestId);
+        if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) return;
+        if (!workspaceReady || !workspaceRemoteUrl) {
+          armWorkspacePublication(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+          return;
+        }
+        if (activeWorkspaceIncidentId) {
+          workspaceConvergence.block();
+          sendWorkspaceReady();
+          if (workspacePublicationIncidentAction(options2.requestId) === "defer_automatic") return;
+          if (pendingPublication) {
+            explicitWorkspacePublications.enqueue({ requestId: options2.requestId, trigger }, pendingPublication.requestId);
+            return;
+          }
+          const snapshot2 = workspaceConvergence.snapshot();
+          pendingPublication = {
+            requestId: options2.requestId,
+            trigger,
+            dirtyGeneration: snapshot2.dirtyGeneration,
+            explicit: true,
+            workInFlight: false,
+            requestedAt: Date.now()
+          };
+          try {
+            ws.send(
+              JSON.stringify({
+                type: "workspace_publication_request",
+                requestId: options2.requestId,
+                trigger,
+                dirtyGeneration: snapshot2.dirtyGeneration,
+                localHead: snapshot2.localHead,
+                desiredCanonicalHead: snapshot2.desiredCanonicalHead
+              })
+            );
+          } catch (error) {
+            pendingPublication = void 0;
+            workspaceConvergence.defer();
+            process.stderr.write(
+              `[r5d-worker] failed to request blocked workspace publication authority: ${error instanceof Error ? error.message : String(error)}
+`
+            );
+            armWorkspacePublication(trigger, { delayMs: 1e3, requestId: options2.requestId });
+          }
+          return;
+        }
+        if (pendingPublication) {
+          armWorkspacePublication(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+          return;
+        }
+        const snapshot = workspaceConvergence.snapshot();
+        const requestId = options2.requestId ?? crypto.randomUUID();
+        pendingPublication = {
+          requestId,
           trigger,
-          ...fingerprint ? { fingerprint } : {}
+          dirtyGeneration: snapshot.dirtyGeneration,
+          explicit: options2.requestId !== void 0,
+          workInFlight: false,
+          requestedAt: Date.now()
+        };
+        try {
+          ws.send(
+            JSON.stringify({
+              type: "workspace_publication_request",
+              requestId,
+              trigger,
+              dirtyGeneration: snapshot.dirtyGeneration,
+              localHead: snapshot.localHead,
+              desiredCanonicalHead: snapshot.desiredCanonicalHead
+            })
+          );
+        } catch (error) {
+          pendingPublication = void 0;
+          workspaceConvergence.defer();
+          process.stderr.write(
+            `[r5d-worker] failed to request workspace publication: ${error instanceof Error ? error.message : String(error)}
+`
+          );
+          armWorkspacePublication(trigger, { delayMs: 1e3, ...options2.requestId ? { requestId: options2.requestId } : {} });
+        }
+      },
+      Math.max(0, options2.delayMs)
+    );
+    workspacePublicationTimer.unref();
+  };
+  const markWorkspaceDirty = (trigger, force = false) => {
+    workspaceConvergence.markDirty();
+    armWorkspacePublication(trigger, { delayMs: force ? 0 : WORKSPACE_PUBLICATION_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;
+    try {
+      const snapshot = workspaceConvergence.snapshot();
+      const hydrateVisible = !pendingPublication && snapshot.dirtyGeneration === snapshot.publishedGeneration;
+      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 publication" });
+      }
+      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 {
+      workspaceHeadConvergenceInFlight = false;
+      heartbeatBusyGrace = grantWorkerHeartbeatBusyGrace(lastServerHeartbeatAt, heartbeatBusyGrace);
+      if (pendingWorkspaceHead !== void 0) {
+        setTimeout(() => void convergeAvailableWorkspaceHead(), 1e3).unref();
+      }
     }
   };
   const manifestCheckoutKey = (projectId, branchName) => `${projectId}\0${branchName}`;
@@ -2433,7 +2577,7 @@ async function startWorker(options) {
     workspaceShadowRoot,
     manifestByProjectId
   });
-  const ensureVisibleWorkspaceCheckouts = (targets, options2 = {}) => {
+  const ensureVisibleWorktrees = (targets, options2 = {}) => {
     const created = [];
     for (const target of targets) {
       const manifest = manifestByProjectId.get(target.projectId);
@@ -2462,20 +2606,62 @@ async function startWorker(options) {
         reconcileExistingOrigin: remote.reconcileExistingOrigin,
         requireRemoteBranch: remote.requireRemoteBranch,
         requiredBaseCommit: remote.requiredBaseCommit,
-        allowRequiredRemoteMigration: !(options2.strictCanonicalRevalidation && remote.requireRemoteBranch),
+        allowRequiredRemoteMigration: !(options2.strictCanonicalRevalidation && remote.requiredBaseCommit),
         clearPersistentAuth: !remote.persistAuth
       });
       if (!existed) created.push(target);
     }
     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 || pendingPublication || pendingManifestCheckouts.size === 0 || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+          if (pendingManifestCheckouts.size > 0 && currentWorkerSocket === ws && ws.readyState === WebSocket.OPEN) {
+            schedulePendingManifestCheckoutHydration(1e3);
+          }
+          return;
+        }
+        workspaceManifestHydrationInFlight = true;
+        void workspaceSyncSingleFlight.runExclusive(async () => {
+          if (!workspaceReady || activeWorkspaceIncidentId || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+            return;
+          }
+          const targets = [...pendingManifestCheckouts.values()];
+          ensureVisibleWorktrees(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(() => {
+          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 +2670,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) {
@@ -2537,7 +2687,7 @@ async function startWorker(options) {
           });
         }
         pendingTargets = shouldEnsureCheckouts ? scopedPendingTargets : [];
-        const createdCheckouts = ensureVisibleWorkspaceCheckouts(checkoutTargets, {
+        const createdCheckouts = ensureVisibleWorktrees(checkoutTargets, {
           strictCanonicalRevalidation: true
         });
         const newVisibleCheckoutByKey = /* @__PURE__ */ new Map();
@@ -2551,24 +2701,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 +2716,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 +2725,6 @@ async function startWorker(options) {
           if (pendingManifestCheckouts.get(key) === target) pendingManifestCheckouts.delete(key);
         }
       }
-      previousPeriodicFingerprint = null;
       sendWorkspaceSyncResult(authority, resultWithTelemetry);
       return resultWithTelemetry;
     } catch (error) {
@@ -2611,12 +2747,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 +2766,24 @@ async function startWorker(options) {
   let heartbeatBusyGrace = null;
   let heartbeatTimedOut = false;
   let heartbeatWatchdog;
+  const handleGracefulShutdown = () => {
+    if (shutdownAfterClose) return;
+    shutdownAfterClose = true;
+    void waitForWorkspacePublicationOnShutdown({
+      snapshot: () => workspaceConvergence.snapshot(),
+      forcePublication: () => armWorkspacePublication({ type: "manual", detail: "graceful worker shutdown" }, { delayMs: 0 })
+    }).then((outcome) => {
+      process.stdout.write(`[r5d-worker] graceful workspace publication ${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 +2814,8 @@ async function startWorker(options) {
           updateClis: true,
           canonicalResolverCheckout: true,
           browserPortForwarding: true,
-          globalWorkspaceSyncLeaseV1: true
+          globalWorkspaceSyncLeaseV1: true,
+          eventualWorkspaceSyncV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -2689,14 +2842,19 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "workspace_manifest") {
-        recentWorkspaceSyncProof.invalidate();
-        await workspaceSyncSingleFlight.runMutation(() => {
+        const revisionToken = workspaceManifestRevision.begin(message.revision);
+        workspaceReady = false;
+        const manifestFilesystem = inspectWorkspaceManifestFilesystem({
+          projectsRoot,
+          workspaceShadowRoot,
+          projects: message.projects
+        });
+        const completed = await workspaceSyncSingleFlight.runExclusive(async () => {
+          if (!workspaceManifestRevision.isCurrent(revisionToken)) return false;
+          const firstBootstrap = manifestFilesystem.firstBootstrap;
           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);
@@ -2709,80 +2867,77 @@ async function startWorker(options) {
           }
           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;
+          if (!workspaceManifestRevision.isCurrent(revisionToken)) return false;
+          const created = firstBootstrap || migratedProjectIds.length > 0 ? ensureVisibleWorktrees(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
+          });
+          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));
+            }
+          }
           process.stdout.write(
             `[r5d-worker] workspace manifest: ${message.projects.length} projects${migratedProjectIds.length > 0 ? `; migrated ${migratedProjectIds.length} project checkout root(s)` : ""}
 `
           );
+          return true;
         });
-        if (!periodicWorkspaceScan) {
-          const emptyFingerprint = createHash("sha256").update("").digest("hex");
-          periodicWorkspaceScan = setInterval(() => {
-            if (!workspaceRemoteUrl || activeWorkspaceIncidentId || cliUpdateInProgress || periodicWorkspaceScanInFlight) return;
-            periodicWorkspaceScanInFlight = true;
+        if (!completed || !workspaceManifestRevision.complete(revisionToken)) return;
+        workspaceReady = true;
+        sendWorkspaceReady();
+        schedulePendingManifestCheckoutHydration();
+        if (!workspaceSafetyScan) {
+          workspaceSafetyScan = setInterval(() => {
+            if (!workspaceReady || !workspaceRemoteUrl || activeWorkspaceIncidentId || pendingPublication || workspaceSafetyScanInFlight) {
+              return;
+            }
+            workspaceSafetyScanInFlight = true;
             void (async () => {
-              const genericCheckoutKeys = new Set(
-                workspaceProjectsForSync([...manifestByProjectId.values()], { type: "periodic" }).flatMap(
-                  (project) => project.branches.map((branchName) => manifestCheckoutKey(project.projectId, branchName))
-                )
+              const before = workspaceConvergence.snapshot();
+              const hydrateVisible = before.dirtyGeneration === before.publishedGeneration;
+              const converged = await workspaceSyncSingleFlight.runExclusive(
+                () => convergeWorkspaceHead(workspaceSyncInput({ type: "periodic", detail: "idle convergence scan" }), {
+                  hydrateVisible
+                })
               );
-              const hasPendingGenericCheckout = [...pendingManifestCheckouts.values()].some(
-                (target) => genericCheckoutKeys.has(manifestCheckoutKey(target.projectId, target.branchName))
-              );
-              if (hasPendingGenericCheckout) {
-                recentWorkspaceSyncProof.invalidate();
-                previousPeriodicFingerprint = null;
-                requestWorkspaceSync({
-                  type: "periodic",
-                  detail: "workspace manifest additions"
-                });
-                return;
+              workspaceConvergence.observeCanonicalHead(converged.canonicalHead);
+              if (converged.hydrated) workspaceConvergence.setLocalHead(converged.localHead);
+              if (converged.localChanges && hydrateVisible) {
+                markWorkspaceDirty({ type: "periodic", detail: "idle safety scan" });
               }
-              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;
-              }
-              recentWorkspaceSyncProof.invalidate();
-              if (previousPeriodicFingerprint !== observation.fingerprint) {
-                previousPeriodicFingerprint = observation.fingerprint;
-                return;
-              }
-              previousPeriodicFingerprint = null;
-              requestWorkspaceSync({ type: "periodic" }, observation.fingerprint);
+              sendWorkspaceReady();
             })().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) {
+          armWorkspacePublication({ type: "periodic", detail: "resume dirty generation after reconnect" }, { delayMs: 0 });
         }
         return;
       }
@@ -2802,12 +2957,181 @@ 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_publication_now") {
+        armWorkspacePublication(message.trigger, { delayMs: 0, requestId: message.requestId });
+        return;
+      }
+      if (message.type === "workspace_publication_authority") {
+        const publication = pendingPublication;
+        if (!publication || publication.requestId !== message.requestId) {
+          process.stderr.write(`[r5d-worker] ignoring publication authority for unknown request ${message.requestId}
+`);
+          return;
+        }
+        if (message.status !== "granted") {
+          pendingPublication = 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.resetTransientPublicationState();
+            workspaceConvergence.observeIncidentState(Boolean(activeWorkspaceIncidentId));
+            if (message.status === "busy") {
+              armWorkspacePublication(publication.trigger, {
+                delayMs: message.retryAfterMs ?? 1e3,
+                requestId: publication.requestId
+              });
+            } else if (!activeWorkspaceIncidentId) {
+              const explicit = explicitWorkspacePublications.next();
+              if (explicit) {
+                armWorkspacePublication(explicit.trigger, { delayMs: 0, requestId: explicit.requestId });
+              } else if (workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+                armWorkspacePublication(publication.trigger, { delayMs: 0 });
+              }
+            }
+          }
+          sendWorkspaceReady();
+          return;
+        }
+        publication.attemptId = message.attemptId;
+        publication.authorityToken = message.authorityToken;
+        publication.workInFlight = true;
+        pendingPublication = publication;
+        if (currentWorkerSocket !== ws) {
+          publication.workInFlight = false;
+          workspaceConvergence.resetTransientPublicationState();
+          return;
+        }
+        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 = ensureVisibleWorktrees(pendingTargets, { strictCanonicalRevalidation: true });
+            synchronizeStartedAt = Date.now();
+            synchronizeStarted = true;
+            const prepared = await synchronizeWorkspace(
+              workspaceSyncInput(publication.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: publication.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: publication.dirtyGeneration,
+          telemetry: workspacePublicationTelemetry({
+            requestedAt: publication.requestedAt,
+            prepareStartedAt,
+            synchronizeStartedAt,
+            finishedAt
+          })
+        };
+        workspaceConvergence.beginSubmitting();
+        sendWorkspaceReady();
+        try {
+          ws.send(
+            JSON.stringify({
+              type: "workspace_publication_result",
+              requestId: publication.requestId,
+              attemptId: message.attemptId,
+              authorityToken: message.authorityToken,
+              dirtyGeneration: publication.dirtyGeneration,
+              result
+            })
+          );
+        } catch (error) {
+          workspaceConvergence.resetTransientPublicationState();
+          throw error;
+        } finally {
+          publication.workInFlight = false;
+          if (currentWorkerSocket !== ws) workspaceConvergence.resetTransientPublicationState();
+        }
+        return;
+      }
+      if (message.type === "workspace_publication_completed") {
+        const publication = pendingPublication;
+        if (!publication || publication.requestId !== message.requestId || publication.attemptId !== message.attemptId) {
+          process.stderr.write(`[r5d-worker] ignoring completion for unknown publication ${message.requestId}
+`);
+          return;
+        }
+        pendingPublication = void 0;
+        workspaceConvergence.observeCanonicalHead(message.canonicalHead);
+        if (message.status === "published" || message.status === "no_change") {
+          workspaceConvergence.complete({
+            generation: Math.min(message.publishedGeneration ?? publication.dirtyGeneration, publication.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.resetTransientPublicationState();
+          workspaceConvergence.observeIncidentState(Boolean(activeWorkspaceIncidentId));
+        }
+        sendWorkspaceReady();
+        const explicit = message.status === "retry" && publication.explicit ? { requestId: publication.requestId, trigger: publication.trigger } : explicitWorkspacePublications.next();
+        if (explicit) {
+          armWorkspacePublication(explicit.trigger, {
+            delayMs: message.retryAfterMs ?? 0,
+            requestId: explicit.requestId
+          });
+        } else if (message.status === "retry" || message.status === "failed" || workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+          armWorkspacePublication(publication.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 +3159,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 ? explicitWorkspacePublications.next() : void 0;
+        if (explicit) {
+          armWorkspacePublication(explicit.trigger, { delayMs: 0, requestId: explicit.requestId });
+        } else if (!activeWorkspaceIncidentId && workspaceConvergence.snapshot().dirtyGeneration > workspaceConvergence.snapshot().publishedGeneration) {
+          armWorkspacePublication({ type: "periodic", detail: "resume after workspace incident" }, { delayMs: 0 });
+        }
+        if (!activeWorkspaceIncidentId) schedulePendingManifestCheckoutHydration();
+        sendWorkspaceReady();
         return;
       }
       if (message.type === "exec_terminal_ack") {
@@ -2882,7 +3215,6 @@ async function startWorker(options) {
           return;
         }
         cliUpdateInProgress = true;
-        recentWorkspaceSyncProof.invalidate();
         try {
           const result = await installCliUpdate(message);
           sendWorkerMessage(ws, {
@@ -2945,9 +3277,8 @@ async function startWorker(options) {
           });
           return;
         }
-        recentWorkspaceSyncProof.invalidate();
         const releaseWorkspaceMutation = await acquireWorkspaceCommandMutation(message.target, workspaceSyncSingleFlight);
-        let leaseTransferred = false;
+        let mutationLeaseTransferred = false;
         try {
           const resolvedTarget = resolveMessageTarget(message.target);
           process.stdout.write(`[r5d-worker] pty ${message.ptyId}: ${describeWorkerSessionTarget(message.target)}
@@ -2957,9 +3288,14 @@ 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);
+              }
+            } : {}
           });
-          leaseTransferred = releaseWorkspaceMutation !== void 0;
+          mutationLeaseTransferred = releaseWorkspaceMutation !== void 0;
         } catch (error) {
           sendWorkerMessage(ws, {
             type: "pty_error",
@@ -2968,12 +3304,15 @@ async function startWorker(options) {
             error: error instanceof Error ? error.message : String(error)
           });
         } finally {
-          if (!leaseTransferred) releaseWorkspaceMutation?.();
+          if (!mutationLeaseTransferred) releaseWorkspaceMutation?.();
         }
         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 +3321,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)) {
+          armWorkspacePublication({ type: "process_terminal", detail: `pty ${message.ptyId} closed` }, { delayMs: 0 });
+        }
         return;
       }
       if (message.type === "exec") {
@@ -2997,7 +3339,6 @@ async function startWorker(options) {
           });
           return;
         }
-        recentWorkspaceSyncProof.invalidate();
         let result;
         try {
           const runCommand = async () => {
@@ -3018,6 +3359,12 @@ async function startWorker(options) {
           };
         }
         ws.send(JSON.stringify(result));
+        if (targetMayMutateVisibleWorkspace(message.target)) {
+          markWorkspaceDirty(
+            { type: "shell_inline", sessionId: message.sessionId, processRunId: message.runId, detail: "foreground command completed" },
+            true
+          );
+        }
         return;
       }
       if (message.type === "exec_start") {
@@ -3030,25 +3377,38 @@ 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(" ")}
+          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
+              );
+            }
+          }
         };
         const execution = runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
         void execution.catch((error) => {
@@ -3062,9 +3422,8 @@ 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();
         try {
-          const result = await workspaceSyncSingleFlight.runMutation(async () => {
+          const result = await runWorkspaceCommand(message.target, workspaceSyncSingleFlight, async () => {
             const resolvedTarget = resolveMessageTarget(message.target);
             return await executeOperation({
               message,
@@ -3082,6 +3441,14 @@ async function startWorker(options) {
               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({
@@ -3111,11 +3478,23 @@ 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 (workspacePublicationTimer) {
+      clearTimeout(workspacePublicationTimer);
+      workspacePublicationTimer = void 0;
+    }
+    if (!pendingPublication?.workInFlight) {
+      workspaceConvergence.resetTransientPublicationState();
+    }
+    if (workspaceSafetyScan) {
+      clearInterval(workspaceSafetyScan);
+      workspaceSafetyScan = void 0;
+    }
+    if (workspaceManifestHydrationTimer) {
+      clearTimeout(workspaceManifestHydrationTimer);
+      workspaceManifestHydrationTimer = void 0;
     }
     if (terminalReplayTimer) {
       clearInterval(terminalReplayTimer);
@@ -3131,6 +3510,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