@rikcodes/teamclaude 1.1.20-rik.10 → 1.1.20-rik.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.20-rik.10",
+  "version": "1.1.20-rik.12",
   "description": "Multi-account proxy for Claude Code and Codex: pools Claude Max, ChatGPT/Codex, API-key and third-party backend accounts, and rotates on quota",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -1437,6 +1437,26 @@ export class AccountManager {
     return { ...this.sessionTracker.stats(), mode: this.distributionMode, draining: this.drainingCount() };
   }
 
+  /**
+   * Client requests running right now, fleet-wide. What a drain waits on.
+   *
+   * Two counters, because neither one spans a whole request. A session's hold
+   * is taken across the ENTIRE client request, a multi-minute stream included
+   * (see beginSession), which is precisely what a restart must not cut — but it
+   * is only taken for a request that carries a session id. An account's
+   * `inFlight` covers the rest, though only as far as the response headers:
+   * storm control releases that slot there so streaming bodies do not tie up
+   * concurrency. Summing them double-counts a session's request while it is
+   * upstream-bound, which can only make a drain wait longer than it strictly
+   * must — and the drain deadline bounds that.
+   */
+  inFlightRequests() {
+    // The tracker is a plain object to the checker here (see the constructor),
+    // so the cast is how its counter is reached — not a claim about the value.
+    const sessions = /** @type {any} */ (this.sessionTracker).inFlightCount();
+    return sessions + this.accounts.reduce((n, a) => n + (a.inFlight || 0), 0);
+  }
+
   /**
    * Like getActiveAccount, but if the selected account's OAuth token has ALREADY
    * expired it blocks on a refresh before returning — so a caller that injects

package/src/config.js

@@ -102,6 +102,7 @@ export function createDefaultConfig() {
     projection: { enabled: true, windowMinutes: 90, wasteFloor: 0.1 },
     eventLogging: 'hide',
     activityLog: null,
+    autoRestart: false,
     blockedModels: [],
     accounts: [],
   };

package/src/index.js

@@ -37,6 +37,8 @@ import { SessionTitles } from './session-titles.js';
 import { RemoteControl, createAttachSession } from './tui-remote.js';
 import { SxManager } from './sx.js';
 import { autoUpdate, checkForUpdate, currentVersion, resolveVersionLabel, runUpdate, installKind, updateAvailableFromCache, PKG_NAME } from './updater.js';
+import { drainServer, superviseServer, DRAIN_DEADLINE_MS, RESTART_COUNT_ENV, RESTART_EXIT_CODE, SUPERVISED_ENV } from './restart.js';
+import { createVersionSource, UpdateWatcher } from './update-watch.js';
 import { renderStatus, formatPercent } from './status-renderer.js';
 import { sanitizeText } from './safe-text.js';
 import { ClientUsageTracker, UsageDimensionTracker } from './client-usage.js';
@@ -223,6 +225,12 @@ switch (command) {
 // ── server ──────────────────────────────────────────────────
 
 async function serverCommand() {
+  // --supervise: this process supervises, it does not serve. The config, the
+  // accounts, the certificates and the terminal all belong to the child it
+  // starts, so this branch comes before any of them is touched.
+  if (args.includes('--supervise')) {
+    process.exit(await superviseServer());
+  }
   // Installed first: the server is the long-lived process, it runs under a TUI
   // that repaints over anything Node prints on the way out, and a crash here
   // takes every routed session with it. Without this, a proxy that vanished
@@ -331,6 +339,7 @@ async function serverCommand() {
   const persistQuotaState = () =>
     saveState({ quota: accountManager.exportQuotaState(), clients: clientUsage.export(), usageDimensions: dimensionUsage.export(), sidecars: sidecar?.exportPids() || savedState?.sidecars || {} })
       .catch(err => console.error(`[TeamClaude] Failed to save quota state: ${err.message}`));
+  /** @type {ReturnType<typeof setInterval>|null} */
   let quotaSaveInterval = null;
 
   // Persist refreshed tokens back to config (re-read from disk to avoid clobbering
