@ricsam/r5d-worker 0.0.121 → 0.0.122

package/dist/cjs/main.cjs

@@ -74,6 +74,7 @@ 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_process_tree = require("./process-tree.cjs");
+var import_project_checkout_garbage = require("./project-checkout-garbage.cjs");
 var import_pty_output_coalescer = require("./pty-output-coalescer.cjs");
 var import_port_forward_client = require("./port-forward-client.cjs");
 var import_registry_auth = require("./registry-auth.cjs");
@@ -274,6 +275,15 @@ let workerAdmissionGeneration = 0;
 const workspaceMutationGate = new import_workspace_mutation_gate.WorkspaceMutationGate();
 let workspaceSyncQueue = Promise.resolve();
 let startupProjectSnapshotRecoveryCompleted = false;
+const checkoutGarbageCollectors = /* @__PURE__ */ new Map();
+function checkoutGarbageCollectorFor(projectsRoot) {
+  let collector = checkoutGarbageCollectors.get(projectsRoot);
+  if (!collector) {
+    collector = new import_project_checkout_garbage.ProjectCheckoutGarbageCollector({ projectsRoot });
+    checkoutGarbageCollectors.set(projectsRoot, collector);
+  }
+  return collector;
+}
 const workspaceSyncSingleFlight = {
   runExclusive(operation) {
     const queued = workspaceMutationGate.runSync(operation);
@@ -3704,6 +3714,12 @@ async function startWorker(options, projectRuntime = {
   projectRuntime.initializedWorkspaceState = initializedWorkspaceState;
   const projectWorkspaceStateStore = initializedWorkspaceState.store;
   let projectWorkspaceState = initializedWorkspaceState.store.read();
+  const checkoutGarbageCollector = checkoutGarbageCollectorFor(projectsRoot);
+  const staleStagedCheckouts = checkoutGarbageCollector.sweep();
+  if (staleStagedCheckouts > 0) {
+    process.stderr.write(`[r5d-worker] collecting ${staleStagedCheckouts} deleted checkout(s) left from an earlier run
+`);
+  }
   const { projectConfigById, readyProjectIds, reconciledProjectConfigFingerprints } = projectRuntime;
   const pendingCheckouts = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
@@ -3818,6 +3834,7 @@ async function startWorker(options, projectRuntime = {
 `
         );
       }
+      if (deleted.stagedForCollectionPath) checkoutGarbageCollector.enqueue(deleted.stagedForCollectionPath);
     }
     const planSourcePath = import_node_path.default.join(planRoot, project.projectId, ...branchName.split("/"));
     import_node_fs.default.rmSync(planSourcePath, { recursive: true, force: true });
@@ -3901,6 +3918,7 @@ async function startWorker(options, projectRuntime = {
 `
       );
     }
+    if (deleted.stagedForCollectionPath) checkoutGarbageCollector.enqueue(deleted.stagedForCollectionPath);
     import_node_fs.default.rmSync(import_node_path.default.join(planRoot, project.projectId, ...branchName.split("/")), { recursive: true, force: true });
     readyProjectIds.delete(project.projectId);
     reconciledProjectConfigFingerprints.delete(project.projectId);
@@ -5835,6 +5853,7 @@ async function startWorker(options, projectRuntime = {
           workspaceIncidentConfigDeferralV1: true,
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
+          projectBranchDeletionStagedRemovalV1: true,
           projectMirrorLeaseV1: true,
           projectMirrorRefsTokensV1: true,
           projectBranchWorkingTreeModeV1: true
@@ -5936,7 +5955,9 @@ async function startWorker(options, projectRuntime = {
         if (admission !== "new") {
           const response = recoveryStore.response(operationRequestId);
           if (response && admission !== "unknown") sendReplayWorkerMessage(ws, response);
-          return;
+          if (!(admission === "unknown" && message.type === "delete_project_branch" && recoveryStore.readmitUnknownBranchDeletion(operationRequestId))) {
+            return;
+          }
         }
       }
       const messageAdmissionGeneration = workerAdmissionGeneration;

package/dist/cjs/package.json

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

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

@@ -0,0 +1,190 @@
+"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_checkout_garbage_exports = {};
+__export(project_checkout_garbage_exports, {
+  PROJECT_DELETED_CHECKOUTS_DIRECTORY: () => PROJECT_DELETED_CHECKOUTS_DIRECTORY,
+  ProjectCheckoutGarbageCollector: () => ProjectCheckoutGarbageCollector,
+  discoverStagedProjectCheckouts: () => discoverStagedProjectCheckouts,
+  isStagedProjectCheckoutPath: () => isStagedProjectCheckoutPath,
+  ownedStagedPath: () => ownedStagedPath,
+  removeStagedProjectCheckout: () => removeStagedProjectCheckout,
+  stageProjectCheckoutForDeletion: () => stageProjectCheckoutForDeletion
+});
+module.exports = __toCommonJS(project_checkout_garbage_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
+function isRealDirectory(candidate) {
+  try {
+    return import_node_fs.default.lstatSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function stageProjectCheckoutForDeletion(projectRoot, branchName, checkoutPath) {
+  const garbageRoot = import_node_path.default.join(projectRoot, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+  if (!isRealDirectory(checkoutPath)) throw new Error(`Cannot stage ${checkoutPath} for deletion: not a directory`);
+  import_node_fs.default.mkdirSync(garbageRoot, { recursive: true });
+  if (!isRealDirectory(garbageRoot)) throw new Error(`Cannot stage ${checkoutPath} for deletion: ${garbageRoot} is not a directory`);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const target = import_node_path.default.join(garbageRoot, `${branchName.replace(/\//g, "__")}-${timestamp}-${(0, import_node_crypto.randomUUID)().slice(0, 8)}`);
+  import_node_fs.default.renameSync(checkoutPath, target);
+  return target;
+}
+function isStagedProjectCheckoutPath(projectsRoot, candidate) {
+  const relative = import_node_path.default.relative(import_node_path.default.resolve(projectsRoot), import_node_path.default.resolve(candidate));
+  if (!relative || relative.startsWith("..") || import_node_path.default.isAbsolute(relative)) return false;
+  const segments = relative.split(import_node_path.default.sep);
+  return segments.length === 4 && segments[2] === PROJECT_DELETED_CHECKOUTS_DIRECTORY && segments[3] !== "" && !segments[3].startsWith(".");
+}
+function ownedStagedPath(projectsRoot, candidate) {
+  const root = import_node_path.default.resolve(projectsRoot);
+  const resolved = import_node_path.default.resolve(candidate);
+  if (!isStagedProjectCheckoutPath(root, resolved)) return null;
+  let current = root;
+  for (const segment of import_node_path.default.relative(root, import_node_path.default.dirname(resolved)).split(import_node_path.default.sep)) {
+    current = import_node_path.default.join(current, segment);
+    if (!isRealDirectory(current)) return null;
+  }
+  let stat;
+  try {
+    stat = import_node_fs.default.lstatSync(resolved);
+  } catch {
+    return null;
+  }
+  if (stat.isSymbolicLink()) return { kind: "link" };
+  return stat.isDirectory() ? { kind: "directory" } : null;
+}
+function realDirectoryEntries(directory) {
+  if (!isRealDirectory(directory)) return [];
+  try {
+    return import_node_fs.default.readdirSync(directory, { withFileTypes: true }).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function discoverStagedProjectCheckouts(projectsRoot) {
+  const root = import_node_path.default.resolve(projectsRoot);
+  const staged = [];
+  for (const namespace of realDirectoryEntries(root)) {
+    if (namespace.startsWith(".")) continue;
+    for (const project of realDirectoryEntries(import_node_path.default.join(root, namespace))) {
+      if (project.startsWith(".")) continue;
+      const garbageRoot = import_node_path.default.join(root, namespace, project, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+      for (const entry of realDirectoryEntries(garbageRoot)) {
+        const candidate = import_node_path.default.join(garbageRoot, entry);
+        if (ownedStagedPath(root, candidate)) staged.push(candidate);
+      }
+    }
+  }
+  return staged;
+}
+async function removeStagedProjectCheckout(stagedPath) {
+  if (import_node_fs.default.lstatSync(stagedPath).isSymbolicLink()) {
+    import_node_fs.default.unlinkSync(stagedPath);
+    return;
+  }
+  if (process.platform === "win32") {
+    await import_node_fs.default.promises.rm(stagedPath, { recursive: true, force: true });
+    return;
+  }
+  const command = ["rm", "-rf", "--", stagedPath];
+  if (Bun.which("nice")) command.unshift("nice", "-n", "19");
+  if (process.platform === "linux" && Bun.which("ionice")) command.unshift("ionice", "-c", "3");
+  const child = Bun.spawn(command, { stdin: "ignore", stdout: "ignore", stderr: "pipe" });
+  const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+  if (exitCode !== 0) throw new Error(`rm exited ${exitCode}: ${stderr.trim()}`);
+  if (import_node_fs.default.existsSync(stagedPath)) throw new Error("staged checkout still exists after removal");
+}
+class ProjectCheckoutGarbageCollector {
+  projectsRoot;
+  remove;
+  log;
+  queued = /* @__PURE__ */ new Set();
+  tail = Promise.resolve();
+  collectedCount = 0;
+  constructor(options) {
+    this.projectsRoot = import_node_path.default.resolve(options.projectsRoot);
+    this.remove = options.remove ?? removeStagedProjectCheckout;
+    this.log = options.log ?? ((message) => process.stderr.write(`${message}
+`));
+  }
+  /** Number of removals that have completed successfully. */
+  get collected() {
+    return this.collectedCount;
+  }
+  /** Resolves once everything queued so far has been attempted. */
+  get idle() {
+    return this.tail;
+  }
+  enqueue(stagedPath) {
+    const resolved = import_node_path.default.resolve(stagedPath);
+    if (!ownedStagedPath(this.projectsRoot, resolved)) {
+      throw new Error(`Refusing to collect ${stagedPath}: not a staged checkout under ${this.projectsRoot}`);
+    }
+    if (this.queued.has(resolved)) return;
+    this.queued.add(resolved);
+    this.tail = this.tail.then(async () => {
+      try {
+        const owned = ownedStagedPath(this.projectsRoot, resolved);
+        if (owned) {
+          const startedAt = performance.now();
+          await this.remove(resolved);
+          this.collectedCount += 1;
+          this.log(`[r5d-worker] collected deleted checkout ${resolved} in ${Math.round(performance.now() - startedAt)}ms`);
+        } else if (import_node_fs.default.existsSync(resolved) || isRealDirectory(import_node_path.default.dirname(resolved))) {
+          this.log(`[r5d-worker] skipped deleted checkout ${resolved}: no longer an owned staged checkout`);
+        }
+      } catch (error) {
+        this.log(
+          `[r5d-worker] deleted checkout ${resolved} could not be collected yet: ${error instanceof Error ? error.message : String(error)}`
+        );
+      } finally {
+        this.queued.delete(resolved);
+      }
+    });
+  }
+  /** Enqueue every staged checkout left behind by an earlier process. */
+  sweep() {
+    const staged = discoverStagedProjectCheckouts(this.projectsRoot);
+    for (const stagedPath of staged) this.enqueue(stagedPath);
+    return staged.length;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROJECT_DELETED_CHECKOUTS_DIRECTORY,
+  ProjectCheckoutGarbageCollector,
+  discoverStagedProjectCheckouts,
+  isStagedProjectCheckoutPath,
+  ownedStagedPath,
+  removeStagedProjectCheckout,
+  stageProjectCheckoutForDeletion
+});

package/dist/cjs/project-worktrees.cjs

@@ -61,6 +61,7 @@ var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_git_process_environment = require("./git-process-environment.cjs");
 var import_managed_paths = require("./managed-paths.cjs");
+var import_project_checkout_garbage = require("./project-checkout-garbage.cjs");
 var import_project_mirror_refs_token = require("./project-mirror-refs-token.cjs");
 var import_working_tree_mirror = require("./working-tree-mirror.cjs");
 const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
@@ -1340,6 +1341,7 @@ function deleteLinkedProjectBranch(input) {
   const primaryCommonDir = commonGitDirectory(primaryPath);
   if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
   let movedAsidePath;
+  let stagedForCollectionPath;
   if (import_node_fs.default.existsSync(checkoutPath)) {
     const checkoutCommonDir = import_node_fs.default.lstatSync(checkoutPath).isDirectory() ? commonGitDirectory(checkoutPath) : null;
     if (checkoutCommonDir !== primaryCommonDir) {
@@ -1349,7 +1351,8 @@ function deleteLinkedProjectBranch(input) {
       if (projectWorktreeOperationInProgress(checkoutPath)) {
         throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
       }
-      git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
+      stagedForCollectionPath = (0, import_project_checkout_garbage.stageProjectCheckoutForDeletion)(input.projectRoot, input.branchName, checkoutPath);
+      git(primaryPath, ["worktree", "prune"], `prune linked worktree ${input.branchName}`);
     }
   } else {
     tryGit(primaryPath, ["worktree", "prune"]);
@@ -1358,7 +1361,11 @@ function deleteLinkedProjectBranch(input) {
   if (tryGit(primaryPath, ["show-ref", "--verify", "--quiet", branchRef])) {
     git(primaryPath, ["branch", "-D", input.branchName], `delete project branch ${input.branchName}`);
   }
-  return { branchName: input.branchName, ...movedAsidePath ? { movedAsidePath } : {} };
+  return {
+    branchName: input.branchName,
+    ...movedAsidePath ? { movedAsidePath } : {},
+    ...stagedForCollectionPath ? { stagedForCollectionPath } : {}
+  };
 }
 function removeProjectWorktrees(input) {
   const projectRoot = import_node_path.default.resolve(input.projectRoot);

package/dist/cjs/recovery-store.cjs

@@ -98,6 +98,19 @@ class WorkerRecoveryStore {
   isUnknown(requestId) {
     return this.row(requestId)?.state === "unknown";
   }
+  /**
+   * Re-admit an operation whose crash outcome is unknown so it can run again
+   * and record a result. Only a branch deletion qualifies: it is idempotent
+   * for its exact incarnation (durable tombstone plus incarnation preflight),
+   * so a rerun converges on the same outcome. Every other unknown operation
+   * keeps the no-replay invariant.
+   */
+  readmitUnknownBranchDeletion(requestId) {
+    const row = this.row(requestId);
+    if (!row || row.state !== "unknown" || row.request_type !== "delete_project_branch") return false;
+    this.db.run("UPDATE operations SET state='accepted', response=NULL WHERE request_id=?", [row.request_id]);
+    return true;
+  }
   unknown(requestId) {
     const row = this.row(requestId);
     if (row) this.db.run("UPDATE operations SET state='unknown' WHERE request_id=?", [row.request_id]);

package/dist/mjs/main.mjs

@@ -25,6 +25,7 @@ import { Database } from "bun:sqlite";
 import { installCliUpdate, readInstalledCliVersion } from "./cli-update.mjs";
 import { gitTransportSecurityArgs, workerGitProcessEnvironment } from "./git-process-environment.mjs";
 import { terminateProcessTree } from "./process-tree.mjs";
+import { ProjectCheckoutGarbageCollector } from "./project-checkout-garbage.mjs";
 import { createPtyOutputCoalescer } from "./pty-output-coalescer.mjs";
 import { openWorkerPortForwardRelay } from "./port-forward-client.mjs";
 import {
@@ -293,6 +294,15 @@ let workerAdmissionGeneration = 0;
 const workspaceMutationGate = new WorkspaceMutationGate();
 let workspaceSyncQueue = Promise.resolve();
 let startupProjectSnapshotRecoveryCompleted = false;
+const checkoutGarbageCollectors = /* @__PURE__ */ new Map();
+function checkoutGarbageCollectorFor(projectsRoot) {
+  let collector = checkoutGarbageCollectors.get(projectsRoot);
+  if (!collector) {
+    collector = new ProjectCheckoutGarbageCollector({ projectsRoot });
+    checkoutGarbageCollectors.set(projectsRoot, collector);
+  }
+  return collector;
+}
 const workspaceSyncSingleFlight = {
   runExclusive(operation) {
     const queued = workspaceMutationGate.runSync(operation);
@@ -3723,6 +3733,12 @@ async function startWorker(options, projectRuntime = {
   projectRuntime.initializedWorkspaceState = initializedWorkspaceState;
   const projectWorkspaceStateStore = initializedWorkspaceState.store;
   let projectWorkspaceState = initializedWorkspaceState.store.read();
+  const checkoutGarbageCollector = checkoutGarbageCollectorFor(projectsRoot);
+  const staleStagedCheckouts = checkoutGarbageCollector.sweep();
+  if (staleStagedCheckouts > 0) {
+    process.stderr.write(`[r5d-worker] collecting ${staleStagedCheckouts} deleted checkout(s) left from an earlier run
+`);
+  }
   const { projectConfigById, readyProjectIds, reconciledProjectConfigFingerprints } = projectRuntime;
   const pendingCheckouts = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
@@ -3837,6 +3853,7 @@ async function startWorker(options, projectRuntime = {
 `
         );
       }
+      if (deleted.stagedForCollectionPath) checkoutGarbageCollector.enqueue(deleted.stagedForCollectionPath);
     }
     const planSourcePath = path.join(planRoot, project.projectId, ...branchName.split("/"));
     fs.rmSync(planSourcePath, { recursive: true, force: true });
@@ -3920,6 +3937,7 @@ async function startWorker(options, projectRuntime = {
 `
       );
     }
+    if (deleted.stagedForCollectionPath) checkoutGarbageCollector.enqueue(deleted.stagedForCollectionPath);
     fs.rmSync(path.join(planRoot, project.projectId, ...branchName.split("/")), { recursive: true, force: true });
     readyProjectIds.delete(project.projectId);
     reconciledProjectConfigFingerprints.delete(project.projectId);
@@ -5854,6 +5872,7 @@ async function startWorker(options, projectRuntime = {
           workspaceIncidentConfigDeferralV1: true,
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
+          projectBranchDeletionStagedRemovalV1: true,
           projectMirrorLeaseV1: true,
           projectMirrorRefsTokensV1: true,
           projectBranchWorkingTreeModeV1: true
@@ -5955,7 +5974,9 @@ async function startWorker(options, projectRuntime = {
         if (admission !== "new") {
           const response = recoveryStore.response(operationRequestId);
           if (response && admission !== "unknown") sendReplayWorkerMessage(ws, response);
-          return;
+          if (!(admission === "unknown" && message.type === "delete_project_branch" && recoveryStore.readmitUnknownBranchDeletion(operationRequestId))) {
+            return;
+          }
         }
       }
       const messageAdmissionGeneration = workerAdmissionGeneration;

package/dist/mjs/package.json

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

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

@@ -0,0 +1,150 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
+function isRealDirectory(candidate) {
+  try {
+    return fs.lstatSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function stageProjectCheckoutForDeletion(projectRoot, branchName, checkoutPath) {
+  const garbageRoot = path.join(projectRoot, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+  if (!isRealDirectory(checkoutPath)) throw new Error(`Cannot stage ${checkoutPath} for deletion: not a directory`);
+  fs.mkdirSync(garbageRoot, { recursive: true });
+  if (!isRealDirectory(garbageRoot)) throw new Error(`Cannot stage ${checkoutPath} for deletion: ${garbageRoot} is not a directory`);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const target = path.join(garbageRoot, `${branchName.replace(/\//g, "__")}-${timestamp}-${randomUUID().slice(0, 8)}`);
+  fs.renameSync(checkoutPath, 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(".");
+}
+function ownedStagedPath(projectsRoot, candidate) {
+  const root = path.resolve(projectsRoot);
+  const resolved = path.resolve(candidate);
+  if (!isStagedProjectCheckoutPath(root, resolved)) return null;
+  let current = root;
+  for (const segment of path.relative(root, path.dirname(resolved)).split(path.sep)) {
+    current = path.join(current, segment);
+    if (!isRealDirectory(current)) return null;
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(resolved);
+  } catch {
+    return null;
+  }
+  if (stat.isSymbolicLink()) return { kind: "link" };
+  return stat.isDirectory() ? { kind: "directory" } : null;
+}
+function realDirectoryEntries(directory) {
+  if (!isRealDirectory(directory)) return [];
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true }).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function discoverStagedProjectCheckouts(projectsRoot) {
+  const root = path.resolve(projectsRoot);
+  const staged = [];
+  for (const namespace of realDirectoryEntries(root)) {
+    if (namespace.startsWith(".")) continue;
+    for (const project of realDirectoryEntries(path.join(root, namespace))) {
+      if (project.startsWith(".")) continue;
+      const garbageRoot = path.join(root, namespace, project, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+      for (const entry of realDirectoryEntries(garbageRoot)) {
+        const candidate = path.join(garbageRoot, entry);
+        if (ownedStagedPath(root, candidate)) staged.push(candidate);
+      }
+    }
+  }
+  return staged;
+}
+async function removeStagedProjectCheckout(stagedPath) {
+  if (fs.lstatSync(stagedPath).isSymbolicLink()) {
+    fs.unlinkSync(stagedPath);
+    return;
+  }
+  if (process.platform === "win32") {
+    await fs.promises.rm(stagedPath, { recursive: true, force: true });
+    return;
+  }
+  const command = ["rm", "-rf", "--", stagedPath];
+  if (Bun.which("nice")) command.unshift("nice", "-n", "19");
+  if (process.platform === "linux" && Bun.which("ionice")) command.unshift("ionice", "-c", "3");
+  const child = Bun.spawn(command, { stdin: "ignore", stdout: "ignore", stderr: "pipe" });
+  const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+  if (exitCode !== 0) throw new Error(`rm exited ${exitCode}: ${stderr.trim()}`);
+  if (fs.existsSync(stagedPath)) throw new Error("staged checkout still exists after removal");
+}
+class ProjectCheckoutGarbageCollector {
+  projectsRoot;
+  remove;
+  log;
+  queued = /* @__PURE__ */ new Set();
+  tail = Promise.resolve();
+  collectedCount = 0;
+  constructor(options) {
+    this.projectsRoot = path.resolve(options.projectsRoot);
+    this.remove = options.remove ?? removeStagedProjectCheckout;
+    this.log = options.log ?? ((message) => process.stderr.write(`${message}
+`));
+  }
+  /** Number of removals that have completed successfully. */
+  get collected() {
+    return this.collectedCount;
+  }
+  /** Resolves once everything queued so far has been attempted. */
+  get idle() {
+    return this.tail;
+  }
+  enqueue(stagedPath) {
+    const resolved = path.resolve(stagedPath);
+    if (!ownedStagedPath(this.projectsRoot, resolved)) {
+      throw new Error(`Refusing to collect ${stagedPath}: not a staged checkout under ${this.projectsRoot}`);
+    }
+    if (this.queued.has(resolved)) return;
+    this.queued.add(resolved);
+    this.tail = this.tail.then(async () => {
+      try {
+        const owned = ownedStagedPath(this.projectsRoot, resolved);
+        if (owned) {
+          const startedAt = performance.now();
+          await this.remove(resolved);
+          this.collectedCount += 1;
+          this.log(`[r5d-worker] collected deleted checkout ${resolved} in ${Math.round(performance.now() - startedAt)}ms`);
+        } else if (fs.existsSync(resolved) || isRealDirectory(path.dirname(resolved))) {
+          this.log(`[r5d-worker] skipped deleted checkout ${resolved}: no longer an owned staged checkout`);
+        }
+      } catch (error) {
+        this.log(
+          `[r5d-worker] deleted checkout ${resolved} could not be collected yet: ${error instanceof Error ? error.message : String(error)}`
+        );
+      } finally {
+        this.queued.delete(resolved);
+      }
+    });
+  }
+  /** Enqueue every staged checkout left behind by an earlier process. */
+  sweep() {
+    const staged = discoverStagedProjectCheckouts(this.projectsRoot);
+    for (const stagedPath of staged) this.enqueue(stagedPath);
+    return staged.length;
+  }
+}
+export {
+  PROJECT_DELETED_CHECKOUTS_DIRECTORY,
+  ProjectCheckoutGarbageCollector,
+  discoverStagedProjectCheckouts,
+  isStagedProjectCheckoutPath,
+  ownedStagedPath,
+  removeStagedProjectCheckout,
+  stageProjectCheckoutForDeletion
+};

package/dist/mjs/project-worktrees.mjs

@@ -4,6 +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 {
   canonicalizeLocalProjectMirrorRefs,
   parseProjectMirrorRefListing,
@@ -1290,6 +1291,7 @@ function deleteLinkedProjectBranch(input) {
   const primaryCommonDir = commonGitDirectory(primaryPath);
   if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
   let movedAsidePath;
+  let stagedForCollectionPath;
   if (fs.existsSync(checkoutPath)) {
     const checkoutCommonDir = fs.lstatSync(checkoutPath).isDirectory() ? commonGitDirectory(checkoutPath) : null;
     if (checkoutCommonDir !== primaryCommonDir) {
@@ -1299,7 +1301,8 @@ function deleteLinkedProjectBranch(input) {
       if (projectWorktreeOperationInProgress(checkoutPath)) {
         throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
       }
-      git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
+      stagedForCollectionPath = stageProjectCheckoutForDeletion(input.projectRoot, input.branchName, checkoutPath);
+      git(primaryPath, ["worktree", "prune"], `prune linked worktree ${input.branchName}`);
     }
   } else {
     tryGit(primaryPath, ["worktree", "prune"]);
@@ -1308,7 +1311,11 @@ function deleteLinkedProjectBranch(input) {
   if (tryGit(primaryPath, ["show-ref", "--verify", "--quiet", branchRef])) {
     git(primaryPath, ["branch", "-D", input.branchName], `delete project branch ${input.branchName}`);
   }
-  return { branchName: input.branchName, ...movedAsidePath ? { movedAsidePath } : {} };
+  return {
+    branchName: input.branchName,
+    ...movedAsidePath ? { movedAsidePath } : {},
+    ...stagedForCollectionPath ? { stagedForCollectionPath } : {}
+  };
 }
 function removeProjectWorktrees(input) {
   const projectRoot = path.resolve(input.projectRoot);

package/dist/mjs/recovery-store.mjs

@@ -64,6 +64,19 @@ class WorkerRecoveryStore {
   isUnknown(requestId) {
     return this.row(requestId)?.state === "unknown";
   }
+  /**
+   * Re-admit an operation whose crash outcome is unknown so it can run again
+   * and record a result. Only a branch deletion qualifies: it is idempotent
+   * for its exact incarnation (durable tombstone plus incarnation preflight),
+   * so a rerun converges on the same outcome. Every other unknown operation
+   * keeps the no-replay invariant.
+   */
+  readmitUnknownBranchDeletion(requestId) {
+    const row = this.row(requestId);
+    if (!row || row.state !== "unknown" || row.request_type !== "delete_project_branch") return false;
+    this.db.run("UPDATE operations SET state='accepted', response=NULL WHERE request_id=?", [row.request_id]);
+    return true;
+  }
   unknown(requestId) {
     const row = this.row(requestId);
     if (row) this.db.run("UPDATE operations SET state='unknown' WHERE request_id=?", [row.request_id]);

package/dist/types/project-checkout-garbage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a deleted branch checkout waits for collection. Staging is the only
+ * platform write into this directory and a live checkout always lives at
+ * `<projectRoot>/<branch>`, so a crash between staging and collection leaves
+ * nothing that a later sweep could confuse with a replacement branch. The
+ * filesystem is user-managed, though, so the collector never trusts the name
+ * alone: it removes only real directories or leaf links that sit under a real
+ * garbage directory of a real project directory (see `ownedStagedPath`).
+ * Distinct from `.r5d-removed`, which preserves paths that were not this
+ * project's worktree.
+ */
+export declare const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
+/**
+ * Rename a checkout this project owns out of the active namespace. One
+ * same-filesystem rename takes milliseconds whatever the tree holds, so the
+ * branch mutation lease is released long before the bytes are gone. The
+ * garbage directory must be a real directory: a planted link would make the
+ * later collection walk through it, so staging refuses rather than continue.
+ */
+export declare function stageProjectCheckoutForDeletion(projectRoot: string, branchName: string, checkoutPath: string): string;
+/** True when `candidate` is lexically a direct entry of some project's garbage directory under `projectsRoot`. */
+export declare function isStagedProjectCheckoutPath(projectsRoot: string, candidate: string): boolean;
+/**
+ * Whether a lexically staged path is safe to remove right now: every ancestor
+ * below the projects root is a real directory (a linked namespace, project,
+ * or garbage directory would let a removal reach an unrelated tree through
+ * the link), and the entry itself is a real directory or a leaf link. Checked
+ * again immediately before the removal starts, never only at enqueue time.
+ */
+export declare function ownedStagedPath(projectsRoot: string, candidate: string): {
+    kind: "directory" | "link";
+} | null;
+/** Every owned staged checkout under `<projectsRoot>/<namespace>/<project>/.r5d-deleted/`; linked ancestors are not followed. */
+export declare function discoverStagedProjectCheckouts(projectsRoot: string): string[];
+/**
+ * Delete a staged tree in a child process so a large recursive removal never
+ * runs on the worker event loop, at the lowest CPU and (where supported) I/O
+ * priority so live agents on the same volume keep their share. A leaf link is
+ * unlinked in place; its target is never followed.
+ */
+export declare function removeStagedProjectCheckout(stagedPath: string): Promise<void>;
+type Logger = (message: string) => void;
+/**
+ * Collects staged checkouts one at a time, outside every workspace lease.
+ * Entries are enqueued right after staging and by `sweep()` at worker start,
+ * so a crash at any point converges on the next start. A failed removal is
+ * logged and left for the next sweep.
+ */
+export declare class ProjectCheckoutGarbageCollector {
+    private readonly projectsRoot;
+    private readonly remove;
+    private readonly log;
+    private readonly queued;
+    private tail;
+    private collectedCount;
+    constructor(options: {
+        projectsRoot: string;
+        remove?: (stagedPath: string) => Promise<void>;
+        log?: Logger;
+    });
+    /** Number of removals that have completed successfully. */
+    get collected(): number;
+    /** Resolves once everything queued so far has been attempted. */
+    get idle(): Promise<void>;
+    enqueue(stagedPath: string): void;
+    /** Enqueue every staged checkout left behind by an earlier process. */
+    sweep(): number;
+}
+export {};

package/dist/types/project-worktrees.d.ts

@@ -209,6 +209,12 @@ export declare function deleteLinkedProjectBranch(input: {
     branchName: string;
     /** Where a path that was not this project's linked worktree was set aside instead of being deleted. */
     movedAsidePath?: string;
+    /**
+     * Where the linked worktree's tree now waits for garbage collection. The
+     * branch is already gone from Git; the caller hands this path to the
+     * collector so the recursive removal runs outside every workspace lease.
+     */
+    stagedForCollectionPath?: string;
 };
 export declare function removeProjectWorktrees(input: {
     projectRoot: string;

package/dist/types/recovery-store.d.ts

@@ -16,6 +16,14 @@ export declare class WorkerRecoveryStore {
         requestId: string;
     }): "new" | "duplicate" | "unknown" | "conflict";
     isUnknown(requestId: string): boolean;
+    /**
+     * Re-admit an operation whose crash outcome is unknown so it can run again
+     * and record a result. Only a branch deletion qualifies: it is idempotent
+     * for its exact incarnation (durable tombstone plus incarnation preflight),
+     * so a rerun converges on the same outcome. Every other unknown operation
+     * keeps the no-replay invariant.
+     */
+    readmitUnknownBranchDeletion(requestId: string): boolean;
     unknown(requestId: string): void;
     unknownRun(runId: string): void;
     record(message: Message): Message;

package/package.json

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