@ricsam/r5d-worker 0.0.89 → 0.0.91

package/README.md

@@ -41,6 +41,10 @@ Worker labels are mandatory and unique per user. Choose labels that describe hos
 
 The supervisor also reconnects automatically after server rollouts and transient network failures. A brief bounded delay prevents a tight retry loop while the server is unavailable. Pressing Ctrl+C still stops the worker, and agent-managed processes retain their existing in-process recovery path while disconnected.
 
+The runtime opens its control connection before recovering interrupted project snapshots. During recovery and initial project configuration it remains connected but non-dispatchable, reports its current phase plus branch/byte progress to the server, and prints the same progress locally. Recovery runs in a credential-sanitized helper process so the control loop can continue answering heartbeats. A durable `restoring` transaction state permits same-filesystem snapshots to be restored with one atomic directory move; cross-filesystem layouts retain the copy-and-fsync fallback.
+
+The server registry is the sole heartbeat timeout authority. The worker answers server pings but does not run an independent connection watchdog, because synchronous bounded workspace operations can temporarily occupy its event loop. The server keeps those operations leased for their bounded lifetime and closes genuinely stale connections after the lease ends.
+
 Credential-generation restart fencing protects against stale or accidentally detached descendants. It is not a hostile same-UID sandbox: code running as the worker's OS user can read or tamper with that user's config and auth files, install a persistent user service, or return after reboot. Run untrusted agents in a disposable VM that is reset at the boundary, or use a separately privileged credential broker/service account. When rotating the worker's own local `r5dctl` credential, stop the worker and reboot/reset the host before writing the replacement credential so an old same-UID descendant cannot read the new config.
 
 One-click updates use the current user's global npm prefix and never invoke `sudo`. If that prefix is not writable, User Settings provides the exact command to run manually.

package/dist/cjs/main.cjs

@@ -63,7 +63,6 @@ var import_node_child_process = require("node:child_process");
 var import_bun_sqlite = require("bun:sqlite");
 var import_cli_update = require("./cli-update.cjs");
 var import_git_process_environment = require("./git-process-environment.cjs");
-var import_heartbeat = require("./heartbeat.cjs");
 var import_process_tree = require("./process-tree.cjs");
 var import_pty_output_coalescer = require("./pty-output-coalescer.cjs");
 var import_port_forward_client = require("./port-forward-client.cjs");