@@ -376,12 +385,23 @@ async function serverCommand() {
   const headless = args.includes('--headless') || args.includes('--no-tui');
   const useTUI = !headless && process.stdout.isTTY && process.stdin.isTTY;
 
+  // Is anything waiting to relaunch this process? Exit 75 is a request, not a
+  // mechanism: with nothing supervising, it is merely an exit. So the two things
+  // that can ask for one — the `u` key and autoRestart — are wired only when the
+  // answer is yes. `teamclaude server --supervise` sets this on its child, and
+  // the shell loop in docs/usage.md exports it for the same reason.
+  const supervised = process.env[SUPERVISED_ENV] === '1';
+  const restartCount = Number(process.env[RESTART_COUNT_ENV]) || 0;
+
   // Opt-in background quota probe (config.quotaProbeSeconds, default 0 = off).
+  /** @type {Prober|null} */
   let prober = null;
   // Opt-in keep-warm scheduler (interval or persisted reset-target schedule).
+  /** @type {Warmer|null} */
   let warmer = null;
   // Supervised sidecar processes (config.sidecars, default none) — e.g. a local
   // Anthropic→OpenAI translating proxy that a third-party account routes to.
+  /** @type {Sidecar|null} */
   let sidecar = null;
   const serverStartedAt = Date.now();
   // Read once here, not per request: `teamclaude update` swaps package.json on
@@ -491,7 +511,9 @@ async function serverCommand() {
   };
 
   let tui = null;
-  /** @type {Object} */
+  // A bag of optional callbacks the application installs on a shared object the
+  // server, the MITM listener and the control endpoints all read through.
+  /** @type {Record<string, any>} */
   let hooks = {};
 
   if (useTUI) {
@@ -531,6 +553,10 @@ async function serverCommand() {
       // POSIX signals (defined below). In raw mode ctrl-c never reaches the OS as
       // a signal, so without this the process would only tear down via keypress.
       onQuit: () => shutdown(),
+      // `u`. Null without a supervisor: draining to an exit nothing acts on
+      // would take the proxy — and every session on it — down, which is the
+      // opposite of what a key labelled "update" offers.
+      onRestart: supervised ? () => { drainAndRestart('Restart requested'); } : null,
     });
     hooks = {
       onRequestStart: (id, info) => tui.onRequestStart(id, info),
@@ -662,13 +688,14 @@ async function serverCommand() {
     }
     if (tui) {
       tui.start();
-      console.log(`Listening on port ${port} with ${accounts.length} account(s)`);
+      console.log(`Listening on port ${port} with ${accounts.length} account(s) on ${versionLabel}`);
     } else {
       const sep = '='.repeat(60);
       console.log('');
       console.log(sep);
       console.log('  TeamClaude Proxy');
       console.log(sep);
+      console.log(`  Version:    ${versionLabel}`);
       console.log(`  Bind:       ${bindHost}:${port}${bindHost === '127.0.0.1' ? ' (localhost only)' : ' (reachable off-box — ensure proxy.apiKey is set)'}`);
       console.log(`  Accounts:   ${accounts.length}`);
       console.log(`  Threshold:  ${(threshold * 100).toFixed(0)}%`);
@@ -683,11 +710,20 @@ async function serverCommand() {
       console.log(sep);
       console.log('');
     }
+    // Said once, plainly. The complaint this whole path exists to answer is
+    // that the build changes under a window nobody is watching and nothing
+    // anywhere admits it: the title carries the version from here on, and this
+    // line is the moment it changed.
+    if (restartCount > 0) {
+      console.log(`[TeamClaude] Restarted on ${versionLabel} — relaunch #${restartCount} of this supervised run.`);
+    }
   });
 
-  // Reflect the active account in the terminal title so a backgrounded/tabbed
-  // server is glanceable. Works in both TUI and headless modes.
-  const stopTitle = startTerminalTitleUpdater(accountManager);
+  // Reflect the active account and the running build in the terminal title so a
+  // backgrounded/tabbed server is glanceable. Works in both TUI and headless
+  // modes, and is the surface an unattended restart announces itself on: the
+  // title is all that is readable when the window is not the one in front.
+  const stopTitle = startTerminalTitleUpdater(accountManager, versionLabel);
 
   // Persist quota every minute; unref so it never keeps the process alive.
   quotaSaveInterval = setInterval(persistQuotaState, 60_000);
@@ -760,6 +796,82 @@ async function serverCommand() {
   }
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
+
+  // The graceful counterpart to shutdown(), for the other request an operator
+  // can make: not "stop now" but "come back on the new build". shutdown() is
+  // left exactly as it is — destroying live streams is the right answer to
+  // ctrl-c — while this path has to cost the fleet nothing, because the point
+  // of automating it is that it happens while nobody is watching.
+  //
+  // Order matters and is not the same as shutdown()'s. The flag goes up FIRST,
+  // so every answer still to be written carries the header that retires its
+  // socket (markDraining, server.js) — that, not the waiting, is what stops a
+  // restart from breaking sessions that were only ever idle. Then the listener
+  // stops accepting while the connections already open keep serving; then the
+  // bounded wait; then the sidecar, whose replacement the next process spawns;
+  // then quota state, exactly as shutdown() persists it. Exit 75 is the ask.
+  let draining = false;
+  hooks.isDraining = () => draining;
+  /** @param {string} why  what put the restart in motion, for the line on the way out */
+  async function drainAndRestart(why) {
+    if (shuttingDown) return; // ctrl-c beat us here, or a second trigger did
+    shuttingDown = true;
+    draining = true;
+    try { tui?.stop(); } catch { /* terminal already restored */ }
+    stopTitle();
+    console.log(`\n[TeamClaude] ${why} — draining, up to ${Math.round(DRAIN_DEADLINE_MS / 1000)}s for requests in flight.`);
+    prober?.stop();
+    warmer?.stop();
+    eventLoopMonitor.stop();
+    // Nothing below may throw its way out. Neither caller awaits this — the TUI
+    // key returns to its handler and the watcher fires from a timer — so an
+    // escaping rejection would be an unhandled one, and crash-log.js turns that
+    // into exit 1: the supervisor would read a crash and stop, on the one path
+    // whose entire purpose is to come back.
+    try {
+      const { drained, waitedMs, inFlight } = await drainServer({
+        server,
+        inFlight: () => accountManager.inFlightRequests(),
+      });
+      console.log(drained
+        ? `[TeamClaude] Drained in ${(waitedMs / 1000).toFixed(1)}s. Restarting on the new build.`
+        : `[TeamClaude] ${inFlight} request(s) still in flight after ${(waitedMs / 1000).toFixed(0)}s — restarting anyway.`);
+      sidecar?.stop();
+      if (quotaSaveInterval) clearInterval(quotaSaveInterval);
+      await persistQuotaState();
+    } catch (err) {
+      // Committed from the moment the display came down and the listener
+      // closed: there is no serving state left to return to, so say what broke
+      // and let the relaunch be the recovery.
+      console.error(`[TeamClaude] Drain failed: ${err.message}`);
+    }
+    process.exit(RESTART_EXIT_CODE);
+  }
+
+  // Opt-in, and only where a restart would actually happen. Nothing below runs
+  // on a default config, so the install probe behind createVersionSource is not
+  // paid for by anyone who did not ask for this.
+  if (config.autoRestart && !supervised) {
+    console.error('[TeamClaude] autoRestart is set, but nothing will relaunch this process — start it with "teamclaude server --supervise". Auto-restart is off for this run.');
+  } else if (config.autoRestart) {
+    const source = await createVersionSource();
+    if (!source) {
+      console.error('[TeamClaude] autoRestart is set, but this copy is a local or npx install — nothing rewrites it, so a restart would come back on the same build. Auto-restart is off for this run.');
+    } else {
+      new UpdateWatcher({
+        source,
+        // Nothing running and no session still counted active: a restart now
+        // costs a reconnect and nothing else.
+        isIdle: () => accountManager.inFlightRequests() === 0 && accountManager.sessionStats().active === 0,
+        onRestart: ({ build, forced }) => {
+          drainAndRestart(forced
+            ? `Build ${build} is waiting and the fleet has not gone idle`
+            : `Build ${build} is waiting`);
+        },
+      }).start();
+      console.log(`[TeamClaude] Auto-restart is on, watching ${source.describes}.`);
+    }
+  }
 }
 
 // ── import ──────────────────────────────────────────────────
@@ -2192,6 +2304,9 @@ Options:
   --log-to DIR        Log requests/responses to DIR (server, one file per request)
   --activity-log FILE Append TUI activity lines to FILE (server; works in headless mode too)
   --headless          Run the server without the interactive TUI (for backgrounding)
+  --supervise         (server) run the proxy as a child process and relaunch it
+                      whenever it drains for a new build (the TUI's 'u' key, or
+                      the autoRestart setting). Without it neither can restart
   --no-mitm           (run) skip the forward proxy; route via ANTHROPIC_BASE_URL only
   --auto-fallback     (run) if the proxy is down, launch claude directly instead
                       of erroring out (bypasses the proxy: no rotation)
@@ -2403,13 +2518,19 @@ function argValue(flag) {
   return (i >= 0 && args[i + 1]) ? args[i + 1] : null;
 }
 
