@ricsam/r5d-worker 0.0.81 → 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,11 @@ 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";
+const PTY_TMP_PATH_PREFIX = "r5d-worker-tmp://";
 const activeProcesses = /* @__PURE__ */ new Map();
 const credentialBearingProcessGroups = /* @__PURE__ */ new Map();
 const credentialBearingProcessGroupTargets = /* @__PURE__ */ new Map();
@@ -156,6 +163,107 @@ function assertWorkerChildAdmission(input) {
     throw new StaleWorkerAdmissionError();
   }
 }
+function pathIsInsideRoot(rootPath, candidatePath) {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+function resolvePtyEnvFilePath(requestedPath, temporaryRoot = os.tmpdir()) {
+  const canonicalTemporaryRoot = fs.realpathSync.native(temporaryRoot);
+  if (requestedPath.startsWith(PTY_TMP_PATH_PREFIX)) {
+    const filename = requestedPath.slice(PTY_TMP_PATH_PREFIX.length);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(filename)) {
+      throw new Error("PTY environment file temporary token must contain one safe filename");
+    }
+    return path.join(canonicalTemporaryRoot, filename);
+  }
+  if (!path.isAbsolute(requestedPath)) {
+    throw new Error(`PTY environment file path must be absolute or use ${PTY_TMP_PATH_PREFIX}`);
+  }
+  const resolvedPath = path.resolve(requestedPath);
+  const canonicalParent = fs.realpathSync.native(path.dirname(resolvedPath));
+  const canonicalPath = path.join(canonicalParent, path.basename(resolvedPath));
+  if (!pathIsInsideRoot(canonicalTemporaryRoot, canonicalPath) || canonicalPath === canonicalTemporaryRoot) {
+    throw new Error(`PTY environment file path must be inside ${canonicalTemporaryRoot}`);
+  }
+  return canonicalPath;
+}
+function removePtyEnvFiles(paths) {
+  for (const filePath of paths) {
+    try {
+      fs.rmSync(filePath, { force: true });
+    } catch (error) {
+      process.stderr.write(
+        `[r5d-worker] failed to remove PTY environment file ${filePath}: ${error instanceof Error ? error.message : String(error)}
+`
+      );
+    }
+  }
+}
+function stagePtyEnvFiles(envFiles, temporaryRoot = os.tmpdir()) {
+  const staged = { paths: [], resolvedByRequestedPath: /* @__PURE__ */ new Map() };
+  try {
+    for (const envFile of envFiles ?? []) {
+      if (!envFile || typeof envFile.path !== "string" || typeof envFile.content !== "string") {
+        throw new Error("PTY environment files require string path and content values");
+      }
+      if (envFile.mode !== void 0 && envFile.mode !== 384) {
+        throw new Error("PTY environment files must use mode 0600");
+      }
+      const resolvedPath = resolvePtyEnvFilePath(envFile.path, temporaryRoot);
+      if (staged.resolvedByRequestedPath.has(envFile.path) || staged.paths.includes(resolvedPath)) {
+        throw new Error(`Duplicate PTY environment file path: ${envFile.path}`);
+      }
+      const descriptor = fs.openSync(
+        resolvedPath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0),
+        384
+      );
+      staged.paths.push(resolvedPath);
+      staged.resolvedByRequestedPath.set(envFile.path, resolvedPath);
+      try {
+        fs.writeFileSync(descriptor, envFile.content, "utf8");
+        fs.fchmodSync(descriptor, 384);
+        fs.fsyncSync(descriptor);
+      } finally {
+        fs.closeSync(descriptor);
+      }
+    }
+    return staged;
+  } catch (error) {
+    removePtyEnvFiles(staged.paths);
+    throw error;
+  }
+}
+function resolvePtyEnvFileReferences(env, staged) {
+  return Object.fromEntries(Object.entries(env).map(([name, value]) => [name, staged.resolvedByRequestedPath.get(value) ?? value]));
+}
+function workerCommandHasWorkspaceEffect(message) {
+  return message.workspaceEffect !== "none";
+}
+function workerPtyIsWorkspaceBusy(pty, now = Date.now(), foregroundIdleEnabled = PTY_FOREGROUND_IDLE_ENABLED) {
+  return !foregroundIdleEnabled || pty.foregroundBusy || now - pty.lastInputAt < PTY_INPUT_BUSY_GRACE_MS;
+}
+function parseLinuxPtyForegroundBusy(stat) {
+  const commandEnd = stat.lastIndexOf(")");
+  if (commandEnd < 0) return null;
+  const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+  const processGroup = Number(fields[2]);
+  const foregroundProcessGroup = Number(fields[5]);
+  if (!Number.isSafeInteger(processGroup) || processGroup <= 0 || !Number.isSafeInteger(foregroundProcessGroup)) return null;
+  return foregroundProcessGroup !== processGroup;
+}
+const workerPtyTestHarness = {
+  temporaryPathPrefix: PTY_TMP_PATH_PREFIX,
+  inputBusyGraceMs: PTY_INPUT_BUSY_GRACE_MS,
+  resolveEnvFilePath: resolvePtyEnvFilePath,
+  stageEnvFiles: stagePtyEnvFiles,
+  removeEnvFiles: removePtyEnvFiles,
+  resolveEnvFileReferences: resolvePtyEnvFileReferences,
+  commandHasWorkspaceEffect: workerCommandHasWorkspaceEffect,
+  canonicalSyncTerminalHead,
+  ptyIsWorkspaceBusy: workerPtyIsWorkspaceBusy,
+  parseLinuxForegroundBusy: parseLinuxPtyForegroundBusy
+};
 function defaultConfigPath() {
   return path.join(os.homedir(), ".config", "r5d", "r5dctl", "config.json");
 }
