@ricsam/r5d-worker 0.0.123 → 0.0.125

package/dist/types/workspace-filesystem-job-types.d.ts

@@ -0,0 +1,246 @@
+import type { ProjectWorktreeBranch, ProjectWorktreeSnapshot, ProjectWorktreeSnapshotProgress, ProjectWorktreeSnapshotScope, ProjectWorktreeWorkingTreeMode } from "./project-worktrees";
+import type { WorkingTreeGitlink } from "./working-tree-mirror";
+import type { WorkspaceGitMountData, WorkspaceHydrationReceipt } from "./workspace-git-sync";
+import type { WorkspaceMergeProjectionMount, WorkspaceMergeProjectionResult } from "./workspace-merge-projection";
+import type { ProjectCheckoutPathMoveBranch } from "./workspace-path-move";
+/**
+ * The closed set of filesystem transactions the worker runs on its executor
+ * thread. Every input is plain data (paths, mount descriptors, receipts); the
+ * busy predicates, mutation tokens, hooks and gates that decide *whether* a
+ * job may run stay on the control thread. Every body is the synchronous code
+ * that used to run on the control thread, unchanged in its write and fsync
+ * ordering. A job kind outside this table is rejected by both threads.
+ */
+export type WorkspaceFilesystemJobTable = {
+    /** `recoverWorkspaceCheckoutDurability`: rebuild an interrupted outer checkout boundary. */
+    checkout_durability_recovery: {
+        input: {
+            workspacePath: string;
+            preserveResolutionInProgress: boolean;
+        };
+        result: null;
+    };
+    /** Checkout durability recovery, pending hydration transaction restore/completion, basis-ref repair. */
+    hydration_recovery: {
+        input: {
+            workspacePath: string;
+            preserveResolutionInProgress: boolean;
+        };
+        result: null;
+    };
+    /** The complete hydration transaction: snapshot, hydrate, fsync, commit marker, receipt; restore on failure. */
+    hydration_transaction: {
+        input: {
+            workspacePath: string;
+            hydrationMounts: WorkspaceGitMountData[];
+            advancedDurabilityMounts: WorkspaceGitMountData[];
+            targetReceipt: WorkspaceHydrationReceipt | null;
+        };
+        result: {
+            hydratedMountIds: string[];
+        };
+    };
+    /** Pre-clone hydration of visible mounts without a transaction (no outer Git directory yet). */
+    hydration_raw: {
+        input: {
+            workspacePath: string;
+            mounts: WorkspaceGitMountData[];
+        };
+        result: {
+            hydratedMountIds: string[];
+        };
+    };
+    /** Recover the durable checkout boundary and record the transition that follows. */
+    checkout_transition_begin: {
+        input: {
+            workspacePath: string;
+        };
+        result: null;
+    };
+    /** Make the outer checkout durable and record its head as the durable boundary. */
+    checkout_transition_complete: {
+        input: {
+            workspacePath: string;
+        };
+        result: null;
+    };
+    /** Durability barrier over the outer checkout tree without changing the record. */
+    outer_checkout_fsync: {
+        input: {
+            workspacePath: string;
+        };
+        result: null;
+    };
+    /** Three-way merge projection of one stale mount (ours snapshot + merge-tree). */
+    projection_merge: {
+        input: {
+            workspacePath: string;
+            mount: WorkspaceMergeProjectionMount;
+            basisHead: string;
+            currentHead: string;
+            attemptId: string;
+        };
+        result: WorkspaceMergeProjectionResult;
+    };
+    /** Byte mirror of one visible mount into the outer checkout. */
+    projection_mirror: {
+        input: {
+            workspacePath: string;
+            mount: WorkspaceGitMountData;
+        };
+        result: {
+            gitlinks: WorkingTreeGitlink[];
+        };
+    };
+    /** Outer-tree edits after the mirrors: tombstone removal, merged subtree materialization, deferred restores. */
+    projection_outer_apply: {
+        input: {
+            workspacePath: string;
+            removeMounts: WorkspaceGitMountData[];
+            materialize: Array<{
+                workspaceRelativePath: string;
+                resultTree: string;
+            }>;
+            restoreFromHead: WorkspaceGitMountData[];
+        };
+        result: null;
+    };
+    /** Persist projected visible mounts and publish the projection receipt. */
+    projection_receipt: {
+        input: {
+            workspacePath: string;
+            fsyncMounts: WorkspaceGitMountData[];
+            receipt: WorkspaceHydrationReceipt;
+        };
+        result: null;
+    };
+    /** `snapshotBranchTrees`: copy every checkout a reconciliation may rewrite. */
+    project_snapshot_create: {
+        input: {
+            projectRoot: string;
+            branches: ProjectWorktreeBranch[];
+            temporaryRoot: string;
+            scope: ProjectWorktreeSnapshotScope;
+            ownerSessionId: string;
+        };
+        result: ProjectWorktreeSnapshot;
+    };
+    /** Mirror captured checkouts back over the reconciled worktrees. */
+    project_snapshot_apply: {
+        input: {
+            mirrors: Array<{
+                snapshotPath: string;
+                targetPath: string;
+            }>;
+        };
+        result: null;
+    };
+    /** `persistReconciledProjectAndConsumeSnapshot`. */
+    project_snapshot_persist: {
+        input: {
+            snapshot: ProjectWorktreeSnapshot;
+            durabilityPaths: string[] | null;
+        };
+        result: null;
+    };
+    /** `rollbackProjectWorktreeSnapshot`. */
+    project_snapshot_rollback: {
+        input: {
+            snapshot: ProjectWorktreeSnapshot;
+        };
+        result: null;
+    };
+    /** `recoverStaleProjectWorktreeSnapshots` at startup. */
+    project_snapshots_recover: {
+        input: {
+            projectsRoot: string;
+            temporaryRoot: string;
+            currentProcessId: number;
+            currentOwnerSessionId: string;
+        };
+        result: {
+            restored: string[];
+            removed: string[];
+            failed: Array<{
+                path: string;
+                error: string;
+            }>;
+        };
+    };
+    /** `createLinkedProjectBranch`: branch ref, linked worktree, index seed and working-tree copy. */
+    project_branch_create: {
+        input: {
+            projectRoot: string;
+            sourceBranchName: string;
+            branchName: string;
+            workingTree: ProjectWorktreeWorkingTreeMode;
+        };
+        result: {
+            branchPath: string;
+            baseCommitHash: string;
+        };
+    };
+    /** `preserveProjectCheckoutPathMove`. */
+    project_checkout_path_move: {
+        input: {
+            oldProjectRoot: string;
+            newProjectRoot: string;
+            projectsDurabilityRoot: string;
+            outerWorkspaceRoot: string;
+            branches: ProjectCheckoutPathMoveBranch[];
+        };
+        result: {
+            preservedBranchNames: string[];
+        };
+    };
+};
+export type WorkspaceFilesystemJobKind = keyof WorkspaceFilesystemJobTable;
+export type WorkspaceFilesystemJobInput<K extends WorkspaceFilesystemJobKind> = WorkspaceFilesystemJobTable[K]["input"];
+export type WorkspaceFilesystemJobResult<K extends WorkspaceFilesystemJobKind> = WorkspaceFilesystemJobTable[K]["result"];
+export type WorkspaceFilesystemJobProgress = ProjectWorktreeSnapshotProgress;
+export type WorkspaceFilesystemJobContext = {
+    progress: (progress: WorkspaceFilesystemJobProgress) => void;
+};
+export type WorkspaceFilesystemJobOperations = {
+    [K in WorkspaceFilesystemJobKind]: (input: WorkspaceFilesystemJobInput<K>, context: WorkspaceFilesystemJobContext) => WorkspaceFilesystemJobResult<K>;
+};
+export declare const WORKSPACE_FILESYSTEM_JOB_KINDS: readonly WorkspaceFilesystemJobKind[];
+export declare function isWorkspaceFilesystemJobKind(value: unknown): value is WorkspaceFilesystemJobKind;
+/** Short, path-bearing description used in stall diagnostics and errors. */
+export declare function describeWorkspaceFilesystemJob<K extends WorkspaceFilesystemJobKind>(kind: K, input: WorkspaceFilesystemJobInput<K>): string;
+/** Errors cross the thread boundary as data; the properties callers inspect are preserved. */
+export type WorkspaceFilesystemSerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    branchMayExist?: true;
+    cleanupFailures?: string[];
+    errors?: WorkspaceFilesystemSerializedError[];
+    cause?: WorkspaceFilesystemSerializedError;
+};
+export declare function serializeWorkspaceFilesystemError(error: unknown, depth?: number): WorkspaceFilesystemSerializedError;
+export declare function restoreWorkspaceFilesystemError(serialized: WorkspaceFilesystemSerializedError): Error;
+/** Control thread → executor thread. */
+export type WorkspaceFilesystemThreadRequest = {
+    type: "run";
+    id: number;
+    kind: WorkspaceFilesystemJobKind;
+    input: unknown;
+    /** The control thread's environment at dispatch; the thread runs the job under exactly this. */
+    environment: Record<string, string>;
+};
+/** Executor thread → control thread. */
+export type WorkspaceFilesystemThreadReply = {
+    type: "progress";
+    id: number;
+    progress: WorkspaceFilesystemJobProgress;
+} | {
+    type: "result";
+    id: number;
+    result: unknown;
+} | {
+    type: "failure";
+    id: number;
+    error: WorkspaceFilesystemSerializedError;
+};

