/**
 * The shape of an actionable refusal (GUIDELINES §3: `<what went wrong> — <how to fix it>`,
 * most important line last). `what` and `hint` are SEPARATE fields by design: the command
 * glue prints the hint as its own line, and a hint must only ever be text WE wrote — never a
 * tail sliced off a message that may have come from a server, a parser, or an exception
 * (PR #157 review, M3: deriving the hint by splitting prose on an em-dash let upstream text
 * become "the most important line").
 *
 * `code` names the catalog row (error-catalog.ts): origin and exit derive from it, so a
 * failure can never claim one thing on stderr and another in its exit code. `trace` is the
 * third kind of text — the AGENT's own stderr — printed verbatim under its own header and
 * never mixed into `what` or `hint`.
 *
 * Domain modules produce these; `commands/failure.ts` renders them. A caught exception's
 * message becomes `what` with NO hint and the PLATFORM code.
 */
import type { ErrorCode } from "./error-catalog";
export interface CliFailure {
    /** Catalog code — origin and exit derive from it (error-catalog.ts). */
    code: ErrorCode;
    what: string;
    hint?: string;
    /** Agent-origin only: the agent's OWN stderr tail, verbatim. Never text we wrote. */
    trace?: string;
}
export declare function stripAnsi(text: string): string;
/**
 * A failure from text we do not own (an exception, a server message): the text, no hint.
 * WHOSE fault comes from the HTTP status when the error carries one (api-client's ApiError):
 * a 4xx is the marketplace refusing THIS request for the current state — not retryable, so
 * REFUSED (exit 3); anything else is PLATFORM (exit 1, retry). The staging matrix 2026-09-06
 * found `test --agent <bogus>` ("no such agent", a 404) and a reserved secret name (a 422)
 * both telling the builder's agent to retry.
 */
/** The one sentence every signed-out refusal ends with. Lives here, dependency-free, so the
 * workspace resolver and `failureFrom` cannot drift apart on what "sign in" means. */
export declare const NOT_SIGNED_IN_HINT = "run `clustly login` (or pipe a key to `clustly login --with-token`) first";
/**
 * A `clustly.yaml` the parser refused.
 *
 * NOT `failureFrom`: that maps any bare Error to PLATFORM, whose catalog row says "your input was
 * fine" and whose exit 1 means "retry" — advice that can never succeed against a file with a typo
 * in it, and which files the builder's mistake under the console's red ours-to-fix badge (field
 * report 2026-09-19: `price_usdc: 0.5` on `clustly publish`). MANIFEST_INVALID is origin `state`,
 * exit 3: fix the file, do not retry. No hint — the parser's own message already names the line
 * and, for an unknown key, the keys that exist.
 */
export declare function manifestFailure(e: unknown): CliFailure;
export declare function failureFrom(e: unknown): CliFailure;