@ricsam/r5d-worker 0.0.88 → 0.0.89

package/dist/cjs/main.cjs

@@ -150,6 +150,11 @@ class StaleWorkerAdmissionError extends Error {
     this.name = "StaleWorkerAdmissionError";
   }
 }
+class WorkspaceSyncAdmissionChangedError extends Error {
+  name = "WorkspaceSyncAdmissionChangedError";
+}
+let unsafeWorkspaceSyncRecoveryAttempts = 0;
+let unsafeWorkspaceSyncBouncePending = false;
 function advanceWorkerAdmissionGeneration() {
   workerAdmissionGeneration += 1;
   return workerAdmissionGeneration;
@@ -1633,16 +1638,33 @@ function workspaceSyncFailureHydrationIsSafe(input) {
   if (input.error instanceof import_workspace_git_sync.WorkspaceRemediationAncestryError) return true;
   if (input.resetToCanonical) return false;
   try {
-    return input.inspectCurrentHydration();
+    return input.inspectRecoverableHydration();
   } catch {
     return false;
   }
 }
+const WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS = 3;
+const WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE = 4008;
+function unsafeWorkspaceSyncRecoveryBounceDelayMs(attempt) {
+  return Math.min(1e3 * 2 ** Math.max(0, attempt - 1), 3e4);
+}
+function unsafeWorkspaceSyncFailureResponse(input) {
+  if (input.resetToCanonical) return "fatal_exit";
+  if (!input.hasRetainableWork) return "fatal_exit";
+  if (input.recoveryAttempts >= input.maxRecoveryAttempts) return "fatal_exit";
+  if (input.bouncePending) return "recovery_pending";
+  return "recovery_bounce";
+}
 function fenceUnsafeWorkspaceSyncFailure(input) {
-  if (input.hydrationCurrent) return false;
+  if (input.hydrationRecoverable) return "none";
   input.invalidateExecution();
-  requireCredentialGenerationRestart(true, input.fatalExit, input.exitCode);
-  return true;
+  const response = unsafeWorkspaceSyncFailureResponse(input);
+  if (response === "fatal_exit") {
+    requireCredentialGenerationRestart(true, input.fatalExit, input.exitCode);
+    throw new Error("Unsafe workspace synchronization fence continued past its fatal exit");
+  }
+  if (response === "recovery_bounce") input.scheduleRecoveryBounce();
+  return response;
 }
 const workerGitSecurityTestHarness = {
   commandArgs: workerGitCommand.commandArgs,
@@ -1670,6 +1692,11 @@ const workerGitSecurityTestHarness = {
   credentialReapContractStatus,
   verifiedCredentialReapContract,
   fenceUnsafeWorkspaceSyncFailure,
+  unsafeWorkspaceSyncFailureResponse,
+  unsafeWorkspaceSyncRecoveryBounceDelayMs,
+  WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS,
+  WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE,
+  WorkspaceSyncAdmissionChangedError,
   workspaceConfigurationIncidentDeferral,
   workspaceIncidentTerminalClearDisposition,
   workspaceIncidentTerminalRefreshFence,
@@ -4286,6 +4313,28 @@ async function startWorker(options) {
       );
     }
   };
+  const scheduleUnsafeWorkspaceSyncRecoveryBounce = (cause) => {
+    unsafeWorkspaceSyncBouncePending = true;
+    const attempt = unsafeWorkspaceSyncRecoveryAttempts;
+    if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+      process.stderr.write(
+        `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; awaiting reconnect recovery (attempt ${attempt} of ${WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS}): ${cause}
+`
+      );
+      return;
+    }
+    process.stderr.write(
+      `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; bouncing the worker socket for in-process recovery (attempt ${attempt} of ${WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS}): ${cause}
+`
+    );
+    const timer = setTimeout(() => {
+      if (!unsafeWorkspaceSyncBouncePending) return;
+      if (currentWorkerSocket === ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+        ws.close(WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE, "Workspace synchronization failed without a recoverable hydration basis");
+      }
+    }, unsafeWorkspaceSyncRecoveryBounceDelayMs(attempt));
+    timer.unref();
+  };
   const runWorkspaceSync = async (input) => {
     const attemptId = input.attemptId ?? crypto.randomUUID();
     const requestedAt = Date.now();
@@ -4294,7 +4343,7 @@ async function startWorker(options) {
     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");
+        throw new WorkspaceSyncAdmissionChangedError("Workspace synchronization admission changed while asynchronous work was in flight");
       }
     };
     if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
