feat(transport): TransportSelector + strict-by-default transport (#778)

[danielmeppiel]

Summary

Closes #778. Closes #328. Follow-up to #661 / #665.

Independent of #700 (HTTP-allow validation) — zero overlap; either can merge first. See "Independence from #700" below.

This PR implements Transport Selection v1: APM now distinguishes "user expressed a transport preference" from "user expressed none" instead of running the same permissive HTTPS-then-SSH chain for everything.

What changes for users

Scenario	Before this PR	After this PR
ssh://host/repo.git	Silently downgraded to HTTPS on SSH failure (#661 hazard)	Strict SSH-only. Fails loudly naming the SSH URL.
https://host/repo.git	Could fall through to SSH	Strict HTTPS-only.
owner/repo shorthand, no git config insteadOf	HTTPS first, then SSH on failure	HTTPS only (strict).
owner/repo shorthand, git config url.git@host:.insteadOf https://host/	HTTPS only — never tried SSH (#328)	SSH first (strict), matching git clone owner/repo behavior on that machine.
Need today's permissive multi-protocol chain	Default	Set APM_ALLOW_PROTOCOL_FALLBACK=1 (or --allow-protocol-fallback). When fallback runs, a [!] warning names both protocols.

Migration / non-breaking transition for current users

This is a ### Changed (BREAKING) entry, but the rescue is one env var. The PR was scoped explicitly so a current user with a CI pipeline that depended on the silent-fallback can keep working with a single line:

env:
  APM_ALLOW_PROTOCOL_FALLBACK: "1"

The CHANGELOG entry leads with this, the new docs page leads with this, and the error message that triggers when a strict clone fails names both the URL and the rescue env var.

New CLI surface

On apm install:

• --ssh / --https — pick the initial transport for shorthand URLs (mutually exclusive). Explicit-scheme URLs ignore CLI prefs.
• --allow-protocol-fallback — opt back into the legacy permissive chain.

Env vars (apply globally, picked up by both CLI and programmatic callers):

• APM_GIT_PROTOCOL=ssh|https
• APM_ALLOW_PROTOCOL_FALLBACK=1

Independence from #700

• feat: support allow-insecure HTTP dependencies #700 = HTTP-allow validation (src/apm_cli/install/validation.py + apm.yml parser).
• Transport Selection v1: honor user-specified transport, no silent downgrade #778 = clone-attempt branching (src/apm_cli/deps/github_downloader.py + new transport_selection.py + CLI flags).
• git diff --stat main..HEAD shows zero edits in feat: support allow-insecure HTTP dependencies #700's territory. Trivial CHANGELOG conflict possible; both can merge in either order.

Architecture

New module src/apm_cli/deps/transport_selection.py (~310 LOC) extracts the decision from the orchestrator:

• ProtocolPreference enum (NONE / SSH / HTTPS).
• TransportAttempt frozen dataclass — pure data, comparable with ==, no closures.
• TransportPlan frozen dataclass — (attempts, strict, fallback_hint).
• InsteadOfResolver Protocol; default GitConfigInsteadOfResolver shells out git config --get-regexp '^url\..*\.insteadof$'. Lazy load, double-checked locking around the cache.
• TransportSelector.select(dep_ref, cli_pref, allow_fallback, has_token) -> TransportPlan.

GitHubPackageDownloader._clone_with_fallback now consumes a TransportPlan and iterates plan.attempts instead of running the hardcoded chain. URL building stays in the orchestrator (existing _build_repo_url honors use_ssh, token).

Critical invariant kept: GitConfigInsteadOfResolver._load_rewrites() runs with the process's normal env (NOT the downloader's locked-down git_env which sets GIT_CONFIG_GLOBAL=/dev/null). Otherwise issue #328 would be unfixable because the user's insteadOf config would be invisible.

Per-attempt clone env (Wave 2 panel finding, fixed in commit 724f8e7)

The first cut decided the clone env (locked-down vs relaxed) once per dependency from has_token. Under --allow-protocol-fallback the plan can mix attempts of different use_token values, so SSH + plain-HTTPS attempts in a mixed chain were running with GIT_ASKPASS=echo + GIT_CONFIG_GLOBAL=/dev/null + GIT_CONFIG_NOSYSTEM=1 — breaking ssh-agent passphrase prompts, gh auth, Keychain.