@@ -1414,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();
@@ -1446,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) {
@@ -1597,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}`;
 }
@@ -1901,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);
   });
 }
@@ -1918,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);
   });
 }
@@ -2337,7 +2552,9 @@ async function executeCommand(input) {
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
-    credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    if (workerCommandHasWorkspaceEffect(input.message)) {
+      credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    }
     activeProcesses.set(input.message.runId, {
       process: subprocess,
       target: input.resolvedTarget.target,
@@ -2348,7 +2565,8 @@ async function executeCommand(input) {
       argv: input.message.argv,
       command: input.message.argv.join(" "),
       cwd,
-      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
     });
     if (input.message.timeoutMs) {
       timeout = setTimeout(() => {
@@ -2434,7 +2652,9 @@ async function executeStreamingCommand(input) {
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
-    credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    if (workerCommandHasWorkspaceEffect(input.message)) {
+      credentialBearingProcessGroupTargets.set(subprocess.pid, input.resolvedTarget.target);
+    }
     activeProcesses.set(input.message.runId, {
       process: subprocess,
       target: input.resolvedTarget.target,
@@ -2447,7 +2667,8 @@ async function executeStreamingCommand(input) {
       command: input.message.command,
       cwd,
       startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      ...interactive ? { interactive: true, stdin: subprocess.stdin } : {}
+      ...interactive ? { interactive: true, stdin: subprocess.stdin } : {},
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
     });
     started = true;
     sendWorkerMessage(input.ws, {
@@ -2489,12 +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 } : {}
+      ...timedOut ? { timedOut: true } : {},
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+      ...canonicalWorkspaceHead ? { canonicalWorkspaceHead } : {}
     };
     pendingProcessTerminals.set(input.message.runId, terminal);
     sendWorkerMessage(input.ws, terminal);
@@ -2502,11 +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
+        durationMs: Date.now() - startedAt,
+        ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+        ...canonicalWorkspaceHead ? { canonicalWorkspaceHead } : {}
       };
       pendingProcessTerminals.set(input.message.runId, terminal);
       sendWorkerMessage(input.ws, terminal);
@@ -2587,7 +2814,8 @@ function buildActiveProcessReports() {
     command: active.command,
     ...active.cwd ? { cwd: active.cwd } : {},
     startedAt: active.startedAt,
-    ...active.interactive ? { interactive: true } : {}
+    ...active.interactive ? { interactive: true } : {},
+    ...active.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
   }));
 }
 function sendActiveProcessReport(ws) {
@@ -2599,8 +2827,13 @@ function sendActiveProcessReport(ws) {
 const PTY_BRIDGE_SCRIPT = String.raw`
 const readline = require("node:readline");
 const nodePty = require("node-pty");
+const fs = require("node:fs");
+const { execFile } = require("node:child_process");
 
 let ptyProcess = null;
