/**
 * Whether a directory can host a `git`/`gh` evidence invocation, which tree to
 * run in when the CLEO root is not itself a checkout, and what to say when no
 * tree can be found (gh#1462).
 *
 * `pr:` and `commit:` atoms shell out to `gh` / `git` from a working directory.
 * `gh` does its OWN repo discovery: it walks up from its cwd and, finding no
 * repository before the filesystem boundary, fails with
 *
 *   fatal: not a git repository (or any parent up to mount point /mnt)
 *
 * That message arrives as `E_EVIDENCE_TOOL_FAILED` — the same code a tool that
 * genuinely ran and failed produces — so a CLEO root that is a PARENT of the
 * checkout is indistinguishable from a broken `gh` or an atom this project
 * cannot satisfy. The layout is the cause; the error has to say so.
 *
 * Both atoms ask the same question and need the same remediation, so it lives
 * here rather than being spelled out twice.
 *
 * @task gh#1462
 */
/**
 * Error code for "no git work tree at or above the evidence execution root".
 *
 * Deliberately distinct from `E_EVIDENCE_TOOL_FAILED` (the tool ran and failed)
 * and from `E_EVIDENCE_INVALID` (the atom itself cannot hold here). The reader
 * of this code is being told to fix the directory, not to stop trusting the
 * evidence route.
 *
 * @task gh#1462
 */
export declare const E_EVIDENCE_GIT_ROOT: "E_EVIDENCE_GIT_ROOT";
/**
 * Environment variable naming the checkout that evidence tools must run in.
 *
 * The CLEO-specific override, and the one the failure message points at. It
 * beats every other signal because it is the only one that can only have been
 * set on purpose for this invocation.
 *
 * @task T12308
 */
export declare const EVIDENCE_GIT_ROOT_ENV = "CLEO_EVIDENCE_GIT_ROOT";
/**
 * A copy of `env` with git's ambient repo-pointing variables removed.
 *
 * @param env - Source environment. Defaults to the current process env.
 * @returns Environment safe for directory-discovery probes.
 * @task T12308
 */
export declare function discoveryEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
/**
 * True when `dir` is inside a git work tree of its own — its own checkout or a
 * descendant of one, since git walks up. False when the directory is missing,
 * is not a work tree, or `git` itself cannot be spawned.
 *
 * Ambient `GIT_DIR`/`GIT_WORK_TREE` are ignored on purpose; see
 * {@link GIT_AMBIENT_REPO_VARS}.
 *
 * @param dir - Directory the tools would run in.
 * @task gh#1462
 */
export declare function isGitWorkTree(dir: string): boolean;
/**
 * Why `root` looks like a checkout that git cannot open with the inherited
 * repo pointers ignored, or `null` when it opens (or is plainly not a checkout).
 *
 * Evidence reads strip ambient `GIT_DIR`/`GIT_WORK_TREE` ({@link discoveryEnv}).
 * A linked worktree whose `.git` link points at a moved main repository works
 * for its owner only with those exported, so every evidence probe fails there
 * and a freshness or coverage check would silently judge nothing (T13703). A
 * root with no `.git` and no exported pointer is a genuine non-git root and
 * returns `null`, keeping its no-binding behaviour.
 *
 * @param root - The resolved bind root.
 * @param env - Environment whose exported pointers are reported. Defaults to `process.env`.
 * @returns The refusal reason naming the remedy, or `null`.
 * @task T13703
 */
export declare function brokenWorkTreeReason(root: string, env?: NodeJS.ProcessEnv): string | null;
/**
 * Absolute toplevel of the checkout containing `dir`, or `null` when there is
 * none.
 *
 * @param dir - Directory to resolve from.
 * @task T12308
 */
export declare function gitToplevel(dir: string): string | null;
/**
 * Absolute git common directory of the checkout containing `dir` — shared by a
 * repository's main checkout and its linked worktrees — or `null` when none.
 *
 * @param dir - Directory to resolve from.
 * @task T14012
 */
export declare function gitCommonDir(dir: string): string | null;
/**
 * Raw `origin` remote URL of the checkout containing `dir`, or `null`.
 *
 * @param dir - Directory to resolve from.
 * @task T14012
 */
export declare function gitOriginUrl(dir: string): string | null;
/**
 * True when `HEAD` of the checkout at `toplevel` contains `relPath` (a file or
 * directory), i.e. the repository tracks something there.
 *
 * @param toplevel - Checkout toplevel.
 * @param relPath - POSIX path relative to `toplevel`.
 * @task T14012
 */
export declare function gitHeadHasPath(toplevel: string, relPath: string): boolean;
/**
 * Toplevels of the submodules checked out below `toplevel`, recursively.
 *
 * @param toplevel - Superproject checkout toplevel.
 * @returns Canonical absolute paths; empty when there are none.
 * @task T14012
 */
export declare function gitSubmoduleToplevels(toplevel: string): string[];
/**
 * Every git work tree directly below `dir`, in stable sorted order.
 *
 * One level only, on purpose. A CLEO root that parents its checkouts — the
 * layout gh#1462 reports — has the repositories as direct children, while a
 * recursive search would descend into `node_modules` and vendored trees.
 * Dot-directories are skipped so `.cleo/`, `.git/` and editor state are never
 * candidates.
 *
 * @param dir - Candidate parent directory (the CLEO store root).
 * @returns Canonical absolute paths; empty when there are none.
 * @task T12308
 */
