@ricsam/r5d-worker 0.0.99 → 0.0.100

package/dist/cjs/main.cjs

@@ -97,9 +97,35 @@ function workerServerHeartbeatAction(input) {
   if (input.watchdogSweepDelayed || input.probeElapsedMs === void 0) return "start_probe";
   return input.probeElapsedMs >= input.timeoutMs ? "terminate" : "wait";
 }
+const WORKSPACE_HYDRATION_LEASE_OPERATION_PREFIX = "hydration:";
+function createWorkspaceHydrationLeaseHooks(send, options = {}) {
+  const yieldToEventLoop = options.yieldToEventLoop ?? (() => new Promise((resolve) => setImmediate(resolve)));
+  const log = options.log ?? ((line) => process.stdout.write(`${line}
+`));
+  const now = options.now ?? (() => performance.now());
+  const operationId = (context) => `${WORKSPACE_HYDRATION_LEASE_OPERATION_PREFIX}${context.transactionId}`;
+  const startedAtMs = /* @__PURE__ */ new Map();
+  return {
+    async beforeTransaction(context) {
+      send({ type: "heartbeat_lease", operationId: operationId(context), kind: "hydration", active: true });
+      startedAtMs.set(context.transactionId, now());
+      log(`[r5d-worker] hydrating ${context.mountIds.length} workspace mount(s) under hydration lease ${context.transactionId}`);
+      await yieldToEventLoop();
+    },
+    afterTransaction(context) {
+      const startedAt = startedAtMs.get(context.transactionId);
+      startedAtMs.delete(context.transactionId);
+      send({ type: "heartbeat_lease", operationId: operationId(context), kind: "hydration", active: false });
+      log(
+        `[r5d-worker] released hydration lease ${context.transactionId} after ${startedAt === void 0 ? "?" : Math.round(now() - startedAt)}ms`
+      );
+    }
+  };
+}
 const workerLifecycleTestHarness = {
   boundedWorkerLifecycleProgress,
-  workerServerHeartbeatAction
+  workerServerHeartbeatAction,
+  createWorkspaceHydrationLeaseHooks
 };
 class ProjectWorkspaceConfigurationDeferredError extends Error {
 }
@@ -4370,6 +4396,7 @@ async function startWorker(options) {
       error: error instanceof Error ? error.message : String(error)
     };
   };
+  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks((message) => sendWorkerMessageFromCurrentSource(ws, message));
   const performWorkspaceSync = async (input) => {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
@@ -4392,7 +4419,8 @@ async function startWorker(options) {
         credentialHelper: workspaceCredentialHelper,
         credentialUsername: workspaceCredentialUsername,
         gitIdentity: workspaceGitIdentity,
-        mounts: configuredMounts
+        mounts: configuredMounts,
+        hydrationHooks: workspaceHydrationTransactionHooks
       });
       await applyObservedProjectHeadsAfterInboundWorkspace(observedProjectHeads2, reset.activeMountIds, true);
       return {
@@ -4446,7 +4474,8 @@ async function startWorker(options) {
       assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : async ({ activeMountIds, publishedHead }) => {
         await pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, inboundMoveMountIds);
-      }
+      },
+      hydrationHooks: workspaceHydrationTransactionHooks
     });
     input.assertStillAdmitted?.();
     if (result.initialPublicationMountIds && result.initialPublicationMountIds.length > 0) {
@@ -5040,7 +5069,10 @@ async function startWorker(options) {
           sourcePath: recoverySourceOverrides.get(mount.id) ?? mount.sourcePath,
           busy: mount.busyForRecovery ?? mount.busy
         }));
