@rikcodes/teamclaude 1.1.13-rik.2 → 1.1.13-rik.5

package/README.md

@@ -1,8 +1,12 @@
 # TeamClaude
 
-> **Fork notice (rikbrown).** This fork adds three features and two reload fixes on top of
+> **Fork notice (rikbrown).** This fork adds four features and two reload fixes on top of
 > [KarpelesLab/teamclaude](https://github.com/KarpelesLab/teamclaude):
 >
+> - **[OpenAI models via a Codex sidecar](docs/openai.md)** (`sidecars` + `customModels`, opt-in):
+>   route `gpt-*` requests through a supervised local translating proxy to a ChatGPT subscription,
+>   under real model names — `/model gpt-5.6-sol` in the picker and typed, correct 272k context
+>   sizing, and dispatchable GPT subagents — while Claude traffic stays on the Claude accounts.
 > - **[Soonest-weekly rotation](docs/routing.md#soonest-weekly-rotation)** (`soonestWeekly`, opt-in): rank
 >   equal-priority accounts by the weekly window that governs the requested model, continuously — preempt the
 >   current account when another resets more than `poolHours` sooner, and balance `distributeSessions` within
@@ -12,12 +16,14 @@
 >   bucket's consumption over a rolling window and tag every account row with whichever window binds
 >   first — `Ses TTL 38m` when it runs out before it resets, `Wk 22% unspent` when the reset arrives
 >   first and that much expires. A readout only: no selection code reads it.
-> - **[Session titles](docs/usage.md#session-titles-in-the-activity-log)** (`sessionTitles`, on by default):
+> - **[Session titles](docs/usage.md#session-titles-in-the-activity-log)** (`sessionTitles`, off by default):
 >   name each activity row after the Claude Code session that sent the request, reading the title
 >   `/rename` writes and the one Claude Code generates. A session with neither keeps its short id.
 > - `soonestWeekly` and `distributeSessions` changes now apply on config reload; upstream applies
 >   `distributeSessions` only at startup.
 >
+> Setup and use of each: [Fork features](#fork-features).
+>
 > Published as [`@rikcodes/teamclaude`](https://www.npmjs.com/package/@rikcodes/teamclaude); self-update
 > tracks that package, so installs of this fork can never be replaced by an upstream release.
 >
@@ -68,6 +74,7 @@ Already logged into Claude Code? `teamclaude import` takes its credentials inste
 - Holds the request open until quota resets instead of returning 429 when every account is spent, so an unattended run finishes on its own (`holdSeconds`, off by default).
 - Refreshes OAuth tokens before they expire and writes them back to config. Client refreshes pass through untouched.
 - Takes any Anthropic-compatible API (DeepSeek, GLM) as a low-priority fallback for when the Claude accounts are done.
+- Serves OpenAI models next to Claude ones — a supervised local sidecar translates `gpt-*` requests onto a ChatGPT subscription, with real model names in `/model` and GPT subagents dispatchable from a Claude parent (`sidecars` + `customModels`, this fork).
 - No dependencies. Node built-ins only.
 
 ## Everyday commands
@@ -99,6 +106,95 @@ Every field, plus environment variables and network tuning: [docs/configuration.
 
 Step-by-step lifecycle: [docs/routing.md](docs/routing.md#request-lifecycle).
 
+## Fork features
+
+How to set up and use the features in this fork. Everything else in this README is upstream behaviour.
+
+### OpenAI models via a Codex sidecar
+
+A Claude Code session can use OpenAI models alongside the Claude accounts. They are billed to a ChatGPT Plus/Pro subscription and use their real model names in the same session. TeamClaude does not translate the wire format itself. A local **sidecar** does this: [raine/claude-code-proxy](https://github.com/raine/claude-code-proxy) speaks `/v1/messages` on the front and the Codex Responses API on the back. TeamClaude starts and supervises this process. It sends every `gpt-*` request to the sidecar and keeps every other request on the Claude accounts.
+
+**1. Install the sidecar and log it into your ChatGPT account** (one time):
+
+```bash
+brew install raine/claude-code-proxy/claude-code-proxy
+claude-code-proxy codex auth login
+```
+
+**2. Connect it** — add four pieces to `~/.config/teamclaude.json`:
+
+```json
+{
+  "sidecars": [
+    { "name": "codex", "command": ["claude-code-proxy", "serve", "--no-monitor", "--port", "18765"] }
+  ],
+  "accounts": [
+    { "name": "codex", "type": "oauth", "accessToken": "unused-local-sidecar",
+      "upstream": "http://127.0.0.1:18765", "priority": 100 }
+  ],
+  "routes": [
+    { "name": "codex", "match": ["gpt-*"], "accounts": ["codex"] },
+    { "name": "anthropic", "match": ["*"], "accounts": ["your-claude-account", "..."] }
+  ],
+  "customModels": [
+    { "model": "gpt-5.6-sol",   "label": "GPT-5.6 Sol",   "contextTokens": 272000 },
+    { "model": "gpt-5.6-terra", "label": "GPT-5.6 Terra", "contextTokens": 272000 },
+    { "model": "gpt-5.6-luna",  "label": "GPT-5.6 Luna",  "contextTokens": 272000 }
+  ]
+}
+```
+
+- `sidecars` — the process that TeamClaude owns. It starts with the server, restarts with backoff after a crash, and stops on shutdown. Its pid, restart count and latest stderr lines are in `teamclaude status --json` under `sidecars`.
+- `accounts` — the sidecar as a [third-party backend account](docs/accounts.md#third-party-backend-accounts). The token is a placeholder because the sidecar uses its own Codex login for authentication. `priority: 100` is the convention for third-party backends. The routes determine what reaches it.
+- `routes` — sends `gpt-*` to the sidecar. **Keep the catch-all `*` route.** Without it, the sidecar joins the exhaustion-fallback pool. A spent Claude fleet would then silently send Claude-model requests to the sidecar, which maps `claude-*` names onto GPT models. With the route, a request can reach a GPT model only when it asks for one by name.
+- `customModels` — the rows that make the models visible to Claude Code (next section).
+
+**3. Restart the server.** `teamclaude status --json` should show the sidecar as `running`. If it enters a crash loop, `stderrTail` explains why — the usual cause is that the sidecar is not logged in.
+
+#### How models get into Claude Code
+
+Claude Code offers only models that it knows, and it does not know `gpt-*`. `customModels` closes this gap. Each row contains a model id that the proxy can serve, an optional picker label and description, and the model's context window.
+
+At launch, `teamclaude run` — and the `claude` alias, which passes through `run` — gives these rows to Claude Code:
+
+| Row field | Where it ends up |
+| --- | --- |
+| `model`, `label`, `description` | A `/model` picker row under the **real** model id (`--settings`), so `/model gpt-5.6-sol` works picked or typed |
+| `model` | A dispatchable subagent named after the model (`--agents`), so "dispatch a `gpt-5.6-terra` subagent" works from a Claude parent |
+| `contextTokens` | `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, set to the largest value across rows, so Claude Code compacts at the real window instead of assuming 200k |
+
+For tools that spawn `claude` themselves, `teamclaude env` can set only environment variables. It carries the window and `ANTHROPIC_CUSTOM_MODEL_OPTION` for the **first** row. For GPT subagents under `env`, create `~/.claude/agents/<name>.md` with `model: gpt-5.6-terra` in its frontmatter.
+
+Each request is routed by the model name in its body, so one session can freely mix models: use `claude --model gpt-5.6-sol` for a whole session, `/model gpt-5.6-sol` during a session, or a Claude parent that dispatches a GPT subagent.
+
+**To add a model:**
+
+1. Check that your sidecar build lists it: `curl -s http://127.0.0.1:18765/v1/models`. The sidecar has its own allow-list and rejects any id that it does not know, regardless of the TeamClaude configuration. Upgrade the sidecar if the id is missing.
+2. Add a `customModels` row. Codex publishes the window for each model as `context_window` in `~/.codex/models_cache.json`; copy it to `contextTokens`.
+3. Start a new `teamclaude run` session. The rows are read at launch, so you do not need to restart the server. If you upgraded the sidecar binary, restart the server — or send `SIGTERM` to the sidecar process and let the supervisor restart it with the new binary.
+
+Claude Code prints one `[claude-code:unrecognized_model]` line to stderr for each custom model. This is expected; suppressing it would lose the correct context window. The quota bars for the sidecar account show `unknown` unless the sidecar forwards Codex's rate-limit headers — see [Quota](docs/openai.md#quota). Keep the sidecar on loopback, and use **one** ChatGPT subscription for each person. Pooling several subscriptions is the pattern that OpenAI's fraud systems target ([terms of service](docs/openai.md#terms-of-service)).
+
+Full details: [docs/openai.md](docs/openai.md).
+
+### Soonest-weekly rotation
+
+Default selection is sticky. It re-ranks only when the current account is exhausted, so a weekly window can expire with unused quota. `soonestWeekly` re-ranks continuously. Among equal-priority accounts, the one whose governing weekly window resets soonest is used first. It preempts the current account when another account resets more than `poolHours` sooner.
+
+```json
+"soonestWeekly": { "enabled": true, "poolHours": 12 }
+```
+
+`distributeSessions` works with this setting. New sessions balance across that pool instead of across all equal-priority accounts. Both settings take effect when the configuration reloads (upstream applies `distributeSessions` only at startup). Details: [Routing](docs/routing.md#soonest-weekly-rotation).
+
+### Burn-rate projection
+
+This feature is on by default. Each account row shows which window binds first: `Ses TTL 38m` when the session bucket runs out before it resets, or `Wk 22% unspent` when the weekly reset arrives first and that amount of quota expires. This is a readout only; no selection code reads it. Tune or disable it with `projection: { enabled, windowMinutes, wasteFloor }`. Details: [Quota](docs/quota.md#burn-rate-projection).
+
+### Session titles
+
+This feature is off by default. Activity rows use the name of the Claude Code session that sent the request. They use the title written by `/rename` or the title that Claude Code generates; a session with neither keeps its short id. Toggle the feature from the settings screen (**g** → Session titles) or with `sessionTitles: { enabled, width, projectsDir }`. Details: [Usage](docs/usage.md#session-titles-in-the-activity-log).
+
 ## Documentation
 
 | Page | Contents |
@@ -107,6 +203,7 @@ Step-by-step lifecycle: [docs/routing.md](docs/routing.md#request-lifecycle).
 | [Usage](docs/usage.md) | Server and TUI, running Claude Code, shell alias, command reference, logging |
 | [Routing](docs/routing.md) | Rotation, the two kinds of 429, storm control, model routes, session spreading, pinning, prompt cache |
 | [Quota](docs/quota.md) | Quota probe, keep-warm, holding on exhaustion |
+| [OpenAI models](docs/openai.md) | Codex sidecar setup, custom model registration, GPT subagents, limitations |
 | [Configuration](docs/configuration.md) | Config format, every field, environment variables, network tuning |
 | [Proxy modes](docs/proxy-modes.md) | MITM forward proxy, sx.org residential egress |
 | [Compliance](docs/compliance.md) | Terms of service notes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.13-rik.2",
+  "version": "1.1.13-rik.5",
   "description": "Multi-account Claude proxy with automatic quota-based rotation",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -19,9 +19,35 @@ const FORCED_REFRESH_FLOOR_MS = 10_000;
 const PERSISTED_QUOTA_FIELDS = [
   'unified5h', 'unified7d', 'unified7dSonnet', 'unified7dFable',
   'unified5hReset', 'unified7dReset', 'unified7dSonnetReset', 'unified7dFableReset', 'unifiedStatus',
+  'unified7dSonnetSeenAt', 'unified7dFableSeenAt',
   'tokensLimit', 'tokensRemaining', 'requestsLimit', 'requestsRemaining', 'resetsAt',
 ];
 
+// The family (Fable/Sonnet) weekly buckets and the field holding when each was
+// last confirmed by upstream. See _clearExpiredQuotas: a SPENT family reading is
+// only trusted while it is fresh, because nothing but a request of that family
+// can refresh it.
+const FAMILY_WEEKLY_BUCKETS = [
+  { key: 'unified7dFable', label: 'Fable' },
+  { key: 'unified7dSonnet', label: 'Sonnet' },
+];
+
+// Longest Codex window still treated as a session bucket. The two lengths seen
+// in practice are 300 minutes (5h) and 10080 (weekly), so a day sits safely
+// between them.
+const CODEX_WEEKLY_MIN_MINUTES = 1440;
+
+// A Codex `*-reset-at` header as a ms timestamp. The wire format isn't pinned
+// down (the sidecar forwards it opaquely), so accept epoch seconds, epoch ms,
+// or an ISO-8601 date; anything else is null.
+function parseResetAt(value) {
+  if (value == null || value === '') return null;
+  const n = Number(value);
+  if (Number.isFinite(n)) return n > 1e12 ? n : n * 1000;
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
 function emptyQuota() {
   return {
     // Standard API rate limits (API key accounts)
@@ -38,6 +64,11 @@ function emptyQuota() {
     unified7dReset: null,       // ms timestamp
     unified7dSonnetReset: null, // ms timestamp
     unified7dFableReset: null,  // ms timestamp
+    // When each family bucket was last confirmed by upstream (ms timestamp).
+    // Only these two buckets need it: they are the ones a spent reading can seal
+    // itself into, since selection stops sending the family that would refresh them.
+    unified7dSonnetSeenAt: null,
+    unified7dFableSeenAt: null,
     unifiedStatus: null,        // allowed | allowed_warning | rejected
     resetsAt: null,
   };
@@ -89,6 +120,9 @@ function makeAccount(acct, index) {
     // (post-401) refreshes so a burst of stale in-flight requests can't rotate
     // the refresh-token family once per request — see ensureTokenFresh.
     _lastRefreshAt: null,
+    // The refresh token upstream last rejected as invalid, if it is still the
+    // one we hold — see the dead-token guard in ensureTokenFresh.
+    _deadRefreshToken: null,
   };
 }
 
@@ -109,7 +143,7 @@ function sampleModelFor(route) {
 }
 
 export class AccountManager {
-  constructor(accounts, switchThreshold = 0.98, { refreshFn = refreshAccessToken, throttleProbeFloorMs, forcedRefreshFloorMs = FORCED_REFRESH_FLOOR_MS, routes, ramp, distributeSessions = false, soonestWeekly, projection, sessionTracker } = {}) {
+  constructor(accounts, switchThreshold = 0.98, { refreshFn = refreshAccessToken, throttleProbeFloorMs, familyStaleMs, forcedRefreshFloorMs = FORCED_REFRESH_FLOOR_MS, routes, ramp, distributeSessions = false, soonestWeekly, projection, sessionTracker } = {}) {
     // How long a just-minted token is trusted against a forced refresh.
     this._forcedRefreshFloorMs = forcedRefreshFloorMs;
     // Injectable for tests (mirrors Prober's probeFn); defaults to the real
@@ -129,6 +163,13 @@ export class AccountManager {
     // bias selection for a route's models and reset on restart. A pinned account
     // that becomes ineligible is skipped — routing falls back to best-available.
     this.routePins = new Map();
+    // Selection cursor per route (routeName → account index; '' when no route
+    // matches). A single global cursor reads traffic that alternates between
+    // routes as a rotation: the cursor sits on the other route's account, that
+    // account fails this model's route check, and selection "switches" away from
+    // it. Each such switch arms the ramp below, so steady interleaved traffic
+    // holds both accounts at the ramp floor while nothing has failed over.
+    this.routeCursors = new Map();
     this.switchThreshold = switchThreshold;
     this.setRoutes(routes);
     this.setSoonestWeekly(soonestWeekly);
@@ -159,6 +200,13 @@ export class AccountManager {
     // retry-after, short enough that a stale hold cannot pin the fleet.
     this.throttleProbeFloorMs = throttleProbeFloorMs
       ?? (Number(process.env.TEAMCLAUDE_THROTTLE_PROBE_FLOOR_MS) || 60_000);
+    // How long a SPENT family (Fable/Sonnet) weekly reading is trusted before it
+    // is cleared for revalidation (see _clearExpiredQuotas). Long enough that a
+    // genuinely spent bucket costs at most one rejected request per account per
+    // window, short enough that a stale reading cannot lock a family out for the
+    // rest of the weekly window.
+    this.familyStaleMs = familyStaleMs
+      ?? (Number(process.env.TEAMCLAUDE_FAMILY_STALE_MS) || 30 * 60_000);
   }
 
   /** Start (or restart) the ramp window for an account that just became current,
@@ -245,6 +293,16 @@ export class AccountManager {
    * request keeps flowing (upstream then fails just the advisor call).
    */
   getActiveAccount(exclude = null, model = null, advisorModel = null, sessionId = null) {
+    const account = this._pickActiveAccount(exclude, model, advisorModel, sessionId);
+    // Record where this route now sits, whatever path chose it — the steady-state
+    // path returns the account the cursor already names and never reaches the
+    // rotation code, so recording there alone would leave the cursor unset and
+    // the next real failover unpaced.
+    if (account) this.routeCursors.set(this._cursorKey(model), account.index);
+    return account;
+  }
+
+  _pickActiveAccount(exclude, model, advisorModel, sessionId) {
     // Clear expired quotas across all accounts and switch proactively if a
     // session reset made a sooner-expiring account the better choice. This runs
     // on every request so the behaviour holds without the TUI render loop.
@@ -757,6 +815,29 @@ export class AccountManager {
         if (name !== 'fable' && name !== 'sonnet' && !names.has(name)) this.routePins.delete(name);
       }
     }
+    // A reload can rename or drop a route, stranding its cursor under a key
+    // nothing resolves to. Clearing them costs one extra best-available walk per
+    // route and keeps no state that outlives the table it belonged to.
+    this.routeCursors?.clear();
+  }
+
+  /** Cursor key for a model: its route's name, or '' when no route matches. */
+  _cursorKey(model) {
+    return this._routeForModel(model)?.name || '';
+  }
+
+  /** The account this route was serving from before the current selection, or
+   * null when it has none — used to tell a rotation from ordinary routing.
+   *
+   * Before a route has its own cursor, the global one stands in, but only when
+   * it names an account the route could have used: a cursor left on another
+   * route's account was never this route's position, so moving off it is not a
+   * rotation. */
+  _previousCursor(model) {
+    const recorded = this.routeCursors.get(this._cursorKey(model));
+    if (recorded != null) return recorded;
+    const current = this.accounts[this.currentIndex];
+    return current && this._routeAllows(current, model) ? current.index : null;
   }
 
   /** The first configured route whose globs match `model`, or null. */
@@ -947,11 +1028,44 @@ export class AccountManager {
     if (q.unified7dSonnet != null && q.unified7dSonnetReset && now >= q.unified7dSonnetReset) {
       q.unified7dSonnet = null;
       q.unified7dSonnetReset = null;
+      q.unified7dSonnetSeenAt = null;
       changed = true;
     }
     if (q.unified7dFable != null && q.unified7dFableReset && now >= q.unified7dFableReset) {
       q.unified7dFable = null;
       q.unified7dFableReset = null;
+      q.unified7dFableSeenAt = null;
+      changed = true;
+    }
+
+    // A family bucket is refreshed ONLY by upstream evidence for that family:
+    // the `7d_oi` headers ride on Fable responses (they are absent from every
+    // other model's response), and the Sonnet bucket comes from the usage
+    // endpoint — an opt-in probe that is off by default. So once such a bucket
+    // reads spent, selection stops sending that family to the account, which is
+    // also the only thing that could have corrected the reading: it seals itself
+    // in until its cached reset passes, up to a week of lockout on an account
+    // whose real family quota reset long ago (issue #167).
+    //
+    // A spent family reading is therefore trusted only while it is fresh. Past
+    // the staleness floor it is cleared, the family falls back to the shared
+    // weekly bucket, and the next request of that family re-establishes the
+    // truth from real headers — a 429 re-arms the gate with a fresh reading and
+    // a fresh timestamp, so a genuinely spent bucket costs one rejected request
+    // per account per window and no more. A reading with headroom is left alone:
+    // it gates nothing, so it cannot seal anything in.
+    for (const { key, label } of FAMILY_WEEKLY_BUCKETS) {
+      if (q[key] == null || q[key] < this.switchThreshold) continue;
+      const seenField = `${key}SeenAt`;
+      // Unknown age (restored from an older state file, or set by a path that
+      // predates the stamp): start the clock now rather than clearing at once,
+      // so a reading is never discarded before it has had a window to prove out.
+      if (!q[seenField]) { q[seenField] = now; continue; }
+      if (now < q[seenField] + this.familyStaleMs) continue;
+      console.log(`[TeamClaude] Account "${account.name}" ${label} weekly reading is stale — revalidating on the next ${label} request`);
+      q[key] = null;
+      q[`${key}Reset`] = null;
+      q[seenField] = null;
       changed = true;
     }
 
@@ -1116,7 +1230,8 @@ export class AccountManager {
   _selectNext(exclude = null, model = null, advisorModel = null) {
     const best = this._pickBestAvailable(exclude, model, advisorModel);
     if (best) {
-      const switched = best.index !== this.currentIndex;
+      const previous = this._previousCursor(model);
+      const switched = previous != null && previous !== best.index;
       this.currentIndex = best.index;
       // If we switched to an account whose weekly quota is still unknown, flag
       // it so we re-evaluate once that quota is learned (see updateQuota).
@@ -1188,8 +1303,14 @@ export class AccountManager {
     // overage included"). On current subscription plans this is the Fable weekly
     // limit (it correlates with the usage endpoint's Fable-scoped weekly bucket).
     // Utilization here is already a 0-1 fraction (can exceed 1 when in overage).
+    // These headers ride on Fable responses only, so stamp when the reading was
+    // taken: that timestamp is what lets a spent reading be revalidated instead
+    // of sealing the account out of the family forever (see _clearExpiredQuotas).
     const u7dOi = parseFloat(headers['anthropic-ratelimit-unified-7d_oi-utilization']);
-    if (!isNaN(u7dOi)) account.quota.unified7dFable = u7dOi;
+    if (!isNaN(u7dOi)) {
+      account.quota.unified7dFable = u7dOi;
+      account.quota.unified7dFableSeenAt = Date.now();
+    }
     const r7dOi = headers['anthropic-ratelimit-unified-7d_oi-reset'];
     if (r7dOi) account.quota.unified7dFableReset = parseInt(r7dOi, 10) * 1000;
 
@@ -1204,6 +1325,25 @@ export class AccountManager {
     const uStatus = headers['anthropic-ratelimit-unified-status'];
     if (uStatus) account.quota.unifiedStatus = uStatus;
 
+    // OpenAI/Codex windows (`x-codex-*`, forwarded by a translating sidecar for
+    // a ChatGPT-subscription account). Codex reports two windows, `primary` and
+    // `secondary`, whose meaning comes from the declared length rather than the
+    // position: a ChatGPT Pro plan reports its weekly limit as the primary one
+    // and meters no secondary window at all. So each window is filed by length,
+    // which lands it in the same 5h/weekly slots the rest of the code reads —
+    // display, projection and switch-threshold logic apply unchanged. A window
+    // with no length is a bucket the plan does not have, not one at 0% used.
+    // used-percent is 0-100 (not the 0-1 fraction Anthropic reports).
+    for (const window of ['primary', 'secondary']) {
+      const used = parseFloat(headers[`x-codex-${window}-used-percent`]);
+      const minutes = parseInt(headers[`x-codex-${window}-window-minutes`], 10);
+      if (isNaN(used) || !(minutes > 0)) continue;
+      const reset = parseResetAt(headers[`x-codex-${window}-reset-at`]);
+      const weekly = minutes > CODEX_WEEKLY_MIN_MINUTES;
+      account.quota[weekly ? 'unified7d' : 'unified5h'] = used / 100;
+      if (reset != null) account.quota[weekly ? 'unified7dReset' : 'unified5hReset'] = reset;
+    }
+
     // Standard rate limits (API key accounts)
     const tokensLimit = parseInt(headers['anthropic-ratelimit-tokens-limit'], 10);
     const tokensRemaining = parseInt(headers['anthropic-ratelimit-tokens-remaining'], 10);
@@ -1258,6 +1398,10 @@ export class AccountManager {
     if (!disabled && account.status === 'error') {
       account.status = 'active';
       account.rateLimitedUntil = null;
+      // Operator escape hatch: re-enabling is an explicit "try this again", so
+      // drop the dead-token guard too — otherwise the account would come back
+      // active but never attempt a refresh (see ensureTokenFresh).
+      account._deadRefreshToken = null;
       console.log(`[TeamClaude] Account "${account.name}" re-enabled — clearing error state`);
     }
   }
@@ -1280,12 +1424,23 @@ export class AccountManager {
       if (usage.sevenDay.utilization != null) q.unified7d = usage.sevenDay.utilization;
       if (usage.sevenDay.resetAt != null) q.unified7dReset = usage.sevenDay.resetAt;
     }
+    // The family buckets carry a "last confirmed" stamp (see _clearExpiredQuotas).
+    // A probe is upstream evidence just like a response header, so it refreshes
+    // the stamp — this is the one path that can correct a spent family reading
+    // without spending quota, which is why enabling the probe sidesteps the
+    // staleness problem entirely.
     if (usage.sevenDaySonnet) {
-      if (usage.sevenDaySonnet.utilization != null) q.unified7dSonnet = usage.sevenDaySonnet.utilization;
+      if (usage.sevenDaySonnet.utilization != null) {
+        q.unified7dSonnet = usage.sevenDaySonnet.utilization;
+        q.unified7dSonnetSeenAt = Date.now();
+      }
       if (usage.sevenDaySonnet.resetAt != null) q.unified7dSonnetReset = usage.sevenDaySonnet.resetAt;
     }
     if (usage.sevenDayFable) {
-      if (usage.sevenDayFable.utilization != null) q.unified7dFable = usage.sevenDayFable.utilization;
+      if (usage.sevenDayFable.utilization != null) {
+        q.unified7dFable = usage.sevenDayFable.utilization;
+        q.unified7dFableSeenAt = Date.now();
+      }
       if (usage.sevenDayFable.resetAt != null) q.unified7dFableReset = usage.sevenDayFable.resetAt;
     }
 
@@ -1337,6 +1492,31 @@ export class AccountManager {
     const account = this.accounts[accountIndex];
     if (!account || account.type !== 'oauth' || !account.refreshToken) return;
 
+    // Dead-token guard: a refresh token upstream already rejected (invalid_grant)
+    // will be rejected every time, so retrying it only floods the OAuth endpoint
+    // — observed live: 287 identical invalid_grant calls after two accounts' tokens
+    // were invalidated (a `/login` elsewhere rotates the token and kills the copy
+    // teamclaude holds). Paths that bypass availability checks keep calling this
+    // (the quota prober refreshes every OAuth account regardless of status, and a
+    // pinned request reaches here without _isAvailable), so marking the account
+    // 'error' alone does not stop the retries. Keyed on the token VALUE, not the
+    // status: the moment a DIFFERENT refresh token arrives (re-login, config
+    // reload, updateAccountTokens) the guard lifts on its own.
+    //
+    // While it holds, the account must also READ as needing a re-login. A
+    // re-import can hand updateAccountTokens a new access token alongside the
+    // same dead refresh token; that path resets status to 'active', so without
+    // this the access token's 401 would force a refresh that silently does
+    // nothing here and the retry would relay the 401 to the client instead of
+    // rotating to another account.
+    if (account._deadRefreshToken && account._deadRefreshToken === account.refreshToken) {
+      if (account.status !== 'error') {
+        account.status = 'error';
+        console.error(`[TeamClaude] Account "${account.name}" still holds a rejected refresh token — run: teamclaude login`);
+      }
+      return;
+    }
+
     if (!force && !isTokenExpiringSoon(account.expiresAt)) return;
 
     // A forced refresh answers a 401, but 401s arrive in bursts: every request
@@ -1365,6 +1545,7 @@ export class AccountManager {
         account.refreshToken = newTokens.refreshToken;
         account.expiresAt = newTokens.expiresAt;
         account._lastRefreshAt = Date.now();
+        account._deadRefreshToken = null; // this token works; clear any stale guard
         console.log(`[TeamClaude] Token refreshed for account "${account.name}"`);
         this._onTokenRefresh?.(accountIndex, newTokens);
       } catch (err) {
@@ -1378,6 +1559,10 @@ export class AccountManager {
         const isAuthRejection = err.status === 400 || err.status === 401 || err.status === 403;
         if (isAuthRejection) {
           account.status = 'error';
+          // Remember WHICH token was rejected so we stop re-sending it (see the
+          // dead-token guard above). A transient failure deliberately does not
+          // arm this — that token may still be good.
+          account._deadRefreshToken = account.refreshToken;
           console.error(`[TeamClaude] Account "${account.name}" needs re-login (refresh token rejected) — run: teamclaude login`);
         }
       } finally {
@@ -1441,6 +1626,12 @@ export class AccountManager {
       if (idx === index) this.routePins.delete(name);
       else if (idx > index) this.routePins.set(name, idx - 1);
     }
+    // Same for the selection cursors: a cursor on the removed account is dropped
+    // so the route re-picks, and one above it follows the shift.
+    for (const [name, idx] of [...this.routeCursors.entries()]) {
+      if (idx === index) this.routeCursors.delete(name);
+      else if (idx > index) this.routeCursors.set(name, idx - 1);
+    }
   }
 
   /**

package/src/claude-env.js

@@ -30,7 +30,66 @@ export function encodePinComponent(s) {
 // `/tc-acct/` prefix. TC_ACCT itself is then unset, so the pin does not leak
 // into claude or anything it spawns — same reasoning as `run` deleting it from
 // the child environment.
-export function buildClaudeEnvLines({ port, useMitm = true, caPath = null, holdSeconds = 0, account = null, proxyApiKey = '' }) {
+// `config.customModels` → the `--settings` JSON that puts each model in the
+// /model picker under its REAL id ({model, label?, description?} rows; typed
+// `/model <id>` also accepts picker rows). contextTokens is ours, not Claude
+// Code's — it feeds CLAUDE_CODE_MAX_CONTEXT_TOKENS below. Null when empty so
+// callers can skip the flag entirely.
+export function buildCustomModelSettings(customModels) {
+  if (!customModels?.length) return null;
+  const options = customModels.map(({ model, label, description }) => ({
+    model,
+    ...(label ? { label } : {}),
+    ...(description ? { description } : {}),
+  }));
+  return JSON.stringify({ modelPicker: { options } });
+}
+
+// `config.customModels` → the `--agents` JSON that makes each model
+// dispatchable as a subagent. The Agent tool's per-invocation `model`
+// parameter is an alias enum (sonnet|opus|haiku|fable) and rejects custom ids;
+// an agent DEFINITION's `model:` field accepts any id, so each custom model
+// gets a general-purpose agent named after it ("dispatch a gpt-5.6-terra
+// subagent" then works out of the box). Null when empty.
+export function buildCustomModelAgents(customModels) {
+  if (!customModels?.length) return null;
+  const agents = {};
+  for (const { model, label } of customModels) {
+    agents[model] = {
+      description: `General-purpose subagent running on ${label || model} (via TeamClaude). `
+        + `Use when asked to run a task on ${model}.`,
+      prompt: `You are a general-purpose subagent running on the ${model} model. `
+        + 'Complete the task you are given and report the results concisely.',
+      model,
+    };
+  }
+  return JSON.stringify(agents);
+}
+
+// The env-only registration for launchers we can't pass flags to (`teamclaude
+// env`). ANTHROPIC_CUSTOM_MODEL_OPTION registers ONE model (env can't express a
+// list — the picker rows need `--settings`, i.e. `teamclaude run`), so the
+// first entry is the one that gets a picker row and typed-/model acceptance.
+// CLAUDE_CODE_MAX_CONTEXT_TOKENS is global for all unknown model ids: use the
+// largest declared window so no custom model is compacted early; deliberately
+// NOT modelOverrides, which would pin the window to the mapped Claude model's.
+export function buildCustomModelVars(customModels) {
+  if (!customModels?.length) return {};
+  const vars = { ANTHROPIC_CUSTOM_MODEL_OPTION: customModels[0].model };
+  if (customModels[0].label) vars.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME = customModels[0].label;
+  if (customModels[0].description) vars.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION = customModels[0].description;
+  const windows = customModels.map(m => m.contextTokens).filter(n => Number.isFinite(n));
+  if (windows.length) vars.CLAUDE_CODE_MAX_CONTEXT_TOKENS = String(Math.max(...windows));
+  return vars;
+}
+
+// Single-quote a value for an unquoted-context shell `export` line (labels and
+// descriptions contain spaces). POSIX: close, escaped quote, reopen.
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+export function buildClaudeEnvLines({ port, useMitm = true, caPath = null, holdSeconds = 0, account = null, proxyApiKey = '', customModels = null }) {
   const lines = [];
   const pin = (account || '').trim();
 
@@ -61,5 +120,10 @@ export function buildClaudeEnvLines({ port, useMitm = true, caPath = null, holdS
   const holdMs = (holdSeconds || 0) * 1000;
   if (holdMs > 0) lines.push(`export API_TIMEOUT_MS=${holdMs + 60_000}`);
 
+  // Custom (third-party) model registration — see buildCustomModelVars.
+  for (const [key, value] of Object.entries(buildCustomModelVars(customModels))) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
+
   return lines;
 }

package/src/config.js

@@ -59,7 +59,7 @@ export function createDefaultConfig() {
     holdSeconds: 0,
     distributeSessions: false,
     projection: { enabled: true, windowMinutes: 90, wasteFloor: 0.1 },
-    sessionTitles: { enabled: true, width: 18 },
+    sessionTitles: { enabled: false, width: 18 },
     eventLogging: 'hide',
     blockedModels: [],
     accounts: [],

package/src/identity.js

@@ -94,3 +94,27 @@ export function matchAccounts(accounts, query, orgFilter) {
   }
   return matches;
 }
+
+/**
+ * Automatic naming is safe only when the profile identifies the account.
+ * An explicit name is the caller's opt-in to importing without detection.
+ */
+export function canUpsertOAuthAccount(profile, userNamed) {
+  return Boolean(
+    userNamed
+    || (profile && !profile.error && (profile.accountUuid || profile.email))
+  );
+}
+
+/**
+ * Copy only known profile identity fields. Omitting unavailable fields keeps a
+ * named re-import from erasing identity already stored on the account.
+ */
+export function oauthIdentityFields(profile) {
+  if (!profile || profile.error) return {};
+  return Object.fromEntries(
+    ['accountUuid', 'orgUuid', 'orgName']
+      .filter(key => profile[key])
+      .map(key => [key, profile[key]])
+  );
+}