+let foregroundTimer = null;
+let foregroundPollInFlight = false;
+let lastForegroundBusy = null;
 
 function send(message, callback) {
   process.stdout.write(JSON.stringify(message) + "\n", callback);
@@ -2610,6 +2843,46 @@ function decode(data) {
   return Buffer.from(data, "base64").toString("utf8");
 }
 
+function emitForeground(busy) {
+  if (busy === lastForegroundBusy) return;
+  lastForegroundBusy = busy;
+  send({ type: "foreground", busy });
+}
+
+function linuxForegroundBusy(pid) {
+  const stat = fs.readFileSync("/proc/" + pid + "/stat", "utf8");
+  const commandEnd = stat.lastIndexOf(")");
+  if (commandEnd < 0) throw new Error("invalid /proc stat");
+  const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+  const processGroup = Number(fields[2]);
+  const foregroundProcessGroup = Number(fields[5]);
+  if (!Number.isSafeInteger(processGroup) || processGroup <= 0 || !Number.isSafeInteger(foregroundProcessGroup)) {
+    throw new Error("invalid process group fields");
+  }
+  return foregroundProcessGroup !== processGroup;
+}
+
+function pollForeground() {
+  if (!ptyProcess || !Number.isSafeInteger(ptyProcess.pid) || ptyProcess.pid <= 0) return;
+  if (process.platform === "linux") {
+    try {
+      emitForeground(linuxForegroundBusy(ptyProcess.pid));
+    } catch {
+      emitForeground(true);
+    }
+    return;
+  }
+  if (process.platform !== "darwin" || foregroundPollInFlight) return;
+  foregroundPollInFlight = true;
+  const pid = ptyProcess.pid;
+  execFile("/bin/ps", ["-o", "tpgid=", "-p", String(pid)], (error, stdout) => {
+    foregroundPollInFlight = false;
+    if (!ptyProcess || ptyProcess.pid !== pid) return;
+    const foregroundProcessGroup = Number(String(stdout).trim());
+    emitForeground(Boolean(error) || !Number.isSafeInteger(foregroundProcessGroup) || foregroundProcessGroup !== pid);
+  });
+}
+
 const rl = readline.createInterface({ input: process.stdin });
 
 rl.on("line", (line) => {
@@ -2628,9 +2901,14 @@ rl.on("line", (line) => {
         send({ type: "output", data: Buffer.from(data, "utf8").toString("base64") });
       });
       ptyProcess.onExit((event) => {
+        if (foregroundTimer) clearInterval(foregroundTimer);
+        foregroundTimer = null;
         send({ type: "exit", exitCode: event.exitCode, signal: event.signal }, () => process.exit(0));
       });
-      send({ type: "opened" });
+      send({ type: "opened", pid: ptyProcess.pid });
+      pollForeground();
+      foregroundTimer = setInterval(pollForeground, ${PTY_FOREGROUND_POLL_MS});
+      foregroundTimer.unref();
       return;
     }
 
@@ -2723,7 +3001,11 @@ function createNodePtyBridge(options) {
   };
   const handleEvent = (event) => {
     if (event.type === "opened") {
-      options.onOpened();
+      options.onOpened(event.pid);
+      return;
+    }
+    if (event.type === "foreground") {
+      options.onForeground(event.busy);
       return;
     }
     if (event.type === "output") {
@@ -2804,6 +3086,9 @@ function createNodePtyBridge(options) {
     }
   };
 }
+const workerPtyBridgeTestHarness = {
+  create: createNodePtyBridge
+};
 function resolveHostShell(command, platform = process.platform) {
   if (platform === "win32") {
     const file2 = process.env.COMSPEC || "powershell.exe";
@@ -2839,64 +3124,90 @@ async function openPty(input) {
     }
   });
   input.assertAdmission();
-  const ptyProcess = createNodePtyBridge({
-    file: shell.file,
-    args: shell.args,
-    ptyOptions: {
-      name: "xterm-256color",
-      cols: Math.max(1, Math.min(Math.floor(input.message.cols || 80), 500)),
-      rows: Math.max(1, Math.min(Math.floor(input.message.rows || 24), 500)),
-      cwd: input.resolvedTarget.rootPath,
-      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, planProcessEnv, targetProcessEnv, shell.env ?? {}])
-    },
-    onOpened: () => {
-      sendWorkerMessage(input.ws, {
-        type: "pty_opened",
-        requestId: input.message.requestId,
-        ptyId: input.message.ptyId
-      });
-    },
-    onOutput: (data) => {
-      outputCoalescer.push(data);
-    },
-    onExit: (event) => {
-      outputCoalescer.flush();
-      input.releaseWorkspaceMutation?.();
-      activePtys.delete(input.message.ptyId);
-      input.onTerminal?.();
-      sendWorkerMessage(input.ws, {
-        type: "pty_exit",
-        ptyId: input.message.ptyId,
-        exitCode: event.exitCode,
-        signal: event.signal
-      });
-    },
-    onError: (error) => {
-      outputCoalescer.flush();
-      input.releaseWorkspaceMutation?.();
-      activePtys.delete(input.message.ptyId);
-      input.onTerminal?.();
-      sendWorkerMessage(input.ws, {
-        type: "pty_error",
-        requestId: input.message.requestId,
-        ptyId: input.message.ptyId,
-        error: error.message
-      });
-    },
-    onTerminationError: (error) => {
-      sendWorkerMessage(input.ws, {
-        type: "pty_error",
-        requestId: input.message.requestId,
-        ptyId: input.message.ptyId,
-        error: error.message
-      });
-    }
-  });
-  activePtys.set(input.message.ptyId, {
-    ...ptyProcess,
-    target: input.resolvedTarget.target,
-    ...input.releaseWorkspaceMutation ? { releaseWorkspaceMutation: input.releaseWorkspaceMutation } : {}
-  });
+  const stagedEnvFiles = stagePtyEnvFiles(input.message.envFiles);
+  let envFilesRemoved = false;
+  const cleanupEnvFiles = () => {
+    if (envFilesRemoved) return;
+    envFilesRemoved = true;
+    removePtyEnvFiles(stagedEnvFiles.paths);
+  };
+  try {
+    const ptyProcess = createNodePtyBridge({
+      file: shell.file,
+      args: shell.args,
+      ptyOptions: {
+        name: "xterm-256color",
+        cols: Math.max(1, Math.min(Math.floor(input.message.cols || 80), 500)),
+        rows: Math.max(1, Math.min(Math.floor(input.message.rows || 24), 500)),
+        cwd: input.resolvedTarget.rootPath,
+        env: workerChildProcessEnvironment([
+          githubProcessEnv(),
+          resolvePtyEnvFileReferences(input.message.env ?? {}, stagedEnvFiles),
+          planProcessEnv,
+          targetProcessEnv,
+          shell.env ?? {}
+        ])
+      },
+      onOpened: () => {
+        sendWorkerMessage(input.ws, {
+          type: "pty_opened",
+          requestId: input.message.requestId,
+          ptyId: input.message.ptyId
+        });
+      },
+      onForeground: (busy) => {
+        const activePty = activePtys.get(input.message.ptyId);
+        if (activePty && (busy || input.message.command === void 0)) activePty.foregroundBusy = busy;
+      },
+      onOutput: (data) => {
+        outputCoalescer.push(data);
+      },
+      onExit: (event) => {
+        outputCoalescer.flush();
+        input.releaseWorkspaceMutation?.();
+        activePtys.delete(input.message.ptyId);
+        cleanupEnvFiles();
+        input.onTerminal?.();
+        sendWorkerMessage(input.ws, {
+          type: "pty_exit",
+          ptyId: input.message.ptyId,
+          exitCode: event.exitCode,
+          signal: event.signal
+        });
+      },
+      onError: (error) => {
+        outputCoalescer.flush();
+        input.releaseWorkspaceMutation?.();
+        activePtys.delete(input.message.ptyId);
+        cleanupEnvFiles();
+        input.onTerminal?.();
+        sendWorkerMessage(input.ws, {
+          type: "pty_error",
+          requestId: input.message.requestId,
+          ptyId: input.message.ptyId,
+          error: error.message
+        });
+      },
+      onTerminationError: (error) => {
+        sendWorkerMessage(input.ws, {
+          type: "pty_error",
+          requestId: input.message.requestId,
+          ptyId: input.message.ptyId,
+          error: error.message
+        });
+      }
+    });
+    activePtys.set(input.message.ptyId, {
+      ...ptyProcess,
+      target: input.resolvedTarget.target,
+      foregroundBusy: true,
+      lastInputAt: 0,
+      ...input.releaseWorkspaceMutation ? { releaseWorkspaceMutation: input.releaseWorkspaceMutation } : {}
+    });
+  } catch (error) {
+    cleanupEnvFiles();
+    throw error;
+  }
 }
 function writePty(ws, message) {
   const ptyProcess = activePtys.get(message.ptyId);
@@ -2908,6 +3219,7 @@ function writePty(ws, message) {
     });
     return;
   }