export declare function findNestedGitWorkTrees(dir: string): string[];
/**
 * The single git work tree directly below `dir`, or `null` when there is none
 * or more than one.
 *
 * Ambiguity returns `null` so the caller can report it — or disambiguate with
 * {@link findWorkTreeContainingCommit} — instead of picking one.
 *
 * @param dir - Candidate parent directory (the CLEO store root).
 * @task gh#1462
 */
export declare function findNestedGitWorkTree(dir: string): string | null;
/**
 * The one candidate checkout that contains `sha`, or `null` when none or
 * several do.
 *
 * This is what makes a multi-repo CLEO root resolvable WITHOUT configuration:
 * a `commit:` atom is a statement about exactly one repository, and "which of
 * these checkouts has this object" has a single correct answer almost always.
 * Several matches (shared history) or none stay unresolved rather than being
 * guessed, so the caller reports the ambiguity.
 *
 * @param candidates - Checkouts to search, e.g. from {@link findNestedGitWorkTrees}.
 * @param sha - Commit SHA the evidence is about.
 * @task T12308
 */
export declare function findWorkTreeContainingCommit(candidates: readonly string[], sha: string): string | null;
/**
 * True when the checkout containing `dir` has commit `sha` (a 7–40 hex sha).
 *
 * @param dir - Checkout to probe.
 * @param sha - Commit SHA.
 * @task T14012
 */
export declare function gitHasCommit(dir: string, sha: string): boolean;
/** An evidence git root the operator declared, and where the declaration came from. */
export interface DeclaredEvidenceGitRoot {
    /** Absolute path exactly as declared (resolved against the store root when relative). */
    path: string;
    /** Human-readable provenance, used verbatim in failure text. */
    source: string;
}
/**
 * `evidence.gitRoot` from the text of a `.cleo/project-context.json`.
 *
 * Split from the file read so a caller that must bound the read (a probe
 * over hundreds of checkouts, some on slow filesystems) can read the file
 * asynchronously under its own deadline and still share this parse.
 *
 * @param raw - File contents.
 * @returns The trimmed declared root, or `null` when absent or malformed.
 * @task T12511
 */
export declare function parseConfiguredGitRoot(raw: string): string | null;
/**
 * The checkout the operator declared for evidence execution, if any.
 *
 * Precedence, most to least specific:
 *
 *  1. `CLEO_EVIDENCE_GIT_ROOT` — set for this invocation, for this purpose.
 *  2. `GIT_WORK_TREE` — git's own override, and the one the old failure text
 *     advertised. It is honoured by RUNNING in that tree, which is the part
 *     that was missing: setting it alone never helped, because every tool
 *     still ran with its cwd at the CLEO root.
 *  3. `.cleo/project-context.json` → `evidence.gitRoot` — the durable,
 *     committed answer for a root that parents several repositories.
 *
 * The result is NOT validated here. A declared path that is not a work tree
 * must fail loudly and by name rather than falling back to a different tree
 * and attesting against it, so validation belongs to the caller's guard.
 *
 * @param storeRoot - CLEO store root; relative declarations resolve against it.
 * @param env - Environment to read. Defaults to the current process env.
 * @task T12308
 */
export declare function resolveDeclaredEvidenceGitRoot(storeRoot: string, env?: NodeJS.ProcessEnv): DeclaredEvidenceGitRoot | null;
/** Context that makes {@link describeMissingGitWorkTree} name the actual fix. */
export interface MissingGitWorkTreeContext {
    /** CLEO store root, when it differs from the directory that was tried. */
    storeRoot?: string;
    /** Checkouts found directly below the store root. */
    candidates?: readonly string[];
    /** Provenance of a declared root that turned out not to be a work tree. */
    declaredFrom?: string;
}
/**
 * Reason text for {@link E_EVIDENCE_GIT_ROOT}.
 *
 * The previous text offered `GIT_DIR`/`GIT_WORK_TREE` as the remedy. That
 * advice could not work: the guard asks whether the *current directory* is
 * inside a work tree, and the CLEO root never is, so following it produced the
 * identical error and left the reader with nothing to try. Every branch here
 * therefore names a remedy that has a test proving it resolves the layout.
 *
 * @param dir - Directory the tools would have run in.
 * @param context - What else is known about the layout.
 * @task gh#1462
 * @task T12308
 */
export declare function describeMissingGitWorkTree(dir: string, context?: MissingGitWorkTreeContext): string;
/**
 * The complete {@link E_EVIDENCE_GIT_ROOT} reason for a store root whose
 * resolved execution root turned out not to be a checkout.
 *
 * Composed here, beside the resolution inputs it reports on, so the message
 * and the resolution order cannot drift apart: a declaration that was honoured
 * is named, otherwise the sibling checkouts that made the choice ambiguous are.
 *
 * @param storeRoot - Absolute CLEO store root.
 * @param executionRoot - Root the tools would have run in.
 * @task T12308
 */
export declare function describeUnusableEvidenceGitRoot(storeRoot: string, executionRoot: string): string;
//# sourceMappingURL=work-tree.d.ts.map