@rikcodes/teamclaude 1.1.13-rik.1

package/src/updater.js

@@ -0,0 +1,177 @@
+// Opt-out-able self-update, in the spirit of Claude Code's auto-updater.
+//
+// We ONLY ever touch a global npm install (`npm install -g @karpeleslab/teamclaude`):
+//   - a git checkout (a `.git` at the package root) is a dev tree — never touched;
+//   - a local dependency / npx copy is left alone (we only notify).
+// Checks hit the npm registry at most once a day (cached in a small file next to
+// the config), so the overwhelmingly common invocation does zero network I/O.
+// Disable entirely with TEAMCLAUDE_DISABLE_AUTOUPDATE=1 or config.autoUpdate=false.
+//
+// Every side-effecting dependency (fetch, spawn, the clock, the cache path) is
+// injectable so the logic is unit-testable without network or npm.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { getConfigPath } from './config.js';
+
+export const PKG_NAME = '@rikcodes/teamclaude'; // fork: self-updates track this scope, never upstream's
+const REGISTRY = 'https://registry.npmjs.org';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Package root = one directory above this file's src/ directory. */
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+/** Installed version, read from the shipped package.json (null if unreadable). */
+export function currentVersion(root = packageRoot()) {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Numeric compare of x.y.z, then the pre-release tail. >0 if a is newer.
+ *  The tail matters here: this fork versions releases as X.Y.Z-rik.N on the
+ *  same upstream base, so ignoring it would make every -rik.N publish compare
+ *  equal and never trigger an update. Ordering follows semver: base segments
+ *  first, a release outranks any pre-release of the same base, and two
+ *  pre-releases compare segment-wise (numerically where both are numbers). */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const [base, ...pre] = String(v).split('+')[0].split('-');
+    return { nums: base.split('.').map((n) => parseInt(n, 10) || 0), pre: pre.join('-') };
+  };
+  const pa = parse(a), pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa.nums[i] || 0) - (pb.nums[i] || 0);
+    if (d) return d;
+  }
+  if (!pa.pre || !pb.pre) return (pa.pre ? 0 : 1) - (pb.pre ? 0 : 1);
+  const sa = pa.pre.split('.'), sb = pb.pre.split('.');
+  for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+    if (sa[i] === undefined) return -1;
+    if (sb[i] === undefined) return 1;
+    const na = Number(sa[i]), nb = Number(sb[i]);
+    const d = Number.isFinite(na) && Number.isFinite(nb) ? na - nb : sa[i].localeCompare(sb[i]);
+    if (d) return d;
+  }
+  return 0;
+}
+
+/** `npm root -g` (the global modules dir), or null if npm is unavailable. */
+function npmGlobalRoot() {
+  try {
+    const r = spawnSync('npm', ['root', '-g'], { encoding: 'utf8', timeout: 5000 });
+    if (r.status === 0 && r.stdout) return r.stdout.trim();
+  } catch { /* npm missing */ }
+  return null;
+}
+
+/** How this copy was installed: 'git', 'global', 'local', or 'unknown'. */
+export function installKind({ root = packageRoot(), globalRoot = npmGlobalRoot } = {}) {
+  if (existsSync(join(root, '.git'))) return 'git';
+  const norm = root.split('\\').join('/');
+  if (!norm.includes('/node_modules/')) return 'unknown';
+  const g = typeof globalRoot === 'function' ? globalRoot() : globalRoot;
+  if (g && norm.startsWith(g.split('\\').join('/'))) return 'global';
+  return 'local';
+}
+
+/** Fetch the registry's current "latest" version (null on any failure/timeout). */
+export async function fetchLatestVersion({ fetchImpl = fetch, timeoutMs = 5000 } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${REGISTRY}/${PKG_NAME}`, {
+      signal: ctrl.signal,
+      headers: { accept: 'application/vnd.npm.install-v1+json' }, // abbreviated packument (small, has dist-tags)
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return json['dist-tags']?.latest || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function defaultCacheFile() {
+  return join(dirname(getConfigPath()), 'update-check.json');
+}
+async function readCache(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); } catch { return {}; }
+}
+async function writeCache(path, obj) {
+  try { await writeFile(path, JSON.stringify(obj)); } catch { /* best effort */ }
+}
+
+/**
+ * Throttled version check. Returns { current, latest, updateAvailable } or null
+ * if the version is unknown / the registry couldn't be reached and nothing is
+ * cached. Only fetches when the cached check is older than `intervalMs` (or
+ * `force`), so back-to-back invocations do no network I/O.
+ */
+export async function checkForUpdate({
+  current = currentVersion(),
+  cachePath = defaultCacheFile(),
+  fetchImpl = fetch,
+  now = Date.now(),
+  intervalMs = DAY_MS,
+  force = false,
+} = {}) {
+  if (!current) return null;
+  const cache = await readCache(cachePath);
+  let latest = cache.latest || null;
+  const fresh = cache.checkedAt && (now - cache.checkedAt) < intervalMs;
+  if (force || !fresh) {
+    const fetched = await fetchLatestVersion({ fetchImpl });
+    if (fetched) latest = fetched;
+    await writeCache(cachePath, { checkedAt: now, latest });
+  }
+  if (!latest) return null;
+  return { current, latest, updateAvailable: compareVersions(latest, current) > 0 };
+}
+
+/** Install a specific version globally. Returns true on success. */
+export function runUpdate(version = 'latest', { spawnImpl = spawnSync } = {}) {
+  const r = spawnImpl('npm', ['install', '-g', `${PKG_NAME}@${version}`], {
+    stdio: 'inherit',
+    timeout: 180000,
+  });
+  return !!r && !r.error && r.status === 0;
+}
+
+/**
+ * The automatic path used at startup / session-end. Skips dev checkouts and
+ * respects the opt-out; when an update exists it silently installs it for a
+ * global install, or just prints a one-line notice otherwise. Cheap in the
+ * common case: the expensive `npm root -g` probe only runs when an update is
+ * actually available.
+ */
+export async function autoUpdate({ config = {}, force = false, log = console.error } = {}) {
+  const root = packageRoot();
+  if (existsSync(join(root, '.git'))) return { skipped: 'git' }; // dev checkout — never touch
+  if (process.env.TEAMCLAUDE_DISABLE_AUTOUPDATE || config.autoUpdate === false) {
+    return { skipped: 'disabled' };
+  }
+  const info = await checkForUpdate({ force });
+  if (!info) return { skipped: 'check-failed' };
+  if (!info.updateAvailable) return { ...info, upToDate: true };
+
+  if (installKind({ root }) !== 'global') {
+    log(`[TeamClaude] Update available: ${info.current} → ${info.latest}. Run: teamclaude update`);
+    return { ...info, notified: true };
+  }
+  log(`[TeamClaude] Updating ${info.current} → ${info.latest}…`);
+  const ok = runUpdate(info.latest);
+  log(ok
+    ? `[TeamClaude] Updated to ${info.latest}. Restart teamclaude to use the new version.`
+    : `[TeamClaude] Auto-update failed. Run manually: npm install -g ${PKG_NAME}@latest`);
+  return { ...info, updated: ok };
+}

package/src/upstream-fetch.js

@@ -0,0 +1,267 @@
+// Zero-dependency `fetch` shim that routes upstream requests through the sx.org
+// proxy when it is enabled. With sx disabled it IS global fetch (byte-for-byte
+// the same behavior), so the default path is unchanged.
+//
+// Node's global fetch can't use a CONNECT proxy without `undici` (a dependency —
+// and "zero dependencies" is a project feature), so when sx is enabled we issue
+// the request with `https.request` over a tunneled TLS socket and return a small
+// object exposing exactly the fetch-Response surface src/server.js relies on:
+// `status`, `headers.get()/.entries()`, `text()`, `arrayBuffer()`, and `body`
+// (a web ReadableStream, so streamResponse()'s getReader()/cancel() is untouched).
+
+import http from 'node:http';
+import https from 'node:https';
+import { ReadableStream } from 'node:stream/web';
+import { tunnelTls } from './sx.js';
+import { proxyForHost, proxyAgent } from './upstream-proxy.js';
+
+// Pooled keep-alive agents for the direct (non-sx) path. Node's global fetch
+// multiplexes ALL requests to an origin over a SINGLE HTTP/2 connection; under
+// many concurrent large uploads (Claude Code POSTs ~1MB of context per turn)
+// that one connection serializes on HTTP/2's shared flow-control windows —
+// api.anthropic.com advertises maxConcurrentStreams=100 (not the limit) but only
+// a 64KB initial window, so concurrent uploads queue behind WINDOW_UPDATEs and a
+// trivial request can wait minutes for headers (issue #106). Independent HTTP/1.1
+// connections have no application-layer flow control: each upload fills its own
+// socket at TCP speed, exactly like N direct Claude Code processes. maxSockets is
+// per-origin and bounds the fan-out. Escape hatch:
+// TEAMCLAUDE_UPSTREAM_GLOBAL_FETCH=1 reverts to the old global-fetch path.
+const MAX_SOCKETS = Number(process.env.TEAMCLAUDE_UPSTREAM_MAX_SOCKETS) || 256;
+const httpsAgent = new https.Agent({ keepAlive: true, maxSockets: MAX_SOCKETS });
+const httpAgent = new http.Agent({ keepAlive: true, maxSockets: MAX_SOCKETS });
+const USE_GLOBAL_FETCH = /^(1|true|yes|on)$/i.test(process.env.TEAMCLAUDE_UPSTREAM_GLOBAL_FETCH || '');
+
+// Time to wait for RESPONSE HEADERS before treating the upstream socket as dead.
+// This is NOT a limit on the response body (SSE completions can stream for
+// minutes); the deadline is cleared the instant headers arrive, so a slow, long
+// answer is never cut. It measures time-to-first-byte only, which streaming
+// delivers within seconds, and its job is to convert an indefinite hang on a
+// half-dead pooled socket (e.g. after the host's network drops and reconnects,
+// leaving Node's global fetch pool holding stale keep-alive connections) into a
+// fast, retryable failure. Without it a reused dead socket hangs until Node's
+// 300s default, long past the point the client gave up, and only a full process
+// restart clears the poisoned pool. Each aborted request evicts one dead socket,
+// so a burst of stale connections drains over the next few retries.
+//
+// NOTE (non-streaming requests): for a request without `stream: true`, the whole
+// response arrives as the "headers+body" unit, so first-byte ≈ full generation.
+// Claude Code's completions stream, so this is safe in practice, but a very long
+// non-streaming generation could trip this — raise it per-call or via the env var
+// for such callers. Mid-stream stalls (a drop AFTER headers) are handled
+// separately by the body-idle watchdog in server.js's streamResponse.
+//
+// We abort ONLY in the pre-headers window and clear the timer once the body
+// starts, so we never abort mid-stream. That matters: an AbortSignal fired after
+// data has started leaves the socket occupied and leaks a "zombie" connection
+// that drains the pool over time; aborting before the first byte lets undici
+// destroy the socket cleanly instead. The textbook fix is dispatcher-level
+// timeouts via undici's setGlobalDispatcher(new Agent({ headersTimeout,
+// keepAliveTimeout })); we stay zero-dependency, so this reactive guard is the
+// stand-in.
+//
+// Default is generous (well above Claude's realistic first-byte, even when
+// queued or under load) so a slow-but-legitimate response is never mistaken for
+// a dead socket. Override with TEAMCLAUDE_UPSTREAM_HEADERS_TIMEOUT_MS (or
+// per-call opts).
+const DEFAULT_HEADERS_TIMEOUT_MS = 120_000;
+
+function resolveHeadersTimeout(perCall) {
+  if (perCall != null) return perCall;
+  const env = Number(process.env.TEAMCLAUDE_UPSTREAM_HEADERS_TIMEOUT_MS);
+  return env > 0 ? env : DEFAULT_HEADERS_TIMEOUT_MS;
+}
+
+function headersTimeoutError(ms) {
+  const err = new Error(`upstream response headers timed out after ${ms}ms`);
+  // Recognized by server.js isTransient → fail fast + let the client retry, so
+  // Node's fetch pool evicts the stale connection instead of wedging.
+  err.code = 'TEAMCLAUDE_HEADERS_TIMEOUT';
+  return err;
+}
+
+// `useProxy` is decided by the caller (it varies per attempt — e.g. direct first,
+// then via sx after a 429). With it false, or sx unprovisioned, this is plain fetch
+// (plus the headers-timeout guard).
+export function upstreamFetch(url, opts = {}, sx = null, useProxy = false) {
+  const { headersTimeoutMs, ...fetchOpts } = opts;
+  const timeoutMs = resolveHeadersTimeout(headersTimeoutMs);
+  if (sx && useProxy && sx.isProvisioned()) return proxiedFetch(url, fetchOpts, sx, timeoutMs);
+  // The global-fetch escape hatch cannot speak CONNECT (that is why the tunnel
+  // is hand-rolled at all), so an upstream proxy overrides it rather than being
+  // silently dropped — on a host that needs the proxy, ignoring it means every
+  // request fails.
+  const useGlobal = USE_GLOBAL_FETCH && !proxyForHost(new URL(url).hostname);
+  return useGlobal ? directFetch(url, fetchOpts, timeoutMs) : pooledFetch(url, fetchOpts, timeoutMs);
+}
+
+/**
+ * `fetch` for teamclaude's own control-plane calls — OAuth token exchange and
+ * refresh, profile, usage. Identical to global fetch when no upstream proxy is
+ * configured; tunneled through it when one is.
+ *
+ * These are not request-forwarding traffic, but they are the calls that decide
+ * whether an account can be added or kept alive at all. Leaving them direct
+ * would mean `login` fails and every token refresh dies on a host that can only
+ * reach the network through a proxy, which is precisely the reported setup.
+ */
+export function proxyFetch(url, opts = {}) {
+  const { headersTimeoutMs, ...rest } = opts;
+  if (!proxyForHost(new URL(url).hostname)) return fetch(url, rest);
+  return pooledFetch(url, rest, resolveHeadersTimeout(headersTimeoutMs));
+}
+
+// Default direct path: HTTP/1.1 over a pooled keep-alive agent, so N concurrent
+// requests use N connections instead of serializing over one h2 connection (#106).
+//
+// "Direct" here means "not via sx". A configured upstream proxy (config
+// `upstreamProxy`, or HTTPS_PROXY — see upstream-proxy.js) still applies: on
+// those hosts there is no such thing as a direct socket to api.anthropic.com,
+// which is the whole of issue #155.
+function pooledFetch(url, opts, timeoutMs) {
+  const u = new URL(url);
+  const isHttp = u.protocol === 'http:';
+  const port = Number(u.port) || (isHttp ? 80 : 443);
+  const proxy = proxyForHost(u.hostname);
+  if (proxy) {
+    const agent = proxyAgent(proxy, { targetHost: u.hostname, targetPort: port, tls: !isHttp, tlsOptions: opts.tlsOptions || {} });
+    return nodeRequest(u, opts, timeoutMs, { transport: isHttp ? http : https, agent });
+  }
+  return nodeRequest(u, opts, timeoutMs, { transport: isHttp ? http : https, agent: isHttp ? httpAgent : httpsAgent });
+}
+
+// Legacy direct path (escape hatch): Node global fetch, driven by our own
+// AbortController so we can arm a headers-only deadline and disarm it the moment
+// headers arrive (letting the body stream with no deadline). AbortSignal.timeout
+// can't do this — it would also kill the body.
+function directFetch(url, opts, timeoutMs) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(headersTimeoutError(timeoutMs)), timeoutMs);
+  timer.unref?.();
+  return fetch(url, { ...opts, signal: ctrl.signal }).then(
+    (res) => { clearTimeout(timer); return res; },
+    (err) => { clearTimeout(timer); throw err; },
+  );
+}
+
+// sx path: every socket is a fresh TLS connection tunneled through sx.org. The
+// agent is created per request (its createConnection closes over this call's
+// target), so keep-alive would give no reuse — it would only park the tunneled
+// socket in a soon-orphaned pool and leak an open sx.org connection per request.
+function proxiedFetch(url, opts, sx, timeoutMs) {
+  const u = new URL(url);
+  const proxy = sx.getProxy();
+  const agent = new https.Agent({ keepAlive: false });
+  agent.createConnection = (_options, cb) => {
+    // sx.tlsOptions is undefined in production (system CAs verify api.anthropic.com);
+    // tests inject a CA here to reach a self-signed upstream.
+    tunnelTls({ proxy, targetHost: u.hostname, targetPort: Number(u.port) || 443, tlsOptions: sx.tlsOptions || {} })
+      .then((sock) => cb(null, sock))
+      .catch((err) => cb(err));
+    return undefined; // socket delivered asynchronously via cb
+  };
+  return nodeRequest(u, opts, timeoutMs, { transport: https, agent });
+}
+
+// Shared node:http(s) request → the fetch-Response subset server.js uses, with
+// the headers-only deadline: it fires before headers arrive and tears the request
+// down; it is cleared the instant the response starts, so a body that streams for
+// minutes is never cut. `req` is created BEFORE the timer so a synchronous
+// throw (e.g. an invalid client header) can't leave a scheduled timer that later
+// fires against an uninitialized binding.
+function nodeRequest(u, opts, timeoutMs, { transport, agent }) {
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      u,
+      { method: opts.method || 'GET', headers: opts.headers || {}, agent },
+      (res) => { clearTimeout(timer); cleanupAbort(); resolve(makeResponse(res)); },
+    );
+    const timer = setTimeout(() => req.destroy(headersTimeoutError(timeoutMs)), timeoutMs);
+    timer.unref?.();
+
+    // Honour an AbortSignal the way fetch does. Callers that already guard a
+    // hung call this way (oauth's refresh timeout, which otherwise wedges every
+    // request for that account) must keep working when the call is tunneled.
+    const signal = opts.signal;
+    const onAbort = () => req.destroy(signal?.reason ?? new Error('aborted'));
+    const cleanupAbort = () => signal?.removeEventListener?.('abort', onAbort);
+    if (signal) {
+      if (signal.aborted) { clearTimeout(timer); req.destroy(); reject(signal.reason ?? new Error('aborted')); return; }
+      signal.addEventListener?.('abort', onAbort, { once: true });
+    }
+
+    req.once('error', (err) => { clearTimeout(timer); cleanupAbort(); reject(err); });
+
+    const body = opts.body;
+    const method = (opts.method || 'GET').toUpperCase();
+    if (body == null || method === 'GET' || method === 'HEAD') req.end();
+    else if (typeof body === 'string' || Buffer.isBuffer(body) || body instanceof Uint8Array) req.end(Buffer.from(body));
+    else req.end(String(body));
+  });
+}
+
+// Adapt a Node IncomingMessage to a web ReadableStream. Done by hand rather than
+// Readable.toWeb because that adapter double-closes the controller on Node 18
+// (ERR_INVALID_STATE "Controller is already closed" when the socket's 'close'
+// fires after 'end'), which crashes the process. The `closed` guard makes close
+// idempotent; backpressure via pause/resume so a slow consumer doesn't buffer the
+// whole (possibly minutes-long) stream in memory.
+function nodeToWeb(res) {
+  let closed = false;
+  const close = (controller) => {
+    if (closed) return;
+    closed = true;
+    try { controller.close(); } catch { /* already closed / consumer gone */ }
+  };
+  return new ReadableStream({
+    start(controller) {
+      res.on('data', (chunk) => {
+        try { controller.enqueue(chunk); } catch { return; }
+        if (controller.desiredSize != null && controller.desiredSize <= 0) res.pause();
+      });
+      res.on('end', () => close(controller));
+      res.on('close', () => close(controller));
+      res.on('error', (err) => {
+        if (closed) return;
+        closed = true;
+        try { controller.error(err); } catch { /* consumer gone */ }
+      });
+    },
+    pull() { res.resume(); },
+    cancel() { res.destroy(); },
+  });
+}
+
+// Wrap a Node IncomingMessage as the subset of a fetch Response that server.js uses.
+function makeResponse(res) {
+  const web = nodeToWeb(res); // single web stream — one consumer either way
+  const collect = async () => {
+    const chunks = [];
+    const reader = web.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+  };
+  return {
+    status: res.statusCode,
+    ok: res.statusCode >= 200 && res.statusCode < 300,
+    headers: makeHeaders(res.headers),
+    body: web,
+    async json() { return JSON.parse((await collect()).toString('utf8')); },
+    async text() { return (await collect()).toString('utf8'); },
+    async arrayBuffer() { const b = await collect(); return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength); },
+  };
+}
+
+// res.headers already has lowercased keys; values are string | string[] (set-cookie).
+function makeHeaders(h) {
+  const flat = (v) => (Array.isArray(v) ? v.join(', ') : v);
+  const entries = function* () { for (const [k, v] of Object.entries(h)) yield [k, flat(v)]; };
+  return {
+    get: (name) => { const v = h[name.toLowerCase()]; return v == null ? null : flat(v); },
+    entries,
+    [Symbol.iterator]: entries,
+  };
+}

package/src/upstream-proxy.js

@@ -0,0 +1,214 @@
+// Outbound (egress) proxy for everything teamclaude sends to Anthropic.
+//
+// Distinct from two other things that also say "proxy" in this codebase:
+//   - `config.proxy` is the LOCAL server Claude Code talks to (inbound).
+//   - `config.sx` is the sx.org residential-egress integration, a specific
+//     paid provider with its own provisioning API and its own routing policy
+//     (always / on-429 / off).
+// This one is the plain corporate case: the machine cannot open a socket to
+// api.anthropic.com at all, and every outbound connection has to go through an
+// HTTP CONNECT proxy (issue #155). It is not a routing policy — when set, it is
+// simply how this host reaches the internet.
+//
+// Node's global fetch cannot use a CONNECT proxy without undici, and "zero
+// dependencies" is a project feature, so the tunnel is built by hand on top of
+// the same connectThroughProxy() the sx path uses.
+//
+// Precedence: an explicit request to route via sx wins (sx IS an egress proxy;
+// chaining one through the other would be two hops to solve one problem). With
+// sx off or not selected for this attempt, the upstream proxy applies.
+
+import http from 'node:http';
+import https from 'node:https';
+import tls from 'node:tls';
+import { connectThroughProxy } from './sx.js';
+
+/**
+ * Parse a proxy URL into the shape connectThroughProxy wants.
+ *
+ * Accepts `http://host:port`, `http://user:pass@host:port`, and a bare
+ * `host:port` (people write proxies that way constantly, and rejecting it would
+ * be pedantry). Returns null for empty input; throws on input that looks like a
+ * URL but isn't usable, so a typo in the config surfaces at startup rather than
+ * as a mystery connection failure on the first request.
+ */
+export function parseProxyUrl(value) {
+  if (!value || typeof value !== 'string') return null;
+  const raw = value.trim();
+  if (!raw) return null;
+
+  // A bare host:port has no scheme; give it one so URL can do the parsing.
+  const withScheme = /^[a-z0-9+.-]+:\/\//i.test(raw) ? raw : `http://${raw}`;
+  let u;
+  try {
+    u = new URL(withScheme);
+  } catch {
+    throw new Error(`invalid proxy URL: ${value}`);
+  }
+  if (!/^https?:$/.test(u.protocol)) {
+    // socks5:// is a different wire protocol, not a CONNECT proxy — say so
+    // plainly instead of failing later inside the tunnel.
+    throw new Error(`unsupported proxy protocol "${u.protocol.replace(/:$/, '')}" (only http/https): ${value}`);
+  }
+  if (!u.hostname) throw new Error(`proxy URL has no host: ${value}`);
+
+  const port = u.port ? Number(u.port) : (u.protocol === 'https:' ? 443 : 8080);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`proxy URL has an invalid port: ${value}`);
+  }
+  return {
+    host: u.hostname,
+    port,
+    // decodeURIComponent so a password containing e.g. %40 survives the round trip.
+    username: u.username ? decodeURIComponent(u.username) : null,
+    password: u.password ? decodeURIComponent(u.password) : null,
+  };
+}
+
+/**
+ * Render a proxy back to a storable URL, credentials intact. For writing the
+ * config — never for logs or the screen, which must use describeProxy().
+ */
+export function proxyToUrl(proxy) {
+  if (!proxy) return null;
+  const auth = proxy.username
+    ? `${encodeURIComponent(proxy.username)}${proxy.password ? `:${encodeURIComponent(proxy.password)}` : ''}@`
+    : '';
+  return `http://${auth}${proxy.host}:${proxy.port}`;
+}
+
+/** Render a proxy back to a string, with the password masked. For logs and the TUI. */
+export function describeProxy(proxy) {
+  if (!proxy) return 'none';
+  const auth = proxy.username ? `${proxy.username}:***@` : '';
+  return `http://${auth}${proxy.host}:${proxy.port}`;
+}
+
+/**
+ * NO_PROXY matching, in the form everyone else implements it: a comma-separated
+ * list of suffixes, where a leading dot is optional and `*` disables the proxy
+ * entirely. Matching is on the hostname only — the port-qualified form
+ * (`host:443`) is accepted and its port ignored, which is what curl does.
+ */
+export function bypassesProxy(hostname, noProxy) {
+  if (!noProxy || !hostname) return false;
+  const host = hostname.toLowerCase().replace(/\.$/, '');
+  for (const raw of String(noProxy).split(',')) {
+    const entry = raw.trim().toLowerCase().replace(/:\d+$/, '').replace(/^\./, '').replace(/\.$/, '');
+    if (!entry) continue;
+    if (entry === '*') return true;
+    if (host === entry || host.endsWith(`.${entry}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Where the proxy setting comes from, in precedence order: the config file
+ * first (explicit and persistent), then the conventional environment variables.
+ *
+ * Honouring the environment matters for the reported case — the operator had
+ * already set HTTPS_PROXY and reasonably expected it to be used (#155). It is
+ * also what every other CLI on that machine does. `config.upstreamProxy: false`
+ * opts out entirely, for a host where the variables are set for other tools but
+ * must not apply here.
+ */
+export function resolveUpstreamProxy(config = {}, env = process.env) {
+  if (config.upstreamProxy === false) return { proxy: null, source: 'disabled', noProxy: null };
+
+  const noProxy = config.noProxy ?? env.NO_PROXY ?? env.no_proxy ?? null;
+
+  if (config.upstreamProxy) {
+    return { proxy: parseProxyUrl(config.upstreamProxy), source: 'config', noProxy };
+  }
+  const candidates = [
+    ['HTTPS_PROXY', env.HTTPS_PROXY], ['https_proxy', env.https_proxy],
+    ['ALL_PROXY', env.ALL_PROXY], ['all_proxy', env.all_proxy],
+  ];
+  for (const [name, value] of candidates) {
+    if (value) return { proxy: parseProxyUrl(value), source: `env:${name}`, noProxy };
+  }
+  return { proxy: null, source: 'none', noProxy };
+}
+
+// ── Process-wide state ───────────────────────────────────────
+//
+// A single setting for the whole process rather than a value threaded through
+// every call: it describes how this HOST reaches the network, so every outbound
+// path (request forwarding, token refresh, profile and usage lookups) must agree
+// on it. Threading it would mean passing config into oauth.js, which has no
+// business knowing about config.
+
+// Undefined until something resolves it. Reading it falls back to the
+// environment alone, so short-lived commands that never load a config (and any
+// code path that runs before startup wiring) still honour HTTPS_PROXY instead of
+// silently going direct. A bad value in the environment must not take a command
+// down, so a parse failure degrades to "no proxy" here and is reported loudly at
+// startup, where the config value is validated eagerly.
+let current = null;
+
+export function setUpstreamProxy(resolved) {
+  current = resolved || { proxy: null, source: 'none', noProxy: null };
+  return current;
+}
+
+export function getUpstreamProxy() {
+  if (!current) {
+    try { current = resolveUpstreamProxy({}, process.env); } catch { current = { proxy: null, source: 'none', noProxy: null }; }
+  }
+  return current;
+}
+
+/** Reset the memo. Tests only. */
+export function resetUpstreamProxy() { current = null; }
+
+/** The proxy to use for `hostname`, or null when going direct. */
+export function proxyForHost(hostname) {
+  const { proxy, noProxy } = getUpstreamProxy();
+  if (!proxy) return null;
+  if (bypassesProxy(hostname, noProxy)) return null;
+  return proxy;
+}
+
+/**
+ * An http(s).Agent whose sockets are CONNECT tunnels through `proxy`.
+ *
+ * keepAlive is off: createConnection closes over one target, so a pooled socket
+ * could not be reused for a different host anyway, and parking it would leak an
+ * open proxy connection per request. The upstream path's reason for pooling
+ * (#106 — avoiding a single multiplexed h2 connection) still holds, because each
+ * tunnel is its own TCP connection carrying its own HTTP/1.1 exchange.
+ */
+export function proxyAgent(proxy, { targetHost, targetPort, tls: useTls = true, tlsOptions = {} }) {
+  const agent = new (useTls ? https : http).Agent({ keepAlive: false });
+  agent.createConnection = (_options, cb) => {
+    connectThroughProxy({
+      proxyHost: proxy.host,
+      proxyPort: proxy.port,
+      auth: proxy.username ? `${proxy.username}:${proxy.password ?? ''}` : null,
+      targetHost,
+      targetPort,
+      label: 'upstream proxy',
+    })
+      .then((sock) => {
+        if (!useTls) {
+          // connectThroughProxy pauses the socket so a TLS layer sees every
+          // byte. Nothing resumes it on the plaintext path, so the HTTP parser
+          // would attach to a socket that never flows and the request would sit
+          // until the headers deadline. Resume after the caller has it.
+          cb(null, sock);
+          sock.resume();
+          return;
+        }
+        // TLS is established end-to-end over the tunnel, so the proxy sees only
+        // ciphertext and cert verification stays at its secure default.
+        const tlsSock = tls.connect({ socket: sock, servername: targetHost, ...tlsOptions });
+        const onErr = (err) => { tlsSock.removeListener('secureConnect', onOk); sock.destroy(); cb(err); };
+        const onOk = () => { tlsSock.removeListener('error', onErr); cb(null, tlsSock); };
+        tlsSock.once('secureConnect', onOk);
+        tlsSock.once('error', onErr);
+      })
+      .catch((err) => cb(err));
+    return undefined; // socket is delivered asynchronously through cb
+  };
+  return agent;
+}