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

package/README.md

@@ -1,6 +1,6 @@
 # TeamClaude
 
-> **Fork notice (rikbrown).** This fork adds one feature and two reload fixes on top of
+> **Fork notice (rikbrown).** This fork adds three features and two reload fixes on top of
 > [KarpelesLab/teamclaude](https://github.com/KarpelesLab/teamclaude):
 >
 > - **[Soonest-weekly rotation](docs/routing.md#soonest-weekly-rotation)** (`soonestWeekly`, opt-in): rank
@@ -8,6 +8,13 @@
 >   current account when another resets more than `poolHours` sooner, and balance `distributeSessions` within
 >   that pool instead of across all accounts. Spends the quota closest to refreshing first, so a window no
 >   longer rolls over with quota unspent.
+> - **[Burn-rate projection](docs/quota.md#burn-rate-projection)** (`projection`, on by default): sample each
+>   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):
+>   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.
 >
@@ -18,11 +25,14 @@
 > npm install -g @rikcodes/teamclaude
 > ```
 >
+> Already have upstream installed globally? Run `npm uninstall -g @karpeleslab/teamclaude` first —
+> both packages provide the `teamclaude` command.
+>
 > Branch: `rik/soonest-weekly-pool`. Everything else matches upstream.
 
-[![CI](https://github.com/KarpelesLab/teamclaude/actions/workflows/ci.yml/badge.svg)](https://github.com/KarpelesLab/teamclaude/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@karpeleslab/teamclaude.svg)](https://www.npmjs.com/package/@karpeleslab/teamclaude)
-[![node](https://img.shields.io/node/v/@karpeleslab/teamclaude.svg)](https://nodejs.org)
+[![CI](https://github.com/rikbrown/teamclaude/actions/workflows/ci.yml/badge.svg?branch=rik/soonest-weekly-pool)](https://github.com/rikbrown/teamclaude/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@rikcodes/teamclaude.svg)](https://www.npmjs.com/package/@rikcodes/teamclaude)
+[![node](https://img.shields.io/node/v/@rikcodes/teamclaude.svg)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Multi-account Claude proxy with automatic quota-based rotation for [Claude Code](https://claude.ai/claude-code).
@@ -48,6 +58,8 @@ Already logged into Claude Code? `teamclaude import` takes its credentials inste
 ## What it does
 
 - Rotates to the next account when the 5h session or 7d weekly bucket reaches the threshold (98% by default), preferring the account whose weekly quota resets soonest.
+- Optionally spends the account whose weekly window resets soonest **first**, preempting the current account when another resets more than `poolHours` sooner, so a window stops rolling over with quota unspent (`soonestWeekly`, this fork).
+- Projects each quota window's burn rate against its reset, so a row says `Ses TTL 38m · Wk 22% unspent` instead of leaving you to read it off a bar (`projection`, this fork).
 - Tracks the per-model weekly cap separately, so an account out of Fable quota is skipped for Fable requests and still serves Opus and Sonnet.
 - Tells a spent quota bucket apart from a per-minute rate limit and only rotates on the first one. Rotating on a rate limit would just move the burst to the next account and drop the warm cache, so it paces the same account instead.
 - Paces requests onto a freshly switched account, so a herd of agents failing over at the same instant doesn't throttle it and cascade down the fleet.
@@ -99,23 +111,33 @@ Step-by-step lifecycle: [docs/routing.md](docs/routing.md#request-lifecycle).
 | [Proxy modes](docs/proxy-modes.md) | MITM forward proxy, sx.org residential egress |
 | [Compliance](docs/compliance.md) | Terms of service notes |
 
+## Releasing this fork
+
+Versions are `<upstream base>-rik.<n>`, e.g. `1.1.13-rik.1`. The self-updater orders that tail, so every publish reaches existing installs within a day.
+
+1. Rebase onto the upstream release you want as the base, if any.
+2. Bump `version` in `package.json` and commit.
+3. Push to `rik/soonest-weekly-pool` — the Publish workflow runs the tests, publishes to npm, and cuts a GitHub release.
+
+The workflow authenticates with npm Trusted Publishing (OIDC), which needs a one-time setup on npmjs.com: `@rikcodes/teamclaude` → Settings → Trusted Publisher → GitHub Actions, owner `rikbrown`, repo `teamclaude`, workflow `publish.yml`. Until that exists, publish by hand:
+
+```bash
+pnpm publish --publish-branch rik/soonest-weekly-pool --tag latest --otp=<code>
+```
+
+A prerelease version always needs an explicit `--tag`, and `latest` is the tag the self-updater reads.
+
 ## Security
 
-The only canonical sources for TeamClaude are this repository (https://github.com/KarpelesLab/teamclaude) and the [`@karpeleslab/teamclaude`](https://www.npmjs.com/package/@karpeleslab/teamclaude) npm package. TeamClaude is **never** distributed as a downloadable binary archive, so be wary of soft-forks that bundle a `.zip` and tell you to extract and run it. See [SECURITY.md](SECURITY.md) for details and how to report issues.
+This repository is a personal fork and is **not** the canonical project. Upstream's canonical sources are unchanged: the [KarpelesLab repository](https://github.com/KarpelesLab/teamclaude) and the [`@karpeleslab/teamclaude`](https://www.npmjs.com/package/@karpeleslab/teamclaude) npm package.
 
-## Compliance
+This fork is distributed as this repository and the [`@rikcodes/teamclaude`](https://www.npmjs.com/package/@rikcodes/teamclaude) npm package, published by `rikbrown`. The separate package name means it can never be installed over the canonical one.
 
-TeamClaude is a local proxy holding your own credentials and driving your own Claude Code CLI. How that lines up with Anthropic's terms, including the multi-subscription question people ask most, is written up in [docs/compliance.md](docs/compliance.md). Not legal advice.
+Neither is **ever** distributed as a downloadable binary archive, so be wary of any copy that bundles a `.zip` and tells you to extract and run it. See [SECURITY.md](SECURITY.md) for details and how to report issues.
 
-## Star history
+## Compliance
 
-<a href="https://www.star-history.com/?repos=KarpelesLab%2Fteamclaude&type=date&legend=top-left">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=KarpelesLab/teamclaude&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=KarpelesLab/teamclaude&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=KarpelesLab/teamclaude&type=date&legend=top-left" />
- </picture>
-</a>
+TeamClaude is a local proxy holding your own credentials and driving your own Claude Code CLI. How that lines up with Anthropic's terms, including the multi-subscription question people ask most, is written up in [docs/compliance.md](docs/compliance.md). Not legal advice.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.13-rik.1",
+  "version": "1.1.13-rik.2",
   "description": "Multi-account Claude proxy with automatic quota-based rotation",
   "type": "module",
   "main": "src/index.js",
@@ -10,6 +10,11 @@
   "files": [
     "src/"
   ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test --test-timeout=120000",
+    "lint": "eslint ."
+  },
   "keywords": [
     "claude",
     "anthropic",
@@ -34,10 +39,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "test": "node --test --test-timeout=120000",
-    "lint": "eslint ."
   }
-}
+}

package/src/account-manager.js

@@ -2,6 +2,7 @@ import { refreshAccessToken, isTokenExpiringSoon, isTokenExpired } from './oauth
 import { sameIdentity } from './identity.js';
 import { weeklyBucketForModel, modelGlobMatches } from './model.js';
 import { SessionTracker } from './session-tracker.js';
+import { QuotaProjection, PROJECTED_BUCKETS } from './quota-projection.js';
 
 // Re-exported for callers that import these model helpers from here.
 export { isFableModel, parseRequestModel, parseAdvisorModel } from './model.js';
@@ -108,7 +109,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, sessionTracker } = {}) {
+  constructor(accounts, switchThreshold = 0.98, { refreshFn = refreshAccessToken, throttleProbeFloorMs, 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
@@ -131,6 +132,7 @@ export class AccountManager {
     this.switchThreshold = switchThreshold;
     this.setRoutes(routes);
     this.setSoonestWeekly(soonestWeekly);
+    this.setProjection(projection);
     // Storm control: when rotation switches to a fresh account, a burst of
     // in-flight requests (e.g. dozens of agents failing over together) would all
     // hit it at once and instantly throttle it — cascading down the fleet
@@ -693,6 +695,47 @@ export class AccountManager {
     };
   }
 
+  /**
+   * Burn-rate projection settings, applied live on config reload. Enabled by
+   * default: the projection is a readout and no selection code consults it, so
+   * turning it on cannot change which account serves a request.
+   */
+  setProjection(cfg) {
+    const c = cfg || {};
+    this.projection = new QuotaProjection({
+      enabled: c.enabled !== false,
+      windowMinutes: c.windowMinutes,
+      wasteFloor: c.wasteFloor ?? 0.1,
+    });
+  }
+
+  /** Sample every reported bucket. Both quota write paths call this: response
+   *  headers (updateQuota) and the usage probe (applyUsageData). */
+  _recordQuotaSamples(account, now = Date.now()) {
+    const q = account.quota;
+    for (const bucket of PROJECTED_BUCKETS) {
+      if (q[bucket] !== undefined) this.projection.record(account.index, bucket, q[bucket], now);
+    }
+  }
+
+  /** Every bucket's projection for one account, keyed by bucket name. Buckets
+   *  without a usable rate are absent rather than null. */
+  projectionsFor(accountIndex, now = Date.now()) {
+    const account = this.accounts[accountIndex];
+    if (!account) return {};
+    const q = account.quota;
+    const out = {};
+    for (const bucket of PROJECTED_BUCKETS) {
+      const projected = this.projection.project(accountIndex, bucket, {
+        utilization: q[bucket],
+        resetAt: q[`${bucket}Reset`],
+        now,
+      });
+      if (projected) out[bucket] = projected;
+    }
+    return out;
+  }
+
   /**
    * Normalize and store the configurable routing table. A route pins a set of
    * model globs to an exclusive set of accounts (and may override the governing
@@ -1177,6 +1220,8 @@ export class AccountManager {
     if (tokensReset) account.quota.resetsAt = tokensReset;
     else if (requestsReset) account.quota.resetsAt = requestsReset;
 
+    this._recordQuotaSamples(account);
+
     account.usage.totalRequests++;
     account.usage.lastUsed = new Date().toISOString();
 
@@ -1244,6 +1289,8 @@ export class AccountManager {
       if (usage.sevenDayFable.resetAt != null) q.unified7dFableReset = usage.sevenDayFable.resetAt;
     }
 
+    this._recordQuotaSamples(account);
+
     // If we just learned this account's weekly window while probing, re-evaluate
     // selection (same path as learning it from a live response).
     if (account.probing && q.unified7dReset != null) {
@@ -1437,6 +1484,7 @@ export class AccountManager {
       routes: this.getRoutes(),
       sessions: { ...sessions, distribute: this.distributeSessions },
       soonestWeekly: { ...this.soonestWeekly },
+      projection: this.projection.settings(),
       accounts: this.accounts.map(a => ({
         name: a.name,
         type: a.type,
@@ -1447,6 +1495,10 @@ export class AccountManager {
         sessions: sessions.perAccount[a.index] || 0,
         quota: { ...a.quota },
         usage: { ...a.usage },
+        projection: (() => {
+          const buckets = this.projectionsFor(a.index);
+          return { headline: this.projection.headline(Object.values(buckets)), buckets };
+        })(),
         rateLimitedUntil: a.rateLimitedUntil
           ? new Date(a.rateLimitedUntil).toISOString()
           : null,

package/src/config.js

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

package/src/index.js

@@ -16,6 +16,7 @@ import { ensureCerts } from './mitm.js';
 import { Prober } from './prober.js';
 import { Warmer } from './warmer.js';
 import { TUI } from './tui.js';
+import { SessionTitles } from './session-titles.js';
 import { RemoteControl, createAttachSession } from './tui-remote.js';
 import { SxManager } from './sx.js';
 import { autoUpdate, checkForUpdate, currentVersion, runUpdate, installKind, PKG_NAME } from './updater.js';
@@ -178,7 +179,12 @@ async function serverCommand() {
   }
 
   const threshold = config.switchThreshold || 0.98;
-  const accountManager = new AccountManager(accounts, threshold, { routes: config.routes, ramp: config.stormRamp, distributeSessions: config.distributeSessions, soonestWeekly: config.soonestWeekly });
+  const accountManager = new AccountManager(accounts, threshold, { routes: config.routes, ramp: config.stormRamp, distributeSessions: config.distributeSessions, soonestWeekly: config.soonestWeekly, projection: config.projection });
+  // Names the activity log's session column from Claude Code's own on-disk
+  // session titles. Built whether or not the TUI runs, so a reload has one
+  // object to reconfigure.
+  const sessionTitles = new SessionTitles(config.sessionTitles);
+
 
   // Restore quota observed in a previous run so a restart doesn't lose rotation
   // state (passive — we never call the API to re-learn it). Stale windows are
@@ -269,6 +275,10 @@ async function serverCommand() {
     accountManager.setDistributeSessions(config.distributeSessions);
     config.soonestWeekly = diskConfig.soonestWeekly;
     accountManager.setSoonestWeekly(config.soonestWeekly);
+    config.projection = diskConfig.projection;
+    accountManager.setProjection(config.projection);
+    config.sessionTitles = diskConfig.sessionTitles;
+    sessionTitles.configure(config.sessionTitles);
     // Apply an sx.org key/mode change made on disk (e.g. via POST /teamclaude/reload).
     const diskSxKey = diskConfig.sx?.apiKey || null;
     const diskSxMode = diskConfig.sx?.mode || 'always';
@@ -299,7 +309,7 @@ async function serverCommand() {
 
   if (useTUI) {
     tui = new TUI({
-      accountManager, config, sx, activityLogPath,
+      accountManager, config, sx, activityLogPath, sessionTitles,
       saveConfig: () => atomicConfigUpdate(async diskConfig => {
         // Write in-memory accounts as the authoritative state, preserving
         // extra disk-only fields (e.g. importFrom) where the account still exists.

package/src/quota-projection.js

@@ -0,0 +1,166 @@
+/**
+ * Burn-rate projection for quota buckets.
+ *
+ * Each bucket reports utilization as a 0-1 fraction. Sampling that over a
+ * rolling window gives a consumption rate, and the rate against the bucket's
+ * known reset answers the question the bars cannot: will this window stop you
+ * before it resets, or expire with quota unspent?
+ *
+ * The rate is a least-squares slope rather than a first-to-last delta, so one
+ * large response does not swing the figure. The window is a trade: consumption
+ * is bursty and a recent-rate estimate is meant to track it, but utilization
+ * arrives quantised to whole percent, so too narrow a window contains no step
+ * to measure. Nothing is reported rather than a fabricated rate when the
+ * samples cannot support one.
+ */
+
+/** Every bucket that reports utilization, in the order the TUI shows them. */
+export const PROJECTED_BUCKETS = ['unified5h', 'unified7d', 'unified7dSonnet', 'unified7dFable'];
+
+/** Buckets whose leftovers are worth reporting. A 5h window refills the same
+ *  day, so its unspent tail costs nothing and is never reported as a surplus. */
+const WEEKLY_BUCKETS = new Set(['unified7d', 'unified7dSonnet', 'unified7dFable']);
+
+/** Row labels, matching the TUI's bar labels so one tag reads against them. */
+const BUCKET_LABELS = {
+  unified5h: 'Ses',
+  unified7d: 'Wk',
+  unified7dSonnet: 'S7',
+  unified7dFable: 'F7',
+};
+
+/** Two samples one second apart would extrapolate a burst across a whole week.
+ *  Below this span the samples are kept but no rate is reported. */
+const MIN_SPAN_MS = 5 * 60_000;
+
+/** Utilization is reported as whole percent, so the signal is a staircase with
+ *  1% steps. A window narrower than this can contain no step at all: measured
+ *  against a 1%/h burn, a 30-minute window reports nothing half the time and
+ *  ranges 0.4-2.9%/h when it does speak, while 90 minutes holds 0.9-1.1%/h. */
+const DEFAULT_WINDOW_MINUTES = 90;
+
+export class QuotaProjection {
+  constructor({ enabled = true, windowMinutes = DEFAULT_WINDOW_MINUTES, wasteFloor = 0.1 } = {}) {
+    this.enabled = enabled !== false;
+    this.windowMs = Math.max(1, windowMinutes) * 60_000;
+    this.wasteFloor = Math.max(0, Math.min(1, wasteFloor));
+    /** @type {Map<string, Array<{t: number, u: number}>>} */
+    this.samples = new Map();
+  }
+
+  /** The settings in force, for the status readout. */
+  settings() {
+    return {
+      enabled: this.enabled,
+      windowMinutes: this.windowMs / 60_000,
+      wasteFloor: this.wasteFloor,
+    };
+  }
+
+  /** Record one utilization reading. A null reading means the window rolled
+   *  (_clearExpiredQuotas nulls the bucket at its reset), so the history is
+   *  dropped: without this the roll reads as a large negative burn. */
+  record(accountIndex, bucket, utilization, at = Date.now()) {
+    if (!this.enabled) return;
+    const key = `${accountIndex}:${bucket}`;
+    if (utilization == null || isNaN(utilization)) {
+      this.samples.delete(key);
+      return;
+    }
+    let list = this.samples.get(key);
+    if (!list) {
+      list = [];
+      this.samples.set(key, list);
+    }
+    // A window can also roll as a decrease: a probe reports the fresh window
+    // before _clearExpiredQuotas nulls the bucket. Utilization never falls
+    // within a window, so a drop means the same restart a null does.
+    if (list.length && utilization < list[list.length - 1].u) list.length = 0;
+    list.push({ t: at, u: utilization });
+    const cutoff = at - this.windowMs;
+    while (list.length && list[0].t < cutoff) list.shift();
+  }
+
+  /** Consumption in utilization per millisecond, or null when the samples in
+   *  the window cannot support an estimate (too few, too short a span, or no
+   *  measurable consumption). */
+  rate(accountIndex, bucket) {
+    if (!this.enabled) return null;
+    const list = this.samples.get(`${accountIndex}:${bucket}`);
+    if (!list || list.length < 2) return null;
+    const span = list[list.length - 1].t - list[0].t;
+    if (span < MIN_SPAN_MS) return null;
+
+    // Times are relative to the first sample: epoch milliseconds squared loses
+    // precision in the sums below.
+    const t0 = list[0].t;
+    let sumT = 0, sumU = 0, sumTT = 0, sumTU = 0;
+    for (const { t, u } of list) {
+      const x = t - t0;
+      sumT += x;
+      sumU += u;
+      sumTT += x * x;
+      sumTU += x * u;
+    }
+    const n = list.length;
+    const denom = n * sumTT - sumT * sumT;
+    if (denom === 0) return null;
+    const slope = (n * sumTU - sumT * sumU) / denom;
+    return slope > 0 ? slope : null;
+  }
+
+  /**
+   * Project one bucket against its reset.
+   * @returns {{bucket: string, kind: 'deficit'|'surplus', exhaustsInMs?: number,
+   *   unspent?: number, resetInMs: number} | null}
+   */
+  project(accountIndex, bucket, { utilization, resetAt, now = Date.now() } = {}) {
+    if (!this.enabled) return null;
+    if (utilization == null || resetAt == null) return null;
+    const rate = this.rate(accountIndex, bucket);
+    if (rate == null) return null;
+
+    const resetInMs = resetAt - now;
+    const remaining = 1 - utilization;
+    if (remaining <= 0) return { bucket, kind: 'deficit', exhaustsInMs: 0, resetInMs };
+
+    const exhaustsInMs = remaining / rate;
+    if (exhaustsInMs <= resetInMs) return { bucket, kind: 'deficit', exhaustsInMs, resetInMs };
+
+    if (!WEEKLY_BUCKETS.has(bucket)) return null;
+    const unspent = remaining - rate * resetInMs;
+    if (unspent < this.wasteFloor) return null;
+    return { bucket, kind: 'surplus', unspent, resetInMs };
+  }
+
+  /** Projections in display order: anything that will stop you comes before
+   *  anything that will merely expire, soonest and largest first. */
+  rank(projections) {
+    const rank = p => (p.kind === 'deficit' ? 0 : 1);
+    return (projections || []).filter(Boolean).sort((a, b) => {
+      if (rank(a) !== rank(b)) return rank(a) - rank(b);
+      return a.kind === 'deficit' ? a.exhaustsInMs - b.exhaustsInMs : b.unspent - a.unspent;
+    });
+  }
+
+  /** The most urgent projection, or null when there is nothing to report. */
+  headline(projections) {
+    return this.rank(projections)[0] || null;
+  }
+}
+
+/** Render a projection as a row tag, e.g. "Ses TTL 38m" or "Wk 22% unspent". */
+export function formatProjection(projection) {
+  if (!projection) return null;
+  const label = BUCKET_LABELS[projection.bucket] || projection.bucket;
+  if (projection.kind === 'deficit') return `${label} TTL ${formatDuration(projection.exhaustsInMs)}`;
+  return `${label} ${Math.round(projection.unspent * 100)}% unspent`;
+}
+
+function formatDuration(ms) {
+  const minutes = Math.max(0, Math.round(ms / 60_000));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h${minutes % 60}m`;
+  return `${Math.floor(hours / 24)}d${hours % 24}h`;
+}

package/src/session-titles.js

@@ -0,0 +1,184 @@
+/**
+ * Session titles for the activity log.
+ *
+ * The proxy already knows which Claude Code session a request belongs to: the
+ * client sends `x-claude-code-session-id`, and the TUI prints its first six hex
+ * characters. That distinguishes concurrent sessions but does not name them.
+ *
+ * Claude Code stores the name on disk under `~/.claude/projects/<slug>/`. A
+ * `/rename` writes `<session-id>/custom-title.json`; it also appends a
+ * `custom-title` record to the transcript, which is the only copy for a session
+ * renamed before the sidecar existed. Claude Code generates its own title as
+ * well and appends it as an `ai-title` record, so most sessions have a usable
+ * name without a rename.
+ *
+ * Lookups are cached and run off the render path: `get` returns what is cached
+ * and schedules the read, so a frame never waits on the disk.
+ */
+
+import { readdir, readFile, open } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DEFAULT_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+/** A rename must reach the TUI without a restart, and a re-read costs one
+ *  directory scan and one 64 KB read. */
+const DEFAULT_TTL_MS = 30_000;
+
+/** Measured across 218 transcripts: the last title record sits within 32.7 KB
+ *  of EOF at p99 and 46.3 KB at the maximum. Reading more would only reach
+ *  sessions that have written megabytes since their last title. */
+const DEFAULT_TAIL_BYTES = 64 * 1024;
+
+/** Columns the activity log gives the session label. Every row pays this width,
+ *  named or not, so the columns after it stay aligned. A typed name fits: the
+ *  longest in use is "adv-review-rewrite" at 18. A generated title is a sentence
+ *  and is cut. */
+const DEFAULT_WIDTH = 18;
+
+/** The activity log falls back to this many hex characters of the session id,
+ *  so a label can never be narrower. */
+const SHORT_ID_LEN = 6;
+
+export class SessionTitles {
+  constructor({ projectsDir = DEFAULT_PROJECTS_DIR, ttlMs = DEFAULT_TTL_MS, tailBytes = DEFAULT_TAIL_BYTES, ...cfg } = {}) {
+    this.projectsDir = projectsDir;
+    this.ttlMs = ttlMs;
+    this.tailBytes = tailBytes;
+    /** @type {Map<string, {title: string|null, at: number}>} */
+    this.cache = new Map();
+    /** @type {Map<string, Promise<string|null>>} */
+    this.inflight = new Map();
+    this.configure(cfg);
+  }
+
+  /** Apply a config change in place, so a reload takes effect without a
+   *  restart. An absent key returns to its default. */
+  configure(cfg) {
+    const { enabled = true, width = DEFAULT_WIDTH } = cfg || {};
+    this.enabled = enabled !== false;
+    // A label narrower than the short id it falls back to would cut the id.
+    this.width = Math.max(SHORT_ID_LEN, Math.trunc(width) || DEFAULT_WIDTH);
+  }
+
+  /** The settings in force, for the status readout. */
+  settings() {
+    return { enabled: this.enabled, width: this.width };
+  }
+
+  /** The cached title, or null. Never touches the disk: a miss or a stale entry
+   *  schedules the read and the caller gets the previous answer until it lands. */
+  get(sessionId, now = Date.now()) {
+    if (!this.enabled || !sessionId) return null;
+    const hit = this.cache.get(sessionId);
+    if (!hit || now - hit.at >= this.ttlMs) this._schedule(sessionId, now);
+    return hit ? hit.title : null;
+  }
+
+  /** Read the title now. Resolves to null when the session has none. */
+  async resolve(sessionId, now = Date.now()) {
+    if (!this.enabled || !sessionId) return null;
+    return this._schedule(sessionId, now);
+  }
+
+  /** Number of reads in flight. */
+  pending() {
+    return this.inflight.size;
+  }
+
+  /** Settle every scheduled read. A resolve can schedule another, so this loops. */
+  async idle() {
+    while (this.inflight.size) await Promise.all([...this.inflight.values()]);
+  }
+
+  _schedule(sessionId, now) {
+    const existing = this.inflight.get(sessionId);
+    if (existing) return existing;
+    // A missing title is cached like a found one: without that, every frame
+    // would rescan the projects directory for a session that has no name.
+    const read = this._read(sessionId)
+      .catch(() => null)
+      .then((title) => {
+        this.cache.set(sessionId, { title, at: now });
+        return title;
+      })
+      .finally(() => this.inflight.delete(sessionId));
+    this.inflight.set(sessionId, read);
+    return read;
+  }
+
+  /** The project directory is keyed by the session's cwd, which the proxy does
+   *  not know, so each directory is tried until one holds the session. */
+  async _read(sessionId) {
+    const entries = await readdir(this.projectsDir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const project = join(this.projectsDir, entry.name);
+      const renamed = await this._fromSidecar(join(project, sessionId, 'custom-title.json'));
+      if (renamed) return renamed;
+      const recorded = await this._fromTranscript(join(project, `${sessionId}.jsonl`));
+      if (recorded) return recorded;
+    }
+    return null;
+  }
+
+  async _fromSidecar(path) {
+    const raw = await readFile(path, 'utf8').catch(() => null);
+    if (raw == null) return null;
+    try {
+      return cleanTitle(JSON.parse(raw).customTitle);
+    } catch {
+      return null;
+    }
+  }
+
+  async _fromTranscript(path) {
+    const file = await open(path, 'r').catch(() => null);
+    if (!file) return null;
+    try {
+      const { size } = await file.stat();
+      const start = Math.max(0, size - this.tailBytes);
+      const buffer = Buffer.alloc(Math.min(size, this.tailBytes));
+      if (buffer.length) await file.read(buffer, 0, buffer.length, start);
+      const lines = buffer.toString('utf8').split('\n');
+      // A window that does not start at byte 0 opens mid-line; that fragment is
+      // not a JSON record.
+      if (start > 0) lines.shift();
+      return lastTitle(lines);
+    } finally {
+      await file.close();
+    }
+  }
+}
+
+/** A typed name wins wherever it sits in the file; otherwise the most recent
+ *  generated one. Both are re-appended as a session runs, so the scan reads
+ *  backwards and stops at the first match. */
+function lastTitle(lines) {
+  let generated = null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    // Transcript lines are mostly multi-kilobyte messages; reject those on a
+    // substring before paying for JSON.parse.
+    if (!line || line[0] !== '{' || !line.includes('-title"')) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (record.type === 'custom-title') {
+      const typed = cleanTitle(record.customTitle);
+      if (typed) return typed;
+    }
+    if (record.type === 'ai-title' && !generated) generated = cleanTitle(record.aiTitle);
+  }
+  return generated;
+}
+
+function cleanTitle(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}

