[Enhancement]: Consider opt-in single-connection SFTP multiplexing for concurrent file transfers #188

Problem

Current SFTPAdapter.openSession() uses a connection pool with limit: options?.concurrency ?? 1: concurrent transfers can create one SSH login per file in flight. The source even documents PERF-SFTP-MULTIPLEX as a future optimization: the ssh2 SFTP channel supports multiple concurrent request IDs, so a single SSH connection can potentially multiplex operations without N independent handshakes.

A maintained downstream currently uses one reusable SSH/SFTP client for concurrent source transfers, plus a bounded transient handshake retry. This reduces pressure on SFTP servers with strict concurrent-login limits, but may behave differently on certain SSH servers and is not automatically a drop-in replacement for the existing pool.

Proposed upstream design discussion

Consider an explicitly reviewable single-connection multiplex mode for SFTP source sessions, with the pool behavior preserved for compatibility until supported integration/performance evidence is available. The API/default choice should be made with maintainers, not silently changed by a fork.

Acceptance proposals:

• A request for concurrency 8 with many files uses one SSH session in multiplex mode, while still having more than one file I/O operation in flight.
• Connection lifecycle is fail-closed and race-safe: close exactly once, new requests after close or disconnect fail, mid-transfer disconnect is observable, and retry applies only to transient initial handshakes (not authentication).
• Shared directory creation cache and concurrent file creation remain safe.
• Existing pool mode retains current documented behavior and unit/integration expectations unless intentionally migrated.
• Benchmarks compare multi-connection pooling and single-connection multiplexing on representative high-latency and restrictive SFTP servers, including large and many-small-file workloads.
• No DB migrations, deployment-specific credentials or Homelab-only settings.

Source-tree directory scanning is separately covered by #186 / draft PR #187. This issue concerns file transfer sessions, not directory scans. Once an interface/default is accepted, an upstream-native PR can be prepared against the current dev baseline with test-first coverage.