feat(config+session): M18.2 — plumb ConnectTimeout/ConnectionAttempts; wrap connect with retry (FR-80) (#29)

Closes the M12.6 ConnectTimeout / ConnectionAttempts deferral loop.
The primary `AnvilSession::connect` path now retries transient TCP
failures with jittered exponential backoff per the M18.1 retry
module; per-attempt connect timeouts wrap russh's `client::connect`
in `tokio::time::timeout` when configured.

src/config.rs:

- AnvilConfig: three new public fields:
    connect_timeout: Option<Duration>
    connection_attempts: Option<u32>
    max_retry_window: Option<Duration>
  Each None falls through to retry::RetryPolicy::default() at
  session-build time.

- AnvilConfigBuilder: matching three setters.  CLI applies them
  AFTER apply_ssh_config so flags beat config (matches OpenSSH
  precedence).

- apply_ssh_config: now consumes resolved.connect_timeout and
  resolved.connection_attempts, but only if the builder field is
  still None (preserves CLI-wins precedence).  max_retry_window
  is CLI-only — not in OpenSSH's grammar.

- warn_unhonored_directives helper REMOVED.  Every ssh_config(5)
  directive Anvil's resolver parses today is now consumed:
  HostKeyAlgorithms / KexAlgorithms / Ciphers / MACs landed in
  M17; ConnectTimeout / ConnectionAttempts in M18.

src/session.rs:

- AnvilSession: new private field `retry_history:
  Vec<RetryAttempt>` capturing per-attempt failures during the
  connect path.  Surfaced via the new
  pub fn AnvilSession::retry_history(&self) -> &[RetryAttempt]
  accessor for `gitway --test --json`'s data.retry_attempts
  envelope (FR-83).  Empty when first attempt succeeded.

- connect(): wrapped in retry::run.  Each attempt:
    1. Build fresh HandlerPieces (russh consumes the handler).
    2. Call client::connect(...), wrapped in tokio::time::timeout
       when policy.connect_timeout is Some.  Elapsed → mapped to
       AnvilErrorKind::Io(io::ErrorKind::TimedOut) which the
       FR-82 classifier treats as Retry.
    3. Return (handle, ConnectArtifacts).
  Retry history flows from retry::run into the AnvilSession
  field.  Auth / host-key / protocol errors are fatal per FR-82
  and surface immediately without retry.

- New private struct ConnectArtifacts and helper
  retry_policy_from_config(config) extracted to keep the closure
  signature concise.

- connect_via_proxy_command and connect_via_jump_hosts (final
  hop + per-hop) construct AnvilSession with retry_history:
  Vec::new() for now.  The plan PR body documents this
  scope-narrowing: the ProxyCommand subprocess lifecycle and
  per-hop direct-tcpip channels make retry semantics murkier
  than the primary path; deferred to a follow-up sub-milestone.
  FR-80..FR-83 are met for `gitway --test` against a direct
  target host today; the proxy / jump paths fall back to the
  pre-M18 single-attempt behaviour and surface the same opaque
  IO error they did before.

Public API: pure additive (three new pub fields on AnvilConfig +
three new builder setters + new retry_history accessor).
build_russh_config signature unchanged.

207 lib tests + integration tests still pass.

Plan: M18.2 of anvil-gitway-milestone-plan.md.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

src/config.rs

@@ -108,6 +108,19 @@ pub struct AnvilConfig {
     /// Host-key algorithm preference (PRD §5.8.6 FR-76).  `None` →
     /// curated default.
     pub host_key_algorithms: Option<Vec<String>>,
+    /// Per-attempt TCP connect timeout (PRD §5.8.7 FR-80).  `None`
+    /// disables the timeout (matches OpenSSH's "no `ConnectTimeout`"
+    /// semantics).
+    pub connect_timeout: Option<Duration>,
+    /// Total number of connection attempts including the initial one
+    /// (PRD §5.8.7 FR-80).  `None` selects the curated default
+    /// ([`crate::retry::RetryPolicy`]'s `attempts = 3`).
+    pub connection_attempts: Option<u32>,
+    /// Hard ceiling on total elapsed wall-clock time across all
+    /// retry attempts (PRD §5.8.7 FR-81).  `None` selects the
+    /// curated default (30 s).  CLI-only — not part of OpenSSH's
+    /// `ssh_config(5)` grammar.
+    pub max_retry_window: Option<Duration>,
 }
 
 impl AnvilConfig {
@@ -191,6 +204,9 @@ pub struct AnvilConfigBuilder {
     ciphers: Option<Vec<String>>,
     macs: Option<Vec<String>>,
     host_key_algorithms: Option<Vec<String>>,
+    connect_timeout: Option<Duration>,
+    connection_attempts: Option<u32>,
+    max_retry_window: Option<Duration>,
 }
 
 impl AnvilConfigBuilder {
@@ -219,6 +235,15 @@ impl AnvilConfigBuilder {
             ciphers: None,
             macs: None,
             host_key_algorithms: None,
+            // Retry / timeout knobs default to None.  At session
+            // build time, None falls through to
+            // `crate::retry::RetryPolicy::default()` (3 attempts,
+            // 250 ms base, 30 s max_window, no connect timeout) —
+            // matches OpenSSH's defaults except for the new
+            // max_window cap which is Gitway-specific.
+            connect_timeout: None,
+            connection_attempts: None,
+            max_retry_window: None,
         }
     }
 
@@ -351,6 +376,30 @@ impl AnvilConfigBuilder {
         self
     }
 
+    /// Override the per-attempt TCP connect timeout (PRD §5.8.7
+    /// FR-80).  `None` disables the timeout.  CLI overrides this
+    /// AFTER `apply_ssh_config` so flags beat config (matches
+    /// OpenSSH precedence).
+    pub fn connect_timeout(mut self, timeout: Option<Duration>) -> Self {
+        self.connect_timeout = timeout;
+        self
+    }
+
+    /// Override the total connection-attempt count (PRD §5.8.7
+    /// FR-80).  `None` selects the curated default (3).
+    pub fn connection_attempts(mut self, attempts: Option<u32>) -> Self {
+        self.connection_attempts = attempts;
+        self
+    }
+
+    /// Override the wall-clock cap on total retry time (PRD
+    /// §5.8.7 FR-81).  `None` selects the curated default (30 s).
+    /// Not part of OpenSSH's `ssh_config(5)` grammar — CLI-only.
+    pub fn max_retry_window(mut self, window: Option<Duration>) -> Self {
+        self.max_retry_window = window;
+        self
+    }
+
     /// Layer values from a [`ResolvedSshConfig`] into this builder.
     ///
     /// Provides ssh_config-derived defaults that subsequent builder calls
@@ -432,7 +481,23 @@ impl AnvilConfigBuilder {
             crate::algorithms::anvil_default_host_keys,
             |b, v| b.host_key_algorithms = Some(v),
         );
-        warn_unhonored_directives(resolved);
+
+        // M18 / FR-80: ConnectTimeout + ConnectionAttempts from
+        // ssh_config flow through to the retry-policy fields.  CLI
+        // overrides applied AFTER apply_ssh_config win over these
+        // (matches OpenSSH precedence).  Don't clobber a value
+        // already set on the builder — that's how the CLI-wins
+        // precedence is achieved.
+        if self.connect_timeout.is_none() {
+            if let Some(d) = resolved.connect_timeout {
+                self.connect_timeout = Some(d);
+            }
+        }
+        if self.connection_attempts.is_none() {
+            if let Some(n) = resolved.connection_attempts {
+                self.connection_attempts = Some(n);
+            }
+        }
         self
     }
 
@@ -484,40 +549,20 @@ impl AnvilConfigBuilder {
             ciphers: self.ciphers,
             macs: self.macs,
             host_key_algorithms: self.host_key_algorithms,
+            connect_timeout: self.connect_timeout,
+            connection_attempts: self.connection_attempts,
+            max_retry_window: self.max_retry_window,
         }
     }
 }
 
