/**
 * Halt report schema per DESIGN.md §6. The first-line-of-defence documentation
 * for "what did brewing try, why did it stop, what should the human do next."
 * Written to disk + posted as a GitHub issue comment on halt.
 */
export interface HaltReport {
    story_id: string;
    halt_reason: HaltReason;
    halt_timestamp: string;
    iterations_run: number;
    checkpoints_committed: number;
    tests_green: number;
    tests_total: number;
    tokens_spent_usd: number;
    budget_usd: number;
    model: string;
    summary_plain_english: string;
    /**
     * α.51 — brew mode in effect when the halt fired. Populated by
     * brew/agent.ts from BrewContext.allowedPaths + the dispatched
     * --mode flag. Chef reads this to know whether
     * "rejected-overflow" iteration outcomes are due to `--mode plate`
     * (hardcoded restrictive paths) vs `--mode freehand` (no
     * restriction — would be a code bug if scope-rejected) vs explicit
     * `allowed_paths` config. Without this, chef hallucinates that
     * `allowed_paths` is a spec yaml field (it is not) and gives PM
     * advice that has no effect (delgoosh#656 dogfood 2026-05-25).
     */
    brew_mode?: "auto" | "plate" | "freehand";
    /** The `allowedPaths` array brew enforced. Empty array = no restriction. */
    allowed_paths?: string[];
    /**
     * α.57 — name of the branch brew committed checkpoints onto + pushed.
     * Without this, downstream chef-on-brew-halt can't tell which branch
     * holds the in-progress src/ files; chef checks out main (the
     * default-branch checkout that chef's workflow performs), then can't
     * find the files the failing tests import, then HALLUCINATES contents.
     * Caught 2026-05-26 dogfood: delgoosh#003 chef-drift logged
     * "brew-halt enriched: 2 failing test file(s), 0 source file(s)" —
     * source-file resolver couldn't see files that only exist on the
     * brew branch.
     */
    brew_branch?: string;
    /** Full per-iteration diffs. Carries every iteration brewing ran, not just the last few,
     * so post-hoc diagnosis of a stuck loop doesn't lose iters 1..N-3. */
    iteration_diffs?: IterationDiff[];
    last_agent_rationale?: string;
    /** Suggested human actions. At least one MUST be present — if not, it's a halt-logic bug. */
    suggested_actions: SuggestedAction[];
}
export type HaltReason = "SUCCESS_ALL_GREEN" | "BUDGET_EXHAUSTED" | "ITERATION_CAP" | "STAGNATION_CAP" | "WALL_CLOCK" | "TESTS_NEVER_GREEN" | "TEST_RUNNER_BROKEN" | "MANIFEST_DRIFT" | "VIOLATION_STREAK" | "API_ERROR" | "AGENT_STALLED_NO_EDITS" | "AGENT_SELF_REPORTED_STUCK" | "TRANSITIVE_REGRESSION" | "MOCKUP_DESIGN_CONFLICT" | "SPEC_AMBIGUITY_DETECTED";
export interface IterationDiff {
    iteration: number;
    target_test_id: string;
    files_changed: number;
    files_touched: string[];
    lines_added: number;
    lines_removed: number;
    outcome: "checkpoint" | "reverted-regression" | "reverted-no-progress" | "rejected-overflow" | "rejected-frozen-path" | "test-runner-broken";
    note: string;
    /** For `reverted-regression` outcomes: the previously-green tests this iter broke.
     * Load-bearing for diagnosing assertion contradictions across stories. */
    broken_tests?: string[];
    spend_delta_usd?: number;
    rationale?: string;
}
export interface SuggestedAction {
    id: string;
    label: string;
    description: string;
    /** Optional free-text hint for an agent resuming this story later. */
    prompt_prefill?: string;
}
export declare function writeHaltReport(path: string, report: HaltReport): void;
/** Render a halt report as a markdown comment for posting on an issue. */
export declare function haltReportToMarkdown(report: HaltReport): string;
/**
 * Build the default suggested-actions list for a given halt reason. Invariant
 * (DESIGN.md §6.3): every halt must surface at least one concrete option. If
 * the caller passes extras, they go first; defaults come after so the caller
 * can tailor without losing fallback options.
 */
export declare function defaultSuggestedActions(reason: HaltReason, ctx: {
    budget_usd: number;
    iterations_run: number;
}): SuggestedAction[];
//# sourceMappingURL=halt.d.ts.map