Fix:

• _env_for(attempt.use_token) per-attempt closure: only token-bearing attempts get the locked-down env.
• Adjacent contract bug: _build_repo_url(token=None) fell back to self.github_token, so "plain HTTPS" attempts in a mixed chain still embedded the token in the URL — violating the use_token=False contract. Fixed via empty-string sentinel: token="" means explicit "no token" and is what the orchestrator now passes for non-token attempts.
• Regression test test_allow_fallback_env_is_per_attempt_not_per_dep drives a 3-attempt mixed chain and asserts auth-HTTPS=locked-down, SSH=relaxed, plain-HTTPS=relaxed-and-tokenless.

Also fixed concurrency: GitConfigInsteadOfResolver cache lazy-load now uses double-checked locking with threading.Lock so parallel downloads can't double-populate.

Tests

Suite	Count	Notes
tests/unit/test_transport_selection.py (NEW)	30	14-row selection matrix; env helpers; resolver caching; "must use normal env" contract
tests/unit/test_auth_scoping.py (regression)	+1	Per-attempt env in mixed chain + plain-HTTPS token-leak guard
tests/integration/test_transport_selection_integration.py (NEW)	7	2 always-on (public shorthand HTTPS, explicit https:// strict) + 5 SSH-required (explicit ssh:// strict, bad-host no-fallback, insteadOf override, APM_GIT_PROTOCOL=ssh, allow_fallback rescue). Gated on APM_RUN_INTEGRATION_TESTS=1; SSH cases auto-skip if no key.
scripts/test-integration.sh	+1 block	Runs the integration suite in CI

Full unit suite: 4061 passed (was 4029; +32 net new).

APM Review Panel sign-off

Synthesized review across the panel personas (per .github/skills/apm-review-panel/).

python-architect (Wave 0 + 2): VERDICT: ship. All 6 mandatory edits from the Wave 0 verdict applied. Two deliberate scope-shrinks acknowledged: (1) _clone_with_fallback not renamed to _clone_with_transport (5+ tests patch it by name); (2) list_remote_refs (~line 876 in github_downloader.py) still hardcodes HTTPS — flagged as fast-follow, not in scope.

supply-chain-security-expert: Strict-by-default closes the induced-downgrade hazard #661 was filed for. Token-leak guard in plain-HTTPS attempts is a meaningful additional hardening discovered during the fix. Escape hatch is ### Changed (BREAKING)-documented and gated by an explicit env var, not implicit. APPROVED.

auth-expert: _env_for per-attempt is the correct contract — token attempts must run locked-down, non-token attempts must let credential helpers (gh auth, Keychain, ssh-agent) work. The token="" sentinel is documented in the source. Resolver _load_rewrites() running with normal env (not git_env) is correct and is the ONLY way to honor user insteadOf config. APPROVED.

devx-ux-expert: Migration story is one env var, named in the error message that triggers the broken case. Three new flags (--ssh, --https, --allow-protocol-fallback) plus three new env vars (APM_GIT_PROTOCOL, APM_ALLOW_PROTOCOL_FALLBACK) document cleanly in CLI ref + dependencies guide; warning on permitted fallback names both protocols. Migration-UX deviation noted: under allow_fallback=True we let explicit-scheme URLs fall through to the shorthand chain rather than staying strict. Architect's Wave 0 verdict said "explicit_scheme always strict." Deviation kept on purpose — users explicitly opting into fallback mode are saying "I want today's behavior" and should get it for explicit URLs too. APPROVED with deviation acknowledged.

cli-logging-expert: [!] warning format on permitted fallback matches STATUS_SYMBOLS convention. Errors on strict-mode failure name the URL and the rescue env var. Per-(url, from-to) dedup avoids warning fatigue. APPROVED.

oss-growth-hacker: Closing #328 (community pain on shorthand+SSH) is the highest-leverage win in this PR — closes a frequently-cited friction. Strict default also positions APM as a safer choice vs alternatives. APPROVED.

apm-ceo (final call): SHIP. Pre-1.0 breaking change with a one-flag rescue is consistent with CONTRIBUTING.md philosophy. The combination — closes #328, fixes #661 hazard, ships independently of #700 — is high-leverage. Wave 5 sign-off granted.

Risks & known follow-ups (out of scope for this PR)

• list_remote_refs (~line 876 of github_downloader.py) still hardcodes HTTPS. Architect-flagged fast-follow; tracked separately.
• git config --get-regexp requires git ≥ 1.8.5; older git silently degrades to no insteadOf detection (today's behavior).

---

Refs #778, #328, #661, #665, #700, #777

[danielmeppiel]

Visual reference for reviewers

Three diagrams to make the PR easier to read end-to-end. All flows live in src/apm_cli/deps/transport_selection.py (TransportSelector.select) and src/apm_cli/deps/github_downloader.py (_clone_with_fallback).

1. Selection: input -> TransportPlan

How TransportSelector.select(dep_ref, cli_pref, allow_fallback, has_token) decides which attempts to make and whether they are strict.

flowchart TD
    Start[apm install dep_ref] --> Parse{URL kind?}

    Parse -->|"explicit ssh://"| ExSsh[plan: SSH only]
    Parse -->|"explicit https://"| ExHttps[plan: HTTPS only]
    Parse -->|"shorthand owner/repo"| Short[Look up insteadOf]

    Short --> InsteadOf{"git config<br/>url.&lt;base&gt;.insteadOf<br/>rewrites to SSH?"}

    InsteadOf -->|yes| ShortSsh[first attempt: SSH]
    InsteadOf -->|no| CliPref{CLI / env preference?}

    CliPref -->|--ssh / APM_GIT_PROTOCOL=ssh| ShortSsh
    CliPref -->|--https / APM_GIT_PROTOCOL=https / unset| ShortHttps[first attempt: HTTPS]

    ExSsh --> Fb1{allow_fallback?}
    ExHttps --> Fb1
    ShortSsh --> Fb2{allow_fallback?}
    ShortHttps --> Fb2

    Fb1 -->|no| StrictExplicit["TransportPlan(<br/>attempts=[picked_protocol],<br/>strict=True)"]
    Fb1 -->|yes| FallExplicit["TransportPlan(<br/>attempts=[picked, other],<br/>strict=False,<br/>warn on cross-protocol)"]

    Fb2 -->|no| StrictShort["TransportPlan(<br/>attempts=[first],<br/>strict=True)"]
    Fb2 -->|yes| FallShort["TransportPlan(<br/>attempts=[first, other,<br/>plain-https if has_token],<br/>strict=False)"]

    classDef strict fill:#d4edda,stroke:#28a745,color:#000
    classDef permissive fill:#fff3cd,stroke:#856404,color:#000
    class StrictExplicit,StrictShort strict
    class FallExplicit,FallShort permissive

Loading

Green = new strict default. Yellow = legacy permissive chain, only reachable via --allow-protocol-fallback / APM_ALLOW_PROTOCOL_FALLBACK=1.

2. Orchestration: per-attempt env + token contract

How _clone_with_fallback walks the plan. The fix from the Wave 2 gate lives in the _env_for(attempt.use_token) decision and the token="" empty-string sentinel.

flowchart TD
    In["plan = TransportPlan(attempts, strict)"] --> Loop{for attempt in attempts}

    Loop --> EnvDecide{attempt.use_token?}

    EnvDecide -->|true| Locked["env = self.git_env<br/>(GIT_ASKPASS=echo,<br/>GIT_CONFIG_GLOBAL=/dev/null,<br/>GIT_CONFIG_NOSYSTEM=1)"]
    EnvDecide -->|false| Relaxed["env = filtered process env<br/>(ssh-agent, gh auth,<br/>Keychain, ~/.gitconfig visible)"]

    Locked --> Url["url = _build_repo_url(<br/>token=dep_token if use_token else '')"]
    Relaxed --> Url

    Url --> Clone["Repo.clone_from(url, env=env)"]

    Clone --> Ok{success?}
    Ok -->|yes| Done[return path]

    Ok -->|no| Strict{plan.strict?}
    Strict -->|yes| FailLoud["raise: name URL,<br/>name protocol attempted,<br/>suggest APM_ALLOW_PROTOCOL_FALLBACK=1"]
    Strict -->|no| WarnNext["[!] warn: from->to,<br/>continue loop"]

    WarnNext --> Loop

    classDef new fill:#d4edda,stroke:#28a745,color:#000
    classDef bug fill:#f8d7da,stroke:#dc3545,color:#000
    class EnvDecide,Url new
    class FailLoud new

Loading

The two highlighted nodes are the Wave 2 fix:

• EnvDecide was previously hoisted out of the loop (decided once per dep from has_token) -- broke ssh-agent and credential helpers in mixed --allow-protocol-fallback chains.
• Url -- previously called _build_repo_url(token=None) for non-token attempts, but None triggered fallback to self.github_token, so the URL still embedded the token. token="" is now an explicit "no token" sentinel.

3. Before / after for a concrete bug case (#661)

User declares git+ssh://git@host:22/org/repo.git and SSH auth fails (e.g. ssh-agent locked).

sequenceDiagram
    autonumber
    participant U as User
    participant APM as apm install
    participant SSH as SSH transport
    participant HTTPS as HTTPS transport

    rect rgb(255, 235, 235)
        Note over U,HTTPS: Before this PR (silent downgrade hazard)
        U->>APM: install ssh://...:22/org/repo
        APM->>SSH: clone (locked-down env)
        SSH-->>APM: auth failed
        APM->>HTTPS: silently retry on https://host:22/org/repo
        HTTPS-->>APM: 200 OK (different transport, maybe different ACL)
        APM-->>U: install succeeded (user never sees the downgrade)
    end

    rect rgb(220, 245, 220)
        Note over U,HTTPS: After this PR (strict by default)
        U->>APM: install ssh://...:22/org/repo
        APM->>SSH: clone (locked-down env)
        SSH-->>APM: auth failed
        APM-->>U: error: SSH clone failed for ssh://...:22/org/repo<br/>Set APM_ALLOW_PROTOCOL_FALLBACK=1 to opt into HTTPS retry.
    end

    rect rgb(255, 250, 220)
        Note over U,HTTPS: Opt-in escape hatch (migration path)
        U->>APM: APM_ALLOW_PROTOCOL_FALLBACK=1 apm install ...
        APM->>SSH: clone (locked-down env)
        SSH-->>APM: auth failed
        APM->>U: [!] SSH failed, falling back to HTTPS for ssh://...:22/...
        APM->>HTTPS: clone (relaxed env, no token in URL if use_token=false)
        HTTPS-->>APM: 200 OK
        APM-->>U: install succeeded (with explicit consent, named in warning)
    end

Loading

The warning in the third pane is what makes the escape hatch safe: the user opted in and sees the cross-protocol retry happen; before this PR it happened silently every time.

[Copilot]

Pull request overview

Implements Transport Selection v1 so APM distinguishes explicit transport (scheme) from shorthand and becomes strict-by-default, with an opt-in legacy cross-protocol fallback via CLI/env.

Changes:

• Add TransportSelector decision engine and route clone attempts through a computed TransportPlan.
• Add apm install flags/env vars to control shorthand transport (--ssh/--https, APM_GIT_PROTOCOL) and legacy fallback (--allow-protocol-fallback, APM_ALLOW_PROTOCOL_FALLBACK).
• Add unit + integration coverage and update docs/CHANGELOG for the new contract.

Show a summary per file

File	Description
tests/unit/test_transport_selection.py	New unit test matrix for transport planning and insteadOf resolution/caching.
tests/unit/test_auth_scoping.py	Regression tests for per-attempt env + token scoping under fallback.
tests/integration/test_transport_selection_integration.py	New networked integration coverage validating strictness + overrides.
tests/fixtures/gitconfig_insteadof_to_ssh	Fixture .gitconfig for insteadOf HTTPS->SSH rewrite.
src/apm_cli/models/dependency/reference.py	Add explicit_scheme signal to parsed dependency references.
src/apm_cli/install/service.py	Thread transport prefs into the install pipeline.
src/apm_cli/install/request.py	Extend request with protocol preference + fallback toggle.
src/apm_cli/install/pipeline.py	Thread protocol preference + fallback into InstallContext.
src/apm_cli/install/phases/resolve.py	Construct downloader with protocol pref + fallback.
src/apm_cli/install/context.py	Store protocol pref + fallback on context.
src/apm_cli/deps/transport_selection.py	New transport selection module (plan + insteadOf resolver).
src/apm_cli/deps/github_downloader.py	Consume TransportPlan; implement strict-by-default cloning + warnings.
src/apm_cli/commands/install.py	Add --ssh/--https/--allow-protocol-fallback and resolve env/flag behavior.
scripts/test-integration.sh	Add CI integration test invocation for transport selection suite.
packages/apm-guide/.apm/skills/apm-usage/dependencies.md	Document strict selection + overrides + fallback escape hatch.
docs/src/content/docs/reference/cli-commands.md	Document new flags and transport env vars for apm install.
docs/src/content/docs/guides/dependencies.md	Document strict transport contract and migration/fallback guidance.
docs/src/content/docs/getting-started/authentication.md	Update SSH hang guidance and link to transport selection docs.
CHANGELOG.md	Add BREAKING/Added entries describing transport selection changes.

Copilot's findings

Comments suppressed due to low confidence (2)

CHANGELOG.md:18

• This entry is very long and doesn't match the changelog format used elsewhere (concise, one line per PR, ending with (#PR)), and it mixes multiple concerns into one bullet. Please condense and ensure the bullet ends with the PR number (e.g. (#778)).

### Added

- `apm install` accepts `--ssh` / `--https` flags and `APM_GIT_PROTOCOL=ssh|https` env to pick the initial transport for shorthand URLs. `apm install` also accepts `--allow-protocol-fallback` (env: `APM_ALLOW_PROTOCOL_FALLBACK=1`) as the escape hatch for cross-protocol fallback when migrating off the previous permissive behavior (#778).
- Add APM Review Panel skill (`.github/skills/apm-review-panel/`) and four new specialist personas (`devx-ux-expert`, `supply-chain-security-expert`, `apm-ceo`, `oss-growth-hacker`) with auto-activating per-persona skills. Routes specialist findings through an APM CEO arbiter for strategic / breaking-change calls, with the OSS growth hacker side-channeling adoption insights via `WIP/growth-strategy.md`. Instrumentation per Handbook Ch. 9 (`The Instrumented Codebase`); PROSE-compliant (thin SKILL.md routers, persona detail lazy-loaded via markdown links, explicit boundaries per persona).

docs/src/content/docs/guides/dependencies.md:155

• This excerpt contains non-ASCII punctuation (e.g. em dash "—" and Unicode arrow "→"). The repo's cross-platform encoding rules require docs to stay printable ASCII; please replace with ASCII equivalents ("--", "->", straight quotes, etc.).

>
> ```yaml
> # DON'T — ambiguous: APM can't tell where the repo path ends
> # gitlab.com/group/subgroup/repo/file.prompt.md
> #   → parsed as repo=group/subgroup, virtual=repo/file.prompt.md (wrong!)

• Files reviewed: 19/19 changed files
• Comments generated: 5

[danielmeppiel]

Both findings addressed in f179970:

1. Non-ASCII punctuation in docs/src/content/docs/guides/dependencies.md -- partial fix. Replaced the em dash in the Fields: line that I introduced with --. The other non-ASCII characters at lines ~150-160 (the "nested groups" warning block: # DON'T --, -> parsed as) are pre-existing in main and predate this PR -- the project does have a tech-debt cleanup needed for the existing docs, but doing it inside this PR would expand the diff well beyond the transport-selection scope. Tracking as a fast-follow.

2. CHANGELOG entry too long, mixed concerns -- valid. Split the original two-concern bullet into:

• One tighter ### Changed (BREAKING) entry covering the strict-by-default contract + the rescue env var.
• Two single-purpose ### Added entries: one for the initial-protocol flags (--ssh/--https/APM_GIT_PROTOCOL), one for the fallback escape hatch (--allow-protocol-fallback/APM_ALLOW_PROTOCOL_FALLBACK).

All three entries end with (#778) per Keep-a-Changelog convention.

[danielmeppiel]

Architecture: design patterns at play

A fourth diagram for reviewers who want the design rationale rather than the runtime flow.

classDiagram
    direction LR

    class ProtocolPreference {
        <<Enum>>
        NONE
        SSH
        HTTPS
    }

    class TransportAttempt {
        <<Value Object / frozen dataclass>>
        +use_ssh: bool
        +use_token: bool
        +reason: str
    }

    class TransportPlan {
        <<Value Object / frozen dataclass>>
        +attempts: list~TransportAttempt~
        +strict: bool
        +fallback_hint: str
    }

    class InsteadOfResolver {
        <<Protocol / Strategy>>
        +resolve(host) Optional~str~
    }

    class GitConfigInsteadOfResolver {
        <<Default Strategy>>
        -_cache: dict
        -_lock: Lock
        +resolve(host) Optional~str~
        -_load_rewrites()
    }

    class FakeInsteadOfResolver {
        <<Test Double>>
        +rewrites: dict
        +resolve(host) Optional~str~
    }

    class TransportSelector {
        <<Factory / Pure Function>>
        -insteadof_resolver: InsteadOfResolver
        +select(dep_ref, cli_pref, allow_fallback, has_token) TransportPlan
    }

    class GitHubPackageDownloader {
        <<Orchestrator>>
        -protocol_pref: ProtocolPreference
        -allow_protocol_fallback: bool
        -github_token: str
        -git_env: dict
        -selector: TransportSelector
        +download(dep_ref) Path
        -_clone_with_fallback(...)
        -_env_for(use_token) dict
        -_build_repo_url(..., token: str) str
    }

    class InstallContext {
        <<DI Container>>
        +protocol_pref: ProtocolPreference
        +allow_protocol_fallback: bool
    }

    class CliInstallCmd {
        <<Adapter>>
        +--ssh / --https
        +--allow-protocol-fallback
        +APM_GIT_PROTOCOL env
        +APM_ALLOW_PROTOCOL_FALLBACK env
    }

    InsteadOfResolver <|.. GitConfigInsteadOfResolver : implements
    InsteadOfResolver <|.. FakeInsteadOfResolver : implements
    TransportSelector o-- InsteadOfResolver : injected (Strategy)
    TransportSelector ..> TransportPlan : returns
    TransportPlan o-- TransportAttempt : composed of
    TransportSelector ..> ProtocolPreference : consumes
    GitHubPackageDownloader o-- TransportSelector : composed
    GitHubPackageDownloader ..> TransportPlan : iterates
    InstallContext ..> GitHubPackageDownloader : configures
    CliInstallCmd ..> InstallContext : populates

Loading

Patterns mapped

Pattern	Where	Why it matters here
Strategy (via typing.Protocol)	InsteadOfResolver + GitConfigInsteadOfResolver / FakeInsteadOfResolver	Tests can swap in a fake without subprocess shelling; future hosts (e.g. Mercurial-style rewrites) plug in without touching TransportSelector.
Value Object (frozen dataclass)	TransportAttempt, TransportPlan	Plans are comparable with ==, hashable, safe to share across threads, and cheap to construct in tests. No behavior on the data -- forces the decision to live in TransportSelector.select().
Pure-function Factory	TransportSelector.select(...)	Same inputs always produce the same plan. The 14-row test matrix becomes assert select(...) == TransportPlan([...]). No side effects, no I/O (the only I/O is the resolver, which is injected).
Separation of policy / mechanism	transport_selection.py (policy) vs github_downloader.py (mechanism)	Selection logic is testable without git, without network, without filesystem. Clone logic stays focused on URL building + subprocess + retry.
Closure as per-attempt strategy	_env_for(use_token) inside _clone_with_fallback	Captures self.git_env once but lets the env switch per attempt within the loop. Avoids hoisting the decision out of the loop (the bug Wave 2 caught).
Sentinel value	token="" in _build_repo_url	Distinguishes "explicit no token" from "use the instance default" (None). Without it, use_token=False attempts in mixed chains silently embedded the token in the URL.
Lazy init + double-checked locking	GitConfigInsteadOfResolver._cache + threading.Lock	First resolve pays the git config subprocess cost; subsequent resolves are O(1) dict lookups. Lock prevents redundant subprocess calls under parallel downloads.
Adapter	CLI command + env-var resolvers in commands/install.py	Translates CLI flags / env vars into the typed ProtocolPreference enum + allow_fallback: bool that the install pipeline consumes. Programmatic callers (no CLI) get the same defaults via protocol_pref_from_env() / is_fallback_allowed().
Dependency injection through context	InstallRequest -> InstallContext -> GitHubPackageDownloader ctor	Transport prefs flow as data, not as globals. Each install run is reproducible from its InstallRequest.

What this design buys reviewers

• The selection decision is one function with a 14-row test matrix -- no mocks, no subprocess, no filesystem. If the matrix changes, the test changes; if the matrix doesn't change, neither does the test.
• The orchestrator stays agnostic to selection rules. Adding a new rule (e.g. "honor pushInsteadOf") means changing TransportSelector.select() and adding rows to the matrix -- not editing _clone_with_fallback.
• The escape hatch is one boolean flowing through one frozen field on the plan. There is no runtime branching elsewhere -- the orchestrator's if plan.strict: break is the entire enforcement.

[danielmeppiel]

Integration with neighboring systems

How TransportSelector composes with the rest of the install pipeline.

1. Lockfile repo_url -- transport-agnostic by design

LockedDependency.repo_url is a bare owner/repo (or org/project/repo for ADO). It does not include the scheme or host. That is the right choice and TransportSelector preserves it:

• A dependency installed today over SSH and re-installed tomorrow over HTTPS produces the same lockfile entry.
• Identity (get_unique_key()) returns repo_url -- so duplicate detection works regardless of which transport the user chose.
• Switching APM_GIT_PROTOCOL between machines does not invalidate the lockfile.

The transport choice is a property of the clone attempt, not the identity of the package. Selection happens fresh on every install from (dep_ref, env, CLI flags) -- nothing is persisted.

2. Lockfile port -- preserved verbatim across attempts

port: Optional[int] was added on DependencyReference and LockedDependency in #665 as a first-class field. TransportSelector does not read it; the orchestrator's _build_repo_url(host, port=dep_ref.port, ...) re-emits it on every attempt regardless of the picked scheme:

ssh://host:7999/org/repo  -- port=7999 captured into dep_ref.port
                          -> first attempt:  ssh://host:7999/org/repo
                          -> if --allow-protocol-fallback fires:
                                              https://host:7999/org/repo

The port survives the cross-protocol retry. This was the explicit fix for #661 and remains intact under the new strict-by-default contract -- the only behavioral change is that the cross-protocol retry now requires opt-in.

3. apm-policy.yml -- gap, not conflict

The current policy schema has McpTransportPolicy (which restricts MCP server transport: stdio / sse / http) but no equivalent governance for git transport. Today there is no:

• policy.git_transport.allowed = [ssh, https]
• policy.git_transport.forbid_fallback = true
• policy.git_transport.allow_http = false

This is a gap, not a conflict -- TransportSelector reads CLI/env, not policy. Worth filing as a follow-up: org-level enforcement of strict-only across CI (so a contractor cannot set APM_ALLOW_PROTOCOL_FALLBACK=1 in their pipeline to bypass the security improvement) is a natural next step. The hook points are clean:

• commands/install.py resolves protocol_pref and allow_fallback -- the policy check would short-circuit there.
• policy/schema.py already has the inheritance/discovery infra; a GitTransportPolicy would slot in next to McpTransportPolicy.

Out of scope for #778; flagging for a future issue.

4. Artifactory / PROXY_REGISTRY_URL -- different code path entirely

When PROXY_REGISTRY_URL (or the deprecated ARTIFACTORY_BASE_URL) is set, the dependency download path branches:

• Proxied registry path (registry_proxy.RegistryClient.fetch_file / artifactory_entry.fetch_entry_from_archive): pulls files / archives over HTTP(S) GET from the configured proxy. TransportSelector is not involved -- there is no git clone. The proxy URL's scheme (https://artifactory.corp/...) is the only protocol in play, and it is fixed by the env var.
• Direct git path (_clone_with_fallback): TransportSelector decides the scheme. Fires when no proxy is configured, or when the proxy host does not match the dep host (FQDN mismatch in download_file_from_artifactory() falls back to the standalone helper).

Practical implications:

• Orgs using PROXY_REGISTRY_ONLY=1 are unaffected by the new strict-by-default behavior -- they never reach the git clone code path. The breaking change does not regress them.
• Orgs using the proxy as a cache (not enforce-only) hit the git path for cache misses; they get the new strict default, which is the correct outcome.
• No interaction between APM_GIT_PROTOCOL and PROXY_REGISTRY_URL -- they govern disjoint transports.

flowchart LR
    Install[apm install dep_ref] --> Cfg{PROXY_REGISTRY_URL set?}

    Cfg -->|yes, host matches| Proxy[fetch_file via RegistryClient<br/>HTTPS GET to proxy URL<br/>TransportSelector NOT used]
    Cfg -->|no, or host mismatch| Git[git clone via _clone_with_fallback]

    Git --> TS[TransportSelector.select<br/>builds TransportPlan]
    TS --> Loop[orchestrator iterates plan.attempts<br/>port preserved on every attempt]
    Loop --> Lock["LockedDependency<br/>(repo_url, port -- no scheme)"]

    Proxy --> Lock

    classDef bypass fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef new fill:#d4edda,stroke:#28a745,color:#000
    class Proxy bypass
    class TS,Loop new

Loading

Summary table

Surface	Interaction with TransportSelector	Status after #778
LockedDependency.repo_url	Identity is transport-agnostic; selection runs fresh on every install	Unchanged
LockedDependency.port	Read by _build_repo_url, re-emitted on every attempt	Unchanged (#661 fix preserved)
apm-policy.yml	No git_transport policy field today	Gap; future opportunity for org-level enforcement of strict-only
PROXY_REGISTRY_URL / Artifactory	Disjoint code path (HTTP file fetch, not git clone)	Unchanged; proxy users unaffected

The net effect: the breaking change is localized to the direct-git-clone code path, which is exactly the surface that #661 / #328 were filed against. Lockfile, port handling, and proxy users see no behavior change.

[danielmeppiel]

Indicate here APM < 0.8.13

[danielmeppiel]

Done in 51ab924. Tightened the caution panel to:

Breaking change in APM 0.8.13 -- APM versions before 0.8.13 silently retried failed clones across protocols. Starting in 0.8.13 the behavior is strict by default [...]

That makes the version cutover unambiguous for anyone landing on this page from a search result without scrolling to the changelog.

While here, also took care of the four other Copilot review findings in the same commit:

• transport_selection.py -- collapsed the explicit == "http" branch into plain HTTPS so TransportAttempt.scheme stays in {ssh, https} and the downloader contract is consistent. Plain http:// URLs now build an HTTPS attempt with no token (no cleartext credential leak possible) until feat: support allow-insecure HTTP dependencies #700 introduces a first-class HTTP transport with explicit --allow-insecure gating.
• github_downloader.py -- the [!] "Protocol fallback" warning is now gated on actual scheme change (ssh <-> https) rather than label change, so an auth-only downgrade inside a single protocol (e.g. authenticated HTTPS -> plain HTTPS in a --ssh + --allow-protocol-fallback mixed plan) is no longer misreported as a protocol switch.
• pipeline.py / request.py / context.py / commands/install.py -- allow_protocol_fallback is now Optional[bool] = None end-to-end. Non-CLI programmatic callers regain the documented "None => read APM_ALLOW_PROTOCOL_FALLBACK env" behavior. The CLI still resolves env at the command boundary so behavior there is unchanged.
• tests/unit/test_auth_scoping.py -- replaced the one stray Unicode arrow with -> to satisfy the ASCII-only source rule.

All 4061 unit tests pass.