@ricsam/r5d-worker 0.0.82 → 0.0.83

package/dist/mjs/main.mjs

@@ -79,12 +79,14 @@ import {
   pruneAuthoritativelyDesiredBranchDeletions
 } from "./project-workspace-state.mjs";
 import {
+  configureExistingWorkspaceGitForRemediation,
   ensureWorkspaceGitClone,
   hydrateWorkspaceGitMounts,
   recoverWorkspaceGitHydration,
   resetWorkspaceGit,
   synchronizeWorkspaceGit,
-  workspaceGitHydrationIsCurrent
+  workspaceGitHydrationIsCurrent,
+  WorkspaceRemediationAncestryError
 } from "./workspace-git-sync.mjs";
 class ProjectWorkspaceConfigurationDeferredError extends Error {
 }
@@ -99,6 +101,7 @@ const DEFAULT_READ_MAX_BYTES = 5e4;
 const MAX_LINE_LENGTH = 2e3;
 const WORKSPACE_GIT_QUIET_MS = 5e3;
 const WORKSPACE_GIT_PERIODIC_MS = 6e4;
+const WORKSPACE_INCIDENT_CONFIG_REFRESH_TIMEOUT_MS = 6e4;
 const PTY_INPUT_BUSY_GRACE_MS = 3e3;
 const PTY_FOREGROUND_POLL_MS = 1e3;
 const PTY_FOREGROUND_IDLE_ENABLED = process.env.R5D_PTY_FOREGROUND_IDLE !== "0";
@@ -257,6 +260,7 @@ const workerPtyTestHarness = {
   removeEnvFiles: removePtyEnvFiles,
   resolveEnvFileReferences: resolvePtyEnvFileReferences,
   commandHasWorkspaceEffect: workerCommandHasWorkspaceEffect,
+  canonicalSyncTerminalHead,
   ptyIsWorkspaceBusy: workerPtyIsWorkspaceBusy,
   parseLinuxForegroundBusy: parseLinuxPtyForegroundBusy
 };
