Explain suspended mirrors in entire repo mirror create

[nodo]

https://entire.io/gh/entireio/cli/trails/497

Summary

When entire repo mirror create hits a suspended mirror placement, the output is baffling — it prints Mirror already exists and then fails with the raw OAuth error invalid_target: no mirror at this URL. Those read as contradictory.

They aren't. They come from two lookups that disagree about suspended rows:

• create is idempotent on (repo, cluster) and ignores suspended_at → reports "already exists".
• The clone probe's repo-scoped token exchange resolves the mirror through the data plane's auth gate, which hides suspended placements behind invalid_target as an enumeration guard → "no mirror at this URL".

This PR makes the failure self-explanatory: when the clone probe is refused for a mirror we just confirmed exists, print the likely cause and the exact operator recovery command instead of the raw OAuth error.

What changed

• auth: new ErrRepoTargetUnknown sentinel; RepoScopedToken detects an STS invalid_target via errors.As on the typed sts.ExchangeError (xe.Code == "invalid_target") and wraps it with the sentinel, preserving the verbatim STS text via a second %w.
• repo mirror create: explainSuspendedMirror translates that sentinel into an actionable message + entire-core admin mirrors resume <id>, returning a SilentError. Unrelated probe errors (timeout, cancel, auth) pass through verbatim.
• deps / toolchain: pulls the typed-error auth-go build and bumps Go to 1.26.4 (see open item use github runners #1).

Before

Mirror already exists (01KS6KFJR2XS6PZ188MVYE07AN)
  entire://aws-us-east-2.entire.io/gh/entireio/entire-upgrade
authorize clone probe: repo-scoped token exchange: token exchange: status 400: invalid_target: no mirror at this URL

After

Mirror already exists (01KS6KFJR2XS6PZ188MVYE07AN)
  entire://aws-us-east-2.entire.io/gh/entireio/entire-upgrade

Mirror 01KS6KFJR2XS6PZ188MVYE07AN is registered but the cluster won't issue clone tokens for it.
This usually means the placement is suspended after upstream GitHub access
was lost (App uninstalled, the repo went private, or a transient API error).
An operator can re-enable it once access is restored:
  entire-core admin mirrors resume 01KS6KFJR2XS6PZ188MVYE07AN

Detection — typed, not string-matched

var xe *sts.ExchangeError
if errors.As(err, &xe) && xe.Code == "invalid_target" {
    return "", fmt.Errorf("repo-scoped token exchange: %w: %w", ErrRepoTargetUnknown, err)
}

Tests

• TestRepoScopedToken_InvalidTarget — a 400 invalid_target STS response surfaces as ErrRepoTargetUnknown, with the verbatim detail preserved.
• TestExplainSuspendedMirror — renders the mirror id + resume command through the real wrapping chain; unrelated errors pass through untouched.

Draft — open items

This is intentionally a draft; two things are still in flight:

1. auth-go release (pseudo-version → v0.5.0). The typed sts.ExchangeError{StatusCode, Code, Description} lands in auth-go branch sts-typed-exchange-error, currently consumed here as a pseudo-version (v0.4.1-0.20260603110757-7103c3dc992a). Once that branch is merged and tagged v0.5.0, repoint go.mod at the clean release. That auth-go build also raised the stdlib floor, which is why this PR bumps Go to 1.26.4 (also picks up GO-2026-5037 / GO-2026-5039).
2. Wording precision. invalid_target is not exclusively suspension — the server collapses {absent, suspended, orphaned} into one no mirror at this URL, and on a fresh create it's more likely propagation lag than suspension. Planned refinement: soften to "most likely suspended", surface the server's own description (xe.Description) verbatim, add entire-core admin mirrors list as a diagnostic, and possibly branch on the created flag (fresh vs existing).

Test plan

• mise run lint — clean (golangci-lint 0 issues, gofmt/gomod/shellcheck pass)
• go build ./... + targeted tests for the touched packages, against go 1.26.4
• Manual repro against a suspended mirror once auth-go v0.5.0 is tagged and go.mod is repointed

🤖 Generated with Claude Code

---

Note

Low Risk
CLI-only UX and error classification for mirror create; no auth protocol or server behavior changes beyond a dependency bump for typed STS errors.

Overview
When entire repo mirror create reports an existing mirror but the clone readiness probe fails with STS invalid_target, the CLI now explains the likely suspended placement case instead of a contradictory raw OAuth error.

RepoScopedToken maps typed sts.ExchangeError with code invalid_target to ErrRepoTargetUnknown, while keeping the original STS text in the error chain. explainSuspendedMirror turns that into operator guidance (entire-core admin mirrors resume <id>) and a SilentError so the message is not duplicated; fresh creates still surface the raw error (propagation lag, not suspension).

Tests cover invalid_target wrapping and the explain helper’s branches. auth-go is bumped to a pseudo-version with typed exchange errors; Go is updated to 1.26.4 in go.mod and mise.toml.

^{Reviewed by Cursor Bugbot for commit 928dd85. Configure here.}

[Copilot]

Pull request overview

Improves the UX of entire repo mirror create when the clone-readiness probe fails due to STS token exchange returning invalid_target (commonly caused by suspended mirror placements), by classifying the auth failure via a sentinel error and rendering an actionable recovery message instead of the raw OAuth text.

Changes:

• auth: Introduces ErrRepoTargetUnknown and maps STS invalid_target token-exchange failures to it (while preserving the original STS error text in the error chain).
• repo mirror create: Adds explainSuspendedMirror handling so this specific auth failure is rendered as a clear “registered but not servable” message plus the operator resume command, returning SilentError to avoid duplicate/raw error output.
• Tests: Adds coverage for invalid-target wrapping and the suspended-mirror explanation behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
cmd/entire/cli/repo_mirror.go	Hooks suspended-mirror explanation into the create clone-probe failure path.
cmd/entire/cli/repo_mirror_test.go	Adds unit tests asserting the explanation + SilentError behavior.
cmd/entire/cli/repo_mirror_probe.go	Implements explainSuspendedMirror to translate ErrRepoTargetUnknown into an actionable message.
cmd/entire/cli/auth/repo_token.go	Adds ErrRepoTargetUnknown and detects STS invalid_target to wrap with the sentinel.
cmd/entire/cli/auth/repo_token_test.go	Adds test exercising the STS error-decoding path and verifying sentinel wrapping + preserved detail.

[nodo]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 928dd85. Configure here.}