Merge pull request #171 from compoundingtech/fix/transition-companion-doctor

Treat the transition companion absence as healthy

Author: myobie

now.md

@@ -4,16 +4,16 @@ The living handoff for whoever owns fabric next (there was none before; keep thi
 current). This records what is DONE, what is IN FLIGHT, and what is NEXT — the
 things the repo history alone does not carry.
 
-_Last updated: 2026-09-04 by Silber.fabric-codex. Main is ahead of the fleet.
-Ask Silber.cos for the current fleet build. Do not cut or deploy a release
-without Silber.cos._
+_Last updated: 2026-09-05 by Silber.fabric-codex. Silber and hetz run Release A.
+Bluey was away and last reported the earlier fleet build. Ask Silber.cos before
+each release or deployment._
 
 For extraction steps 6 and 8, merge on green without asking for a separate
 Silber.cos approval. Silber.cos holds the step 7 activation gate and every
 release or deployment gate. Before any deployment, prove matched-pair rollback
 on hetz. macOS needs a detached update supervisor; the current change adds it.
 
-## Current main — 2026-09-04
+## Current main — 2026-09-05
 
 PR #154 made the current-connection fault class visible. PR #155 froze the
 sync-process extraction plan. PR #156 made `peers.toml` formatting stable.
@@ -46,7 +46,7 @@ PR #164 added a detached macOS update supervisor. PR #165 added pair-aware,
 fail-closed rollback. PR #166 made real launchd and systemd tests exercise that
 reader. All three changes are merged.
 
-The fleet build `0.2.1+48208e4` has only single-binary supervisor logic. The
+The pre-transition fleet build `0.2.1+48208e4` has only single-binary supervisor logic. The
 rollback runs this old binary on purpose because it is the machine's known-good
 copy. New rollback logic therefore cannot protect the release that introduces
 it.
@@ -79,7 +79,33 @@ exact status and manual recovery commands. PR #169 keeps expected companion
 absence silent on launchd and systemd. Step 7 restores paired archives after
 Release A reaches every machine.
 
-The local library suite passed 499 tests with five measurements ignored. The
+PR #170 set the operator-visible version boundary. Release A
+`v0.2.2+a2f8a73` is published from exact commit `a2f8a73`. Its three archives
+passed checksum and one-member checks. Each archive contains only `fabric`.
+
+Hetz and Silber now run `0.2.2+a2f8a73`. Hetz restarted through systemd and its
+detached supervisor confirmed the new version. A hetz-side observer sent 360
+pings to Silber over 451.5 seconds. No ping failed. The restart-crossing ping
+returned through the relay in 835 ms, so observed unreachability was zero.
+
+The same observer disproved the tentative sync-starvation explanation for slow
+pings. After both machines ran Release A, 24 of 341 pings exceeded one second,
+seven exceeded three seconds, and the maximum was 9.212 seconds. The connection
+stayed alive with zero attach failures. This remains unassigned work.
+
+The old running updater performs the transition install. It therefore prints
+the old premature `control-socket ready` line. On macOS, it also cannot schedule
+the detached supervisor that Release A first introduces. Bluey's instructions
+must tell Nathan to ignore that line, wait two minutes, and use manual recovery
+if the new version does not answer.
+
+Release A intentionally has no companion binary or service while embedded sync
+remains active. Doctor incorrectly reports both absences as problems and tells
+the operator to run `fabric service install`. This change makes that exact
+transition green. A present companion binary with a missing service remains a
+problem. An enabled service with a missing binary now asks for a matched pair.
+
+The local library suite passed 513 tests with five measurements ignored. The
 binary suite passed 19 tests, and the update contract passed eight tests. The
 five-second latency property measured 502 records, seven scans, a 10.001166 ms
 source maximum, and a 20.102959 ms delivery maximum. The explicit live-launchd

src/doctor.rs

@@ -152,6 +152,9 @@ pub struct Facts {
     /// unit file exists. Presence is not enablement.
     pub service: ServiceEnablement,
     pub sync_service: ServiceEnablement,
+    /// Whether the managed install path has a sibling `fabric-sync` binary.
+    /// `None` means the path could not be established.
+    pub sync_companion_binary: Option<bool>,
     pub sync_runtime: crate::control::SyncRuntimeStatus,
     pub own_version: String,
     pub peers: Vec<PeerFact>,
@@ -175,9 +178,19 @@ impl Facts {
     }
 }
 
