@rikcodes/teamclaude 1.1.20-rik.11 → 1.1.20-rik.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.20-rik.11",
+  "version": "1.1.20-rik.13",
   "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);
@@ -739,11 +775,27 @@ async function serverCommand() {
   // instead of re-running teardown, which would re-arm server.close() and leak a
   // 'close' listener on the server each time (MaxListenersExceededWarning).
   let shuttingDown = false;
-  async function shutdown() {
-    if (shuttingDown) process.exit(0); // second ctrl-c: stop waiting, just go
-    shuttingDown = true;
+  // Everything this process borrowed from the terminal, given back: at most
+  // once, never throwing, and on every path that leaves. shutdown() does it
+  // first, as it always has. A restart drain now keeps the display up to the
+  // last moment and does it last — which makes the guard below, the "stop
+  // waiting, just go" path, the one that would otherwise walk out of a drain
+  // leaving the operator on the alternate screen with raw mode still on and a
+  // terminal they cannot type into.
+  const restoreTerminal = () => {
     try { tui?.stop(); } catch { /* terminal already restored */ }
+    // Stopping the title belongs here rather than at the top of a drain: while
+    // one runs the title still names the build that is running, which is the
+    // whole reason it carries the build at all.
     stopTitle();
+  };
+  async function shutdown() {
+    // Second ctrl-c, or a signal arriving during a restart drain: stop waiting,
+    // just go — but hand the terminal back first, because nothing after this
+    // line runs and on the drain path the display is still up.
+    if (shuttingDown) { restoreTerminal(); process.exit(0); }
+    shuttingDown = true;
+    restoreTerminal();
     if (!tui) console.log('\n[TeamClaude] Shutting down...');
     prober?.stop();
     warmer?.stop();
@@ -760,6 +812,105 @@ 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.
+  //
+  // The display is the other difference. shutdown() tears it down first; this
+  // keeps it to the end. A drain is up to thirty seconds of waiting the
+  // operator asked for, and taking the dashboard away at the start of it left
+  // them watching plain console lines with no way to tell how far it had got or
+  // what was holding it.
+  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;
+    tui?.restartDrainStarted({
+      deadlineMs: DRAIN_DEADLINE_MS,
+      inFlight: () => accountManager.inFlightRequests(),
+    });
+    // Under the TUI console.log IS the log pane (tui.js), so this line and the
+    // two the drain ends with report themselves on screen beside the live
+    // counter, and nothing extra has to be written for them.
+    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();
+    /** @type {string|null} */
+    let failure = null;
+    // 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 listener closed: there is no serving
+      // state left to return to, so record what broke and let the relaunch be
+      // the recovery. Read off `err` defensively because throwing HERE is the
+      // one thing the try above cannot absorb, and an unhandled rejection out
+      // of this function is exit 1 — a crash, on the path whose whole purpose
+      // is to come back.
+      failure = /** @type {any} */ (err)?.message || String(err);
+    } finally {
+      // The last thing before the exit, and in a finally because the catch is
+      // not the only way out of the block above.
+      restoreTerminal();
+    }
+    // After the restore, so it lands on the screen the relaunch comes back to
+    // rather than in a log pane that goes with the alternate screen.
+    if (failure) console.error(`[TeamClaude] Drain failed: ${failure}`);
+    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 +2343,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 +2557,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 +2578,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

@@ -144,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) {
@@ -270,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
@@ -873,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

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.12+acc19b3"), 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,25 @@ 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, at the same width and for the same reason: a
+  // tab strip gives a title a few dozen columns at best, and neither string was
+  // chosen here. 24 rather than 20 because a checkout names both halves of what
+  // it runs — `1.1.20-rik.12+acc19b3`, 21 columns — and cutting that at 20 ends
+  // the title in half a sha, which names no commit while reading like it does.
+  // A label still long enough to be cut at 24 was never one of ours.
+  const build = version ? ` ${truncate(version, 24)}` : '';
+  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,35 @@ export function fitLine(s, w) {
   return s;
 }
 
+/** The build label at `max` columns, or '' when nothing legible fits.
+ *
+ *  Build metadata is spent before anything is cut. A checkout labels itself
+ *  `<version>+<sha>`, and of the two it is the version the header is read for;
+ *  the sha only says which build of it. Shortening the sha instead would be
+ *  worse than losing it — four hex digits name no commit, and are read as if
+ *  they did.
+ *
+ *  What is left is 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) {
+  if (max >= vw(label)) return label;
+  // Everything after the last `+` is semver build metadata, which is by
+  // definition not the identity — so it is what gets spent first. `> 0` keeps a
+  // label that is nothing but metadata from being spent down to nothing.
+  const plus = label.lastIndexOf('+');
+  const bare = plus > 0 ? label.slice(0, plus) : label;
+  if (max >= vw(bare)) return bare;
+  if (max < HEAD_LABEL_MIN) return '';
+  return `…${bare.slice(bare.length - (max - 1))}`;
+}
+
 function formatReset(resetTs) {
   if (!resetTs) return '';
   const ms = resetTs - Date.now();
@@ -411,6 +444,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 +472,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)
@@ -466,6 +504,15 @@ export class TUI {
     this.frame = 0;
     this.running = false;
     this.timer = null;
+    // Set while THIS PROCESS is draining to be relaunched: when the wait
+    // started, what bounds it, and how to ask how much is still running.
+    // Deliberately not named `draining`: the header's `drain N` marker and the
+    // account manager's drainingCount() are SESSION draining — sessions being
+    // moved off an account during a rotation — and the two have nothing to do
+    // with each other. One is a request finishing somewhere else; this one is
+    // the process going away.
+    /** @type {{ startedAt: number, deadlineMs: number, inFlight: () => number }|null} */
+    this._restartDrain = null;
     // Injectable so a test can drive the repaint tick by hand instead of
     // sleeping through real 500ms/5s intervals.
     this._setTimeout = setTimeout;
@@ -544,8 +591,11 @@ export class TUI {
     this._scheduleTick();
   }
 
-  /** Fast while something is animating, slow when there is nothing to animate. */
-  _tickDelay() { return this.active.size > 0 ? SPIN_MS : IDLE_TICK_MS; }
+  /** Fast while something is animating, slow when there is nothing to animate.
+   *  A restart drain counts as animating: an idle tick is five seconds, and an
+   *  elapsed counter that moves once every five of them reads as a frozen
+   *  screen — which is the complaint keeping the display up exists to answer. */
+  _tickDelay() { return (this.active.size > 0 || this._restartDrain) ? SPIN_MS : IDLE_TICK_MS; }
 
   _scheduleTick() {
     if (!this.running) return;
@@ -600,6 +650,28 @@ export class TUI {
     process.stdin.pause();
   }
 
+  /**
+   * The server has begun draining to be relaunched: its listener is closed and
+   * it is waiting out the requests still running before it exits on 75.
+   *
+   * The display stays up for all of it, and this is what puts the drain on it.
+   * The wait is up to 30 seconds the operator asked for by pressing `u`, and
+   * the two things they want from it — how long it has run, and what is still
+   * holding it — are already here. The dashboard used to come down first, so
+   * the answer to both was a blank console for the duration.
+   *
+   * There is no matching "ended": the process exits at the end of the drain,
+   * and stop() is what takes the screen back (index.js, immediately before the
+   * exit and on every abrupt way out of one).
+   *
+   * @param {{ deadlineMs: number, inFlight: () => number }} drain
+   */
+  restartDrainStarted({ deadlineMs, inFlight }) {
+    this._restartDrain = { startedAt: Date.now(), deadlineMs, inFlight };
+    this._retick();   // idle cadence → something to animate again
+    if (this.running) this.render();
+  }
+
   // 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) {
@@ -676,6 +748,17 @@ export class TUI {
   _key(k) {
     if (k === 'ctrl-c') { this.stop(); this.onQuit?.(); return; }
 
+    // Draining to a restart: the listener is closed and this process is on its
+    // way out, so switching, disabling, probing, syncing or editing anything
+    // would act on state that is about to be discarded, and `u` is already
+    // running. Ctrl-c above stays the one key that means something — the escape
+    // from the wait — and the footer says so, which is why nothing is logged
+    // for the rest: a line per keypress would push the drain's own progress out
+    // of the pane. `q` is not an exception on purpose. An unattended restart
+    // can begin while the operator is typing into a prompt, and a letter key
+    // that quietly became "quit" is a poor way to find that out.
+    if (this._restartDrain) return;
+
     switch (this.mode) {
       case 'normal': this._keyNormal(k); break;
       case 'select': this._keySelect(k); break;
@@ -704,6 +787,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 +1212,20 @@ 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 now keeps this TUI up for the whole drain, which is
+  // where the progress goes (restartDrainStarted, and the footer). Its own
+  // "draining, up to 30s" line lands in the pane beside the counter, so there
+  // is nothing left for this to announce.
+  //
+  // A second `u` is not a second restart: the server guards on its own flag and
+  // would do nothing at all, so a log line here would be a claim that it had.
+  _doRestart() {
+    if (!this.onRestart || this._restartDrain) return;
+    this.onRestart();
+  }
+
   // ── Network settings ───────────────────────────────
 
   /**
@@ -1474,8 +1572,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 +1589,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;
@@ -1656,7 +1772,7 @@ export class TUI {
 
     // ── Footer
     lines.push(' ' + dim('─'.repeat(W - 2)));
-    lines.push(this._renderFooter());
+    lines.push(this._renderFooter(W));
 
     // Write buffer
     let buf = `${ESC}H`;
@@ -2261,12 +2377,17 @@ export class TUI {
     }
   }
 
-  _renderFooter() {
+  /** @param {number} [W]  columns to compose against; only the drain line uses it */
+  _renderFooter(W = process.stdout.columns || 80) {
+    // A restart drain outranks every mode: the keys this line would otherwise
+    // advertise are all refused while one runs (see _key), and how far the
+    // drain has got is the only thing on screen worth the row.
+    if (this._restartDrain) return this._restartDrainFooter(this._restartDrain, W);
     switch (this.mode) {
       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':
@@ -2298,4 +2419,30 @@ export class TUI {
         return '';
     }
   }
+
+  /**
+   * The footer while this process drains to a restart: how long the wait has
+   * run against the bound it cannot exceed, what is still holding it, and the
+   * way out of it.
+   *
+   * Elapsed against the deadline, not a countdown. The drain ends when the last
+   * request does, which is usually long before 30s, so a number counting down
+   * to a moment that will not arrive would be the wrong kind of wrong — worse
+   * than one counting up to a bound that may never be reached.
+   *
+   * Whole seconds: the frame is composed twice a second while a drain runs, and
+   * tenths would buy a full repaint every time for a digit nobody reads.
+   *
+   * Cut by dropping a whole clause rather than by leaving it to fitLine, which
+   * truncates the tail — and at 40 columns the tail is the escape hatch.
+   *
+   * @param {{ startedAt: number, deadlineMs: number, inFlight: () => number }} drain
+   * @param {number} W
+   */
+  _restartDrainFooter(drain, W) {
+    const secs = Math.max(0, Math.round((Date.now() - drain.startedAt) / 1000));
+    const state = `${yellow('Restarting')}  ${secs}s/${Math.round(drain.deadlineMs / 1000)}s  ${drain.inFlight()} in flight`;
+    const lines = [` ${state}  ${dim('ctrl-c to go now')}`, ` ${state}`];
+    return lines.find(line => vw(line) <= W) ?? lines[lines.length - 1];
+  }
 }

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)), '..');
 }
 
@@ -44,9 +44,22 @@ export function currentVersion(root = packageRoot()) {
 
 /**
  * How the running copy identifies itself, for display: the exact tag when the
- * checkout sits on one, else the short sha, else the shipped package.json
- * version, else the literal `local`. `git` reports a checkout — npm cannot
- * update one, so nothing should offer to.
+ * checkout sits on one, else the package.json version joined to the short sha,
+ * else whichever of those two is readable, else the literal `local`. `git`
+ * reports a checkout — npm cannot update one, so nothing should offer to.
+ *
+ * A checkout needs both halves. The sha is here because package.json alone
+ * cannot tell a published release from a local tarball built out of it, so the
+ * sha is what marks a checkout at a glance. But it answers "which commit", and
+ * the question asked after a restart is "which build" — which a sha never
+ * answers, and which is the whole reason this label exists. The two are joined
+ * with `+`, semver's build metadata, because that is precisely what the sha is:
+ * the same version, pinned to the build that produced it. It also tells a
+ * caller short of columns which end to spend, build metadata being by
+ * definition the part that is not the identity.
+ *
+ * A tag still wins outright, and alone: it names a release and a commit at
+ * once, so appending the sha to it would say the same thing twice.
  *
  * The git calls are pinned to the package root. `teamclaude server` is started
  * from the operator's own project directory, and resolving against the process
@@ -59,18 +72,22 @@ export function currentVersion(root = packageRoot()) {
  */
 export async function resolveVersionLabel({ root = packageRoot(), exec = pexec } = {}) {
   const git = existsSync(join(root, '.git'));
+  const version = currentVersion(root);
   if (git) {
     /** @type {{ cwd: string, encoding: 'utf8', timeout: number }} */
     const opts = { cwd: root, encoding: 'utf8', timeout: 2000 };
-    const probes = [['describe', '--tags', '--exact-match', 'HEAD'], ['rev-parse', '--short', 'HEAD']];
-    for (const args of probes) {
+    /** @param {string[]} args */
+    const ask = async (args) => {
       try {
-        const label = safeLine((await exec('git', args, opts)).stdout, LABEL_MAX);
-        if (label) return { label, git };
-      } catch { /* not on a tag, a shallow or broken checkout, or no git binary */ }
-    }
+        return safeLine((await exec('git', args, opts)).stdout, LABEL_MAX);
+      } catch { return ''; /* not on a tag, a shallow or broken checkout, or no git binary */ }
+    };
+    const tag = await ask(['describe', '--tags', '--exact-match', 'HEAD']);
+    if (tag) return { label: tag, git };
+    const sha = await ask(['rev-parse', '--short', 'HEAD']);
+    if (sha) return { label: safeLine(version ? `${version}+${sha}` : sha, LABEL_MAX), git };
   }
-  return { label: safeLine(currentVersion(root) || 'local', LABEL_MAX), git };
+  return { label: safeLine(version || 'local', LABEL_MAX), git };
 }
 
 /** Numeric compare of x.y.z, then the pre-release tail. >0 if a is newer.