Context-Aware Control-Plane Target Resolution

Done auditing. Here's the bottom line before we pick a direction.

Bottom line

The mechanism you're describing already exists — you don't need a new /.well-known/entire-auth.json, and entire-server likely needs zero changes. The blast radius is a wiring job in the CLI, not new protocol/server work. Two facts change the framing:

1. The discovery endpoint already exists: /.well-known/entire-cluster.json on the data plane returns core_urls (the login/core servers it accepts auth from) — exactly your "I'll accept auth from [au/us.auth.partial.to]" idea. There's also /.well-known/entire-federation on cores for cross-region peers.
2. The CLI already has the full resolver in internal/entireclient/clusterdiscovery: ResolveContextForCluster(host) → *contexts.Context. Given a data host, it fetches+caches the well-known, reads core_urls, and picks the login context whose CoreURL matches (active-context-wins → sole-eligible → error on zero/ambiguous). git-remote-entire already uses this for every clone/push. The main CLI commands just don't.

So ENTIRE_API_BASE_URL=https://partial.to entire activity auto-discovering us.auth.partial.to is ResolveContextForCluster("partial.to") — which is written, tested, and shipping. We're lifting it into the rest of the CLI.

Audit: who resolves hosts how

Inflection points: ~24 call sites funnel through ~5 constructors (coreapi.New, NewAuthenticatedAPIClient, auth.NewClient, dispatch NewCloudClient, search.Search). Retarget those 5 and everything downstream follows.

The one real risk

The default no-env case: does prod entire.io actually serve /.well-known/entire-cluster.json advertising us.auth.entire.io? The endpoint is implemented on the entiredb data-plane server, but if the prod entire.io deployment doesn't serve it, discovery breaks for normal users and we need a static fallback. That's an ops fact I can't verify from this repo.

A few forks decide how much we bite off. Let me get your calls:

Plan confirmed and low-risk — no tests pin those symbols. Let me track this and start building.

Fair — "three families" is the wrong framing and I muddied it. There aren't three auth systems. There's one identity model and a set of resource servers. Let me restate cleanly:

One identity provider (the "core" / login server): entire-core (e.g. us.auth.entire.io). This is what mints your JWT, what contexts.json is keyed on (CoreURL), and — co-located — it also serves the control-plane CRUD (/api/v1/orgs, repos, grants). An auth context is a login to one core.

Resource servers that trust a core and accept its JWTs:

• the git cluster = entiredb/entire-server (git-remote-entire hits it)
• the web/data API = entire.io (activity/search/trail/dispatch)

So the "three" I sloppily named were really: the core (1 thing, both IdP + control-plane) plus two resource servers. The only reason they looked like peers in my audit is that the CLI currently resolves each one's host independently from env vars.

The unifying model you're after is just:

