4 files changed, 284 insertions, 4 deletions

diff --git a/src/git/authorization.rs b/src/git/authorization.rs
index db2b992..27107db 100644
--- a/src/git/authorization.rs
+++ b/src/git/authorization.rs
@@ -666,12 +666,88 @@ pub async fn get_state_authorization_for_specific_owner_repo(
             debug!("Purgatory events found but none from authorized authors");
         }
     } else {
-        debug!("No matching state events found in purgatory");
+        // Check if there are ANY state events in purgatory for this identifier
+        let all_purgatory_states = purgatory.find_state(identifier);
+
+        if !all_purgatory_states.is_empty() {
+            // There are state events but none match the push - diagnose why
+            debug!(
+                "Found {} state event(s) in purgatory for {} but none match the push",
+                all_purgatory_states.len(),
+                identifier
+            );
+
+            // Count authorized state events and collect diagnostic info
+            let mut authorized_count = 0;
+            let mut diagnostic_reasons = Vec::new();
+
+            // Diagnose why each authorized state event doesn't match
+            for entry in all_purgatory_states.iter() {
+                let author_hex = entry.event.pubkey.to_hex();
+                if authorized.contains(&author_hex) {
+                    authorized_count += 1;
+                    if let Some(reason) = crate::purgatory::diagnose_state_mismatch(
+                        &entry.event,
+                        &pushed_updates,
+                        &local_refs,
+                    ) {
+                        debug!(
+                            "State event {} from authorized author {} doesn't match push: {}",
+                            entry.event.id,
+                            entry
+                                .event
+                                .pubkey
+                                .to_bech32()
+                                .unwrap_or_else(|_| author_hex.clone()),
+                            reason
+                        );
+                        diagnostic_reasons.push(reason);
+                    }
+                }
+            }
+
+            // Create concise WARN message summarizing the rejection
+            let summary = if authorized_count > 0 {
+                let reason_summary = if !diagnostic_reasons.is_empty() {
+                    // Take the first diagnostic reason as representative
+                    format!(" ({})", diagnostic_reasons[0])
+                } else {
+                    String::new()
+                };
+                format!(
+                    "{} state event{} in purgatory from authorized publisher{} but doesn't match push{}",
+                    authorized_count,
+                    if authorized_count == 1 { "" } else { "s" },
+                    if authorized_count == 1 { "" } else { "s" },
+                    reason_summary
+                )
+            } else {
+                format!(
+                    "{} state event{} in purgatory but none from authorized publishers",
+                    all_purgatory_states.len(),
+                    if all_purgatory_states.len() == 1 {
+                        ""
+                    } else {
+                        "s"
+                    }
+                )
+            };
+
+            warn!("Push rejected for {}: {}", identifier, summary);
+            return Ok(AuthorizationResult::denied(summary));
+        } else {
+            debug!("No state events found in purgatory for {}", identifier);
+            warn!(
+                "Push rejected for {}: No state events in purgatory",
+                identifier
+            );
+            return Ok(AuthorizationResult::denied("No state events in purgatory"));
+        }
     }
 
     // No matching state found in purgatory
     Ok(AuthorizationResult::denied(
-        "No state event found in purgatory from authorized publishers",
+        "No matching state event found in purgatory from authorized publishers",
     ))
 }
 
diff --git a/src/git/handlers.rs b/src/git/handlers.rs
index e3a6ad4..7244abb 100644
--- a/src/git/handlers.rs
+++ b/src/git/handlers.rs
@@ -254,7 +254,7 @@ pub async fn handle_receive_pack(
     }
 
     // GRASP Authorization Check
-    info!(
+    debug!(
         "Authorizing push for {} owned by {} via database query",
         identifier, owner_pubkey
     );
diff --git a/src/purgatory/helpers.rs b/src/purgatory/helpers.rs
index 193ef99..a9f6e66 100644
--- a/src/purgatory/helpers.rs
+++ b/src/purgatory/helpers.rs
@@ -225,6 +225,117 @@ pub fn get_unpushed_refs(event: &Event, pushed_refs: &[RefPair]) -> Vec<RefPair>
         .collect()
 }
 