-/// Emits a single `log::warn!` listing any directives in `resolved` that
-/// the resolver successfully parsed but Anvil does not yet honor.  Called
-/// from [`AnvilConfigBuilder::apply_ssh_config`] so the warning fires
-/// when a config is actually being prepared for connection — `gitway
-/// config show` and similar inspection callers do not trigger it.
-///
-/// The remaining unhonored set after M17:
-/// - `ConnectTimeout`, `ConnectionAttempts` — parsed but not yet wired
-///   into `connect()`.  M18 honors them.
-///
-/// `HostKeyAlgorithms` / `KexAlgorithms` / `Ciphers` / `MACs` were
-/// the M17 deferral; they're now consumed by `apply_ssh_config` via
-/// the `apply_alg_directive` helper above.
-fn warn_unhonored_directives(resolved: &ResolvedSshConfig) {
-    let mut m18: Vec<&'static str> = Vec::new();
-    if resolved.connect_timeout.is_some() {
-        m18.push("ConnectTimeout");
-    }
-    if resolved.connection_attempts.is_some() {
-        m18.push("ConnectionAttempts");
-    }
-
-    if !m18.is_empty() {
-        log::warn!(
-            "ssh_config: directive(s) {} parsed but not yet honored \
-             (landing in M18 — Gitway PRD §8)",
-            m18.join(", "),
-        );
-    }
-}
+// Note: the `warn_unhonored_directives` helper that lived here from
+// M12.6 → M17.2 → M18.2 was removed in M18.2.  Every `ssh_config(5)`
+// directive Anvil's resolver parses today is now consumed by
+// `apply_ssh_config` (HostKeyAlgorithms / KexAlgorithms / Ciphers /
+// MACs landed in M17; ConnectTimeout / ConnectionAttempts in M18).
+// Future deferral warnings should reintroduce a similar helper if a
+// new milestone parses-but-doesn't-yet-consume a directive.
 
 #[cfg(test)]
 mod tests {

src/session.rs

@@ -242,6 +242,13 @@ pub struct AnvilSession {
     auth_banner: Arc<Mutex<Option<String>>>,
     /// SHA-256 fingerprint of the server key that passed verification, if any.
     verified_fingerprint: Arc<Mutex<Option<String>>>,
+    /// Per-attempt history captured by [`crate::retry::run`] during
+    /// the connect path (M18, FR-83).  Empty when the first attempt
+    /// succeeded; otherwise one entry per failed attempt that
+    /// triggered a retry, plus the final attempt that succeeded.
+    /// Surfaced via [`Self::retry_history`] for the
+    /// `gitway --test --json` envelope.
+    retry_history: Vec<crate::retry::RetryAttempt>,
 }
 
 /// Manual Debug impl because `client::Handle<H>` does not implement `Debug`.
@@ -345,20 +352,55 @@ impl AnvilSession {
     /// Does **not** authenticate; call [`authenticate`](Self::authenticate) or
     /// [`authenticate_best`](Self::authenticate_best) after this.
     ///
+    /// **M18 / FR-80 / FR-81 / FR-82**: the TCP connect is wrapped in
+    /// a [`crate::retry::run`] loop with per-attempt
+    /// [`tokio::time::timeout`] (when `config.connect_timeout` is
+    /// `Some`).  Transient failures (`ECONNREFUSED`, `ETIMEDOUT`,
+    /// DNS NXDOMAIN, …) are retried with jittered exponential
+    /// backoff; auth / host-key / protocol errors are fatal and
+    /// surface immediately.  See [`Self::retry_history`] for the
+    /// per-attempt history captured during the loop.
+    ///
     /// # Errors
     ///
-    /// Returns an error on network failure or if the server's host key does not
-    /// match any pinned fingerprint.
+    /// Returns an error on terminal network failure (after exhausting
+    /// the retry budget) or if the server's host key does not
+    /// match any pinned fingerprint (fatal — never retried).
     pub async fn connect(config: &AnvilConfig) -> Result<Self, AnvilError> {
-        let pieces = Self::build_handler_pieces(config)?;
+        let policy = retry_policy_from_config(config);
 
         log::debug!("session: connecting to {}:{}", config.host, config.port);
 
-        let handle = client::connect(
-            pieces.russh_cfg,
-            (config.host.as_str(), config.port),
-            pieces.handler,
-        )
+        // Each attempt rebuilds `pieces` because russh's
+        // `client::connect` consumes the handler.  This is cheap —
+        // `build_handler_pieces` is pure setup, no I/O.
+        let ((handle, pieces), retry_history) = crate::retry::run(&policy, || async {
+            let pieces = Self::build_handler_pieces(config)?;
+            let connect_fut = client::connect(
+                pieces.russh_cfg,
+                (config.host.as_str(), config.port),
+                pieces.handler,
+            );
+            let handle = match policy.connect_timeout {
+                Some(t) => match tokio::time::timeout(t, connect_fut).await {
+                    Ok(Ok(h)) => h,
+                    Ok(Err(e)) => return Err(e),
+                    Err(_elapsed) => {
+                        return Err(AnvilError::new(crate::error::AnvilErrorKind::Io(
+                            std::io::Error::from(std::io::ErrorKind::TimedOut),
+                        )));
+                    }
+                },
+                None => connect_fut.await?,
+            };
+            Ok((
+                handle,
+                ConnectArtifacts {
+                    auth_banner: pieces.auth_banner,
+                    verified_fingerprint: pieces.verified_fingerprint,
+                },
+            ))
+        })
         .await?;
 
         log::debug!("session: SSH handshake complete with {}", config.host);
@@ -367,9 +409,23 @@ impl AnvilSession {
             handle,
             auth_banner: pieces.auth_banner,
             verified_fingerprint: pieces.verified_fingerprint,
+            retry_history,
         })
     }
 
+    /// Returns the [`crate::retry::RetryAttempt`] history captured
+    /// during the most-recent `connect*` call on this session.
+    ///
+    /// Empty when the first attempt succeeded.  Non-empty when the
+    /// retry loop fired at least once; the last entry's `attempt`
+    /// matches the attempt number that ultimately succeeded.
+    /// Surfaced by `gitway --test --json`'s `data.retry_attempts`
+    /// envelope (FR-83).
+    #[must_use]
+    pub fn retry_history(&self) -> &[crate::retry::RetryAttempt] {
+        &self.retry_history
+    }
+
     /// Establishes the SSH session through a chain of `ProxyJump`
     /// bastion hops (FR-56).
     ///
@@ -508,6 +564,11 @@ impl AnvilSession {
                 handle,
                 auth_banner: pieces.auth_banner,
                 verified_fingerprint: pieces.verified_fingerprint,
+                // Per-hop retry not yet wired through M18.2 — see
+                // M18.2 commit body.  Empty history; consumers
+                // reading retry_history() see only the primary
+                // connect's attempts.
+                retry_history: Vec::new(),
             };
             hop_session
                 .authenticate_best(&hop_config)
@@ -563,6 +624,12 @@ impl AnvilSession {
             handle: final_handle,
             auth_banner: target_pieces.auth_banner,
             verified_fingerprint: target_pieces.verified_fingerprint,
+            // M18.2: ProxyJump chain doesn't yet have retry wired
+            // for the per-hop connects (each hop's
+            // direct-tcpip channel makes the retry semantics
+            // murkier).  Documented as scoped-out in the M18.2
+            // commit body; deferred to a follow-up.
+            retry_history: Vec::new(),
         })
     }
 
