feat(retry): M18.1 — RetryPolicy + classifier + run loop + CAT_RETRY (FR-81, FR-82, FR-83 lib side) (#28)

Adds the library-side scaffold M18 needs to honour ConnectTimeout +
ConnectionAttempts from `~/.ssh/config` (FR-80, M18.2), classify
transient vs fatal errors (FR-82), drive an exponential-backoff
retry loop with jitter (FR-81), and capture per-attempt history for
FR-83's `gitway --test --json` envelope.

src/retry.rs (new, ~430 lines + ~190 lines of tests):

- pub struct RetryPolicy { attempts, base, factor, cap, max_window,
  connect_timeout } with builder-style setters.  Default values
  per PRD: 3 attempts, 250 ms base, x2 factor, 8 s cap, 30 s max
  window, no connect_timeout.

- pub enum Disposition { Retry, Fatal }
  pub fn classify(err: &AnvilError) -> Disposition (FR-82):
  * AuthenticationFailed / HostKeyMismatch / NoKeyFound /
    KeyEncrypted -> Fatal
  * Io kind in {ConnectionRefused, TimedOut, HostUnreachable,
    NetworkUnreachable, NotFound (DNS NXDOMAIN), AddrNotAvailable}
    -> Retry
  * Everything else (russh protocol, signing, signature-invalid,
    other Io kinds) -> Fatal
  HTTP 429/503 detection from FR-82's defensive wording is out of
  scope: Anvil speaks raw SSH; HTTP statuses only surface in
  ProxyCommand subprocess output that Anvil doesn't parse.

- pub struct RetryAttempt { attempt: u32, reason: String,
  elapsed: Duration } captures per-failure history for FR-83.

- pub async fn run<F, Fut, T>(policy, op) -> Result<(T, Vec<RetryAttempt>), AnvilError>
  drives the loop with jittered exponential backoff:
    delay_n = min(base * factor^(n-1), cap) + uniform_jitter([0, base/2])
  Jitter sourced from rand_core::OsRng (already in deps from M19's
  prepend_revoked).
  Bails on max_window before starting another attempt.
  Emits tracing::warn! at CAT_RETRY per failed attempt with
  attempt / reason / elapsed_ms / disposition fields.

- run is timeout-agnostic: the per-attempt tokio::time::timeout
  wrap lives at the call site (M18.2's session.rs::connect) so
  the same loop driver can be reused for non-network operations.

- 15 unit tests covering: default-policy values, builder
  chainability, classifier matrix (auth-fatal / host-key-fatal /
  no-key-fatal / io-connection-refused-retry / io-timed-out-retry /
  io-not-found-retry / io-permission-denied-fatal), run loop
  (success-first-try / bail-on-fatal / retry-and-record-history /
  exhaust-attempt-count), backoff curve (exponential growth, cap
  enforcement, 1000-draw jitter window).

src/log.rs:
- New pub const CAT_RETRY = "anvil_ssh::retry"; appended to
  CATEGORIES.
- categories_slice_matches_individual_constants test updated to
  include the new constant.

src/error.rs:
- New pub fn AnvilError::io_kind(&self) -> Option<std::io::ErrorKind>
  returns the underlying io::Error::kind() for the Io variant.
  Used by retry::classify; also useful for downstream consumers
  inspecting failure categories.
- New pub fn AnvilError::is_transient(&self) -> bool returning
  matches!(retry::classify(self), Disposition::Retry).  Surfaces
  the classifier as a single-call predicate for log-aggregation
  pipelines and CLI error paths.

src/lib.rs:
- pub mod retry;

Public API: pure additive.  Version bump to 0.9.0 lands in M18.3.

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

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

Author: UnbreakableMJ

src/error.rs

@@ -191,6 +191,36 @@ impl AnvilError {
         matches!(self.kind, AnvilErrorKind::Io(_))
     }
 
+    /// Returns the underlying [`std::io::ErrorKind`] when this error
+    /// is an I/O variant, or `None` otherwise.
+    ///
+    /// Used by [`crate::retry::classify`] (M18, FR-82) to distinguish
+    /// transient connection failures (`ConnectionRefused`,
+    /// `TimedOut`, `HostUnreachable`, …) from fatal ones
+    /// (`PermissionDenied`, etc.).
+    #[must_use]
+    pub fn io_kind(&self) -> Option<std::io::ErrorKind> {
+        match &self.kind {
+            AnvilErrorKind::Io(e) => Some(e.kind()),
+            _ => None,
+        }
+    }
+
+    /// Returns `true` when this error is classified as transient by
+    /// [`crate::retry::classify`] — i.e. the [`crate::retry::run`]
+    /// loop would retry it (M18, FR-82).
+    ///
+    /// Useful for callers that want to short-circuit before reaching
+    /// the retry loop, e.g. log-aggregation pipelines deciding
+    /// whether a single failure should page on-call.
+    #[must_use]
+    pub fn is_transient(&self) -> bool {
+        matches!(
+            crate::retry::classify(self),
+            crate::retry::Disposition::Retry,
+        )
+    }
+
     /// Returns `true` if the server's host key did not match any pinned fingerprint.
     #[must_use]
     pub fn is_host_key_mismatch(&self) -> bool {

src/lib.rs

@@ -55,6 +55,7 @@ pub mod keygen;
 pub mod log;
 pub mod proxy;
 pub mod relay;
+pub mod retry;
 pub mod session;
 pub mod sshsig;
 pub mod time;

src/log.rs

@@ -69,13 +69,19 @@ pub const CAT_CHANNEL: &str = "anvil_ssh::channel";
 /// source `file` and `line` number (FR-66).
 pub const CAT_CONFIG: &str = "anvil_ssh::config";
 
+/// `target =` string for the connection-retry / timeout category
+/// (M18, FR-83).  Events at this target record each retry attempt
+/// with `attempt`, `reason`, `elapsed_ms`, and (on terminal failure)
+/// a `disposition` field of `fatal` / `exhausted`.
+pub const CAT_RETRY: &str = "anvil_ssh::retry";
+
 /// All Anvil-defined categories, in declaration order.  Used by
 /// downstream CLIs (e.g. Gitway's `--debug-categories` flag) to
 /// validate user-supplied category names before building an
 /// `EnvFilter`.  Does not include `russh` — that's a synthetic
 /// passthrough recognized by the consumer's filter, not an Anvil
 /// category.
-pub const CATEGORIES: &[&str] = &[CAT_KEX, CAT_AUTH, CAT_CHANNEL, CAT_CONFIG];
+pub const CATEGORIES: &[&str] = &[CAT_KEX, CAT_AUTH, CAT_CHANNEL, CAT_CONFIG, CAT_RETRY];
 
 /// Installs the `log` → `tracing` bridge.
 ///
@@ -125,7 +131,10 @@ mod tests {
 
     #[test]
     fn categories_slice_matches_individual_constants() {
-        assert_eq!(CATEGORIES, &[CAT_KEX, CAT_AUTH, CAT_CHANNEL, CAT_CONFIG]);
+        assert_eq!(
+            CATEGORIES,
+            &[CAT_KEX, CAT_AUTH, CAT_CHANNEL, CAT_CONFIG, CAT_RETRY],
+        );
     }
 
     #[test]