test: cover SSH publickey diagnostic edges

Adds explicit publickey-only and non-SSH negative coverage for the clone failure diagnostic, and records the user-facing fix in the changelog. Addresses panel follow-ups from test coverage and growth.

apm-spec-waiver: Diagnostic-only failure text; no OpenAPM protocol behavior change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -20,6 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- SSH clone failures from passphrase-protected keys now explain how to unblock
+  non-interactive clones with `ssh-add`, CI deploy keys, or token-backed HTTPS
+  instead of ending with an opaque git error. (#2244)
 - Govern policy cache freshness now honors the effective policy's `cache.ttl`;
   bounded property coverage protects all 39 enforceable fields, cold/warm parity,
   canonical serialization, and last-good bytes after malformed refreshes. (#2235)

tests/unit/deps/test_bare_cache_clone_failure.py

@@ -9,8 +9,12 @@
 from apm_cli.models.apm_package import DependencyReference
 
 
-def test_clone_failure_message_explains_passphrase_protected_ssh_key() -> None:
-    """SSH passphrase failures must tell users how to unblock non-interactive clones."""
+def _clone_failure_message(
+    *,
+    stderr: bytes,
+    explicit_scheme: str | None,
+) -> str:
+    """Build a clone failure message for an SSH diagnostic scenario."""
     plan = MagicMock()
     plan.strict = True
     plan.attempts = [MagicMock(label="SSH")]
@@ -20,19 +24,16 @@ def test_clone_failure_message_explains_passphrase_protected_ssh_key() -> None:
     last_error = subprocess.CalledProcessError(
         128,
         ["git", "clone", "ssh://github.com/owner/repo"],
-        stderr=(
-            b"Enter passphrase for key '/Users/alice/.ssh/id_ed25519':\n"
-            b"Permission denied (publickey).\n"
-        ),
+        stderr=stderr,
     )
 
-    message = build_clone_failure_message(
+    return build_clone_failure_message(
         repo_url_base="owner/repo",
         plan=plan,
         dep_ref=DependencyReference(
             repo_url="owner/repo",
             host="github.com",
-            explicit_scheme="ssh",
+            explicit_scheme=explicit_scheme,
         ),
         dep_host="github.com",
         is_ado=False,
@@ -46,8 +47,42 @@ def test_clone_failure_message_explains_passphrase_protected_ssh_key() -> None:
         sanitize_git_error=lambda value: value,
     )
 
+
+def test_clone_failure_message_explains_passphrase_protected_ssh_key() -> None:
+    """SSH passphrase failures must tell users how to unblock non-interactive clones."""
+    message = _clone_failure_message(
+        stderr=(
+            b"Enter passphrase for key '/Users/alice/.ssh/id_ed25519':\n"
+            b"Permission denied (publickey).\n"
+        ),
+        explicit_scheme="ssh",
+    )
+
     assert "SSH authentication failed" in message
     assert "ssh-add <key-file>" in message
     assert "ssh-agent" in message
     assert "token-backed HTTPS" in message
     assert "will not open a raw passphrase prompt" in message
+
+
+def test_clone_failure_message_explains_explicit_ssh_publickey_failure() -> None:
+    """Explicit SSH publickey denials should get the same non-interactive guidance."""
+    message = _clone_failure_message(
+        stderr=b"Permission denied (publickey).\n",
+        explicit_scheme="ssh",
+    )
+
+    assert "SSH authentication failed" in message
+    assert "ssh-add <key-file>" in message
+    assert "token-backed HTTPS" in message
+
+
+def test_clone_failure_message_omits_ssh_diagnostic_for_non_ssh_publickey_text() -> None:
+    """Publickey text on a non-SSH dependency must not produce SSH-only guidance."""
+    message = _clone_failure_message(
+        stderr=b"Permission denied (publickey).\n",
+        explicit_scheme=None,
+    )
+
+    assert "SSH authentication failed" not in message
+    assert "ssh-add <key-file>" not in message