-// Keep the terminal title in sync with the active account (e.g. "teamclaude 2/4
-// work") so a backgrounded or tabbed `teamclaude server` is glanceable. TTY-only
+// Keep the terminal title in sync with the active account and the running build
+// (e.g. "teamclaude 2/4 work 1.1.20-rik.11") so a backgrounded or tabbed
+// `teamclaude server` is glanceable — and so a restart onto a new build is
+// visible there without anyone going looking. TTY-only
 // — never emit escapes into a pipe, a `--log-to` redirect, or a systemd journal;
 // opt out entirely with TEAMCLAUDE_NO_TITLE. Polls (rather than hooking every
 // currentIndex mutation) and writes only when the title actually changes.
 // Returns an idempotent stop() that restores the shell's previous title.
-function startTerminalTitleUpdater(accountManager) {
+/**
+ * @param {AccountManager} accountManager
+ * @param {string|null} [version]
+ */
+function startTerminalTitleUpdater(accountManager, version = null) {
   const out = process.stdout;
   if (!out.isTTY || process.env.TEAMCLAUDE_NO_TITLE) return () => {};
 
@@ -2418,7 +2539,7 @@ function startTerminalTitleUpdater(accountManager) {
     const total = accountManager.accounts.length;
     const index = Math.min(accountManager.currentIndex || 0, Math.max(0, total - 1));
     const name = accountManager.accounts[index]?.name || null;
-    const title = formatTerminalTitle({ index, total, name });
+    const title = formatTerminalTitle({ index, total, name, version });
     if (title !== last) { last = title; out.write(titleSequence(title)); }
   };
 

package/src/restart.js

@@ -0,0 +1,186 @@
+// Drain-and-restart: applying a new build without cutting a live session.
+//
+// Restarting the proxy used to mean ctrl-c and a fast re-run, which breaks
+// every Claude Code session going through it, for two separate reasons:
+//
+//   1. shutdown() calls server.closeAllConnections(), which DESTROYS in-flight
+//      streaming responses. That abruptness is deliberate — a person holding
+//      ctrl-c wants out now — so it is left exactly as it is, and the graceful
+//      path lives here instead.
+//   2. A restart kills idle keep-alive sockets the client still holds pooled.
+//      The client finds out by writing to a corpse, which is the same failure
+//      family as the two keep-alive fixes before this one.
+//
+// A drain answers both: stop accepting connections, tell every response on the
+// way out that its socket is finished (`Connection: close`, set in server.js
+// off `hooks.isDraining`), and wait for the requests already running to end.
+// Clients retire their pooled sockets cooperatively and reconnect into the
+// relaunched process.
+//
+// The relaunch itself is exit code 75 plus a supervisor, because a foreground
+// TUI cannot re-exec itself: the parent exits, the shell prints a prompt, and
+// the child fights it for the terminal.
+
+import { spawn } from 'node:child_process';
+
+// "Restart me." Chosen from the sysexits.h range (EX_TEMPFAIL) so it cannot
+// collide with the 0/1 a crash or a clean quit already uses, and so a
+// supervisor that does not know about it treats it as an ordinary failure.
+export const RESTART_EXIT_CODE = 75;
+
+// How long a drain waits for in-flight requests before going anyway. A stuck
+// stream — an upstream that stopped sending without closing — must never be
+// able to block a restart forever, and the requests that outlive this get the
+// abrupt end they would have got from ctrl-c.
+export const DRAIN_DEADLINE_MS = 30_000;
+const DRAIN_POLL_MS = 100;
+
+// A child that asks to be restarted this many times inside the window is
+// looping, not updating: something makes the new build ask for a restart the
+// moment it is up, and relaunching it forever would hide that behind a
+// flickering terminal.
+export const RESTART_LOOP_LIMIT = 5;
+export const RESTART_LOOP_WINDOW_MS = 60_000;
+
+// Set on a supervised child. Two things read it: the `u` key and the automatic
+// restart, neither of which may exit 75 unless something is actually waiting to
+// relaunch this process — otherwise "apply the update" reads as "kill the proxy
+// and every session on it". The documented shell one-liner exports it too.
+export const SUPERVISED_ENV = 'TEAMCLAUDE_SUPERVISED';
+// How many relaunches this process is, so it can say so once it is listening.
+export const RESTART_COUNT_ENV = 'TEAMCLAUDE_RESTARTS';
+
+/**
+ * Stop taking work and wait for what is running to finish.
+ *
+ * `server.close()` and NOT `closeAllConnections()`: close stops the listener,
+ * while the connections already open keep streaming — and keep serving, which
+ * is the point. A client whose pooled socket is still good sends its next
+ * request into this window and gets a real answer carrying `Connection: close`,
+ * so it retires that socket itself rather than discovering it dead later. Only
+ * the sockets that stayed idle through the whole drain are closed, at the end,
+ * where the gap between the close and the relaunch is as small as it can be.
+ *
+ * Every side effect is injectable so the deadline can be tested without
+ * spending it.
+ *
+ * @param {Object} opts
+ * @param {{ close?: Function, closeIdleConnections?: Function }} opts.server
+ * @param {() => number} opts.inFlight  requests still running, fleet-wide
+ * @param {number} [opts.deadlineMs]
+ * @param {number} [opts.pollMs]
+ * @param {() => number} [opts.now]
+ * @param {(ms: number) => Promise<void>} [opts.sleep]
+ * @returns {Promise<{ drained: boolean, waitedMs: number, inFlight: number }>}
+ */
+export async function drainServer({
+  server, inFlight, deadlineMs = DRAIN_DEADLINE_MS, pollMs = DRAIN_POLL_MS,
+  now = Date.now, sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms)),
+}) {
+  const started = now();
+  // No callback: a CONNECT tunnel is not tracked as a connection Node will tell
+  // us about, so waiting for close() to call back could wait forever. What we
+  // wait on is the request count below, which the deadline bounds.
+  server.close?.();
+  let open = inFlight();
+  while (open > 0 && now() - started < deadlineMs) {
+    await sleep(pollMs);
+    open = inFlight();
+  }
+  // The sockets that never carried a response during the drain, and so never
+  // got the `Connection: close` that retires them politely. Closing them is
+  // unavoidable — the process is going — so it happens here, last, rather than
+  // at the start where it would yank a socket the client was about to use.
+  server.closeIdleConnections?.();
+  return { drained: open <= 0, waitedMs: now() - started, inFlight: Math.max(0, open) };
+}
+
+/**
+ * Run the real server as a child and relaunch it when it asks (exit 75). Any
+ * other exit is the child's answer and ends the supervisor with it.
+ *
+ * `stdio: 'inherit'` hands over the actual terminal, so the child's TUI owns
+ * raw mode, the tty size and the title exactly as it would unsupervised. The
+ * supervisor itself must therefore touch neither stdin nor the screen.
+ *
+ * Resolves with the exit code this process should use.
+ *
+ * @param {Object} [opts]
+ * @param {string[]} [opts.argv]  what to run: [script, ...args], `--supervise` removed
+ * @param {typeof spawn} [opts.spawnFn]
+ * @param {string} [opts.execPath]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {(line: string) => void} [opts.log]
+ * @param {() => number} [opts.now]
+ * @param {number} [opts.limit]
+ * @param {number} [opts.windowMs]
+ * @param {(event: string, handler: Function) => void} [opts.onSignal]
+ */
+export function superviseServer({
+  argv = process.argv.slice(1), spawnFn = spawn, execPath = process.execPath,
+  env = process.env, log = console.error, now = Date.now,
+  limit = RESTART_LOOP_LIMIT, windowMs = RESTART_LOOP_WINDOW_MS,
+  onSignal = (event, handler) => process.on(event, /** @type {any} */ (handler)),
+} = {}) {
+  const childArgv = argv.filter(a => a !== '--supervise');
+  /** @type {number[]} */
+  const relaunches = [];
+  /** @type {import('node:child_process').ChildProcess|null} */
+  let child = null;
+  let stopping = false;
+
+  // SIGTERM is aimed at this pid alone, so it has to be passed on or the child
+  // keeps the terminal with nothing supervising it. SIGINT deliberately is NOT:
+  // ctrl-c goes to the whole foreground process group, so the child already has
+  // it, and a second one tells its shutdown() to stop waiting and exit at once
+  // — the graceful teardown skipped by the very key meant to allow it.
+  onSignal('SIGTERM', () => { stopping = true; child?.kill('SIGTERM'); });
+  onSignal('SIGINT', () => { stopping = true; });
+
+  return new Promise((resolve) => {
+    const launch = (/** @type {number} */ restarts) => {
+      try {
+        child = spawnFn(execPath, childArgv, {
+          stdio: 'inherit',
+          env: { ...env, [SUPERVISED_ENV]: '1', [RESTART_COUNT_ENV]: String(restarts) },
+        });
+      } catch (err) {
+        log(`[TeamClaude] Could not start the server: ${/** @type {Error} */ (err).message}`);
+        resolve(1);
+        return;
+      }
+      if (!child || typeof child.once !== 'function') { resolve(1); return; }
+      child.once('error', (err) => {
+        log(`[TeamClaude] Could not start the server: ${err.message}`);
+        resolve(1);
+      });
+      child.once('exit', (code, signal) => {
+        child = null;
+        // Killed rather than exited: the operator or the OS ended it, and there
+        // is nothing here to second-guess. 128+n is the shell's convention for
+        // reporting which signal it was.
+        if (code === null) { resolve(signal ? 128 + (signalNumber(signal) || 0) : 1); return; }
+        if (code !== RESTART_EXIT_CODE || stopping) { resolve(code); return; }
+
+        const at = now();
+        relaunches.push(at);
+        while (relaunches.length && at - relaunches[0] > windowMs) relaunches.shift();
+        if (relaunches.length > limit) {
+          log(`[TeamClaude] The server asked to restart ${relaunches.length} times in ${Math.round(windowMs / 1000)}s — it is looping, not updating. Giving up; start it again by hand once you know why.`);
+          resolve(1);
+          return;
+        }
+        launch(restarts + 1);
+      });
+    };
+    launch(0);
+  });
+}
+
+/** Signal name to number, for the 128+n exit convention. Unknown names report
+ *  0, which reads as "killed, we don't know by what" rather than throwing.
+ *  @param {NodeJS.Signals|string} name */
+function signalNumber(name) {
+  const table = /** @type {Record<string, number>} */ ({ SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 });
+  return table[String(name)] || 0;
+}