@@ -629,6 +696,11 @@ impl AnvilSession {
             handle,
             auth_banner: pieces.auth_banner,
             verified_fingerprint: pieces.verified_fingerprint,
+            // M18.2: ProxyCommand connect path doesn't yet have
+            // retry wired (the subprocess lifecycle complicates
+            // re-spawning per attempt).  Documented as scoped-out
+            // in the M18.2 commit body; deferred to a follow-up.
+            retry_history: Vec::new(),
         })
     }
 
@@ -1021,6 +1093,34 @@ impl AnvilSession {
 /// constant for) are silently dropped here because russh's `Name`
 /// types only accept `&'static str`; a future v1.1 may surface
 /// these via a hard error at the override-validation stage.
+/// Per-attempt artifacts captured during a successful connect inside
+/// [`AnvilSession::connect`]'s retry loop.  Keeps the closure
+/// signature concise and avoids leaking `HandlerPieces`'s internals
+/// (e.g. the consumed-on-connect `russh_cfg` Arc) past the loop
+/// boundary.
+struct ConnectArtifacts {
+    auth_banner: Arc<Mutex<Option<String>>>,
+    verified_fingerprint: Arc<Mutex<Option<String>>>,
+}
+
+/// Builds a [`crate::retry::RetryPolicy`] from the connect-related
+/// fields on [`AnvilConfig`] (M18, FR-80 / FR-81).  Each `None`
+/// field falls through to the corresponding `RetryPolicy::default()`
+/// value.
+fn retry_policy_from_config(config: &AnvilConfig) -> crate::retry::RetryPolicy {
+    let mut policy = crate::retry::RetryPolicy::default();
+    if let Some(t) = config.connect_timeout {
+        policy.connect_timeout = Some(t);
+    }
+    if let Some(n) = config.connection_attempts {
+        policy.attempts = n.max(1);
+    }
+    if let Some(w) = config.max_retry_window {
+        policy.max_window = w;
+    }
+    policy
+}
+
 fn build_russh_config(config: &AnvilConfig) -> client::Config {
     let kex_strings = config
         .kex_algorithms