refactor(state-machine): proof-carrying Connected state + revocation bus skeleton (Phase 0)

Phase 0 of the Proof-Carrying Connected refactor (plan:
~/.claude/plans/iterative-roaming-aho.md). Zero behavior change — this ship
only adds the type-level scaffolding so later phases can land incrementally.

What ships here:

  * New `state_machine::verifier` module defining:
      - `ConnectedProof` struct (crate-private constructors `mint()` and
        `forced()`). Code outside `state_machine::verifier` cannot mint one.
      - `EvidenceKinds` bitflags (UI_SNAPSHOT, WINDOW_INVENTORY, EVENT_STREAM,
        TCP_PROBE, SUPERVISOR_ALIVE, FORCED).
      - `RevocationSource` enum with per-source `debounce()`, `next_state()`,
        and `tag()`.  JvmDied/ReloginDialog/SessionConflict fire immediately;
        ErrorDialog/WindowClassMorphed debounce 500ms; LoginFormVisible 1s;
        DisconnectedLabelStable 2s.
      - `RevocationTracker` with per-tag first-seen timestamps, `observe()`
        returning Some once debounce elapses, `clear()` / `clear_all()`.
      - `VerificationFailure` enum for Phase 2.
      - 10 unit tests covering tracker debounce semantics.

  * `State::Connected` → `State::Connected(ConnectedProof)`:
      - `Display` impl ignores the proof payload, preserving the external
        JSON contract (`"state":"Connected"`).
      - `State::from_name("Connected")` now produces a `forced` sentinel
        proof flagged with `EvidenceKinds::FORCED` for SETSTATE override.
      - Call-site updates: `matches!(state, State::Connected(_))` replaces
        `== State::Connected` in every semantic "is this Connected?" check
        (queries.rs, mod.rs:222/225/260/478, types.rs client_advisory).
      - The 3 current promotion sites (mod.rs:1157/1456/1593) pass a forced
        sentinel — these will route through `try_enter_connected()` in
        Phase 2.

  * `StateMachine` now owns a `RevocationTracker` field; `clear_all()` is
    called in `apply_transition()` whenever we leave the Connected family,
    so stale debounce timers from a prior session don't leak across.

Tests: 141 pass (was 131). Clippy clean. No production behavior change yet —
zion should still reach and hold Connected exactly as before. Phase 1 wires
the revocation tracker into do_connected for source-tagged demotion.

Author: Lcstyle

ibctl/Cargo.toml

@@ -18,6 +18,7 @@ toml = "0.8"
 futures-core = "0.3"
 secrecy = "0.10"
 jiff = "0.2"
+bitflags = "2"
 nix = { version = "0.30", features = ["signal", "process"] }
 
 [lints]

ibctl/src/state_machine/mod.rs

@@ -10,9 +10,12 @@
 mod queries;
 mod socat;
 mod types;
+mod verifier;
 
 // Re-export public API
 pub use types::{Channels, State, StateMachine, StateMachineError};
+#[allow(unused_imports)] // surfaced in later phases
+pub(super) use verifier::{ConnectedProof, EvidenceKinds, RevocationSource, RevocationTracker};
 
 use std::path::Path;
 use std::time::Instant;
