/**
 * CLEO orphan cleanup utilities — worktrees and temp directories.
 *
 * Provides two independent cleanup operations:
 *
 * 1. `pruneOrphanWorktrees` — removes worktree directories under
 *    `~/.local/share/cleo/worktrees/<projectHash>/` whose task IDs
 *    are not in the active-task set.
 *
 * 2. `pruneOrphanTempDirs` — removes CLEO-generated temp directories
 *    under `os.tmpdir()` that match any known CLEO prefix and are
 *    older than a configurable age threshold (default: 2 hours).
 *
 * Both operations are safe by design:
 * - Only remove paths that match CLEO-specific patterns.
 * - Never throw — failures are returned in the result's `errors` array.
 * - `dryRun: true` returns what would be removed without deleting.
 *
 * Consumed by:
 * - `cleo gc --worktrees` / `cleo gc --temp` (Group D)
 * - `cleo doctor` orphan audit (Group C)
 *
 * @task T9043
 */
/**
 * All CLEO-generated temp directory prefixes that may accumulate in os.tmpdir().
 *
 * Compiled from a monorepo-wide audit of `mkdtemp`/`mkdtempSync` usages.
 *
 * @task T9043
 */
export declare const CLEO_TEMP_PREFIXES: readonly string[];
/**
 * Default maximum age (in milliseconds) for orphaned CLEO temp directories.
 *
 * Directories older than this threshold are eligible for pruning.
 * Default: 2 hours. Suitable for both CI and interactive dev sessions.
 *
 * @task T9043
 */
export declare const DEFAULT_TEMP_MAX_AGE_MS: number;
/**
 * Result of an orphan cleanup operation.
 *
 * @task T9043
 */
export interface CleanupResult {
    /** Number of entries removed (or that would be removed in dry-run). */
    removed: number;
    /** Absolute paths that were removed (or would be removed). */
    removedPaths: string[];
    /** Number of worktrees quarantined (dirty/unpushed — preserved, not deleted). */
    quarantined: number;
    /** Absolute paths that were quarantined (tar archives placed in quarantine dir). */
    quarantinedPaths: string[];
    /** Entries that were skipped (dry-run or preserved). */
    skipped: number;
    /** Errors encountered during removal (non-fatal). */
    errors: Array<{
        path: string;
        reason: string;
    }>;
    /** Whether this was a dry run. */
    dryRun: boolean;
    /**
     * True when pruning was skipped entirely because the preserve set was empty
     * while worktrees exist (fail-closed guard, T11996).
     */
    skippedFailClosed?: boolean;
}
/**
 * Options for `pruneOrphanWorktrees`.
 *
 * @task T9043
 */
export interface PruneOrphanWorktreesOptions {
    /**
     * Root directory containing per-project-hash worktree subdirs.
     * Typically `~/.local/share/cleo/worktrees/`.
     */
    worktreesRoot: string;
    /**
     * Project hash to scope to. When provided, only
     * `<worktreesRoot>/<projectHash>/` is scanned.
     * When omitted, all project hashes under `worktreesRoot` are scanned.
     */
    projectHash?: string;
    /**
     * Task IDs whose worktrees must be preserved.
     *
     * Any worktree directory whose name is NOT in this set will be removed.
     * Pass an empty set to remove all non-active worktrees.
     */
    activeTaskIds: Set<string>;
    /**
     * When true, report removals without deleting anything.
     *
     * @default false
     */
    dryRun?: boolean;
}
/**
 * Options for `pruneOrphanTempDirs`.
 *
 * @task T9043
 */
export interface PruneOrphanTempDirsOptions {
    /**
     * Maximum age of a CLEO temp directory before it is eligible for removal.
     *
     * @default DEFAULT_TEMP_MAX_AGE_MS (2 hours)
     */
    maxAgeMs?: number;
    /**
     * Override for the system temp directory (for testing).
     *
     * @default os.tmpdir()
     */
    tempDir?: string;
    /**
     * When true, report removals without deleting anything.
     *
     * @default false
     */
    dryRun?: boolean;
}
/**
 * An audited orphan entry (used by cleo doctor checks).
 *
 * @task T9043
 */
export interface OrphanEntry {
    /** Absolute path to the orphaned directory. */
    path: string;
    /** Age of the directory in milliseconds (based on mtime). */
    ageMs: number;
    /** Human-readable age (e.g. "3h 15m"). */
    ageLabel: string;
}
/**
 * Prune orphaned agent worktree directories.
 *
 * Scans `worktreesRoot` (or `worktreesRoot/<projectHash>`) for directories
 * whose names are NOT in `activeTaskIds` and removes them.
 *
 * Safety invariants (T11996):
 * - Fail-closed: if `activeTaskIds` is empty AND worktrees exist, skip pruning
 *   entirely and return `skippedFailClosed: true`. This prevents mass-deletion
 *   when the task store is unavailable or freshly initialised.
 * - Dirty guard: worktrees with uncommitted changes are quarantined (packed
 *   into `.tar.gz` in `<worktreesRoot>/../quarantine/worktrees/`) instead of
 *   deleted. The original directory is left on disk.
 * - Unpushed guard: worktrees whose branch has commits not reachable from any
 *   remote ref are quarantined, not deleted.
 * - A worktree that is both dirty AND has unpushed commits is quarantined once.
 *
 * @param options - See `PruneOrphanWorktreesOptions`.
 * @returns Cleanup result.
 *
 * @task T9043
 * @task T11996
 */
export declare function pruneOrphanWorktrees(options: PruneOrphanWorktreesOptions): CleanupResult;
/**
 * Prune orphaned CLEO-generated temp directories.
 *
 * Scans `os.tmpdir()` for directories whose names start with any prefix in
 * `CLEO_TEMP_PREFIXES` and whose mtime is older than `maxAgeMs`. This is
 * safe because all CLEO temp dirs are transient; any that survive longer
 * than the threshold were left by crashed or aborted processes.
 *
 * @param options - See `PruneOrphanTempDirsOptions`.
 * @returns Cleanup result.
 *
 * @task T9043
 */
export declare function pruneOrphanTempDirs(options?: PruneOrphanTempDirsOptions): CleanupResult;
/**
 * List orphaned CLEO-generated temp directories without removing them.
 *
 * Used by `auditOrphanTempDirs` doctor check. Returns entries whose age
 * exceeds the threshold, sorted oldest-first.
 *
 * @param maxAgeMs - Age threshold in milliseconds (default: 2 hours).
 * @param tempDir - Override for os.tmpdir() (testing).
 * @returns Array of orphan entries sorted oldest-first.
 *
 * @task T9043
 */
export declare function listOrphanTempDirs(maxAgeMs?: number, tempDir?: string): OrphanEntry[];
/**
 * List orphaned worktree directories without removing them.
 *
 * Used by `auditOrphanWorktrees` doctor check. Returns all task-directory
 * entries not in `activeTaskIds`, sorted by path.
 *
 * @param worktreesRoot - Root of the CLEO worktrees hierarchy.
 * @param activeTaskIds - Set of currently active task IDs to exclude.
 * @param projectHash - Scope to a single project hash (optional).
 * @returns Array of orphan entries sorted by path.
 *
 * @task T9043
 */
export declare function listOrphanWorktrees(worktreesRoot: string, activeTaskIds: Set<string>, projectHash?: string): OrphanEntry[];
//# sourceMappingURL=cleanup.d.ts.map