feat(cli): reconcile gateway registrations when a gateway is deleted upstream #4979

User Story

I use OpenShell's openshell CLI to work with gateways that a management plane provisions and later deletes on my behalf.

When my management plane deletes openshell gateways, the openshell CLI becomes out-of-date, the cache now may believe gateways still exist when they don't. openshell gateway list still shows the dead gateway, and openshell gateway add with the same name fails with "already exists." Nothing told me the gateway was simply gone, so the error messaging could be better. Also, it would be nice for the cache to just be accurate instead of forcing me to do openshell gateway delete.

This affects anyone whose gateways are managed outside the openshell CLI.

Problem Statement

If some management plane creates and deletes openshell gateways, there is no way for the management plane to communicate to user's openshell CLI that "this gateway no longer exists"

Impact / Why This Matters

To recover today, you have to already know the gateway is gone and run openshell gateway remove <name> yourself. But the CLI only surfaces a low-level auth error that reads like a credentials or config bug, so you end up debugging the wrong thing.

Meanwhile openshell gateway list keeps showing dead gateways, and you can't reuse the old name with openshell gateway add because it says "already exists." It's a rough edge for anyone whose gateways have a lifecycle outside the CLI.

Proposed Design

When you add a gateway, let the user set an optional flag (name TBD) that points the CLI at a way to check whether that gateway still exists. Gateways added without it behave exactly as today.

With it set, the CLI keeps itself honest:

• openshell gateway list stops showing gateways that have been deleted upstream, and prunes them. One that's only unreachable (a blip, or the owner is briefly down) is left alone — nothing is removed on doubt.
• openshell gateway add can reuse the name of a now-deleted gateway instead of refusing with "already exists" — it sees the old one is gone and replaces it.
• When the CLI can't reach the owner at all, a failed command should at least say something actionable (log in again, or remove it) instead of a confusing low-level error.

The flag's value is just an opaque status URL the CLI treats generically, a "still here" status and a "permanently gone" status... so any management plane can provide one without OpenShell knowing anything vendor-specific. Exact shape left to implementers.

Acceptance Criteria

• The existence check is opt-in; gateways added without it behave exactly as today (no new required flags, no behavior change).
• openshell gateway list stops showing, and prunes, a gateway confirmed deleted upstream.
• openshell gateway add can reuse the name of a confirmed-deleted gateway by replacing it.
• An unreachable or unclear existence check never removes or hides a gateway.

Alternatives Considered

• Have the management plane run openshell gateway remove on delete: can't work. It's a local, per-machine command, the management plane has no path to a user's config, and one gateway may be registered on many machines (often deleted via console/API/GC with no CLI session). This is really cache invalidation — the robust pattern is the client revalidating, not the server pushing deletes to every cache.

• Just improve the error message: turning the auth failure into "gateway deleted" helps (and matches the direction accepted in feat(providers): expose actionable OAuth refresh failures #2886), but it's a guess — the same error can mean a real misconfig — so it can't safely prune or free a name. Fine as a fallback, not the mechanism.

• Probe the gateway's own endpoint: once deleted, the endpoint is gone too, so it can't tell "deleted" from "temporarily down." The check has to come from something that outlives the gateway.

• Manual openshell gateway remove: today's workaround; only works if you already know the gateway is gone — the missing piece.

Agent Investigation

Investigated against main (d0a163a) with an agent.

Observed behavior (validated in code):

• A gateway added with openshell gateway add is saved as GatewayMetadata (crates/openshell-bootstrap/src/metadata.rs:15) under ~/.config/openshell. Nothing ever re-checks it against an authority, so a gateway deleted upstream is never noticed.
• openshell gateway list reads the saved gateways (list_gateways_with_source, metadata.rs:328) and prints them as-is — no liveness/existence step.
• openshell gateway add hard-fails a name collision with "Gateway '' already exists" (commands/gateway.rs:920), which is why a deleted name can't be reused.
• The low-level auth error users actually see is emitted here on refresh failure (main.rs:215).

Feasibility:

• The new field is additive and serde-skippable on GatewayMetadata, so "not set" = today's behavior.
• The two surfaces to change already exist and are small: list_gateways_with_source for the prune, and the gateway.rs:920 guard for name reuse. remove_gateway_metadata (metadata.rs:418) already does the pruning.
• The CLI already has a reusable HTTP client with insecure handling (oidc_auth.rs:95) for an opt-in check; a pure status->state classifier keeps it unit-testable without a network.
• Confirms this must be CLI-local: no server-side extension (middleware/interceptor/provider) can read or prune a user's ~/.config.

Open questions (for implementers):

• Should gateway list do the network check inline (bounded concurrency + short timeout) or behind a flag? It must stay non-fatal — an unreachable owner leaves gateways untouched.
• The existence check should not require a valid gateway token (the broken auth is the thing being diagnosed), so the contract should tolerate an unauthenticated probe.
• Whether the "actionable error on unreachable owner" piece (main.rs:215) ships here or as a follow-up.

Prior art: #2886 (accepted) established that opaque auth failures should be made actionable.

Checklist

• I've reviewed existing issues and the published docs
• This is a design proposal, not a "please build this" request