-        await (0, import_workspace_git_sync.recoverWorkspaceGitHydration)(workspaceShadowRoot, recoveryMounts, { preserveStaleBases: true });
+        await (0, import_workspace_git_sync.recoverWorkspaceGitHydration)(workspaceShadowRoot, recoveryMounts, {
+          preserveStaleBases: true,
+          hydrationHooks: workspaceHydrationTransactionHooks
+        });
         for (const project of message.projects) {
           for (const { branchName } of project.preserveOnlyBranches) {
             if (stillPendingCreatedBranches.has((0, import_workspace_automatic_sync_policy.pendingCreatedBranchKey)(project.projectId, branchName))) {
@@ -5084,7 +5116,7 @@ async function startWorker(options) {
           // layouts can be marked ready. No process can resolve an unready
           // target, and preserving the fetched outer tree here prevents clean
           // checkout initialization from erasing synchronized dirt.
-          { ignoreBusy: true }
+          { ignoreBusy: true, hydrationHooks: workspaceHydrationTransactionHooks }
         );
         await ensureConfiguredProjects((progress) => {
           sendLifecycleProgress({ phase: "configuring", operationId: configurationOperationId, ...progress });

package/dist/cjs/package.json

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

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

@@ -1601,56 +1601,67 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
     const busyMountIds = new Set(input.ignoreBusy ? [] : candidateMounts.filter((mount) => mount.busy?.()).map(({ id }) => id));
     const requestedIds = new Set(input.mounts.map(({ id }) => id));
     const requiredIds = new Set(requiredMounts.map(({ id }) => id));
-    const hydrationMounts2 = input.mounts.filter(({ id }) => !busyMountIds.has(id));
-    const advancedDurabilityMounts2 = durabilityMounts.filter(
+    const hydrationMounts = input.mounts.filter(({ id }) => !busyMountIds.has(id));
+    const advancedDurabilityMounts = durabilityMounts.filter(
       ({ id }) => !busyMountIds.has(id) && (requestedIds.has(id) || !requiredIds.has(id))
     );
     const unavailableRequiredIds = requiredMounts.filter(({ id }) => busyMountIds.has(id) || !requestedIds.has(id)).map(({ id }) => id);
     const carriedMounts = carryMounts.filter(({ id }) => !busyMountIds.has(id));
     return {
       busyMountIds,
-      hydrationMounts: hydrationMounts2,
-      advancedDurabilityMounts: advancedDurabilityMounts2,
+      hydrationMounts,
+      advancedDurabilityMounts,
       skippedMountIds: [.../* @__PURE__ */ new Set([...busyMountIds, ...unavailableRequiredIds])].sort(),
-      targetReceipt: targetHead ? receiptWithMountsAtHead(receiptBeforeTransaction, targetHead, [...advancedDurabilityMounts2, ...carriedMounts], receiptMounts) : null
+      targetReceipt: targetHead ? receiptWithMountsAtHead(receiptBeforeTransaction, targetHead, [...advancedDurabilityMounts, ...carriedMounts], receiptMounts) : null
     };
   };
   const noopCandidate = computeSelection();
   if (noopCandidate.hydrationMounts.length === 0 && noopCandidate.advancedDurabilityMounts.length === 0 && noopCandidate.targetReceipt && lstatIfExists(hydrationTransactionPath(workspacePath)) === null && workspaceHydrationReceiptsEqual(receiptBeforeTransaction, noopCandidate.targetReceipt) && hydratedWorkspaceReceiptFileIsV3(workspacePath) && await workspaceBasisRefsAreCurrentAsync(workspacePath, noopCandidate.targetReceipt)) {
     return { hydratedMountIds: [], skippedMountIds: noopCandidate.skippedMountIds };
   }
-  const selection = computeSelection();
-  const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = selection;
-  const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
+  const hooks = input.hydrationHooks;
+  const context = {
+    transactionId: crypto.randomUUID(),
+    workspacePath,
+    mountIds: [...new Set([...noopCandidate.hydrationMounts, ...noopCandidate.advancedDurabilityMounts].map(({ id }) => id))].sort()
+  };
+  if (hooks) await hooks.beforeTransaction(context);
   try {
-    const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
-    const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
-    if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
-      throw new Error("Workspace hydration did not include every required mount");
-    }
-    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
-    markHydrationTransactionDurable(workspacePath);
-    if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
-    removeHydrationTransaction(workspacePath);
-    return {
-      hydratedMountIds: hydration.hydratedMountIds,
-      skippedMountIds: selection.skippedMountIds
-    };
-  } catch (error) {
-    const transactionPath = hydrationTransactionPath(workspacePath);
-    if (lstatIfExists(transactionPath) && hydrationTransactionCommitted(transactionPath)) {
-      throw error;
-    }
+    const selection = computeSelection();
+    const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = selection;
+    const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
     try {
-      restoreHydrationTransaction(workspacePath, manifest);
+      const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
+      const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
+      if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
+        throw new Error("Workspace hydration did not include every required mount");
+      }
+      fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
+      markHydrationTransactionDurable(workspacePath);
+      if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
       removeHydrationTransaction(workspacePath);
-    } catch (restoreError) {
-      throw new AggregateError(
-        [error, restoreError],
-        `Workspace hydration failed and its durable snapshot could not be restored: ${error instanceof Error ? error.message : String(error)}`
-      );
+      return {
+        hydratedMountIds: hydration.hydratedMountIds,
+        skippedMountIds: selection.skippedMountIds
+      };
+    } catch (error) {
+      const transactionPath = hydrationTransactionPath(workspacePath);
+      if (lstatIfExists(transactionPath) && hydrationTransactionCommitted(transactionPath)) {
+        throw error;
+      }
+      try {
+        restoreHydrationTransaction(workspacePath, manifest);
+        removeHydrationTransaction(workspacePath);
+      } catch (restoreError) {
+        throw new AggregateError(
+          [error, restoreError],
+          `Workspace hydration failed and its durable snapshot could not be restored: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      throw error;
     }
-    throw error;
+  } finally {
+    hooks?.afterTransaction(context);
   }
 }
 async function hydrateWorkspaceGitMounts(workspacePath, mounts, options = {}) {
@@ -1662,7 +1673,8 @@ async function hydrateWorkspaceGitMounts(workspacePath, mounts, options = {}) {
   return hydrateWorkspaceGitMountsTransactionally({
     workspacePath,
     mounts,
-    ignoreBusy: options.ignoreBusy
+    ignoreBusy: options.ignoreBusy,
+    hydrationHooks: options.hydrationHooks
   });
 }
 async function recoverWorkspaceGitHydration(workspacePath, mounts, options = {}) {
@@ -1702,7 +1714,8 @@ async function recoverWorkspaceGitHydration(workspacePath, mounts, options = {})
     receiptMounts: configuredBasisMounts,
     requiredMounts: hydrationTargets,
     ignoreBusy: options.ignoreBusy,
-    recordCurrentHead: true
+    recordCurrentHead: true,
+    hydrationHooks: options.hydrationHooks
   });
   void hydration;
 }
@@ -1753,7 +1766,8 @@ async function resetWorkspaceGit(input) {
     durabilityMounts: [...requiredLiveMounts, ...selected.tombstones, ...durablyAbsentMounts],
     receiptMounts: input.mounts,
     requiredMounts: requiredLiveMounts,
-    recordCurrentHead: true
+    recordCurrentHead: true,
+    hydrationHooks: input.hydrationHooks
   });
   const requiredLiveIds = requiredLiveMounts.map(({ id }) => id).sort();
   const resetHead = revParse(workspacePath, "HEAD");
@@ -2008,7 +2022,8 @@ async function synchronizeWorkspaceGit(input) {
   await recoverWorkspaceGitHydration(workspacePath, input.mounts, {
     ...deferredMountIds.size > 0 ? { deferMountIds: deferredMountIds } : {},
     preserveResolutionInProgress,
-    preserveStaleBases: true
+    preserveStaleBases: true,
+    hydrationHooks: input.hydrationHooks
   });
   const selected = activeMounts(input.mounts);
   const projectionMutationTokens = new Map(
@@ -2134,7 +2149,8 @@ async function synchronizeWorkspaceGit(input) {
       carryMounts: uncoveredCompletionMounts.filter(({ id }) => unchangedMountIds.has(id)),
       receiptMounts: completionReceiptMounts,
       requiredMounts: uncoveredRequiredLiveMounts.filter(({ id }) => !unchangedMountIds.has(id)),
-      recordCurrentHead: true
+      recordCurrentHead: true,
+      hydrationHooks: input.hydrationHooks
     });
     for (const id of hydration.skippedMountIds) cycleSkippedMountIds.add(id);
     refreshCycleSkippedMounts(completionReceiptMounts);

package/dist/mjs/main.mjs

@@ -104,9 +104,35 @@ function workerServerHeartbeatAction(input) {
   if (input.watchdogSweepDelayed || input.probeElapsedMs === void 0) return "start_probe";
   return input.probeElapsedMs >= input.timeoutMs ? "terminate" : "wait";
 }
+const WORKSPACE_HYDRATION_LEASE_OPERATION_PREFIX = "hydration:";
+function createWorkspaceHydrationLeaseHooks(send, options = {}) {
+  const yieldToEventLoop = options.yieldToEventLoop ?? (() => new Promise((resolve) => setImmediate(resolve)));
+  const log = options.log ?? ((line) => process.stdout.write(`${line}
+`));
+  const now = options.now ?? (() => performance.now());
+  const operationId = (context) => `${WORKSPACE_HYDRATION_LEASE_OPERATION_PREFIX}${context.transactionId}`;
+  const startedAtMs = /* @__PURE__ */ new Map();
+  return {
+    async beforeTransaction(context) {
+      send({ type: "heartbeat_lease", operationId: operationId(context), kind: "hydration", active: true });
+      startedAtMs.set(context.transactionId, now());
+      log(`[r5d-worker] hydrating ${context.mountIds.length} workspace mount(s) under hydration lease ${context.transactionId}`);
+      await yieldToEventLoop();
+    },
+    afterTransaction(context) {
+      const startedAt = startedAtMs.get(context.transactionId);
+      startedAtMs.delete(context.transactionId);
+      send({ type: "heartbeat_lease", operationId: operationId(context), kind: "hydration", active: false });
+      log(
+        `[r5d-worker] released hydration lease ${context.transactionId} after ${startedAt === void 0 ? "?" : Math.round(now() - startedAt)}ms`
+      );
+    }
+  };
+}
 const workerLifecycleTestHarness = {
   boundedWorkerLifecycleProgress,
-  workerServerHeartbeatAction
+  workerServerHeartbeatAction,
+  createWorkspaceHydrationLeaseHooks
 };
 class ProjectWorkspaceConfigurationDeferredError extends Error {
 }
@@ -4377,6 +4403,7 @@ async function startWorker(options) {
       error: error instanceof Error ? error.message : String(error)
     };
   };
+  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks((message) => sendWorkerMessageFromCurrentSource(ws, message));
   const performWorkspaceSync = async (input) => {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
@@ -4399,7 +4426,8 @@ async function startWorker(options) {
         credentialHelper: workspaceCredentialHelper,
         credentialUsername: workspaceCredentialUsername,
         gitIdentity: workspaceGitIdentity,
-        mounts: configuredMounts
+        mounts: configuredMounts,
+        hydrationHooks: workspaceHydrationTransactionHooks
       });
       await applyObservedProjectHeadsAfterInboundWorkspace(observedProjectHeads2, reset.activeMountIds, true);
       return {
@@ -4453,7 +4481,8 @@ async function startWorker(options) {
       assertStillAdmitted: input.assertStillAdmitted,
       afterWorkspacePublished: outerRemediation ? void 0 : async ({ activeMountIds, publishedHead }) => {
         await pushChangedProjectHeads(activeMountIds, publishedHead, publicationHeads, expectedMirrorHeads, inboundMoveMountIds);
-      }
+      },
+      hydrationHooks: workspaceHydrationTransactionHooks
     });
     input.assertStillAdmitted?.();
     if (result.initialPublicationMountIds && result.initialPublicationMountIds.length > 0) {
@@ -5047,7 +5076,10 @@ async function startWorker(options) {
           sourcePath: recoverySourceOverrides.get(mount.id) ?? mount.sourcePath,
           busy: mount.busyForRecovery ?? mount.busy
         }));
-        await recoverWorkspaceGitHydration(workspaceShadowRoot, recoveryMounts, { preserveStaleBases: true });
+        await recoverWorkspaceGitHydration(workspaceShadowRoot, recoveryMounts, {
+          preserveStaleBases: true,
+          hydrationHooks: workspaceHydrationTransactionHooks
+        });
         for (const project of message.projects) {
           for (const { branchName } of project.preserveOnlyBranches) {
             if (stillPendingCreatedBranches.has(pendingCreatedBranchKey(project.projectId, branchName))) {
@@ -5091,7 +5123,7 @@ async function startWorker(options) {
           // layouts can be marked ready. No process can resolve an unready
           // target, and preserving the fetched outer tree here prevents clean
           // checkout initialization from erasing synchronized dirt.
-          { ignoreBusy: true }
+          { ignoreBusy: true, hydrationHooks: workspaceHydrationTransactionHooks }
         );
         await ensureConfiguredProjects((progress) => {
           sendLifecycleProgress({ phase: "configuring", operationId: configurationOperationId, ...progress });

package/dist/mjs/package.json

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

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

@@ -1564,56 +1564,67 @@ async function hydrateWorkspaceGitMountsTransactionally(input) {
     const busyMountIds = new Set(input.ignoreBusy ? [] : candidateMounts.filter((mount) => mount.busy?.()).map(({ id }) => id));
     const requestedIds = new Set(input.mounts.map(({ id }) => id));
     const requiredIds = new Set(requiredMounts.map(({ id }) => id));
-    const hydrationMounts2 = input.mounts.filter(({ id }) => !busyMountIds.has(id));
-    const advancedDurabilityMounts2 = durabilityMounts.filter(
+    const hydrationMounts = input.mounts.filter(({ id }) => !busyMountIds.has(id));
+    const advancedDurabilityMounts = durabilityMounts.filter(
       ({ id }) => !busyMountIds.has(id) && (requestedIds.has(id) || !requiredIds.has(id))
     );
     const unavailableRequiredIds = requiredMounts.filter(({ id }) => busyMountIds.has(id) || !requestedIds.has(id)).map(({ id }) => id);
     const carriedMounts = carryMounts.filter(({ id }) => !busyMountIds.has(id));
     return {
       busyMountIds,
-      hydrationMounts: hydrationMounts2,
-      advancedDurabilityMounts: advancedDurabilityMounts2,
+      hydrationMounts,
+      advancedDurabilityMounts,
       skippedMountIds: [.../* @__PURE__ */ new Set([...busyMountIds, ...unavailableRequiredIds])].sort(),
-      targetReceipt: targetHead ? receiptWithMountsAtHead(receiptBeforeTransaction, targetHead, [...advancedDurabilityMounts2, ...carriedMounts], receiptMounts) : null
+      targetReceipt: targetHead ? receiptWithMountsAtHead(receiptBeforeTransaction, targetHead, [...advancedDurabilityMounts, ...carriedMounts], receiptMounts) : null
     };
   };
   const noopCandidate = computeSelection();
   if (noopCandidate.hydrationMounts.length === 0 && noopCandidate.advancedDurabilityMounts.length === 0 && noopCandidate.targetReceipt && lstatIfExists(hydrationTransactionPath(workspacePath)) === null && workspaceHydrationReceiptsEqual(receiptBeforeTransaction, noopCandidate.targetReceipt) && hydratedWorkspaceReceiptFileIsV3(workspacePath) && await workspaceBasisRefsAreCurrentAsync(workspacePath, noopCandidate.targetReceipt)) {
     return { hydratedMountIds: [], skippedMountIds: noopCandidate.skippedMountIds };
   }
-  const selection = computeSelection();
-  const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = selection;
-  const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
+  const hooks = input.hydrationHooks;
+  const context = {
+    transactionId: crypto.randomUUID(),
+    workspacePath,
+    mountIds: [...new Set([...noopCandidate.hydrationMounts, ...noopCandidate.advancedDurabilityMounts].map(({ id }) => id))].sort()
+  };
+  if (hooks) await hooks.beforeTransaction(context);
   try {
-    const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
-    const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
-    if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
-      throw new Error("Workspace hydration did not include every required mount");
-    }
-    fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
-    markHydrationTransactionDurable(workspacePath);
-    if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
-    removeHydrationTransaction(workspacePath);
-    return {
-      hydratedMountIds: hydration.hydratedMountIds,
-      skippedMountIds: selection.skippedMountIds
-    };
-  } catch (error) {
-    const transactionPath = hydrationTransactionPath(workspacePath);
-    if (lstatIfExists(transactionPath) && hydrationTransactionCommitted(transactionPath)) {
-      throw error;
-    }
+    const selection = computeSelection();
+    const { hydrationMounts, advancedDurabilityMounts, targetReceipt } = selection;
+    const { manifest, durabilityScopes } = beginHydrationTransaction(workspacePath, hydrationMounts, targetReceipt);
     try {
-      restoreHydrationTransaction(workspacePath, manifest);
+      const hydration = hydrateWorkspaceGitMountsRaw(workspacePath, hydrationMounts, { ignoreBusy: true });
+      const expectedHydratedIds = hydrationMounts.map(({ id }) => id).sort();
+      if (hydration.skippedMountIds.length > 0 || hydration.hydratedMountIds.length !== expectedHydratedIds.length || hydration.hydratedMountIds.some((id, index) => id !== expectedHydratedIds[index])) {
+        throw new Error("Workspace hydration did not include every required mount");
+      }
+      fsyncHydratedWorkspaceMounts(advancedDurabilityMounts, durabilityScopes);
+      markHydrationTransactionDurable(workspacePath);
+      if (targetReceipt) updateHydratedWorkspaceReceipt(workspacePath, targetReceipt);
       removeHydrationTransaction(workspacePath);
-    } catch (restoreError) {
-      throw new AggregateError(
-        [error, restoreError],
-        `Workspace hydration failed and its durable snapshot could not be restored: ${error instanceof Error ? error.message : String(error)}`
-      );
+      return {
+        hydratedMountIds: hydration.hydratedMountIds,
+        skippedMountIds: selection.skippedMountIds
+      };
+    } catch (error) {
+      const transactionPath = hydrationTransactionPath(workspacePath);
+      if (lstatIfExists(transactionPath) && hydrationTransactionCommitted(transactionPath)) {
+        throw error;
+      }
+      try {
+        restoreHydrationTransaction(workspacePath, manifest);
+        removeHydrationTransaction(workspacePath);
+      } catch (restoreError) {
+        throw new AggregateError(
+          [error, restoreError],
+          `Workspace hydration failed and its durable snapshot could not be restored: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      throw error;
     }
-    throw error;
+  } finally {
+    hooks?.afterTransaction(context);
   }
 }
 async function hydrateWorkspaceGitMounts(workspacePath, mounts, options = {}) {
@@ -1625,7 +1636,8 @@ async function hydrateWorkspaceGitMounts(workspacePath, mounts, options = {}) {
   return hydrateWorkspaceGitMountsTransactionally({
     workspacePath,
     mounts,
-    ignoreBusy: options.ignoreBusy
+    ignoreBusy: options.ignoreBusy,
+    hydrationHooks: options.hydrationHooks
   });
 }
 async function recoverWorkspaceGitHydration(workspacePath, mounts, options = {}) {
@@ -1665,7 +1677,8 @@ async function recoverWorkspaceGitHydration(workspacePath, mounts, options = {})
     receiptMounts: configuredBasisMounts,
     requiredMounts: hydrationTargets,
     ignoreBusy: options.ignoreBusy,
-    recordCurrentHead: true
+    recordCurrentHead: true,
+    hydrationHooks: options.hydrationHooks
   });
   void hydration;
 }
@@ -1716,7 +1729,8 @@ async function resetWorkspaceGit(input) {
     durabilityMounts: [...requiredLiveMounts, ...selected.tombstones, ...durablyAbsentMounts],
     receiptMounts: input.mounts,
     requiredMounts: requiredLiveMounts,
-    recordCurrentHead: true
+    recordCurrentHead: true,
+    hydrationHooks: input.hydrationHooks
   });
   const requiredLiveIds = requiredLiveMounts.map(({ id }) => id).sort();
   const resetHead = revParse(workspacePath, "HEAD");
@@ -1971,7 +1985,8 @@ async function synchronizeWorkspaceGit(input) {
   await recoverWorkspaceGitHydration(workspacePath, input.mounts, {
     ...deferredMountIds.size > 0 ? { deferMountIds: deferredMountIds } : {},
     preserveResolutionInProgress,
-    preserveStaleBases: true
+    preserveStaleBases: true,
+    hydrationHooks: input.hydrationHooks
   });
   const selected = activeMounts(input.mounts);
   const projectionMutationTokens = new Map(
@@ -2097,7 +2112,8 @@ async function synchronizeWorkspaceGit(input) {
       carryMounts: uncoveredCompletionMounts.filter(({ id }) => unchangedMountIds.has(id)),
       receiptMounts: completionReceiptMounts,
       requiredMounts: uncoveredRequiredLiveMounts.filter(({ id }) => !unchangedMountIds.has(id)),
-      recordCurrentHead: true
+      recordCurrentHead: true,
+      hydrationHooks: input.hydrationHooks
     });
     for (const id of hydration.skippedMountIds) cycleSkippedMountIds.add(id);
     refreshCycleSkippedMounts(completionReceiptMounts);

package/dist/types/main.d.ts

@@ -2,6 +2,7 @@
 import { Database } from "bun:sqlite";
 import type { WorkerGitIdentity } from "./git-identity";
 import { configureGitHubRegistryAuthFiles, type PreparedPrivateAuthFileGeneration } from "./registry-auth";
+import { type WorkspaceHydrationTransactionHooks } from "./workspace-git-sync";
 type WorkerProjectConfig = {
     projectId: string;
     checkoutPathSegments: [namespace: string, project: string];
@@ -23,6 +24,11 @@ type WorkerProjectConfig = {
         baseCommitHash: string;
     }>;
 };
+type WorkerAheadOfOriginBranch = {
+    projectId: string;
+    branchName: string;
+    ahead: number;
+};
 type WorkerLifecycleProgress = {
     phase: "starting" | "recovering" | "configuring" | "syncing" | "ready" | "failed";
     operationId: string;
@@ -39,9 +45,28 @@ declare function workerServerHeartbeatAction(input: {
     timeoutMs: number;
     watchdogSweepDelayed: boolean;
 }): "wait" | "start_probe" | "terminate";
+/**
+ * A hydration transaction blocks this event loop until it ends, so no pong,
+ * progress, or result can leave the process while it runs; on a slow disk
+ * that is hours. Declare a hydration heartbeat lease first: the server keeps
+ * the control socket open and defers the affected request deadlines while the
+ * lease is active instead of reading the silence as a dead worker, which is
+ * what turned one slow hydration into a mandatory canonical reset (incident
+ * 3bccab03). Bun writes the frame to the socket synchronously; the extra
+ * event-loop turn lets control messages that were already queued run before
+ * the busy observation that precedes the transaction body.
+ */
+declare function createWorkspaceHydrationLeaseHooks(send: (message: Extract<WorkerClientMessage, {
+    type: "heartbeat_lease";
+}>) => void, options?: {
+    yieldToEventLoop?: () => Promise<void>;
+    log?: (line: string) => void;
+    now?: () => number;
+}): WorkspaceHydrationTransactionHooks;
 export declare const workerLifecycleTestHarness: {
     boundedWorkerLifecycleProgress: typeof boundedWorkerLifecycleProgress;
     workerServerHeartbeatAction: typeof workerServerHeartbeatAction;
+    createWorkspaceHydrationLeaseHooks: typeof createWorkspaceHydrationLeaseHooks;
 };
 type WorkspaceSyncTrigger = {
     type: "connect" | "inbound_head" | "write" | "edit" | "shell_inline" | "process_terminal" | "process_cancel" | "periodic" | "manual" | "remediation" | "remediation_confirm" | "remediation_reset";
@@ -103,6 +128,144 @@ export type WorkerSessionTarget = {
     ownerUserId: string;
     rootProfile: "visible_projects" | "canonical_sync";
 };
+type WorkerClientMessage = {
+    type: "hello";
+    hostInfo?: Record<string, unknown>;
+    startupReady?: boolean;
+} | {
+    type: "worker_progress";
+    progress: WorkerLifecycleProgress;
+} | {
+    type: "heartbeat_lease";
+    operationId: string;
+    active: boolean;
+    /** A hydration transaction may block the worker for hours; the server bounds it separately from preparation leases. */
+    kind?: "hydration";
+} | {
+    type: "startup_ready";
+} | {
+    type: "active_processes";
+    processes: Array<{
+        runId: string;
+        target: WorkerSessionTarget;
+        sessionId: string;
+        platform: string;
+        arch: string;
+        mode: "foreground" | "detached";
+        pid?: number;
+        processGroupId?: number;
+        credentialId?: string;
+        argv: string[];
+        command: string;
+        cwd?: string;
+        startedAt: string;
+        interactive?: boolean;
+        workspaceEffect?: "none";
+    }>;
+} | {
+    type: "pty_opened";
+    requestId: string;
+    ptyId: string;
+} | {
+    type: "pty_output";
+    ptyId: string;
+    data: string;
+} | {
+    type: "pty_exit";
+    ptyId: string;
+    exitCode: number;
+    signal?: number | string;
+} | {
+    type: "pty_error";
+    ptyId: string;
+    requestId?: string;
+    error: string;
+} | {
+    type: "operation_result";
+    requestId: string;
+    result?: WorkerOperationResult;
+    error?: string;
+} | {
+    type: "exec_result";
+    requestId: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs?: number;
+    error?: string;
+} | {
+    type: "exec_accepted";
+    requestId: string;
+    runId: string;
+} | {
+    type: "exec_started";
+    requestId: string;
+    runId: string;
+    cwd: string;
+    pid?: number;
+    processGroupId?: number;
+} | {
+    type: "exec_start_error";
+    requestId: string;
+    runId: string;
+    error: string;
+} | {
+    type: "exec_output";
+    runId: string;
+    stream: "stdout" | "stderr";
+    data: string;
+} | {
+    type: "exec_exit";
+    runId: string;
+    exitCode: number;
+    durationMs?: number;
+    timedOut?: boolean;
+    workspaceEffect?: "none";
+    canonicalWorkspaceHead?: string;
+} | {
+    type: "exec_error";
+    runId: string;
+    error: string;
+    durationMs?: number;
+    workspaceEffect?: "none";
+    canonicalWorkspaceHead?: string;
+} | {
+    type: "cancel_result";
+    requestId: string;
+    runId: string;
+    cancelled: boolean;
+    message?: string;
+} | {
+    type: "pong";
+} | {
+    type: "workspace_configured";
+    requestId: string;
+    result: WorkspaceSyncResult;
+    pendingCheckouts: Array<{
+        projectId: string;
+        branchName: string;
+    }>;
+    aheadOfOriginBranches: WorkerAheadOfOriginBranch[];
+    deferredWorkspaceSyncForIncidentId?: string;
+} | {
+    type: "workspace_sync_started";
+    attemptId: string;
+} | {
+    type: "workspace_sync_result";
+    requestId?: string;
+    result: WorkspaceSyncResult;
+} | {
+    type: "session_artifacts_sync_result";
+    requestId: string;
+    sessionId: string;
+    error?: string;
+} | {
+    type: "update_clis_result";
+    requestId: string;
+    installedWorkerVersion?: string;
+    installedR5dctlVersion?: string;
+    error?: string;
+};
 type WorkerServerMessage = {
     type: "connected";
     label: string;
@@ -371,6 +534,23 @@ type WorkerViewFileBytesResult = {
     width: number;
     height: number;
 };
+type WorkerExecStdinAck = {
+    type: "exec_stdin";
+    runId: string;
+    bytesWritten: number;
+    eof: boolean;
+};
+type WorkerCreateProjectBranchResult = {
+    type: "create_project_branch";
+    branchId: string;
+    branchName: string;
+    baseCommitHash: string;
+};
+type WorkerDeleteProjectBranchResult = {
+    type: "delete_project_branch";
+    branchId: string;
+    branchName: string;
+};
 type WorkerCodeEntry = {
     name: string;
     type: "file" | "directory";
@@ -389,6 +569,7 @@ type WorkerCodeReadResult = {
     mtime: string;
     base64: string;
 };
+type WorkerOperationResult = WorkerReadFileResult | WorkerWriteFileResult | WorkerEditFileResult | WorkerGrepResult | WorkerFindResult | WorkerLsResult | WorkerViewFileBytesResult | WorkerExecStdinAck | WorkerCreateProjectBranchResult | WorkerDeleteProjectBranchResult | WorkerCodeListResult | WorkerCodeReadResult;
 declare class WorkspaceSyncAdmissionChangedError extends Error {
     readonly name = "WorkspaceSyncAdmissionChangedError";
 }

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

@@ -49,6 +49,26 @@ export type WorkspaceGitMount = {
  * unready state for concurrent visible work.
  */
 export declare function workspaceGitMountsForRemediation(mounts: readonly WorkspaceGitMount[]): WorkspaceGitMount[];
+export type WorkspaceHydrationTransactionContext = {
+    /** Unique per transaction; pairs the begin and end observations. */
+    transactionId: string;
+    workspacePath: string;
+    /** Mounts the transaction may hydrate or carry across the durability barrier. */
+    mountIds: string[];
+};
+/**
+ * Observes the synchronous body of a hydration transaction (snapshot,
+ * hydration pass, durability barrier, receipt). That body deliberately never
+ * yields, so the worker cannot answer control-socket messages while it runs,
+ * and on a slow disk it can run for hours. `beforeTransaction` is awaited
+ * after the last asynchronous precheck and before the final busy observation,
+ * so it may announce the operation and yield once; `afterTransaction` runs
+ * after the body committed or rolled back.
+ */
+export type WorkspaceHydrationTransactionHooks = {
+    beforeTransaction: (context: WorkspaceHydrationTransactionContext) => Promise<void> | void;
+    afterTransaction: (context: WorkspaceHydrationTransactionContext) => void;
+};
 export type WorkspaceGitSyncOutcome = "no_change" | "updated" | "pushed" | "large_diff_blocked" | "conflict_blocked";
 export type WorkspaceGitSyncResult = {
     outcome: WorkspaceGitSyncOutcome;
@@ -137,6 +157,7 @@ export declare function ensureWorkspaceGitClone(input: {
 declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): void;
 export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[], options?: {
     ignoreBusy?: boolean;
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<{
     hydratedMountIds: string[];
     skippedMountIds: string[];
@@ -146,6 +167,7 @@ export declare function recoverWorkspaceGitHydration(workspacePath: string, moun
     deferMountIds?: ReadonlySet<string>;
     preserveResolutionInProgress?: boolean;
     preserveStaleBases?: boolean;
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<void>;
 export declare function resetWorkspaceGit(input: {
     workspacePath: string;
@@ -157,6 +179,7 @@ export declare function resetWorkspaceGit(input: {
         email: string;
     };
     mounts: readonly WorkspaceGitMount[];
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<{
     startingHead: string | null;
     localHead: string | null;
@@ -194,6 +217,8 @@ export declare function synchronizeWorkspaceGit(input: {
         publishedHead: string;
         activeMountIds: string[];
     }) => void | Promise<void>;
+    /** Announces each synchronous hydration transaction of this cycle; see WorkspaceHydrationTransactionHooks. */
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<WorkspaceGitSyncResult>;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;

package/package.json

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