export interface CommandResult {
    stdout: string;
    stderr: string;
    code: number;
    /**
     * Present and `true` when the command was terminated by the
     * `gracefulKillAfterMs` timeout-escalation path. Tools that wrote
     * partial output before the timeout (e.g. `xctrace record` which
     * incrementally flushes the `.trace` bundle) can return that output
     * to the caller alongside this flag, rather than the caller having
     * to choose between "throw on timeout" and "no timeout protection".
     */
    timedOut?: boolean;
}
export interface RunCommandOptions {
    /** Working directory to run the command in. */
    cwd?: string;
    /** Timeout in ms (kill the child if it exceeds this). */
    timeoutMs?: number;
    /**
     * Extra environment variables to expose to the child process. When provided,
     * these are MERGED on top of `process.env` (PATH, DEVELOPER_DIR, HOME and
     * other inherited vars are preserved). Pass an empty object to inherit
     * unchanged; pass `undefined` (or omit) for the same default.
     */
    env?: Record<string, string>;
    /**
     * Signal to send when the command exceeds `timeoutMs`. Defaults to
     * `SIGTERM`. Pass `SIGINT` for processes that flush partial output on
     * graceful interruption (e.g. xctrace writes the `.trace` bundle
     * incrementally and needs SIGINT to finalize template metadata; SIGTERM
     * leaves a corrupt trace that fails on export).
     */
    timeoutSignal?: NodeJS.Signals;
    /**
     * When `> 0`, switches the timeout path from "kill + reject" to
     * "graceful kill + resolve with partial output". On timeout: send
     * `timeoutSignal`, wait this many ms for the child to exit, then
     * escalate to SIGKILL if still alive. The promise resolves with the
     * partial stdout/stderr + `timedOut: true` on the response, instead
     * of rejecting with a timeout error.
     *
     * Use when partial output is meaningful (xctrace traces, long-running
     * recordings, etc.). Default `0` preserves the historical
     * "reject-on-timeout" behavior for all existing callers.
     */
    gracefulKillAfterMs?: number;
}
/**
 * Run a command and collect stdout/stderr. Does not throw on non-zero exit code,
 * the caller decides what's acceptable (e.g. `leaks` exits 1 when leaks are found,
 * which is normal).
 */
export declare function runCommand(cmd: string, args: string[], opts?: RunCommandOptions): Promise<CommandResult>;