/**
 * Worktree Manager
 *
 * This module provides git worktree management for the orchestration system.
 * Each worker agent gets a dedicated git worktree for true parallel development.
 *
 * Key features:
 * - Verify git repo exists before operations
 * - Create isolated worktrees for workers
 * - Branch naming: agent/{worker-name}/{task-id}-{slug}
 * - Worktree path: .stoneforge/.worktrees/{worker-name}-{task-slug}/
 * - Clean up worktrees after merge
 *
 * @module
 */
import type { ElementId, Timestamp } from '@stoneforge/core';
/**
 * Lifecycle state of a worktree
 */
export type WorktreeState = 'creating' | 'active' | 'suspended' | 'merging' | 'cleaning' | 'archived';
/**
 * All valid worktree states
 */
export declare const WorktreeStates: readonly ["creating", "active", "suspended", "merging", "cleaning", "archived"];
/**
 * Valid state transitions for worktrees
 */
export declare const WorktreeStateTransitions: Record<WorktreeState, WorktreeState[]>;
/**
 * Information about a git worktree
 */
export interface WorktreeInfo {
    /** Full path to the worktree directory */
    readonly path: string;
    /** Relative path from workspace root (e.g., ".stoneforge/.worktrees/alice-feature") */
    readonly relativePath: string;
    /** Branch checked out in this worktree */
    readonly branch: string;
    /** HEAD commit hash */
    readonly head: string;
    /** Whether this is the main worktree */
    readonly isMain: boolean;
    /** Worktree lifecycle state */
    state: WorktreeState;
    /** Agent name associated with this worktree */
    readonly agentName?: string;
    /** Task ID associated with this worktree */
    readonly taskId?: string;
    /** When the worktree was created */
    readonly createdAt?: Timestamp;
}
/**
 * Options for creating a worktree
 */
export interface CreateWorktreeOptions {
    /** Agent name for path generation */
    readonly agentName: string;
    /** Task ID for branch naming */
    readonly taskId: ElementId;
    /** Task title for slug generation (optional) */
    readonly taskTitle?: string;
    /** Custom branch name (overrides auto-generated) */
    readonly customBranch?: string;
    /** Custom worktree path (overrides auto-generated) */
    readonly customPath?: string;
    /** Base branch to create from (default: current branch) */
    readonly baseBranch?: string;
    /** Track remote branch (default: true) */
    readonly trackRemote?: boolean;
    /** Install dependencies after worktree creation (default: false) */
    readonly installDependencies?: boolean;
}
/**
 * Options for removing a worktree
 */
export interface RemoveWorktreeOptions {
    /** Force removal even if there are uncommitted changes */
    readonly force?: boolean;
    /** Also delete the branch (local) */
    readonly deleteBranch?: boolean;
    /** Force delete branch even if not fully merged */
    readonly forceBranchDelete?: boolean;
    /** Also delete the remote branch (requires deleteBranch to be true) */
    readonly deleteRemoteBranch?: boolean;
}
/**
 * Result of creating a worktree
 */
export interface CreateWorktreeResult {
    /** The created worktree info */
    readonly worktree: WorktreeInfo;
    /** The branch name created/checked out */
    readonly branch: string;
    /** Full path to the worktree */
    readonly path: string;
    /** Whether a new branch was created */
    readonly branchCreated: boolean;
}
/**
 * Configuration for the WorktreeManager
 */
export interface WorktreeManagerConfig {
    /** Workspace root directory (must be a git repo) */
    readonly workspaceRoot: string;
    /** Directory for worktrees relative to workspace root (default: ".stoneforge/.worktrees") */
    readonly worktreeDir?: string;
    /** Default base branch (default: auto-detect from git) */
    readonly defaultBaseBranch?: string;
}
/**
 * Error thrown when git repository is not found
 */
export declare class GitRepositoryNotFoundError extends Error {
    constructor(path: string);
}
/**
 * Error thrown when a worktree operation fails
 */
export declare class WorktreeError extends Error {
    readonly code: string;
    readonly details?: string;
    constructor(message: string, code: string, details?: string);
}
/**
 * WorktreeManager interface for git worktree operations.
 *
 * The manager provides methods for:
 * - Initializing workspace and verifying git repo
 * - Creating worktrees for workers
 * - Removing worktrees after merge
 * - Listing and querying worktrees
 */