package/dist/types/workspace-filesystem-jobs.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceFilesystemJobOperations } from "./workspace-filesystem-job-types";
+/**
+ * The operation table of the workspace filesystem executor thread. It is the
+ * only thing the thread can run; every entry is an existing synchronous
+ * transaction body. Imported by the thread entry module only.
+ */
+export declare const workspaceFilesystemJobOperations: WorkspaceFilesystemJobOperations;

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

@@ -5,6 +5,27 @@ export declare const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confi
 export declare const WORKSPACE_GIT_HYDRATED_RECEIPT = "r5d/workspace-hydrated-head";
 export declare const WORKSPACE_GIT_HYDRATION_TRANSACTION = "r5d/workspace-hydration-transaction";
 export declare const WORKSPACE_GIT_CHECKOUT_DURABILITY = "r5d/workspace-checkout-durability";
+type WorkspaceHydrationMountBasis = {
+    id: string;
+    incarnationKey: string;
+    sourcePath: string;
+    durabilityRootPath: string;
+    workspaceRelativePath: string;
+    sourceMode: WorkingTreeSourceMode;
+    hydrateDeletionMode: "all" | "git";
+    preserveLocalOnInitialOuterAbsence: boolean;
+    preserveLocalOnHydrationBasisChange: boolean;
+    deleteWhenSourceMissing: boolean;
+};
+type WorkspaceHydrationMountReceipt = WorkspaceHydrationMountBasis & {
+    head: string;
+};
+export type WorkspaceHydrationReceipt = {
+    version: 3;
+    mounts: WorkspaceHydrationMountReceipt[];
+    /** Non-enumerable read-compat marker used only to finish a v1/v2 crash transition. */
+    legacyHead?: string;
+};
 export type WorkspaceGitMount = {
     id: string;
     /** Durable logical incarnation (for example the project-branch row id). */
@@ -49,6 +70,15 @@ export type WorkspaceGitMount = {
     /** Activity-only fence used before checkout readiness is established on reconnect. */
     busyForRecovery?: () => boolean;
 };
+/**
+ * The data of a mount, without its control-thread predicates. This is what a
+ * workspace filesystem job receives: a job never evaluates `busy()` or
+ * `mutationToken()`; the control thread evaluated them before dispatch and
+ * holds the mount (see WorkspaceHydrationTransactionHooks.holdMounts) until
+ * the job ends.
+ */
+export type WorkspaceGitMountData = Pick<WorkspaceGitMount, "id" | "hydrationIncarnationKey" | "sourcePath" | "durabilityRootPath" | "workspaceRelativePath" | "sourceMode" | "hydrateDeletionMode" | "preserveLocalOnInitialOuterAbsence" | "preserveLocalOnHydrationBasisChange" | "initialPublicationSourceRelativePath" | "deleteWhenSourceMissing" | "lastProjectedMutationToken">;
+export declare function workspaceGitMountData(mount: WorkspaceGitMount): WorkspaceGitMountData;
 /**
  * Incident-bound configuration keeps project checkouts unready while the
  * canonical remediation owns the workspace. The guarded remediation sync is
@@ -65,17 +95,23 @@ export type WorkspaceHydrationTransactionContext = {
     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.
+ * Observes a hydration transaction (snapshot, hydration pass, durability
+ * barrier, receipt) and fences the mounts any workspace filesystem job reads
+ * or writes. The body runs on the executor thread and on a stalled disk it
+ * can run for a long time. `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. `holdMounts` is called synchronously right
+ * after the busy observation that selected the mounts, before the job is
+ * dispatched, and its release is called when the job's result or failure
+ * arrived: while held, command admission for those mounts waits (see
+ * WorkspaceMountHoldFence), which replaces the guarantee the un-yielding body
+ * used to give.
  */
 export type WorkspaceHydrationTransactionHooks = {
     beforeTransaction: (context: WorkspaceHydrationTransactionContext) => Promise<void> | void;
     afterTransaction: (context: WorkspaceHydrationTransactionContext) => void;
+    holdMounts: (mountIds: readonly string[], description: string) => () => void;
 };
 export type WorkspaceGitSyncOutcome = "no_change" | "updated" | "pushed" | "large_diff_blocked" | "conflict_blocked";
 export type WorkspaceGitSyncResult = {
@@ -126,6 +162,23 @@ export declare function workspaceGitHydrationIsCurrent(workspacePath: string, mo
  * Configuration-time recovery keeps the strict predicate.
  */
 export declare function workspaceGitHydrationIsRecoverable(workspacePath: string, mounts?: readonly WorkspaceGitMount[]): boolean;
+/** Executor job body: recover the durable boundary, then record the transition that follows. */
+export declare function runCheckoutTransitionBeginJob(input: {
+    workspacePath: string;
+}): null;
+/** Executor job body: make the outer checkout durable and record its head as the durable boundary. */
+export declare function runCheckoutTransitionCompleteJob(input: {
+    workspacePath: string;
+}): null;
+/** Executor job body: `recoverWorkspaceCheckoutDurability`. */
+export declare function runCheckoutDurabilityRecoveryJob(input: {
+    workspacePath: string;
+    preserveResolutionInProgress: boolean;
+}): null;
+/** Executor job body: the outer-tree durability barrier alone. */
+export declare function runOuterCheckoutFsyncJob(input: {
+    workspacePath: string;
+}): null;
 declare function configureWorkspaceRepository(input: {
     workspacePath: string;
     remoteUrl: string;
@@ -179,6 +232,36 @@ type ProjectedMountGitlinks = {
  * `stageWorkspaceGitlinks` before `git add -A`, which can never create one.
  */
 declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): ProjectedMountGitlinks[];
+/**
+ * Executor job body: the complete hydration transaction. Snapshot exactly
+ * what hydration replaces, hydrate, cross the durability barrier, write the
+ * commit marker, publish the receipt, remove the transaction; on failure
+ * restore the snapshot unless the visible tree is already durable. The write
+ * and fsync ordering is the one the control thread used to run inline.
+ */
+export declare function runHydrationTransactionJob(input: {
+    workspacePath: string;
+    hydrationMounts: readonly WorkspaceGitMountData[];
+    advancedDurabilityMounts: readonly WorkspaceGitMountData[];
+    targetReceipt: WorkspaceHydrationReceipt | null;
+}): {
+    hydratedMountIds: string[];
+};
+/** Executor job body: hydrate visible mounts before an outer clone exists (no transaction to record). */
+export declare function runHydrationRawJob(input: {
+    workspacePath: string;
+    mounts: readonly WorkspaceGitMountData[];
+}): {
+    hydratedMountIds: string[];
+};
+/**
+ * Executor job body: checkout durability recovery, pending hydration
+ * transaction restore or completion, and basis-ref repair, in that order.
+ */
+export declare function runHydrationRecoveryJob(input: {
+    workspacePath: string;
+    preserveResolutionInProgress: boolean;
+}): null;
 export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[], options?: {
     ignoreBusy?: boolean;
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
@@ -257,6 +340,29 @@ export type SynchronizeWorkspaceGitInput = {
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
 };
 export declare function synchronizeWorkspaceGit(input: SynchronizeWorkspaceGitInput): Promise<WorkspaceGitSyncResult>;
+/** Executor job body: byte-mirror one visible mount into the outer checkout. */
+export declare function runProjectionMirrorJob(input: {
+    workspacePath: string;
+    mount: WorkspaceGitMountData;
+}): {
+    gitlinks: WorkingTreeGitlink[];
+};
+/** Executor job body: outer-tree edits that follow the mirrors, in the cycle's order. */
+export declare function runProjectionOuterApplyJob(input: {
+    workspacePath: string;
+    removeMounts: readonly WorkspaceGitMountData[];
+    materialize: ReadonlyArray<{
+        workspaceRelativePath: string;
+        resultTree: string;
+    }>;
+    restoreFromHead: readonly WorkspaceGitMountData[];
+}): null;
+/** Executor job body: persist projected visible mounts, then publish the projection receipt. */
+export declare function runProjectionReceiptJob(input: {
+    workspacePath: string;
+    fsyncMounts: readonly WorkspaceGitMountData[];
+    receipt: WorkspaceHydrationReceipt;
+}): null;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;
     workspaceCloneCommandArgs: typeof workspaceCloneCommandArgs;

package/dist/types/workspace-mount-hold-fence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tracks the mounts whose bytes a workspace filesystem job is reading or
+ * writing on the executor thread. The sync engine takes a hold immediately
+ * after the busy observation that selected a mount, in the same synchronous
+ * stretch, and releases it when the job's result or failure arrives. Command
+ * admission waits on the fence before reserving a mount, so no tracked
+ * process, PTY or file operation can start in a mount while a job owns it,
+ * and no job can start on a mount a command already reserved (that mount was
+ * busy at the observation). Holds are counted per mount; overlapping holds
+ * (a recovery pass and a projection of the same mount cannot overlap under the
+ * mutation gate, but counting keeps the fence correct regardless) release in
+ * any order.
+ */
+export type WorkspaceMountHoldRelease = () => void;
+export declare class WorkspaceMountHoldAbortedError extends Error {
+    constructor(reason: string);
+}
+export declare class WorkspaceMountHoldFence {
+    private readonly holds;
+    private readonly waiters;
+    private readonly now;
+    constructor(options?: {
+        now?: () => number;
+    });
+    /** Take one hold on every listed mount; the returned release is idempotent. */
+    hold(mountIds: readonly string[], description: string): WorkspaceMountHoldRelease;
+    isHeld(mountIds: readonly string[]): boolean;
+    /** Human-readable holder of the first held mount among `mountIds`, for diagnostics. */
+    describeHold(mountIds: readonly string[]): string | null;
+    /** Every held mount id, sorted, for status reporting. */
+    heldMountIds(): string[];
+    /**
+     * Resolves in the same turn as the release that leaves none of `mountIds`
+     * held, so the caller can re-check and reserve without an interleaving
+     * hold. Resolves immediately when nothing is held. Rejects with
+     * WorkspaceMountHoldAbortedError when `signal` aborts first.
+     */
+    waitForRelease(mountIds: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    private wake;
+}

package/package.json

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

package/dist/cjs/project-snapshot-recovery-runner.cjs

@@ -1,171 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var project_snapshot_recovery_runner_exports = {};
-__export(project_snapshot_recovery_runner_exports, {
-  PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND: () => PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND,
-  recoverProjectSnapshotsInChild: () => recoverProjectSnapshotsInChild,
-  runProjectSnapshotRecoveryHelper: () => runProjectSnapshotRecoveryHelper
-});
-module.exports = __toCommonJS(project_snapshot_recovery_runner_exports);
-var import_node_path = __toESM(require("node:path"), 1);
-var import_node_child_process = require("node:child_process");
-var import_project_worktrees = require("./project-worktrees.cjs");
-const PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND = "__recover-project-snapshots";
-function requireAbsolutePath(value, label) {
-  if (!value) throw new Error(`Missing ${label}`);
-  const resolved = import_node_path.default.resolve(value);
-  if (resolved !== value) throw new Error(`${label} must be an absolute path`);
-  return resolved;
-}
-function parseHelperArguments(args) {
-  let projectsRoot;
-  let snapshotRoot;
-  for (let index = 0; index < args.length; index += 1) {
-    const argument = args[index];
-    if (argument === "--projects-root") {
-      projectsRoot = args[index + 1];
-      index += 1;
-      continue;
-    }
-    if (argument === "--snapshot-root") {
-      snapshotRoot = args[index + 1];
-      index += 1;
-      continue;
-    }
-    throw new Error(`Unknown project snapshot recovery helper argument: ${argument ?? "(missing)"}`);
-  }
-  return {
-    projectsRoot: requireAbsolutePath(projectsRoot, "projects root"),
-    snapshotRoot: requireAbsolutePath(snapshotRoot, "snapshot root")
-  };
-}
-function writeHelperMessage(message) {
-  process.stdout.write(`${JSON.stringify(message)}
-`);
-}
-function runProjectSnapshotRecoveryHelper(args) {
-  const { projectsRoot, snapshotRoot } = parseHelperArguments(args);
-  const result = (0, import_project_worktrees.recoverStaleProjectWorktreeSnapshots)({
-    projectsRoot,
-    temporaryRoot: snapshotRoot,
-    onProgress: (progress) => writeHelperMessage({ type: "progress", progress })
-  });
-  writeHelperMessage({ type: "result", result });
-  return result.failed.length === 0 ? 0 : 1;
-}
-function isRecoveryProgress(value) {
-  if (!value || typeof value !== "object") return false;
-  const progress = value;
-  return progress.operation === "restore" && (progress.phase === "scanning" || progress.phase === "copying" || progress.phase === "moving" || progress.phase === "syncing" || progress.phase === "cleaning") && typeof progress.projectRoot === "string" && Number.isSafeInteger(progress.completedBranches) && Number.isSafeInteger(progress.totalBranches) && typeof progress.completedBytes === "number" && Number.isFinite(progress.completedBytes) && (progress.totalBytes === void 0 || typeof progress.totalBytes === "number" && Number.isFinite(progress.totalBytes));
-}
-function isRecoveryResult(value) {
-  if (!value || typeof value !== "object") return false;
-  const result = value;
-  return Array.isArray(result.restored) && Array.isArray(result.removed) && Array.isArray(result.failed);
-}
-function recoveryChildEnvironment() {
-  const environment = {};
-  for (const name of ["PATH", "TMPDIR", "TMP", "TEMP", "SystemRoot", "WINDIR"]) {
-    const value = process.env[name];
-    if (value !== void 0) environment[name] = value;
-  }
-  return environment;
-}
-async function recoverProjectSnapshotsInChild(input) {
-  const entrypoint = process.argv[1];
-  if (!entrypoint) throw new Error("Cannot locate the r5d-worker runtime entrypoint for snapshot recovery");
-  const child = (0, import_node_child_process.spawn)(
-    process.execPath,
-    [
-      entrypoint,
-      PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND,
-      "--projects-root",
-      import_node_path.default.resolve(input.projectsRoot),
-      "--snapshot-root",
-      import_node_path.default.resolve(input.snapshotRoot)
-    ],
-    {
-      env: recoveryChildEnvironment(),
-      stdio: ["ignore", "pipe", "pipe"]
-    }
-  );
-  const terminateOnParentExit = () => {
-    if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
-  };
-  const parentProcessEvents = process;
-  parentProcessEvents.once("exit", terminateOnParentExit);
-  let stdout = "";
-  let stderr = "";
-  let result;
-  child.stdout.setEncoding("utf8");
-  child.stdout.on("data", (chunk) => {
-    stdout += chunk;
-    while (true) {
-      const newline = stdout.indexOf("\n");
-      if (newline < 0) break;
-      const line = stdout.slice(0, newline);
-      stdout = stdout.slice(newline + 1);
-      if (!line.trim()) continue;
-      let message;
-      try {
-        message = JSON.parse(line);
-      } catch {
-        stderr += `Invalid recovery helper output: ${line}
-`;
-        continue;
-      }
-      if (!message || typeof message !== "object") continue;
-      const record = message;
-      if (record.type === "progress" && isRecoveryProgress(record.progress)) input.onProgress?.(record.progress);
-      if (record.type === "result" && isRecoveryResult(record.result)) result = record.result;
-    }
-  });
-  child.stderr.setEncoding("utf8");
-  child.stderr.on("data", (chunk) => {
-    stderr = `${stderr}${chunk}`.slice(-32768);
-  });
-  const exitCode = await new Promise((resolve, reject) => {
-    child.once("error", reject);
-    child.once("close", (code, signal) => {
-      if (signal) reject(new Error(`Project snapshot recovery helper exited on signal ${signal}`));
-      else resolve(code ?? 1);
-    });
-  }).finally(() => parentProcessEvents.off("exit", terminateOnParentExit));
-  if (exitCode !== 0 || !result) {
-    const detail = stderr.trim();
-    throw new Error(detail || `Project snapshot recovery helper exited with status ${exitCode}`);
-  }
-  return result;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND,
-  recoverProjectSnapshotsInChild,
-  runProjectSnapshotRecoveryHelper
-});