@@ -1518,6 +1522,86 @@ function credentialReapContractStatus(probe) {
 function verifiedCredentialReapContract(probe) {
   return credentialReapContractStatus(probe) === "verified_systemd";
 }
+function workspaceConfigurationIncidentDeferral(input) {
+  const incidentId = input.requestedIncidentId ?? input.activeIncidentId;
+  if (incidentId === null) return { incidentId: null };
+  if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(incidentId)) {
+    return { incidentId: null, error: new Error("Workspace configuration incident deferral requires a canonical incident UUID") };
+  }
+  if (input.requestedIncidentId !== void 0 && input.requestedIncidentId !== input.activeIncidentId) {
+    return {
+      incidentId: null,
+      error: new Error(
+        `Workspace configuration incident deferral ${input.requestedIncidentId} does not match active incident ${input.activeIncidentId ?? "none"}`
+      )
+    };
+  }
+  return { incidentId };
+}
+function workspaceIncidentTerminalClearDisposition(input) {
+  if (!input.deferredConfiguration) return "ordinary_resume";
+  void input.clearedIncidentId;
+  return input.deferredConfiguration.serverRefreshExpected ? "await_server_refresh" : "reconnect_for_refresh";
+}
+function deferredWorkspaceTargetIsAllowed(deferredConfiguration, activeIncidentId, target) {
+  const canonicalTarget = target.type === "workspace" && target.rootProfile === "canonical_sync";
+  if (deferredConfiguration) return activeIncidentId === deferredConfiguration.incidentId && canonicalTarget;
+  return activeIncidentId === null || canonicalTarget;
+}
+function deferredWorkspaceSyncTriggerIsAllowed(deferredConfiguration, activeIncidentId, trigger) {
+  const incidentId = deferredConfiguration?.incidentId ?? activeIncidentId;
+  return incidentId === null || (deferredConfiguration === null || activeIncidentId === deferredConfiguration.incidentId) && (trigger.type === "remediation" || trigger.type === "remediation_confirm" || trigger.type === "remediation_reset");
+}
+function workspaceOperationsAreFenced(deferredConfiguration, activeIncidentId) {
+  return deferredConfiguration !== null || activeIncidentId !== null;
+}
+function workspaceCommandTransportIsAllowed(deferredConfiguration, activeIncidentId, transport) {
+  return !workspaceOperationsAreFenced(deferredConfiguration, activeIncidentId) || transport === "exec_start";
+}
+function deferredCredentialTransitionMustWait(input) {
+  return input.incidentId !== null && input.transitionPhase !== "current" && input.canonicalRemediationActive;
+}
+function workspaceConfigurationIncidentSnapshotIsCurrent(capturedIncidentId, activeIncidentId) {
+  return capturedIncidentId === null ? activeIncidentId === null : activeIncidentId === null || activeIncidentId === capturedIncidentId;
+}
+function deferredWorkspaceRefreshWatchdogIsCurrent(input) {
+  return input.deferredConfiguration?.incidentId === input.capturedIncidentId && input.activeIncidentId === null;
+}
+function incidentDeferredProjectCheckouts(projects) {
+  return projects.flatMap(
+    (project) => project.executionDisabled ? [] : project.branches.map(({ branchName }) => ({ projectId: project.projectId, branchName }))
+  ).sort((left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName));
+}
+function deferredIncidentWorkspaceConfigurationResult(input) {
+  return {
+    type: "workspace_sync",
+    attemptId: input.attemptId,
+    workerLabel: input.workerLabel,
+    trigger: { type: "connect", detail: "workspace synchronization deferred for active remediation" },
+    outcome: "no_change",
+    startingHead: input.head,
+    ...input.head ? { localHead: input.head } : {},
+    rebaseCount: 0,
+    diffSizeBytes: 0,
+    gitStatus: "",
+    affectedProjects: [],
+    affectedPaths: [],
+    activeMountIds: [],
+    skippedMountIds: [...input.skippedMountIds].sort(),
+    activeProjectBranchPublications: [],
+    discardedPaths: [],
+    localChangesDiscarded: false
+  };
+}
+function workspaceSyncFailureHydrationIsSafe(input) {
+  if (input.error instanceof WorkspaceRemediationAncestryError) return true;
+  if (input.resetToCanonical) return false;
+  try {
+    return input.inspectCurrentHydration();
+  } catch {
+    return false;
+  }
+}
 function fenceUnsafeWorkspaceSyncFailure(input) {
   if (input.hydrationCurrent) return false;
   input.invalidateExecution();
@@ -1550,7 +1634,21 @@ const workerGitSecurityTestHarness = {
   credentialReapContractStatus,
   verifiedCredentialReapContract,
   fenceUnsafeWorkspaceSyncFailure,
+  workspaceConfigurationIncidentDeferral,
+  workspaceIncidentTerminalClearDisposition,
+  deferredWorkspaceTargetIsAllowed,
+  deferredWorkspaceSyncTriggerIsAllowed,
+  workspaceOperationsAreFenced,
+  workspaceCommandTransportIsAllowed,
+  deferredCredentialTransitionMustWait,
+  workspaceConfigurationIncidentSnapshotIsCurrent,
+  deferredWorkspaceRefreshWatchdogIsCurrent,
+  incidentDeferredProjectCheckouts,
+  deferredIncidentWorkspaceConfigurationResult,
+  workspaceSyncFailureHydrationIsSafe,
   assertWorkerChildAdmission,
+  executeWriteFileOperation,
+  executeEditFileOperation,
   terminateCredentialBearingChildren,
   terminateCredentialBearingChildrenWithRetention,
   async commitCredentialGeneration(prepared, credential, children, beforeMutation, previousGenerationFenced = false) {
@@ -1701,6 +1799,15 @@ function hasProjectWorktree(checkoutPath) {
     return false;
   }
 }
+function canonicalSyncTerminalHead(resolvedTarget, readHead = (rootPath) => runGit(["rev-parse", "HEAD"], { cwd: rootPath })) {
+  if (resolvedTarget.target.type !== "workspace" || resolvedTarget.target.rootProfile !== "canonical_sync") return void 0;
+  try {
+    const head = readHead(resolvedTarget.rootPath);
+    return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(head) ? head : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function describeWorkerSessionTarget(target) {
   return target.type === "project" ? `${target.projectId}/${target.branchName}` : `${target.ownerUserId}/${target.rootProfile}`;
 }
@@ -2005,8 +2112,10 @@ async function executeWriteFileOperation(input) {
     planRoot: input.planRoot,
     access: "write"
   });
+  input.assertAdmission();
   const resolved = resolveWorkerFilePath(input.resolvedTarget.rootPath, input.message.filePath, builtInPaths);
   return withFileMutationQueue(mutationQueueKey(input.resolvedTarget.target, resolved), async () => {
+    input.assertAdmission();
     return writeWorkerTextFile(input.resolvedTarget.rootPath, input.message.filePath, input.message.content, builtInPaths);
   });
 }
@@ -2022,8 +2131,10 @@ async function executeEditFileOperation(input) {
     planRoot: input.planRoot,
     access: "write"
   });
+  input.assertAdmission();
   const resolved = resolveWorkerFilePath(input.resolvedTarget.rootPath, input.message.filePath, builtInPaths);
   return withFileMutationQueue(mutationQueueKey(input.resolvedTarget.target, resolved), async () => {
+    input.assertAdmission();
     return editWorkerTextFile(input.resolvedTarget.rootPath, input.message.filePath, input.message.edits, builtInPaths);
   });
 }
@@ -2599,13 +2710,15 @@ async function executeStreamingCommand(input) {
         });
       })
     ]);
+    const canonicalWorkspaceHead = canonicalSyncTerminalHead(input.resolvedTarget);
     const terminal = {
       type: "exec_exit",
       runId: input.message.runId,
       exitCode,
       durationMs: Date.now() - startedAt,
       ...timedOut ? { timedOut: true } : {},
-      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+      ...canonicalWorkspaceHead ? { canonicalWorkspaceHead } : {}
     };
     pendingProcessTerminals.set(input.message.runId, terminal);
     sendWorkerMessage(input.ws, terminal);
