hostctl 0.3.0__tar.gz → 0.3.2__tar.gz

{hostctl-0.3.0 → hostctl-0.3.2}/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-09-23
+
+### Fixed
+
+- **`redact_uri` no longer over-redacts a well-formed URI.** The textual
+  fallback -- which reads the last `@` in the whole string as the userinfo
+  delimiter -- ran whenever `urlsplit` reported no password, including for
+  URIs that simply do not have one. `ssh://nas:22/mail/user@example.com`
+  carries no credential at all and came back as `ssh://nas@example.com`: a
+  diagnostic quietly naming a different host. Guessing is now confined to
+  input that does not parse -- when the URI is well formed, `urlsplit`'s
+  authority is the authority, so an `@` in a path is left alone. A password
+  hidden by an unencoded `/`, `?` or `#` is still redacted: that input is
+  malformed (the separator ends the authority, leaving `user:secret` read as
+  host:port), and detecting exactly that is what now gates the fallback.
+
+### Changed
+
+- `ConnectionString` now documents the parsing contract it already enforced:
+  the input must be a valid URI, and reserved characters in a password must
+  be percent-encoded. There is no lenient mode and none is planned -- a
+  password may itself contain `@` and `:`, so nothing can recover where an
+  unescaped one ended, and a guess in the parser would be a guess about what
+  to connect to. Documentation and tests only; behaviour is unchanged.
+
+## [0.3.1] - 2026-09-22
+
+### Fixed
+
+- **A composite path falls back when SFTP cannot connect.** Nothing on the
+  path route connected the provider first: pathlib_next dialled SFTP inside
+  the operation, so an untrusted host key (`HostKeyNotVerifiable`) or a
+  refused port escaped raw and the next path provider was never tried --
+  while `run()` on the same host fell back. A composite path now calls the
+  provider's `connect()` before dispatch, and SFTP maps asyncssh's connect
+  errors the way the SSH leg already did. Most likely to fire since 0.3.0
+  started verifying the SFTP host key: any host not yet in `known_hosts`.
+- **`run()` no longer re-dials a declined provider on every call.** 0.3.0
+  cleared every decline per call, so a dead primary cost a full connect
+  attempt (~9 s against a refused port) on each `run()` while the fallback
+  served. A decline now lasts for the generation again, and is re-admitted
+  only when no other provider can serve -- which keeps a single-provider
+  host from bricking on one transient refusal, for paths as well as `run()`.
+- A path refusal with nothing left to try names why ("no path provider
+  completed read (...: Host key is not trusted ...)") and keeps the cause.
+
 ## [0.3.0] - 2026-09-22
 
 ### Added
@@ -741,7 +787,10 @@ test suite on Python 3.9 through 3.14.
   assigned to it; a config-less host now builds its own family configuration
   instead.
 
-[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.7...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/jose-pr/hostctl/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/jose-pr/hostctl/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/jose-pr/hostctl/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/jose-pr/hostctl/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/jose-pr/hostctl/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/jose-pr/hostctl/compare/v0.2.4...v0.2.5

{hostctl-0.3.0 → hostctl-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hostctl
-Version: 0.3.0
+Version: 0.3.2
 Summary: Run commands and access files on a host, local or remote, protocol-agnostic
 Project-URL: Homepage, https://github.com/jose-pr/hostctl/
 Project-URL: Documentation, https://jose-pr.github.io/hostctl/

{hostctl-0.3.0 → hostctl-0.3.2}/docs/guide/providers.md

@@ -100,7 +100,15 @@ the same conservative default.
 
 A provider that declines is remembered for the current connection generation, so
 later operations skip it instead of re-attempting it every time. Reconnecting or
-replacing a provider starts a new generation and re-probes everything.
+replacing a provider starts a new generation and re-probes everything. The one
+exception is a host with nothing else left: when every other candidate is
+unavailable, an earlier refusal is tried again rather than failing without
+dialling, so one transient refusal cannot brick a single-provider host.
+
+Paths and commands connect the same way: a composite path calls the provider's
+`connect()` before each dispatch, which is where a refused port or an untrusted
+host key becomes `OperationNotStarted`. A path provider's `connect()` must
+therefore be idempotent and cheap once connected.
 
 ## Selection traces
 

{hostctl-0.3.0 → hostctl-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.3.0"
+version = "0.3.2"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/AGENTS.md

@@ -156,7 +156,11 @@ and dispatches it with no args, and that script is shell text, not a program.
   renders. Supplying a password both in the URI and as an argument raises.
   `redact_uri(uri)` STRIPS a password and returns a valid, reusable URI (not a
   masked one, so a rendered form can never round-trip a wrong credential), for
-  logs, reprs, and error messages.
+  logs, reprs, and error messages. A WELL-FORMED URI IS NEVER OVER-REDACTED:
+  when it parses, `urlsplit`'s authority is the authority, so an `@` elsewhere
+  (`ssh://nas:22/mail/user@example.com`) is left alone. Only input that does
+  not parse gets the textual last-`@` guess, which may over-redact -- by then
+  the text has already failed to say where its authority ended.
 - A connection URI may carry a raw tab, CR, or LF in its **userinfo**: those
   are percent-encoded before `urlsplit` sees them, which would otherwise
   delete them silently (`ssh://u:pw<LF>otp:1@host` would authenticate with
@@ -189,9 +193,19 @@ path grammar, so `path()` raises.
 `ConnectionString(value, *, scheme=None, port=None, ...)` is the parsed form
 of a target -- host, scheme, port, user, password -- with `is_local` answered
 by `netimps` rather than guessed. It exists so a caller never reimplements
-connection-string parsing. `uri_hostname(value)` returns the bare hostname of
-a URI authority, unbracketing an IPv6 literal; it is the sibling of
-`uri_host`, `redact_uri` and `parse_credentials`.
+connection-string parsing. A bare host parses (a missing scheme is not an
+error), but otherwise the value MUST be a valid URI: an unclosed IPv6 literal,
+a non-numeric port, or an unescaped `/`, `?` or `#` in a password RAISES.
+**Percent-encode reserved characters in a password** -- there is no lenient
+mode and none will be added, because a password may itself contain `@` and
+`:`, so nothing can recover where an unescaped one ended, and guessing would
+be guessing what to connect to. (`@` and `:` do parse: last `@`, first `:`,
+per the URI grammar.) Use `redact_uri` when the text may not parse at all and
+the job is only keeping a secret out of a log.
+
+`uri_hostname(value)` returns the bare hostname of a URI authority,
+unbracketing an IPv6 literal; it is the sibling of `uri_host`, `redact_uri`
+and `parse_credentials`.
 
 `__version__` is the installed version string.
 
@@ -315,7 +329,12 @@ hostctl applies to whatever you return.
   falls through to the next provider for **that call only**; it does not take
   the provider out of service.
 - `ProviderSelector` holds the ordered providers and the per-generation
-  declines; `ProviderSelection` is one resolved choice.
+  declines; `ProviderSelection` is one resolved choice. `select()` re-admits
+  a decline recorded by an earlier operation only when no other provider can
+  serve.
+- A provider's optional `connect()` is where a pre-dispatch failure belongs.
+  Composite paths call a path provider's `connect()` before **every**
+  dispatch, so it must be idempotent and cheap once connected.
   `ProviderSelector.redact(value)` is the one redaction used in traces --
   rendered commands routinely carry credentials, so log through it.
 - `SessionInitializer` is the hook a provider may accept to prepare a session

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/host/_common.py

@@ -230,6 +230,12 @@ def redact_uri(uri: str) -> str:
 
     A URI with no password is returned unchanged.
 
+    **A well-formed URI is never over-redacted.** When the URI parses, what
+    `urlsplit` says is the authority *is* the authority, so an `@` anywhere
+    else -- a mailbox in a path, `ssh://nas:22/mail/user@example.com` -- is
+    left alone. Guessing is confined to input that does not parse, where
+    there is nothing better to go on: see below.
+
     This never raises. It is meant for error messages and log records, where
     failing to render a diagnostic would be worse than rendering an odd one.
     Characters `urlsplit` would delete (tab, CR, LF) are percent-encoded first,
@@ -238,31 +244,37 @@ def redact_uri(uri: str) -> str:
     """
     try:
         parsed = _urlsplit(_encode_stripped_characters(uri))
-        password = parsed.password
+        # Not dead code: `.port` is a property that RAISES, and touching it
+        # is what decides "well formed" here. It catches both shapes that
+        # matter in one place -- a non-numeric or out-of-range port, and an
+        # unencoded `/`, `?` or `#` in a password, since the latter ends the
+        # authority and leaves `user:secret` being read as host:port. So the
+        # bad port IS the symptom of the hidden password.
+        parsed.port  # noqa: B018
     except ValueError:
-        # A malformed IPv6 authority. The textual fallback below still strips
-        # the userinfo, which is the whole job.
-        password = None
+        pass  # Malformed. The textual fallback below is all that is left.
     else:
-        if password is not None:
-            try:
-                return _without_password(parsed).geturl()
-            except ValueError:
-                # `_rebuild_authority` reads `parsed.port`, which raises for a
-                # non-numeric or out-of-range one. This function is called
-                # from inside exception handlers to format a diagnostic, so
-                # raising here would replace the real error with this one.
-                pass
-
-    # `urlsplit` finds no password when one contains an unencoded `/`, `?` or
-    # `#`: those end the authority, so the secret lands in the path or query
-    # and the "redacted" form used to be the input in full. Randomly generated
-    # passwords routinely contain `/`.
-    #
-    # Fall back to reading the userinfo textually. The last `@` wins, as it
-    # does in a real authority. This can over-redact a path that contains `@`
-    # -- deliberately: an odd diagnostic beats a password in a log, which is
-    # the trade-off this function already documents.
+        if parsed.password is None:
+            # Well formed and carrying no password: there is nothing to
+            # strip, and the fallback must not run. It reads the LAST `@` in
+            # the whole string as the userinfo delimiter, which would rewrite
+            # `ssh://nas:22/mail/user@example.com` -- a URI with no
+            # credentials at all -- into `ssh://nas@example.com`, naming a
+            # different host.
+            return uri
+        try:
+            return _without_password(parsed).geturl()
+        except ValueError:
+            # Not reachable through `.port`, which is already validated above;
+            # kept because "never raises" is a contract this function is
+            # called from inside exception handlers to honour.
+            pass
+
+    # Only a malformed URI reaches here. Read the userinfo textually: the last
+    # `@` wins, as it does in a real authority. This can over-redact -- but
+    # the text has already failed to say where its authority ended, so there
+    # is no reading of it that is known to be right, and an odd diagnostic
+    # beats a password in a log.
     head, separator, _rest = uri.partition("://")
     start = len(head) + len(separator)
     authority_end = uri.rfind("@")

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/host/_connection.py

@@ -110,6 +110,23 @@ class ConnectionString:
     not an invalid URI -- it is a URI with the scheme left off, which is what
     people type on a command line.
 
+    Beyond that, **the input must be a valid URI, and a malformed one
+    raises** -- an unclosed IPv6 literal, a non-numeric port, or a password
+    written with an unescaped `/`, `?` or `#` (each ends the authority, so
+    what precedes it is read as a port and fails to cast).
+
+    **Reserved characters in a password must be percent-encoded, and one
+    that is not gets no rescue attempt.** There is no rescue to make: a
+    password may itself contain `@` and `:`, so no rule recovers where an
+    unescaped one ended. Those two do parse -- the last `@` and the
+    first `:` win, as in any authority, giving `pa@ss` and `pa:ss` -- but
+    that is the URI grammar being applied, not a guess about the secret.
+    Guessing here would be guessing about what to *connect to*, so a raise is
+    the answer. :func:`redact_uri` is the other job and keeps its own rules:
+    stripping a secret out of text that may not parse at all, for a log line
+    nothing connects to. It does not over-redact a well-formed URI either --
+    it guesses only once the text has failed to parse.
+
     Every field can also be supplied directly, and three layers decide each
     one: **an explicit argument wins, then whatever the string carried, then
     `defaults`.**

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/host/_ssh.py

@@ -706,10 +706,24 @@ class SftpPathProvider(PathProvider):
     # Closing is owned by SshExecutorProvider for the shared transport;
     # connecting is not, because the SFTP client has to be established from
     # the caller's thread before any native recursive operation runs.
+    #
+    # Composite paths call this before EVERY dispatch, so once connected it
+    # must stay cheap: a lock, a liveness check and a cache hit.
     def connect(self):
+        from .. import _async
+
         try:
             self.transport.connect()
-            self.transport.warm_sftp()
+            try:
+                self.transport.warm_sftp()
+            except Exception as exc:
+                # pathlib_next dials its own SFTP connection and hands back
+                # asyncssh's errors raw -- `HostKeyNotVerifiable` is not an
+                # OSError -- so map them as the transport's own connect does.
+                normalized = _async.normalize_asyncssh_error(exc)
+                if normalized is exc:
+                    raise
+                raise normalized from exc
         except (OSError, TimeoutError) as exc:
             log.debug(
                 "SFTP provider declining before dispatch: %s: %s",

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/host/composite_path.py

@@ -498,10 +498,20 @@ class _CompositePathMixin:
         candidates = self._providers_in_order(operation, pin=pin)
         attempted = False
         not_implemented: typing.Optional[NotImplementedError] = None
+        not_started: typing.Optional[OperationNotStarted] = None
         for provider in candidates:
             attempted = True
             old = (self._provider, self._backend_path, self._factory, self._pinned)
             try:
+                # Connect first, where a failure is provably pre-dispatch.
+                # SFTP used to be dialled lazily inside the backend by the
+                # operation itself, so an unreachable server or an untrusted
+                # host key escaped as a raw transport error and the next
+                # provider was never tried -- while `run()`, which connects
+                # before dispatch, fell back on the same host.
+                connect = getattr(provider, "connect", None)
+                if connect is not None:
+                    connect()
                 backend_path = self._provider_path(provider)
                 if pin:
                     # A write/open operation owns the provider choice before
@@ -531,6 +541,7 @@ class _CompositePathMixin:
                 # `excluded` already stops us retrying it for this call.
                 continue
             except OperationNotStarted as exc:
+                not_started = exc
                 if pin:
                     self._provider, self._backend_path, self._factory, self._pinned = (
                         old
@@ -554,7 +565,16 @@ class _CompositePathMixin:
             # visibly with a single provider, where "try the next one" has
             # nothing to try.
             raise not_implemented
-        raise OperationNotStarted(f"no path provider completed {operation}")
+        # Carry the last refusal: "no provider completed" alone hid WHY -- a
+        # rejected host key read the same as a refused port.
+        cause = not_started.cause if not_started is not None else None
+        detail = ""
+        if not_started is not None:
+            reason = f"{not_started}: {cause}" if cause is not None else not_started
+            detail = f" ({ProviderSelector.redact(reason)})"
+        raise OperationNotStarted(
+            f"no path provider completed {operation}{detail}", cause=cause
+        ) from (cause or not_started)
 
     def via(self, name: str):
         provider = next((item for item in self._providers if item.name == name), None)

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/host/system.py

@@ -826,11 +826,11 @@ class SystemHost(Host):
             raise NotImplementedError(
                 f"{type(self).__name__} does not provide the 'run' capability"
             )
-        # A refusal recorded by an earlier call must not decide this one: a
-        # single-provider SSH host that hit one transient ConnectionError
-        # never dialled out again until close(). Within this call, `excluded`
-        # still stops a provider being retried after it declines.
-        self._executor_selector.retry_declined()
+        # No `retry_declined()` here. Clearing every refusal per call re-dialled
+        # a dead primary on EVERY run() -- ~9 s each against a refused port --
+        # although the fallback was serving. The selector re-admits an earlier
+        # refusal only when nothing else is left, which is what keeps a
+        # single-provider host from bricking on one transient failure.
         excluded: list[str] = []
         while True:
             provider = self._executor_selector.select(exclude=excluded).provider

{hostctl-0.3.0 → hostctl-0.3.2}/src/hostctl/provider/_common.py

@@ -337,13 +337,12 @@ class ProviderSelector:
         return self._generation
 
     def retry_declined(self) -> None:
-        """Forget refusals recorded during an earlier call.
+        """Forget every refusal recorded this generation.
 
-        A decline exists to stop one dispatch re-dialling a provider that just
-        refused; it was never meant to outlive the call. Kept for the life of
-        the selector it bricked a single-provider host: one transient refusal
-        (sshd restarting, a network blip) and hostctl never dialled out again
-        until `close()`.
+        Not needed to recover a host: `select()` already re-admits an earlier
+        refusal when nothing else can serve. This is for a caller that knows
+        the declined provider is back (sshd restarted) and wants it preferred
+        over a fallback that is still serving.
         """
         with self._lock:
             self._declined.clear()
@@ -539,6 +538,15 @@ class ProviderSelector:
                 len(self._attempt_trace),
             )
             return result
+        if self._readmit_earlier_declines(excluded, capability):
+            # Nothing else can serve, so a refusal recorded by an EARLIER
+            # operation gets another chance rather than failing this one
+            # without dialling: one transient refusal (sshd restarting) on a
+            # single-provider host otherwise bricked it until close(). A
+            # decline this operation made itself is in `excluded` and stays.
+            return self.select(
+                capability=capability, exclude=excluded, policy=policy, pin=pin
+            )
         log.debug(
             "no provider available (generation %d); candidates: %s",
             self._generation,
@@ -563,6 +571,32 @@ class ProviderSelector:
             cause=cause,
         ) from cause
 
+    def _readmit_earlier_declines(
+        self, excluded: typing.AbstractSet[str], capability: str | None
+    ) -> bool:
+        """Forget declines that the running operation did not make.
+
+        A name the caller excluded is one it tried and saw refuse, so only
+        declines outside `excluded` came from an earlier operation.
+        """
+        with self._lock:
+            stale = [
+                provider.name
+                for provider in self.providers
+                if provider.name in self._declined
+                and provider.name not in excluded
+                and (capability is None or capability in provider.capabilities)
+            ]
+            for name in stale:
+                del self._declined[name]
+                self._decline_causes.pop(name, None)
+        for name in stale:
+            log.debug(
+                "provider %s re-admitted: every other candidate is unavailable",
+                _redacted_name(name),
+            )
+        return bool(stale)
+
     def _record(self, entry: dict[str, object]) -> None:
         """Merge one trace entry, letting a later record supersede an earlier.
 

{hostctl-0.3.0 → hostctl-0.3.2}/tests/test_connection_string.py

@@ -357,3 +357,39 @@ def test_replace_normalises_what_init_normalises():
 
     assert parsed.replace(scheme="WSS") == parsed
     assert ConnectionString("ssh://nas").replace(port="2222").port == 2222
+
+
+@pytest.mark.parametrize(
+    "target",
+    [
+        "ssh://root:pa/ss@nas",
+        "ssh://root:pa?ss@nas",
+        "ssh://root:pa#ss@nas",
+        "ssh://root:pw@[::1",
+        "ssh://root:pw@nas:notaport",
+    ],
+)
+def test_a_malformed_uri_raises_rather_than_being_guessed_at(target):
+    """The input must be a valid URI, and there is deliberately no lenient
+    mode: what this parses is what gets connected to, so a guess here is a
+    guess about the target. An unescaped `/`, `?` or `#` ends the authority,
+    which is why `root:pa` is then read as a port and fails to cast."""
+    with pytest.raises(ValueError):
+        ConnectionString(target)
+
+
+def test_reserved_characters_in_a_password_must_be_percent_encoded():
+    value = ConnectionString("ssh://root:pa%2Fss@nas")
+
+    assert value.username == "root"
+    assert value.password == "pa/ss"
+
+
+def test_at_and_colon_in_a_password_parse_by_the_uri_grammar():
+    """These two do not raise -- the last `@` and the first `:` delimit, as in
+    any authority. They are also why no textual fallback is possible: a
+    password may contain both, so nothing recovers where an unescaped one
+    ended. `redact_uri` may over-redact, but only once the text has failed
+    to parse at all; this may not guess even then."""
+    assert ConnectionString("ssh://root:pa@ss@nas").password == "pa@ss"
+    assert ConnectionString("ssh://root:pa:ss@nas").password == "pa:ss"

{hostctl-0.3.0 → hostctl-0.3.2}/tests/test_host_api.py

@@ -638,6 +638,32 @@ def test_redact_uri_leaves_a_credential_free_uri_alone():
     assert redact_uri("wss://nas:8443/api?x=1") == "wss://nas:8443/api?x=1"
 
 
+@pytest.mark.parametrize(
+    "uri",
+    (
+        "ssh://nas:22/mail/user@example.com",
+        "ssh://user@nas:22/path/foo@bar",
+        "https://host:443/a@b",
+        "ssh://nas:22/mail/a@b/more@here",
+    ),
+)
+def test_redact_uri_never_over_redacts_a_well_formed_uri(uri):
+    """The textual fallback reads the LAST `@` as the userinfo delimiter, and
+    it used to run whenever `urlsplit` reported no password -- including for
+    URIs that simply do not have one.
+
+    `ssh://nas:22/mail/user@example.com` carries no credential at all and came
+    back as `ssh://nas@example.com`: not merely over-redacted but pointing at
+    a different host. Guessing is now confined to input that does not parse.
+    """
+    assert redact_uri(uri) == uri
+
+
+def test_redact_uri_still_strips_a_password_beside_an_at_sign_in_the_path():
+    """The guard above must not cost the actual redaction."""
+    assert redact_uri("ssh://root:pw@nas:22/mail/a@b") == "ssh://root@nas:22/mail/a@b"
+
+
 def test_an_unsupported_session_raises_not_implemented_not_a_runtime_error():
     """AGENTS.md: unsupported run()/path()/spawn() raise NotImplementedError.
 

{hostctl-0.3.0 → hostctl-0.3.2}/tests/test_provider_fault_injection.py

@@ -800,6 +800,137 @@ def test_path_falls_back_over_every_candidate_not_just_one():
     assert path.provider.name == "third"
 
 
+def _served_by_memory(text="served"):
+    backend = MemPathBackend()
+    MemPath("/etc", backend=backend).mkdir(parents=True)
+    MemPath("/etc/hostname", backend=backend).write_text(text)
+    return PathProvider("memory", lambda *parts: MemPath(*parts, backend=backend))
+
+
+def _sftp_that_cannot_connect(*, connect=None, warm=None):
+    from hostctl import SshConfig
+    from hostctl.host._ssh import SftpPathProvider, _SshTransport
+
+    transport = _SshTransport(SshConfig("nas.example", username="root"))
+    transport.connect = connect or (lambda: None)
+    transport.warm_sftp = warm or (lambda: None)
+    return SftpPathProvider(transport)
+
+
+@pytest.mark.parametrize(
+    "error",
+    (
+        # What `_SshTransport.connect()` makes of each: an untrusted host key
+        # (`HostKeyNotVerifiable`) and a refused or firewalled port.
+        ConnectionError("Host key is not trusted for host nas.example"),
+        ConnectionRefusedError(10061, "connection refused"),
+        TimeoutError("connect timed out"),
+    ),
+    ids=("host-key", "refused", "timeout"),
+)
+def test_a_path_falls_back_when_sftp_cannot_connect(error):
+    """`run()` connects before dispatch and fell back; `path()` did not.
+
+    Nothing on the composite-path route called `SftpPathProvider.connect()`:
+    pathlib_next dialled SFTP lazily inside the operation, so the transport
+    error escaped `_dispatch` and the working next provider was never tried.
+    """
+
+    def refuse():
+        raise error
+
+    host = PosixHost(
+        path_providers=(_sftp_that_cannot_connect(connect=refuse), _served_by_memory())
+    )
+
+    path = host.path("/etc/hostname")
+
+    assert path.read_text() == "served"
+
+
+def test_a_raw_asyncssh_host_key_error_from_the_sftp_leg_declines():
+    """pathlib_next dials its own SFTP connection and raises asyncssh's error
+    raw; `HostKeyNotVerifiable` is not an OSError, so it was never taken as
+    "nothing started" even where `connect()` did run."""
+    import asyncssh
+
+    def untrusted():
+        raise asyncssh.HostKeyNotVerifiable("Host key is not trusted")
+
+    host = PosixHost(
+        path_providers=(_sftp_that_cannot_connect(warm=untrusted), _served_by_memory())
+    )
+
+    assert host.path("/etc/hostname").read_text() == "served"
+
+
+def test_a_path_refusal_names_its_cause_when_nothing_is_left():
+    def refuse():
+        raise ConnectionError("Host key is not trusted for host nas.example")
+
+    host = PosixHost(path_providers=(_sftp_that_cannot_connect(connect=refuse),))
+
+    with pytest.raises(OperationNotStarted) as raised:
+        host.path("/etc/hostname").read_text()
+
+    assert "Host key is not trusted" in str(raised.value)
+    assert isinstance(raised.value.cause, ConnectionError)
+
+
+def test_a_path_refusal_does_not_brick_a_single_provider_host():
+    """Now that a failed SFTP connect declines, the decline must not outlive
+    the refusal on a host with nothing to fall back to."""
+    state = {"failing": True}
+
+    def flaky():
+        if state["failing"]:
+            raise ConnectionRefusedError(10061, "sshd restarting")
+
+    backend = MemPathBackend()
+    MemPath("/etc", backend=backend).mkdir(parents=True)
+    MemPath("/etc/hostname", backend=backend).write_text("back")
+    provider = _sftp_that_cannot_connect(connect=flaky)
+    provider.factory = lambda *parts: MemPath(*parts, backend=backend)
+    host = PosixHost(path_providers=(provider,))
+
+    with pytest.raises(OperationNotStarted):
+        host.path("/etc/hostname").read_text()
+
+    state["failing"] = False
+    assert host.path("/etc/hostname").read_text() == "back"
+
+
+def test_a_declined_primary_is_not_redialled_while_the_fallback_serves():
+    """Every `run()` cleared every decline, so a dead primary was dialled
+    again on each call -- ~9 s apiece against a refused port -- although the
+    fallback had been serving all along."""
+    dialled = []
+
+    def refuse(command, *args, **options):
+        dialled.append(command)
+        raise OperationNotStarted(
+            "connection refused", cause=ConnectionRefusedError("refused")
+        )
+
+    host = PosixHost(
+        executor_providers=(
+            ExecutorProvider("ssh", refuse, capabilities=()),
+            ExecutorProvider(
+                "fallback",
+                lambda command, *args, **options: subprocess.CompletedProcess(
+                    (command,), 0, b"ok", b""
+                ),
+                capabilities=(),
+            ),
+        )
+    )
+
+    for _ in range(3):
+        assert host.run("uptime", check=False).stdout == b"ok"
+
+    assert len(dialled) == 1
+
+
 def test_two_threads_selecting_do_not_share_a_trace():
     """The per-operation trace and the probe/decline maps were unsynchronised
     instance state, so concurrent operations on one host mixed trace entries