Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(process): record evaluated alternatives for background worktree removal (#2206)
Maximilian Roosb320a3d8fecd
diff --git a/src/commands/process.rs b/src/commands/process.rsindex c9f947700..1bb6b2506 100644--- a/src/commands/process.rs+++ b/src/commands/process.rs@@ -539,6 +539,99 @@ fn parse_trash_entry_timestamp(name: &str) -> Option<u64> {////// When `changed_directory` is false, no placeholder exists, so the background/// command just removes the staged directory directly.+///+/// # Design alternatives evaluated (2026-04)+///+/// Two weaknesses in the current design prompted an investigation:+///+/// 1. **Silent `rmdir` failure.** If anything lands in the placeholder+/// during the 1-second sleep (e.g., macOS `.DS_Store`, a filesystem+/// race, an editor saving against the old path), `rmdir` fails silently+/// because of `2>/dev/null`, and the empty directory at `original_path`+/// lingers forever. This was the root cause of an intermittent+/// `test_bare_repo_merge_workflow` flake.+/// 2. **"Create then delete" placeholder lifecycle.** wt creates an empty+/// directory that the background shell removes one second later; its+/// only purpose is keeping `$PWD` valid for shells (notably Nushell)+/// that stat it between wt's exit and the wrapper's `cd`.+///+/// Two alternatives were prototyped and reviewed; neither was adopted.+///+/// ## Option A — Fully deferred cleanup with a pending-removal marker+///+/// Sync phase shrinks to: write a `PendingRemoval` marker under+/// `<git-common-dir>/wt/pending/`, spawn detached `wt internal+/// finish-removal <marker>`, exit. The detached process sleeps 1 second,+/// then does rename + prune + `branch -D` + `rm -rf` + marker delete —+/// the work that today happens synchronously. Concurrent operations+/// (e.g., `wt switch --create <same-branch>` within the 1-second window)+/// check for matching markers and force-finish the cleanup inline via a+/// `finish_blocking_for` helper. Crashed cleanup processes are reclaimed+/// by extending the existing `sweep_stale_trash` path with a+/// `sweep_stale_pending` variant.+///+/// Benefits: eliminates the placeholder lifecycle entirely (the original+/// path never disappears during wt's execution, so `$PWD` stays valid+/// "for free"); no `rmdir` silent-failure mode; marker-based+/// coordination on the recreate race.+///+/// Drawbacks surfaced by Codex review:+///+/// - **Data safety (P1).** The clean-check runs sync but the rename+/// runs ~1 second later. Writes to existing files during that window+/// (editor save, background build) are silently renamed into trash+/// and `rm -rf`'d. Today's sync rename keeps that window+/// microsecond-wide. Mitigation: revalidate cleanliness in the+/// finisher and bail on dirty — but that turns "remove" into a silent+/// no-op visible only in log files.+/// - **Hook timing (P2).** `spawn_hooks_after_remove` runs right after+/// the sync phase returns. In the deferred design, `post-remove`+/// hooks fire while `git worktree list` still reports the worktree+/// and the branch still exists, contrary to the hook's documented+/// contract. Fix: move hook invocation into the finisher.+/// - **Retained-branch coordination (P1).** The marker's `branch` field+/// must be recorded independently of the `delete_branch` flag, or+/// `finish_blocking_for(Some("feature"), ..)` misses markers whose+/// branch was retained (`--no-delete-branch`, unmerged safe-delete).+/// - **Complexity cost.** New module (`src/commands/pending.rs`), new+/// hidden CLI subcommand (`wt internal finish-removal`), sweep+/// recovery, coordination calls in `plan_switch`,+/// `validate_worktree_creation`, and `handle_remove_command`. ~450+/// lines of new code plus tests.+///+/// ## Option B — Sync rename + `rm -rf` instead of `rmdir`+///+/// Keep the current sync phase (rename + prune + `branch -D` + create+/// placeholder), add the pending-removal marker + coordination hooks,+/// and in this function substitute `rm -rf <placeholder>` for+/// `rmdir <placeholder> 2>/dev/null`.+///+/// Benefits: fixes the flake's root cause (silent-failure mode gone);+/// inherits marker-based coordination; keeps the data-safety window at+/// microseconds; keeps hook timing correct.+///+/// Drawbacks:+///+/// - Doesn't eliminate the "create then delete" placeholder pattern —+/// just makes its cleanup robust.+/// - Introduces a narrow new window: if something writes to the+/// placeholder during the 1-second sleep, `rm -rf` deletes it.+/// Today's silent `rmdir` accidentally preserves such writes as+/// orphaned leftovers (ugly but data-preserving). Mitigation:+/// revalidate emptiness in the finisher and skip `rm -rf` on+/// non-empty placeholders — turns that accidental preservation into a+/// deliberate invariant.+///+/// ## Decision+///+/// Neither was adopted. The flaky test was fixed at the test layer by+/// teaching `wait_for_worktree_removed` to accept "gone or empty+/// placeholder" as the success condition — matching what+/// `assert_worktree_removed` already documents. If flakiness resurfaces+/// or the visible-placeholder aesthetic becomes a real friction point,+/// Option B is the low-risk path forward: strictly dominates main+/// except for the narrow write-into-placeholder edge case, and reuses+/// most of the pending-module work from Option A.pub fn build_remove_command_staged(staged_path: &std::path::Path,original_path: &std::path::Path,diff --git a/src/testing/mod.rs b/src/testing/mod.rsindex 8bbb0ec27..ec21521f2 100644--- a/src/testing/mod.rs+++ b/src/testing/mod.rs@@ -2199,25 +2199,52 @@ fn exponential_sleep(attempt: u32) {ExponentialBackoff::default().sleep(attempt);}-/// Assert that a worktree's contents have been removed.+/// True when a worktree's contents have been removed — either the path+/// is gone, or it's an empty placeholder directory.///-/// After background removal, the path may briefly exist as an empty placeholder-/// directory (for shell PWD validity). This asserts the contents are gone —-/// either the path doesn't exist, or it's an empty directory.-pub fn assert_worktree_removed(path: &Path) {- // Use read_dir as the single check to avoid a TOCTOU race where the- // background process removes the placeholder between exists() and read_dir().- let is_empty_or_gone = match path.read_dir() {+/// After the instant-removal path renames the worktree into trash, the+/// original path can linger as an empty placeholder until the background+/// shell's `sleep 1 && rmdir` runs (the placeholder keeps `$PWD` valid+/// for shells like Nushell that validate it). The `rmdir` silences+/// errors with `2>/dev/null` and only removes empty directories, so+/// under load — or when any stray file (e.g., `.DS_Store`) lands in the+/// placeholder — the path can remain indefinitely. Production doesn't+/// care (empty placeholder is harmless); tests that do a strict+/// `!path.exists()` check would flake.+fn worktree_contents_removed(path: &Path) -> bool {+ // Single `read_dir` avoids a TOCTOU race between `exists()` and the+ // background process removing the placeholder.+ match path.read_dir() {Ok(mut entries) => entries.next().is_none(), // empty placeholderErr(_) => true, // already gone (NotFound or other)- };+ }+}++/// Assert that a worktree's contents have been removed.+///+/// Mirrors `worktree_contents_removed`: the path must be either gone+/// or an empty placeholder.+pub fn assert_worktree_removed(path: &Path) {assert!(- is_empty_or_gone,+ worktree_contents_removed(path),"Worktree contents should be removed (empty placeholder OK): {}",path.display());}+/// Poll until a worktree's contents have been removed.+///+/// Prefer this over `wait_for(..., || !path.exists())` when removal+/// goes through the instant-removal path (`wt merge`, `wt remove`),+/// which can leave an empty placeholder directory. See+/// `worktree_contents_removed`.+pub fn wait_for_worktree_removed(path: &Path) {+ wait_for(+ &format!("worktree contents removed: {}", path.display()),+ || worktree_contents_removed(path),+ );+}+/// Wait for a file to exist, polling with exponential backoff./// Use this instead of fixed sleeps for background commands to avoid flaky tests.pub fn wait_for_file(path: &Path) {diff --git a/tests/integration_tests/bare_repository.rs b/tests/integration_tests/bare_repository.rsindex 4173ec3cd..06749a6af 100644--- a/tests/integration_tests/bare_repository.rs+++ b/tests/integration_tests/bare_repository.rs@@ -1,7 +1,7 @@use crate::common::{BareRepoTest, TestRepo, TestRepoBase, canonicalize, configure_directive_files,configure_git_cmd, configure_git_env, directive_files, repo, setup_temp_snapshot_settings,- wait_for, wait_for_file, wait_for_file_content, wt_command,+ wait_for_file, wait_for_file_content, wait_for_worktree_removed, wt_command,};use insta_cmd::assert_cmd_snapshot;use rstest::rstest;@@ -652,7 +652,12 @@ fn test_bare_repo_merge_workflow() {}// Wait for background removal to complete- wait_for("feature worktree removed", || !feature_worktree.exists());+ // Use the "gone or empty placeholder" predicate — the instant-removal+ // path leaves an empty dir behind if the background `rmdir` silently+ // fails (stray `.DS_Store`, scheduling delay under parallel load).+ // That placeholder is production-harmless but trips a strict+ // `!exists()` check.+ wait_for_worktree_removed(&feature_worktree);// Verify main worktree still exists and has the feature commitassert!(main_worktree.exists());