@ricsam/r5d-worker 0.0.123 → 0.0.124

package/dist/mjs/package.json

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

package/dist/mjs/project-checkout-garbage.mjs

@@ -19,11 +19,33 @@ function stageProjectCheckoutForDeletion(projectRoot, branchName, checkoutPath)
   fs.renameSync(checkoutPath, target);
   return target;
 }
+function stageProjectForDeletion(projectsRoot, projectRoot) {
+  const root = path.resolve(projectsRoot);
+  const resolved = path.resolve(projectRoot);
+  const relative = path.relative(root, resolved);
+  const segments = relative.split(path.sep);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative) || segments.length !== 2 || segments.some((segment) => !segment || segment.startsWith("."))) {
+    throw new Error(`Cannot stage ${projectRoot} for deletion: not a project root under ${projectsRoot}`);
+  }
+  if (!isRealDirectory(resolved)) throw new Error(`Cannot stage ${projectRoot} for deletion: not a directory`);
+  const garbageRoot = path.join(root, segments[0], PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+  fs.mkdirSync(garbageRoot, { recursive: true });
+  if (!isRealDirectory(garbageRoot)) throw new Error(`Cannot stage ${projectRoot} for deletion: ${garbageRoot} is not a directory`);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const target = path.join(garbageRoot, `${segments[1]}-${timestamp}-${randomUUID().slice(0, 8)}`);
+  fs.renameSync(resolved, target);
+  return target;
+}
 function isStagedProjectCheckoutPath(projectsRoot, candidate) {
   const relative = path.relative(path.resolve(projectsRoot), path.resolve(candidate));
   if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return false;
   const segments = relative.split(path.sep);
-  return segments.length === 4 && segments[2] === PROJECT_DELETED_CHECKOUTS_DIRECTORY && segments[3] !== "" && !segments[3].startsWith(".");
+  const entry = segments[segments.length - 1];
+  if (!entry || entry.startsWith(".")) return false;
+  if (segments.length === 4)
+    return segments[2] === PROJECT_DELETED_CHECKOUTS_DIRECTORY && !segments[0].startsWith(".") && !segments[1].startsWith(".");
+  if (segments.length === 3) return segments[1] === PROJECT_DELETED_CHECKOUTS_DIRECTORY && !segments[0].startsWith(".");
+  return false;
 }
 function ownedStagedPath(projectsRoot, candidate) {
   const root = path.resolve(projectsRoot);
@@ -56,6 +78,11 @@ function discoverStagedProjectCheckouts(projectsRoot) {
   const staged = [];
   for (const namespace of realDirectoryEntries(root)) {
     if (namespace.startsWith(".")) continue;
+    const namespaceGarbageRoot = path.join(root, namespace, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+    for (const entry of realDirectoryEntries(namespaceGarbageRoot)) {
+      const candidate = path.join(namespaceGarbageRoot, entry);
+      if (ownedStagedPath(root, candidate)) staged.push(candidate);
+    }
     for (const project of realDirectoryEntries(path.join(root, namespace))) {
       if (project.startsWith(".")) continue;
       const garbageRoot = path.join(root, namespace, project, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
@@ -146,5 +173,6 @@ export {
   isStagedProjectCheckoutPath,
   ownedStagedPath,
   removeStagedProjectCheckout,
-  stageProjectCheckoutForDeletion
+  stageProjectCheckoutForDeletion,
+  stageProjectForDeletion
 };

package/dist/mjs/project-workspace-state.mjs

@@ -280,47 +280,63 @@ function lstatIfExists(targetPath) {
     throw error;
   }
 }
-function ensureDurableStateRoot(stateRoot) {
+async function fsyncDirectoryAsync(directory) {
+  const handle = await fs.promises.open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function lstatIfExistsAsync(targetPath) {
+  try {
+    return await fs.promises.lstat(targetPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function ensureDurableStateRoot(stateRoot) {
   const resolvedStateRoot = path.resolve(stateRoot);
   let existingAncestor = resolvedStateRoot;
-  while (!lstatIfExists(existingAncestor)) {
+  while (!await lstatIfExistsAsync(existingAncestor)) {
     const parent = path.dirname(existingAncestor);
     if (parent === existingAncestor) throw new Error(`Project workspace state has no existing ancestor: ${resolvedStateRoot}`);
     existingAncestor = parent;
   }
-  const ancestorStat = lstatIfExists(existingAncestor);
+  const ancestorStat = await lstatIfExistsAsync(existingAncestor);
   if (!ancestorStat || ancestorStat.isSymbolicLink() || !ancestorStat.isDirectory()) {
     throw new Error(`Project workspace state must descend from a real directory: ${resolvedStateRoot}`);
   }
-  fs.mkdirSync(resolvedStateRoot, { recursive: true, mode: 448 });
+  await fs.promises.mkdir(resolvedStateRoot, { recursive: true, mode: 448 });
   let current = resolvedStateRoot;
   while (true) {
-    const stat = lstatIfExists(current);
+    const stat = await lstatIfExistsAsync(current);
     if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) {
       throw new Error(`Project workspace state path must be a real directory: ${current}`);
     }
-    fsyncDirectory(current);
+    await fsyncDirectoryAsync(current);
     if (current === existingAncestor) break;
     current = path.dirname(current);
   }
 }
-function writeStateAtomically(stateRoot, statePath, state, afterStateRootFsync) {
-  ensureDurableStateRoot(stateRoot);
+async function writeStateAtomically(stateRoot, statePath, state, afterStateRootFsync) {
+  await ensureDurableStateRoot(stateRoot);
   afterStateRootFsync?.();
   const temporaryPath = path.join(stateRoot, `.${PROJECT_WORKSPACE_STATE_FILE}.${process.pid}.${randomUUID()}.tmp`);
-  let descriptor;
+  let handle;
   try {
-    descriptor = fs.openSync(temporaryPath, "wx", 384);
-    fs.writeFileSync(descriptor, `${JSON.stringify(normalizeState(state), null, 2)}
+    handle = await fs.promises.open(temporaryPath, "wx", 384);
+    await handle.writeFile(`${JSON.stringify(normalizeState(state), null, 2)}
 `, "utf8");
-    fs.fsyncSync(descriptor);
-    fs.closeSync(descriptor);
-    descriptor = void 0;
-    fs.renameSync(temporaryPath, statePath);
-    fsyncDirectory(stateRoot);
+    await handle.sync();
+    await handle.close();
+    handle = void 0;
+    await fs.promises.rename(temporaryPath, statePath);
+    await fsyncDirectoryAsync(stateRoot);
   } finally {
-    if (descriptor !== void 0) fs.closeSync(descriptor);
-    fs.rmSync(temporaryPath, { force: true });
+    if (handle !== void 0) await handle.close();
+    await fs.promises.rm(temporaryPath, { force: true });
   }
 }
 function createBranchTombstone(project, branchName) {
@@ -696,7 +712,7 @@ class ProjectWorkspaceStateStore {
       locallyPendingCreatedBranches: state.locallyPendingCreatedBranches
     });
   }
-  reconcile(input) {
+  async reconcile(input) {
     const previous = readState(this.statePath);
     const authoritativeDesiredProjects = normalizeDesiredProjects(input.desiredProjects);
     for (const project of authoritativeDesiredProjects) {
@@ -772,11 +788,11 @@ class ProjectWorkspaceStateStore {
       enabledRepositoryTransitions: previous.enabledRepositoryTransitions.filter(({ projectId }) => authoritativeProjectIds.has(projectId)),
       tombstones
     });
-    writeStateAtomically(this.stateRoot, this.statePath, nextState);
+    await writeStateAtomically(this.stateRoot, this.statePath, nextState);
     return stateView(this.projectsRoot, nextState);
   }
   /** Record a successful enabled reseed without letting disabled config consume it. */
-  recordEnabledRepositoryTransition(input) {
+  async recordEnabledRepositoryTransition(input) {
     const [transition] = normalizeEnabledRepositoryTransitions([input]);
     const state = readState(this.statePath);
     if (!state.desiredProjects.some(({ projectId }) => projectId === transition.projectId)) {
@@ -785,11 +801,11 @@ class ProjectWorkspaceStateStore {
     state.enabledRepositoryTransitions = state.enabledRepositoryTransitions.filter(({ projectId }) => projectId !== transition.projectId);
     state.enabledRepositoryTransitions.push(transition);
     state.enabledRepositoryTransitions.sort((left, right) => left.projectId.localeCompare(right.projectId));
-    writeStateAtomically(this.stateRoot, this.statePath, state);
+    await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
   /** Persist the create intent before invoking Git so a crash cannot orphan an untracked worktree. */
-  recordPendingCreatedBranch(input) {
+  async recordPendingCreatedBranch(input) {
     const [pending] = normalizePendingCreatedBranches([input]);
     const state = readState(this.statePath);
     const existingPending = state.locallyPendingCreatedBranches.find(
@@ -812,11 +828,11 @@ class ProjectWorkspaceStateStore {
     state.locallyPendingCreatedBranches.sort(
       (left, right) => left.projectId.localeCompare(right.projectId) || left.branchName.localeCompare(right.branchName)
     );
-    writeStateAtomically(this.stateRoot, this.statePath, state);
+    await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
   /** Roll back an intent only when Git failed before creating its branch. */
-  rollbackPendingCreatedBranch(input) {
+  async rollbackPendingCreatedBranch(input) {
     const [pending] = normalizePendingCreatedBranches([input]);
     const state = readState(this.statePath);
     const key = pendingCreatedBranchKey(pending);
@@ -829,11 +845,11 @@ class ProjectWorkspaceStateStore {
     );
     const project = state.desiredProjects.find(({ projectId }) => projectId === pending.projectId);
     if (project) project.branches = project.branches.filter(({ branchName }) => branchName !== pending.branchName);
-    writeStateAtomically(this.stateRoot, this.statePath, state);
+    await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
   /** Clear a create intent after an authoritative desired config contains it. */
-  clearPendingCreatedBranch(input) {
+  async clearPendingCreatedBranch(input) {
     const [pending] = normalizePendingCreatedBranches([input]);
     const state = readState(this.statePath);
     const key = pendingCreatedBranchKey(pending);
@@ -843,11 +859,11 @@ class ProjectWorkspaceStateStore {
     state.locallyPendingCreatedBranches = state.locallyPendingCreatedBranches.filter(
       (candidate) => pendingCreatedBranchKey(candidate) !== key
     );
-    writeStateAtomically(this.stateRoot, this.statePath, state);
+    await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
   /** Persist a branch tombstone before mutating its linked worktree or local ref. */
-  beginBranchDeletion(input) {
+  async beginBranchDeletion(input) {
     const [target] = normalizePendingCreatedBranches([input]);
     const state = readState(this.statePath);
     const project = state.desiredProjects.find(({ projectId }) => projectId === target.projectId);
@@ -863,10 +879,10 @@ class ProjectWorkspaceStateStore {
     state.locallyPendingCreatedBranches = state.locallyPendingCreatedBranches.filter(
       (candidate) => pendingCreatedBranchKey(candidate) !== key
     );
-    writeStateAtomically(this.stateRoot, this.statePath, state);
+    await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
-  recordTreePublication(input) {
+  async recordTreePublication(input) {
     if (!GIT_OBJECT_ID_PATTERN.test(input.publishedHead)) throw new Error("Invalid published workspace head");
     const state = readState(this.statePath);
     const ids = new Set(input.tombstoneIds);
@@ -879,10 +895,10 @@ class ProjectWorkspaceStateStore {
     state.tombstones = state.tombstones.filter(
       (tombstone) => !tombstone.treePublishedHead || tombstone.kind === "branch" && !branchIsCurrentlyDesired(state.desiredProjects, tombstone.projectId, tombstone.branchName)
     );
-    if (changed) writeStateAtomically(this.stateRoot, this.statePath, state);
+    if (changed) await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
-  recordMirrorRefDeletion(input) {
+  async recordMirrorRefDeletion(input) {
     validateManagedBranchName(input.branchName);
     const state = readState(this.statePath);
     const tombstone = state.tombstones.find(({ id }) => id === input.tombstoneId);
@@ -901,13 +917,13 @@ class ProjectWorkspaceStateStore {
     if (branchNames.every((branchName) => tombstone.mirrorRefsDeleted.includes(branchName))) {
       state.tombstones = state.tombstones.filter(({ id }) => id !== tombstone.id);
     }
-    writeStateAtomically(this.stateRoot, this.statePath, state);
+    await writeStateAtomically(this.stateRoot, this.statePath, state);
     return stateView(this.projectsRoot, state);
   }
 }
 const projectWorkspaceStateTestHarness = {
   writeEmptyStateAtDurableRootBoundary(stateRoot, afterStateRootFsync) {
-    writeStateAtomically(stateRoot, path.join(stateRoot, PROJECT_WORKSPACE_STATE_FILE), EMPTY_STATE, afterStateRootFsync);
+    return writeStateAtomically(stateRoot, path.join(stateRoot, PROJECT_WORKSPACE_STATE_FILE), EMPTY_STATE, afterStateRootFsync);
   }
 };
 export {

package/dist/mjs/project-worktrees.mjs

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { gitCredentialUsernameConfigKey, gitTransportSecurityArgs, workerGitProcessEnvironment } from "./git-process-environment.mjs";
 import { validateManagedBranchName } from "./managed-paths.mjs";
-import { stageProjectCheckoutForDeletion } from "./project-checkout-garbage.mjs";
+import { stageProjectCheckoutForDeletion, stageProjectForDeletion } from "./project-checkout-garbage.mjs";
 import {
   canonicalizeLocalProjectMirrorRefs,
   parseProjectMirrorRefListing,
@@ -14,6 +14,7 @@ import {
   projectMirrorRefsTokens
 } from "./project-mirror-refs-token.mjs";
 import { mirrorWorkingTree } from "./working-tree-mirror.mjs";
+import { workspaceFilesystemExecutor } from "./workspace-filesystem-executor.mjs";
 const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 const PROJECT_WORKTREE_SNAPSHOT_MANIFEST = "transaction.json";
 const PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION = 1;
@@ -429,7 +430,7 @@ function assertNoOutstandingSnapshotForProject(temporaryRoot, projectRoot) {
     }
   }
 }
-function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress, scope = "project") {
+function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress, scope, ownerSessionId) {
   const resolvedProjectRoot = path.resolve(projectRoot);
   const resolvedTemporaryRoot = path.resolve(temporaryRoot ?? os.tmpdir());
   assertNoOutstandingSnapshotForProject(resolvedTemporaryRoot, resolvedProjectRoot);
@@ -452,7 +453,7 @@ function snapshotBranchTrees(projectRoot, branches, temporaryRoot, onProgress, s
       state: "building",
       scope,
       ownerProcessId: process.pid,
-      ownerSessionId: PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID,
+      ownerSessionId,
       projectRoot: resolvedProjectRoot,
       branches: branchSnapshots,
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -975,7 +976,7 @@ async function reconcileLinkedLayout(input) {
     plan.push({ branchName: branch.branchName, checkoutPath, seed: resolved.seed, action: keep ? "keep" : "reset" });
   }
   const mutatedBranches = new Set(plan.filter(({ action }) => action !== "keep").map(({ branchName }) => branchName));
-  if (mutatedBranches.size > 0) input.beforeDestructiveMutation(mutatedBranches);
+  if (mutatedBranches.size > 0) await input.beforeDestructiveMutation(mutatedBranches);
   for (const entry of plan) {
     if (entry.action === "keep") continue;
     if (entry.action === "reset") {
@@ -1016,13 +1017,19 @@ async function ensureProjectWorktrees(input) {
   const snapshotStorageRoot = path.resolve(input.snapshotRoot ?? os.tmpdir());
   assertNoOutstandingSnapshotForProject(snapshotStorageRoot, projectRoot);
   let snapshot;
-  const ensureSnapshot = (branchNames) => {
-    snapshot ??= snapshotBranchTrees(
-      projectRoot,
-      branchNames ? input.branches.filter(({ branchName }) => branchNames.has(branchName)) : input.branches,
-      snapshotStorageRoot,
-      input.onSnapshotProgress,
-      branchNames ? "branches" : "project"
+  const ensureSnapshot = async (branchNames) => {
+    snapshot ??= await workspaceFilesystemExecutor().run(
+      "project_snapshot_create",
+      {
+        projectRoot,
+        branches: (branchNames ? input.branches.filter(({ branchName }) => branchNames.has(branchName)) : input.branches).map((branch) => ({
+          ...branch
+        })),
+        temporaryRoot: snapshotStorageRoot,
+        scope: branchNames ? "branches" : "project",
+        ownerSessionId: PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID
+      },
+      { onProgress: input.onSnapshotProgress }
     );
     return snapshot;
   };
@@ -1040,10 +1047,12 @@ async function ensureProjectWorktrees(input) {
         ...input,
         projectRoot,
         defaultBranch,
-        beforeDestructiveMutation: ensureSnapshot
+        beforeDestructiveMutation: async (branchNames) => {
+          await ensureSnapshot(branchNames);
+        }
       }));
     } else {
-      ensureSnapshot();
+      await ensureSnapshot();
       mirrorHeads = await initializeLinkedLayout({ ...input, projectRoot, defaultBranch });
       mutatedBranches = new Set(input.branches.map(({ branchName }) => branchName));
     }
@@ -1051,17 +1060,12 @@ async function ensureProjectWorktrees(input) {
     if (mutatedBranches.size > 0 && !preparedSnapshot) {
       throw new Error("Project worktree mutation started without a prepared recovery snapshot");
     }
-    for (const branch of input.branches) {
-      if (!mutatedBranches.has(branch.branchName)) continue;
+    const snapshotMirrors = input.branches.flatMap((branch) => {
+      if (!mutatedBranches.has(branch.branchName)) return [];
       const snapshotPath = preparedSnapshot?.paths.get(branch.branchName);
-      if (!snapshotPath) continue;
-      mirrorWorkingTree({
-        sourceRoot: snapshotPath,
-        targetRoot: branchPath(projectRoot, branch.branchName),
-        sourceMode: "all",
-        deletionMode: "git"
-      });
-    }
+      return snapshotPath ? [{ snapshotPath, targetPath: branchPath(projectRoot, branch.branchName) }] : [];
+    });
+    if (snapshotMirrors.length > 0) await workspaceFilesystemExecutor().run("project_snapshot_apply", { mirrors: snapshotMirrors });
     const states = [];
     for (const branch of input.branches) {
       const checkoutPath = branchPath(projectRoot, branch.branchName);
@@ -1077,24 +1081,23 @@ async function ensureProjectWorktrees(input) {
     states.sort((left, right) => left.branchName.localeCompare(right.branchName));
     if (snapshot) {
       const primaryGitDirectory = path.join(branchPath(projectRoot, input.primaryBranchName), ".git");
-      persistReconciledProjectAndConsumeSnapshot(
+      await workspaceFilesystemExecutor().run("project_snapshot_persist", {
         snapshot,
-        void 0,
-        snapshot.manifest.scope === "branches" ? [
+        durabilityPaths: snapshot.manifest.scope === "branches" ? [
           ...snapshot.manifest.branches.map(({ branchName }) => branchPath(projectRoot, branchName)),
           // Branch refs and worktree registrations moved in the shared
           // administrative directory; objects are fsynced by git itself.
           path.join(primaryGitDirectory, "refs"),
           path.join(primaryGitDirectory, "packed-refs"),
           path.join(primaryGitDirectory, "worktrees")
-        ] : void 0
-      );
+        ] : null
+      });
     }
     return states;
   } catch (error) {
     if (!snapshot) throw error;
     try {
-      rollbackProjectWorktreeSnapshot(snapshot);
+      await workspaceFilesystemExecutor().run("project_snapshot_rollback", { snapshot });
     } catch (recoveryError) {
       throw new Error(
         `Project worktree reconciliation failed and its snapshot could not be fully restored; recovery state is retained at ${snapshot.root}`,
@@ -1225,7 +1228,7 @@ function createLinkedProjectBranch(input) {
     throw error;
   }
 }
-function createOrRetryLinkedProjectBranch(input) {
+async function createOrRetryLinkedProjectBranch(input) {
   if (input.pendingRetry) {
     deleteLinkedProjectBranch({
       projectRoot: input.projectRoot,
@@ -1233,7 +1236,12 @@ function createOrRetryLinkedProjectBranch(input) {
       branchName: input.branchName
     });
   }
-  return createLinkedProjectBranch(input);
+  return await workspaceFilesystemExecutor().run("project_branch_create", {
+    projectRoot: input.projectRoot,
+    sourceBranchName: input.sourceBranchName,
+    branchName: input.branchName,
+    workingTree: input.workingTree
+  });
 }
 function classifyProjectCheckout(input) {
   const checkoutPath = branchPath(input.projectRoot, input.branchName);
@@ -1327,7 +1335,8 @@ function removeProjectWorktrees(input) {
       throw new Error(`Project branch ${branchName} has an in-progress Git operation`);
     }
   }
-  fs.rmSync(projectRoot, { recursive: true, force: true });
+  if (!fs.existsSync(projectRoot)) return {};
+  return { stagedForCollectionPath: stageProjectForDeletion(input.projectsRoot, projectRoot) };
 }
 async function deleteProjectMirrorBranch(input) {
   validateManagedBranchName(input.branchName);
@@ -1570,11 +1579,37 @@ async function reseedProjectHeadsFromMirror(input) {
     reseeded: moved
   }));
 }
+function runProjectSnapshotCreateJob(input, context) {
+  return snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot, context.progress, input.scope, input.ownerSessionId);
+}
+function runProjectSnapshotApplyJob(input) {
+  for (const { snapshotPath, targetPath } of input.mirrors) {
+    mirrorWorkingTree({ sourceRoot: snapshotPath, targetRoot: targetPath, sourceMode: "all", deletionMode: "git" });
+  }
+  return null;
+}
+function runProjectSnapshotPersistJob(input) {
+  persistReconciledProjectAndConsumeSnapshot(input.snapshot, void 0, input.durabilityPaths ?? void 0);
+  return null;
+}
+function runProjectSnapshotRollbackJob(input) {
+  rollbackProjectWorktreeSnapshot(input.snapshot);
+  return null;
+}
 const projectWorktreesTestHarness = {
   commandArgs: gitCommandArgs,
   configureRepository,
   createPreparedSnapshot(input) {
-    return { root: snapshotBranchTrees(input.projectRoot, input.branches, input.temporaryRoot, void 0, input.scope).root };
+    return {
+      root: snapshotBranchTrees(
+        input.projectRoot,
+        input.branches,
+        input.temporaryRoot,
+        void 0,
+        input.scope ?? "project",
+        PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID
+      ).root
+    };
   },
   consumeSnapshot(snapshotRoot) {
     const manifest = readSnapshotManifest(snapshotRoot);
@@ -1590,6 +1625,7 @@ const projectWorktreesTestHarness = {
 };
 export {
   PROJECT_REMOVED_CHECKOUTS_DIRECTORY,
+  PROJECT_WORKTREE_SNAPSHOT_OWNER_SESSION_ID,
   PROJECT_WORKTREE_SNAPSHOT_PREFIX,
   ProjectBranchCreationRollbackIncompleteError,
   applyObservedProjectMirrorHeads,
@@ -1613,5 +1649,9 @@ export {
   pushProjectMirrorHeads,
   recoverStaleProjectWorktreeSnapshots,
   removeProjectWorktrees,
-  reseedProjectHeadsFromMirror
+  reseedProjectHeadsFromMirror,
+  runProjectSnapshotApplyJob,
+  runProjectSnapshotCreateJob,
+  runProjectSnapshotPersistJob,
+  runProjectSnapshotRollbackJob
 };

package/dist/mjs/recovery-journal-protocol.mjs

@@ -0,0 +1,30 @@
+const WORKER_RECOVERY_JOURNAL_OPS = [
+  "admit",
+  "readmitUnknownBranchDeletion",
+  "record",
+  "unknown",
+  "unknownRun",
+  "acknowledgeResult",
+  "acknowledgeOutput",
+  "acknowledgeTerminal",
+  "cancelSession",
+  "isRequestCancelled",
+  "operations",
+  "recoveryState",
+  "terminals",
+  "outputReplayBegin",
+  "outputReplayNext",
+  "outputReplayEnd"
+];
+function isWorkerRecoveryJournalOp(value) {
+  return typeof value === "string" && WORKER_RECOVERY_JOURNAL_OPS.includes(value);
+}
+function serializeWorkerRecoveryJournalError(error) {
+  if (!(error instanceof Error)) return { name: "Error", message: String(error) };
+  return { name: error.name, message: error.message, ...typeof error.stack === "string" ? { stack: error.stack } : {} };
+}
+export {
+  WORKER_RECOVERY_JOURNAL_OPS,
+  isWorkerRecoveryJournalOp,
+  serializeWorkerRecoveryJournalError
+};

package/dist/mjs/recovery-journal-runtime.mjs

@@ -0,0 +1,112 @@
+import {
+  isWorkerRecoveryJournalOp,
+  serializeWorkerRecoveryJournalError
+} from "./recovery-journal-protocol.mjs";
+import { WorkerRecoveryStore } from "./recovery-store.mjs";
+function serveRecoveryJournal(port, filename, hooks = {}) {
+  const store = new WorkerRecoveryStore(filename);
+  const outputReplays = /* @__PURE__ */ new Map();
+  let nextReplayId = 1;
+  function runOp(op, args) {
+    switch (op) {
+      case "admit": {
+        const message = args[0];
+        const admission = store.admit(message);
+        return {
+          admission,
+          response: admission === "new" ? void 0 : store.response(message.requestId),
+          cancelled: store.isRequestCancelled(message.requestId)
+        };
+      }
+      case "readmitUnknownBranchDeletion":
+        return store.readmitUnknownBranchDeletion(args[0]);
+      case "record": {
+        const message = args[0];
+        if (typeof message.requestId === "string" && store.isUnknown(message.requestId)) return { suppressed: true, recorded: message };
+        return { suppressed: false, recorded: store.record(message) };
+      }
+      case "unknown":
+        store.unknown(args[0]);
+        return null;
+      case "unknownRun":
+        store.unknownRun(args[0]);
+        return null;
+      case "acknowledgeResult":
+        store.acknowledgeResult(args[0]);
+        return null;
+      case "acknowledgeOutput":
+        store.acknowledgeOutput(args[0], args[1], args[2]);
+        return null;
+      case "acknowledgeTerminal":
+        store.acknowledgeTerminal(args[0]);
+        return null;
+      case "cancelSession":
+        store.cancelSession(args[0]);
+        return null;
+      case "isRequestCancelled":
+        return store.isRequestCancelled(args[0]);
+      case "operations":
+        return store.operations();
+      case "recoveryState": {
+        const requests = args[0];
+        return {
+          operations: store.operations(),
+          cursors: store.outputCursors(),
+          responses: store.responses(requests),
+          terminals: store.terminals()
+        };
+      }
+      case "terminals":
+        return store.terminals();
+      case "outputReplayBegin": {
+        const replayId = nextReplayId++;
+        outputReplays.set(replayId, store.output(args[0]));
+        return replayId;
+      }
+      case "outputReplayNext": {
+        const replay = outputReplays.get(args[0]);
+        if (!replay) return { frames: [], done: true };
+        const maxFrames = args[1];
+        const frames = [];
+        while (frames.length < maxFrames) {
+          const next = replay.next();
+          if (next.done) {
+            outputReplays.delete(args[0]);
+            return { frames, done: true };
+          }
+          frames.push(next.value);
+        }
+        return { frames, done: false };
+      }
+      case "outputReplayEnd":
+        outputReplays.delete(args[0]);
+        return null;
+    }
+  }
+  port.on("message", (message) => {
+    if (!message || typeof message !== "object") return;
+    const request = message;
+    if (request.type !== "batch" || typeof request.id !== "number" || !Array.isArray(request.entries)) return;
+    const entries = request.entries;
+    try {
+      hooks.beforeBatch?.();
+      const results = store.batch(
+        () => entries.map((entry) => {
+          if (!isWorkerRecoveryJournalOp(entry.op)) throw new Error(`Unknown recovery journal operation: ${String(entry.op)}`);
+          return { seq: entry.seq, value: runOp(entry.op, entry.args) };
+        })
+      );
+      port.postMessage({ type: "batch_result", id: request.id, results });
+    } catch (error) {
+      port.postMessage({
+        type: "batch_failure",
+        id: request.id,
+        error: serializeWorkerRecoveryJournalError(error)
+      });
+    }
+  });
+  port.postMessage({ type: "ready", ledgerId: store.ledgerId });
+}
+export {
+  serveRecoveryJournal
+};

package/dist/mjs/recovery-journal-thread.mjs

@@ -0,0 +1,8 @@
+import { isMainThread, parentPort, workerData } from "node:worker_threads";
+import { serveRecoveryJournal } from "./recovery-journal-runtime.mjs";
+if (isMainThread || !parentPort) {
+  throw new Error("The recovery journal thread must be started by the worker runtime");
+}
+const data = workerData;
+if (!data || typeof data.filename !== "string" || !data.filename) throw new Error("The recovery journal thread needs a store filename");
+serveRecoveryJournal(parentPort, data.filename);