+  ptyProcess.lastInputAt = Date.now();
   ptyProcess.write(message.data);
 }
 function resizePty(message) {
@@ -3076,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;
@@ -3345,13 +3660,24 @@ async function startWorker(options) {
     });
   };
   const activeWorkspaceMutationTargets = () => [
-    ...Array.from(activeProcesses.values(), ({ target }) => target),
+    ...Array.from(activeProcesses.values()).filter(workerCommandHasWorkspaceEffect).map(({ target }) => target),
     ...credentialBearingProcessGroupTargets.values(),
     ...workspaceSyncPriorityProcessTargets.values(),
     ...workspaceSyncPriorityOperationTargets.values(),
-    ...Array.from(activePtys.values(), ({ target }) => target),
+    ...Array.from(activePtys.values()).filter((pty) => workerPtyIsWorkspaceBusy(pty)).map(({ target }) => target),
     ...workspaceSyncPriorityPtyTargets.values()
   ];
+  let visibleWorkspaceMutationEpoch = 0;
+  const projectWorkspaceMutationEpochs = /* @__PURE__ */ new Map();
+  const recordVisibleWorkspaceMutation = (target) => {
+    if (target.type === "workspace") {
+      if (target.rootProfile === "visible_projects") visibleWorkspaceMutationEpoch += 1;
+      return;
+    }
+    const key = projectBranchKey(target.projectId, target.branchName);
+    projectWorkspaceMutationEpochs.set(key, (projectWorkspaceMutationEpochs.get(key) ?? 0) + 1);
+  };
+  const projectWorkspaceMutationToken = (projectId, branchName) => `${visibleWorkspaceMutationEpoch}:${projectWorkspaceMutationEpochs.get(projectBranchKey(projectId, branchName)) ?? 0}`;
   const canonicalWorkspaceMutationIsActive = (targets) => targets.some((target) => target.type === "workspace" && target.rootProfile === "canonical_sync");
   const projectBranchMountActivityBusy = (projectId, branchName, branchPath) => {
     const activeTargets = activeWorkspaceMutationTargets();
@@ -3388,6 +3714,7 @@ async function startWorker(options) {
           preserveLocalOnInitialOuterAbsence: creatorLocalIncarnation,
           preserveLocalOnHydrationBasisChange: preservesCheckoutPathMove,
           busy: () => projectBranchMountBusy(project.projectId, branch.branchName, branchPath),
+          mutationToken: () => projectWorkspaceMutationToken(project.projectId, branch.branchName),
           busyForRecovery: () => projectBranchMountActivityBusy(project.projectId, branch.branchName, branchPath)
         });
         mounts.push({
@@ -3401,6 +3728,7 @@ async function startWorker(options) {
           preserveLocalOnInitialOuterAbsence: creatorLocalIncarnation,
           preserveLocalOnHydrationBasisChange: preservesCheckoutPathMove,
           busy: () => projectBranchMountBusy(project.projectId, branch.branchName, branchPath),
+          mutationToken: () => projectWorkspaceMutationToken(project.projectId, branch.branchName),
           busyForRecovery: () => projectBranchMountActivityBusy(project.projectId, branch.branchName, branchPath)
         });
       }
