Struct Manager 

pub struct Manager { /* private fields */ }

Core worktree lifecycle manager. Entry point for all iso-code operations.

Manager is Send but not Sync — the circuit-breaker counter uses Cell for zero-overhead single-threaded access. To share a Manager across threads, wrap it in Arc<Mutex<Manager>>.

Implementations

impl Manager

pub fn new( repo_root: impl AsRef<Path>, config: Config, ) -> Result<Self, WorktreeError>

Construct a Manager for the given repository root.

Construction performs, in order:

1. Validate git --version is at least 2.20.
2. Canonicalize repo_root and detect GitCapabilities.
3. Ensure .git/iso-code/ exists and initialize state.json on first use.
4. Scan for orphaned worktrees (non-fatal; emits warnings only).
5. Sweep expired port leases.

pub fn with_adapter( repo_root: impl AsRef<Path>, config: Config, adapter: Option<Box<dyn EcosystemAdapter>>, ) -> Result<Self, WorktreeError>

Construct a Manager with an explicit EcosystemAdapter.

The adapter’s setup() method will be called after create() and attach() when the corresponding options have setup = true.

pub fn git_capabilities(&self) -> &GitCapabilities

Return the detected git capabilities.

pub fn repo_root(&self) -> &Path

Return the repository root path.

pub fn config(&self) -> &Config

Return the current configuration.

pub fn list(&self) -> Result<Vec<WorktreeHandle>, WorktreeError>

List all worktrees, reconciling git porcelain output with state.json.

Reconciliation runs on every call:

1. Run git worktree list --porcelain.
2. Enrich each handle with state.json metadata (created_at, session_uuid, …).
3. Move state entries missing from git output to stale_worktrees.
4. Purge stale entries whose expires_at has passed.
5. Sweep port leases: drop dead holders and expired leases.

pub fn create( &self, branch: impl Into<String>, path: impl AsRef<Path>, options: CreateOptions, ) -> Result<(WorktreeHandle, CopyOutcome), WorktreeError>

Create a new managed worktree.

The sequence is ordered and must not be reshuffled:

1. Run every pre-create guard.
2. Write a Creating entry to state.json.
3. Run git worktree add.
4. Post-create git-crypt verification.
5. Run EcosystemAdapter::setup if the caller requested it.
6. Transition the entry to Active (or Locked if options.lock).

If any step after git worktree add fails, the worktree is force-removed with git worktree remove --force and the Creating entry is cleared before the error propagates.

pub fn attach( &self, path: impl AsRef<Path>, options: AttachOptions, ) -> Result<WorktreeHandle, WorktreeError>

Attach an existing worktree (already in git’s registry) under iso-code management.

Never calls git worktree add — the worktree must already appear in git worktree list --porcelain. If the path is already tracked in active_worktrees the existing handle is returned (idempotent). If a matching entry exists in stale_worktrees, its port and session_uuid are recovered.

pub fn delete( &self, handle: &WorktreeHandle, options: DeleteOptions, ) -> Result<(), WorktreeError>

Delete a managed worktree.

Ordered pre-flight checks (each may abort the delete):

1. Refuse to delete the caller’s current working directory.
2. Reject a dirty working tree unless options.force_dirty.
3. Reject unmerged commits unless options.force.
4. Reject worktrees held by git worktree lock.

Once the checks pass, the entry transitions to Deleting, git worktree remove runs, and the entry is finally cleared from state.json.

pub fn gc(&self, options: GcOptions) -> Result<GcReport, WorktreeError>

Garbage collect orphaned and stale worktrees.

The default GcOptions is dry-run. Locked worktrees are always preserved, regardless of options.force. Evicted entries are moved to stale_worktrees so their metadata can be recovered — gc() never silently drops state.

pub fn touch(&self, branch: &str) -> Result<(), WorktreeError>

Mark branch as recently active by bumping its last_activity timestamp in state.json. Callers wrap user-visible actions (shell into the worktree, run a build, etc.) with this so gc() can tell “idle since creation” apart from “recently used.” Returns InvalidStateTransition-style StateCorrupted if the branch isn’t tracked in active_worktrees.

pub fn port_lease(&self, branch: &str) -> Option<PortLease>

Return the active port lease for a branch, if any.

pub fn allocate_port( &self, branch: &str, session_uuid: &str, ) -> Result<u16, WorktreeError>

Allocate a port lease for a branch without creating a worktree.

pub fn disk_usage(&self, path: &Path) -> u64

Return the on-disk byte size of a worktree tree, skipping the .git/ subtree and deduplicating hardlinks on Unix.

pub fn release_port(&self, branch: &str) -> Result<(), WorktreeError>

Release a port lease explicitly.

pub fn renew_port_lease(&self, branch: &str) -> Result<(), WorktreeError>

Extend an active port lease’s TTL by another 8 hours from now.

Callers running a long-lived dev server invoke this roughly every TTL/3 to keep the lease from expiring mid-session. Returns StateCorrupted if the branch has no active lease — expired leases must be re-allocated via Manager::allocate_port rather than renewed, since their port may have been reassigned.