@@ -81,6 +80,7 @@ var import_repository_transition_policy = require("./repository-transition-polic
 var import_supervisor = require("./supervisor.cjs");
 var import_managed_paths = require("./managed-paths.cjs");
 var import_project_worktrees = require("./project-worktrees.cjs");
+var import_project_snapshot_recovery_runner = require("./project-snapshot-recovery-runner.cjs");
 var import_project_workspace_state = require("./project-workspace-state.cjs");
 var import_workspace_git_sync = require("./workspace-git-sync.cjs");
 const import_meta = {};
@@ -3408,28 +3408,6 @@ async function startWorker(options) {
   runGit(["--version"]);
   await verifyR5dctlAuth(baseUrl, token, label);
   const initializedWorkspaceState = await workspaceSyncSingleFlight.runExclusive(() => {
-    if (!startupProjectSnapshotRecoveryCompleted) {
-      const snapshotRecovery = (0, import_project_worktrees.recoverStaleProjectWorktreeSnapshots)({
-        projectsRoot,
-        temporaryRoot: projectWorktreeSnapshotsRoot
-      });
-      if (snapshotRecovery.restored.length > 0) {
-        process.stdout.write(`[r5d-worker] restored ${snapshotRecovery.restored.length} interrupted project snapshot(s)
-`);
-      }
-      if (snapshotRecovery.removed.length > 0) {
-        process.stdout.write(`[r5d-worker] removed ${snapshotRecovery.removed.length} completed/incomplete project snapshot(s)
-`);
-      }
-      for (const failure of snapshotRecovery.failed) {
-        process.stderr.write(`[r5d-worker] failed to recover stale project snapshot ${failure.path}: ${failure.error}
-`);
-      }
-      if (snapshotRecovery.failed.length > 0) {
-        throw new Error("Project snapshot recovery is incomplete; refusing to mutate project checkouts");
-      }
-      startupProjectSnapshotRecoveryCompleted = true;
-    }
     import_node_fs.default.mkdirSync(projectsRoot, { recursive: true });
     import_node_fs.default.mkdirSync(syncRoot, { recursive: true });
     import_node_fs.default.mkdirSync(artifactRoot, { recursive: true });
@@ -3468,6 +3446,8 @@ async function startWorker(options) {
   let cliUpdateInProgress = false;
   let reloadAfterClose = false;
   let shutdownAfterClose = false;
+  let startupRecoveryComplete = startupProjectSnapshotRecoveryCompleted;
+  let startupRecoveryPromise = Promise.resolve();
   const automaticWorkspaceSyncIsCurrentlyAdmitted = () => workspaceAutomaticSyncIsAdmitted({
     workspaceConfigured,
     activeIncidentId: activeWorkspaceIncidentId,
@@ -3884,8 +3864,14 @@ async function startWorker(options) {
       })
     )
   ].sort();
-  const ensureConfiguredProjects = async () => {
-    for (const project of projectConfigById.values()) {
+  const ensureConfiguredProjects = async (onProgress) => {
+    const projects = [...projectConfigById.values()];
+    for (const [projectIndex, project] of projects.entries()) {
+      onProgress?.({
+        detail: `Configuring ${project.projectPath}`,
+        completedItems: projectIndex,
+        totalItems: projects.length
+      });
       validateProjectId(project.projectId);
       (0, import_repository_transition_policy.assertRepositoryTransitionState)(project);
       for (const branch of project.branches) validateBranchName(branch.branchName);
@@ -3933,7 +3919,14 @@ async function startWorker(options) {
           mirrorUrl: connection.mirrorUrl,
           mirrorCredentialUsername: connection.mirrorCredentialUsername,
           credentialHelper: connection.credentialHelper,
-          gitIdentity: workspaceGitIdentity
+          gitIdentity: workspaceGitIdentity,
+          onSnapshotProgress: (progress) => onProgress?.({
+            detail: progress.phase === "scanning" ? `Measuring ${project.projectPath} workspace snapshot` : progress.phase === "syncing" ? `Making ${project.projectPath} workspace snapshot durable` : `${progress.operation === "restore" ? "Restoring" : "Snapshotting"} ${project.projectPath}${progress.branchName ? `/${progress.branchName}` : ""}`,
+            completedBytes: progress.completedBytes,
+            completedItems: progress.completedBranches,
+            totalItems: progress.totalBranches,
+            ...progress.totalBytes === void 0 ? {} : { totalBytes: progress.totalBytes }
+          })
         });
         readyProjectIds.add(project.projectId);
         reconciledProjectConfigFingerprints.set(project.projectId, configFingerprint);
@@ -3968,6 +3961,11 @@ async function startWorker(options) {
 `
         );
       }
+      onProgress?.({
+        detail: `Configured ${project.projectPath}`,
+        completedItems: projectIndex + 1,
+        totalItems: projects.length
+      });
     }
   };
   const collectAheadOfOriginBranches = async () => {
@@ -4360,6 +4358,11 @@ async function startWorker(options) {
       if (input.sendResult !== false) sendWorkspaceSyncResult(input.requestId, result2);
       return result2;
     }
+    sendLifecycleProgress({
+      phase: "syncing",
+      operationId: attemptId,
+      detail: input.trigger.detail ?? `Synchronizing workspace (${input.trigger.type})`
+    });
     if (!input.requestId && input.sendResult !== false) {
       if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
         throw new Error("Cannot start autonomous workspace synchronization without an open worker control socket");
@@ -4462,6 +4465,9 @@ async function startWorker(options) {
       }
     };
     if (input.sendResult !== false) sendWorkspaceSyncResult(input.requestId, result);
+    sendLifecycleProgress(
+      result.outcome === "failed" ? { phase: "failed", operationId: attemptId, detail: result.error ?? "Workspace synchronization failed" } : { phase: "ready", operationId: attemptId, detail: "Workspace synchronized" }
+    );
     return result;
   };
   const scheduleAutomaticWorkspaceSync = (trigger, delayMs = WORKSPACE_GIT_QUIET_MS) => {
@@ -4501,7 +4507,6 @@ async function startWorker(options) {
           );
         }).finally(() => {
           automaticSyncInFlight = false;
-          heartbeatBusyGrace = (0, import_heartbeat.grantWorkerHeartbeatBusyGrace)(lastServerHeartbeatAt, heartbeatBusyGrace);
           if (pendingAutomaticTrigger && automaticWorkspaceSyncIsCurrentlyAdmitted()) {
             scheduleAutomaticWorkspaceSync(pendingAutomaticTrigger, WORKSPACE_GIT_QUIET_MS);
           }
@@ -4537,6 +4542,14 @@ async function startWorker(options) {
     });
   };
   const configureWorkerWorkspace = async (message, receiptGeneration) => {
+    const configurationOperationId = crypto.randomUUID();
+    sendLifecycleProgress({
+      phase: "configuring",
+      operationId: configurationOperationId,
+      detail: `Preparing ${message.projects.length} project(s)`,
+      completedItems: 0,
+      totalItems: message.projects.length
+    });
     const incidentDeferral = workspaceConfigurationIncidentDeferral({
       requestedIncidentId: message.deferWorkspaceSyncForIncidentId,
       activeIncidentId: activeWorkspaceIncidentId
@@ -4901,7 +4914,13 @@ async function startWorker(options) {
           // checkout initialization from erasing synchronized dirt.
           { ignoreBusy: true }
         );
-        await ensureConfiguredProjects();
+        await ensureConfiguredProjects((progress) => {
+          sendLifecycleProgress({ phase: "configuring", operationId: configurationOperationId, ...progress });
+          process.stdout.write(
+            `[r5d-worker] ${progress.detail ?? "Configuring workspace"}${progress.completedBytes === void 0 ? "" : `: ${progress.completedBytes}/${progress.totalBytes ?? "?"} bytes`}${progress.completedItems === void 0 ? "" : `, ${progress.completedItems}/${progress.totalItems ?? "?"} item(s)`}
+`
+          );
+        });
         const configurationSyncAdmissionGeneration = workerAdmissionGeneration;
         const assertConfigurationSyncStillAdmitted = () => {
           if (receiptGeneration !== workspaceConfigurationReceiptGeneration || configurationSyncAdmissionGeneration !== workerAdmissionGeneration || !workspaceConfigurationIncidentSnapshotIsCurrent(incidentDeferral.incidentId, activeWorkspaceIncidentId) || currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) {
@@ -5000,10 +5019,60 @@ async function startWorker(options) {
       Authorization: `Bearer ${token}`
     }
   });
-  let lastServerHeartbeatAt = null;
-  let heartbeatBusyGrace = null;
-  let heartbeatTimedOut = false;
-  let heartbeatWatchdog;
+  const sendLifecycleProgress = (progress) => {
+    if (currentWorkerSocket !== ws || ws.readyState !== WebSocket.OPEN) return;
+    sendWorkerMessage(ws, { type: "worker_progress", progress });
+  };
+  const describeSnapshotProgress = (progress) => {
+    const project = import_node_path.default.relative(projectsRoot, progress.projectRoot) || import_node_path.default.basename(progress.projectRoot);
+    const branch = progress.branchName ? `/${progress.branchName}` : "";
+    if (progress.phase === "scanning") return `Scanning ${project} recovery snapshot`;
+    if (progress.phase === "syncing") return `Making restored ${project} files durable`;
+    if (progress.phase === "cleaning") return `Cleaning recovered ${project} snapshot`;
+    return `Restoring ${project}${branch}`;
+  };
+  const performStartupRecovery = async (operationId) => {
+    if (startupProjectSnapshotRecoveryCompleted) return;
+    sendLifecycleProgress({ phase: "recovering", operationId, detail: "Checking interrupted workspace transactions" });
+    const snapshotRecovery = await workspaceSyncSingleFlight.runExclusive(
+      async () => await (0, import_project_snapshot_recovery_runner.recoverProjectSnapshotsInChild)({
+        projectsRoot,
+        snapshotRoot: projectWorktreeSnapshotsRoot,
+        onProgress: (progress) => {
+          const lifecycleProgress = {
+            phase: "recovering",
+            operationId,
+            detail: describeSnapshotProgress(progress),
+            completedBytes: progress.completedBytes,
+            completedItems: progress.completedBranches,
+            totalItems: progress.totalBranches,
+            ...progress.totalBytes === void 0 ? {} : { totalBytes: progress.totalBytes }
+          };
+          sendLifecycleProgress(lifecycleProgress);
+          process.stdout.write(
+            `[r5d-worker] ${lifecycleProgress.detail}: ${progress.completedBranches}/${progress.totalBranches} branch(es), ${progress.completedBytes}/${progress.totalBytes ?? "?"} bytes
+`
+          );
+        }
+      })
+    );
+    if (snapshotRecovery.restored.length > 0) {
+      process.stdout.write(`[r5d-worker] restored ${snapshotRecovery.restored.length} interrupted project snapshot(s)
+`);
+    }
+    if (snapshotRecovery.removed.length > 0) {
+      process.stdout.write(`[r5d-worker] removed ${snapshotRecovery.removed.length} completed/incomplete project snapshot(s)
+`);
+    }
+    for (const failure of snapshotRecovery.failed) {
+      process.stderr.write(`[r5d-worker] failed to recover stale project snapshot ${failure.path}: ${failure.error}
+`);
+    }
+    if (snapshotRecovery.failed.length > 0) {
+      throw new Error("Project snapshot recovery is incomplete; refusing to mutate project checkouts");
+    }
+    startupProjectSnapshotRecoveryCompleted = true;
+  };
   const handleGracefulShutdown = () => {
     if (shutdownAfterClose) return;
     shutdownAfterClose = true;
@@ -5031,25 +5100,29 @@ async function startWorker(options) {
   };
   process.on("SIGTERM", handleGracefulShutdown);
   process.on("SIGINT", handleGracefulShutdown);
-  const stopHeartbeatWatchdog = () => {
-    if (heartbeatWatchdog) {
-      clearInterval(heartbeatWatchdog);
-      heartbeatWatchdog = void 0;
-    }
-  };
   ws.addEventListener("open", () => {
     currentWorkerSocket = ws;
-    heartbeatWatchdog = setInterval(() => {
-      if (heartbeatTimedOut || !(0, import_heartbeat.hasWorkerHeartbeatTimedOutWithBusyGrace)(lastServerHeartbeatAt, heartbeatBusyGrace)) {
-        return;
+    const startupOperationId = crypto.randomUUID();
+    startupRecoveryPromise = Promise.resolve().then(async () => await performStartupRecovery(startupOperationId)).then(() => {
+      startupRecoveryComplete = true;
+      if (currentWorkerSocket === ws && ws.readyState === WebSocket.OPEN) {
+        sendWorkerMessage(ws, { type: "startup_ready" });
+        sendLifecycleProgress({
+          phase: "configuring",
+          operationId: crypto.randomUUID(),
+          detail: "Waiting for workspace configuration"
+        });
       }
-      heartbeatTimedOut = true;
-      stopHeartbeatWatchdog();
-      process.stderr.write("[r5d-worker] server heartbeat timed out; reconnecting\n");
-      ws.terminate();
-    }, import_heartbeat.WORKER_HEARTBEAT_INTERVAL_MS);
+    }).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      sendLifecycleProgress({ phase: "failed", operationId: startupOperationId, detail: message });
+      process.stderr.write(`[r5d-worker] startup recovery failed: ${message}
+`);
+      ws.close(1011, "Project snapshot recovery failed");
+    });
     const hello = {
       type: "hello",
+      startupReady: startupRecoveryComplete,
       hostInfo: {
         hostname: (0, import_node_os.hostname)(),
         platform: process.platform,
@@ -5087,6 +5160,8 @@ async function startWorker(options) {
   ws.addEventListener("message", (event) => {
     void (async () => {
       const message = JSON.parse(String(event.data));
+      if (!startupRecoveryComplete && message.type !== "ping") await startupRecoveryPromise;
+      if (!startupRecoveryComplete && message.type !== "ping") return;
       const messageAdmissionGeneration = workerAdmissionGeneration;
       const assertMessageAdmission = () => assertWorkerChildAdmission({
         capturedGeneration: messageAdmissionGeneration,
@@ -5094,7 +5169,7 @@ async function startWorker(options) {
         sourceSocketIsCurrent: currentWorkerSocket === ws,
         sourceSocketOpen: ws.readyState === WebSocket.OPEN,
         workspaceConfigured,
-        runtimeHealthy: !shutdownAfterClose && !heartbeatTimedOut
+        runtimeHealthy: !shutdownAfterClose
       });
       if (message.type === "connected") {
         return;
@@ -5114,6 +5189,19 @@ async function startWorker(options) {
           aheadOfOriginBranches: configured.aheadOfOriginBranches,
           ...configured.deferredWorkspaceSyncForIncidentId ? { deferredWorkspaceSyncForIncidentId: configured.deferredWorkspaceSyncForIncidentId } : {}
         });
+        sendLifecycleProgress(
+          configured.result.outcome === "failed" ? {
+            phase: "failed",
+            operationId: configured.result.attemptId,
+            detail: configured.result.error ?? "Workspace configuration failed"
+          } : {
+            phase: "ready",
+            operationId: configured.result.attemptId,
+            detail: `${message.projects.length} project(s) configured`,
+            completedItems: message.projects.length,
+            totalItems: message.projects.length
+          }
+        );
         process.stdout.write(
           `[r5d-worker] workspace configured: ${message.projects.length} project(s), ${configured.pending.length} pending checkout(s)
 `
@@ -5453,8 +5541,6 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "ping") {
-        lastServerHeartbeatAt = Date.now();
-        heartbeatBusyGrace = null;
         ws.send(JSON.stringify({ type: "pong" }));
         return;
       }
@@ -5868,15 +5954,12 @@ async function startWorker(options) {
     })().catch((error) => {
       process.stderr.write(`[r5d-worker] message handling failed: ${error instanceof Error ? error.message : String(error)}
 `);
-    }).finally(() => {
-      heartbeatBusyGrace = (0, import_heartbeat.grantWorkerHeartbeatBusyGrace)(lastServerHeartbeatAt, heartbeatBusyGrace);
     });
   });
   ws.addEventListener("close", (event) => {
     const processEvents = process;
     processEvents.off("SIGTERM", handleGracefulShutdown);
     processEvents.off("SIGINT", handleGracefulShutdown);
-    stopHeartbeatWatchdog();
     if (workspaceAutomaticTimer) {
       clearTimeout(workspaceAutomaticTimer);
       workspaceAutomaticTimer = void 0;
@@ -5907,6 +5990,21 @@ async function startWorker(options) {
     if (shutdownAfterClose) {
       process.exit(0);
     }
+    if (!startupRecoveryComplete) {
+      process.stderr.write("[r5d-worker] control connection closed during workspace recovery; finishing recovery before reconnecting\n");
+      void startupRecoveryPromise.then(() => {
+        if (!startupRecoveryComplete) {
+          process.exit(1);
+          return;
+        }
+        void startWorker(options).catch((error) => {
+          process.stderr.write(`[r5d-worker] reconnect failed: ${error instanceof Error ? error.message : String(error)}
+`);
+          process.exit(error instanceof WorkerServerUnavailableError ? import_supervisor.WORKER_RECONNECT_EXIT_CODE : 1);
+        });
+      });
+      return;
+    }
     if (activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0) {
       process.stderr.write(
         `[r5d-worker] ${activeProcesses.size} process(es), ${credentialBearingProcessGroups.size} owned process group(s), and ${activePtys.size} PTY(s) active with ${pendingProcessTerminals.size} terminal report(s) pending; reconnecting in ${import_supervisor.WORKER_RECONNECT_DELAY_MS}ms
@@ -5937,6 +6035,11 @@ async function startWorker(options) {
   });
 }
 async function main() {
+  if (process.argv[2] === import_project_snapshot_recovery_runner.PROJECT_SNAPSHOT_RECOVERY_HELPER_COMMAND) {
+    const exitCode2 = (0, import_project_snapshot_recovery_runner.runProjectSnapshotRecoveryHelper)(process.argv.slice(3));
+    if (exitCode2 !== 0) process.exit(exitCode2);
+    return;
+  }
   const parsed = parseArgs(process.argv.slice(2));
   if (parsed.command === "help") {
     printHelp();

package/dist/cjs/package.json

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

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

@@ -0,0 +1,171 @@
+"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
+});