package/src/server.js

@@ -61,6 +61,29 @@ const INLINE_RETRY_AFTER_MAX_SECONDS = 15;
 // the account so concurrent requests wait, then retries the same account.
 const RATE_LIMIT_ABSORB_MAX_SECONDS =
   Number(process.env.TEAMCLAUDE_RATE_LIMIT_ABSORB_MAX_SECONDS) || 60;
+// How long to wait before the one retry of a headerless 429 — a 429 carrying no
+// retry-after and no anthropic-ratelimit-* headers at all.
+//
+// Measured over a 32-minute window: these arrive in 0.6-0.8s, about once every
+// 8 minutes on Fable traffic and never on any other model, and they follow the
+// request onto whichever account the failover hop moves it to. That hop re-asks
+// roughly 0.7s after the first refusal and is refused again, which is direct
+// evidence that a wait shorter than that buys nothing but a third identical
+// refusal. The ceiling is what the client does instead: Claude Code shows
+// "will retry in 2m 38s" and then usually succeeds, so any wait measured in
+// seconds trades a visible stall for an invisible one. 2s clears the interval
+// already known to fail while keeping the worst case — the retry is refused too
+// and the client gets its 429 anyway, just later — at about 4s.
+//
+// One delay, not a ladder: the limit's window is unknown, and a second guess at
+// it would cost the client the wait without evidence that it helps. Override
+// with TEAMCLAUDE_HEADERLESS_429_RETRY_DELAY_MS.
+const DEFAULT_HEADERLESS_429_RETRY_DELAY_MS = 2000;
+
+function resolveHeaderless429RetryDelayMs() {
+  const env = Number(process.env.TEAMCLAUDE_HEADERLESS_429_RETRY_DELAY_MS);
+  return env > 0 ? env : DEFAULT_HEADERLESS_429_RETRY_DELAY_MS;
+}
 const OAUTH_ENTITLEMENT_ERROR_CODE = 'oauth_not_allowed_for_organization';
 const ERROR_BODY_INSPECTION_LIMIT = 64 * 1024;
 // How long an idle keep-alive connection is held open.
@@ -121,6 +144,36 @@ const CONNECTION_SPECIFIC_HEADERS = new Set([
   'proxy-connection', 'te', 'trailer',
 ]);
 