@@ -4346,31 +4395,62 @@ async function startWorker(options) {
             assertStillAdmitted
           });
         } catch (error) {
-          const hydrationCurrent = workspaceSyncFailureHydrationIsSafe({
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          const hydrationRecoverable = workspaceSyncFailureHydrationIsSafe({
             error,
             resetToCanonical: input.resetToCanonical === true,
-            inspectCurrentHydration: () => (0, import_workspace_git_sync.workspaceGitHydrationIsCurrent)(workspaceShadowRoot, buildWorkspaceMounts())
+            inspectRecoverableHydration: () => (0, import_workspace_git_sync.workspaceGitHydrationIsRecoverable)(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)}
+          if (hydrationRecoverable) {
+            if (error instanceof WorkspaceSyncAdmissionChangedError) {
+              process.stderr.write(
+                `[r5d-worker] workspace synchronization was cancelled with every mount at a recorded basis; the next cycle converges it: ${errorMessage}
 `
-            );
+              );
+            }
+            return await failedWorkspaceSyncResult(attemptId, input.trigger, error);
           }
-          fenceUnsafeWorkspaceSyncFailure({
-            hydrationCurrent,
+          const fenced = fenceUnsafeWorkspaceSyncFailure({
+            hydrationRecoverable,
+            resetToCanonical: input.resetToCanonical === true,
+            recoveryAttempts: unsafeWorkspaceSyncRecoveryAttempts,
+            maxRecoveryAttempts: WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS,
+            hasRetainableWork: activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0,
+            bouncePending: unsafeWorkspaceSyncBouncePending,
             invalidateExecution: () => {
               workspaceConfigured = false;
               advanceWorkerAdmissionGeneration();
             },
+            scheduleRecoveryBounce: () => {
+              unsafeWorkspaceSyncRecoveryAttempts += 1;
+              scheduleUnsafeWorkspaceSyncRecoveryBounce(errorMessage);
+            },
+            fatalExit: (exitCode) => {
+              process.stderr.write(
+                `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; exiting for exact recovery after ${unsafeWorkspaceSyncRecoveryAttempts} in-process recovery attempt(s): ${errorMessage}
+`
+              );
+              process.exit(exitCode);
+            },
             exitCode: 1
           });
-          return await failedWorkspaceSyncResult(attemptId, input.trigger, error);
+          if (fenced === "recovery_pending") {
+            process.stderr.write(
+              `[r5d-worker] workspace synchronization failed without a recoverable hydration basis while in-process recovery is already pending: ${errorMessage}
+`
+            );
+          }
+          return {
+            ...await failedWorkspaceSyncResult(attemptId, input.trigger, error),
+            failureReason: "unsafe_hydration",
+            recoveryAttempt: unsafeWorkspaceSyncRecoveryAttempts
+          };
         }
       });
     } finally {
       workspaceSyncRequestsInFlight -= 1;
     }
+    if (result.outcome !== "failed") unsafeWorkspaceSyncRecoveryAttempts = 0;
     const finishedAt = Date.now();
     result = {
       ...result,
@@ -4825,7 +4905,9 @@ async function startWorker(options) {
         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");
+            throw new WorkspaceSyncAdmissionChangedError(
+              "Workspace configuration synchronization admission changed while asynchronous work was in flight"
+            );
           }
         };
         const result = await performWorkspaceSync({
@@ -5022,6 +5104,8 @@ async function startWorker(options) {
         const refreshesDeferredConfiguration = deferredWorkspaceConfiguration !== null && activeWorkspaceIncidentId === null && message.deferWorkspaceSyncForIncidentId === void 0;
         advanceWorkerAdmissionGeneration();
         const configured = await configureWorkerWorkspace(message, receiptGeneration);
+        unsafeWorkspaceSyncBouncePending = false;
+        if (configured.result.outcome !== "failed") unsafeWorkspaceSyncRecoveryAttempts = 0;
         sendWorkerMessageFromCurrentSource(ws, {
           type: "workspace_configured",
           requestId: message.requestId,

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.88",
+  "version": "0.0.89",
   "type": "commonjs"
 }

package/dist/cjs/workspace-git-sync.cjs

@@ -42,6 +42,7 @@ __export(workspace_git_sync_exports, {
   resetWorkspaceGit: () => resetWorkspaceGit,
   synchronizeWorkspaceGit: () => synchronizeWorkspaceGit,
   workspaceGitHydrationIsCurrent: () => workspaceGitHydrationIsCurrent,
+  workspaceGitHydrationIsRecoverable: () => workspaceGitHydrationIsRecoverable,
   workspaceGitMountsForRemediation: () => workspaceGitMountsForRemediation,
   workspaceGitSyncTestHarness: () => workspaceGitSyncTestHarness
 });
@@ -420,18 +421,25 @@ function hydratedWorkspaceReceiptFileIsV3(workspacePath) {
   }
 }
 function workspaceGitHydrationIsCurrent(workspacePath, mounts) {
+  return workspaceGitHydrationHolds(workspacePath, mounts, false);
+}
+function workspaceGitHydrationIsRecoverable(workspacePath, mounts) {
+  return workspaceGitHydrationHolds(workspacePath, mounts, true);
+}
+function workspaceGitHydrationHolds(workspacePath, mounts, tolerateIdleRecordedBasis) {
   const resolvedWorkspacePath = import_node_path.default.resolve(workspacePath);
   if (!import_node_fs.default.existsSync(import_node_path.default.join(resolvedWorkspacePath, ".git"))) return true;
   if (mounts) validateMounts(resolvedWorkspacePath, mounts);
   const head = revParse(resolvedWorkspacePath, "HEAD");
   if (!workspaceCheckoutDurabilityIsCurrent(resolvedWorkspacePath)) return false;
+  if (tolerateIdleRecordedBasis && lstatIfExists(hydrationTransactionPath(resolvedWorkspacePath)) !== null) return false;
   const receipt = readHydratedWorkspaceReceipt(resolvedWorkspacePath);
   if (!workspaceBasisRefsAreCurrent(resolvedWorkspacePath, receipt ?? { version: 3, mounts: [] })) return false;
   if (head === null) return true;
   if (!receipt) return false;
   return mounts ? configuredWorkspaceHydrationBasisMounts(resolvedWorkspacePath, mounts).every(
-    (mount) => workspaceHydrationReceiptCoversMount(receipt, head, mount) || Boolean(mount.busy?.() && workspaceHydrationReceiptMountBasisHead(receipt, mount))
-  ) : Boolean(receipt && receipt.mounts.every((mount) => mount.head === head));
+    (mount) => workspaceHydrationReceiptCoversMount(receipt, head, mount) || Boolean((tolerateIdleRecordedBasis || mount.busy?.()) && workspaceHydrationReceiptMountBasisHead(receipt, mount))
+  ) : Boolean(receipt && receipt.mounts.every((mount) => tolerateIdleRecordedBasis || mount.head === head));
 }
 const WORKSPACE_GIT_BASIS_REF_PREFIX = "refs/r5d/workspace-basis/";
 const WORKSPACE_GIT_BASIS_STAGING_REF_PREFIX = "refs/r5d/workspace-basis-staging/";
@@ -2190,6 +2198,7 @@ const workspaceGitSyncTestHarness = {
   resetWorkspaceGit,
   synchronizeWorkspaceGit,
   workspaceGitHydrationIsCurrent,
+  workspaceGitHydrationIsRecoverable,
   workspaceGitMountsForRemediation,
   workspaceGitSyncTestHarness
 });

package/dist/mjs/main.mjs

@@ -88,7 +88,7 @@ import {
   recoverWorkspaceGitHydration,
   resetWorkspaceGit,
   synchronizeWorkspaceGit,
-  workspaceGitHydrationIsCurrent,
+  workspaceGitHydrationIsRecoverable,
   workspaceGitMountsForRemediation,
   WorkspaceRemediationAncestryError
 } from "./workspace-git-sync.mjs";
@@ -158,6 +158,11 @@ class StaleWorkerAdmissionError extends Error {
     this.name = "StaleWorkerAdmissionError";
   }
 }
+class WorkspaceSyncAdmissionChangedError extends Error {
+  name = "WorkspaceSyncAdmissionChangedError";
+}
+let unsafeWorkspaceSyncRecoveryAttempts = 0;
+let unsafeWorkspaceSyncBouncePending = false;
 function advanceWorkerAdmissionGeneration() {
   workerAdmissionGeneration += 1;
   return workerAdmissionGeneration;
@@ -1641,16 +1646,33 @@ function workspaceSyncFailureHydrationIsSafe(input) {
   if (input.error instanceof WorkspaceRemediationAncestryError) return true;
   if (input.resetToCanonical) return false;
   try {
-    return input.inspectCurrentHydration();
+    return input.inspectRecoverableHydration();
   } catch {
     return false;
   }
 }
+const WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS = 3;
+const WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE = 4008;
+function unsafeWorkspaceSyncRecoveryBounceDelayMs(attempt) {
+  return Math.min(1e3 * 2 ** Math.max(0, attempt - 1), 3e4);
+}
+function unsafeWorkspaceSyncFailureResponse(input) {
+  if (input.resetToCanonical) return "fatal_exit";
+  if (!input.hasRetainableWork) return "fatal_exit";
+  if (input.recoveryAttempts >= input.maxRecoveryAttempts) return "fatal_exit";
+  if (input.bouncePending) return "recovery_pending";
+  return "recovery_bounce";
+}
 function fenceUnsafeWorkspaceSyncFailure(input) {
-  if (input.hydrationCurrent) return false;
+  if (input.hydrationRecoverable) return "none";
   input.invalidateExecution();
-  requireCredentialGenerationRestart(true, input.fatalExit, input.exitCode);
-  return true;
+  const response = unsafeWorkspaceSyncFailureResponse(input);
+  if (response === "fatal_exit") {
+    requireCredentialGenerationRestart(true, input.fatalExit, input.exitCode);
+    throw new Error("Unsafe workspace synchronization fence continued past its fatal exit");
+  }
+  if (response === "recovery_bounce") input.scheduleRecoveryBounce();
+  return response;
 }
 const workerGitSecurityTestHarness = {
   commandArgs: workerGitCommand.commandArgs,
@@ -1678,6 +1700,11 @@ const workerGitSecurityTestHarness = {
   credentialReapContractStatus,
   verifiedCredentialReapContract,
   fenceUnsafeWorkspaceSyncFailure,
+  unsafeWorkspaceSyncFailureResponse,
+  unsafeWorkspaceSyncRecoveryBounceDelayMs,
+  WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS,
+  WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE,
+  WorkspaceSyncAdmissionChangedError,
   workspaceConfigurationIncidentDeferral,
   workspaceIncidentTerminalClearDisposition,
   workspaceIncidentTerminalRefreshFence,
@@ -4294,6 +4321,28 @@ async function startWorker(options) {
       );
     }
   };
+  const scheduleUnsafeWorkspaceSyncRecoveryBounce = (cause) => {
+    unsafeWorkspaceSyncBouncePending = true;
+    const attempt = unsafeWorkspaceSyncRecoveryAttempts;
+    if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
+      process.stderr.write(
+        `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; awaiting reconnect recovery (attempt ${attempt} of ${WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS}): ${cause}
+`
+      );
+      return;
+    }
+    process.stderr.write(
+      `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; bouncing the worker socket for in-process recovery (attempt ${attempt} of ${WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS}): ${cause}
+`
+    );
+    const timer = setTimeout(() => {
+      if (!unsafeWorkspaceSyncBouncePending) return;
+      if (currentWorkerSocket === ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+        ws.close(WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE, "Workspace synchronization failed without a recoverable hydration basis");
+      }
+    }, unsafeWorkspaceSyncRecoveryBounceDelayMs(attempt));
+    timer.unref();
+  };
   const runWorkspaceSync = async (input) => {
     const attemptId = input.attemptId ?? crypto.randomUUID();
     const requestedAt = Date.now();
@@ -4302,7 +4351,7 @@ async function startWorker(options) {
     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");
+        throw new WorkspaceSyncAdmissionChangedError("Workspace synchronization admission changed while asynchronous work was in flight");
       }
     };
     if (!deferredWorkspaceSyncTriggerIsAllowed(deferredWorkspaceConfiguration, activeWorkspaceIncidentId, input.trigger)) {
@@ -4354,31 +4403,62 @@ async function startWorker(options) {
             assertStillAdmitted
           });
         } catch (error) {
-          const hydrationCurrent = workspaceSyncFailureHydrationIsSafe({
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          const hydrationRecoverable = workspaceSyncFailureHydrationIsSafe({
             error,
             resetToCanonical: input.resetToCanonical === true,
-            inspectCurrentHydration: () => workspaceGitHydrationIsCurrent(workspaceShadowRoot, buildWorkspaceMounts())
+            inspectRecoverableHydration: () => workspaceGitHydrationIsRecoverable(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)}
+          if (hydrationRecoverable) {
+            if (error instanceof WorkspaceSyncAdmissionChangedError) {
+              process.stderr.write(
+                `[r5d-worker] workspace synchronization was cancelled with every mount at a recorded basis; the next cycle converges it: ${errorMessage}
 `
-            );
+              );
+            }
+            return await failedWorkspaceSyncResult(attemptId, input.trigger, error);
           }
-          fenceUnsafeWorkspaceSyncFailure({
-            hydrationCurrent,
+          const fenced = fenceUnsafeWorkspaceSyncFailure({
+            hydrationRecoverable,
+            resetToCanonical: input.resetToCanonical === true,
+            recoveryAttempts: unsafeWorkspaceSyncRecoveryAttempts,
+            maxRecoveryAttempts: WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS,
+            hasRetainableWork: activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0,
+            bouncePending: unsafeWorkspaceSyncBouncePending,
             invalidateExecution: () => {
               workspaceConfigured = false;
               advanceWorkerAdmissionGeneration();
             },
+            scheduleRecoveryBounce: () => {
+              unsafeWorkspaceSyncRecoveryAttempts += 1;
+              scheduleUnsafeWorkspaceSyncRecoveryBounce(errorMessage);
+            },
+            fatalExit: (exitCode) => {
+              process.stderr.write(
+                `[r5d-worker] workspace synchronization failed without a recoverable hydration basis; exiting for exact recovery after ${unsafeWorkspaceSyncRecoveryAttempts} in-process recovery attempt(s): ${errorMessage}
+`
+              );
+              process.exit(exitCode);
+            },
             exitCode: 1
           });
-          return await failedWorkspaceSyncResult(attemptId, input.trigger, error);
+          if (fenced === "recovery_pending") {
+            process.stderr.write(
+              `[r5d-worker] workspace synchronization failed without a recoverable hydration basis while in-process recovery is already pending: ${errorMessage}
+`
+            );
+          }
+          return {
+            ...await failedWorkspaceSyncResult(attemptId, input.trigger, error),
+            failureReason: "unsafe_hydration",
+            recoveryAttempt: unsafeWorkspaceSyncRecoveryAttempts
+          };
         }
       });
     } finally {
       workspaceSyncRequestsInFlight -= 1;
     }
+    if (result.outcome !== "failed") unsafeWorkspaceSyncRecoveryAttempts = 0;
     const finishedAt = Date.now();
     result = {
       ...result,
@@ -4833,7 +4913,9 @@ async function startWorker(options) {
         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");
+            throw new WorkspaceSyncAdmissionChangedError(
+              "Workspace configuration synchronization admission changed while asynchronous work was in flight"
+            );
           }
         };
         const result = await performWorkspaceSync({
@@ -5030,6 +5112,8 @@ async function startWorker(options) {
         const refreshesDeferredConfiguration = deferredWorkspaceConfiguration !== null && activeWorkspaceIncidentId === null && message.deferWorkspaceSyncForIncidentId === void 0;
         advanceWorkerAdmissionGeneration();
         const configured = await configureWorkerWorkspace(message, receiptGeneration);
+        unsafeWorkspaceSyncBouncePending = false;
+        if (configured.result.outcome !== "failed") unsafeWorkspaceSyncRecoveryAttempts = 0;
         sendWorkerMessageFromCurrentSource(ws, {
           type: "workspace_configured",
           requestId: message.requestId,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.88",
+  "version": "0.0.89",
   "type": "module"
 }

package/dist/mjs/workspace-git-sync.mjs

@@ -376,18 +376,25 @@ function hydratedWorkspaceReceiptFileIsV3(workspacePath) {
   }
 }
 function workspaceGitHydrationIsCurrent(workspacePath, mounts) {
+  return workspaceGitHydrationHolds(workspacePath, mounts, false);
+}
+function workspaceGitHydrationIsRecoverable(workspacePath, mounts) {
+  return workspaceGitHydrationHolds(workspacePath, mounts, true);
+}
+function workspaceGitHydrationHolds(workspacePath, mounts, tolerateIdleRecordedBasis) {
   const resolvedWorkspacePath = path.resolve(workspacePath);
   if (!fs.existsSync(path.join(resolvedWorkspacePath, ".git"))) return true;
   if (mounts) validateMounts(resolvedWorkspacePath, mounts);
   const head = revParse(resolvedWorkspacePath, "HEAD");
   if (!workspaceCheckoutDurabilityIsCurrent(resolvedWorkspacePath)) return false;
+  if (tolerateIdleRecordedBasis && lstatIfExists(hydrationTransactionPath(resolvedWorkspacePath)) !== null) return false;
   const receipt = readHydratedWorkspaceReceipt(resolvedWorkspacePath);
   if (!workspaceBasisRefsAreCurrent(resolvedWorkspacePath, receipt ?? { version: 3, mounts: [] })) return false;
   if (head === null) return true;
   if (!receipt) return false;
   return mounts ? configuredWorkspaceHydrationBasisMounts(resolvedWorkspacePath, mounts).every(
-    (mount) => workspaceHydrationReceiptCoversMount(receipt, head, mount) || Boolean(mount.busy?.() && workspaceHydrationReceiptMountBasisHead(receipt, mount))
-  ) : Boolean(receipt && receipt.mounts.every((mount) => mount.head === head));
+    (mount) => workspaceHydrationReceiptCoversMount(receipt, head, mount) || Boolean((tolerateIdleRecordedBasis || mount.busy?.()) && workspaceHydrationReceiptMountBasisHead(receipt, mount))
+  ) : Boolean(receipt && receipt.mounts.every((mount) => tolerateIdleRecordedBasis || mount.head === head));
 }
 const WORKSPACE_GIT_BASIS_REF_PREFIX = "refs/r5d/workspace-basis/";
 const WORKSPACE_GIT_BASIS_STAGING_REF_PREFIX = "refs/r5d/workspace-basis-staging/";
@@ -2145,6 +2152,7 @@ export {
   resetWorkspaceGit,
   synchronizeWorkspaceGit,
   workspaceGitHydrationIsCurrent,
+  workspaceGitHydrationIsRecoverable,
   workspaceGitMountsForRemediation,
   workspaceGitSyncTestHarness
 };

package/dist/types/main.d.ts

@@ -69,6 +69,10 @@ type WorkspaceSyncResult = {
         synchronizeMs: number;
     };
     error?: string;
+    /** Typed reason for a failed outcome the server should surface loudly. */
+    failureReason?: "unsafe_hydration";
+    /** Consecutive in-process recovery bounces taken for unsafe hydration failures. */
+    recoveryAttempt?: number;
 };
 export type WorkerSessionTarget = {
     type: "project";
@@ -356,6 +360,9 @@ type WorkerCodeReadResult = {
     mtime: string;
     base64: string;
 };
+declare class WorkspaceSyncAdmissionChangedError extends Error {
+    readonly name = "WorkspaceSyncAdmissionChangedError";
+}
 declare function assertWorkerChildAdmission(input: {
     capturedGeneration: number;
     currentGeneration: number;
@@ -609,14 +616,29 @@ declare function deferredIncidentWorkspaceConfigurationResult(input: {
 declare function workspaceSyncFailureHydrationIsSafe(input: {
     error: unknown;
     resetToCanonical: boolean;
-    inspectCurrentHydration: () => boolean;
+    inspectRecoverableHydration: () => boolean;
 }): boolean;
+declare function unsafeWorkspaceSyncRecoveryBounceDelayMs(attempt: number): number;
+type UnsafeWorkspaceSyncFailureResponse = "fatal_exit" | "recovery_bounce" | "recovery_pending";
+declare function unsafeWorkspaceSyncFailureResponse(input: {
+    resetToCanonical: boolean;
+    recoveryAttempts: number;
+    maxRecoveryAttempts: number;
+    hasRetainableWork: boolean;
+    bouncePending: boolean;
+}): UnsafeWorkspaceSyncFailureResponse;
 declare function fenceUnsafeWorkspaceSyncFailure(input: {
-    hydrationCurrent: boolean;
+    hydrationRecoverable: boolean;
+    resetToCanonical: boolean;
+    recoveryAttempts: number;
+    maxRecoveryAttempts: number;
+    hasRetainableWork: boolean;
+    bouncePending: boolean;
     invalidateExecution: () => void;
+    scheduleRecoveryBounce: () => void;
     fatalExit?: (exitCode: number) => void;
     exitCode?: number;
-}): boolean;
+}): "none" | "recovery_bounce" | "recovery_pending";
 export declare const workerGitSecurityTestHarness: {
     commandArgs: (args: string[]) => string[];
     credentialHelperForRemotes: typeof credentialHelperForRemotes;
@@ -641,6 +663,11 @@ export declare const workerGitSecurityTestHarness: {
     credentialReapContractStatus: typeof credentialReapContractStatus;
     verifiedCredentialReapContract: typeof verifiedCredentialReapContract;
     fenceUnsafeWorkspaceSyncFailure: typeof fenceUnsafeWorkspaceSyncFailure;
+    unsafeWorkspaceSyncFailureResponse: typeof unsafeWorkspaceSyncFailureResponse;
+    unsafeWorkspaceSyncRecoveryBounceDelayMs: typeof unsafeWorkspaceSyncRecoveryBounceDelayMs;
+    WORKSPACE_UNSAFE_SYNC_MAX_RECOVERY_ATTEMPTS: number;
+    WORKSPACE_UNSAFE_SYNC_RECOVERY_CLOSE_CODE: number;
+    WorkspaceSyncAdmissionChangedError: typeof WorkspaceSyncAdmissionChangedError;
     workspaceConfigurationIncidentDeferral: typeof workspaceConfigurationIncidentDeferral;
     workspaceIncidentTerminalClearDisposition: typeof workspaceIncidentTerminalClearDisposition;
     workspaceIncidentTerminalRefreshFence: typeof workspaceIncidentTerminalRefreshFence;

package/dist/types/workspace-git-sync.d.ts

@@ -71,6 +71,16 @@ export declare class WorkspaceRemediationAncestryError extends Error {
 declare function gitCommandArgs(args: string[]): string[];
 declare function workspaceCloneCommandArgs(args: string[], remoteUrl: string, credentialHelper?: string | null, credentialUsername?: string | null): string[];
 export declare function workspaceGitHydrationIsCurrent(workspacePath: string, mounts?: readonly WorkspaceGitMount[]): boolean;
+/**
+ * Failure-time variant of the currency check. A mount pinned at a valid
+ * recorded basis is convergent whether or not it is busy right now: the next
+ * cycle merges it forward from that exact basis and a genuine collision
+ * surfaces as a projection_merge conflict, never a silent overwrite. Live
+ * busy-ness must not decide safety here because the same disconnect that
+ * aborts a sync also clears the process/PTY maps busy-ness is computed from.
+ * Configuration-time recovery keeps the strict predicate.
+ */
+export declare function workspaceGitHydrationIsRecoverable(workspacePath: string, mounts?: readonly WorkspaceGitMount[]): boolean;
 declare function configureWorkspaceRepository(input: {
     workspacePath: string;
     remoteUrl: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.88",
+  "version": "0.0.89",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",