@karpeleslab/teamclaude 1.0.7 → 1.0.9

package/src/sx.js

@@ -0,0 +1,218 @@
+// sx.org proxy integration — an IP-based-429 workaround.
+//
+// teamclaude's transient 429s key on the proxy's OUTBOUND IP, not the account,
+// so account failover doesn't help. sx.org is a residential proxy-port provider:
+// with an API key we provision a port and tunnel upstream Anthropic traffic
+// through it, giving a different egress IP. Crucially, TLS terminates END-TO-END
+// at the upstream (we `tls.connect` over the tunnel with the upstream's
+// servername and the default secure cert check) — the sx.org proxy only ever
+// relays ciphertext and cannot see request content.
+//
+// When no API key is configured (or mode is 'off') this module is dormant and the
+// dial paths behave exactly as before — routing is decided per-attempt by
+// useByDefault() / useOn429() / useForConnect(), all false until provisioned.
+
+import net from 'node:net';
+import tls from 'node:tls';
+
+const CONNECT_TIMEOUT_MS = 30000; // residential exits can be slow to establish
+
+// Resolved per call (not at import) so tests can point it at a local mock.
+const sxBase = () => process.env.SX_API_BASE || 'https://api.sx.org';
+
+// ── sx.org REST (apiKey is a query param; these hit api.sx.org directly, never
+// the proxy, and are unrelated to Anthropic traffic) ──
+async function sxGet(path, apiKey, params = {}) {
+  const url = new URL(sxBase() + path);
+  url.searchParams.set('apiKey', apiKey);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
+  const res = await fetch(url, { headers: { accept: 'application/json' } });
+  return res.json();
+}
+
+async function sxPost(path, apiKey, body) {
+  const url = new URL(sxBase() + path);
+  url.searchParams.set('apiKey', apiKey);
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return res.json();
+}
+
+export const SX_MODES = ['off', '429', 'always'];
+const normalizeMode = (m) => (SX_MODES.includes(m) ? m : 'always');
+
+// Normalize either API shape into { host, port, username, password, portId }.
+//   ports-list:  { proxy: "host:port", login, password, id }
+//   create-port: { server, port, login, password, id }
+function parsePort(p) {
+  let host, port;
+  if (typeof p.proxy === 'string' && p.proxy.includes(':')) {
+    const i = p.proxy.lastIndexOf(':');
+    host = p.proxy.slice(0, i); port = p.proxy.slice(i + 1);
+  } else {
+    host = p.server; port = p.port;
+  }
+  return { host, port: parseInt(port, 10), username: p.login, password: p.password, portId: p.id };
+}
+
+/**
+ * Open a CONNECT tunnel through an HTTP proxy to targetHost:targetPort and
+ * resolve with the raw (still-plaintext) socket once the proxy answers 200.
+ */
+export function connectThroughProxy({ proxyHost, proxyPort, auth, targetHost, targetPort, timeout = CONNECT_TIMEOUT_MS }) {
+  return new Promise((resolve, reject) => {
+    // autoSelectFamily (happy-eyeballs) — default on Node 20+ but not 18; set it
+    // so a dual-stack proxy host whose IPv6 path is unreachable falls back to IPv4
+    // instead of hanging the connect (sx.org returns an IP, but be robust).
+    const sock = net.connect({ port: proxyPort, host: proxyHost, autoSelectFamily: true });
+    let buf = '';
+    const timer = setTimeout(() => fail(new Error(`sx.org proxy CONNECT timed out after ${timeout}ms`)), timeout);
+    const cleanup = () => {
+      clearTimeout(timer);
+      sock.removeListener('data', onData);
+      sock.removeListener('error', fail);
+    };
+    const fail = (err) => { cleanup(); sock.destroy(); reject(err); };
+    const onData = (chunk) => {
+      buf += chunk.toString('latin1');
+      const idx = buf.indexOf('\r\n\r\n');
+      if (idx < 0) { if (buf.length > 65536) fail(new Error('sx.org proxy CONNECT response too large')); return; }
+      const statusLine = buf.slice(0, buf.indexOf('\r\n'));
+      const m = statusLine.match(/^HTTP\/\d\.\d\s+(\d{3})/);
+      if (!m || m[1] !== '200') { fail(new Error(`sx.org proxy refused CONNECT: ${statusLine}`)); return; }
+      cleanup();
+      sock.pause(); // stop flowing so the TLS layer we hand it to sees every byte
+      const rest = Buffer.from(buf.slice(idx + 4), 'latin1'); // bytes already past the header
+      if (rest.length) sock.unshift(rest);
+      resolve(sock);
+    };
+    sock.once('connect', () => {
+      const lines = [`CONNECT ${targetHost}:${targetPort} HTTP/1.1`, `Host: ${targetHost}:${targetPort}`];
+      if (auth) lines.push(`Proxy-Authorization: Basic ${Buffer.from(auth).toString('base64')}`);
+      lines.push('Proxy-Connection: keep-alive', '', '');
+      sock.write(lines.join('\r\n'));
+    });
+    sock.on('data', onData);
+    sock.once('error', fail);
+  });
+}
+
+/**
+ * CONNECT through `proxy`, then complete a TLS handshake to targetHost so TLS is
+ * end-to-end (the proxy sees ciphertext only). Resolves with the TLSSocket after
+ * secureConnect. Cert verification stays at its secure default; tests inject a CA
+ * via tlsOptions.ca.
+ */
+export async function tunnelTls({ proxy, targetHost, targetPort = 443, tlsOptions = {} }) {
+  const sock = await connectThroughProxy({
+    proxyHost: proxy.host,
+    proxyPort: proxy.port,
+    auth: proxy.username ? `${proxy.username}:${proxy.password}` : null,
+    targetHost,
+    targetPort,
+  });
+  return new Promise((resolve, reject) => {
+    const tlsSock = tls.connect({ socket: sock, servername: targetHost, ...tlsOptions });
+    const onErr = (err) => { tlsSock.removeListener('secureConnect', onOk); sock.destroy(); reject(err); };
+    const onOk = () => { tlsSock.removeListener('error', onErr); resolve(tlsSock); };
+    tlsSock.once('secureConnect', onOk);
+    tlsSock.once('error', onErr);
+  });
+}
+
+/**
+ * Holds the sx.org credential + the provisioned proxy. Shared in-process by the
+ * reverse proxy, the MITM handler, and the TUI so a key change applies live.
+ */
+export class SxManager {
+  constructor({ log = () => {} } = {}) {
+    this.log = log;
+    this.apiKey = null;
+    this.proxy = null;   // { host, port, username, password, portId }
+    this.mode = 'always'; // off | 429 | always — how routing decisions are made
+    this._rlUntil = 0;    // sticky-routing window end (ms) for '429' mode
+  }
+
+  isProvisioned() { return !!(this.apiKey && this.proxy); }
+  getProxy() { return this.proxy; }
+  getMode() { return this.mode; }
+
+  // ── routing decisions ──
+  // Reverse-proxy first attempt: only 'always' routes pre-emptively.
+  useByDefault() { return this.isProvisioned() && this.mode === 'always'; }
+  // Reverse-proxy retry after a 429: 'always' and '429' both route (the 429 is
+  // IP-based, so a fresh egress IP can clear it).
+  useOn429() { return this.isProvisioned() && this.mode !== 'off'; }
+  // MITM connect-time (one tunnel carries many requests, so no per-request
+  // failover): 'always' routes; '429' routes only inside the sticky window set
+  // when a 429 was recently observed.
+  useForConnect() {
+    if (!this.isProvisioned() || this.mode === 'off') return false;
+    return this.mode === 'always' || this.isRecentlyRateLimited();
+  }
+
+  noteRateLimited(seconds = 60) { this._rlUntil = Date.now() + Math.min(Math.max(seconds, 1), 300) * 1000; }
+  isRecentlyRateLimited() { return Date.now() < this._rlUntil; }
+
+  /** Set the API key (+ optional mode) and provision unless mode is 'off'. */
+  async configure(apiKey, mode = this.mode) {
+    this.mode = normalizeMode(mode);
+    if (!apiKey) { this.disable(); return { ok: false, error: 'no API key' }; }
+    this.apiKey = apiKey;
+    if (this.mode === 'off') { this.proxy = null; return { ok: true, mode: this.mode, proxy: null }; }
+    return this._ensureProxy();
+  }
+
+  /** Switch mode WITHOUT clearing the key; provision lazily when turning on. */
+  async setMode(mode) {
+    this.mode = normalizeMode(mode);
+    if (this.mode === 'off') { this.proxy = null; return { ok: true, mode: this.mode }; }
+    if (this.apiKey && !this.proxy) return this._ensureProxy();
+    return { ok: true, mode: this.mode, proxy: this.proxy };
+  }
+
+  /** Full deconfigure — forget the key entirely. */
+  disable() { this.apiKey = null; this.proxy = null; }
+
+  async _ensureProxy() {
+    try {
+      this.proxy = await this.provision();
+      this.log(`[TeamClaude] sx.org proxy ready: ${this.proxy.host}:${this.proxy.port}`);
+      return { ok: true, mode: this.mode, proxy: this.proxy };
+    } catch (err) {
+      this.proxy = null;
+      this.log(`[TeamClaude] sx.org provisioning failed: ${err.message}`);
+      return { ok: false, error: err.message };
+    }
+  }
+
+  /** Account balance/traffic, or null on error. */
+  async getBalance() {
+    if (!this.apiKey) return null;
+    try {
+      const r = await sxGet('/v2/user/balance', this.apiKey);
+      return r?.success ? r : null;
+    } catch { return null; }
+  }
+
+  /** Reuse an active port if one exists, else create a residential US one. */
+  async provision() {
+    if (!this.apiKey) throw new Error('sx.org API key not set');
+    const list = await sxGet('/v2/proxy/ports', this.apiKey, { per_page: 50 });
+    const proxies = list?.message?.proxies || [];
+    const active = proxies.find((p) => p.status === 1 && p.login && p.password && p.proxy);
+    if (active) return parsePort(active);
+
+    const created = await sxPost('/v2/proxy/create-port', this.apiKey, {
+      country_code: 'US', proxy_type_id: 1, type_id: 1, // type_id 1 = residential
+    });
+    if (!created?.success || !created.data) {
+      const detail = created?.errors ? JSON.stringify(created.errors) : (created?.message || JSON.stringify(created));
+      throw new Error(`sx.org create-port failed: ${detail}`);
+    }
+    return parsePort(created.data);
+  }
+}

