feat: M13.2 — AnvilSession::connect_via_proxy_command (FR-55) (#10)

Adds the public constructor that consumes the ProxyCommand template
captured into ResolvedSshConfig in M12 and the building blocks landed
in M13.1 (token expansion + ChildStdio adapter).

session.rs:
- New private HandlerPieces struct + Self::build_handler_pieces helper
  factor out the russh config + GitwayHandler + auth_banner +
  verified_fingerprint mutex setup that connect() and the new
  connect_via_proxy_command both need. M13.4's connect_via_jump_hosts
  will reuse the same helper. The host-key fingerprint lookup
  (with the StrictHostKeyChecking::AcceptNew tolerance shipped in
  M12.5) lives there now, in one place.

- pub async fn connect_via_proxy_command(config, template, alias):
    1. Reject the literal `none` (case-insensitive) — that's the FR-59
       disable sentinel; callers should reach for connect() instead.
       The ssh_config resolver preserves `none` as a literal so first-
       wins protects it; the dispatcher in M13.6 turns that into a
       call to connect() rather than this method.
    2. Build the handler via build_handler_pieces.
    3. Spawn the ProxyCommand child via crate::proxy::command::
       spawn_proxy_command (token-expanded against config.host /
       config.port / config.username / alias).
    4. Hand the resulting ChildStdio (AsyncRead+AsyncWrite+Unpin+Send)
       to russh::client::connect_stream. russh drives the SSH
       handshake over the child's stdio.
    5. Return the AnvilSession with the same shape as connect() —
       indistinguishable to callers thereafter.

- The existing connect() now calls build_handler_pieces too; behavior
  is identical (same russh::client::connect call, same handler).

proxy/mod.rs:
- Removed the M13.1-era #![allow(dead_code)]; spawn_proxy_command and
  ChildStdio::new are now used by session.rs.

Tests: 173 lib + 1 matrix + 6 integration; 0 failures.

Plan: M13.2 of let-us-plan-on-bright-cosmos.md. Stacked on M13.1 (PR #6).

Author: UnbreakableMJ

src/proxy/mod.rs

@@ -1,13 +1,5 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Rust guideline compliant 2026-03-30
-#![allow(
-    dead_code,
-    reason = "M13.1 lands the proxy module's building blocks (token \
-              expansion, ChildStdio adapter, spawn helper) as crate-private \
-              items; M13.2 wires them into AnvilSession::connect_via_proxy_command \
-              and the dead-code analysis turns clean. Remove this allow at \
-              M13.2 time."
-)]
 //! `ProxyCommand` and `ProxyJump` consumers (PRD §5.8.2, M13).
 //!
 //! M12 captured `proxy_command` and `proxy_jump` losslessly into

src/session.rs

@@ -178,20 +178,28 @@ impl fmt::Debug for AnvilSession {
     }
 }
 