@@ -2613,12 +2726,14 @@ async function executeStreamingCommand(input) {
     if (!started && error instanceof StaleWorkerAdmissionError) throw error;
     const message = error instanceof Error ? error.message : String(error);
     if (started) {
+      const canonicalWorkspaceHead = canonicalSyncTerminalHead(input.resolvedTarget);
       const terminal = {
         type: "exec_error",
         runId: input.message.runId,
         error: message,
         durationMs: Date.now() - startedAt,
-        ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
+        ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+        ...canonicalWorkspaceHead ? { canonicalWorkspaceHead } : {}
       };
       pendingProcessTerminals.set(input.message.runId, terminal);
       sendWorkerMessage(input.ws, terminal);
@@ -3273,6 +3388,9 @@ async function startWorker(options) {
   let workspaceGitIdentity = null;
   let workspaceConfigured = false;
   let activeWorkspaceIncidentId = null;
+  let deferredWorkspaceConfiguration = null;
+  let deferredWorkspaceConfigurationRefreshTimer;
+  let workspaceConfigurationReceiptGeneration = 0;
   let workspaceAutomaticTimer;
   let workspacePeriodicTimer;
   let pendingAutomaticTrigger;
@@ -3990,6 +4108,7 @@ async function startWorker(options) {
       ...result.conflictPaths ? { conflictPaths: result.conflictPaths } : {},
       ...result.conflictSnapshotRefs ? { conflictSnapshotRefs: result.conflictSnapshotRefs } : {},
       ...result.conflictKind ? { conflictKind: result.conflictKind } : {},
+      ...result.verifiedAncestorHeads ? { verifiedAncestorHeads: result.verifiedAncestorHeads } : {},
       ...result.error ? { error: result.error } : {}
     };
   };
@@ -4075,10 +4194,13 @@ async function startWorker(options) {
       commitDetail: input.confirmationReason ?? input.trigger.detail,
       allowLargeDiff: input.confirmedLargeDiff,
       skipMountMirror: outerRemediation,
+      requiredAncestorHeads: input.requiredAncestorHeads,
+      assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : ({ activeMountIds, publishedHead }) => {
         pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, inboundMoveMountIds);
       }
     });
+    input.assertStillAdmitted?.();
     if (["no_change", "updated", "pushed"].includes(result.outcome) && !outerRemediation) {
       applyObservedProjectHeadsAfterInboundWorkspace(observedProjectHeads, result.activeMountIds, false);
     }
