Suggest cortex serve when a context named "cortex" refuses the connection

[esnible]

Problem

Point a context at a local rossoctl cortex serve, forget to start it, and the CLI says only this:

Error: requesting http://localhost:9097/api/v1/agents?namespace=team1: Get "...": dial tcp [::1]:9097: connect: connection refused

Accurate, and silent about the remedy — which in this one case the CLI can name, because cortex serve is the only server rossoctl can start itself.

What this does

Adds the hint to errorHint, the single place every command's error is already printed from Execute. That covers agents, tools, status, envvars, and anything added later, instead of repeating it at the eleven call sites that reach a client.

Error: requesting http://localhost:9097/api/v1/agents?namespace=team1: Get "...": dial tcp [::1]:9097: connect: connection refused
Hint: nothing is listening at http://localhost:9097/api/v1/. Run `rossoctl cortex serve` to start the local API.

Design notes

The condition is errors.Is(err, syscall.ECONNREFUSED), not the message text. apiclient wraps the dial failure with %w, so the errno survives in the chain. Matching the syscall distinguishes a refused connection from a timeout or an unresolvable host — neither of which a local server would fix, and the second of which is the likelier typo. Text matching would also have broken an existing test requiring a bare errors.New("connection refused") to produce no hint. That case still passes, and a new test pins the DNS distinction against an RFC 2606 .invalid name.

The hint fires only for a context named cortex. Anywhere else it would be misdirection: a production API that is down is not fixed by running a local server, and saying so sends the user after the wrong problem. A name as the marker is a convention, not a guarantee, which is why this is appended to the real error and never replaces it. An explicit --server suppresses it, since --server overrides every context and the context name then says nothing about what was dialed.

config.TypeCortex is removed rather than used. The original request was to key on it, and it could not work — the type was declared but never set. All four context-creating sites hardcode TypeAPI and create-context has no --type flag, so no condition keyed on it could ever fire. Type is an unvalidated bare string, so a config.yaml written when "cortex" existed still parses and carries the value as-is; no migration, and a test keeps a literal "cortex" to pin that such a context still routes to the HTTP client. A local cortex is an ordinary HTTP server reached by pointing a context at its address — which "api" already describes.

The context lookup is defensive. Checking the name can itself fail, and it happens while an error is already being reported, so a config that will not load leaves the hint silent rather than replacing the failure the user is trying to read. A test writes a malformed config to require that.

The test chains come from a real dial to a closed port, wrapped the way apiclient wraps it, rather than from a constructed syscall.Errno. A fake errno would keep passing if net/http stopped surfacing the syscall — precisely the change that would silently disable this hint in production.

Verification

go build ./..., go vet ./..., gofmt -l cmd internal, and go test ./... all pass. Six new tests in cmd/root_test.go; the pre-existing 401 hint and the errors.New("connection refused") silence are both unregressed.

End to end:

Situation	Result
Context cortex, nothing listening	raw error + the hint
Context prod, nothing listening	raw error, no hint
Context cortex, cortex serve running	No agents found., exit 0

Notes and limitations

• rossoctl login still gets no hint: fetchAuthConfigForLogin wraps with %v, severing the chain. Pre-existing, deliberate at that site for the 401 circularity its comment describes, and left alone here. Worth a follow-up.
• The trigger is a naming convention, so a context pointed at a local cortex under a different name gets no hint, and a context named cortex pointed elsewhere gets a slightly wrong one. Both are why this is additive to the real error.
• staticcheck was not run: the installed build is Go 1.25 and this module requires 1.26.4. Linting rests on go vet.
• Neither README documents the context type field, so no documentation changed.
• Incidental finding: agents list fails on a missing namespace before it dials, so reaching this path needs create-context --namespace.

Assisted by Claude.

Signed-off-by: Ed Snible snible@us.ibm.com