package/src/tui.js

@@ -8,6 +8,7 @@ const ESC = '\x1b[';
 const RESET = `${ESC}0m`;
 const BOLD = `${ESC}1m`;
 const DIM = `${ESC}2m`;
+const REV = `${ESC}7m`;   // reverse video — used for the BIOS-style settings cursor
 
 const bold = s => `${BOLD}${s}${RESET}`;
 const dim = s => `${DIM}${s}${RESET}`;
@@ -115,21 +116,25 @@ function timestamp() {
 // ── TUI class ────────────────────────────────────────────────
 
 export class TUI {
-  constructor({ accountManager, config, saveConfig, syncAccounts, onQuit }) {
+  constructor({ accountManager, config, saveConfig, syncAccounts, onQuit, sx = null }) {
     this.am = accountManager;
     this.config = config;
     this.saveConfig = saveConfig;
     this.syncAccounts = syncAccounts;
     this.onQuit = onQuit;
+    this.sx = sx;            // sx.org proxy manager (may be null)
+    this.sxBalance = null;   // last fetched sx.org balance, for the settings screen
 
     this.log = [];           // completed activity entries
     this.active = new Map(); // in-flight requests
-    this.mode = 'normal';    // normal | select | add | input
+    this.mode = 'normal';    // normal | select | add | input | settings
     this.selAction = null;   // switch | remove
     this.selIdx = 0;
+    this.setIdx = 0;         // cursor row on the settings screen (BIOS-style nav)
     this.inputPrompt = '';
     this.inputBuf = '';
     this.inputCb = null;
+    this.inputReturn = 'normal'; // mode to fall back to when an input is cancelled
     this.frame = 0;
     this.running = false;
     this.timer = null;
@@ -206,6 +211,8 @@ export class TUI {
   _onData(d) {
     if (d === '\x1b[A') return this._key('up');
     if (d === '\x1b[B') return this._key('down');
+    if (d === '\x1b[C') return this._key('right');
+    if (d === '\x1b[D') return this._key('left');
     if (d === '\x1b') return this._key('esc');
     if (d === '\r' || d === '\n') return this._key('enter');
     if (d === '\x03') return this._key('ctrl-c');
@@ -221,6 +228,7 @@ export class TUI {
       case 'select': this._keySelect(k); break;
       case 'add':    this._keyAdd(k); break;
       case 'input':  this._keyInput(k); break;
+      case 'settings': this._keySettings(k); break;
     }
     this.render();
   }
@@ -238,6 +246,148 @@ export class TUI {
     }
     else if (k === 'a') { this.mode = 'add'; }
     else if (k === 'R') { this._doSync(); }
+    else if (k === 'g' && this.sx) { this.mode = 'settings'; this.setIdx = 0; this._loadSxBalance(); }
+  }
+
+  // Navigable rows on the settings screen, top to bottom. Both the renderer and
+  // the key handler build this list so the cursor and the display stay in sync.
+  // Rows are conditional (sx.org rows only when that build feature is present),
+  // so always index through the returned array — never hard-code positions.
+  _settingsFields() {
+    const fields = [];
+
+    fields.push({
+      id: 'threshold',
+      label: 'Switch threshold',
+      hint: '←→ ±1%',
+      value: () => {
+        const thr = this.am.switchThreshold ?? this.config.switchThreshold ?? 0.98;
+        return green(`${Math.round(thr * 100)}%`);
+      },
+      left: () => this._nudgeThreshold(-1),
+      right: () => this._nudgeThreshold(+1),
+      enter: () => this._promptInput('Switch threshold % (1-100)', v => this._doSetThreshold(v.trim())),
+    });
+
+    fields.push({
+      id: 'probe',
+      label: 'Quota probe',
+      hint: '←→ ±30s',
+      value: () => {
+        const probe = this.config.quotaProbeSeconds || 0;
+        return probe > 0 ? green(`${probe}s`) : gray('off (passive)');
+      },
+      left: () => this._nudgeProbe(-30),
+      right: () => this._nudgeProbe(+30),
+      enter: () => this._promptInput('Quota probe seconds (0=off, min 30)', v => this._doSetProbe(v.trim())),
+    });
+
+    if (this.sx) {
+      fields.push({
+        id: 'sxmode',
+        label: 'sx.org mode',
+        hint: '←→ cycle',
+        value: () => {
+          const mode = this.sx.getMode();
+          return mode === 'always' ? green('always')
+            : mode === '429' ? cyan('on 429 only')
+            : gray('off');
+        },
+        left: () => this._cycleSxMode(-1),
+        right: () => this._cycleSxMode(+1),
+        enter: () => this._cycleSxMode(+1),
+      });
+
+      fields.push({
+        id: 'sxkey',
+        label: 'sx.org API key',
+        hint: 'Enter to set',
+        value: () => {
+          const key = this.config.sx?.apiKey;
+          return key ? key.slice(0, 4) + '…' + key.slice(-4) : dim('(not set)');
+        },
+        enter: () => this._promptInput('sx.org API key', v => this._doSetSxKey(v.trim())),
+      });
+
+      if (this.config.sx?.apiKey) {
+        fields.push({
+          id: 'sxclear',
+          label: 'Clear sx.org key',
+          hint: 'Enter to clear',
+          value: () => dim('—'),
+          enter: () => this._doClearSxKey(),
+        });
+      }
+    }
+
+    return fields;
+  }
+
+  _keySettings(k) {
+    const fields = this._settingsFields();
+    const n = fields.length;
+    if (n > 0 && this.setIdx >= n) this.setIdx = n - 1;
+    const f = fields[this.setIdx];
+
+    if (k === 'up' || k === 'k') this.setIdx = (this.setIdx - 1 + n) % n;
+    else if (k === 'down' || k === 'j') this.setIdx = (this.setIdx + 1) % n;
+    else if (k === 'left') f?.left?.();
+    else if (k === 'right') f?.right?.();
+    else if (k === 'enter') f?.enter?.();
+    else if (k === 'esc' || k === 'q') { this.mode = 'normal'; }
+  }
+
+  // Open the text-input prompt and return to the settings screen afterward.
+  _promptInput(prompt, cb) {
+    this.mode = 'input';
+    this.inputReturn = 'settings';
+    this.inputPrompt = prompt;
+    this.inputBuf = '';
+    this.inputCb = v => { if (v) cb(v); };
+  }
+
+  _nudgeThreshold(deltaPct) {
+    const cur = Math.round((this.am.switchThreshold ?? this.config.switchThreshold ?? 0.98) * 100);
+    const next = Math.max(1, Math.min(100, cur + deltaPct));
+    if (next !== cur) this._doSetThreshold(String(next));
+  }
+
+  _nudgeProbe(deltaSec) {
+    const cur = this.config.quotaProbeSeconds || 0;
+    const next = Math.max(0, cur + deltaSec);
+    if (next !== cur) this._doSetProbe(String(next));
+  }
+
+  async _doSetThreshold(input) {
+    const pct = Number(input);
+    if (!Number.isFinite(pct) || pct < 1 || pct > 100) {
+      this._addLog('Invalid threshold — enter 1–100'); this.mode = 'settings'; if (this.running) this.render(); return;
+    }
+    const v = Math.round(pct) / 100;
+    this.config.switchThreshold = v;
+    this.am.switchThreshold = v; // apply to the running rotation immediately
+    try { await this.saveConfig(this.config); }
+    catch (e) { this._addLog(`Failed to save: ${e.message}`); }
+    this._addLog(`Switch threshold set to ${Math.round(v * 100)}%`);
+    this.mode = 'settings';
+    if (this.running) this.render();
+  }
+
+  async _doSetProbe(input) {
+    let secs = parseInt(input, 10);
+    if (Number.isNaN(secs) || secs < 0) {
+      this._addLog('Invalid interval — enter 0 (off) or seconds'); this.mode = 'settings'; if (this.running) this.render(); return;
+    }
+    if (secs > 0 && secs < 30) secs = 30; // match the CLI minimum (don't hammer the usage endpoint)
+    this.config.quotaProbeSeconds = secs;
+    try { await this.saveConfig(this.config); }
+    catch (e) { this._addLog(`Failed to save: ${e.message}`); }
+    // syncAccounts re-reads disk config and reschedules the running prober live.
+    try { await this.syncAccounts(); }
+    catch (e) { this._addLog(`Reload failed: ${e.message}`); }
+    this._addLog(secs > 0 ? `Quota probe every ${secs}s` : 'Quota probe disabled');
+    this.mode = 'settings';
+    if (this.running) this.render();
   }
 
   _keySelect(k) {
@@ -262,6 +412,7 @@ export class TUI {
     if (k === 'i') { this._doImport(); this.mode = 'normal'; }
     else if (k === 'k') {
       this.mode = 'input';
+      this.inputReturn = 'normal';
       this.inputPrompt = 'API key';
       this.inputBuf = '';
       this.inputCb = v => { if (v) this._doAddKey(v); };
@@ -273,10 +424,10 @@ export class TUI {
     if (k === 'enter') {
       const cb = this.inputCb;
       const v = this.inputBuf;
-      this.mode = 'normal'; this.inputCb = null; this.inputBuf = '';
+      this.mode = this.inputReturn; this.inputCb = null; this.inputBuf = '';
       cb?.(v);
     }
-    else if (k === 'esc') { this.mode = 'normal'; this.inputCb = null; this.inputBuf = ''; }
+    else if (k === 'esc') { this.mode = this.inputReturn; this.inputCb = null; this.inputBuf = ''; }
     else if (k === 'bs') { this.inputBuf = this.inputBuf.slice(0, -1); }
     else if (k.length === 1) { this.inputBuf += k; }
   }
@@ -296,6 +447,57 @@ export class TUI {
     }
   }
 
+  // ── sx.org settings ────────────────────────────────
+
+  _loadSxBalance() {
+    this.sxBalance = null;
+    if (!this.sx?.apiKey) return;
+    this.sx.getBalance()
+      .then(b => { this.sxBalance = b; if (this.running) this.render(); })
+      .catch(() => {});
+  }
+
+  _sxModeLabel(m) { return m === 'always' ? 'always' : m === '429' ? 'on 429 only' : 'off'; }
+
+  async _doSetSxKey(key) {
+    const mode = this.config.sx?.mode || 'always';
+    this.config.sx = { apiKey: key, mode };
+    try { await this.saveConfig(this.config); }
+    catch (e) { this._addLog(`Failed to save sx.org key: ${e.message}`); }
+    this._addLog('sx.org: configuring...');
+    const r = await this.sx.configure(key, mode);
+    if (r.ok && r.proxy) this._addLog(`sx.org key saved — proxy ${r.proxy.host}:${r.proxy.port} (mode: ${this._sxModeLabel(mode)})`);
+    else if (r.ok) this._addLog(`sx.org key saved (mode: ${this._sxModeLabel(mode)})`);
+    else this._addLog(`sx.org error: ${r.error}`);
+    this._loadSxBalance();
+    this.mode = 'settings';
+    if (this.running) this.render();
+  }
+
+  // Cycle off → on-429 → always (dir +1) or the reverse (dir -1). Keeps the API
+  // key, so the user can disable sx.org without deconfiguring it.
+  async _cycleSxMode(dir = 1) {
+    const order = ['off', '429', 'always'];
+    const next = order[(order.indexOf(this.sx.getMode()) + dir + order.length) % order.length];
+    this.config.sx = { ...(this.config.sx || {}), mode: next };
+    try { await this.saveConfig(this.config); }
+    catch (e) { this._addLog(`Failed to save: ${e.message}`); }
+    const r = await this.sx.setMode(next);
+    this._addLog(`sx.org mode: ${this._sxModeLabel(next)}${r.ok ? '' : ` — ${r.error}`}`);
+    if (next !== 'off') this._loadSxBalance();
+    if (this.running) this.render();
+  }
+
+  async _doClearSxKey() {
+    this.config.sx = null;
+    try { await this.saveConfig(this.config); }
+    catch (e) { this._addLog(`Failed to save: ${e.message}`); }
+    this.sx.disable();
+    this.sxBalance = null;
+    this._addLog('sx.org key cleared');
+    if (this.running) this.render();
+  }
+
   async _doImport() {
     try {
       this._addLog('Importing credentials...');
@@ -439,6 +641,10 @@ export class TUI {
     lines.push(left + ' '.repeat(Math.max(1, W - vw(left) - vw(right))) + right);
     lines.push(' ' + dim('─'.repeat(W - 2)));
 
+    const footerH = 2;
+    if (this.mode === 'settings') {
+      this._renderSettings(lines);
+    } else {
     // ── Accounts
     if (this.am.accounts.length === 0) {
       lines.push('');
@@ -472,11 +678,11 @@ export class TUI {
     }
 
     // Completed log
-    const footerH = 2;
     const space = Math.max(0, H - lines.length - footerH);
     for (let i = 0; i < space && i < this.log.length; i++) {
       lines.push(`   ${gray(this.log[i].t)}  ${this.log[i].msg}`);
     }
+    } // end non-settings body
 
     // Pad to fill
     while (lines.length < H - footerH) lines.push('');
@@ -529,7 +735,7 @@ export class TUI {
     const q = a.quota;
     let r1 = null, r2 = null, l1 = 'Ses', l2 = 'Wk ', t1 = null, t2 = null;
 
-    if (q.unified5h != null || q.unified7d != null) {
+    if (q.unified5h != null || q.unified7d != null || q.unified7dSonnet != null) {
       r1 = q.unified5h;
       r2 = q.unified7d;
       t1 = q.unified5hReset;
@@ -548,14 +754,76 @@ export class TUI {
     let line = ` ${sel}${cur} ${name} ${type} ${status} ${l1} ${bar(r1, bw, t1)}`;
     if (showBoth) {
       line += `  ${l2} ${bar(r2, bw, t2)}`;
+      // Sonnet weekly bar — only shown when the usage probe has populated it.
+      if (q.unified7dSonnet != null) {
+        line += `  S7  ${bar(q.unified7dSonnet, bw, q.unified7dSonnetReset)}`;
+      }
     }
     return line;
   }
 
+  _renderSettings(lines) {
+    const fields = this._settingsFields();
+    if (this.setIdx >= fields.length) this.setIdx = Math.max(0, fields.length - 1);
+    const selId = fields[this.setIdx]?.id;
+    const byId = id => fields.find(f => f.id === id);
+
+    // Render a navigable setting row with a BIOS-style highlight bar on the
+    // cursor row. Read-only info rows pass field=null and never highlight.
+    const row = field => {
+      const selected = field && field.id === selId;
+      const label = (field ? field.label : '').padEnd(16);
+      const value = field ? field.value() : '';
+      if (selected) {
+        const hint = field.hint ? `   ${dim(field.hint)}` : '';
+        const inner = rpad(` ${label}  ${strip(value)} `, 34);
+        return `  ${cyan('▸')}${REV}${inner}${RESET}${hint}`;
+      }
+      return `    ${dim(label)}  ${value}`;
+    };
+    // A plain read-only info line (not selectable), aligned with the rows above.
+    const info = (label, value) => `    ${dim(label.padEnd(16))}  ${value}`;
+
+    lines.push('');
+    // ── Rotation
+    lines.push(bold('  Rotation') + dim('  — switch accounts when quota crosses the threshold'));
+    lines.push(row(byId('threshold')));
+    lines.push('');
+    // ── Quota probe
+    lines.push(bold('  Quota probe') + dim('  — refresh idle accounts from the usage endpoint'));
+    lines.push(row(byId('probe')));
+    lines.push('');
+    // ── sx.org
+    lines.push(bold('  sx.org proxy') + dim('  — route upstream via a residential IP (429 workaround)'));
+    lines.push('');
+    if (!this.sx) { lines.push(yellow('  Unavailable in this build.')); return; }
+    const key = this.config.sx?.apiKey;
+    const mode = this.sx.getMode();
+    const p = this.sx.getProxy?.();
+    const proxyStr = mode === 'off' ? gray('—')
+      : this.sx.isProvisioned() ? green(`${p.host}:${p.port}`)
+      : key ? yellow('not provisioned')
+      : gray('no key');
+    const b = this.sxBalance;
+    lines.push(row(byId('sxmode')));
+    lines.push(row(byId('sxkey')));
+    lines.push(info('Proxy', proxyStr));
+    lines.push(info('Balance', b ? green('$' + Number(b.balance).toFixed(4)) : dim('…')));
+    if (byId('sxclear')) lines.push(row(byId('sxclear')));
+    lines.push('');
+    lines.push(dim('  always    tunnel ALL upstream traffic through sx.org'));
+    lines.push(dim('  on 429    only retry through sx.org after a 429 (fresh IP)'));
+    lines.push(dim('  off       never use sx.org (API key is kept)'));
+    lines.push('');
+    lines.push(dim('  TLS stays end-to-end; residential traffic is metered by sx.org.'));
+  }
+
   _renderFooter() {
     switch (this.mode) {
       case 'normal':
-        return ` ${bold('s')}witch  ${bold('a')}dd  ${bold('r')}emove  ${bold('d')}isable  ${bold('R')}eload  ${bold('q')}uit`;
+        return ` ${bold('s')}witch  ${bold('a')}dd  ${bold('r')}emove  ${bold('d')}isable  ${bold('R')}eload  ${bold('g')} settings  ${bold('q')}uit`;
+      case 'settings':
+        return ` ${dim('↑↓')} navigate  ${dim('←→')} change  ${bold('Enter')} edit  ${bold('Esc')} back`;
       case 'select': {
         const act = this.selAction === 'switch' ? 'switch'
           : this.selAction === 'toggle' ? 'enable/disable'