package/src/status-renderer.js

@@ -276,9 +276,12 @@ function formatServerSummary(server, now) {
   return started ? `up ${formatDuration(now - started)}` : 'unknown';
 }
 
-function formatPercent(value) {
+export function formatPercent(value) {
   if (value == null || Number.isNaN(Number(value))) return '-';
-  return `${Math.round(Number(value) * 100)}%`;
+  // The switch threshold can be set to a tenth of a percent, so rounding to a
+  // whole one would print a value that was never stored. Reported utilization
+  // arrives on a whole-percent grid, so bars are unaffected.
+  return `${Math.round(Number(value) * 1000) / 10}%`;
 }
 
 function formatNumber(value) {

package/src/tui-remote.js

@@ -1,4 +1,5 @@
 import { TUI } from './tui.js';
+import { SessionTitles } from './session-titles.js';
 import { modelGlobMatches } from './model.js';
 
 // Attach mode — the dashboard against a server running somewhere else (a
@@ -234,6 +235,10 @@ export function createAttachSession({ control, config, onQuit, pollMs = DEFAULT_
     accountManager: am,
     config,
     remote: true,
+    // Titles come from this machine's Claude Code sessions. Attaching to a
+    // server on another host leaves the ids unresolved, which shows the short
+    // id rather than a wrong name.
+    sessionTitles: new SessionTitles(config?.sessionTitles),
     // Every screen that writes config is unreachable in attach mode; if one ever
     // becomes reachable, this fails loudly instead of silently dropping a save.
     saveConfig: async () => { throw new Error('attach mode cannot write config'); },

package/src/tui.js

@@ -1,6 +1,8 @@
 import { createWriteStream } from 'node:fs';
 import { importCredentials, fetchProfile } from './oauth.js';
 import { sameIdentity, findUpsertTarget } from './identity.js';
+import { formatProjection } from './quota-projection.js';
+import { formatPercent } from './status-renderer.js';
 import { parseProxyUrl, proxyToUrl, describeProxy, resolveUpstreamProxy, setUpstreamProxy, getUpstreamProxy } from './upstream-proxy.js';
 
 // ── ANSI helpers ─────────────────────────────────────────────
@@ -62,10 +64,12 @@ function sessionColorCode(sid) {
   for (let i = 0; i < sid.length; i++) h = (h * 31 + sid.charCodeAt(i)) >>> 0;
   return SESSION_FG[h % SESSION_FG.length];
 }
-// Fixed-width colored short id (blank-padded when there's no session, e.g. a
-// telemetry request), so the activity column stays aligned.
-const sessionTag = sid =>
-  sid ? fg(sessionColorCode(sid), sid.slice(0, SESSION_ID_LEN)) : ' '.repeat(SESSION_ID_LEN);
+// Fixed-width colored session label: the name Claude Code holds on disk for the
+// session (see session-titles.js), else the short id. Blank-padded when there's
+// no session (e.g. a telemetry request). One width for every row, named or not,
+// keeps the columns after it aligned.
+const sessionTag = (sid, title = null, width = SESSION_ID_LEN) =>
+  sid ? fg(sessionColorCode(sid), (title || sid.slice(0, SESSION_ID_LEN)).slice(0, width).padEnd(width)) : ' '.repeat(width);
 
 // Which quota-family bar (F7/S7) a route binds to, or null for a general route.
 // Auto routes are named 'fable'/'sonnet'; a configured route is classified by its
@@ -198,7 +202,10 @@ export class TUI {
     remote = false, applySwitch = null,
     // Injectable so the import path can be exercised without a real credentials
     // file or a live profile call.
-    readCredentials = importCredentials, readProfile = fetchProfile }) {
+    readCredentials = importCredentials, readProfile = fetchProfile,
+    // Names the activity column against the session id the client sent. Absent
+    // or disabled leaves every row showing the short id.
+    sessionTitles = null }) {
     this.am = accountManager;
     this.remote = remote;
     this.applySwitch = applySwitch;
@@ -213,6 +220,7 @@ export class TUI {
     this._readCredentials = readCredentials;
     this._readProfile = readProfile;
     this._activityStream = null;
+    this.sessionTitles = sessionTitles;
 
     this.log = [];           // completed activity entries
     this.active = new Map(); // in-flight requests
@@ -312,9 +320,20 @@ export class TUI {
     process.stdin.pause();
   }
 
+  // A title lookup costs a directory scan and a file read, so it stays off the
+  // render path: this returns what is cached and schedules the rest.
+  _sessionTag(sid) {
+    const titles = this.sessionTitles;
+    if (!titles?.enabled) return sessionTag(sid);
+    return sessionTag(sid, titles.get(sid), titles.width);
+  }
+
   // ── server hooks ───────────────────────────────────
 
   onRequestStart(id, info) {
+    // Start the lookup now, so the title is cached by the time the request ends
+    // and its log line is composed.
+    this._sessionTag(info.sessionId);
     this.active.set(id, { ...info, t: timestamp(), started: Date.now(), account: null });
     this.render();
     if (this.active.size === 1) this._retick();   // idle → animating
@@ -338,7 +357,7 @@ export class TUI {
     const model = info.model ? ` (${info.model})` : ''; // shown when the request named a model
     const sid = info.sessionId || r?.sessionId || null;
     const pin = (info.pinned || r?.pinned) ? dim(' [pin]') : '';
-    this._addLog(`${sessionTag(sid)} ${info.method} ${info.path}${model} → ${acct}${pin} (${info.status}, ${dur}s)`);
+    this._addLog(`${this._sessionTag(sid)} ${info.method} ${info.path}${model} → ${acct}${pin} (${info.status}, ${dur}s)`);
     if (this.active.size === 0) this._retick();   // animating → idle
   }
 
@@ -411,13 +430,10 @@ export class TUI {
       id: 'threshold',
       label: 'Switch threshold',
       hint: '←→ ±1%',
-      value: () => {
-        const thr = this.am.switchThreshold ?? this.config.switchThreshold ?? 0.98;
-        return green(`${Math.round(thr * 100)}%`);
-      },
+      value: () => green(formatPercent(this.am.switchThreshold ?? this.config.switchThreshold ?? 0.98)),
       left: () => this._nudgeThreshold(-1),
       right: () => this._nudgeThreshold(+1),
-      enter: () => this._promptInput('Switch threshold % (1-100)', v => this._doSetThreshold(v.trim())),
+      enter: () => this._promptInput('Switch threshold % (1-100, tenths allowed)', v => this._doSetThreshold(v.trim())),
     });
 
     fields.push({
@@ -448,6 +464,18 @@ export class TUI {
       enter: () => this._cycleEventLogging(+1),
     });
 
+    if (this.sessionTitles) {
+      fields.push({
+        id: 'sessionTitles',
+        label: 'Session titles',
+        hint: '←→ toggle',
+        value: () => (this.sessionTitles.enabled ? green('on') : gray('off')),
+        left: () => this._toggleSessionTitles(),
+        right: () => this._toggleSessionTitles(),
+        enter: () => this._toggleSessionTitles(),
+      });
+    }
+
     fields.push({
       id: 'routes',
       label: 'Manage routing',
@@ -572,9 +600,11 @@ export class TUI {
   }
 
   _nudgeThreshold(deltaPct) {
-    const cur = Math.round((this.am.switchThreshold ?? this.config.switchThreshold ?? 0.98) * 100);
+    // Stepping from the exact percent, not a rounded one, so a threshold set to
+    // a tenth keeps its fraction instead of snapping to the nearest whole.
+    const cur = (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));
+    if (next !== cur) return this._doSetThreshold(String(next));
   }
 
   _nudgeProbe(deltaSec) {
@@ -588,7 +618,9 @@ export class TUI {
     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;
+    // Tenths of a percent are kept; anything finer is quantised so the stored
+    // value is the one the screen shows.
+    const v = Math.round(pct * 10) / 1000;
     this.config.switchThreshold = v;
     this.am.switchThreshold = v; // apply to the running rotation immediately
     try { await this.saveConfig(this.config); }
@@ -848,6 +880,17 @@ export class TUI {
     if (this.running) this.render();
   }
 
+  async _toggleSessionTitles() {
+    const next = { ...this.sessionTitles.settings(), enabled: !this.sessionTitles.enabled };
+    this.sessionTitles.configure(next);
+    // The shared config object is what a save writes and a reload re-applies.
+    this.config.sessionTitles = { ...this.config.sessionTitles, ...next };
+    try { await this.saveConfig(this.config); }
+    catch (e) { this._addLog(`Failed to save: ${e.message}`); }
+    this._addLog(`Session titles: ${next.enabled ? 'on' : 'off'}`);
+    if (this.running) this.render();
+  }
+
   async _cycleEventLogging(dir = 1) {
     // Claude Code telemetry display/handling: show → hide → block → show.
     const order = ['show', 'hide', 'block'];
@@ -1107,7 +1150,7 @@ export class TUI {
       const m = r.model ? dim(` (${r.model})`) : ''; // filled in as soon as the model is peeked from the stream
       const pin = r.pinned ? dim(' [pin]') : '';
       const a = r.account ? ` → ${r.account}${pin}` : '';
-      lines.push(` ${sp} ${gray(r.t)}  ${sessionTag(r.sessionId)} ${r.method} ${r.path}${m}${a} ${dim(`(${el}s...)`)}`);
+      lines.push(` ${sp} ${gray(r.t)}  ${this._sessionTag(r.sessionId)} ${r.method} ${r.path}${m}${a} ${dim(`(${el}s...)`)}`);
     }
 
     // Completed log
@@ -1230,6 +1273,21 @@ export class TUI {
     if (q.unified7dSonnet != null && q.unified7dSonnet >= th) blocked.push('Sonnet');
     if (q.unified7dFable != null && q.unified7dFable >= th) blocked.push('Fable');
     if (blocked.length) line += `  ${red('⊘ ' + blocked.join(' '))}`;
+
+    // Burn-rate tags, most urgent first: TTL for a window that runs out before
+    // it resets, an unspent share for one that expires with quota left. A
+    // deficit will stop this account, so it is colored; a surplus is a note and
+    // stays gray. Optional on the manager so a stand-in without projection
+    // support still renders.
+    const buckets = this.am.projectionsFor?.(idx) || {};
+    const ranked = this.am.projection?.rank(Object.values(buckets)) || [];
+    if (ranked.length) {
+      const tags = ranked.map(p => {
+        const text = formatProjection(p);
+        return p.kind === 'deficit' ? yellow(text) : gray(text);
+      });
+      line += `  ${tags.join(gray(' · '))}`;
+    }
     return line;
   }
 
@@ -1267,6 +1325,7 @@ export class TUI {
     // ── Activity log
     lines.push(bold('  Activity log') + dim('  — what to do with Claude Code\'s telemetry'));
     lines.push(row(byId('eventlog')));
+    if (byId('sessionTitles')) lines.push(row(byId('sessionTitles')));
     lines.push('');
     // ── Routing
     lines.push(bold('  Routing') + dim('  — pin model families to specific accounts, or block them outright'));