/**
 * Git Worktree — Create/remove/list worktrees for Repo Mesh node cloning
 *
 * Used by the `clone_mesh_node` daemon command to create isolated
 * worktree-based nodes for parallel branch work within a mesh.
 *
 * Worktrees are placed outside the source repo to avoid .gitignore
 * pollution and submodule conflicts:
 *   <repoParent>/.adhdev-worktrees/<meshName>/<branch>/
 */
export interface WorktreeCreateOptions {
    /** Absolute path to the source repo's git root */
    repoRoot: string;
    /** Branch name for the new worktree */
    branch: string;
    /** Starting point for the branch (default: HEAD) */
    baseBranch?: string;
    /** Mesh name, used for organizing worktree directories */
    meshName: string;
    /** Override the auto-resolved target directory */
    targetDir?: string;
    /**
     * Remote to fetch+compare the base branch against before branching.
     * Default: 'origin'.
     */
    remote?: string;
    /**
     * When true (default) and `baseBranch` is given, fetch the base branch from
     * `remote` and, if the local base branch is strictly behind the remote
     * (no divergence), branch the worktree from the remote-tracking ref instead
     * of the stale local ref. The decision is always surfaced via `baseSync`.
     * Set false to preserve the legacy "branch from local ref, never fetch"
     * behavior.
     */
    syncBaseFromRemote?: boolean;
}
/**
 * How the worktree's start point was resolved relative to the remote base.
 * Surfaced so the coordinator can detect a stale base node before dispatching
 * work onto a worktree built on a behind/diverged base.
 */
export interface WorktreeBaseSync {
    /** The base branch name requested (e.g. 'main'). */
    branch: string;
    /** The remote compared against (e.g. 'origin'). */
    remote: string;
    /** The actual ref/commit-ish used as the worktree branch start point. */
    startRef: string;
    /** Whether `git fetch <remote> <branch>` succeeded. */
    fetched: boolean;
    /** Local base-branch SHA before clone, if the local ref exists. */
    localSha?: string;
    /** Remote-tracking base-branch SHA after fetch, if it exists. */
    remoteSha?: string;
    /** Commits the local base ref is behind the remote (0 when up-to-date/ahead). */
    behindBy: number;
    /** Commits the local base ref is ahead of the remote. */
    aheadBy: number;
    /** What was done with the base ref. */
    action: 'up_to_date' | 'local_behind_used_remote' | 'local_ahead_used_local' | 'diverged_used_local' | 'no_remote_ref_used_local' | 'no_local_ref_used_remote';
    /** Human-readable warning when the base was stale/diverged. */
    warning?: string;
}
export interface WorktreeCreateResult {
    success: true;
    worktreePath: string;
    branch: string;
    /** Present when `baseBranch` was given and base sync resolution ran. */
    baseSync?: WorktreeBaseSync;
}
export interface WorktreeEntry {
    path: string;
    head: string;
    branch: string | null;
    bare: boolean;
}
export interface WorktreeRemoveOptions {
    /** Refuse to remove a worktree with uncommitted or untracked changes. */
    requireClean?: boolean;
    /**
     * If normal removal fails with Git's submodule-worktree guard, retry with
     * `git worktree remove --force`. Callers must perform their own
     * higher-level managed-path/convergence checks before enabling this.
     */
    allowSubmoduleForceFallback?: boolean;
}
export interface WorktreeRemoveResult {
    success: true;
    removedPath: string;
    fallback?: 'git_worktree_remove_force_submodule';
    forced?: boolean;
    reason?: 'working_trees_containing_submodules';
}
/**
 * Resolve the target directory for a new worktree.
 * Places worktrees at: <repoParent>/.adhdev-worktrees/<meshName>/<branch>/
 */
export declare function resolveWorktreePath(repoRoot: string, meshName: string, branch: string): string;
/**
 * Create a new git worktree with a fresh branch.
 *
 * Runs: git worktree add <targetDir> -b <branch> [startRef]
 *
 * When `baseBranch` is given and `syncBaseFromRemote` is not disabled, the
 * start point is resolved against the remote first (see
 * resolveWorktreeBaseStartPoint) so a stale local base does not produce a stale
 * worktree. The resolution is returned as `baseSync`.
 */
export declare function createWorktree(opts: WorktreeCreateOptions): Promise<WorktreeCreateResult>;
/**
 * Remove a git worktree and clean up the directory.
 *
 * Runs: git worktree remove <worktreePath>
 */
export declare function removeWorktree(repoRoot: string, worktreePath: string, opts?: WorktreeRemoveOptions): Promise<WorktreeRemoveResult>;
/**
 * List all worktrees for a repository.
 *
 * Runs: git worktree list --porcelain
 */
export declare function listWorktrees(repoRoot: string): Promise<WorktreeEntry[]>;
/**
 * Parse `git worktree list --porcelain` output into structured entries.
 */
export declare function parseWorktreeListOutput(output: string): WorktreeEntry[];
export interface BranchRefDeleteResult {
    /** True if the branch ref no longer exists after this call. */
    deleted: boolean;
    /** Why it was (not) deleted, for surfacing in the cleanup result. */
    reason: string;
    /** True when a forced delete (`-D`) was needed (e.g. squash/patch-equivalent merge). */
    forced?: boolean;
}
/**
 * Delete a local branch ref after its worktree was removed.
 *
 * SAFETY: this is only meant to be called once the caller has independently
 * verified that the branch is fully merged / its content is contained in the
 * default ref (no work loss). It first tries the safe `git branch -d`, which
 * refuses to delete a branch git itself does not consider merged. If
 * `safeDeleteOnly` is false (the caller proved containment by patch-equivalence,
 * which `-d` cannot see), it falls back to `git branch -D`. When the branch is
 * already gone, this reports `deleted: true` idempotently.
 */
export declare function deleteBranchRef(repoRoot: string, branch: string, opts?: {
    safeDeleteOnly?: boolean;
}): Promise<BranchRefDeleteResult>;