+/// Diagnose why a state event doesn't match the push.
+///
+/// Returns a human-readable explanation of the mismatch between the state event
+/// and what would result from applying the push to local refs.
+///
+/// # Arguments
+/// * `event` - The state event to check
+/// * `pushed_updates` - Ref updates in the current push operation
+/// * `local_refs` - Refs already existing locally (ref_name -> SHA)
+///
+/// # Returns
+/// String explaining why the state doesn't match, or None if it matches
+pub fn diagnose_state_mismatch(
+    event: &Event,
+    pushed_updates: &[RefUpdate],
+    local_refs: &HashMap<String, String>,
+) -> Option<String> {
+    let state_refs = extract_refs_from_state(event);
+
+    // Filter local_refs to only branches and tags
+    let mut would_be_state: HashMap<String, String> = local_refs
+        .iter()
+        .filter(|(ref_name, _)| {
+            ref_name.starts_with("refs/heads/") || ref_name.starts_with("refs/tags/")
+        })
+        .map(|(k, v)| (k.clone(), v.clone()))
+        .collect();
+
+    // Apply all pushed updates to create the would-be state
+    for update in pushed_updates {
+        // Only process branches and tags
+        if !update.ref_name.starts_with("refs/heads/") && !update.ref_name.starts_with("refs/tags/")
+        {
+            continue;
+        }
+
+        if update.is_deletion() {
+            would_be_state.remove(&update.ref_name);
+        } else {
+            would_be_state.insert(update.ref_name.clone(), update.new_oid.clone());
+        }
+    }
+
+    // Convert event's state refs to a HashMap for comparison
+    let declared_state: HashMap<String, String> = state_refs
+        .into_iter()
+        .map(|r| (r.ref_name, r.object_sha))
+        .collect();
+
+    // Check if they match
+    if would_be_state == declared_state {
+        return None; // No mismatch
+    }
+
+    // Build diagnostic message
+    let mut reasons = Vec::new();
+
+    // Check for refs in declared state but not in would-be state
+    for (ref_name, declared_sha) in &declared_state {
+        if let Some(would_be_sha) = would_be_state.get(ref_name) {
+            if would_be_sha != declared_sha {
+                let would_be_short = if would_be_sha.len() >= 8 {
+                    &would_be_sha[..8]
+                } else {
+                    would_be_sha.as_str()
+                };
+                let declared_short = if declared_sha.len() >= 8 {
+                    &declared_sha[..8]
+                } else {
+                    declared_sha.as_str()
+                };
+                reasons.push(format!(
+                    "{} would be at {} but state declares {}",
+                    ref_name, would_be_short, declared_short
+                ));
+            }
+        } else {
+            let declared_short = if declared_sha.len() >= 8 {
+                &declared_sha[..8]
+            } else {
+                declared_sha.as_str()
+            };
+            reasons.push(format!(
+                "{} missing (state declares {})",
+                ref_name, declared_short
+            ));
+        }
+    }
+
+    // Check for refs in would-be state but not in declared state
+    for (ref_name, would_be_sha) in &would_be_state {
+        if !declared_state.contains_key(ref_name) {
+            let would_be_short = if would_be_sha.len() >= 8 {
+                &would_be_sha[..8]
+            } else {
+                would_be_sha.as_str()
+            };
+            reasons.push(format!(
+                "{} would exist at {} but state doesn't declare it",
+                ref_name, would_be_short
+            ));
+        }
+    }
+
+    if reasons.is_empty() {
+        Some("Unknown mismatch".to_string())
+    } else {
+        Some(reasons.join("; "))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -695,4 +806,97 @@ mod tests {
         // Should return true - real OID exists, symbolic ref skipped
         assert!(can_apply_state(&event, repo_path));
     }
+
+    #[test]
+    fn test_diagnose_state_mismatch_missing_ref() {
+        // State declares both main and test branches
+        let event = create_test_state_event(
+            "test-repo",
+            vec![("refs/heads/main", "abc123"), ("refs/heads/test", "def456")],
+        );
+
+        // Push only creates test branch
+        let pushed_updates = vec![RefUpdate {
+            old_oid: "0000000000000000000000000000000000000000".to_string(),
+            new_oid: "def456".to_string(),
+            ref_name: "refs/heads/test".to_string(),
+        }];
+
+        // No local refs
+        let local_refs = HashMap::new();
+
+        let diagnosis = diagnose_state_mismatch(&event, &pushed_updates, &local_refs);
+        assert!(diagnosis.is_some());
+        let msg = diagnosis.unwrap();
+        assert!(msg.contains("refs/heads/main"));
+        assert!(msg.contains("missing"));
+    }
+
+    #[test]
+    fn test_diagnose_state_mismatch_wrong_sha() {
+        // State declares main at abc123
+        let event = create_test_state_event("test-repo", vec![("refs/heads/main", "abc123")]);
+
+        // Push updates main to different SHA
+        let pushed_updates = vec![RefUpdate {
+            old_oid: "0000000000000000000000000000000000000000".to_string(),
+            new_oid: "wrong123".to_string(),
+            ref_name: "refs/heads/main".to_string(),
+        }];
+
+        let local_refs = HashMap::new();
+
+        let diagnosis = diagnose_state_mismatch(&event, &pushed_updates, &local_refs);
+        assert!(diagnosis.is_some());
+        let msg = diagnosis.unwrap();
+        assert!(msg.contains("refs/heads/main"));
+        assert!(msg.contains("would be at"));
+        assert!(msg.contains("state declares"));
+    }
+
+    #[test]
+    fn test_diagnose_state_mismatch_extra_ref() {
+        // State declares only main
+        let event = create_test_state_event("test-repo", vec![("refs/heads/main", "abc123")]);
+
+        // Push creates both main and test
+        let pushed_updates = vec![
+            RefUpdate {
+                old_oid: "0000000000000000000000000000000000000000".to_string(),
+                new_oid: "abc123".to_string(),
+                ref_name: "refs/heads/main".to_string(),
+            },
+            RefUpdate {
+                old_oid: "0000000000000000000000000000000000000000".to_string(),
+                new_oid: "def456".to_string(),
+                ref_name: "refs/heads/test".to_string(),
+            },
+        ];
+
+        let local_refs = HashMap::new();
+
+        let diagnosis = diagnose_state_mismatch(&event, &pushed_updates, &local_refs);
+        assert!(diagnosis.is_some());
+        let msg = diagnosis.unwrap();
+        assert!(msg.contains("refs/heads/test"));
+        assert!(msg.contains("doesn't declare"));
+    }
+
+    #[test]
+    fn test_diagnose_state_mismatch_no_mismatch() {
+        // State declares main
+        let event = create_test_state_event("test-repo", vec![("refs/heads/main", "abc123")]);
+
+        // Push creates main at correct SHA
+        let pushed_updates = vec![RefUpdate {
+            old_oid: "0000000000000000000000000000000000000000".to_string(),
+            new_oid: "abc123".to_string(),
+            ref_name: "refs/heads/main".to_string(),
+        }];
+
+        let local_refs = HashMap::new();
+
+        let diagnosis = diagnose_state_mismatch(&event, &pushed_updates, &local_refs);
+        assert!(diagnosis.is_none()); // No mismatch
+    }
 }
diff --git a/src/purgatory/mod.rs b/src/purgatory/mod.rs
index 8094450..2c278f6 100644
--- a/src/purgatory/mod.rs
+++ b/src/purgatory/mod.rs
@@ -16,7 +16,7 @@ pub mod persistence;
 pub mod sync;
 mod types;
 
-pub use helpers::{can_apply_state, can_satisfy_state, extract_refs_from_state, get_unpushed_refs};
+pub use helpers::{can_apply_state, can_satisfy_state, diagnose_state_mismatch, extract_refs_from_state, get_unpushed_refs};
 pub use types::{EventSource, PrPurgatoryEntry, RefPair, RefUpdate, StatePurgatoryEntry};
 
 use dashmap::DashMap;