feat(accounts): per-account egress proxy (http, socks4/4a, socks5/5h)

[fluffypony]

This lets one account leave through its own proxy whilst the rest of the fleet carries on as before. The contract is that ALL of that account's traffic goes through the proxy, and ONLY that account's.

teamclaude login --name "waffles@waffle.com" --routing "socks5h://alice:s3cret@proxy.example.com:1080"
teamclaude routing waffles@waffle.com socks5h://alice:s3cret@proxy.example.com:1080
teamclaude routing waffles@waffle.com none

{ "name": "waffles@waffle.com", "type": "oauth", "routing": "socks5h://alice:s3cret@proxy.example.com:1080" }

upstreamProxy moves every account together and only speaks CONNECT, so it can't do this. Schemes are http (CONNECT), socks4, socks4a, socks5 and socks5h with user:pass@ auth, and the a / h forms resolve at the proxy the way curl's do. There are no new dependencies - the SOCKS handshakes are hand-rolled on the same primitives as the sx CONNECT tunnel, and TLS stays end-to-end in every case.

It's a big PR (+3 668 lines, 2 177 of them tests), so here's a map of it, sorry😅

What gets routed

Everything TeamClaude does with the account's credential: forwarding, token refresh, the usage / profile / Codex / backend-quota probes, the OAuth code exchange and profile lookup at login, teamclaude accounts and teamclaude api. It all goes through one routing option on upstreamFetch / proxyFetch, which outranks both sx and upstreamProxy for that call. It doesn't chain them - that would be two hops to solve one problem, and the first hop wouldn't be the proxy the operator picked.

You can set it from the CLI (routing <name> [url|none], login / import --routing), the config (accounts[].routing, live on reload through sync-accounts.js), the TUI (g → "Account proxy", which sits next to "Upstream proxy") and MCP (set_account_routing). docs/accounts.md has the long version.

The URL carries a password, so it's masked everywhere it can be printed: the status payload (attach mode and status --json never see it), the TUI, a dashboard badge, parse errors, and the MCP write log. That last one needed a small auditArgs hook on the tool definition, because the write log prints tool arguments verbatim.

Two things are NOT routed, and the docs say so:

• Claude Code's own identity plane (/api/oauth/*, /v1/code/*, its token refresh). That's relayed with the client's credential and belongs to no pooled account, even when it's the same human behind both.
• A sign-in that names no account, because the account is only known once the profile comes back. The command tells you when that happened, and login --name <account> fixes it by borrowing the routing the entry already has.

When the proxy dies

If you only review one thing closely, make it this.

ECONNREFUSED sits in SOCKET_TRANSIENT, on the reasoning that every account dials the same host, so failing over is pointless and the right move is to close the connection and let the client retry. From ONE account's proxy that reasoning is backwards. The retry lands on the same account and hits the same dead proxy, forever.

So routingAgent wraps any failure to open a connection through an account's routing (refused, timed out, bad credentials, a target the proxy can't reach, or TLS that never completes over the tunnel) as TEAMCLAUDE_ROUTING_FAILED, and keeps the socket error on cause. isTransientUpstreamError returns false for it, so it takes the ordinary failover path. Nothing of the request has been sent at that point, so failing over can't duplicate anything upstream.

The account then sits out for 30 seconds, because otherwise every request queued behind the first one pays the connect timeout before it fails over, and against a black-holed proxy that's up to 30s each. It's modelled on the entitlement cooldown: routingFailedUntil, unavailable reason routing, not probeable while it lasts, and lifted by any response that comes back through the proxy or by changing the account's routing. exhaustedMessage names it rather than filing it under "quota or rate limit", and the retry-after is the rest of the hold. A pin still goes to the account it names.

Related: a 429 on a routed account no longer arms the sx sticky window or takes the "retrying via sx.org" branch. That 429 was earned by the account's own exit address, and the branch would have re-sent immediately through the proxy that had just been refused.

Testing the proxy before anything depends on it

login --routing, import --routing, routing <name> <url> and the TUI row all open a tunnel to the account's upstream and finish the TLS handshake before they change anything. No request is sent.

The reason is OAuth. The code is single-use, so finding a typo'd proxy password at the token exchange costs you the whole browser flow. --no-check skips the test for a proxy that isn't up yet, and routing <name> --check runs it against what's already stored.

Also - --routing=URL works, a bare --routing is an error rather than being ignored (the alternative is the account being added from your own IP without a word), and --routing none signs in direct and clears what's stored.

Two TUI fixes that came along for the ride

Both turned up whilst testing the new prompt, and both predate this branch:

• _onData drops any chunk longer than one character, so a PASTED value vanishes without a sign. Nobody types socks5h://user:long-password@host:1080 by hand, and the sx key and upstream proxy prompts have the same problem.
• A body taller than the terminal pushes the footer off the bottom, and the footer is where prompts get typed. The settings screen needs 46 rows on master, so on anything shorter you're typing blind. The body is now a window that follows the cursor row.

Happy to split those into their own PR if you'd rather take them separately.

Tests

8 new test files, plus additions to the MCP, dashboard, exhausted-message and TUI suites. The full suite (2 260) passes on Node 20, 22, 24 and 25, and lint, typecheck and the strict ratchet (13 fewer than base) are clean. That's all on macOS, so CI will tell us about Linux.

The in-repo tests use SOCKS mocks written next to the client, which means a misreading of the protocol could hide in both. So the branch also went up against real servers - all five schemes against 3proxy, SOCKS5 auth against microsocks, and CONNECT + Basic auth against tinyproxy. They all pass. The handshake bytes for socks4a and socks5h with auth are identical to what curl sends for --socks4a and --socks5-hostname --proxy-user, apart from curl also offering GSSAPI in its greeting.

Not done: keep-alive for routed sockets. Every request pays a new tunnel plus a TLS handshake, which is what the upstreamProxy path does today, and a socket pool felt like too much for a first PR. Per-account VPN egress is next on my list, which is why all of this lives in one module (src/account-routing.js).

One thing I'm not precious about is the name. routing collides a little with model routes (route, routes, docs/routing.md), which is why the TUI row says "Account proxy" - "Manage routing" was already taken. I kept routing for the config key and the CLI because "routing an account's traffic" is how I think about it, but egress or proxy would work just as well. Would you rather I rename it before this goes in?

[MagicalTux]

I reviewed this closely and it is going in. Two things were done on the branch, so you know what changed under you:

1. Two unrelated commits were dropped from the tip: 294df4d "Preserve model credit errors instead of retrying them" and 01b98f0 "fix(proxy): surface minute-long rate limits promptly". Both change fleet-wide 429 policy for every user (the inline absorb cap from 60 s to 15 s, and a credits_required branch that reads the body of every 429), neither is mentioned in the description, and they deserve their own review. Please resubmit them as a separate PR if you still want them; the review notes on them are in this thread's history if useful.

2. Small fixes were applied on top (three commits, then a merge of master): the routing tunnel gets a 20 s budget so a black-holed proxy on an OAuth account is classified as a routing failure instead of racing the refresh's 30 s abort and being retried as transient; SOCKS5 replies check VER/REP before being sized by ATYP, SOCKS4 replies check VN; ipv6Bytes uses v6Groups so an embedded IPv4 tail encodes correctly; checkRouting never rejects; a routing that names this server's own listener is refused (it would recurse through the MITM); a black-hole proxy test; and profileForCredentials (from fix(import): refuse an account whose token the upstream rejected #460, merged meanwhile) is routed too, so a --routing login's token refresh and profile lookup go through the proxy as well. The config key stays routing.

CI will run on the updated branch; I will merge once it is green.