## Code Review — PR #1475: route cluster-addressed mirror commands to the cluster's core

### Overview

Fixes mirror mutation verbs (`create`/`remove`, `collaborators add`/`remove`/`list`) 400ing with `unknown cluster_host` when the active context's core doesn't front the target cluster. The insight is sound: these are the CLI's first _cluster-anchored_ control-plane calls — the core to dial is a property of the supplied `<cluster-host>`, not the active login. The fix routes them through `/.well-known/entire-cluster.json` discovery, exactly mirroring the established git (`NewRepoTokenSource`) and data-API resolution paths. Identity-anchored commands (`repo create/list`, `mirror list/get`) correctly stay on the active context.

### Strengths

- **Architecturally consistent.**`ResolveControlPlaneTargetForCluster` reuses the same `resolveContextForCluster` seam, `userdirs.Config()/Cache()`, and `repoExchangeTransportForTest` as the repo-token path — no new discovery machinery, just a new entry point. This is the right call.
- **Clean, behavior-preserving refactors.**`targetForContext`, `clientFromEnvToken`, `clientForTarget`, `runCoreClient`, and `renderCoreList` are all pure extractions that leave the active-context path identical and isolate the cluster variants to "which core does `newClient` dial." Verified the non-cluster commands are untouched.
- **Strong test.**`TestResolveControlPlaneTargetForCluster_DialsClusterCoreNotActive` deliberately seeds a token _only_ for the cluster core, so a regression that dialed the active context fails loudly rather than passing by luck — exactly the right way to test a routing fix. Empty-host guard is covered too.
- **Documentation is thorough** and the `NO TRUST GATE` reasoning (env-token sent verbatim as bearer vs. exchanged as STS subject_token → no aud-redirection escalation) is correctly carried forward and extended to `NewForCluster`.

### Issues / suggestions

**1\. `mirror list` header can lie when `ENTIRE_TOKEN` is set (low severity).** The header calls `auth.ResolveControlPlaneTarget()`, which ignores `ENTIRE_TOKEN` and resolves from the active context. But the actual request via `coreapi.New()` honors `ENTIRE_TOKEN` and dials the _token's_ aud. If both `ENTIRE_TOKEN` **and** a `contexts.json` are present, the header would name the context core while the request hits a different core.

**2\. Double resolution for the `mirror list` header (cosmetic).** The target is resolved once for the header and again inside `runCoreList → coreapi.New()`. Harmless (active-context path is local, no network) but slightly redundant; not worth restructuring unless #1 prompts a touch-up there anyway.

**3\. No coverage of the discovery-error / login-hint path** through `NewForCluster`. The "no eligible context → login hint" behavior is the user-facing payoff described in the doc comment, but it lives in `clusterdiscovery.ResolveContextForCluster` (stubbed in tests). Assuming that's tested in `clusterdiscovery`, this is fine — just noting the new wrapper only has the happy path and empty-host covered.

### Risk

Localized to cluster-scoped mirror commands; the active-context and env-token paths are provably unchanged by the refactor. The main residual risk is mis-discovery sending a mutation to the wrong federation, but that's the same trust path git/data-API already rely on. Cursor's "Medium Risk" framing is fair.

**Verdict: approve.** The fix is correct and well-tested. Issue #1 is the only one I'd consider addressing before merge (a one-line guard); #2 and #3 are optional.

## Summary

**Branch:**`fix/mirror-list-header-env-token` (off `fix/control-plane-cluster-routing`, since the header code only exists on the PR branch — not yet on `main`)

**The fix:** The `mirror list` stderr banner called `auth.ResolveControlPlaneTarget()`, which ignores `ENTIRE_TOKEN`. In env-token mode the request actually dials the token's own `aud` (via `coreapi.New` → `clientFromEnvToken`), so when both `ENTIRE_TOKEN` and a `contexts.json` were present, the banner named a core the request never talks to. Now the banner is skipped whenever `ENTIRE_TOKEN` is set.

**What changed:**

- Extracted the inline banner logic into a pure, testable `mirrorListHeader(json bool) string` helper that returns `""` for the three skip cases (`--json`, env-token set, no resolvable context) and the `"Listing mirrors on <core>"` string otherwise.
- Added `TestMirrorListHeader` covering all four cases — the key one asserts the banner is suppressed even when a resolvable active context exists, proving the env-token guard wins.

**Verification:**`mise run fmt` + `mise run lint` (0 issues) + full `cmd/entire/cli` package tests pass.

Note this is stacked on the unmerged PR #1475, so it should either merge after #1475 lands or be folded into it. Want me to push the branch and open a PR (targeting `fix/control-plane-cluster-routing`), or leave it local?