export interface WorktreeManager {
    /**
     * Initializes the workspace, verifying git repo exists.
     *
     * @throws GitRepositoryNotFoundError if no git repo found
     */
    initWorkspace(): Promise<void>;
    /**
     * Checks if the workspace has been initialized.
     */
    isInitialized(): boolean;
    /**
     * Gets the workspace root directory.
     */
    getWorkspaceRoot(): string;
    /**
     * Creates a new worktree for a worker.
     *
     * @param options - Worktree creation options
     * @returns The created worktree result
     */
    createWorktree(options: CreateWorktreeOptions): Promise<CreateWorktreeResult>;
    /**
     * Creates a read-only worktree detached on the default branch.
     * Used for triage sessions that should not create new branches.
     *
     * @param options - Agent name and purpose for path generation
     * @returns The created worktree result
     */
    createReadOnlyWorktree(options: {
        agentName: string;
        purpose: string;
    }): Promise<CreateWorktreeResult>;
    /**
     * Removes a worktree.
     *
     * @param worktreePath - Path to the worktree (relative or absolute)
     * @param options - Removal options
     */
    removeWorktree(worktreePath: string, options?: RemoveWorktreeOptions): Promise<void>;
    /**
     * Suspends a worktree (marks it inactive but preserves it).
     *
     * @param worktreePath - Path to the worktree
     */
    suspendWorktree(worktreePath: string): Promise<void>;
    /**
     * Resumes a suspended worktree.
     *
     * @param worktreePath - Path to the worktree
     */
    resumeWorktree(worktreePath: string): Promise<void>;
    /**
     * Lists all worktrees in the workspace.
     *
     * @param includeMain - Whether to include the main worktree (default: false)
     */
    listWorktrees(includeMain?: boolean): Promise<WorktreeInfo[]>;
    /**
     * Gets information about a specific worktree.
     *
     * @param worktreePath - Path to the worktree (relative or absolute)
     */
    getWorktree(worktreePath: string): Promise<WorktreeInfo | undefined>;
    /**
     * Gets the worktree path for an agent/task combination.
     *
     * @param agentName - The agent's name
     * @param taskTitle - The task title (optional, used for slug)
     */
    getWorktreePath(agentName: string, taskTitle?: string): string;
    /**
     * Gets worktrees for a specific agent.
     *
     * @param agentName - The agent's name
     */
    getWorktreesForAgent(agentName: string): Promise<WorktreeInfo[]>;
    /**
     * Checks if a worktree exists at the given path.
     *
     * @param worktreePath - Path to check
     */
    worktreeExists(worktreePath: string): Promise<boolean>;
    /**
     * Gets the current branch of the main worktree.
     */
    getCurrentBranch(): Promise<string>;
    /**
     * Gets the default base branch (main, master, etc).
     */
    getDefaultBranch(): Promise<string>;
    /**
     * Checks if a branch exists.
     *
     * @param branchName - The branch name to check
     */
    branchExists(branchName: string): Promise<boolean>;
}
/**
 * Implementation of the WorktreeManager.
 */
export declare class WorktreeManagerImpl implements WorktreeManager {
    private readonly config;
    private initialized;
    private defaultBranch;
    private worktreeStates;
    private realWorkspaceRoot;
    constructor(config: WorktreeManagerConfig);
    initWorkspace(): Promise<void>;
    isInitialized(): boolean;
    getWorkspaceRoot(): string;
    createWorktree(options: CreateWorktreeOptions): Promise<CreateWorktreeResult>;
    /**
     * Create a read-only (detached HEAD) worktree for triage sessions.
     * Uses `git worktree add --detach` so no new branch is created.
     */
    createReadOnlyWorktree(options: {
        agentName: string;
        purpose: string;
    }): Promise<CreateWorktreeResult>;
    removeWorktree(worktreePath: string, options?: RemoveWorktreeOptions): Promise<void>;
    suspendWorktree(worktreePath: string): Promise<void>;
    resumeWorktree(worktreePath: string): Promise<void>;
    listWorktrees(includeMain?: boolean): Promise<WorktreeInfo[]>;
    getWorktree(worktreePath: string): Promise<WorktreeInfo | undefined>;
    getWorktreePath(agentName: string, taskTitle?: string): string;
    getWorktreesForAgent(agentName: string): Promise<WorktreeInfo[]>;
    worktreeExists(worktreePath: string): Promise<boolean>;
    getCurrentBranch(): Promise<string>;
    getDefaultBranch(): Promise<string>;
    branchExists(branchName: string): Promise<boolean>;
    private ensureInitialized;
    private execGit;
    /**
     * Installs dependencies in a worktree directory.
     * Detects the package manager (pnpm, npm, yarn, bun) and runs install.
     * Uses a longer timeout since dependency installation can take a while.
     *
     * Tries a strict install first (--frozen-lockfile / ci) and falls back to
     * a plain install when the lockfile is out of sync with package.json
     * (common when the base branch has uncommitted lockfile changes).
     */
    private installDependencies;
    private resolvePath;
    private getRelativePath;
    private parseWorktreeList;
    private finalizeWorktreeInfo;
    private detectDefaultBranch;
    private ensureGitignore;
}
/**
 * Creates a WorktreeManager instance
 */
export declare function createWorktreeManager(config: WorktreeManagerConfig): WorktreeManager;
/**
 * Type guard to check if a value is a valid WorktreeState
 */
export declare function isWorktreeState(value: unknown): value is WorktreeState;
/**
 * Checks if a state transition is valid
 */
export declare function isValidStateTransition(from: WorktreeState, to: WorktreeState): boolean;
/**
 * Gets human-readable description of a worktree state
 */
export declare function getWorktreeStateDescription(state: WorktreeState): string;
//# sourceMappingURL=worktree-manager.d.ts.map