import type { ChildResult } from "../core/types.js";
/** Named timeout bound for every git invocation (crash safety). */
export declare const WORKTREE_GIT_TIMEOUT_MS = 30000;
/** Auto-commit description bound: truncated to 200 chars (benchmark bound). */
export declare const WORKTREE_DESC_MAX_CHARS = 200;
/** Branch prefix for preserved agent work (benchmark: pi-agent-<agentId>). */
export declare const WORKTREE_BRANCH_PREFIX = "pi-agent-";
/** Retries with fresh timestamp suffixes when the branch name is taken. */
export declare const WORKTREE_BRANCH_CONFLICT_ATTEMPTS = 3;
/** Forced identity for the machine-authored auto-commit (hermetic repos). */
export declare const WORKTREE_COMMIT_IDENTITY: {
    readonly name: "pi-subagents";
    readonly email: "pi-subagents@localhost";
};
/** Options for `createWorktree`. */
export interface WorktreeOptions {
    /** Description used in the auto-commit message (truncated to 200 chars). */
    description?: string;
    /** Base directory for the worktree (default: os tmpdir, NEVER inside the repo). */
    baseDir?: string;
    /** Named timeout bound for git invocations (default WORKTREE_GIT_TIMEOUT_MS). */
    gitTimeoutMs?: number;
}
/** A created (disposable) worktree awaiting a child run + cleanup. */
export interface WorktreeCreation {
    /** Absolute repo root the worktree was created from. */
    repoRoot: string;
    /** Absolute worktree path (the child's cwd). */
    worktreePath: string;
    /** Branch cleanup creates when changes exist: pi-agent-<sanitized runId>. */
    branch: string;
    /** HEAD sha of the repo at creation time (detached base of the worktree). */
    baseSha: string;
    /** Sanitized run id the branch name derives from. */
    runId: string;
    /** Carried description for the auto-commit message. */
    description?: string;
    /** Named timeout bound used by cleanup git invocations. */
    gitTimeoutMs: number;
}
/** Post-cleanup outcome attached to the enriched child result. */
export interface WorktreeRunOutcome {
    worktreePath: string;
    baseSha: string;
    /** Created branch (present only when changes/commits were preserved). */
    branch?: string;
    /** True when the worktree had changes or a moved HEAD at cleanup. */
    hasChanges: boolean;
    /** True when CLEANUP itself created the auto-commit (dirty tree). */
    committed: boolean;
    /** HEAD sha the branch points at (cleanup commit or the child's commit). */
    commitSha?: string;
    /** True when the worktree directory was successfully removed. */
    removed: boolean;
    /** Set when cleanup itself failed (best-effort, never throws to the run). */
    cleanupError?: string;
}
/** ChildResult enriched with the C6 worktree outcome (engine attaches it). */
export type WorktreeChildResult = ChildResult & {
    worktree?: WorktreeRunOutcome;
};
/** Classified worktree gate failure kinds (preflight, cycle-4 honesty fix). */
export type WorktreeErrorKind = "non_git_repo" | "no_commits" | "git_error";
/**
 * Classify a git failure detail into a worktree error kind:
 *   non_git_repo — `fatal: not a git repository` (outside any repo)
 *   no_commits   — unresolvable HEAD (`ambiguous argument 'HEAD'` /
 *                  `unknown revision` / `does not have any commits yet`)
 *   git_error    — any other git failure (timeout, permission, …)
 * Pure string classification — no fs, no spawn.
 */
export declare function classifyWorktreeGitError(detail: string): WorktreeErrorKind;
/** Classified worktree preflight outcome (clean errors; detail carried apart). */
export interface WorktreeGateOutcome {
    /** Clean, classified gate-error lines — NO raw git stderr (parent-facing). */
    errors: string[];
    /** Failure kind when the gate blocked (undefined when it passed). */
    kind?: WorktreeErrorKind;
    /** Bounded raw git detail (single line, ≤200 chars) for tool `details` only. */
    detail?: string;
}
/** Read the C6 worktree outcome from a child result (undefined when absent). */
export declare function getWorktreeOutcome(result: ChildResult): WorktreeRunOutcome | undefined;
/** Auto-commit message: "pi-agent: <desc>" with newlines collapsed + 200-char truncation. */
export declare function worktreeCommitMessage(description: string): string;
/**
 * Preflight validator: `worktree` isolation requires a git repository with
 * at least one commit (a resolvable HEAD). Returns blocking errors otherwise.
 */
export declare function validateWorktreeIsolation(isolation: string | undefined, repoRoot: string, opts?: {
    gitTimeoutMs?: number;
}): string[];
/**
 * Classified preflight validator (cycle 4): the gate error line carries ONLY
 * the classification (`… with at least one commit (non_git_repo)`) — the raw
 * git stderr stays out of the parent-facing message and rides `detail`
 * (bounded, single-line) for tool `details` payloads instead.
 */
export declare function validateWorktreeIsolationDetailed(isolation: string | undefined, repoRoot: string, opts?: {
    gitTimeoutMs?: number;
}): WorktreeGateOutcome;
/**
 * Create a disposable DETACHED worktree of `repoRoot` at HEAD, placed under
 * `opts.baseDir ?? tmpdir()` (never inside the repo). The path embeds the
 * sanitized runId + timestamp + pid + random suffix so concurrent runs never
 * collide. Throws a descriptive error when the target is not a git repo or
 * has no commits.
 */
export declare function createWorktree(repoRoot: string, runId: string, opts?: WorktreeOptions): WorktreeCreation;
/**
 * Cleanup after the child run (benchmark cleanupWorktree, worktree.ts:102-164):
 *   - dirty tree -> `git add -A` + auto-commit (--no-verify) + branch
 *     pi-agent-<runId> (timestamp suffix on conflict) + worktree remove;
 *   - clean tree with HEAD unchanged -> plain removal, hasChanges:false;
 *   - clean tree with HEAD MOVED (child committed itself) -> branch at the
 *     child's HEAD (committed:false, commitSha = the child's commit).
 * Always removes the worktree; throws only on git failures.
 */
export declare function cleanupWorktree(creation: WorktreeCreation, opts?: {
    gitTimeoutMs?: number;
}): WorktreeRunOutcome;
/**
 * Crash recovery (benchmark pruneWorktrees, worktree.ts:189): prune stale
 * worktree administrative entries whose directories are gone.
 */
export declare function pruneWorktrees(repoRoot: string, opts?: {
    gitTimeoutMs?: number;
}): void;