An auth context = a login to one core. Every upstream call resolves to some host; that host either is a core (control plane → use the context's CoreURL directly) or is a resource server that advertises which cores it trusts (via a .well-known), so the CLI picks the matching context and exchanges its token for that resource.

• Cluster already does this (entire-cluster.json → core_urls → clusterdiscovery).
• Control plane needs no discovery — the host is the core. ← today's slice.
• entire.io is the gap: it needs to grow the same kind of .well-known so the CLI can map it back to a core/context.

So today's work is unchanged. I'll fix the design-doc framing to "one core + resource servers," not "three families." Want me to proceed with the build on that framing?

Today = the control-plane slice only. Concretely:

What changes: org, repo, project, grant (every command behind runCore → coreapi.New()). Right now they always dial the static default core (us.auth.entire.io unless ENTIRE_AUTH_BASE_URL is set) and resolve the token from a singleton manager pinned to that same host. So if you've entire auth use'd a context on a different core, these commands silently ignore it — the exact bug pattern your handover flagged.

The fix: make coreapi.New() resolve its host + token from the active context instead of the static default. Since the control-plane host is the core, there's no .well-known discovery here — just "use the active context's CoreURL and its token." Precedence:

1. ENTIRE_AUTH_BASE_URL explicitly set → unchanged (override wins).
2. else active context → its CoreURL + a per-context refreshing token source (this is where silent JWT refresh lands for the control plane — a down payment on COR-389, reusing the existing NewRefreshingLoginProvider).
3. else → static default (today's behavior for users who never ran auth use).

Deliverables (the 5 tasks):

• api.AuthBaseURLOverridden() + auth.insecureHTTPEnabled() readers
• auth.ResolveControlPlaneTarget() — the shared resolver
• rewire coreapi.New() through it
• unit tests for precedence + the token-source wiring
• a short design doc in the "one core + resource servers" framing, recording what's deferred

What today explicitly does NOT touch:

• Cluster (git-remote-entire) — already context-aware, nothing to do.
• entire.io API family (activity/search/trail/dispatch) — deferred; needs the new entire-api.json well-known on your side first + the audience token-exchange. Design only.

Net user-visible effect after today: entire auth use <ctx> actually retargets org/repo/project/grant to that context's core, and their tokens refresh silently. Want me to build it?

All 6077 tests pass; lint clean. Done.

Bottom line

org/repo/project/grant now follow the active auth context instead of the static default core — and refresh their token silently. Override and no-context paths are unchanged. The web/data API family (activity/search/trail/dispatch) is designed but deferred (needs the entire.io well-known you'll add).

What changed

• auth.ResolveControlPlaneTarget() (cmd/entire/cli/auth/control_plane.go) — the shared resolver. Precedence: ENTIRE_AUTH_BASE_URL set → static (unchanged) → else active context's CoreURL + per-context refreshing bearer → else static default.
• coreapi.New() now consults the resolver; bearerSource → providerSource (token-func backed). NewWithBearer (used by auth status) untouched.
• api.AuthBaseURLOverridden() + auth.insecureHTTPEnabled() — the two small readers the resolver needs.
• Tests: resolver precedence (override / active context / fallback) + providerSource bearer/error/session-skip mapping.
• docs/architecture/upstream-host-resolution.md — the "one core + resource servers" model, what's done, and the deferred entire-api.json work (incl. the audience field the cluster blob lacks).

The mechanism (silent refresh)

The old singleton manager is pinned to AuthBaseURL() as issuer — wrong store/STS host for a context on another core. The per-context provider keys its manager on c.CoreURL, so refresh/STS hit the right core and an expired access token is re-minted from the stored refresh token. That's the COR-389 prize landing for the control plane.

Manual sanity check (I can't hit a live core from here)

Not committed — yours to commit/push. Want me to start the deferred API-family slice, or stop here?

Done. Three commits, tree clean, nothing pushed.

Each is self-contained (builds + lints independently — readers ship with the resolver that uses them, so no unused-symbol gap). Yours to push.

Done. Tree clean, nothing pushed.

Answer to your question

That warning was stale, not next-bit work — my control-plane change made it wrong. It claimed auth use doesn't retarget org/repo/grant; now it does. (auth status already retargeted since #1341, so it was half-wrong even before.) Removed it.

Chasing it also surfaced a real inconsistency I'd introduced — fixed per your call:

Two follow-up commits

• c6bee36e1e — active context wins over ENTIRE_AUTH_BASE_URL (env is fallback-only, matching auth status). Dropped the now-dead AuthBaseURLOverridden helper. A token from core B can't auth against core A, so override-host-with-context-identity never made sense.
• b27626a386 — removed warnIfCrossCoreContext + its test; rewrote auth use help to say control-plane commands follow the active context, and that the data-API commands (activity/search/trail/dispatch) don't yet — that note is the honest pointer to the next slice.

Lint clean, affected tests green (cli, auth, api, coreapi). Five commits total on the branch now. The genuine remaining gotcha — data-API commands ignoring the context — is exactly the entire.io .well-known work you'll add next.

Pushed to cor-389-control-plane-context-aware. Here's my suggested PR — not created yet, your review first:

Title: COR-389: control-plane commands follow the active auth context

Body:

entire auth use <ctx-on-another-core> entire org list # now hits that context's core, with a silently-refreshed token

Two things to confirm:

• CI caveat: I ran unit tests + lint, but not the full mise run test:ci (integration + canary). Want me to run it before you merge? The "Test" line currently overclaims slightly — I'll soften it to "unit tests + lint green" unless you want me to actually run the full suite now.
• Anything to add/cut, or change the title?

Force-push failed — your SSH signing agent (Secretive) couldn't sign, likely needs a Touch ID approval that didn't reach this subprocess. The rebase is done locally and clean; it just needs your agent.

Please run it yourself so the agent can prompt you:

Once that lands, I'll create the draft PR with the description above (I'll soften the Test line to match what I actually ran — unit tests for the affected packages + lint clean; I did not run full mise run test:ci). Want me to run the full mise run test:ci before creating the PR, or create it now and you run CI via the PR?

Draft PR created: https://github.com/entireio/cli/pull/1367

• Branch cor-389-control-plane-context-aware, rebased clean on latest main (resolved the conflict with the new completeContextNames shell-completion — kept it, dropped the stale warning).
• Draft, base main, 5 commits.
• Test line states the truth: unit tests for affected packages + lint clean; full test:ci left to CI.

Say the word if you want me to run mise run test:ci locally before you mark it ready, or tweak the description/title.

Lint clean, tests green. Committing the review fixes:

Pushed (fast-forward 2fae4e2297..0b6eacfa90). The "remote helper 'entire' aborted" noise is the checkpoint-remote helper, not the branch push — the branch updated fine.

Bottom line

Both review comments addressed; no user-facing "core" remains in the PR's changes.

• Help text (auth use): "the context's core" → "the context's login server".
• Error strings: build core API client → build Entire API client (both New and NewWithBearer).
• New() doc comment: corrected the precedence (active context wins; ENTIRE_AUTH_BASE_URL is fallback, not override) and scoped the "always wins" claim — true only because control-plane commands have no resource host to match against, unlike clone / the data API (your point).
• Reconciled with your Fix comment. (Copilot Autofix): it partially fixed the same doc comment; my fuller rewrite supersedes it. Rebased my one fixup commit on top, so history stays linear.

Audit result: the only user-facing "core" were those two spots. Remaining "core"/"control plane" occurrences are code comments and identifiers (internal), and "control plane" in pre-existing error text — the reviewer's rule is specifically about "core", which is now clean.

Both new comments are on the latest commit (0b6eacfa9). Here's my read — and I agree with you that the literal suggestions aren't quite right.

Comment 1 — "Contexts load error blocks fallback" (Medium, control_plane.go:42)

Their claim: if contexts.json can't be read/parsed, ResolveControlPlaneTarget returns the load error, breaking org/repo/grant — while auth status still degrades to the legacy keyring token. Inconsistent.

My read — partially valid, but their implied fix (always degrade) has a real downside:

• The factual asymmetry is true. resolveStatusTarget swallows the contexts error (if err == nil { … }) and falls through to legacy; mine propagates it.
• But contexts.Load does not error on a missing file — it returns an empty File{}. So this only fires on genuine corruption, an IO/permission error, or a flock timeout under concurrent entire processes. That last one is the interesting case: a transient lock collision would spuriously break a control-plane command.
• The counter-argument to "just degrade": control-plane commands mutate (create org, grant access). Silently falling back to a legacy keyring identity when the config is corrupt is arguably worse for a mutation than erroring — you could act as an unexpected identity. For a read-only status, degrading is harmless.

My recommendation: don't blanket-degrade. Either (a) keep failing but make the message actionable ("couldn't read contexts.json: … — fix or remove it"), or (b) degrade only for transient/lock errors and surface genuine corruption. I lean (a) — simplest, and corruption is rare. The consistency-with-status argument is weaker than it looks because the two commands have different blast radius (read vs write).

Comment 2 — "Missing ErrNotLoggedIn in token chain" (Medium, client.go:90)

Their claim: in the active-context path, missing creds come back from NewRefreshingLoginProvider without wrapping auth.ErrNotLoggedIn, so providerSource.BearerAuth skips the login hint and users get a generic "resolve control-plane token" error.

My read — the diagnosis is right but their fix would make UX worse:

• True: the refreshing provider returns its own messages (no usable login for "ctx" (https://…); run ENTIRE_AUTH_BASE_URL=… entire login) without %w-wrapping the sentinel, so errors.Is is false and my code prefixes it with resolve control-plane token:.
• But that provider message is better than the generic not logged in — run 'entire login' hint — it names the specific context and the exact re-login command for that core. If we "fix" it by wrapping the sentinel so the generic hint fires, we'd replace the tailored message with the worse one.
• The only actual wart is the redundant resolve control-plane token: prefix on an already-complete message.

My recommendation: drop the prefix in the else-branch — return the provider's error verbatim — and keep the ErrNotLoggedIn → friendly hint mapping for the static path (where TokenForResource does return a bare sentinel). Net: static path still gets the standard hint; active-context path shows its tailored, core-specific hint cleanly. That satisfies the rule's intent (a login hint when not logged in) without downgrading the message.

So: comment 2 I'd fix, but not their way. Comment 1 is a genuine judgment call — fail-loud-but-clearer vs degrade-like-status. Which way do you want to lean on each? And do you want me to reply on the PR threads explaining the reasoning, or just push fixes?

Pushed — remote now at 6621920f51.

Done — both comments addressed, but not their literal way

Comment 1 (load error blocks fallback): kept fail-loud — and made it symmetric. resolveStatusTarget no longer swallows a genuine contexts.json read/parse error; it surfaces it like the control plane does. A missing file still reads as "no contexts" (not an error), so this only fires on real corruption/IO failure — which the user must see before a mutation acts as a stale legacy identity. Tests added for both ResolveControlPlaneTarget and resolveStatusTarget.

Comment 2 (missing ErrNotLoggedIn hint): fixed for best UX, not by wrapping the sentinel (which would downgrade the message). Dropped the resolve control-plane token: prefix so NewRefreshingLoginProvider's tailored message — naming the context, its login server, and the exact re-login command — reaches the user verbatim. The bare-sentinel static path still gets the standard entire login hint. Test tightened to assert verbatim surfacing.

Build + lint clean, affected tests green. Commit 6621920f51.

Want me to post replies on the two PR threads explaining why I diverged from the literal suggestions (especially comment 2, where wrapping the sentinel would have made it worse)? I'll keep them short.