+/**
+ * While the server is draining, tell this response's client that the socket is
+ * finished with.
+ *
+ * The cooperative half of a restart (see restart.js). A process that simply
+ * stops leaves every pooled keep-alive socket a corpse the client discovers
+ * only by writing to it — the failure this proxy has now been bitten by twice,
+ * and the reason a restart "breaks running sessions" even when the drain waits
+ * politely for the requests it can see. `Connection: close` retires the socket
+ * from the client's pool the moment this response lands, so the next request
+ * opens a fresh connection into the relaunched process.
+ *
+ * Set with setHeader rather than in a writeHead object: every answer below
+ * builds its own header object, and `connection` is stripped from all of them
+ * as hop-by-hop, so this survives the merge on each of the dozen exits instead
+ * of having to be added to each.
+ *
+ * HTTP/2 is left alone — the header is illegal there (Node refuses it) and a
+ * MITM tunnel's h2 session goes away with the CONNECT socket regardless.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {any} hooks  the application's hook bag; `isDraining` is optional
+ */
+export function markDraining(req, res, hooks) {
+  if (!hooks.isDraining?.()) return;
+  if ((req.httpVersionMajor || 1) >= 2) return;
+  try { res.setHeader('Connection', 'close'); } catch { /* already answered */ }
+}
+
 // Constant-time proxy-API-key comparison (both the HTTP gate and the CONNECT
 // gate use it). Returns false on any type/length mismatch without leaking timing.
 export function safeKeyEqual(a, b) {
@@ -247,6 +300,9 @@ export function createProxyServer(accountManager, config, hooks = {}, sx = null,
 
   const requestHandler = async (req, res) => {
     try {
+      // Before any exit below writes a head, control endpoints included: a
+      // status poll and a dashboard refresh hold pooled sockets too.
+      markDraining(req, res, hooks);
       // Dashboard page — served BEFORE the auth gate on purpose. The page is a
       // static asset containing no data: everything it shows comes from
       // /teamclaude/status, which stays behind the gate and is fetched by the
@@ -850,6 +906,9 @@ export function clientSessionId(headers) {
 export function createProxyRequestListener({ accountManager, upstream, logDir = null, hooks = {}, sx = null, holdMs = 0, config = {}, forcedPin = null, egress = null, clientUsage = null, forcedClient = null, dimensionUsage = null }) {
   let counter = 0;
   return async (req, res) => {
+    // Again here, not only in the base server's wrapper: this listener is also
+    // the MITM tunnel's, where nothing above it has seen the request.
+    markDraining(req, res, hooks);
     // The activity entry this request opened, while it is still open. Every
     // consumer holds the row until it is told the request ended, so exactly one
     // path must close it. Each closing site clears this first, which is how the
@@ -2419,7 +2478,45 @@ export async function forwardRequest(req, res, body, accountManager, upstream, r
       } else if (ctx.rateLimitHopped && requestScoped) {
         // Second headerless 429, on a different account: it followed the
         // request. Nothing here is about either account.
-        console.log(`[TeamClaude] 429 followed the request onto "${account.name}" with no rate-limit headers — it is about the request, not the accounts; returning it to the client`
+        //
+        // That does not make it permanent. Measured: these land about once every
+        // 8 minutes on Fable traffic, from four different starting accounts, and
+        // the client's own retry usually succeeds — so most are a transient the
+        // fleet cannot route around, not a model id upstream refuses. Returning
+        // it straight away is what left Claude Code sitting on "will retry in
+        // 2m 38s", with nothing in the session transcript to explain the pause.
+        //
+        // So take one short retry first, on THIS account. Not on a third one:
+        // the limit is scoped to neither account, so another hop would pay a
+        // cold prompt cache to learn what the first hop already established —
+        // the same argument that bounds the hop budget above. ctx.hopTo keeps
+        // the attempt on the account it landed on and off the fleet cursor
+        // (#286), and `route` keeps its egress, since the wait is the only
+        // variable being tested. A fresh IP is a different hypothesis and the sx
+        // retry below still owns it: when it is armed it goes first, for free,
+        // and this retry takes the attempt after it.
+        //
+        // Only for a caller that actually waits. A Codex one does not: it gives
+        // the response head 60s, then retries the whole request itself (see
+        // holdsConnection, and the incident recorded in
+        // test/codex-no-inline-hold.test.js). Holding it here would stack our
+        // wait underneath its own, which is the trade that file exists to refuse.
+        const retryDelayMs = resolveHeaderless429RetryDelayMs();
+        const callerWaits = holdsConnection(ctx.provider);
+        if (!ctx.headerless429Retried && !switchingToSx && retryCount < maxRetries
+          && !res.headersSent && !clientGone(res) && !ctx.signal?.aborted && callerWaits) {
+          // Once per request: a retry that is refused too has made the point.
+          ctx.headerless429Retried = true;
+          console.log(`[TeamClaude] 429 followed the request onto "${account.name}" with no rate-limit headers — retrying it once on the same account in ${retryDelayMs}ms`
+            + (refusal ? ` (${safeLine(refusal)})` : ''));
+          await waitForRetry(retryDelayMs, ctx.signal);
+          if (clientGone(res)) { ctx.abandoned = true; return; }
+          ctx.hopTo = account.index;
+          return forwardRequest(req, res, body, accountManager, upstream, retryCount + 1, hooks, reqId, ctx, logDir, sx, route);
+        }
+        console.log(`[TeamClaude] 429 followed the request onto "${account.name}" with no rate-limit headers — `
+          + (callerWaits ? 'it is about the request, not the accounts' : `${ctx.provider} caller does not wait`)
+          + '; returning it to the client'
           + (refusal ? ` (${safeLine(refusal)})` : ''));
       } else if (ctx.rateLimitHopped) {
         // Second 429 this request, on a different account. Say so once: the
@@ -2445,10 +2542,16 @@ export async function forwardRequest(req, res, body, accountManager, upstream, r
       // third time is the other half of #288. With no sibling to hop to, one
       // short retry covers a momentary blip, and then it is the client's turn.
       if (requestScoped) {
-        if (!ctx.rateLimitHopped && !ctx.requestScopedRetried && retryCount < maxRetries) {
+        // Same rule as the post-hop retry and the inline absorb below: a wait is
+        // only invisible to a caller that waits longer than we do.
+        if (!ctx.rateLimitHopped && !ctx.requestScopedRetried && retryCount < maxRetries
+          && holdsConnection(ctx.provider)) {
           ctx.requestScopedRetried = true;
-          console.log(`[TeamClaude] 429 with no rate-limit headers on "${account.name}" — retrying once in 2s${refusal ? ` (${safeLine(refusal)})` : ''}`);
-          await waitForRetry(2000, ctx.signal);
+          // The same number as the post-hop retry above: one phenomenon, one
+          // delay, one env var to move both.
+          const retryDelayMs = resolveHeaderless429RetryDelayMs();
+          console.log(`[TeamClaude] 429 with no rate-limit headers on "${account.name}" — retrying once in ${retryDelayMs}ms${refusal ? ` (${safeLine(refusal)})` : ''}`);
+          await waitForRetry(retryDelayMs, ctx.signal);
           if (clientGone(res)) { ctx.abandoned = true; return; }
           return forwardRequest(req, res, body, accountManager, upstream, retryCount + 1, hooks, reqId, ctx, logDir, sx, nextUseSx);
         }

package/src/session-tracker.js

@@ -341,6 +341,20 @@ export class SessionTracker {
     return s.inFlight > 0 || now - s.lastSeen <= this.activeTtlMs;
   }
 
+  /** Requests in flight across every session, for a drain to wait on.
+   *
+   *  The hold this counts spans the whole client request, a long stream
+   *  included (see beginRequest), so zero here means no client is mid-answer —
+   *  which is the one thing a restart has to be sure of. Counted on demand
+   *  rather than kept as a running total: this is asked a few times a second
+   *  during a drain and never otherwise, while the map is bounded by MAX_SESSIONS.
+   */
+  inFlightCount() {
+    let n = 0;
+    for (const s of this.sessions.values()) n += s.inFlight;
+    return n;
+  }
+
   // Expired = idle past the known window AND nothing in flight (a long-running
   // request keeps the session alive no matter how old lastSeen is).
   _isExpired(s, now) {

package/src/terminal-title.js

@@ -1,7 +1,8 @@
-// Reflect the active account in the terminal title (e.g. "teamclaude 2/4 work"),
-// so a backgrounded or tabbed `teamclaude server` is glanceable without
-// switching to it. Pure/side-effect-free here so it can be unit-tested; the
-// caller owns the TTY gate and the interval.
+// Reflect the active account and the running build in the terminal title (e.g.
+// "teamclaude 2/4 work 1.1.20-rik.11"), so a backgrounded or tabbed
+// `teamclaude server` is glanceable without switching to it. Pure/side-effect-
+// free here so it can be unit-tested; the caller owns the TTY gate and the
+// interval.
 
 const OSC_TITLE = '\x1b]0;'; // OSC 0 — set icon name + window title
 const BEL = '\x07';
@@ -20,11 +21,21 @@ function truncate(s, max) {
   return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
 }
 
-// Short, glanceable title: "teamclaude <pos>/<total> <name>". `index` is 0-based.
-export function formatTerminalTitle({ index = 0, total = 0, name = null } = {}) {
+// Short, glanceable title: "teamclaude <pos>/<total> <name> <version>". `index`
+// is 0-based.
+//
+// The version is here because the title is the only surface still readable
+// while the window is backgrounded — which is exactly the state a server is in
+// when a drain-and-restart swaps the build under it. Without it the only
+// evidence that anything happened is a screen that scrolled while nobody was
+// looking.
+export function formatTerminalTitle({ index = 0, total = 0, name = null, version = null } = {}) {
   const pos = total > 0 ? `${index + 1}/${total}` : '0/0';
   const who = name ? ` ${truncate(name, 24)}` : '';
-  return `teamclaude ${pos}${who}`;
+  // Bounded like the account name, for the same reason: a tab strip gives a
+  // title a few dozen columns at best, and neither string was chosen here.
+  const build = version ? ` ${truncate(version, 20)}` : '';
+  return `teamclaude ${pos}${who}${build}`;
 }
 
 // Wrap a title string in the OSC set-title sequence, stripping control chars so a

package/src/tui.js

@@ -213,11 +213,15 @@ const BAR_MAX = 20;
 // terminal lays the table out exactly as it did before the column could grow.
 const NAME_MIN = 12;
 
-// Clear space the centred version label needs on each side before it is drawn
-// at all. Below that it reads as a collision with the title or the port block,
-// so the whole label is dropped rather than squeezed.
+// Clear space the version label needs on each side before it is drawn at all.
+// Below that it reads as a collision with the title or the port block.
 const HEAD_GAP = 2;
 
+// Narrowest label still worth drawing: an ellipsis and three columns of build.
+// Under that the header goes back to naming no build at all, which at those
+// widths is the honest answer.
+const HEAD_LABEL_MIN = 4;
+
 // Which pair of bars a row draws: the subscription buckets (Ses/Wk, plus the
 // S7/F7 family bars) when any unified reading exists, else the metered Tok/Req
 // pair an API-key account reports. The account row budget is drawn per
@@ -281,6 +285,23 @@ export function fitLine(s, w) {
   return s;
 }
 
+/** The build label at `max` columns, or '' when nothing legible fits.
+ *
+ *  Cut from the LEFT, unlike every other truncation here, because what tells
+ *  one build from the next is its tail: `…rik.11` still identifies the build,
+ *  `1.1.2…` identifies the three before it just as well. Sliced by code unit
+ *  against a display-width budget — a version or a sha is ASCII, and a label
+ *  arriving over the wire is measured again by the caller before it is placed,
+ *  so a wide glyph costs the label its slot rather than the header its width.
+ *  @param {string} label
+ *  @param {number} max */
+export function fitHeadLabel(label, max) {
+  const w = vw(label);
+  if (max >= w) return label;
+  if (max < HEAD_LABEL_MIN) return '';
+  return `…${label.slice(label.length - (max - 1))}`;
+}
+
 function formatReset(resetTs) {
   if (!resetTs) return '';
   const ms = resetTs - Date.now();
@@ -411,6 +432,10 @@ function timestamp() {
 
 export class TUI {
   constructor({ accountManager, config, saveConfig, syncAccounts, onQuit, sx = null, probeQuota = null, activityLogPath = null,
+    // `u`: drain and come back on the new build. Null when nothing would
+    // relaunch the process, which is what stops a key offering an update from
+    // meaning "kill the proxy and every session on it".
+    onRestart = /** @type {(() => void)|null} */ (null),
     // Supervised sidecar state for the conduit lines. A getter, not a snapshot:
     // the supervisor respawns on its own schedule and the TUI redraws on a timer.
     getSidecars = null,
@@ -435,6 +460,7 @@ export class TUI {
     this.saveConfig = saveConfig;
     this.syncAccounts = syncAccounts;
     this.onQuit = onQuit;
+    this.onRestart = onRestart; // drain-and-restart, when something supervises us
     this.sx = sx;            // sx.org proxy manager (may be null)
     this.sxBalance = null;   // last fetched sx.org balance, for the settings screen
     this.probeQuota = probeQuota; // on-demand fleet-wide quota refresh (may be null)
@@ -704,6 +730,7 @@ export class TUI {
       this.mode = 'select'; this.selAction = 'toggle'; this.selIdx = this.am.currentIndex; this.selReturn = 'normal';
     }
     else if (k === 'p' && this.am.accounts.length > 0) { this._doProbe(); }
+    else if (k === 'u' && this.onRestart) { this._doRestart(); }
     else if (k === 'g') { this.mode = 'settings'; this.setIdx = 0; this._loadSxBalance(); }
   }
 
@@ -1128,6 +1155,17 @@ export class TUI {
     }
   }
 
+  // `u`: pick up a new build now instead of waiting for the next lull. The
+  // server owns what happens next — it drains, then exits asking to be
+  // relaunched — and it stops this TUI first, so the line below is on screen
+  // only for the instant before the display goes and the drain reports itself
+  // in plain text.
+  _doRestart() {
+    if (!this.onRestart) return;
+    this._addLog('Draining before restart...');
+    this.onRestart();
+  }
+
   // ── Network settings ───────────────────────────────
 
   /**
@@ -1474,8 +1512,15 @@ export class TUI {
     // server's. A local AccountManager has neither property.
     const label = this.am.versionLabel ?? this.versionLabel;
     const upd = this.am.updateAvailable ?? this.updateAvailable;
-    const mid = label ? dim(label) + (upd ? ` ${green('▲')}` : '') : '';
-    const lw = vw(left), rw = vw(right), mw = vw(mid);
+    const lw = vw(left), rw = vw(right);
+    // Columns left between the two blocks, and what the label may take of them.
+    // The marker is budgeted before the label is cut, so a shortened label and
+    // its marker still fit the room they were measured against.
+    const room = W - lw - rw;
+    const markerW = upd ? 2 : 0;
+    const text = label ? fitHeadLabel(label, room - 2 * HEAD_GAP - markerW) : '';
+    const mid = text ? dim(text) + (upd ? ` ${green('▲')}` : '') : '';
+    const mw = vw(mid);
     // Centred on the line, not in the gap between the two blocks, so the label
     // holds still as the session segment comes and goes.
     const start = Math.floor((W - mw) / 2);
@@ -1484,9 +1529,20 @@ export class TUI {
     // branch can never produce the over-wide line the other branch can, so the
     // two are not interchangeable.
     const midFits = mw > 0 && start - lw >= HEAD_GAP && (W - rw) - (start + mw) >= HEAD_GAP;
+    // Line-centring is a position, not a fit. The two blocks are different
+    // widths, so a label small enough for the gap can still be pushed inside
+    // one of them by where the centre of the LINE falls — and that, not width,
+    // is what used to drop the label every time the session segment grew,
+    // leaving a header that silently stopped naming the build it exists to
+    // name. Centre it in the GAP instead, which is exact by construction: the
+    // two runs below sum to `room`. The label moves when sessions come and go,
+    // which is the price; being able to read it is what that buys.
+    const gapPad = mw > 0 && room - mw >= 2 * HEAD_GAP ? Math.floor((room - mw) / 2) : -1;
     lines.push(midFits
       ? left + ' '.repeat(start - lw) + mid + ' '.repeat(W - rw - start - mw) + right
-      : left + ' '.repeat(Math.max(1, W - lw - rw)) + right);
+      : gapPad >= 0
+        ? left + ' '.repeat(gapPad) + mid + ' '.repeat(room - mw - gapPad) + right
+        : left + ' '.repeat(Math.max(1, W - lw - rw)) + right);
     lines.push(' ' + dim('─'.repeat(W - 2)));
 
     const footerH = 2;
@@ -2266,7 +2322,7 @@ export class TUI {
       case 'normal':
         return this.remote
           ? ` ${bold('s')}witch  ${bold('R')}eload  ${bold('q')}uit`
-          : ` ${bold('s')}witch  ${bold('d')}isable  ${bold('p')}robe quota  ${bold('R')}eload  ${bold('g')} settings  ${bold('q')}uit`;
+          : ` ${bold('s')}witch  ${bold('d')}isable  ${bold('p')}robe quota  ${bold('R')}eload${this.onRestart ? `  ${bold('u')}pdate` : ''}  ${bold('g')} settings  ${bold('q')}uit`;
       case 'settings':
         return ` ${dim('↑↓')} navigate  ${dim('←→')} change  ${bold('Enter')} edit  ${bold('Esc')} back`;
       case 'routes':

package/src/update-watch.js

@@ -0,0 +1,232 @@
+// What tells a running proxy that a newer build is waiting for it.
+//
+// The signal is not the same on every install, and picking only one of them
+// would leave the primary user with dead code:
+//
+//   global npm install — `npm install -g` replaces the files under the running
+//     process, so the version in the package's own package.json stops matching
+//     the version this process loaded. That difference, not the registry, is
+//     the signal: a published release nothing has installed yet is not
+//     something a restart can apply. autoUpdate (updater.js) does the
+//     installing; this only notices that it landed.
+//   git checkout — npm refuses to touch one by design, so there is no installed
+//     version to compare. The deploy clone's HEAD moving is the signal, read
+//     with one cheap `git rev-parse` on a timer.
+//
+// Both answer the same question — "would restarting run something else?" — so
+// both feed the same drain-and-restart, and the install kind picks which is
+// asked.
+//
+// Detecting a new build is not permission to apply it. A restart costs every
+// live session its connection, so it waits for the fleet to go quiet; a fleet
+// that never does gets restarted anyway, because a proxy that updates only
+// when nobody is using it never updates at all.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { compareVersions, currentVersion, installKind, isReleaseVersion, packageRoot } from './updater.js';
+
+const pexec = promisify(execFile);
+
+// How often the source is asked. A git checkout costs one `rev-parse` and a
+// global install one small file read, so this is cheap enough to be frequent
+// and slow enough to be invisible.
+export const UPDATE_POLL_MS = 60_000;
+
+// How long the fleet must stay quiet before a pending build is applied. The
+// session tracker already calls a session inactive after two idle minutes
+// (SESSION_ACTIVE_TTL_MS), so this is the quiet period ON TOP of that — proof
+// that the lull held rather than a gap between two turns of one conversation.
+export const FLEET_IDLE_MS = 60_000;
+
+// ...and how long a pending build waits for that quiet before going anyway. A
+// busy fleet must not be able to postpone an update forever; at this point the
+// drain is what protects the sessions, not the wait.
+export const RESTART_DEADLINE_MS = 30 * 60_000;
+
+// Bounded like every other git call in this package: a checkout on a stalled
+// network mount must cost the proxy a skipped check, not a stuck timer.
+const GIT_TIMEOUT_MS = 2000;
+
+/**
+ * @typedef {Object} VersionSource
+ * @property {string} kind          the install shape this reads
+ * @property {string} describes     what it names, for the log line
+ * @property {() => Promise<string|null>} read  the build a restart would run, or null when that is the one already running
+ */
+
+/**
+ * A git checkout: HEAD's sha, compared against the sha this process started on.
+ *
+ * The baseline is taken on the first successful read rather than in the
+ * constructor, because reading is asynchronous and a watcher that had no
+ * baseline yet would read the first pull as "nothing changed". A first read
+ * that fails (no git binary, a broken checkout) leaves the baseline unset, so
+ * the next successful one becomes it — one missed pull rather than a watcher
+ * that never works again.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.root]
+ * @param {(file: string, args: string[], options: { cwd: string, encoding: 'utf8', timeout: number }) => Promise<{ stdout: string }>} [opts.exec]
+ * @returns {VersionSource}
+ */
+export function gitHeadSource({ root = packageRoot(), exec = pexec } = {}) {
+  let baseline = null;
+  return {
+    kind: 'git',
+    describes: 'the checkout HEAD',
+    async read() {
+      let head = null;
+      try {
+        /** @type {{ cwd: string, encoding: 'utf8', timeout: number }} */
+        const opts = { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS };
+        head = String((await exec('git', ['rev-parse', 'HEAD'], opts)).stdout).trim();
+      } catch { return null; } // no git, no repository, or it took too long
+      // Shape-checked before it is compared: anything else is git reporting a
+      // problem on stdout, and treating that as a sha would restart the proxy
+      // on every poll for as long as the problem lasted.
+      if (!/^[0-9a-f]{7,64}$/.test(head)) return null;
+      baseline ||= head;
+      return head === baseline ? null : head;
+    },
+  };
+}
+
+/**
+ * A global npm install: the version on disk at the package root.
+ *
+ * `currentVersion` is re-read every time on purpose — that file is what
+ * `npm install -g` rewrites under a running process, and the whole signal is
+ * that it stopped matching what this process loaded. Only a newer release
+ * counts: a reinstall of the same version changes nothing worth a restart, and
+ * a downgrade or a version string that is not a release is not something to
+ * relaunch into.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.root]
+ * @param {string|null} [opts.running]  the version this process is executing
+ * @returns {VersionSource}
+ */
+export function npmVersionSource({ root = packageRoot(), running = currentVersion(root) } = {}) {
+  return {
+    kind: 'global',
+    describes: 'the installed package',
+    async read() {
+      const installed = currentVersion(root);
+      if (!installed || !running || !isReleaseVersion(installed)) return null;
+      return compareVersions(installed, running) > 0 ? installed : null;
+    },
+  };
+}
+
+/**
+ * The source for how this copy was installed, or null when a restart could not
+ * pick anything up: a local dependency or an npx copy is nobody's deployment,
+ * and nothing rewrites it under us.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.root]
+ * @param {Function} [opts.kind]
+ * @param {Function} [opts.exec]
+ * @param {string|null} [opts.running]
+ * @returns {Promise<VersionSource|null>}
+ */
+export async function createVersionSource({ root = packageRoot(), kind = installKind, exec = pexec, running = currentVersion(root) } = {}) {
+  const how = await kind({ root });
+  if (how === 'git') return gitHeadSource({ root, exec: /** @type {any} */ (exec) });
+  if (how === 'global') return npmVersionSource({ root, running });
+  return null;
+}
+
+/**
+ * Polls a source and asks for a restart once a new build is waiting AND the
+ * fleet is quiet enough to lose its connections cheaply.
+ *
+ * Fires exactly once: the restart it asks for ends the process, and a second
+ * request during the drain would be noise at best.
+ */
+export class UpdateWatcher {
+  /**
+   * @param {Object} opts
+   * @param {VersionSource|null} opts.source
+   * @param {() => boolean} opts.isIdle       is the fleet serving nothing right now
+   * @param {(info: { build: string, forced: boolean, waitedMs: number }) => void} opts.onRestart
+   * @param {number} [opts.pollMs]
+   * @param {number} [opts.idleMs]
+   * @param {number} [opts.deadlineMs]
+   * @param {() => number} [opts.now]
+   * @param {(line: string) => void} [opts.log]
+   */
+  constructor({
+    source, isIdle, onRestart, pollMs = UPDATE_POLL_MS, idleMs = FLEET_IDLE_MS,
+    deadlineMs = RESTART_DEADLINE_MS, now = Date.now, log = console.log,
+  }) {
+    this.source = source;
+    this.isIdle = isIdle;
+    this.onRestart = onRestart;
+    this.pollMs = pollMs;
+    this.idleMs = idleMs;
+    this.deadlineMs = deadlineMs;
+    this.now = now;
+    this.log = log;
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this.timer = null;
+    /** @type {string|null} the build waiting to be picked up */
+    this._build = null;
+    // Timestamps, and null rather than 0 for "not yet": a clock can legitimately
+    // read 0, and a falsy check would then re-stamp both of these on every poll
+    // — the deadline would never arrive and the quiet period never accumulate.
+    /** @type {number|null} when the build was first seen, for the deadline */
+    this._pendingSince = null;
+    /** @type {number|null} when the fleet last went quiet, for the wait */
+    this._idleSince = null;
+    this._fired = false;
+    this._busy = false;        // a read is outstanding; never overlap them
+  }
+
+  /** No-op without a source, so the caller needs no second condition. */
+  start() {
+    if (!this.source || this.timer) return;
+    // Primes the baseline (see gitHeadSource) rather than waiting a full poll
+    // to learn what is already running.
+    this.check();
+    this.timer = setInterval(() => { this.check(); }, this.pollMs);
+    this.timer.unref?.();
+  }
+
+  stop() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+  }
+
+  /** One poll. Public so a test can drive the decision without spending the
+   *  interval, the idle wait and the deadline in real time. */
+  async check() {
+    if (this._fired || this._busy || !this.source) return null;
+    this._busy = true;
+    try {
+      const build = await this.source.read();
+      if (build) this._build = build;
+      // Nothing waiting: whatever idleness was accumulating is not evidence
+      // about a build, so it starts again with the next one.
+      if (!this._build) { this._idleSince = null; return null; }
+
+      const now = this.now();
+      if (this._pendingSince === null) {
+        this._pendingSince = now;
+        this.log(`[TeamClaude] A newer build is waiting (${this._build}) — restarting once the fleet is idle, or in ${Math.round(this.deadlineMs / 60_000)} min regardless.`);
+      }
+      if (this.isIdle()) this._idleSince ??= now; else this._idleSince = null;
+
+      const settled = this._idleSince !== null && now - this._idleSince >= this.idleMs;
+      const overdue = now - this._pendingSince >= this.deadlineMs;
+      if (!settled && !overdue) return null;
+
+      this._fired = true;
+      this.stop();
+      this.onRestart({ build: this._build, forced: !settled, waitedMs: now - this._pendingSince });
+      return this._build;
+    } finally {
+      this._busy = false;
+    }
+  }
+}

package/src/updater.js

@@ -29,7 +29,7 @@ const LABEL_MAX = 32;
 const pexec = promisify(execFile);
 
 /** Package root = one directory above this file's src/ directory. */
-function packageRoot() {
+export function packageRoot() {
   return resolve(dirname(fileURLToPath(import.meta.url)), '..');
 }