zeph_worktree/lib.rs
1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Per-subagent git worktree lifecycle management for Zeph.
5//!
6//! This crate implements the `zeph-worktree` subsystem described in
7//! `specs/063-worktree-subsystem/spec.md`. It provides:
8//!
9//! - [`WorktreeManager`] — creates, removes, lists, and reconciles git worktrees
10//! - [`WorktreeHandle`] — a live record of one managed worktree
11//! - [`StaleWorktree`] — a worktree discovered by `reconcile` outside session state,
12//! annotated with git's own `prunable` verdict
13//! - [`WorktreeError`] — all errors this crate can produce
14//! - [`GitRunner`] / [`DefaultGitRunner`]
15//! — the git invocation abstraction and its production implementation
16//! - [`manager::probe_capabilities`] — bootstrap git availability probe
17//!
18//! ## Dependency direction
19//!
20//! ```text
21//! zeph-subagent → zeph-worktree → (zeph-config, tokio, thiserror, tracing)
22//! ```
23//!
24//! This crate MUST NOT depend on `zeph-core`, `zeph-subagent`, or
25//! `zeph-channels`.
26//!
27//! ## Example
28//!
29//! ```no_run
30//! use std::path::PathBuf;
31//! use zeph_config::WorktreeConfig;
32//! use zeph_worktree::{DefaultWorktreeManager, git_runner::DefaultGitRunner, manager::probe_capabilities};
33//!
34//! # async fn example() -> Result<(), zeph_worktree::WorktreeError> {
35//! let repo = PathBuf::from("/path/to/repo");
36//! let runner = DefaultGitRunner::new();
37//! probe_capabilities(&runner, &repo).await?;
38//!
39//! let mgr = DefaultWorktreeManager::new(repo, WorktreeConfig::default(), DefaultGitRunner::new()).await?;
40//! let handle = mgr.create("agent-42").await?;
41//! println!("Worktree at {:?}", handle.path);
42//! mgr.remove(&handle, false).await?;
43//! # Ok(())
44//! # }
45//! ```
46
47pub mod error;
48pub mod git_runner;
49pub mod handle;
50pub mod manager;
51pub mod sanitize;
52pub mod usage;
53
54pub use error::WorktreeError;
55pub use git_runner::{DefaultGitRunner, GitRunner};
56pub use handle::{BARE_WORKTREE_SENTINEL, DETACHED_BRANCH_SENTINEL, StaleWorktree, WorktreeHandle};
57pub use manager::{CleanOutcome, WorktreeManager, format_clean_summary, probe_capabilities};
58pub use usage::{QuotaStatus, WorktreeDiskUsage, format_usage_summary};
59
60/// A [`WorktreeManager`] using the production [`DefaultGitRunner`].
61///
62/// This is the type that `SubAgentManager` stores as
63/// `Option<Arc<DefaultWorktreeManager>>`.
64pub type DefaultWorktreeManager = WorktreeManager<DefaultGitRunner>;