+fn is_fabric_only_transition(facts: &Facts) -> bool {
+    facts.manages_service
+        && facts.daemon_running
+        && facts.sync_service == ServiceEnablement::NotInstalled
+        && facts.sync_companion_binary == Some(false)
+        && facts.sync_runtime.owner == "embedded"
+        && facts.sync_runtime.companion == "absent"
+}
+
 /// Turn facts into findings. Pure, so every outcome is testable.
 pub fn diagnose(facts: &Facts) -> Vec<Finding> {
     let fresh = facts.never_configured();
+    let fabric_only_transition = is_fabric_only_transition(facts);
     let mut out = Vec::new();
 
     out.push(if facts.has_identity {
@@ -239,29 +252,65 @@ pub fn diagnose(facts: &Facts) -> Vec<Finding> {
     });
 
     if facts.manages_service {
-        out.push(match facts.sync_service {
-            ServiceEnablement::Enabled => Finding::new(
+        out.push(if fabric_only_transition {
+            Finding::new(
                 "sync service",
                 Verdict::Ok,
-                "the sync companion is installed and enabled",
-            ),
-            ServiceEnablement::PresentNotEnabled => Finding::new(
-                "sync service",
-                if fresh { Verdict::Setup } else { Verdict::Problem },
-                "the sync companion is installed but not enabled",
-            )
-            .with_action("fabric service install"),
-            ServiceEnablement::NotInstalled => Finding::new(
-                "sync service",
-                if fresh { Verdict::Setup } else { Verdict::Problem },
-                "the sync companion service is absent",
+                "the fabric-only transition does not install a sync companion service",
             )
-            .with_action("fabric service install"),
-            ServiceEnablement::Unknown => Finding::new(
-                "sync service",
-                Verdict::Unknown,
-                "could not tell whether the sync companion is enabled",
-            ),
+        } else {
+            match (facts.sync_service, facts.sync_companion_binary) {
+                (ServiceEnablement::Enabled, Some(true)) => Finding::new(
+                    "sync service",
+                    Verdict::Ok,
+                    "the sync companion is installed and enabled",
+                ),
+                (ServiceEnablement::Enabled, Some(false)) => Finding::new(
+                    "sync service",
+                    Verdict::Problem,
+                    "the sync companion service is enabled, but its binary is absent",
+                )
+                .with_action("install a matched fabric and fabric-sync pair"),
+                (ServiceEnablement::Enabled, None) => Finding::new(
+                    "sync service",
+                    Verdict::Unknown,
+                    "could not verify the binary used by the sync companion service",
+                ),
+                (ServiceEnablement::PresentNotEnabled, Some(false)) => Finding::new(
+                    "sync service",
+                    if fresh { Verdict::Setup } else { Verdict::Problem },
+                    "the sync companion service is not enabled, and its binary is absent",
+                )
+                .with_action("install a matched fabric and fabric-sync pair"),
+                (ServiceEnablement::PresentNotEnabled, _) => Finding::new(
+                    "sync service",
+                    if fresh { Verdict::Setup } else { Verdict::Problem },
+                    "the sync companion is installed but not enabled",
+                )
+                .with_action("fabric service install"),
+                (ServiceEnablement::NotInstalled, Some(true)) => Finding::new(
+                    "sync service",
+                    if fresh { Verdict::Setup } else { Verdict::Problem },
+                    "the sync companion service is absent",
+                )
+                .with_action("fabric service install"),
+                (ServiceEnablement::NotInstalled, Some(false)) => Finding::new(
+                    "sync service",
+                    if fresh { Verdict::Setup } else { Verdict::Problem },
+                    "the sync companion binary and service are absent",
+                )
+                .with_action("install a matched fabric and fabric-sync pair"),
+                (ServiceEnablement::NotInstalled, None) => Finding::new(
+                    "sync service",
+                    Verdict::Unknown,
+                    "could not tell whether the absent sync service has a companion binary",
+                ),
+                (ServiceEnablement::Unknown, _) => Finding::new(
+                    "sync service",
+                    Verdict::Unknown,
+                    "could not tell whether the sync companion is enabled",
+                ),
+            }
         });
     }
 
@@ -272,16 +321,30 @@ pub fn diagnose(facts: &Facts) -> Vec<Finding> {
             "the sync runtime is unavailable",
         )
         .with_action("start the fabric daemon and sync companion")
-    } else if facts.manages_service && facts.sync_runtime.companion == "absent" {
+    } else if fabric_only_transition {
         Finding::new(
+            "sync runtime",
+            Verdict::Ok,
+            "embedded sync is active; this fabric-only transition has no companion",
+        )
+    } else if facts.manages_service && facts.sync_runtime.companion == "absent" {
+        let finding = Finding::new(
             "sync runtime",
             Verdict::Problem,
             format!(
                 "{} sync is active, but the supervised companion is absent",
                 facts.sync_runtime.owner
             ),
-        )
-        .with_action("fabric service install")
+        );
+        match facts.sync_companion_binary {
+            Some(true) => finding.with_action("fabric service install"),
+            Some(false) => finding.with_action("install a matched fabric and fabric-sync pair"),
+            None => Finding::new(
+                "sync runtime",
+                Verdict::Unknown,
+                "the sync companion is absent, and its binary could not be checked",
+            ),
+        }
     } else if facts.sync_runtime.companion == "incompatible" {
         Finding::new(
             "sync runtime",
@@ -739,6 +802,7 @@ mod tests {
             daemon_running: true,
             service: ServiceEnablement::Enabled,
             sync_service: ServiceEnablement::Enabled,
+            sync_companion_binary: Some(true),
             sync_runtime: crate::control::SyncRuntimeStatus {
                 owner: "embedded".to_string(),
                 companion: "standby".to_string(),
@@ -790,6 +854,82 @@ mod tests {
         assert!(opening(&configured()).is_none());
     }
 
+    #[test]
+    fn a_fabric_only_transition_does_not_offer_a_stranding_action() {
+        let mut facts = configured();
+        facts.sync_service = ServiceEnablement::NotInstalled;
+        facts.sync_companion_binary = Some(false);
+        facts.sync_runtime.companion = "absent".to_string();
+
+        let findings = diagnose(&facts);
+        for finding in find(&findings, "sync service")
+            .into_iter()
+            .chain(find(&findings, "sync runtime"))
+        {
+            assert_eq!(finding.verdict, Verdict::Ok, "wrong finding: {finding:?}");
+            assert!(
+                finding.action.is_none(),
+                "the transition offered an unsafe action: {finding:?}"
+            );
+        }
+        assert_eq!(exit_code(&findings), 0);
+    }
+
+    #[test]
+    fn a_paired_binary_without_its_service_stays_loud() {
+        let mut facts = configured();
+        facts.sync_service = ServiceEnablement::NotInstalled;
+        facts.sync_runtime.companion = "absent".to_string();
+
+        let findings = diagnose(&facts);
+        for finding in find(&findings, "sync service")
+            .into_iter()
+            .chain(find(&findings, "sync runtime"))
+        {
+            assert_eq!(finding.verdict, Verdict::Problem);
+            assert_eq!(finding.action.as_deref(), Some("fabric service install"));
+        }
+    }
+
+    #[test]
+    fn an_enabled_companion_service_without_its_binary_stays_loud() {
+        let mut facts = configured();
+        facts.sync_companion_binary = Some(false);
+        facts.sync_runtime.companion = "absent".to_string();
+
+        let findings = diagnose(&facts);
+        for finding in find(&findings, "sync service")
+            .into_iter()
+            .chain(find(&findings, "sync runtime"))
+        {
+            assert_eq!(finding.verdict, Verdict::Problem);
+            assert!(
+                finding
+                    .action
+                    .as_deref()
+                    .is_some_and(|action| action.contains("matched")),
+                "the missing binary got the wrong action: {finding:?}"
+            );
+            assert_ne!(finding.action.as_deref(), Some("fabric service install"));
+        }
+    }
+
+    #[test]
+    fn an_unknown_companion_binary_offers_no_action() {
+        let mut facts = configured();
+        facts.sync_companion_binary = None;
+        facts.sync_runtime.companion = "absent".to_string();
+
+        let findings = diagnose(&facts);
+        for finding in find(&findings, "sync service")
+            .into_iter()
+            .chain(find(&findings, "sync runtime"))
+        {
+            assert_eq!(finding.verdict, Verdict::Unknown);
+            assert!(finding.action.is_none(), "unknown state offered an action");
+        }
+    }
+
     #[test]
     fn a_peer_with_no_grants_is_an_actionable_problem() {
         let mut facts = configured();
@@ -820,6 +960,7 @@ mod tests {
             daemon_running: false,
             service: ServiceEnablement::NotInstalled,
             sync_service: ServiceEnablement::NotInstalled,
+            sync_companion_binary: Some(false),
             sync_runtime: crate::control::SyncRuntimeStatus {
                 owner: "unavailable".to_string(),
                 companion: "unknown".to_string(),
@@ -871,6 +1012,7 @@ mod tests {
             // what the gatherer sees.
             service: ServiceEnablement::Enabled,
             sync_service: ServiceEnablement::Enabled,
+            sync_companion_binary: Some(true),
             sync_runtime: crate::control::SyncRuntimeStatus {
                 owner: "unavailable".to_string(),
                 companion: "unknown".to_string(),
@@ -1438,6 +1580,10 @@ where
 
     let service = crate::service::service_enablement();
     let sync_service = crate::service::sync_service_enablement();
+    let sync_companion_binary = crate::update::managed_binary_path()
+        .and_then(|path| crate::update::companion_binary_path(&path))
+        .map(|path| path.exists())
+        .ok();
 
     let mut own_version = env!("CARGO_PKG_VERSION").to_string();
     let mut daemon_running = false;
@@ -1535,6 +1681,7 @@ where
         daemon_running,
         service,
         sync_service,
+        sync_companion_binary,
         sync_runtime,
         own_version,
         peers,