/**
 * run-stage runs the steps of one stage in declared order, threading them
 * through the shared worktree. Steps within a stage hand off through the
 * filesystem (designer writes a note, worker reads it and commits, verifier
 * reads the committed state) — so the stage does not pass commit SHAs between
 * its own steps; it records the LAST committing step's SHA as the stage's
 * handoff token for the NEXT stage.
 *
 * Sequential and fail-fast, with one recovery path: when a verifier returns
 * VERDICT: FAIL [implementation], the stage re-runs its worker with the
 * verifier's feedback injected and re-verifies, bounded by a retry limit. A
 * FAIL [plan] (or an exhausted limit) halts to a human — never auto-replan, as
 * that would break the frozen-plan guarantee. Pure orchestration over run-step,
 * unit-tested against fakes. Progress events are emitted through the optional
 * ProgressPort in deps.
 */
import { type RunStepDeps, type Step, type StepResult } from "./run-step.ts";
export interface Stage {
    issue: string;
    stage: string;
    steps: Step[];
    /**
     * Recovery worker for a stage whose verifying step has NO worker in its own
     * step list — specifically the FINAL whole-feature verification (a planner-
     * tier step with verifies:true that commits nothing). When that holistic
     * verifier returns a code-fixable FAIL [implementation], run-stage re-runs
     * THIS worker with the verdict feedback, then re-verifies — bounded by the
     * retry limit — instead of halting unrecoverably after every stage passed.
     * Omitted for ordinary stages, which recover via their own inline worker.
     */
    recoveryWorker?: Step;
}
export interface StageResult {
    steps: StepResult[];
    /** The last committing step's SHA — the stage's handoff token, if any. */
    commit?: string;
}
/**
 * Bounds the worker re-attempts on an implementation FAIL. `limit` is the
 * number of EXTRA worker runs allowed after the first; 0 (the default) means no
 * retry, preserving the original fail-fast behaviour exactly.
 */
export interface RetryPolicy {
    limit: number;
}
export declare function runStage(deps: RunStepDeps, stage: Stage, retry?: RetryPolicy): Promise<StageResult>;