import { type ProgramIO } from '../cli-helpers.js';
import { type StageLabel } from '../../services/dispatch/stage-enum.js';
import { type HeartbeatOptions } from './sub-agent-shared.js';
/** `heartbeat` as commander hands it to the action (`--stage` is still a raw string). */
export type HeartbeatActionOptions = HeartbeatOptions & {
    stage?: string;
};
/** The progress the argument checks parsed, or nothing: the reject already printed. */
export type HeartbeatArgumentsCheck = {
    ok: true;
    progress: number;
} | {
    ok: false;
};
/** The validated `--stage` (null when the flag was absent or empty), or nothing. */
export type HeartbeatStageCheck = {
    ok: true;
    stage: StageLabel | null;
} | {
    ok: false;
};
/**
 * One failure envelope, printed the same way at every reject site: print, mark
 * the process failed, and let the caller `return`. All six sites already did
 * exactly this, so hoisting them cannot make two of them disagree.
 */
export declare function failHeartbeat(io: ProgramIO, f: {
    asJson: boolean;
    code: string;
    message: string;
    recordPath: string | null;
    nextAction: string;
}): void;
/**
 * The three argument checks that follow the record-existence guard, in the
 * order the command ran them. A reject prints and sets the exit code here; the
 * caller only returns.
 */
export declare function validateHeartbeatArguments(io: ProgramIO, asJson: boolean, options: HeartbeatActionOptions, recordPath: string): HeartbeatArgumentsCheck;
/**
 * optional `--stage` against the bounded enum BEFORE the heartbeat write so the
 * caller gets a specific `INVALID_STAGE` error rather than a generic
 * `HEARTBEAT_ERROR`. An absent or empty flag is not an error: it yields
 * `stage: null`, and `setStage` stays uncalled. The caller still runs this
 * AFTER `assertSafeDispatchRecordPath`, because which of the two fails first is
 * observable.
 */
export declare function resolveHeartbeatStage(io: ProgramIO, asJson: boolean, options: HeartbeatActionOptions, recordPath: string): HeartbeatStageCheck;
/**
 * the LLM-side runner gets a specific hint instead of the generic
 * "see error message" fallback.
 */
export declare function heartbeatErrorNextActions(code: string): string;
/** The writer's error code, or the catch-all the CLI has always answered with. */
export declare function heartbeatErrorCode(error: unknown): string;