Crate zeph_worktree 

Per-subagent git worktree lifecycle management for Zeph.

This crate implements the zeph-worktree subsystem described in specs/063-worktree-subsystem/spec.md. It provides:

• WorktreeManager — creates, removes, lists, and reconciles git worktrees
• WorktreeHandle — a live record of one managed worktree
• StaleWorktree — a worktree discovered by reconcile outside session state, annotated with git’s own prunable verdict
• WorktreeError — all errors this crate can produce
• GitRunner / DefaultGitRunner — the git invocation abstraction and its production implementation
• manager::probe_capabilities — bootstrap git availability probe

Dependency direction

zeph-subagent → zeph-worktree → (zeph-config, tokio, thiserror, tracing)

This crate MUST NOT depend on zeph-core, zeph-subagent, or zeph-channels.

Example

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

let repo = PathBuf::from("/path/to/repo");
let runner = DefaultGitRunner::new();
probe_capabilities(&runner, &repo).await?;

let mgr = DefaultWorktreeManager::new(repo, WorktreeConfig::default(), DefaultGitRunner::new()).await?;
let handle = mgr.create("agent-42").await?;
println!("Worktree at {:?}", handle.path);
mgr.remove(&handle, false).await?;

Re-exports

pub use error::WorktreeError;

pub use git_runner::DefaultGitRunner;

pub use git_runner::GitRunner;

pub use handle::BARE_WORKTREE_SENTINEL;

pub use handle::DETACHED_BRANCH_SENTINEL;

pub use handle::StaleWorktree;

pub use handle::WorktreeHandle;

pub use manager::CleanOutcome;

pub use manager::WorktreeManager;

pub use manager::format_clean_summary;

pub use manager::probe_capabilities;

pub use usage::QuotaStatus;

pub use usage::WorktreeDiskUsage;

pub use usage::format_usage_summary;

Modules

error

Error types for the zeph-worktree crate.

git_runner

GitRunner trait and DefaultGitRunner production implementation.

handle

WorktreeHandle — a live record of a managed git worktree.

manager

WorktreeManager — lifecycle management for per-subagent git worktrees.

sanitize

Input sanitisation for branch components and worktree root paths.

usage

Disk-usage accounting and quota-status types for crate::WorktreeManager.

Type Aliases

DefaultWorktreeManager

A WorktreeManager using the production DefaultGitRunner.