@@ -3421,6 +3749,7 @@ async function startWorker(options) {
         const activeTargets = activeWorkspaceMutationTargets();
         return canonicalWorkspaceMutationIsActive(activeTargets) || hasActiveVisibleProjectsWorkspaceTarget(activeTargets);
       },
+      mutationToken: () => String(visibleWorkspaceMutationEpoch),
       busyForRecovery: () => {
         const activeTargets = activeWorkspaceMutationTargets();
         return canonicalWorkspaceMutationIsActive(activeTargets) || hasActiveVisibleProjectsWorkspaceTarget(activeTargets);
@@ -3778,6 +4107,8 @@ async function startWorker(options) {
       localChangesDiscarded: false,
       ...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 } : {}
     };
   };
@@ -3844,10 +4175,7 @@ async function startWorker(options) {
       };
     }
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
-    const ordinaryCycleHasBusyLiveMount = mounts.some(
-      (mount) => !(mount.deleteWhenSourceMissing && !fs.existsSync(mount.sourcePath)) && mount.busy?.()
-    );
-    const observedProjectHeads = outerRemediation || ordinaryCycleHasBusyLiveMount ? [] : observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
+    const observedProjectHeads = outerRemediation ? [] : observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false });
     const inboundMoveMountIds = new Set(
       observedProjectHeads.flatMap(
         ({ projectId, observations }) => observations.filter(({ shouldMove }) => shouldMove).map(({ branchName }) => projectMountId(projectId, branchName))
@@ -3866,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);
     }
