fix: block landing until exact-head checks settle (#10669)

* fix: wait for exact-head PR checks before landing

* docs: refresh CLI waiver reference

* docs: preserve generated CLI reference EOF

Author: chubes4

crates/homeboy-cli/src/commands/git/args.rs

@@ -434,6 +434,14 @@ pub(super) enum PrCommand {
         /// Retry merge after this many base-branch-modified races.
         #[arg(long, default_value_t = 1)]
         max_base_retries: usize,
+
+        /// Maximum seconds to wait for all checks on the exact PR head to become terminal.
+        #[arg(long, default_value_t = 900)]
+        max_check_wait_seconds: u64,
+
+        /// Waive one non-required failed check as HEAD_SHA|CHECK_NAME|APPROVER.
+        #[arg(long = "check-waiver", value_name = "HEAD_SHA|CHECK_NAME|APPROVER")]
+        check_waivers: Vec<String>,
     },
 }
 

crates/homeboy-cli/src/commands/git/pr.rs

@@ -4,6 +4,7 @@ use homeboy::core::git::{
     PrPolicyMergeOptions, PrPolicyOpenOptions, PrPolicyTargetRefs, PrRefreshOptions,
     PrRefreshStrategy,
 };
+use std::time::Duration;
 
 use super::args::{ComponentPathArgs, PrArgs, PrCommand, PrPolicyArgs, PrPolicyCommand};
 use super::helpers::{parse_pr_state, read_lines_file, resolve_body};
@@ -226,7 +227,13 @@ pub(super) fn run_pr(args: PrArgs) -> CmdResult<GitCommandOutput> {
             refresh_helper,
             refresh_helper_args,
             max_base_retries,
+            max_check_wait_seconds,
+            check_waivers,
         } => {
+            let check_waivers = check_waivers
+                .iter()
+                .map(|raw| parse_check_waiver(raw))
+                .collect::<homeboy::core::Result<Vec<_>>>()?;
             let output = git::land_prs(PrLandOptions {
                 repo,
                 prs,
@@ -238,13 +245,43 @@ pub(super) fn run_pr(args: PrArgs) -> CmdResult<GitCommandOutput> {
                     args: refresh_helper_args,
                 }),
                 max_base_retries,
+                check_wait_timeout: Duration::from_secs(max_check_wait_seconds),
+                check_poll_interval: Duration::from_secs(5),
+                check_waivers,
             })?;
             let exit = if output.summary.blocked > 0 { 1 } else { 0 };
             Ok((GitCommandOutput::Land(output), exit))
         }
     }
 }
 
+fn parse_check_waiver(raw: &str) -> homeboy::core::Result<git::PrCheckWaiver> {
+    let mut parts = raw.splitn(3, '|');
+    let (Some(head_sha), Some(name), Some(approved_by)) =
+        (parts.next(), parts.next(), parts.next())
+    else {
+        return Err(homeboy::core::Error::validation_invalid_argument(
+            "check-waiver",
+            "expected HEAD_SHA|CHECK_NAME|APPROVER",
+            Some(raw.to_string()),
+            None,
+        ));
+    };
+    if head_sha.trim().is_empty() || name.trim().is_empty() || approved_by.trim().is_empty() {
+        return Err(homeboy::core::Error::validation_invalid_argument(
+            "check-waiver",
+            "head SHA, check name, and approver must all be non-empty",
+            Some(raw.to_string()),
+            None,
+        ));
+    }
+    Ok(git::PrCheckWaiver {
+        head_sha: head_sha.to_string(),
+        name: name.to_string(),
+        approved_by: approved_by.to_string(),
+    })
+}
+
 fn parse_pr_refresh_strategy(value: &str) -> homeboy::core::Result<PrRefreshStrategy> {
     match value {
         "auto" => Ok(PrRefreshStrategy::Auto),

crates/homeboy-core/src/git/mod.rs

@@ -72,7 +72,7 @@ pub use operations_tags::{
     is_ancestor, remote_branch_commit, remote_tag_commit, short_head_revision_at, tag, tag_at,
     tag_exists_locally, tag_exists_on_remote,
 };
-pub use pr_land::{land_prs, PrLandOptions, PrLandOutput, PrLandRefreshHelper};
+pub use pr_land::{land_prs, PrCheckWaiver, PrLandOptions, PrLandOutput, PrLandRefreshHelper};
 pub use pr_policy::{
     evaluate_merge_policy, evaluate_open_policy, PrPolicyContext, PrPolicyDecision, PrPolicyFile,
     PrPolicyMergeOptions, PrPolicyMode, PrPolicyOpenOptions, PrPolicyRules, PrPolicyTargetRefs,