/**
 * Failed-first reruns for `tool:test` (T12961).
 *
 * When a test run fails, the failing test FILES are parsed out of the runner's
 * output and remembered per execution root. The next test run in that root —
 * normally after an attempted fix, so on a different tree and a cache miss —
 * runs only those files first:
 *
 *   - still failing (with a parseable FAIL line) → the caller gets that red
 *     result at once and the full run is skipped. It is NOT cached under the
 *     full command's key — the suite did not run — and the pointer moves to
 *     the current tree, so the next run on this same tree runs the normal
 *     command, which decides;
 *   - passing, or no FAIL line (a startup crash) → the normal run (full or
 *     affected) proceeds as before.
 *
 * Everything here is best-effort and fails OPEN to today's behaviour: when the
 * failing files cannot be parsed, resolved to tracked files, or mapped to a
 * runnable vitest binary and config, no focused run is planned and the normal
 * command runs unchanged. `CLEO_EVIDENCE_FRESH=1` skips failed-first. A
 * focused run can only ever *shorten* a red result; it can never produce or
 * cache a pass, because a pass always falls through to the normal command.
 *
 * The flake retry lives in `runToolCached`: a failing normal run is re-run in
 * FULL once, never through a focused run.
 *
 * ## Why the default reporter's text, not a JSON reporter
 *
 * The resolved test command is the project's own (`pnpm run test`, a pinned
 * `testing.command`, an affected-packages command). Injecting
 * `--reporter=json --outputFile=…` into it would change the command — and
 * therefore the cache key and the evidence identity — and does not compose
 * with scripts that fan out (`pnpm -r test`). The `FAIL <file>` lines of the
 * vitest and jest default reporters sit in the closing summary, which is
 * exactly the part the 64 KiB stream tail retains.
 *
 * ## Why the pointer is keyed on (tool, execution root), not on the command
 *
 * A failing test file is a failing test file whichever command found it: a
 * full run's failures are just as worth re-running first before an affected
 * run, whose command (and therefore cache key) differs. Scoping by execution
 * root keeps one agent's red files out of another worktree's runs. Even if
 * they did cross, a focused failure is a genuine failure of THIS tree's tests.
 *
 * @task T12961
 */
/** Canonical tools that record failing files and get failed-first reruns. */
export declare const FAILED_FIRST_TOOLS: ReadonlySet<string>;
/**
 * Most failing files remembered. A larger red set means the tree is broadly
 * broken; the full run is the right next step and the pointer is dropped.
 */
export declare const MAX_FAILED_TEST_FILES = 100;
/** How a failed-first stage ended. */
export type FailedFirstOutcome = 'failed' | 'passed' | 'inconclusive';
/**
 * Report of the failed-first stage of one run, attached to the result (and,
 * when the focused run decided the result, to the cache entry).
 *
 * @task T12961
 */
export interface FailedFirstReport {
    /** Repo-relative test files that were run first. */
    files: string[];
    /** `failed` stops the run; `passed`/`inconclusive` continue to the normal command. */
    outcome: FailedFirstOutcome;
}
/** The remembered failing files for one (tool, execution root). */
export interface FailedFirstPointer {
    schemaVersion: 1;
    canonical: string;
    executionRoot: string;
    /** Test files relative to `executionRoot`, forward slashes. */
    files: string[];
    /** Tree hash of the run that failed. */
    treeHash: string | null;
    capturedAt: string;
}
/** One focused vitest invocation. */
export interface FocusedRun {
    /** Directory holding the vitest config the files belong to. */
    cwd: string;
    /** Absolute path of the vitest binary. */
    cmd: string;
    args: string[];
}
/**
 * Raw `{base, file}` references to failing test files in runner output.
 *
 * @internal exported for tests
 */
export declare function extractFailingTestRefs(output: string): Array<{
    base: string | null;
    file: string;
}>;
/**
 * Parse the failing test files out of a run's output and resolve each to a
 * path relative to `executionRoot`.
 *
 * A reported path is tried against the `pnpm -r` package prefix, the
 * execution root itself, and `searchBase` (the cwd of a focused run). A path
 * none of those resolve is looked up among tracked files by suffix and kept
 * only when exactly one matches. Unresolvable references are dropped; an empty
 * result means "unknown" and disables failed-first for the next run.
 *
 * @param output - stdout and stderr of the run (ANSI allowed).
 * @param executionRoot - Tree the run executed in.
 * @param trackedFiles - Lazily supplied tracked-file list for suffix lookup.
 * @param searchBase - Extra directory paths may be relative to.
 * @returns Sorted, de-duplicated repo-relative paths; `[]` when unknown or
 *   when more than {@link MAX_FAILED_TEST_FILES} failed.
 *
 * @task T12961
 */
export declare function parseFailingTestFiles(output: string, executionRoot: string, trackedFiles?: () => readonly string[], searchBase?: string): string[];
/** `true` when vitest reported that the filters matched no test file. */
export declare function reportsNoTestFiles(output: string): boolean;
/**
 * Plan the focused invocations that re-run `files` in `executionRoot`.
 *
 * Each file runs under the vitest config nearest to it — the same config a
 * `cd <package> && vitest run <file>` would use — with the nearest
 * `node_modules/.bin/vitest`. Files are grouped per config directory.
 *
 * @returns The runs, or `null` when any file is gone or has no vitest config
 *   or binary (failed-first is then skipped; the normal command runs).
 *
 * @task T12961
 */
export declare function planFocusedRuns(files: readonly string[], executionRoot: string): FocusedRun[] | null;
/**
 * Path of the failed-first pointer for one (tool, execution root). Lives in
 * the evidence cache directory, so `clearToolCache` removes it too.
 *
 * @param storeRoot - CLEO store root holding `.cleo/cache/evidence/`.
 * @param canonical - Canonical tool name.
 * @param executionRoot - Normalised execution root.
 *
 * @task T12961
 */
export declare function failedFirstPointerPath(storeRoot: string, canonical: string, executionRoot: string): string;
/**
 * Read the failed-first pointer, or `null` when absent or malformed.
 *
 * @task T12961
 */
export declare function readFailedFirstPointer(storeRoot: string, canonical: string, executionRoot: string): FailedFirstPointer | null;
/**
 * Remember `files` as the failing set, or forget it when `files` is empty.
 * The cache directory must already exist.
 *
 * @task T12961
 */
export declare function writeFailedFirstPointer(storeRoot: string, canonical: string, executionRoot: string, files: readonly string[], treeHash: string | null): void;
//# sourceMappingURL=tool-cache-failed-first.d.ts.map