@@ -3892,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");
@@ -3906,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)}
@@ -3964,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);
@@ -3972,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") {
@@ -3994,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);
           }
         });
@@ -4003,12 +4366,18 @@ async function startWorker(options) {
     );
     workspaceAutomaticTimer.unref();
   };
-  const markWorkspaceDirty = (trigger, force = false) => {
+  const markWorkspaceDirty = (trigger, force = false, target) => {
+    if (target) recordVisibleWorkspaceMutation(target);
     scheduleAutomaticWorkspaceSync(trigger, force ? 0 : WORKSPACE_GIT_QUIET_MS);
   };
   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`);
     }
@@ -4022,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,
@@ -4033,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({
@@ -4146,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()],
@@ -4167,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),
@@ -4230,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;
@@ -4244,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,
@@ -4264,7 +4710,7 @@ async function startWorker(options) {
           sourcePath: recoverySourceOverrides.get(mount.id) ?? mount.sourcePath,
           busy: mount.busyForRecovery ?? mount.busy
         }));
-        recoverWorkspaceGitHydration(workspaceShadowRoot, recoveryMounts);
+        recoverWorkspaceGitHydration(workspaceShadowRoot, recoveryMounts, { preserveStaleBases: true });
         for (const project of message.projects) {
           for (const { branchName } of project.preserveOnlyBranches) {
             if (stillPendingCreatedBranches.has(pendingCreatedBranchKey(project.projectId, branchName))) {
@@ -4311,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 ?? []);
@@ -4331,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)
@@ -4338,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;
@@ -4392,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" }
         });
@@ -4440,7 +4912,10 @@ async function startWorker(options) {
         capabilities: {
           updateClis: true,
           browserPortForwarding: true,
-          execStdinV1: true
+          execStdinV1: true,
+          ptyEnvFilesV1: true,
+          workspaceRemediationAncestorGuardV1: true,
+          workspaceIncidentConfigDeferralV1: true
         },
         projectRoot: projectsRoot,
         artifactRoot,
@@ -4476,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;
@@ -4507,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,
@@ -4519,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);
@@ -4602,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);
@@ -4704,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;
@@ -4809,12 +5350,21 @@ 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.`
           });
           return;
         }
+        if (active.workspaceEffect !== "none" && targetMayMutateVisibleWorkspace(active.target)) {
+          recordVisibleWorkspaceMutation(active.target);
+        }
         try {
           let bytesWritten = 0;
           if (message.data !== void 0 && message.data.length > 0) {
@@ -4825,8 +5375,8 @@ async function startWorker(options) {
             await active.stdin.end();
             active.stdin = void 0;
           }
-          if (targetMayMutateVisibleWorkspace(active.target)) {
-            markWorkspaceDirty({ type: "shell_inline", detail: `exec stdin ${message.runId}` });
+          if (active.workspaceEffect !== "none" && targetMayMutateVisibleWorkspace(active.target)) {
+            markWorkspaceDirty({ type: "shell_inline", detail: `exec stdin ${message.runId}` }, false, active.target);
           }
           sendAck({
             result: {
@@ -4851,13 +5401,28 @@ 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);
         });
         let releaseWorkspaceMutation;
         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)}
 `);
@@ -4870,7 +5435,7 @@ async function startWorker(options) {
             ...releaseWorkspaceMutation ? { releaseWorkspaceMutation } : {},
             ...targetMayMutateVisibleWorkspace(message.target) ? {
               onTerminal: () => {
-                markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} completed` }, true);
+                markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} completed` }, true, message.target);
               }
             } : {}
           });
@@ -4890,8 +5455,16 @@ 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}` });
+          markWorkspaceDirty({ type: "shell_inline", detail: `pty ${message.ptyId}` }, false, activePty.target);
         }
         writePty(ws, message);
         return;
