[amandhaw]

MARSOHS-2084

A MARS session lives in one datacenter region and is only reachable on that
region's API host. Ask another region about it and you get a 404 — nothing is
redirected or forwarded. The hostname is the whole signal: harness-api reads the
forwarded Host itself, and no header carries the region.

This adds --region to doctl harness-runtime so a user can say which region
to talk to.

doctl harness-runtime create                      # ric1, exactly as today
doctl harness-runtime --region mem1 create        # api-mem1.digitalocean.com
doctl harness-runtime create --region mem1        # same thing
doctl harness-runtime list                        # one region, and it says which

How it works

--region mem1 points the client at api-mem1.digitalocean.com, via
godo.HostedAgentsRegionalBaseURL. The flag lives on the command group, so
every subcommand accepts it on either side of the subcommand name.

• Omitting the flag changes nothing. No host is rewritten, no body region is
  sent, and the server places in ric1 as it does today.
• An explicit region always names its own host, --region ric1 included.
• --api-url / DIGITALOCEAN_API_URL still win. The region is applied as a
  client option, which GetGodoClient installs before the override, so a host
  the user chose explicitly is never rewritten.
• port-forward builds its own URL rather than going through the client, so
  it makes the same host choice. Without that, a tunnel would keep dialing the
  default region and 404 on a session held elsewhere.

On a create from a config, the region also travels in the body. That is a
placement check rather than a routing instruction — the host already decided,
and a body region that disagrees is rejected rather than re-placed.

After a create, the host named by the response's Location becomes the host the
wait, prompt and attach use, so they land in the region that actually holds the
session. The server sends Location only for teams on the regional routing
rollout, and an explicit --api-url is left alone, so this is inert in both
cases.

doctl keeps no list of known regions — that would go stale the day a region
opens. harness-api validates against its own registry; this only checks the
shape of what gets put into a hostname.

Not here

Reading a region prefix off a session id (mem1-sess_abc123). Whether ids carry
one is still an open question in the design, so follow-up commands take
--region, or the host that Location named.

Testing

commands/agents_region_test.go covers host selection, the --api-url
precedence, the Location host, the tunnel URL, slug rejection, and that the
flag is inherited by every subcommand. Verified by hand with --trace that each
of --region ric1, --region mem1 and no flag reaches api-ric1, api-mem1
and api.digitalocean.com respectively, and that a configured --api-url still
wins.

🤖 Generated with Claude Code

[DO-rrao]

Reviewing only the change that reaches outside harness-runtime, the client setup in NewCmdConfig. Details inline: a region set in config.yaml reroutes every doctl command, not just this group.

[DO-rrao]

This runs for every doctl command, and agentRegionClientOpts() reads the process-global viper key harness-runtime.region without checking which command is running.

The comment (and the one on agentRegionClientOpts) says the option is nil for every other command because only the harness-runtime group registers --region. That holds for the flag, but viper also loads the key from config.yaml, where users already put per-command defaults. With a config containing only:

harness-runtime:
  region: mem1

an unrelated command goes to the regional host:

$ doctl --config cfg.yaml compute droplet list --trace
[DEBUG] GET https://api-mem1.digitalocean.com/v2/droplets?page=1&per_page=200

The same key with a bad value (say MEM1) would make every doctl command fail with invalid region.

Suggest applying the option only when the command belongs to the group, for example:

var regionOpts []godo.ClientOpt
if c.NS == agentCmdName || strings.HasPrefix(c.NS, agentCmdName+".") {
	regionOpts, err = agentRegionClientOpts()
	if err != nil {
		return err
	}
}

Plus a test that sets the key and checks that a non-agent namespace gets no option. Once it's scoped, a harness-runtime.region default in config.yaml becomes a nice feature for this group rather than a global side effect.

[amandhaw]

You are correct, and the fix is in 598b6e33.

One note on the suggested check: a namespace test does not match the agent commands. agentsNS sets overrideCmdNS("agents"), thus create has the namespace agents.create, and each nested group sets its own (agents.template, agents.config, agents.files). A test for harness-runtime matches no command, and regional routing then stops fully.

The fix reads the command tree instead. agentRegionFlag() gives "" when the command that runs is not harness-runtime or one of its children, at any depth. The gate is in that function, thus all the readers obey one rule: the client options, the port-forward WebSocket URL and the region that doctl prints. A command outside the group also does not get a region error.

Test with a build, with harness-runtime: {region: mem1} in config.yaml:

• compute droplet list → api.digitalocean.com
• harness-runtime list → api-mem1.digitalocean.com
• harness-runtime template list → api-mem1.digitalocean.com

With region: MEM1, only the harness-runtime commands fail.

TestAgentRegionIsScopedToTheGroup covers the four cases: a command outside the group, a bad value outside the group, no command, and a nested agent subcommand.

[DO-rrao]

Thanks. 598b6e3 is the right fix, and you were right about the namespace: the c.NS check in my snippet was wrong, because agent commands use agents.<name>.

But fe0559ec adds that check anyway, on top of 598b6e3, and it turns regional routing off for the API client. isAgentNS(c.NS) is never true for a real agent command, so agentRegionClientOpts() is never called. I built fe0559ec and traced each case:

Command	Host reached	Expected
harness-runtime --region mem1 list	api.digitalocean.com	api-mem1
harness-runtime --region mem1 template list	api.digitalocean.com	api-mem1
harness-runtime list, config region: mem1	api.digitalocean.com	api-mem1
compute droplet list, config region: mem1	api.digitalocean.com	api.digitalocean.com
harness-runtime list, config region: MEM1	api.digitalocean.com, no error	invalid region

It also leaves the code paths disagreeing. port-forward goes through agentRegionFlag() directly, so it still honours the region, while create, list and get don't. port-forward --region mem1 would dial api-mem1 for a session that was created on the default host.

TestIsAgentNS passes namespaces like harness-runtime.list, which no real command has, so the tests stay green.

Suggested fix:

• Drop the isAgentNS gate and TestIsAgentNS. The command-tree check in agentRegionFlag() already covers this, and it covers every reader.
• Add a test that sets activeCommand to a real agent subcommand (for example template list), builds the client the way NewCmdConfig does, and checks the base URL is https://api-mem1.digitalocean.com/.

[amandhaw]

You are correct. fe0559ec is reverted in 869330af.

That commit was a mistake. It applied the first suggestion again, on top of 598b6e3, which had already solved the same problem a different way. isAgentNS(c.NS) never matches a real command, so the client lost the region.

TestIsAgentNS did not catch this. The test used namespaces such as harness-runtime.list. No command has that namespace. The test made the same wrong assumption as the code, thus it stayed green. Both are removed.

The command-tree check in agentRegionFlag() is now the only gate again. It covers the client options, the port-forward URL and the printed region.

The test you asked for is already in 598b6e3: TestAgentRegionIsScopedToTheGroup/a nested agent subcommand still gets the option. It sets activeCommand to template list, builds the client from agentRegionClientOpts() and asserts the base URL is https://api-mem1.digitalocean.com/. Tell me if you want it to call NewCmdConfig directly instead.

Thank you for the trace table. It showed the fault clearly.