@ricsam/r5d-worker 0.0.97 → 0.0.100

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

@@ -6,7 +6,15 @@ import {
   mergeWorkspaceProjectionMount,
   workspaceMergeProjectionSupport
 } from "./workspace-merge-projection.mjs";
-import { mirrorWorkingTree } from "./working-tree-mirror.mjs";
+import {
+  captureWorkingTreeMirrorPlan,
+  fsyncWorkingTreePaths,
+  inspectWorkingTree,
+  mirrorWorkingTree,
+  normalizeWorkingTreeRelativePath,
+  planWorkingTreeMirror,
+  restoreWorkingTreeMirrorScope
+} from "./working-tree-mirror.mjs";
 import { assertManagedDirectoryPath } from "./workspace-mount-boundary.mjs";
 const WORKSPACE_GIT_BRANCH = "main";
 const MAX_WORKSPACE_GIT_DIFF_BYTES = 5 * 1024 * 1024;
@@ -909,7 +917,7 @@ function parseHydrationTransactionManifest(transactionPath) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const candidate = parsed;
-  if (candidate.version !== 2 && candidate.version !== 3 || !Array.isArray(candidate.mounts)) {
+  if (candidate.version !== 2 && candidate.version !== 3 && candidate.version !== 4 || !Array.isArray(candidate.mounts)) {
     throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
   }
   const parseReceipt = (rawReceipt) => {
@@ -922,6 +930,25 @@ function parseHydrationTransactionManifest(transactionPath) {
   };
   const targetReceipt = parseReceipt(candidate.targetReceipt);
   const receiptBefore = parseReceipt(candidate.receiptBefore);
+  const parseScope = (rawScope, existed) => {
+    if (rawScope === void 0) return void 0;
+    if (candidate.version !== 4 || !existed || !rawScope || typeof rawScope !== "object") {
+      throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+    }
+    const parsePaths = (rawPaths) => {
+      if (!Array.isArray(rawPaths)) throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+      const seen = /* @__PURE__ */ new Set();
+      return rawPaths.map((rawPath) => {
+        if (typeof rawPath !== "string" || normalizeWorkingTreeRelativePath(rawPath) !== rawPath || seen.has(rawPath)) {
+          throw new Error(`Workspace hydration transaction manifest is invalid: ${manifestPath}`);
+        }
+        seen.add(rawPath);
+        return rawPath;
+      });
+    };
+    const { absent, trees } = rawScope;
+    return { absent: parsePaths(absent), trees: parsePaths(trees) };
+  };
   const seenIds = /* @__PURE__ */ new Set();
   const seenSnapshots = /* @__PURE__ */ new Set();
   const mounts = candidate.mounts.map((rawMount) => {
@@ -938,10 +965,20 @@ function parseHydrationTransactionManifest(transactionPath) {
     }
     seenIds.add(mount.id);
     seenSnapshots.add(mount.snapshotName);
-    return mount;
+    const scope = parseScope(rawMount.scope, mount.existed);
+    return {
+      id: mount.id,
+      incarnationKey: mount.incarnationKey,
+      sourcePath: mount.sourcePath,
+      durabilityRootPath: mount.durabilityRootPath,
+      workspaceRelativePath: mount.workspaceRelativePath,
+      existed: mount.existed,
+      snapshotName: mount.snapshotName,
+      ...scope ? { scope } : {}
+    };
   });
   return {
-    version: 3,
+    version: candidate.version === 4 ? 4 : 3,
     targetReceipt,
     receiptBefore,
     mounts
@@ -963,6 +1000,7 @@ function hydrationTransactionCommitted(transactionPath) {
 }
 function restoreHydrationTransaction(workspacePath, manifest) {
   const transactionPath = hydrationTransactionPath(workspacePath);
+  const durabilityScopes = /* @__PURE__ */ new Map();
   for (const mount of manifest.mounts) {
     assertManagedDirectoryPath({
       trustedRoot: mount.durabilityRootPath,
@@ -978,6 +1016,11 @@ function restoreHydrationTransaction(workspacePath, manifest) {
     if (!snapshotStatus.isDirectory() || snapshotStatus.isSymbolicLink()) {
       throw new Error(`Workspace hydration snapshot is not a regular directory: ${snapshotPath}`);
     }
+    if (mount.scope) {
+      const restored = restoreWorkingTreeMirrorScope({ snapshotRoot: snapshotPath, targetRoot: mount.sourcePath, scope: mount.scope });
+      durabilityScopes.set(mount.id, restored.paths);
+      continue;
+    }
     mirrorWorkingTree({ sourceRoot: snapshotPath, targetRoot: mount.sourcePath, sourceMode: "all", deletionMode: "all" });
   }
   fsyncHydratedWorkspaceMounts(
@@ -986,7 +1029,8 @@ function restoreHydrationTransaction(workspacePath, manifest) {
       hydrationIncarnationKey: mount.incarnationKey,
       sourceMode: "all",
       hydrateDeletionMode: "all"
-    }))
+    })),
+    durabilityScopes
   );
 }
 function recoverPendingHydrationTransaction(workspacePath) {
@@ -1030,57 +1074,80 @@ function beginHydrationTransaction(workspacePath, mounts, targetReceipt) {
   const transactionPath = hydrationTransactionPath(workspacePath);
   const stagingPath = path.join(stateDirectory, `.workspace-hydration-transaction.${process.pid}.${crypto.randomUUID()}.tmp`);
   fs.mkdirSync(stagingPath, { mode: 448 });
+  const durabilityScopes = /* @__PURE__ */ new Map();
   try {
     const snapshotRoot = path.join(stagingPath, "mounts");
     fs.mkdirSync(snapshotRoot, { mode: 448 });
-    const manifest = {
-      version: 3,
-      targetReceipt,
-      receiptBefore: readHydratedWorkspaceReceipt(workspacePath),
-      mounts: mounts.map((mount, index) => {
-        const sourcePath = path.resolve(mount.sourcePath);
-        const durabilityRootPath = path.resolve(mount.durabilityRootPath);
+    const receiptBefore = readHydratedWorkspaceReceipt(workspacePath);
+    const manifestMounts = mounts.map((mount, index) => {
+      const sourcePath = path.resolve(mount.sourcePath);
+      const durabilityRootPath = path.resolve(mount.durabilityRootPath);
+      assertManagedDirectoryPath({
+        trustedRoot: durabilityRootPath,
+        candidate: sourcePath,
+        label: `Workspace hydration snapshot mount ${mount.id}`
+      });
+      const sourceStatus = lstatIfExists(sourcePath);
+      if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
+        throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
+      }
+      const snapshotName = String(index);
+      const snapshotPath = path.join(snapshotRoot, snapshotName);
+      fs.mkdirSync(snapshotPath, { mode: 448 });
+      let scope;
+      if (sourceStatus && mount.hydrateDeletionMode === "git") {
+        const outerPath = workspaceMountOuterPath(workspacePath, mount);
         assertManagedDirectoryPath({
-          trustedRoot: durabilityRootPath,
-          candidate: sourcePath,
-          label: `Workspace hydration snapshot mount ${mount.id}`
+          trustedRoot: workspacePath,
+          candidate: outerPath,
+          label: `Workspace mount ${mount.id} outer source`
         });
-        const sourceStatus = lstatIfExists(sourcePath);
-        if (sourceStatus && (!sourceStatus.isDirectory() || sourceStatus.isSymbolicLink())) {
-          throw new Error(`Workspace hydration snapshot source is not a regular directory: ${sourcePath}`);
-        }
-        const snapshotName = String(index);
-        const snapshotPath = path.join(snapshotRoot, snapshotName);
-        fs.mkdirSync(snapshotPath, { mode: 448 });
-        if (sourceStatus) {
-          mirrorWorkingTree({
-            sourceRoot: sourcePath,
-            targetRoot: snapshotPath,
-            sourceMode: "all",
-            deletionMode: "all",
-            // This tree is still private and the source authority is untouched.
-            // The single recursive barrier below makes the complete snapshot
-            // durable before its directory entry is published or hydration starts.
-            durability: "deferred_private_staging"
-          });
-        }
-        return {
-          id: mount.id,
-          incarnationKey: mount.hydrationIncarnationKey,
-          sourcePath,
-          durabilityRootPath,
-          workspaceRelativePath: mount.workspaceRelativePath,
-          existed: Boolean(sourceStatus),
-          snapshotName
-        };
-      })
+        const plan = planWorkingTreeMirror({ sourceRoot: outerPath, targetRoot: sourcePath, sourceMode: "all", deletionMode: "git" });
+        scope = captureWorkingTreeMirrorPlan({
+          plan,
+          targetRoot: sourcePath,
+          snapshotRoot: snapshotPath,
+          // Same private-staging deferral as the complete snapshot below.
+          durability: "deferred_private_staging"
+        });
+        durabilityScopes.set(mount.id, [...plan.desired.keys()]);
+      } else if (sourceStatus) {
+        mirrorWorkingTree({
+          sourceRoot: sourcePath,
+          targetRoot: snapshotPath,
+          sourceMode: "all",
+          deletionMode: "all",
+          // This tree is still private and the source authority is untouched.
+          // The single recursive barrier below makes the complete snapshot
+          // durable before its directory entry is published or hydration starts.
+          durability: "deferred_private_staging"
+        });
+      }
+      return {
+        id: mount.id,
+        incarnationKey: mount.hydrationIncarnationKey,
+        sourcePath,
+        durabilityRootPath,
+        workspaceRelativePath: mount.workspaceRelativePath,
+        existed: Boolean(sourceStatus),
+        snapshotName,
+        ...scope ? { scope } : {}
+      };
+    });
+    const manifest = {
+      // Older workers reject version 4, so a scoped snapshot can never be
+      // replayed as a complete copy after a downgrade.
+      version: manifestMounts.some((mount) => mount.scope) ? 4 : 3,
+      targetReceipt,
+      receiptBefore,
+      mounts: manifestMounts
     };
     writePrivateFileDurably(path.join(stagingPath, "manifest.json"), `${JSON.stringify(manifest)}
 `);
     fsyncTree(stagingPath);
     fs.renameSync(stagingPath, transactionPath);
     fsyncDirectory(stateDirectory);
-    return manifest;
+    return { manifest, durabilityScopes };
   } catch (error) {
     fs.rmSync(stagingPath, { recursive: true, force: true });
     fsyncDirectory(stateDirectory);
@@ -1092,7 +1159,11 @@ function markHydrationTransactionDurable(workspacePath) {
   writePrivateFileDurably(path.join(transactionPath, "committed"), "committed\n");
   fsyncDirectory(transactionPath);
 }
-function fsyncHydratedWorkspaceMount(mount) {
+function gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus) {
+  if (mount.hydrateDeletionMode !== "git" || !sourceStatus.isDirectory() || !lstatIfExists(path.join(sourcePath, ".git"))) return null;
+  return [...inspectWorkingTree(sourcePath, "git").keys()];
+}
+function fsyncHydratedWorkspaceMount(mount, scope) {
   assertManagedDirectoryPath({
     trustedRoot: mount.durabilityRootPath,
     candidate: mount.sourcePath,
@@ -1117,7 +1188,17 @@ function fsyncHydratedWorkspaceMount(mount) {
       fs.closeSync(descriptor);
     }
   };
-  if (fs.existsSync(mount.sourcePath)) syncEntry(mount.sourcePath, true);
+  const sourcePath = path.resolve(mount.sourcePath);
+  const sourceStatus = lstatIfExists(sourcePath);
+  if (sourceStatus) {
+    const paths = scope ?? gitVisibleDurabilityPaths(mount, sourcePath, sourceStatus);
+    if (paths) {
+      if (!sourceStatus.isDirectory()) throw new Error(`Workspace mount ${mount.id} source is not a regular directory: ${sourcePath}`);
+      fsyncWorkingTreePaths(sourcePath, paths);
+    } else {
+      syncEntry(sourcePath, true);
+    }
+  }
   const durabilityRoot = path.resolve(mount.durabilityRootPath);
   let boundaryParent = path.dirname(path.resolve(mount.sourcePath));
   while (true) {
@@ -1136,8 +1217,8 @@ function fsyncHydratedWorkspaceMount(mount) {
     boundaryParent = nextParent;
   }
 }
-function fsyncHydratedWorkspaceMounts(mounts) {
-  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount);
+function fsyncHydratedWorkspaceMounts(mounts, scopes = /* @__PURE__ */ new Map()) {
+  for (const mount of mounts) fsyncHydratedWorkspaceMount(mount, scopes.get(mount.id));
 }
 function workspaceIsShallow(workspacePath) {
   return gitResult(workspacePath, ["rev-parse", "--is-shallow-repository"]).stdout === "true";
@@ -1386,6 +1467,9 @@ function restoreDeferredWorkspaceMountsFromHead(workspacePath, mounts) {
     }
   }
 }
+function workspaceMountOuterPath(workspacePath, mount) {
+  return path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+}
 function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
   const hydratedMountIds = [];
   const skippedMountIds = [];
@@ -1394,7 +1478,7 @@ function hydrateWorkspaceGitMountsRaw(workspacePath, mounts, options = {}) {
       skippedMountIds.push(mount.id);
       continue;
     }
-    const sourceRoot = path.join(workspacePath, ...mount.workspaceRelativePath.replace(/\\/g, "/").split("/"));
+    const sourceRoot = workspaceMountOuterPath(workspacePath, mount);
     assertManagedDirectoryPath({
       trustedRoot: workspacePath,
       candidate: sourceRoot,
@@ -1480,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 = 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);
-    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 = {}) {
@@ -1541,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 = {}) {
@@ -1581,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;
 }
@@ -1632,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");
@@ -1887,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(
@@ -2013,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";
 }