@@ -4904,7 +5477,7 @@ async function startWorker(options) {
         const activePty = activePtys.get(message.ptyId);
         closePty(message);
         if (activePty && targetMayMutateVisibleWorkspace(activePty.target)) {
-          markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} closed` }, true);
+          markWorkspaceDirty({ type: "process_terminal", detail: `pty ${message.ptyId} closed` }, true, activePty.target);
         }
         return;
       }
@@ -4919,14 +5492,34 @@ 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);
         try {
-          await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
-            workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
-            targetReserved = true;
-          });
+          if (hasWorkspaceEffect) {
+            await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
+              workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
+              targetReserved = true;
+              if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
+            });
+          }
           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(" ")}
 `);
@@ -4937,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);
@@ -4955,10 +5555,11 @@ async function startWorker(options) {
           if (targetReserved) workspaceSyncPriorityProcessTargets.delete(message.runId);
         }
         ws.send(JSON.stringify(result));
-        if (targetMayMutateVisibleWorkspace(message.target)) {
+        if (hasWorkspaceEffect && targetMayMutateVisibleWorkspace(message.target)) {
           markWorkspaceDirty(
             { type: "shell_inline", sessionId: message.sessionId, processRunId: message.runId, detail: "foreground command completed" },
-            true
+            true,
+            message.target
           );
         }
         return;
@@ -4978,6 +5579,7 @@ async function startWorker(options) {
           requestId: message.requestId,
           runId: message.runId
         });
+        const hasWorkspaceEffect = workerCommandHasWorkspaceEffect(message);
         const runCommand = async () => {
           try {
             const resolvedTarget = resolveMessageTarget(message.target);
@@ -4994,7 +5596,7 @@ async function startWorker(options) {
               assertAdmission: assertMessageAdmission
             });
           } finally {
-            if (targetMayMutateVisibleWorkspace(message.target)) {
+            if (hasWorkspaceEffect && targetMayMutateVisibleWorkspace(message.target)) {
               markWorkspaceDirty(
                 {
                   type: "process_terminal",
@@ -5002,7 +5604,8 @@ async function startWorker(options) {
                   processRunId: message.runId,
                   detail: "process completed"
                 },
-                true
+                true,
+                message.target
               );
             }
           }
@@ -5010,10 +5613,13 @@ async function startWorker(options) {
         const execution = (async () => {
           let targetReserved = false;
           try {
-            await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
-              workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
-              targetReserved = true;
-            });
+            if (hasWorkspaceEffect) {
+              await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
+                workspaceSyncPriorityProcessTargets.set(message.runId, message.target);
+                targetReserved = true;
+                if (targetMayMutateVisibleWorkspace(message.target)) recordVisibleWorkspaceMutation(message.target);
+              });
+            }
             await runWorkspaceCommand(message.target, workspaceSyncSingleFlight, runCommand);
           } finally {
             if (targetReserved) workspaceSyncPriorityProcessTargets.delete(message.runId);
@@ -5031,11 +5637,20 @@ 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) {
           await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
             workspaceSyncPriorityOperationTargets.set(message.requestId, message.target);
+            if (mutatesVisibleWorkspace) recordVisibleWorkspaceMutation(message.target);
           });
         }
         let dirtyTrigger;
@@ -5048,7 +5663,8 @@ async function startWorker(options) {
               baseUrl,
               token,
               artifactRoot,
-              planRoot
+              planRoot,
+              assertAdmission: assertMessageAdmission
             });
           });
           ws.send(
@@ -5065,7 +5681,7 @@ async function startWorker(options) {
               toolCallId: message.requestId,
               ...message.target.type === "project" ? { projectId: message.target.projectId, branchName: message.target.branchName } : {}
             };
-            markWorkspaceDirty(dirtyTrigger);
+            markWorkspaceDirty(dirtyTrigger, false, message.target);
           }
         } catch (error) {
           ws.send(
@@ -5078,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);
             }
           }
@@ -5114,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;
@@ -5225,5 +5845,7 @@ export {
   syncSessionArtifacts,
   workerChildProcessEnvironment,
   workerGitSecurityTestHarness,
+  workerPtyBridgeTestHarness,
+  workerPtyTestHarness,
   writeWorkerTextFile
 };