+/// The pre-handshake state every constructor on [`AnvilSession`]
+/// builds before driving russh.  Factoring it out keeps `connect`,
+/// `connect_via_proxy_command`, and `connect_via_jump_hosts` (M13.4)
+/// in lock-step on host-key handling and the `auth_banner` /
+/// `verified_fingerprint` mutexes the public getters expose.
+struct HandlerPieces {
+    russh_cfg: Arc<client::Config>,
+    handler: GitwayHandler,
+    auth_banner: Arc<Mutex<Option<String>>>,
+    verified_fingerprint: Arc<Mutex<Option<String>>>,
+}
+
 impl AnvilSession {
     // ── Construction ─────────────────────────────────────────────────────────
 
-    /// Establishes a TCP connection to the host in `config` and completes the
-    /// SSH handshake (including host-key verification).
-    ///
-    /// Does **not** authenticate; call [`authenticate`](Self::authenticate) or
-    /// [`authenticate_best`](Self::authenticate_best) after this.
-    ///
-    /// # Errors
+    /// Builds the russh config + handler used by every constructor.
     ///
-    /// Returns an error on network failure or if the server's host key does not
-    /// match any pinned fingerprint.
-    pub async fn connect(config: &AnvilConfig) -> Result<Self, AnvilError> {
+    /// Centralises host-key fingerprint lookup (with the
+    /// [`StrictHostKeyChecking::AcceptNew`] tolerance for unknown hosts
+    /// when a writable `custom_known_hosts` path is set) and the shared
+    /// `auth_banner` / `verified_fingerprint` mutex pair.
+    fn build_handler_pieces(config: &AnvilConfig) -> Result<HandlerPieces, AnvilError> {
         let russh_cfg = Arc::new(build_russh_config(config.inactivity_timeout));
         // For StrictHostKeyChecking=AcceptNew with a writable known_hosts
         // path, an empty fingerprint set is acceptable — the handler will
@@ -229,17 +237,108 @@ impl AnvilSession {
             verified_fingerprint: Arc::clone(&verified_fingerprint),
         };
 
+        Ok(HandlerPieces {
+            russh_cfg,
+            handler,
+            auth_banner,
+            verified_fingerprint,
+        })
+    }
+
+    /// Establishes a TCP connection to the host in `config` and completes the
+    /// SSH handshake (including host-key verification).
+    ///
+    /// Does **not** authenticate; call [`authenticate`](Self::authenticate) or
+    /// [`authenticate_best`](Self::authenticate_best) after this.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error on network failure or if the server's host key does not
+    /// match any pinned fingerprint.
+    pub async fn connect(config: &AnvilConfig) -> Result<Self, AnvilError> {
+        let pieces = Self::build_handler_pieces(config)?;
+
         log::debug!("session: connecting to {}:{}", config.host, config.port);
 
-        let handle =
-            client::connect(russh_cfg, (config.host.as_str(), config.port), handler).await?;
+        let handle = client::connect(
+            pieces.russh_cfg,
+            (config.host.as_str(), config.port),
+            pieces.handler,
+        )
+        .await?;
 
         log::debug!("session: SSH handshake complete with {}", config.host);
 
         Ok(Self {
             handle,
-            auth_banner,
-            verified_fingerprint,
+            auth_banner: pieces.auth_banner,
+            verified_fingerprint: pieces.verified_fingerprint,
+        })
+    }
+
+    /// Establishes the SSH session over a child process spawned from a
+    /// `ProxyCommand` template (FR-55).
+    ///
+    /// `proxy_command_template` is the raw template (typically from
+    /// [`crate::ssh_config::ResolvedSshConfig::proxy_command`] or a CLI
+    /// override).  `%h`, `%p`, `%r`, `%n`, and `%%` are expanded against
+    /// `config.host`, `config.port`, `config.username`, and `alias`
+    /// respectively before the platform shell (`sh -c` / `cmd /C`)
+    /// spawns the command.  The child's stdin/stdout become the SSH
+    /// transport via [`russh::client::connect_stream`].
+    ///
+    /// `alias` is the original argument the user typed before
+    /// `HostName` resolution — it powers the `%n` token.  Pass
+    /// `config.host` if you do not track the alias separately.
+    ///
+    /// The literal value `"none"` (case-insensitive) is recognized as
+    /// the FR-59 disable sentinel: this method returns an error
+    /// directing the caller to use [`Self::connect`] instead.  In
+    /// practice the caller's dispatcher should never invoke this
+    /// method in that case, but the guard keeps the spawn path safe
+    /// against accidental "none" input.
+    ///
+    /// # Errors
+    /// Returns an error on shell-spawn failure, on a host-key
+    /// mismatch, or on any russh handshake failure.
+    pub async fn connect_via_proxy_command(
+        config: &AnvilConfig,
+        proxy_command_template: &str,
+        alias: &str,
+    ) -> Result<Self, AnvilError> {
+        if proxy_command_template.eq_ignore_ascii_case("none") {
+            return Err(AnvilError::invalid_config(
+                "ProxyCommand=none is the disable sentinel; \
+                 call AnvilSession::connect instead",
+            ));
+        }
+
+        let pieces = Self::build_handler_pieces(config)?;
+
+        log::debug!(
+            "session: connecting to {} via ProxyCommand template `{proxy_command_template}`",
+            config.host,
+        );
+
+        let stream = crate::proxy::command::spawn_proxy_command(
+            proxy_command_template,
+            &config.host,
+            config.port,
+            &config.username,
+            alias,
+        )?;
+
+        let handle = client::connect_stream(pieces.russh_cfg, stream, pieces.handler).await?;
+
+        log::debug!(
+            "session: SSH handshake complete with {} (via ProxyCommand)",
+            config.host,
+        );
+
+        Ok(Self {
+            handle,
+            auth_banner: pieces.auth_banner,
+            verified_fingerprint: pieces.verified_fingerprint,
         })
     }