fix(worktree): reconcile detached-HEAD worktrees, run prune on clean, clamp zero timeout (#6051)

reconcile() previously dropped any worktree whose git worktree list
--porcelain block lacked a branch line (detached HEAD), making such
entries permanently invisible to list/clean. The porcelain parser now
flushes on the worktree <path> line alone and assigns a sentinel
branch_name that is provably not a valid git ref, so it can never
collide with a real (including foreign, non-zeph) branch (#5936).

zeph worktree clean now runs git worktree prune once after removing
stale entries, per spec-063 FR-CLEANUP-04 (#5937).

DefaultGitRunner now clamps git_timeout_secs=0 to a 1-second floor
internally, so the invariant holds regardless of caller; the two
ad hoc .max(1) call sites and the bypassable derived Default impl
are removed (#5939).

Author: bug-ops

CHANGELOG.md

@@ -110,6 +110,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   classification) is now constructed and registered as a tool executor, with its trust-snapshot
   `Arc` also threaded onto the `Agent` via `with_trust_snapshot`, in ACP and daemon — previously
   `invoke_skill` was effectively CLI-only (#5975).
+- `fix(worktree)`: `WorktreeManager::reconcile()` no longer silently drops detached-`HEAD`
+  worktrees (#5936). `git worktree list --porcelain` emits a `detached` line instead of
+  `branch refs/heads/<name>` for these worktrees; the porcelain parser previously only flushed a
+  parsed block when both a `worktree <path>` line and a `branch` line were seen, so detached
+  entries were discarded and became permanently invisible to `zeph worktree list`/`zeph worktree
+  clean`. A block is now flushed whenever its `worktree <path>` line is seen, and detached
+  entries get the new `zeph_worktree::DETACHED_BRANCH_SENTINEL` (`"(detached HEAD)"` — the
+  embedded space makes it an invalid git ref name, so it can never collide with a real branch,
+  including one on a worktree foreign to zeph) as their `branch_name`; `WorktreeManager::remove`
+  skips the `git branch -D` step for this sentinel since there is no real branch to prune, while
+  the `git worktree remove --force` path is unaffected (it operates on `path`, not
+  `branch_name`).
+- `fix(worktree)`: `zeph worktree clean` now runs `git worktree prune` after removing stale
+  entries, per spec-063 FR-CLEANUP-04 (#5937). Previously it only issued `git worktree remove
+  --force` for entries discovered by `reconcile()`, leaving any stale administrative files (e.g.
+  from a worktree directory deleted outside Zeph) in the git registry. Added
+  `WorktreeManager::prune()`.
+- `fix(worktree)`: `DefaultGitRunner` now clamps `git_timeout_secs = 0` (and any sub-second
+  timeout) to a 1-second floor inside `new()`/`with_timeout()` itself, per spec-063's NEVER
+  invariant (#5939). Previously the clamp was duplicated ad hoc at two call sites
+  (`src/runner.rs`, `src/commands/worktree.rs`) and the crate's own `Default` impl bypassed both,
+  so `DefaultGitRunner::default()` (and any other future call site) could still construct a
+  zero-timeout runner where every `git` invocation failed instantly. Both call-site `.max(1)`
+  duplications were removed now that the crate enforces the invariant internally; the
+  `git_timeout_secs` doc comment on `WorktreeConfig` was corrected to say so.
 - `fix(tools)`: `CompressedExecutor`, `ToolFilter`, and `Arc<ShellExecutor>` now forward the
   remaining cross-cutting `ToolExecutor` methods to their inner/wrapped executor instead of
   silently falling through to the trait's no-op defaults (#6012). `CompressedExecutor` now

crates/zeph-config/src/worktree.rs

@@ -79,7 +79,9 @@ pub struct WorktreeConfig {
     /// Applied to every `git` call issued by the worktree subsystem (e.g.
     /// `git worktree add`, `git fetch`, `git rev-parse`).  Increase this value
     /// on repositories that are slow to clone or when running over high-latency
-    /// network links.  A value of `0` is treated as `1` at the call site.
+    /// network links.  A value of `0` is clamped to `1` second by
+    /// [`DefaultGitRunner`](https://docs.rs/zeph-worktree/latest/zeph_worktree/git_runner/struct.DefaultGitRunner.html),
+    /// not by any call site.
     pub git_timeout_secs: u64,
 }
 

crates/zeph-worktree/src/git_runner.rs

@@ -52,24 +52,39 @@ pub trait GitRunner: Send + Sync {
 /// # Ok(())
 /// # }
 /// ```
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Clone)]
 pub struct DefaultGitRunner {
     timeout: Duration,
 }
 
+/// Floor applied to every configured timeout so a `git_timeout_secs = 0`
+/// misconfiguration cannot produce an instantly-expiring command timeout
+/// (spec-063 NEVER: `git_timeout_secs = 0` is disallowed).
+const MIN_TIMEOUT: Duration = Duration::from_secs(1);
+
 impl DefaultGitRunner {
     /// Creates a runner with the default 30-second command timeout.
     #[must_use]
     pub fn new() -> Self {
-        Self {
-            timeout: Duration::from_secs(30),
-        }
+        Self::with_timeout(Duration::from_secs(30))
     }
 
     /// Creates a runner with a custom command timeout.
+    ///
+    /// `timeout` is clamped to a minimum of one second — a zero (or
+    /// sub-second) timeout would make every `git` invocation fail
+    /// immediately, which is never the caller's intent.
     #[must_use]
     pub fn with_timeout(timeout: Duration) -> Self {
-        Self { timeout }
+        Self {
+            timeout: timeout.max(MIN_TIMEOUT),
+        }
+    }
+}
+
+impl Default for DefaultGitRunner {
+    fn default() -> Self {
+        Self::new()
     }
 }
 
@@ -223,3 +238,29 @@ impl GitRunner for FakeGitRunner {
         })
     }
 }
+
+#[cfg(test)]
+mod runner_tests {
+    use super::*;
+
+    /// Regression test for #5939: `git_timeout_secs = 0` (surfaced as
+    /// `Duration::ZERO`) must not produce a runner whose every `git`
+    /// invocation times out instantly.
+    #[test]
+    fn with_timeout_clamps_zero_to_one_second() {
+        let runner = DefaultGitRunner::with_timeout(Duration::ZERO);
+        assert_eq!(runner.timeout, Duration::from_secs(1));
+    }
+
+    #[test]
+    fn with_timeout_preserves_values_above_the_floor() {
+        let runner = DefaultGitRunner::with_timeout(Duration::from_mins(1));
+        assert_eq!(runner.timeout, Duration::from_mins(1));
+    }
+
+    #[test]
+    fn default_and_new_are_never_zero() {
+        assert_eq!(DefaultGitRunner::default().timeout, Duration::from_secs(30));
+        assert_eq!(DefaultGitRunner::new().timeout, Duration::from_secs(30));
+    }
+}

crates/zeph-worktree/src/handle.rs

@@ -3,6 +3,28 @@
 
 use std::{path::PathBuf, time::SystemTime};
 
+/// Sentinel used for [`WorktreeHandle::branch_name`] when a worktree discovered
+/// via [`WorktreeManager::reconcile`][crate::WorktreeManager::reconcile] is on a
+/// detached `HEAD` rather than a branch (`git worktree list --porcelain` emits a
+/// `detached` line instead of `branch refs/heads/<name>` for these entries).
+///
+/// The embedded space makes this an invalid git ref name: `git
+/// check-ref-format` rejects any ref component containing a space (see
+/// `git help check-ref-format` — disallowed characters include space, `~`,
+/// `^`, `:`, `?`, `*`, `[`, `\`). `reconcile()` only ever populates
+/// `branch_name` from a `branch refs/heads/<name>` porcelain line, and git
+/// itself refuses to create a ref containing a space in the first place — so
+/// no real branch, including one on a worktree foreign to zeph (i.e. not
+/// created via [`WorktreeManager::create`][crate::WorktreeManager::create],
+/// which further restricts the subagent-id component to
+/// `^[A-Za-z0-9._-]+$`), can ever equal this sentinel. An earlier version of
+/// this constant, `"(detached)"`, lacked this property: parentheses are
+/// valid in git ref names, so a real branch literally named `(detached)`
+/// would have been indistinguishable from a detached-HEAD worktree, causing
+/// [`WorktreeManager::remove`][crate::WorktreeManager::remove] to silently
+/// skip pruning it (#5936 review finding).
+pub const DETACHED_BRANCH_SENTINEL: &str = "(detached HEAD)";
+
 /// A live record of a git worktree that [`WorktreeManager`][crate::WorktreeManager]
 /// has created for a subagent.
 ///
@@ -14,6 +36,10 @@ pub struct WorktreeHandle {
     /// Absolute path on disk where the worktree was checked out.
     pub path: PathBuf,
     /// The git branch name created for this worktree.
+    ///
+    /// For worktrees discovered by [`WorktreeManager::reconcile`][crate::WorktreeManager::reconcile]
+    /// that are on a detached `HEAD`, this is [`DETACHED_BRANCH_SENTINEL`] rather
+    /// than an actual branch name.
     pub branch_name: String,
     /// The resolved base ref used to create the branch.
     ///

crates/zeph-worktree/src/lib.rs

@@ -50,7 +50,7 @@ pub mod sanitize;
 
 pub use error::WorktreeError;
 pub use git_runner::{DefaultGitRunner, GitRunner};
-pub use handle::WorktreeHandle;
+pub use handle::{DETACHED_BRANCH_SENTINEL, WorktreeHandle};
 pub use manager::{WorktreeManager, probe_capabilities};
 
 /// A [`WorktreeManager`] using the production [`DefaultGitRunner`].