@@ -216,11 +219,16 @@ impl StateMachine {
         self.state_entered_at = Instant::now();
         self.consecutive_agent_failures = 0;
 
-        if next == State::Connected && self.state != State::Connected {
+        let next_is_connected = matches!(next, State::Connected(_));
+        let curr_is_connected = matches!(self.state, State::Connected(_));
+        if next_is_connected && !curr_is_connected {
             self.connected_since = Some(Instant::now());
             self.relogin_attempts = 0;
-        } else if next != State::Connected {
+        } else if !next_is_connected {
             self.connected_since = None;
+            // Leaving Connected — reset per-source revocation debounce state
+            // so the next Connected session starts with a clean slate.
+            self.revocation.clear_all();
         }
 
         // Reset 2FA device state when starting a new login or 2FA cycle
@@ -254,7 +262,7 @@ impl StateMachine {
         // so window events may carry stale has_login_button=true during
         // the authentication animation.
         if matches!(next, State::DismissingPopups | State::WaitingFor2fa
-            | State::WaitingForApiReady | State::ConfiguringApi | State::Connected)
+            | State::WaitingForApiReady | State::ConfiguringApi | State::Connected(_))
         {
             self.observation.clear_login_buttons();
         }
@@ -475,7 +483,7 @@ impl StateMachine {
             State::DismissingPopups => self.do_dismiss_popups().await,
             State::WaitingForApiReady => self.do_wait_for_api_ready().await,
             State::ConfiguringApi => self.do_configure_api().await,
-            State::Connected => self.do_connected().await,
+            State::Connected(_) => self.do_connected().await,
             State::ReconnectingSession => self.do_reconnecting_session().await,
             State::Restarting => self.do_restart().await,
             State::WaitingForIB => self.do_waiting_for_ib().await,
@@ -1146,7 +1154,10 @@ impl StateMachine {
             Ok(()) => {
                 log::info!("API configuration complete");
                 self.config_retries = 0;
-                Ok(State::Connected)
+                // Phase 0: use forced sentinel so the enum-shape change is a
+                // no-op behavior change. Phase 2 replaces this with a real
+                // `try_enter_connected(...)` call backed by the verifier.
+                Ok(State::Connected(verifier::ConnectedProof::forced()))
             }
             Err(e) => {
                 // Close any menu left open by the failed attempt
@@ -1445,7 +1456,10 @@ impl StateMachine {
         // This sleep is now just a reconciliation tick — events handle the fast path.
 
         tokio::time::sleep(std::time::Duration::from_secs(10)).await;
-        Ok(State::Connected)
+        // Phase 0: stay-Connected self-return. Phase 1 will replace this path
+        // entirely — the revocation bus drives demotion; otherwise the existing
+        // proof is retained without re-verification.
+        Ok(State::Connected(verifier::ConnectedProof::forced()))
     }
 
     /// Single-step graduated session recovery.
@@ -1582,7 +1596,8 @@ impl StateMachine {
                 if confirmed_authenticated {
                     log::info!("RE-LOGIN: Gateway authenticated (positive confirmation)");
                     self.relogin_attempts = 0;
-                    return Ok(State::Connected);
+                    // Phase 0 sentinel — Phase 2 routes through verifier.
+                    return Ok(State::Connected(verifier::ConnectedProof::forced()));
                 }
 
                 // Inconclusive — stay in ReconnectingSession (retry next tick)
@@ -2452,7 +2467,7 @@ login_dialog_timeout_secs = 0
         };
 
         let mut sm = make_test_state_machine(mock);
-        sm.state = State::Connected;
+        sm.state = State::Connected(verifier::ConnectedProof::forced());
         // Position the liveness timer in the 30-second check window so the
         // periodic check actually fires this iteration.
         sm.state_entered_at = Instant::now() - Duration::from_secs(30);
@@ -2495,9 +2510,10 @@ login_dialog_timeout_secs = 0
         sm.state = State::ConfiguringApi;
 
         let result = sm.do_configure_api().await.expect("handler should not error");
-        assert_eq!(
-            result, State::Connected,
-            "no API settings configured ⇒ skip dialog ⇒ Connected (valid no-op path)"
+        assert!(
+            matches!(result, State::Connected(_)),
+            "no API settings configured ⇒ skip dialog ⇒ Connected (valid no-op path), got {:?}",
+            result
         );
     }
 
@@ -2516,7 +2532,7 @@ login_dialog_timeout_secs = 0
         };
 
         let mut sm = make_test_state_machine(mock);
-        sm.state = State::Connected;
+        sm.state = State::Connected(verifier::ConnectedProof::forced());
         sm.state_entered_at = Instant::now() - Duration::from_secs(30);
         sm.connected_window_class = Some("ibgateway.ay".to_string());
         sm.observation.synced = true;
@@ -2525,9 +2541,11 @@ login_dialog_timeout_secs = 0
         let result = sm.do_connected().await.expect("handler should not error");
 
         // Assert: no transition — stays Connected (handler returns next state to loop back).
-        assert_eq!(
-            result, State::Connected,
-            "healthy Connected state must not self-transition just because a liveness tick fired"
+        // Uses matches! rather than assert_eq! because proof instances differ by issued_at.
+        assert!(
+            matches!(result, State::Connected(_)),
+            "healthy Connected state must not self-transition just because a liveness tick fired, got {:?}",
+            result
         );
     }
 }

ibctl/src/state_machine/queries.rs

@@ -90,7 +90,7 @@ impl StateMachine {
             .unwrap_or(false);
         let socat_pid = self.socat_process.as_ref().map(|c| c.id());
 
-        let is_connected = self.state == State::Connected;
+        let is_connected = matches!(self.state, State::Connected(_));
         let (should_connect, should_wait, wait_reason, client_id_likely_stale) =
             client_advisory(&self.state);
 

ibctl/src/state_machine/types.rs

@@ -15,6 +15,8 @@ use crate::handlers::DialogHandlerRegistry;
 use crate::types::Signal;
 use crate::supervisor::Supervisor;
 
+use super::verifier::{ConnectedProof, RevocationTracker};
+
 #[derive(Debug, Error)]
 pub enum StateMachineError {
     #[error("supervisor error: {0}")]
@@ -52,8 +54,14 @@ pub enum State {
     WaitingForApiReady,
     /// Applying post-login API configuration (master client ID, read-only, etc.)
     ConfiguringApi,
-    /// Fully connected and monitoring for new dialogs
-    Connected,
+    /// Fully connected and monitoring for new dialogs.
+    ///
+    /// The `ConnectedProof` payload is the verifier's evidence that Gateway
+    /// is actually ready. It can only be constructed via `verifier::mint()`
+    /// or `verifier::forced()` (for SETSTATE debug override). No handler can
+    /// accidentally return `Ok(State::Connected(...))` without going through
+    /// the verifier — see `state_machine::verifier` module docs.
+    Connected(ConnectedProof),
     /// Recovering from connection loss — graduated re-login flow.
     /// Waits 30s, clicks Re-login, tracks attempts. If failed, restarts JVM.
     ReconnectingSession,
@@ -82,7 +90,11 @@ impl State {
             "DismissingPopups" => Some(State::DismissingPopups),
             "WaitingForApiReady" => Some(State::WaitingForApiReady),
             "ConfiguringApi" => Some(State::ConfiguringApi),
-            "Connected" => Some(State::Connected),
+            // SETSTATE Connected produces a synthetic "forced" proof.
+            // This is a debug-override path — operators should see the
+            // `evidence=[forced]` marker in logs and STATUS JSON so they can
+            // tell a forced Connected apart from a verifier-minted one.
+            "Connected" => Some(State::Connected(ConnectedProof::forced())),
             "ReconnectingSession" => Some(State::ReconnectingSession),
             "Restarting" => Some(State::Restarting),
             "WaitingForIB" => Some(State::WaitingForIB),
@@ -96,6 +108,10 @@ impl std::fmt::Display for State {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             State::Error(msg) => write!(f, "Error({})", msg),
+            // Display ignores the proof payload to preserve external JSON
+            // contract: STATUS still reports `"state":"Connected"`. Proof
+            // provenance is exposed via a separate `proof` field (Phase 3).
+            State::Connected(_) => write!(f, "Connected"),
             other => write!(f, "{:?}", other),
         }
     }
@@ -237,6 +253,12 @@ pub struct StateMachine {
     pub(super) snapshot_tx: watch::Sender<Arc<QuerySnapshot>>,
     /// Monotonic version counter for snapshots.
     pub(super) snapshot_version: u64,
+    /// Source-tagged revocation bus for `Connected` state. Tracks per-source
+    /// debounce timers for contradictions (login form reappears, "disconnected"
+    /// label stabilizes, window class morph, etc.). See `verifier::RevocationSource`.
+    /// Used by `do_connected` to decide when a contradiction has persisted
+    /// long enough to revoke the proof and transition out.
+    pub(super) revocation: RevocationTracker,
 }
 
 impl StateMachine {
@@ -282,6 +304,7 @@ impl StateMachine {
             stats: Stats::default(),
             snapshot_tx,
             snapshot_version: 0,
+            revocation: RevocationTracker::new(),
         }
     }
 
@@ -311,7 +334,7 @@ pub(crate) fn client_advisory(state: &State) -> (bool, bool, Option<&'static str
         State::WaitingFor2fa => (false, true, Some("2fa_pending")),
         State::HandlingSessionConflict => (false, true, Some("session_conflict")),
         State::DismissingPopups | State::WaitingForApiReady | State::ConfiguringApi => (false, true, Some("configuring")),
-        State::Connected => (true, false, None),
+        State::Connected(_) => (true, false, None),
         State::ReconnectingSession => (false, true, Some("reconnecting")),
         State::Restarting => (false, true, Some("restarting")),
         State::WaitingForIB => (false, true, Some("ib_maintenance")),
@@ -337,7 +360,8 @@ mod tests {
 
     #[test]
     fn test_connected_should_connect() {
-        let (should_connect, should_wait, reason, stale) = client_advisory(&State::Connected);
+        let (should_connect, should_wait, reason, stale) =
+            client_advisory(&State::Connected(ConnectedProof::forced()));
         assert!(should_connect);
         assert!(!should_wait);
         assert!(reason.is_none());
@@ -406,12 +430,13 @@ mod tests {
             State::WaitingForLogin, State::Authenticating,
             State::WaitingFor2fa, State::HandlingSessionConflict,
             State::DismissingPopups, State::ConfiguringApi,
-            State::Connected, State::Restarting, State::Shutdown,
+            State::Connected(ConnectedProof::forced()),
+            State::Restarting, State::Shutdown,
             State::Error("test".into()),
         ];
         for state in &states {
             let (sc, sw, _, _) = client_advisory(state);
-            if matches!(state, State::Connected) {
+            if matches!(state, State::Connected(_)) {
                 assert!(sc, "Connected should allow connect");
                 assert!(!sw, "Connected should not wait");
             }
@@ -421,7 +446,11 @@ mod tests {
     #[test]
     fn test_state_display() {
         assert_eq!(State::Init.to_string(), "Init");
-        assert_eq!(State::Connected.to_string(), "Connected");
+        assert_eq!(
+            State::Connected(ConnectedProof::forced()).to_string(),
+            "Connected",
+            "Display must ignore the proof payload to preserve JSON contract"
+        );
         assert_eq!(State::WaitingFor2fa.to_string(), "WaitingFor2fa");
         assert_eq!(State::Error("boom".into()).to_string(), "Error(boom)");
     }