@@ -4101,6 +4223,28 @@ async function startWorker(options) {
   const runWorkspaceSync = async (input) => {
     const attemptId = input.attemptId ?? crypto.randomUUID();
     const requestedAt = Date.now();
+    const admittedGeneration = workerAdmissionGeneration;
+    const admittedActiveIncidentId = activeWorkspaceIncidentId;
+    const admittedDeferredIncidentId = deferredWorkspaceConfiguration?.incidentId ?? null;
+    const assertStillAdmitted = () => {
+      if (admittedGeneration !== workerAdmissionGeneration || admittedActiveIncidentId !== activeWorkspaceIncidentId || admittedDeferredIncidentId !== (deferredWorkspaceConfiguration?.incidentId ?? null) || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN || !deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
+        throw new Error("Workspace synchronization admission changed while asynchronous work was in flight");
+      }
+    };
+    if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
+      const result2 = {
+        ...failedWorkspaceSyncResult(
+          attemptId,
+          input.trigger,
+          new Error(
+            `Workspace synchronization is deferred for incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}; only remediation synchronization is allowed`
+          )
+        ),
+        telemetry: { totalMs: 0, queueMs: 0, prepareMs: 0, synchronizeMs: 0 }
+      };
+      if (input.sendResult !== false) sendWorkspaceSyncResult(input.requestId, result2);
+      return result2;
+    }
     if (!input.requestId && input.sendResult !== false) {
       if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
         throw new Error("Cannot start autonomous workspace synchronization without an open worker control socket");
@@ -4115,23 +4259,32 @@ async function startWorker(options) {
       result = await workspaceSyncSingleFlight.runExclusive(async () => {
         queueEnteredAt = Date.now();
         syncStartedAt = Date.now();
+        if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
+          return failedWorkspaceSyncResult(
+            attemptId,
+            input.trigger,
+            new Error(
+              `Workspace synchronization was fenced while queued by incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}`
+            )
+          );
+        }
         try {
+          assertStillAdmitted();
           return await performWorkspaceSync({
             attemptId,
             trigger: input.trigger,
             confirmedLargeDiff: input.confirmedLargeDiff,
             confirmationReason: input.confirmationReason,
-            resetToCanonical: input.resetToCanonical
+            resetToCanonical: input.resetToCanonical,
+            requiredAncestorHeads: input.requiredAncestorHeads,
+            assertStillAdmitted
           });
         } catch (error) {
-          let hydrationCurrent = input.resetToCanonical !== true;
-          if (hydrationCurrent) {
-            try {
-              hydrationCurrent = workspaceGitHydrationIsCurrent(workspaceShadowRoot, buildWorkspaceMounts());
-            } catch {
-              hydrationCurrent = false;
-            }
-          }
+          const hydrationCurrent = workspaceSyncFailureHydrationIsSafe({
+            error,
+            resetToCanonical: input.resetToCanonical === true,
+            inspectCurrentHydration: () => workspaceGitHydrationIsCurrent(workspaceShadowRoot, buildWorkspaceMounts())
+          });
           if (!hydrationCurrent) {
             process.stderr.write(
               `[r5d-worker] workspace synchronization failed with an incompletely hydrated visible tree; exiting for exact recovery: ${error instanceof Error ? error.message : String(error)}
@@ -4173,7 +4326,7 @@ async function startWorker(options) {
       pendingCreatedBranchPublicationNotBefore
     );
     const initialDeferral = pendingBranchDeferral();
-    if (!workspaceConfigured || activeWorkspaceIncidentId || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN || automaticSyncInFlight || initialDeferral?.kind === "active_target") {
+    if (!workspaceConfigured || activeWorkspaceIncidentId || deferredWorkspaceConfiguration || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN || automaticSyncInFlight || initialDeferral?.kind === "active_target") {
       return;
     }
     if (workspaceAutomaticTimer) clearTimeout(workspaceAutomaticTimer);
@@ -4181,7 +4334,8 @@ async function startWorker(options) {
       () => {
         workspaceAutomaticTimer = void 0;
         const scheduledTrigger = pendingAutomaticTrigger;
-        if (!scheduledTrigger || !workspaceConfigured || activeWorkspaceIncidentId || currentWorkerSocket !== ws) return;
+        if (!scheduledTrigger || !workspaceConfigured || activeWorkspaceIncidentId || deferredWorkspaceConfiguration || currentWorkerSocket !== ws)
+          return;
         const currentDeferral = pendingBranchDeferral();
         if (currentDeferral?.kind === "active_target") return;
         if (currentDeferral?.kind === "creation_grace") {
@@ -4203,7 +4357,7 @@ async function startWorker(options) {
         }).finally(() => {
           automaticSyncInFlight = false;
           heartbeatBusyGrace = grantWorkerHeartbeatBusyGrace(lastServerHeartbeatAt, heartbeatBusyGrace);
-          if (pendingAutomaticTrigger && !activeWorkspaceIncidentId) {
+          if (pendingAutomaticTrigger && !activeWorkspaceIncidentId && !deferredWorkspaceConfiguration) {
             scheduleAutomaticWorkspaceSync(pendingAutomaticTrigger, WORKSPACE_GIT_QUIET_MS);
           }
         });
@@ -4219,6 +4373,11 @@ async function startWorker(options) {
   const targetMayMutateVisibleWorkspace = (target) => target.type === "project" || target.rootProfile === "visible_projects";
   const resolveMessageTarget = (target) => {
     if (!workspaceConfigured) throw new Error("Worker workspace configuration has not completed successfully");
+    if (!deferredWorkspaceTargetIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, target)) {
+      throw new Error(
+        `Worker workspace configuration is fenced for incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}; only canonical remediation commands are allowed`
+      );
+    }
     if (target.type === "project" && !readyProjectIds.has(target.projectId)) {
       throw new Error(`Project ${target.projectId} is not ready on this worker`);
     }
@@ -4232,7 +4391,26 @@ async function startWorker(options) {
       projectConfigById
     });
   };
-  const configureWorkerWorkspace = async (message) => {
+  const configureWorkerWorkspace = async (message, receiptGeneration) => {
+    const incidentDeferral = workspaceConfigurationIncidentDeferral({
+      requestedIncidentId: message.deferWorkspaceSyncForIncidentId,
+      activeIncidentId: activeWorkspaceIncidentId
+    });
+    if (incidentDeferral.error) {
+      workspaceConfigured = false;
+      return {
+        result: failedWorkspaceSyncResult(crypto.randomUUID(), { type: "connect" }, incidentDeferral.error),
+        pending: incidentDeferredProjectCheckouts(message.projects),
+        aheadOfOriginBranches: []
+      };
+    }
+    if (incidentDeferral.incidentId) {
+      workspaceConfigured = false;
+      deferredWorkspaceConfiguration = {
+        incidentId: incidentDeferral.incidentId,
+        serverRefreshExpected: message.deferWorkspaceSyncForIncidentId === incidentDeferral.incidentId
+      };
+    }
     const incomingCredentialGenerationFingerprint = credentialGenerationFingerprint({
       ...message,
       workerBaseUrl: baseUrl,
@@ -4243,6 +4421,22 @@ async function startWorker(options) {
       pendingFingerprintAtProcessStart: pendingCredentialGenerationIntentAtProcessStart?.fingerprint ?? null,
       incomingFingerprint: incomingCredentialGenerationFingerprint
     });
+    if (deferredCredentialTransitionMustWait({
+      incidentId: incidentDeferral.incidentId,
+      transitionPhase: credentialTransitionPhase,
+      canonicalRemediationActive: canonicalWorkspaceMutationIsActive(activeWorkspaceMutationTargets())
+    })) {
+      return {
+        result: failedWorkspaceSyncResult(
+          crypto.randomUUID(),
+          { type: "connect" },
+          new Error("Workspace credential rotation is deferred until the active canonical remediation command finishes")
+        ),
+        pending: incidentDeferredProjectCheckouts(message.projects),
+        aheadOfOriginBranches: [],
+        ...incidentDeferral.incidentId ? { deferredWorkspaceSyncForIncidentId: incidentDeferral.incidentId } : {}
+      };
+    }
     const credentialReapStatus = credentialReapContractStatus();
     const verifiedCredentialReapContractNow = credentialReapStatus === "verified_systemd";
     const credentialRestartIsContained = credentialGenerationRestartIsContained({
@@ -4356,6 +4550,12 @@ async function startWorker(options) {
     workspaceSyncRequestsInFlight += 1;
     try {
       return await workspaceSyncSingleFlight.runExclusive(async () => {
+        if (receiptGeneration !== workspaceConfigurationReceiptGeneration) {
+          throw new Error("Workspace configuration was superseded by a newer server generation");
+        }
+        if (!workspaceConfigurationIncidentSnapshotIsCurrent(incidentDeferral.incidentId, activeWorkspaceIncidentId)) {
+          throw new Error("Workspace configuration was superseded by a different active workspace incident");
+        }
         for (const project of message.projects) assertRepositoryTransitionState(project);
         const busyConfigurationChanges = busyProjectConfigurationChangeIds({
           currentProjects: [...projectConfigById.values()],
@@ -4377,10 +4577,12 @@ async function startWorker(options) {
         const preserveOnlyBranches = message.projects.flatMap(
           (project) => project.preserveOnlyBranches.map(({ branchId, branchName }) => ({ branchId, projectId: project.projectId, branchName }))
         );
-        projectWorkspaceState = projectWorkspaceStateStore.reconcile({
-          desiredProjects: message.projects,
-          preserveOnlyBranches
-        });
+        if (!incidentDeferral.incidentId) {
+          projectWorkspaceState = projectWorkspaceStateStore.reconcile({
+            desiredProjects: message.projects,
+            preserveOnlyBranches
+          });
+        }
         const stillPendingCreatedBranches = new Map(
           projectWorkspaceState.locallyPendingCreatedBranches.map((branch) => [
             pendingCreatedBranchKey(branch.projectId, branch.branchName),
@@ -4440,6 +4642,12 @@ async function startWorker(options) {
           void 0,
           credentialPublicationPreauthorized
         );
+        if (receiptGeneration !== workspaceConfigurationReceiptGeneration) {
+          throw new Error("Workspace configuration was superseded by a newer server generation");
+        }
+        if (!workspaceConfigurationIncidentSnapshotIsCurrent(incidentDeferral.incidentId, activeWorkspaceIncidentId)) {
+          throw new Error("Workspace configuration was superseded by a different active workspace incident");
+        }
         configuredCredentialGenerationFingerprint = incomingCredentialGenerationFingerprint;
         pendingCredentialGenerationIntentAtProcessStart = null;
         bootstrapCredentialGenerationFingerprintAtProcessStart = null;
@@ -4454,6 +4662,34 @@ async function startWorker(options) {
           branches: project.branches.filter(({ branchName }) => !pendingMirrorDeletes.has(projectBranchKey(project.projectId, branchName)))
         }));
         const nextProjectConfigById = new Map(effectiveProjects.map((project) => [project.projectId, project]));
+        if (incidentDeferral.incidentId) {
+          configureExistingWorkspaceGitForRemediation({
+            workspacePath: workspaceShadowRoot,
+            remoteUrl: message.workspaceRemoteUrl,
+            credentialHelper: nextWorkspaceCredentialHelper,
+            credentialUsername: workerCredentialUsername,
+            gitIdentity: message.gitIdentity
+          });
+          projectConfigById.clear();
+          for (const project of effectiveProjects) projectConfigById.set(project.projectId, project);
+          readyProjectIds.clear();
+          reconciledProjectConfigFingerprints.clear();
+          pendingCheckouts.clear();
+          const pending2 = incidentDeferredProjectCheckouts(message.projects);
+          for (const checkout of pending2) pendingCheckouts.set(projectBranchKey(checkout.projectId, checkout.branchName), checkout);
+          workspaceConfigured = activeWorkspaceIncidentId === incidentDeferral.incidentId;
+          return {
+            result: deferredIncidentWorkspaceConfigurationResult({
+              attemptId: crypto.randomUUID(),
+              workerLabel: label,
+              head: workspaceLocalHead(),
+              skippedMountIds: buildWorkspaceMounts().map(({ id }) => id)
+            }),
+            pending: pending2,
+            aheadOfOriginBranches: [],
+            deferredWorkspaceSyncForIncidentId: incidentDeferral.incidentId
+          };
+        }
         ensureWorkspaceGitClone({
           workspacePath: workspaceShadowRoot,
           remoteUrl: message.workspaceRemoteUrl,
@@ -4521,10 +4757,24 @@ async function startWorker(options) {
           { ignoreBusy: true }
         );
         ensureConfiguredProjects();
+        const configurationSyncAdmissionGeneration = workerAdmissionGeneration;
+        const assertConfigurationSyncStillAdmitted = () => {
+          if (receiptGeneration !== workspaceConfigurationReceiptGeneration || configurationSyncAdmissionGeneration !== workerAdmissionGeneration || !workspaceConfigurationIncidentSnapshotIsCurrent(incidentDeferral.incidentId, activeWorkspaceIncidentId) || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+            throw new Error("Workspace configuration synchronization admission changed while asynchronous work was in flight");
+          }
+        };
         const result = await performWorkspaceSync({
           attemptId: crypto.randomUUID(),
-          trigger: { type: "connect" }
+          trigger: { type: "connect" },
+          assertStillAdmitted: assertConfigurationSyncStillAdmitted
         });
+        assertConfigurationSyncStillAdmitted();
+        if (receiptGeneration !== workspaceConfigurationReceiptGeneration) {
+          throw new Error("Workspace configuration was superseded by a newer server generation");
+        }
+        if (!workspaceConfigurationIncidentSnapshotIsCurrent(incidentDeferral.incidentId, activeWorkspaceIncidentId)) {
+          throw new Error("Workspace configuration was superseded by a different active workspace incident");
+        }
         const publishedHead = result.publishedHead ?? result.localHead ?? result.startingHead;
         if (publishedHead && ["no_change", "published", "updated", "conflict_reset", "reset"].includes(result.outcome)) {
           const activeMountIds = new Set(result.activeMountIds ?? []);
@@ -4541,6 +4791,11 @@ async function startWorker(options) {
             });
           }
         }
+        if (deferredWorkspaceConfigurationRefreshTimer) {
+          clearTimeout(deferredWorkspaceConfigurationRefreshTimer);
+          deferredWorkspaceConfigurationRefreshTimer = void 0;
+        }
+        deferredWorkspaceConfiguration = null;
         workspaceConfigured = true;
         const pending = [...pendingCheckouts.values()].sort(
           (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
@@ -4548,6 +4803,13 @@ async function startWorker(options) {
         return { result, pending, aheadOfOriginBranches: collectAheadOfOriginBranches() };
       });
     } catch (error) {
+      if (receiptGeneration !== workspaceConfigurationReceiptGeneration) {
+        return {
+          result: failedWorkspaceSyncResult(crypto.randomUUID(), { type: "connect" }, error),
+          pending: incidentDeferredProjectCheckouts(message.projects),
+          aheadOfOriginBranches: []
+        };
+      }
       if (error instanceof RegistryAuthConfigurationError) {
         workspaceConfigured = false;
         githubCredential = null;
@@ -4602,7 +4864,7 @@ async function startWorker(options) {
       workspaceAutomaticTimer = void 0;
     }
     void (async () => {
-      if (workspaceConfigured && !activeWorkspaceIncidentId) {
+      if (workspaceConfigured && !activeWorkspaceIncidentId && !deferredWorkspaceConfiguration) {
         await runWorkspaceSync({
           trigger: { type: "manual", detail: "graceful worker shutdown" }
         });
@@ -4651,7 +4913,9 @@ async function startWorker(options) {
           updateClis: true,
           browserPortForwarding: true,
           execStdinV1: true,
-          ptyEnvFilesV1: true
+          ptyEnvFilesV1: true,
+          workspaceRemediationAncestorGuardV1: true,
+          workspaceIncidentConfigDeferralV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -4687,26 +4951,35 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "workspace_config") {
+        const receiptGeneration = ++workspaceConfigurationReceiptGeneration;
+        const refreshesDeferredConfiguration = deferredWorkspaceConfiguration !== null && activeWorkspaceIncidentId === null && message.deferWorkspaceSyncForIncidentId === void 0;
         advanceWorkerAdmissionGeneration();
-        const configured = await configureWorkerWorkspace(message);
+        const configured = await configureWorkerWorkspace(message, receiptGeneration);
         sendWorkerMessageFromCurrentSource(ws, {
           type: "workspace_configured",
           requestId: message.requestId,
           result: configured.result,
           pendingCheckouts: configured.pending,
-          aheadOfOriginBranches: configured.aheadOfOriginBranches
+          aheadOfOriginBranches: configured.aheadOfOriginBranches,
+          ...configured.deferredWorkspaceSyncForIncidentId ? { deferredWorkspaceSyncForIncidentId: configured.deferredWorkspaceSyncForIncidentId } : {}
         });
         process.stdout.write(
           `[r5d-worker] workspace configured: ${message.projects.length} project(s), ${configured.pending.length} pending checkout(s)
 `
         );
+        if (refreshesDeferredConfiguration && configured.result.outcome === "failed" && deferredWorkspaceConfiguration !== null && currentWorkerSocket === ws) {
+          workspaceConfigured = false;
+          advanceWorkerAdmissionGeneration();
+          ws.close(1012, "Deferred workspace configuration refresh failed");
+          return;
+        }
         if (!workspacePeriodicTimer) {
           workspacePeriodicTimer = setInterval(() => {
             scheduleAutomaticWorkspaceSync({ type: "periodic", detail: "periodic workspace reconciliation" }, 0);
           }, WORKSPACE_GIT_PERIODIC_MS);
           workspacePeriodicTimer.unref();
         }
-        if (pendingAutomaticTrigger && !activeWorkspaceIncidentId) {
+        if (pendingAutomaticTrigger && !activeWorkspaceIncidentId && !deferredWorkspaceConfiguration) {
           scheduleAutomaticWorkspaceSync(pendingAutomaticTrigger, 0);
         }
         return;
@@ -4718,11 +4991,20 @@ async function startWorker(options) {
           trigger: message.trigger,
           confirmedLargeDiff: message.confirmedLargeDiff,
           confirmationReason: message.confirmationReason,
-          resetToCanonical: message.resetToCanonical
+          resetToCanonical: message.resetToCanonical,
+          requiredAncestorHeads: message.requiredAncestorHeads
         });
         return;
       }
       if (message.type === "create_project_branch") {
+        if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+          sendWorkerMessage(ws, {
+            type: "operation_result",
+            requestId: message.requestId,
+            error: `Project operations are deferred for workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+          });
+          return;
+        }
         try {
           const pendingBranch = {
             branchId: message.branchId,
@@ -4730,6 +5012,11 @@ async function startWorker(options) {
             branchName: message.targetBranch
           };
           const created = await workspaceSyncSingleFlight.runMutation(() => {
+            if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+              throw new Error(
+                `Project branch creation was fenced while queued by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+              );
+            }
             const project = projectConfigById.get(message.projectId);
             if (!project) throw new Error(`Project ${message.projectId} is missing from the worker workspace configuration`);
             assertRepositoryExecutionEnabled(project);
@@ -4813,9 +5100,22 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "delete_project_branch") {
+        if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+          sendWorkerMessage(ws, {
+            type: "operation_result",
+            requestId: message.requestId,
+            error: `Project operations are deferred for workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+          });
+          return;
+        }
         try {
           const deletionKey = projectBranchKey(message.projectId, message.branchName);
           const deletionNeedsSync = await workspaceSyncSingleFlight.runMutation(() => {
+            if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+              throw new Error(
+                `Project branch deletion was fenced while queued by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+              );
+            }
             const project = projectConfigById.get(message.projectId);
             if (!project) throw new Error(`Project ${message.projectId} is missing from the worker workspace configuration`);
             assertRepositoryExecutionEnabled(project);
@@ -4915,8 +5215,38 @@ async function startWorker(options) {
       }
       if (message.type === "workspace_incident_updated") {
         const previousIncidentId = activeWorkspaceIncidentId;
-        activeWorkspaceIncidentId = applyWorkspaceIncidentUpdate(activeWorkspaceIncidentId, message);
+        const nextIncidentId = applyWorkspaceIncidentUpdate(activeWorkspaceIncidentId, message);
+        if (nextIncidentId !== previousIncidentId) advanceWorkerAdmissionGeneration();
+        activeWorkspaceIncidentId = nextIncidentId;
         if (previousIncidentId && !activeWorkspaceIncidentId && (message.status === "resolved" || message.status === "confirmed" || message.status === "reset")) {
+          const disposition = workspaceIncidentTerminalClearDisposition({
+            deferredConfiguration: deferredWorkspaceConfiguration,
+            clearedIncidentId: previousIncidentId
+          });
+          if (disposition !== "ordinary_resume") {
+            pendingAutomaticTrigger ??= { type: "periodic", detail: "resume after workspace incident" };
+            workspaceConfigured = false;
+            advanceWorkerAdmissionGeneration();
+            if (disposition === "reconnect_for_refresh") {
+              ws.close(1012, "Refreshing deferred workspace configuration");
+            } else {
+              if (deferredWorkspaceConfigurationRefreshTimer) clearTimeout(deferredWorkspaceConfigurationRefreshTimer);
+              const deferredIncidentId = deferredWorkspaceConfiguration?.incidentId;
+              deferredWorkspaceConfigurationRefreshTimer = setTimeout(() => {
+                deferredWorkspaceConfigurationRefreshTimer = void 0;
+                if (!deferredIncidentId || !deferredWorkspaceRefreshWatchdogIsCurrent({
+                  capturedIncidentId: deferredIncidentId,
+                  deferredConfiguration: deferredWorkspaceConfiguration,
+                  activeIncidentId: activeWorkspaceIncidentId
+                }) || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+                  return;
+                }
+                ws.close(1012, "Timed out waiting for deferred workspace configuration refresh");
+              }, WORKSPACE_INCIDENT_CONFIG_REFRESH_TIMEOUT_MS);
+              deferredWorkspaceConfigurationRefreshTimer.unref();
+            }
+            return;
+          }
           scheduleAutomaticWorkspaceSync(pendingAutomaticTrigger ?? { type: "periodic", detail: "resume after workspace incident" }, 0);
         }
         return;
@@ -5020,6 +5350,12 @@ async function startWorker(options) {
           sendAck({ error: `Process run ${message.runId} is not active on this worker` });
           return;
         }
+        if (!deferredWorkspaceTargetIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, active.target)) {
+          sendAck({
+            error: `Process input is deferred for workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}`
+          });
+          return;
+        }
         if (!active.interactive || !active.stdin) {
           sendAck({
             error: `Process run ${message.runId} has no open stdin. Start a new shell command with "interactive": true to write to its stdin.`
@@ -5065,6 +5401,15 @@ async function startWorker(options) {
           });
           return;
         }
+        if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+          sendWorkerMessage(ws, {
+            type: "pty_error",
+            requestId: message.requestId,
+            ptyId: message.ptyId,
+            error: `Shells are deferred for workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+          });
+          return;
+        }
         await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
           workspaceSyncPriorityPtyTargets.set(message.ptyId, message.target);
           if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
@@ -5073,6 +5418,11 @@ async function startWorker(options) {
         let mutationLeaseTransferred = false;
         try {
           releaseWorkspaceMutation = await acquireWorkspaceCommandMutation(message.target, workspaceSyncSingleFlight);
+          if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+            throw new Error(
+              `Shell opening was fenced while queued by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+            );
+          }
           const resolvedTarget = resolveMessageTarget(message.target);
           process.stdout.write(`[r5d-worker] pty ${message.ptyId}: ${describeWorkerSessionTarget(message.target)}
 `);
@@ -5105,6 +5455,14 @@ async function startWorker(options) {
       }
       if (message.type === "pty_input") {
         const activePty = activePtys.get(message.ptyId);
+        if (activePty && workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+          sendWorkerMessage(ws, {
+            type: "pty_error",
+            ptyId: message.ptyId,
+            error: `Shell input is deferred for workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId ?? "unknown"}`
+          });
+          return;
+        }
         if (activePty && targetMayMutateVisibleWorkspace(activePty.target)) {
           markWorkspaceDirty({ type: "shell_inline", detail: `pty ${message.ptyId}` }, false, activePty.target);
         }
@@ -5134,6 +5492,17 @@ async function startWorker(options) {
           });
           return;
         }
+        if (!workspaceCommandTransportIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, "exec")) {
+          sendWorkerMessage(ws, {
+            type: "exec_result",
+            requestId: message.requestId,
+            stdout: "",
+            stderr: "",
+            exitCode: 1,
+            error: `One-shot commands are deferred for workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+          });
+          return;
+        }
         let result;
         let targetReserved = false;
         const hasWorkspaceEffect = workerCommandHasWorkspaceEffect(message);
@@ -5146,6 +5515,11 @@ async function startWorker(options) {
             });
           }
           const runCommand = async () => {
+            if (!workspaceCommandTransportIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, "exec")) {
+              throw new Error(
+                `One-shot command was fenced while queued by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+              );
+            }
             const resolvedTarget = resolveMessageTarget(message.target);
             process.stdout.write(`[r5d-worker] exec ${message.runId}: ${message.argv.join(" ")}
 `);
@@ -5156,7 +5530,14 @@ async function startWorker(options) {
               token,
               artifactRoot,
               planRoot,
-              assertAdmission: assertMessageAdmission
+              assertAdmission: () => {
+                if (!workspaceCommandTransportIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, "exec")) {
+                  throw new Error(
+                    `One-shot command was fenced before spawn by workspace incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}`
+                  );
+                }
+                assertMessageAdmission();
+              }
             });
           };
           result = await runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
@@ -5256,6 +5637,14 @@ 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" || message.type === "code_list" || message.type === "code_read") {
+        if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
+          sendWorkerMessage(ws, {
+            type: "operation_result",
+            requestId: message.requestId,
+            error: `Workspace operations are deferred for incident ${deferredWorkspaceConfiguration?.incidentId ?? activeWorkspaceIncidentId}; use a canonical remediation shell`
+          });
+          return;
+        }
         const reservesVisibleWorkspace = targetMayMutateVisibleWorkspace(message.target);
         const mutatesVisibleWorkspace = (message.type === "write" || message.type === "edit") && targetMayMutateVisibleWorkspace(message.target);
         if (reservesVisibleWorkspace) {
@@ -5274,7 +5663,8 @@ async function startWorker(options) {
               baseUrl,
               token,
               artifactRoot,
-              planRoot
+              planRoot,
+              assertAdmission: assertMessageAdmission
             });
           });
           ws.send(
@@ -5304,7 +5694,7 @@ async function startWorker(options) {
         } finally {
           if (reservesVisibleWorkspace) {
             workspaceSyncPriorityOperationTargets.delete(message.requestId);
-            if (pendingAutomaticTrigger && !activeWorkspaceIncidentId) {
+            if (pendingAutomaticTrigger && !activeWorkspaceIncidentId && !deferredWorkspaceConfiguration) {
               scheduleAutomaticWorkspaceSync(pendingAutomaticTrigger, dirtyTrigger ? WORKSPACE_GIT_QUIET_MS : 0);
             }
           }
@@ -5340,6 +5730,10 @@ async function startWorker(options) {
       clearInterval(workspacePeriodicTimer);
       workspacePeriodicTimer = void 0;
     }
+    if (deferredWorkspaceConfigurationRefreshTimer) {
+      clearTimeout(deferredWorkspaceConfigurationRefreshTimer);
+      deferredWorkspaceConfigurationRefreshTimer = void 0;
+    }
     if (terminalReplayTimer) {
       clearInterval(terminalReplayTimer);
       terminalReplayTimer = void 0;