zeph-worktree

Git worktree lifecycle management for Zeph subagents.

Overview

zeph-worktree creates, removes, lists, and reconciles per-subagent git worktrees. Each background subagent that opts into filesystem isolation gets a dedicated worktree cloned from the host repository, preventing concurrent agents from clobbering each other's working trees.

The crate is intentionally narrow in scope — it wraps git worktree subprocess calls with full path sanitization, capability probing, and a configurable timeout. It has no dependency on zeph-core, zeph-subagent, or zeph-channels.

Key types

Usage

[dependencies]
zeph-worktree = { path = "crates/zeph-worktree" }

use std::path::PathBuf;
use zeph_config::WorktreeConfig;
use zeph_worktree::{DefaultWorktreeManager, git_runner::DefaultGitRunner, manager::probe_capabilities};

#[tokio::main]
async fn main() -> Result<(), zeph_worktree::WorktreeError> {
    let repo = PathBuf::from("/path/to/repo");
    let runner = DefaultGitRunner::new();

    // Verify git ≥ 2.5 is available and the path is a repository.
    probe_capabilities(&runner, &repo).await?;

    let mgr = DefaultWorktreeManager::new(repo, WorktreeConfig::default(), runner).await?;

    // Create a worktree for a subagent.
    let handle = mgr.create("agent-42").await?;
    println!("Worktree at {:?}", handle.path);

    // List all tracked worktrees.
    let all = mgr.list();
    println!("{} active worktrees", all.len());

    // Remove the worktree. The second argument is `prune_branch`, not `force`:
    // the underlying `git worktree remove` is always issued with `--force`.
    mgr.remove(&handle, false).await?;

    Ok(())
}

[!IMPORTANT] Call probe_capabilities once at bootstrap. It checks that git ≥ 2.5 is in PATH and that the target path is a git repository. A missing git binary is caught here, not at first spawn.

Configuration

WorktreeManager is driven by WorktreeConfig from zeph-config:

[worktree]
enabled = true
bg_isolation = "worktree"   # "none" | "worktree"
base_ref = "head"           # "head" | "fresh"
default_branch = "main"     # remote branch used when base_ref = "fresh"; "" auto-detects origin/HEAD
root = ".claude/worktrees"  # worktree root, relative to the repository root
branch_prefix = "agent/"    # full branch name is "{branch_prefix}{subagent_id}"
prune_branch_on_remove = false
git_timeout_secs = 30       # clamped to max(1, value)
cleanup_on_completion = true
# max_worktrees = 20        # optional admission cap; None = unlimited
# disk_quota_mb = 5000      # optional soft disk-usage threshold; None = disabled
auto_reconcile_secs = 0     # periodic reconcile-and-quota sweep; 0 disables it
reconcile_on_startup = true

Invariants

• Path sanitization rejects absolute paths, .. components, and names starting with - before any git call.
• base_ref = "fresh" never silently falls back to HEAD on fetch failure — it returns an error.
• git_timeout_secs = 0 is clamped to 1 by DefaultGitRunner.
• create() admission (quota check + worktree add) closes the check-then-act race under concurrent callers within the same process.
• Lowering max_worktrees below the current worktree count does not evict existing worktrees; it only blocks new admissions until zeph worktree clean runs or the limit is raised.

License

Licensed under either of MIT or Apache License, Version 2.0 at your option.