fix(home): a stored canonical pointer to a retired Home must stop governing (#449)

Independent review r3 of 413028e: the remaining P2 was only half-fixed.
Filtering withdrawn groups in `DaemonView::home_pointer` stops FUTURE
publication, but the prior `(HomePointer, "home")` record stays in
`OwnerSyncStore`. Reconciliation does nothing when the view returns `None`,
tombstone retention never clears owner-sync state, and `canonical_home`
returns the stored value without consulting the locally known tombstone.

So the real lifecycle — advertise, withdraw, then reconcile/restart — left the
device yielding to a dead pointer forever: `provision_home` hit the suppression
branch and returned instead of creating a usable replacement, and `GET /home`
reported `elsewhere` for a group that no longer exists. Permanently, across
restarts. The previous test could not detect this: it inserted an
already-withdrawn group into an EMPTY store, so no stored pointer ever governed.

Fixed on BOTH sides, keyed on the same proof.

Proof of retirement is LOCAL: the group is in our own roster AND carries the
terminal `withdrawn` flag. Inability to see the group is deliberately NOT
proof — a canonical Home on an unreachable device is unknown, not retired, and
treating unknown as retired would let any partitioned device mint over the
owner's real Home and refork the space this issue exists to unify.

- Consumer: new `effective_canonical_home()` backs BOTH `resolve_home` and
  `provision_home`, so a provably retired pointer stops governing.
- Producer: `home_pointer_mint_decision` gained a `stored_is_retired`
  override, fed by the new `SyncDaemonView::canonical_pointer_is_retired`.
  Without this the fix is still broken: the ordering rule refuses EVERY
  replacement, because a replacement Home is always NEWER than the dead one
  it replaces, so the register would keep naming a tombstone forever.

`canonical_pointer_is_retired` fails safe on a contended roster lock (answers
`false`), so a busy daemon never mints over a live canonical Home.

Regressions:
- `a_retired_advertised_home_does_not_suppress_its_replacement` — the real
  lifecycle: advertise, withdraw, reconcile/restart, assert a NEW usable Home
  is provisioned. Verified to FAIL against pre-fix behaviour before being kept
  ("a pointer to a Home we hold and know to be retired must stop governing").
- `an_unreachable_remote_home_is_never_treated_as_retired` — a Home we merely
  cannot see keeps governing, and we still yield rather than fork.
- `a_provably_retired_pointer_can_be_replaced_by_a_newer_home` — and, without
  proof, the ordering rule still stands.

Gates on this exact tree, separate commands, actual exits:
  cargo fmt --all                                                     -> 0
  cargo clippy --all-features --all-targets -- -D warnings            -> 0
  cargo clippy --all-features --lib --bins -- -D warnings
      -D clippy::panic -D clippy::unwrap_used -D clippy::expect_used  -> 0
  cargo check --workspace --all-targets                               -> 0
  RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps       -> 0
  cargo nextest run --workspace --all-features --no-fail-fast         -> 0
      (3322 passed, 0 failed, 295 skipped)

One earlier run of the same tree failed
`inbound_redial_of_suppressed_peer_emits_no_peer_connected` at
`.expect("alice connects bob")` — a QUIC dial under full-suite load, the #316
family. Neither agent in that test is built `with_user_key`, so `owner_sync` is
never constructed and every line changed here sits behind an owner-keypair
guard; it also passes in isolation (2.3s) and the re-run above is green. Not
attributed to this diff and not claimed resolved.

#449 remains partial and open: no adoption, no retirement, enrolled devices
only.

Refs #449

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017ovKUXBeg5GZ51YECS9p51

Author: dirvine

src/owner_sync.rs

@@ -1899,6 +1899,7 @@ fn home_pointer_mint_decision(
     desired: &SyncValue,
     stored: Option<&SyncValue>,
     local_agent_hex: &str,
+    stored_is_retired: bool,
 ) -> bool {
     let SyncValue::HomePointer {
         group_id: desired_id,
@@ -1922,6 +1923,14 @@ fn home_pointer_mint_decision(
         return true; // defensively: a foreign kind is not a Home winner
     };
 
+    // r3 P2: the slot is held by a Home we can PROVE is retired. Take it —
+    // the ordering rule below would otherwise refuse, because a replacement
+    // Home is always newer than the dead one, leaving every device yielding
+    // to a tombstone forever.
+    if stored_is_retired && desired_id != stored_id {
+        return true;
+    }
+
     if desired_id == stored_id {
         // Single-writer refresh: only the Home's designated primary agent,
         // and only when the value actually changed. `mint` would no-op on an
@@ -1977,6 +1986,14 @@ pub trait SyncDaemonView: Send + Sync + 'static {
         display_name: Option<String>,
         machine_name: Option<String>,
     );
+    /// Whether `group_id` is a Home this device can PROVE is retired (r3 P2).
+    ///
+    /// Proof is local: the group is in our roster and carries the terminal
+    /// `withdrawn` flag. Inability to see the group is NOT proof — a Home on
+    /// an unreachable device is unknown, and treating unknown as retired
+    /// would let a partitioned device mint over the owner's real Home.
+    /// Implementations MUST be non-blocking and answer `false` when unsure.
+    fn canonical_pointer_is_retired(&self, group_id: &str) -> bool;
 }
 
 /// Current daemon self-profile names, best-effort snapshot.
@@ -2399,10 +2416,21 @@ impl OwnerSyncService {
             .store
             .stored_value(SyncKind::HomePointer, HOME_POINTER_KEY)
             .await;
+        // r3 P2: a stored pointer naming a Home we hold and know to be
+        // retired must not keep the slot. Without this the ordering rule
+        // would refuse every replacement, since a new Home is always NEWER
+        // than the dead one it replaces.
+        let stored_is_retired = match (&stored, self.view()) {
+            (Some(SyncValue::HomePointer { group_id, .. }), Some(view)) => {
+                view.canonical_pointer_is_retired(group_id)
+            }
+            _ => false,
+        };
         home_pointer_mint_decision(
             desired,
             stored.as_ref(),
             &hex::encode(self.agent.agent_id().as_bytes()),
+            stored_is_retired,
         )
     }
 
@@ -3908,7 +3936,7 @@ mod home_pointer_election_tests {
         for _ in 0..10 {
             let mut mints = 0;
             for (agent_hex, desired) in &devices {
-                if home_pointer_mint_decision(desired, register.as_ref(), agent_hex) {
+                if home_pointer_mint_decision(desired, register.as_ref(), agent_hex, false) {
                     register = Some(desired.clone());
                     mints += 1;
                 }
@@ -3940,9 +3968,19 @@ mod home_pointer_election_tests {
         let newer = home_ptr("g-aaa", "agent-b", 2_000, vec![]);
 
         // Newer already in the slot: the older device takes it.
-        assert!(home_pointer_mint_decision(&older, Some(&newer), "agent-a"));
+        assert!(home_pointer_mint_decision(
+            &older,
+            Some(&newer),
+            "agent-a",
+            false
+        ));
         // Older already in the slot: the newer device yields.
-        assert!(!home_pointer_mint_decision(&newer, Some(&older), "agent-b"));
+        assert!(!home_pointer_mint_decision(
+            &newer,
+            Some(&older),
+            "agent-b",
+            false
+        ));
     }
 
     /// Equal `provisioned_at_ms` — a genuine simultaneous genesis, or just
@@ -3952,8 +3990,31 @@ mod home_pointer_election_tests {
     fn home_pointer_election_breaks_timestamp_ties_on_group_id() {
         let a = home_ptr("g-aaa", "agent-a", 5_000, vec![]);
         let b = home_ptr("g-bbb", "agent-b", 5_000, vec![]);
-        assert!(home_pointer_mint_decision(&a, Some(&b), "agent-a"));
-        assert!(!home_pointer_mint_decision(&b, Some(&a), "agent-b"));
+        assert!(home_pointer_mint_decision(&a, Some(&b), "agent-a", false));
+        assert!(!home_pointer_mint_decision(&b, Some(&a), "agent-b", false));
+    }
+
+    /// A slot held by a PROVABLY retired Home must be takeable (r3 P2).
+    ///
+    /// The ordering rule alone refuses every replacement here, because a new
+    /// Home is always NEWER than the dead one it replaces — so without this
+    /// override the register keeps naming a tombstone forever and every
+    /// device yields to it. The proof is local (`withdrawn` in our own
+    /// roster); an unreachable remote Home is unknown, not retired, and must
+    /// NOT be overridden.
+    #[test]
+    fn a_provably_retired_pointer_can_be_replaced_by_a_newer_home() {
+        let retired = home_ptr("g-old", "agent-a", 1_000, vec![]);
+        let replacement = home_ptr("g-new", "agent-a", 9_999, vec![]);
+
+        assert!(
+            !home_pointer_mint_decision(&replacement, Some(&retired), "agent-a", false),
+            "without proof of retirement the ordering rule stands: a newer Home does not win"
+        );
+        assert!(
+            home_pointer_mint_decision(&replacement, Some(&retired), "agent-a", true),
+            "a provably retired pointer must be replaceable despite being older"
+        );
     }
 
     /// The owner's first device must publish: an empty register is not a
@@ -3963,7 +4024,8 @@ mod home_pointer_election_tests {
         assert!(home_pointer_mint_decision(
             &home_ptr("g-aaa", "agent-a", 1, vec![]),
             None,
-            "agent-a"
+            "agent-a",
+            false
         ));
     }
 
@@ -3985,11 +4047,11 @@ mod home_pointer_election_tests {
             }],
         );
         assert!(
-            home_pointer_mint_decision(&refreshed, Some(&stored), "agent-a"),
+            home_pointer_mint_decision(&refreshed, Some(&stored), "agent-a", false),
             "the primary agent must be able to refresh its own Home pointer"
         );
         assert!(
-            !home_pointer_mint_decision(&refreshed, Some(&stored), "agent-b"),
+            !home_pointer_mint_decision(&refreshed, Some(&stored), "agent-b", false),
             "a co-member must not refresh the primary's Home pointer"
         );
     }

src/server/routes/home.rs

@@ -101,16 +101,50 @@ pub(in crate::server) enum HomeResolution {
 /// The canonical Home is the Tier-1 `("home")` register winner. Absence of a
 /// register value means "no owner device has advertised one yet" — NOT "none
 /// exists" — so an un-synced device with its own Home still reports `Local`.
+/// Whether `group_id` is a Home this device can PROVE is retired (r3 P2).
+///
+/// Proof means: the group is in our own roster and carries the terminal
+/// `withdrawn` flag. Not being able to see the group is deliberately NOT
+/// proof — a canonical Home living on an unreachable device is simply
+/// unknown, and treating unknown as retired would let any partitioned device
+/// mint over the owner's real Home.
+async fn is_provably_retired(state: &Arc<AppState>, group_id: &str) -> bool {
+    state.named_groups.read().await.iter().any(|(id, info)| {
+        (id.as_str() == group_id || info.stable_group_id() == group_id) && info.withdrawn
+    })
+}
+
+/// The canonical Home pointer that should actually govern this device (r3 P2).
+///
+/// The stored `("home")` record survives the withdrawal of the Home it names —
+/// tombstone retention never touches owner-sync state — so a device that
+/// retires its own advertised Home would otherwise keep yielding to the dead
+/// pointer forever and never build a replacement. Filtering the PUBLISHER was
+/// only half the fix; the stored record has to stop governing too.
+pub(in crate::server) async fn effective_canonical_home(state: &Arc<AppState>) -> Option<String> {
+    let canonical = state
+        .owner_sync
+        .as_ref()?
+        .canonical_home()
+        .await
+        .map(|home| home.group_id)?;
+    if is_provably_retired(state, &canonical).await {
+        tracing::info!(
+            group_id = %canonical,
+            "canonical Home pointer names a group we hold and know to be retired; ignoring it (#449)"
+        );
+        return None;
+    }
+    Some(canonical)
+}
+
 pub(in crate::server) async fn resolve_home(state: &Arc<AppState>) -> HomeResolution {
     let Some(user_kp) = state.agent.identity().user_keypair() else {
         return HomeResolution::Unknown;
     };
     let owner = user_kp.user_id();
     let local = find_home(state.as_ref(), &owner).await;
-    let canonical = match state.owner_sync.as_ref() {
-        Some(sync) => sync.canonical_home().await.map(|home| home.group_id),
-        None => None,
-    };
+    let canonical = effective_canonical_home(state).await;
     // Prefer the CANONICAL Home whenever we are already seated in it. After
     // adoption a device is briefly seated in both its old duplicate and the
     // canonical Home; without this, `find_home`'s smallest-id rule could
@@ -625,14 +659,15 @@ pub(in crate::server) async fn provision_home(state: &Arc<AppState>) {
     //    Absence of a register value means "nobody has advertised one yet",
     //    NOT "none exists", so an un-synced or first device still provisions
     //    optimistically — that is what keeps an offline install usable.
-    if let Some(sync) = state.owner_sync.as_ref() {
-        if let Some(canonical) = sync.canonical_home().await {
-            tracing::info!(
-                canonical_group_id = %canonical.group_id,
-                "owner's Home is advertised by another device; not provisioning a duplicate (#449)"
-            );
-            return;
-        }
+    //    A pointer naming a Home we hold and know to be RETIRED does not
+    //    count (r3 P2): the stored record outlives the group it names, so
+    //    yielding to it would leave this device permanently without a Home.
+    if let Some(canonical) = effective_canonical_home(state).await {
+        tracing::info!(
+            canonical_group_id = %canonical,
+            "owner's Home is advertised by another device; not provisioning a duplicate (#449)"
+        );
+        return;
     }
 
     // 4) Fresh provisioning through the full creation path.
@@ -1211,6 +1246,90 @@ pub(in crate::server::routes) mod tests {
         Ok(())
     }
 
+    /// WHY (r3 P2): the REAL lifecycle — advertise, then withdraw, then
+    /// reconcile/restart. This is the case the earlier test could not reach,
+    /// because it only inserted an already-withdrawn group into an EMPTY
+    /// store.
+    ///
+    /// Tombstone retention never clears owner-sync state, so the stored
+    /// `("home")` record outlives the Home it names. Filtering the publisher
+    /// stops future advertisements but leaves the old record governing: the
+    /// device yields to a dead pointer, provisions no replacement, and
+    /// `GET /home` reports `elsewhere` for a group that no longer exists —
+    /// permanently, across restarts.
+    #[tokio::test]
+    async fn a_retired_advertised_home_does_not_suppress_its_replacement() -> anyhow::Result<()> {
+        let dir = tempfile::tempdir()?;
+        let state = owned_state(dir.path(), [0x5D; 32]).await?;
+        let owner = owner_of(&state);
+
+        // 1. Advertise our real Home, exactly as a live device would.
+        provision_home(&state).await;
+        let (advertised, _) = find_home(&state, &owner).await.expect("Home provisioned");
+        advertise_canonical_home(&state, &advertised).await;
+
+        // 2. Retire it. The stored pointer still names it.
+        state
+            .named_groups
+            .write()
+            .await
+            .get_mut(&advertised)
+            .expect("advertised Home")
+            .withdrawn = true;
+        assert_eq!(
+            state
+                .owner_sync
+                .as_ref()
+                .expect("sync")
+                .canonical_home()
+                .await
+                .map(|home| home.group_id)
+                .as_deref(),
+            Some(advertised.as_str()),
+            "precondition: the retired Home is still the stored canonical pointer"
+        );
+
+        // 3. Reconcile / restart.
+        assert!(
+            effective_canonical_home(&state).await.is_none(),
+            "a pointer to a Home we hold and know to be retired must stop governing"
+        );
+        provision_home(&state).await;
+
+        let (replacement, info) = find_home(&state, &owner)
+            .await
+            .expect("a usable replacement Home must be provisioned");
+        assert_ne!(replacement, advertised, "the replacement is a NEW Home");
+        assert!(!info.withdrawn);
+        Ok(())
+    }
+
+    /// WHY (r3 P2): proof of retirement is LOCAL, and absence of knowledge is
+    /// not proof. A canonical Home living on a device we cannot currently
+    /// reach is unknown, not retired — clearing it would let any partitioned
+    /// device mint over the owner's real Home and refork the space this whole
+    /// issue exists to unify.
+    #[tokio::test]
+    async fn an_unreachable_remote_home_is_never_treated_as_retired() -> anyhow::Result<()> {
+        let dir = tempfile::tempdir()?;
+        let state = owned_state(dir.path(), [0x5E; 32]).await?;
+        let remote = "ac".repeat(16);
+        advertise_canonical_home(&state, &remote).await;
+
+        assert_eq!(
+            effective_canonical_home(&state).await.as_deref(),
+            Some(remote.as_str()),
+            "a Home we simply cannot see must keep governing — unknown is not retired"
+        );
+
+        provision_home(&state).await;
+        assert!(
+            find_home(&state, &owner_of(&state)).await.is_none(),
+            "we must still yield to an unreachable canonical Home, not fork a new one"
+        );
+        Ok(())
+    }
+
     /// WHY (#449 D5): withdrawal keeps `members_v2` and `home` populated, so
     /// without an explicit filter a RETIRED Home still resolves here — which
     /// would make `GET /home` serve a tombstone and `provision_home` return

src/server/routes/sync.rs

@@ -136,6 +136,17 @@ impl SyncDaemonView for DaemonView {
             })
     }
 
+    fn canonical_pointer_is_retired(&self, group_id: &str) -> bool {
+        // Fail SAFE when the roster lock is contended: "unsure" must answer
+        // false, so a busy daemon never mints over a live canonical Home.
+        let Ok(groups) = self.state.named_groups.try_read() else {
+            return false;
+        };
+        groups.iter().any(|(id, info)| {
+            (id.as_str() == group_id || info.stable_group_id() == group_id) && info.withdrawn
+        })
+    }
+
     fn apply_names(
         &self,
         human_name: Option<String>,