maxpool 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Multi-account Claude Code proxy with adaptive, rate-aware load balancing across Claude accounts",
   "type": "module",
   "main": "src/index.js",
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "start": "node src/index.js",
-    "test": "node --test",
+    "test": "bash scripts/run-tests.sh",
     "lint": "eslint src/ test/",
     "release": "bash scripts/release.sh"
   },

package/src/account-manager.js

@@ -201,6 +201,21 @@ export class AccountManager {
       bytes: 0, // aggregate buffered body bytes across all held requests
     };
     this.admissionPaused = false;
+    // Single-writer baton: only the lease holder may rotate OAuth refresh tokens
+    // (refresh tokens are single-use; two refreshers brick the account). A worker
+    // booted headless during a reload starts WITHOUT the lease and refreshes
+    // nothing until it acquires the baton. Default true so the standalone /
+    // direct-listen (non-supervised, headless service) path is unchanged.
+    this.writerLease = true;
+  }
+
+  /**
+   * Acquire/release the single-writer baton. While released, ensureTokenFresh is
+   * a no-op (the worker serves on its existing access tokens but never rotates a
+   * single-use refresh token — that's the lease holder's job).
+   */
+  setWriterLease(held) {
+    this.writerLease = Boolean(held);
   }
 
   /**
@@ -556,7 +571,7 @@ export class AccountManager {
     console.log(`[Maxpool] Anthropic recovery probe failed; retrying in ${retryAfter}s (${reason})`);
   }
 
-  noteAmbiguousRateLimit(accountIndex, fingerprint, retryAfterSeconds) {
+  noteAmbiguousRateLimit(accountIndex, fingerprint, _retryAfterSeconds) {
     if (!fingerprint) return false;
     const now = Date.now();
     const windowMs = 30_000;
@@ -1717,6 +1732,12 @@ export class AccountManager {
     const account = this.accounts[accountIndex];
     if (!account || account.type !== 'oauth' || !account.refreshToken) return true;
 
+    // Single-writer baton: a worker without the lease NEVER rotates a single-use
+    // refresh token (doing so would invalidate the lease holder's token →
+    // invalid_grant → bricked account). It serves on its existing access token
+    // for the bounded drain; the lease holder owns all rotation.
+    if (!this.writerLease) return true;
+
     if (!force && !isTokenExpiringSoon(account.expiresAt)) return true;
 
     // Coalesce concurrent refreshes
@@ -1724,6 +1745,9 @@ export class AccountManager {
 
     account._refreshPromise = (async () => {
       console.log(`[Maxpool] Refreshing token for account "${account.name}"...`);
+      // Record the token we're rotating FROM so the persistence layer's
+      // generation guard can detect another writer having already advanced it.
+      account._refreshedFrom = account.refreshToken;
       try {
         const newTokens = await this._refreshAccessToken(account.refreshToken);
         account.credential = newTokens.accessToken;
@@ -1755,6 +1779,18 @@ export class AccountManager {
     return account._refreshPromise;
   }
 
+  /**
+   * Await every in-flight OAuth token refresh to settle. The single-writer baton
+   * uses this on RELEASE: a refresh that passed the `if(!writerLease) return` gate
+   * BEFORE the lease was dropped is still awaiting its OAuth POST; the new worker
+   * must not acquire the lease and rotate the SAME single-use token until these
+   * settle, or the upstream invalidates one token → invalid_grant → bricked.
+   */
+  async drainRefreshes() {
+    const pending = this.accounts.map(a => a._refreshPromise).filter(Boolean);
+    if (pending.length) await Promise.allSettled(pending);
+  }
+
   /**
    * Set a callback to persist refreshed tokens to config.
    */

package/src/config.js

@@ -171,28 +171,100 @@ export async function loadState() {
   }
 }
 
-export async function saveState(state) {
-  await atomicWrite(getStatePath(), JSON.stringify(state, null, 2) + '\n');
+/**
+ * Read just the `_generation` integer of an on-disk JSON file (config or state)
+ * without parsing it as a typed object. Returns 0 when the file is missing,
+ * unreadable, or carries no generation (legacy files), so a first write always
+ * advances to >=1. Never throws.
+ */
+export async function readGeneration(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf-8'));
+    const g = Number(parsed?._generation);
+    return Number.isFinite(g) && g > 0 ? g : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Generation-guarded state write (defense-in-depth single-writer enforcement).
+ *
+ * `state.quota` carries the learned quota. We stamp a monotonic `_generation`
+ * and refuse to clobber a file whose on-disk generation is NEWER than the one
+ * we last observed — that means another writer (a stale ex-lease worker) raced
+ * us, and overwriting would revert fresher quota. The baton sequencing already
+ * guarantees a single writer; this guard catches a sequencing bug.
+ *
+ * Pass `{ expectedGeneration }` to assert the on-disk file is still at the
+ * generation you read; omit it to read-then-bump unconditionally (single-owner
+ * fast path). Returns the generation written, or null when refused.
+ */
+let _stateWriteChain = Promise.resolve();
+
+export function saveState(state, { expectedGeneration = null } = {}) {
+  // Serialize state writes (a 60s interval flush can otherwise race the final
+  // baton flush, read the same on-disk generation, and double-write).
+  const run = async () => {
+    const path = getStatePath();
+    const onDisk = await readGeneration(path);
+    if (expectedGeneration != null && onDisk > expectedGeneration) {
+      // A newer writer advanced the file under us — refuse the stale flush.
+      return null;
+    }
+    const next = onDisk + 1;
+    await atomicWrite(path, JSON.stringify({ ...state, _generation: next }, null, 2) + '\n');
+    return next;
+  };
+  const result = _stateWriteChain.then(run, run);
+  _stateWriteChain = result.then(() => {}, () => {});
+  return result;
 }
 
+/** Barrier: resolves once every queued state write has settled. */
+export const flushStateWrites = () => _stateWriteChain;
+
 let _configWriteChain = Promise.resolve();
 
+/** Barrier: resolves once every queued config write (e.g. a fire-and-forget
+ *  token-refresh persist) has settled. Awaited on baton release so a rotated
+ *  token can't be left unwritten when the new worker boots from disk (M3). */
+export const flushConfigWrites = () => _configWriteChain;
+
 /**
  * Serialize an in-process read-modify-write of the config so concurrent updates
  * cannot lose each other's writes — e.g. a background OAuth token refresh
  * (fire-and-forget) racing a TUI account add/delete. Each update re-reads the
  * latest config, applies updater(config), then saves atomically.
  *
+ * Defense-in-depth single-writer guard: the config carries a monotonic
+ * `_generation`. If `guardGeneration` is supplied and the on-disk generation is
+ * already NEWER than it, the write is REFUSED (a stale ex-lease worker raced the
+ * current writer). The updater additionally receives the on-disk generation as
+ * `config._generation` so a refresh updater can SKIP a token rotation it sees a
+ * fresher writer already performed. The generation is bumped on every write.
+ *
  * NOTE: this serializes writes within THIS process only. A separate
  * `maxpool import`/`login` process writing concurrently is not coordinated
  * (that would require a lockfile) — but those are short, rare, human-driven.
  */
-export function atomicConfigUpdate(updater) {
+export function atomicConfigUpdate(updater, { guardGeneration = null } = {}) {
   const run = async () => {
     const config = await loadConfig() || createDefaultConfig();
-    await updater(config);
+    const onDisk = Number(config._generation) || 0;
+    if (guardGeneration != null && onDisk > guardGeneration) {
+      // Refuse: a newer writer already advanced the config. Surface the live
+      // config so the caller can reconcile, but write nothing.
+      const refused = new Error('config generation advanced; stale write refused');
+      refused.code = 'STALE_GENERATION';
+      refused.onDiskGeneration = onDisk;
+      refused.config = config;
+      throw refused;
+    }
+    const result = await updater(config);
+    config._generation = onDisk + 1;
     await saveConfig(config);
-    return config;
+    return result === undefined ? config : result;
   };
   // Run after any in-flight update regardless of whether it resolved or
   // rejected, so one failure doesn't poison the chain; the caller still sees

package/src/index.js

@@ -2,7 +2,7 @@
 
 import { spawn, spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { loadOrCreateConfig, loadConfig, saveConfig, atomicConfigUpdate, getConfigPath, loadState, saveState } from './config.js';
+import { loadOrCreateConfig, loadConfig, saveConfig, atomicConfigUpdate, getConfigPath, loadState, saveState, getStatePath, readGeneration, flushConfigWrites, flushStateWrites } from './config.js';
 import { AccountManager } from './account-manager.js';
 import { createProxyServer } from './server.js';
 import { Prober } from './prober.js';
@@ -11,11 +11,20 @@ import { TUI } from './tui.js';
 import { RestartController } from './restart-controller.js';
 import { resolveAccounts } from './account-config.js';
 import { maybeCheckForUpdate } from './updater.js';
+import {
+  runReloadBaton,
+  RELOAD_SWAPPED, RELOAD_ROLLED_BACK,
+  MSG_LISTEN, MSG_RELEASE, MSG_TAKEOVER, MSG_PROBE_READY,
+  MSG_RELOAD_REQUEST, MSG_READY, MSG_FAILED, MSG_RELEASED, MSG_PRIMARY,
+} from './reload-protocol.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
 const SERVER_RESTART_EXIT_CODE = 75;
 const SERVER_WORKER_ENV = 'MAXPOOL_SERVER_WORKER';
+// Set by the supervisor when it spawns a worker for a seamless reload: that
+// worker boots HEADLESS (plain logs, no writer lease) and waits for the baton.
+const SERVER_RELOAD_WORKER_ENV = 'MAXPOOL_RELOAD_WORKER';
 
 switch (command) {
   case 'server':
@@ -71,43 +80,329 @@ switch (command) {
 // ── server ──────────────────────────────────────────────────
 
 async function serverCommand() {
-  if (
-    process.env[SERVER_WORKER_ENV] === '1' ||
-    !process.stdout.isTTY ||
-    !process.stdin.isTTY
-  ) {
+  // A spawned worker (env flag set by the supervisor) runs the proxy itself.
+  if (process.env[SERVER_WORKER_ENV] === '1') {
     return serverWorkerCommand();
   }
 
-  // Keep a stable foreground process attached to the shell. The worker can
-  // then request a restart without orphaning its replacement or losing TTY IO.
-  const ignoreTerminalSignal = () => {};
-  process.on('SIGINT', ignoreTerminalSignal);
-  process.on('SIGTERM', ignoreTerminalSignal);
+  // Non-TTY (e.g. `maxpool server` as a background service): keep the existing
+  // tested direct-listen path. The seamless-reload feature is only active under
+  // the TTY supervisor; a service manager already handles restart/respawn.
+  // MAXPOOL_FORCE_SUPERVISOR=1 forces the supervisor path without a TTY (used by
+  // the reload integration tests; the worker still runs plain-log without a TTY).
+  const forceSupervisor = process.env.MAXPOOL_FORCE_SUPERVISOR === '1';
+  if (!forceSupervisor && (!process.stdout.isTTY || !process.stdin.isTTY)) {
+    return serverWorkerCommand();
+  }
+
+  return supervisorCommand();
+}
+
+// ── supervisor (TTY) ─────────────────────────────────────────
+//
+// Owns the listening socket for its whole life (never closes it) and hands the
+// socket HANDLE to exactly one worker at a time over IPC. A worker requests a
+// seamless reload; the supervisor spawns a fresh headless worker, runs the
+// single-writer baton, then swaps. Any failure falls back to the tested abrupt
+// exit-75 respawn. A crash-loop degrades to loud single-worker failure via an
+// exponential backoff, never a tight fork loop.
+
+async function supervisorCommand() {
+  const { createServer } = await import('node:net');
+  const config = await loadOrCreateConfig();
+  const port = config.proxy.port;
+  const host = config.proxy.host || '127.0.0.1';
+
+  // Bind once. EADDRINUSE / EACCES here is a cold-start failure → exit(1) is
+  // correct (there's no worker to keep alive yet).
+  let masterServer = createServer();
+  // We DROP any connection the supervisor accidentally accepts while a worker is
+  // also accepting on the shared handle — but the design avoids that: the
+  // supervisor's acceptor is only LIVE during the brief cutover gap (it stops
+  // once a worker confirms it is the sole acceptor). A bare handler is required
+  // so the rare gap-accepted socket isn't left dangling.
+  const relistenMaster = () => new Promise((resolve, reject) => {
+    if (masterServer.listening) { resolve(); return; }
+    const onErr = err => { masterServer.removeListener('listening', onListen); reject(err); };
+    const onListen = () => { masterServer.removeListener('error', onErr); resolve(); };
+    masterServer.once('error', onErr);
+    masterServer.once('listening', onListen);
+    masterServer.listen(port, host);
+  });
+  const closeMasterAccept = () => new Promise(resolve => {
+    if (!masterServer.listening) { resolve(); return; }
+    masterServer.close(() => resolve());
+  });
+  try {
+    await relistenMaster();
+  } catch (err) {
+    handleServerListenError(err, host, port);
+    return;
+  }
+
+  // Keep the supervisor attached to the shell. The worker shares the supervisor's
+  // process group, so a terminal Ctrl-C (SIGINT/SIGTERM) is delivered by the TTY
+  // to BOTH already — the supervisor must NOT forward those or the worker gets a
+  // doubled signal (the "second Ctrl-C force-quits" footgun). The supervisor
+  // ignores SIGINT/SIGTERM itself (the worker drains + exits, ending the turn).
+  let activeWorker = null;
+  const forwardSignal = sig => { try { activeWorker?.child.kill(sig); } catch { /* ignore */ } };
+  process.on('SIGINT', () => { /* delivered to the worker by the TTY group */ });
+  process.on('SIGTERM', () => { /* delivered to the worker by the TTY group */ });
+  // SIGHUP (from `kill -HUP <supervisor-pid>`) reaches ONLY the supervisor →
+  // forward it so the worker requests a seamless reload.
+  process.on('SIGHUP', () => forwardSignal('SIGHUP'));
+  // A spawn failure / stray rejection must NOT kill the supervisor (it would
+  // wedge the port and drop the service). Log and let the supervision loop or
+  // the reload's own error handling recover.
+  process.on('uncaughtException', err => {
+    console.error(`[Maxpool] Supervisor uncaughtException (continuing): ${err?.stack || err}`);
+  });
+  process.on('unhandledRejection', reason => {
+    console.error(`[Maxpool] Supervisor unhandledRejection (continuing): ${reason}`);
+  });
+
+  // After SIGKILLing a worker that may have owned the TUI, the worker had no
+  // chance to restore the terminal — the supervisor emits the restore itself
+  // (exit alt-screen + show cursor + raw off) so the user's shell is clean.
+  const restoreTerminalFromSupervisor = () => {
+    try {
+      if (process.stdout.isTTY) process.stdout.write('\x1b[?25h\x1b[?1049l');
+      if (process.stdin.isTTY) { try { process.stdin.setRawMode(false); } catch { /* ignore */ } }
+    } catch { /* never throw */ }
+  };
+  process.on('exit', restoreTerminalFromSupervisor);
+
+  // Crash-loop guard: count rapid consecutive non-restart exits and back off so
+  // a worker that crashes on boot doesn't spin the CPU forking. A clean run for
+  // a while resets the counter.
+  let crashCount = 0;
+  const CRASH_WINDOW_MS = 10_000;
+  const MAX_BACKOFF_MS = 8_000;
+
+  let reloadInFlight = false;
+  // Resolver for the CURRENT supervision turn. A swap re-points monitoring to
+  // the new worker WITHOUT ending the turn; only an exit/fallback resolves it.
+  let endTurn = null;
+
+  // Spawn a worker in the SAME process group as the supervisor. A terminal
+  // Ctrl-C (SIGINT/SIGTERM) is delivered by the TTY to the whole foreground
+  // group, so BOTH already receive it — the supervisor therefore does NOT
+  // forward those (that would double-deliver). Same-group also means a group
+  // SIGKILL of the supervisor reaps the worker (no orphan holding the port).
+  const spawnWorker = ({ reload = false } = {}) => {
+    const env = { ...process.env, [SERVER_WORKER_ENV]: '1' };
+    if (reload) env[SERVER_RELOAD_WORKER_ENV] = '1';
+    const child = spawn(process.execPath, process.argv.slice(1), {
+      cwd: process.cwd(),
+      env,
+      stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+    });
+    const worker = makeWorkerChannel(child);
+    if (!reload) {
+      // Cold start: hand the socket and tell it to go primary immediately.
+      worker.send({ type: MSG_LISTEN }, masterServer);
+    }
+    return worker;
+  };
+
+  // Wire a worker as the active primary: its RELOAD_REQUEST triggers the baton;
+  // its MSG_PRIMARY means it is now the sole acceptor (so the supervisor stops
+  // its own competing accept loop); its exit/spawn-error ends the turn.
+  const monitorAsActive = worker => {
+    activeWorker = worker;
+    worker.child.removeAllListeners('message');
+    worker.child.on('message', msg => {
+      if (msg?.type === MSG_RELOAD_REQUEST) orchestrateReload().catch(() => {});
+      else if (msg?.type === MSG_PRIMARY && activeWorker === worker) {
+        // The worker is now sole acceptor on the handle → stop the supervisor
+        // racing it for accepts (the steady-state ~78%-hang bug). The supervisor
+        // still HOLDS the socket via the worker's fd; it re-arms only at reload.
+        closeMasterAccept().catch(() => {});
+      }
+    });
+    worker.child.once('exit', (code, signal) => {
+      // Only the worker that is STILL active when it exits ends the turn. A
+      // reaped old worker (already swapped out) exiting must be ignored here.
+      if (activeWorker === worker) endTurn?.({ code, signal });
+    });
+    // A spawn-time failure (EMFILE/EAGAIN under load) surfaces as 'error', not
+    // 'exit' — treat it as a crashed turn so backoff handles it (M5).
+    worker.child.once('error', err => {
+      if (activeWorker === worker) endTurn?.({ code: 1, signal: null, spawnError: err.message });
+    });
+  };
+
+  // Reload orchestration: spawn a fresh headless worker, run the baton, swap.
+  const orchestrateReload = async () => {
+    if (reloadInFlight) return;
+    reloadInFlight = true;
+    const oldWorker = activeWorker;
+    let newWorker = null;
+    try {
+      newWorker = spawnWorker({ reload: true });
+      // Hold the new worker's spawn-error so a fork failure mid-baton becomes a
+      // clean ROLLED_BACK/FALLBACK instead of crashing the supervisor (M5).
+      newWorker.child.once('error', () => { /* surfaced via waitFor reject */ });
+      const outcome = await runReloadBaton({
+        oldWorker,
+        newWorker,
+        handle: masterServer,
+        // After the OLD worker has released its fd, re-arm the supervisor's own
+        // listener to cover the cutover gap, then hand THAT live handle to the
+        // new worker. The new worker's MSG_PRIMARY then closes it again.
+        prepareHandle: async () => { await relistenMaster(); return masterServer; },
+        log: msg => console.log(`[Maxpool] ${msg}`),
+      });
+
+      if (outcome === RELOAD_SWAPPED) {
+        // Re-point monitoring to the new worker (it's now primary), THEN reap the
+        // old one. Order matters: monitorAsActive sets activeWorker=new so the
+        // old worker's pending exit handler no-ops. monitorAsActive also handles
+        // the new worker's already-sent MSG_PRIMARY is moot here — the new worker
+        // sent PRIMARY during the baton; re-assert the master-accept close.
+        monitorAsActive(newWorker);
+        closeMasterAccept().catch(() => {});
+        reapOldWorker(oldWorker, config);
+        return;
+      }
+
+      if (outcome === RELOAD_ROLLED_BACK) {
+        // Old worker never released — it's still fully primary. Kill the new
+        // headless worker; nothing else changed. ZERO disruption.
+        try { newWorker.child.kill('SIGKILL'); } catch { /* ignore */ }
+        return;
+      }
+
+      // FALLBACK: the old worker may have released; neither is reliably primary.
+      // Kill both and let the respawn loop bring a fresh primary up on the
+      // supervisor-owned socket. Queued conns sit in the OS backlog meanwhile.
+      try { newWorker.child.kill('SIGKILL'); } catch { /* ignore */ }
+      try { oldWorker.child.kill('SIGKILL'); } catch { /* ignore */ }
+      restoreTerminalFromSupervisor(); // SIGKILLed workers can't restore the TUI
+      activeWorker = null;
+      endTurn?.({ code: null, signal: 'SIGKILL', fallback: true });
+    } catch (err) {
+      console.error(`[Maxpool] Reload error: ${err.message}; falling back to abrupt restart`);
+      try { newWorker?.child.kill('SIGKILL'); } catch { /* ignore */ }
+      try { oldWorker.child.kill('SIGKILL'); } catch { /* ignore */ }
+      restoreTerminalFromSupervisor();
+      activeWorker = null;
+      endTurn?.({ code: null, signal: 'SIGKILL', fallback: true });
+    } finally {
+      reloadInFlight = false;
+    }
+  };
+
+  // One supervision turn: monitor `worker` until it exits (or a fallback forces a
+  // respawn). Swaps re-point monitoring without resolving. Resolves exit info.
+  const superviseTurn = worker => new Promise(resolve => {
+    endTurn = info => { endTurn = null; resolve(info); };
+    monitorAsActive(worker);
+  });
+
   try {
     while (true) {
-      const result = await runServerWorker();
-      if (result.code === SERVER_RESTART_EXIT_CODE) continue;
+      const worker = spawnWorker({ reload: false });
+      const startedAt = Date.now();
+      const result = await superviseTurn(worker);
+
+      if (result.fallback) {
+        // Fallback swap killed both workers; bring a fresh primary straight back.
+        crashCount = 0;
+        continue;
+      }
+      if (result.code === SERVER_RESTART_EXIT_CODE) {
+        // Abrupt self-restart (worker-initiated exit-75 fallback path).
+        crashCount = 0;
+        continue;
+      }
+
+      // Non-restart exit. If it died fast, it's likely crash-looping on boot.
+      const ranFor = Date.now() - startedAt;
+      if (ranFor < CRASH_WINDOW_MS && (result.code ?? 1) !== 0) {
+        crashCount++;
+        const backoff = Math.min(MAX_BACKOFF_MS, 250 * 2 ** (crashCount - 1));
+        console.error(`[Maxpool] Worker exited (code ${result.code}, signal ${result.signal}) after ${ranFor}ms — crash #${crashCount}. Backing off ${backoff}ms before respawn.`);
+        await delay(backoff);
+        continue;
+      }
+
+      // Clean shutdown (q / signal). Propagate the exit code and stop.
       if (result.signal) process.exitCode = 1;
       else process.exitCode = result.code ?? 1;
       return;
     }
   } finally {
-    process.off('SIGINT', ignoreTerminalSignal);
-    process.off('SIGTERM', ignoreTerminalSignal);
+    try { masterServer.close(); } catch { /* ignore */ }
   }
 }
 
-function runServerWorker() {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, process.argv.slice(1), {
-      cwd: process.cwd(),
-      env: { ...process.env, [SERVER_WORKER_ENV]: '1' },
-      stdio: 'inherit',
-    });
-    child.once('error', reject);
-    child.once('exit', (code, signal) => resolve({ code, signal }));
-  });
+// Drain + reap a released worker. The worker exits itself once its bounded
+// in-flight finishes; the supervisor SIGKILLs it if it outlives the drain cap.
+function reapOldWorker(worker, config) {
+  if (!worker) return;
+  const drainTimeoutMs = Math.max(1000, Number(config.shutdown?.drainTimeoutMs) || 15_000);
+  let reaped = false;
+  const finish = () => { if (reaped) return; reaped = true; clearTimeout(timer); };
+  const timer = setTimeout(() => {
+    if (reaped) return;
+    console.error(`[Maxpool] Old worker outlived ${Math.ceil(drainTimeoutMs / 1000)}s drain cap; SIGKILL.`);
+    try { worker.child.kill('SIGKILL'); } catch { /* ignore */ }
+    finish();
+  }, drainTimeoutMs);
+  timer.unref?.();
+  worker.child.once('exit', finish);
+}
+
+/**
+ * Wrap a child process in a small IPC channel: `.send(msg[,handle])` and an
+ * async `.waitFor([types], timeoutMs)` that resolves with the first matching
+ * message, or rejects on timeout / premature child exit.
+ */
+function makeWorkerChannel(child) {
+  return {
+    child,
+    send(msg, handle) {
+      try {
+        if (handle) child.send(msg, handle);
+        else child.send(msg);
+      } catch { /* IPC may be torn down mid-swap; baton timeouts cover it */ }
+    },
+    waitFor(types, timeoutMs) {
+      const want = Array.isArray(types) ? types : [types];
+      return new Promise((resolve, reject) => {
+        const cleanup = () => {
+          clearTimeout(timer);
+          child.removeListener('message', onMsg);
+          child.removeListener('exit', onExit);
+          child.removeListener('error', onError);
+        };
+        const onMsg = msg => {
+          if (msg && want.includes(msg.type)) { cleanup(); resolve(msg); }
+        };
+        const onExit = (code, signal) => {
+          cleanup();
+          reject(new Error(`worker exited (code ${code}, signal ${signal}) before ${want.join('/')}`));
+        };
+        // A spawn failure (EMFILE/EAGAIN) surfaces as 'error', not 'exit' — the
+        // baton must see it as a failed step (→ ROLLED_BACK/FALLBACK), not hang.
+        const onError = err => { cleanup(); reject(new Error(`worker spawn error before ${want.join('/')}: ${err.message}`)); };
+        const timer = setTimeout(() => {
+          cleanup();
+          reject(new Error(`timed out waiting for ${want.join('/')}`));
+        }, timeoutMs);
+        timer.unref?.();
+        child.on('message', onMsg);
+        child.once('exit', onExit);
+        child.once('error', onError);
+      });
+    },
+  };
+}
+
+function delay(ms) {
+  return new Promise(resolve => { const t = setTimeout(resolve, ms); t.unref?.(); });
 }
 
 async function serverWorkerCommand() {
@@ -138,23 +433,67 @@ async function serverWorkerCommand() {
     config.routing?.preferredAccount,
   );
 
+  // Supervised = spawned by the TTY supervisor over IPC (handle-based listen +
+  // baton). A reload worker boots HEADLESS without the writer lease and waits
+  // for the baton; a cold-start worker takes the lease on MSG_LISTEN.
+  const supervised = typeof process.send === 'function';
+  const isReloadWorker = process.env[SERVER_RELOAD_WORKER_ENV] === '1';
+
+  // M6: a reload worker boots WITHOUT the writer lease so the AM-level brick
+  // guard (ensureTokenFresh no-op) is CLOSED for the entire headless window —
+  // before any code path could trigger a refresh. acquireLease() flips it true
+  // at takeover. (writerLease defaults true for the standalone/direct path.)
+  if (isReloadWorker) accountManager.setWriterLease(false);
+
   // Restore quota observed in a previous run so a restart doesn't lose routing
   // accuracy and re-probe from scratch. Stale windows clear on first use.
+  // A reload worker restores quota IN-MEMORY only (state file handed via the
+  // lease holder); a cold/direct worker reads the on-disk state file.
   const savedState = await loadState();
   if (savedState?.quota) accountManager.restoreQuotaState(savedState.quota);
-  const persistQuotaState = () =>
-    saveState({ quota: accountManager.exportQuotaState() }).catch(() => {});
+  // Track the state-file generation we last observed so a stale flush is refused.
+  let stateGeneration = Number(savedState?._generation) || 0;
+
+  // ── single-writer baton: refresh / probe / persistence gated by the lease ──
+  // A worker without the lease writes NOTHING (no token rotation, no config
+  // write, no state write, no probe). Only the lease holder may write.
+  let hasLease = false;
+  // `force` performs the FINAL flush during a baton release, AFTER releaseLease()
+  // has already flipped hasLease=false (and cleared the periodic interval, so no
+  // write races this one). Without force, this no-ops post-release and the reload's
+  // learned-quota flush is silently dropped — the new worker would boot from up-to-
+  // 60s-stale quota and the state generation would never advance across a reload.
+  const persistQuotaState = (force = false) => {
+    if (!hasLease && !force) return Promise.resolve();
+    // The forced final flush (baton release / shutdown) is the SOLE writer at that
+    // point — releaseLease() already cleared the periodic interval and the next
+    // worker hasn't acquired the lease yet — so it bypasses the cross-worker
+    // stale-generation guard. Without this, a 60s-interval write that fired just
+    // before releaseLease could bump the on-disk generation and get the forced
+    // flush REFUSED (dropping the final quota snapshot). The guard only exists to
+    // serialize CROSS-worker writes; the final flush is provably intra-worker.
+    const expectedGeneration = force ? null : stateGeneration;
+    return saveState({ quota: accountManager.exportQuotaState() }, { expectedGeneration })
+      .then(written => { if (written != null) stateGeneration = written; })
+      .catch(() => {});
+  };
   // Persist quota every minute; unref so it never keeps the process alive.
-  const quotaSaveInterval = setInterval(persistQuotaState, 60_000);
-  quotaSaveInterval.unref?.();
+  let quotaSaveInterval = null;
 
   // Opt-in background quota probe (config.quotaProbeSeconds, default 0 = off).
   const prober = new Prober(accountManager, { intervalMs: (config.quotaProbeSeconds || 0) * 1000 });
-  prober.start();
 
-  // Persist refreshed tokens back to config (re-read from disk to avoid clobbering
-  // accounts added externally, e.g. by `maxpool import` while server is running)
-  accountManager.onTokenRefresh((idx, newTokens) => {
+  // Persist refreshed tokens back to config. Defense-in-depth: the updater reads
+  // the on-disk refresh token and SKIPS the rotation if a fresher writer already
+  // advanced it (generation guard), so a stale write can't double-spend a token.
+  //
+  // We do NOT gate this on `hasLease`: a refresh that already STARTED (it passed
+  // the lease gate in ensureTokenFresh) MUST persist its rotated single-use token
+  // even if the lease was dropped while its POST was in flight — otherwise the
+  // baton hands off and the new worker boots from the now-invalidated on-disk
+  // token (B1/M3). New refreshes can't start without the lease (ensureTokenFresh
+  // no-ops), so every callback here is from a legitimate lease-era refresh.
+  const persistTokenRefresh = (idx, newTokens) => {
     const account = accountManager.accounts[idx];
     if (!account) return;
     // Keep config.accounts in sync so TUI saveConfig doesn't clobber fresh tokens
@@ -178,21 +517,58 @@ async function serverWorkerCommand() {
       // Match by UUID first, then by name — index may have shifted
       const cfgIdx = findConfigAccount(diskConfig, account);
       if (cfgIdx >= 0) {
-        diskConfig.accounts[cfgIdx].accessToken = newTokens.accessToken;
-        diskConfig.accounts[cfgIdx].refreshToken = newTokens.refreshToken;
-        diskConfig.accounts[cfgIdx].expiresAt = newTokens.expiresAt;
+        const onDisk = diskConfig.accounts[cfgIdx];
+        // Generation guard: if the on-disk refresh token already advanced past
+        // the token we rotated FROM, another writer beat us — skip the write so
+        // we don't revert a fresher single-use token (the brick-the-account case).
+        if (onDisk.refreshToken && onDisk.refreshToken !== account._refreshedFrom &&
+            onDisk.refreshToken !== newTokens.refreshToken) {
+          return;
+        }
+        onDisk.accessToken = newTokens.accessToken;
+        onDisk.refreshToken = newTokens.refreshToken;
+        onDisk.expiresAt = newTokens.expiresAt;
       }
-    }).catch(err => console.error(`[Maxpool] Failed to save refreshed token: ${err.message}`));
-  });
+    }).catch(err => {
+      if (err?.code === 'STALE_GENERATION') return; // another writer advanced; benign
+      console.error(`[Maxpool] Failed to save refreshed token: ${err.message}`);
+    });
+  };
+  accountManager.onTokenRefresh(persistTokenRefresh);
+
   const port = config.proxy.port;
   const host = config.proxy.host || '127.0.0.1';
-  const useTUI = process.stdout.isTTY && process.stdin.isTTY;
+  // A headless reload worker NEVER drives the TUI (single-owner terminal); it
+  // takes the TUI only on baton takeover. Cold/direct workers use it if on a TTY.
+  const useTUI = process.stdout.isTTY && process.stdin.isTTY && !isReloadWorker;
 
   let tui = null;
   let server = null;
   let syncTimer = null;
   let draining = false;
   let restartController = null;
+
+  // Best-effort terminal restore on ANY abnormal exit path (uncaughtException,
+  // a bare process.exit, a crash) so the user's shell is never left in raw mode
+  // or the alt-screen. Idempotent and safe even when no TUI was running.
+  const restoreTerminal = () => {
+    try {
+      if (tui?.running) { tui.stop(); return; }
+      if (process.stdout.isTTY) process.stdout.write('\x1b[?25h\x1b[?1049l');
+      if (process.stdin.isTTY) { try { process.stdin.setRawMode(false); } catch { /* ignore */ } }
+    } catch { /* never throw from a restore */ }
+  };
+  process.on('exit', restoreTerminal);
+  process.on('uncaughtException', err => {
+    console.error(`[Maxpool] Worker uncaughtException: ${err?.stack || err}`);
+    restoreTerminal();
+    // A reload worker must NEVER exit(1) (escapes the supervisor exit-75 loop).
+    // Stay alive so the supervisor's baton timeouts roll us back cleanly.
+    if (!isReloadWorker) process.exit(SERVER_RESTART_EXIT_CODE);
+  });
+  process.on('unhandledRejection', reason => {
+    console.error(`[Maxpool] Worker unhandledRejection: ${reason}`);
+  });
   // Quit drains in-flight requests, then force-exits. Kept short so a single
   // 'q' / Ctrl-C / SIGTERM actually quits under a continuous request flood
   // (where there are always active requests) instead of waiting indefinitely.
@@ -214,22 +590,74 @@ async function serverWorkerCommand() {
     },
   };
 
+  // ── writer lease (single-writer baton) ──
+  // Acquiring the lease turns ON token rotation, the quota-save interval, and the
+  // prober. Releasing turns them all OFF and flushes once. Exactly one worker
+  // holds the lease at a time — enforced by the supervisor's baton sequencing.
+  const acquireLease = async () => {
+    if (hasLease) return;
+    // M4: re-read the on-disk state generation NOW. A reload's old worker bumped
+    // it during its final flush; without this re-sync the new primary's
+    // saveState(expectedGeneration=<boot N>) would be refused for its whole
+    // tenure (quota persistence wedged forever). As sole writer it safely adopts
+    // the current on-disk generation.
+    try { stateGeneration = await readGeneration(getStatePath()); } catch { /* keep prior */ }
+    hasLease = true;
+    accountManager.setWriterLease(true);
+    if (!quotaSaveInterval) {
+      quotaSaveInterval = setInterval(() => { persistQuotaState(); }, 60_000);
+      quotaSaveInterval.unref?.();
+    }
+    prober.start();
+  };
+  // Stop scheduling writes and flip the lease. Returns a promise that settles
+  // once any in-flight prober cycle has finished (so no probe-driven token
+  // rotation is still pending). Token-refresh draining is awaited separately in
+  // the baton release (drainRefreshes) before the lease is handed off.
+  const releaseLease = async () => {
+    if (!hasLease) return;
+    hasLease = false;
+    if (quotaSaveInterval) { clearInterval(quotaSaveInterval); quotaSaveInterval = null; }
+    accountManager.setWriterLease(false);
+    await prober.stop(); // awaits any in-flight probe cycle (B1)
+  };
+
+  // Abrupt self-restart — the tested fallback path. Cuts in-flight connections;
+  // clients retry ~2s. Used when NOT supervised, or when a seamless reload can't
+  // be requested. NEVER exit(1) here (that escapes the exit-75 supervisor loop).
   const restartWorkerNow = () => {
     if (draining) return;
     draining = true;
     if (syncTimer) clearInterval(syncTimer);
-    clearInterval(quotaSaveInterval);
-    persistQuotaState(); // flush learned quota so the restart restores it
-    prober.stop();
-    if (tui?.running) tui.stop();
+    if (tui?.running) { tui.stop(); }
     console.log('\n[Maxpool] Restarting server now; queued requests will reconnect automatically.');
     server.closeAllConnections?.();
-    process.exit(SERVER_RESTART_EXIT_CODE);
+    // Best-effort: flush quota + settle in-flight refreshes/prober before exit so
+    // the respawned worker doesn't boot from a half-written state. Bounded so the
+    // abrupt path stays fast even if a write hangs.
+    Promise.race([
+      (async () => { await persistQuotaState(); await releaseLease(); await flushConfigWrites(); await flushStateWrites(); })(),
+      delay(2000),
+    ]).finally(() => process.exit(SERVER_RESTART_EXIT_CODE));
+  };
+
+  // Seamless reload entry point. When supervised, ask the supervisor to run the
+  // baton (spawn new worker, hand off socket + lease). If anything is off
+  // (not supervised, no IPC), fall back to the abrupt restart.
+  const requestReload = () => {
+    if (draining) return;
+    if (supervised) {
+      try {
+        process.send({ type: MSG_RELOAD_REQUEST });
+        return;
+      } catch { /* IPC gone — fall through to abrupt restart */ }
+    }
+    restartWorkerNow();
   };
 
   restartController = new RestartController({
     pauseAdmission: () => accountManager.setAdmissionPaused(true),
-    restartNow: restartWorkerNow,
+    restartNow: requestReload,
   });
 
   const shutdownGracefully = (reason, options = {}) => {
@@ -240,10 +668,16 @@ async function serverWorkerCommand() {
 
     draining = true;
     if (syncTimer) clearInterval(syncTimer);
-    clearInterval(quotaSaveInterval);
-    persistQuotaState(); // best-effort final flush of learned quota
-    prober.stop();
     if (tui?.running) tui.stop();
+    // Best-effort final flush + settle writes (fire-and-forget; the drain timeout
+    // below bounds total quit time, and write barriers protect the on-disk state).
+    (async () => {
+      await releaseLease();
+      await accountManager.drainRefreshes();
+      await persistQuotaState(true); // force: lease already dropped above (else no-op)
+      await flushConfigWrites();
+      await flushStateWrites();
+    })().catch(() => {});
 
     console.log(`\n[Maxpool] Draining shutdown (${reason}).`);
     console.log(`[Maxpool] Stopped accepting new requests; waiting up to ${Math.ceil(drainTimeoutMs / 1000)}s for ${restartController.activeRequests.size} active request(s), then forcing exit. Press Ctrl-C again to force now.`);
@@ -345,12 +779,12 @@ async function serverWorkerCommand() {
     }
   }, syncIntervalMs);
   syncTimer.unref();
-  const onListenError = err => handleServerListenError(err, host, port);
-  server.once('error', onListenError);
 
-  server.listen(port, host, () => {
-    server.removeListener('error', onListenError);
-    server.on('error', err => console.error(`[Maxpool] Server error: ${err.message}`));
+  // Become the live primary: start serving UI/logs, take the writer lease, run
+  // the update check. `viaTakeover` true means we acquired the socket through the
+  // baton (a reload) — freeze the update check so a reload doesn't re-probe npm
+  // (only a cold supervisor start self-updates).
+  const becomePrimary = async ({ viaTakeover }) => {
     if (tui) {
       if (tui.start()) {
         console.log(`Listening on ${host}:${port} with ${accounts.length} account(s)`);
@@ -361,15 +795,150 @@ async function serverWorkerCommand() {
     } else {
       logPlainServerStart({ host, port, accounts, threshold, config });
     }
+    // On a reload TAKEOVER, adopt the latest tokens from disk. The headless
+    // reload worker loaded config at spawn time; the OLD worker may have rotated
+    // a single-use refresh token DURING the handoff (and flushed it before
+    // MSG_RELEASED). Without this re-sync the new worker would present the now-
+    // invalidated token on its first refresh → invalid_grant → bricked account.
+    if (viaTakeover) {
+      try {
+        const diskConfig = await loadConfig();
+        if (diskConfig) await syncAccountsFromDisk(diskConfig, config, accountManager);
+      } catch (err) {
+        console.error(`[Maxpool] Token re-sync at takeover failed: ${err.message}`);
+      }
+    }
 
-    // Non-blocking update check. Notifies (or self-updates if config.autoUpdate);
-    // never interrupts the running proxy. Failures are swallowed.
-    const notify = msg => (tui?._addLog ? tui._addLog(msg) : console.log(`[Maxpool] ${msg}`));
-    maybeCheckForUpdate(config, notify).catch(() => {});
-  });
+    // Acquire the lease (re-syncs state generation + enables writes) BEFORE we
+    // announce primacy, so the moment the supervisor reaps the old worker we are
+    // a fully-functional sole writer.
+    await acquireLease();
+
+    // Tell the supervisor we are the sole acceptor now → it stops its own accept
+    // loop (the steady-state race fix). Cold start AND takeover both signal this.
+    if (supervised) { try { process.send({ type: MSG_PRIMARY }); } catch { /* ignore */ } }
+
+    // Reload-storm guard: only a cold (non-reload) lease holder probes npm.
+    // A reload-spawned/takeover worker must NEVER re-probe (1x not 2x traffic).
+    if (!viaTakeover && !isReloadWorker) {
+      if (process.env.MAXPOOL_TEST_LOG_UPDATE_CHECK === '1') console.log('[Maxpool] UPDATE_CHECK_FIRED');
+      const notify = msg => (tui?._addLog ? tui._addLog(msg) : console.log(`[Maxpool] ${msg}`));
+      maybeCheckForUpdate(config, notify).catch(() => {});
+    } else if (process.env.MAXPOOL_TEST_LOG_UPDATE_CHECK === '1') {
+      console.log('[Maxpool] UPDATE_CHECK_SKIPPED (reload)');
+    }
+  };
+
+  // ── start accepting ──
+  if (supervised) {
+    // Supervised: NEVER listen(port) directly — the supervisor owns the socket.
+    // Wait for the baton over IPC. A cold worker gets MSG_LISTEN; a reload worker
+    // boots headless (already done above) and waits for MSG_PROBE_READY/TAKEOVER.
+    server.on('error', err => console.error(`[Maxpool] Server error: ${err.message}`));
+
+    const listenOnHandle = handle => new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(handle, () => { server.removeListener('error', reject); resolve(); });
+    });
+
+    // Baton release: the old primary gives up acceptance + the writer lease.
+    // MSG_RELEASED MUST mean "no write is in flight" — not merely "flag flipped"
+    // — so the new worker can acquire the lease and rotate the single-use refresh
+    // token WITHOUT racing a still-pending rotation here (B1) and boots from a
+    // config that already has any rotated token persisted (M3).
+    const releaseBatonAndDrain = async () => {
+      if (draining) { try { process.send({ type: MSG_RELEASED }); } catch { /* ignore */ } return; }
+      draining = true;
+      if (syncTimer) clearInterval(syncTimer);
+      // Stop accepting NEW connections; KEEP in-flight requests alive.
+      server.maxpoolBeginDrain?.();
+      server.close(() => {});
+      server.closeIdleConnections?.(); // retire idle keep-alive sockets now
+
+      // 1) Stop scheduling writes + flip the lease + await any in-flight prober
+      //    cycle (releaseLease awaits prober.stop()).
+      await releaseLease();
+      // 2) Await every in-flight OAuth token refresh that started before the lease
+      //    dropped — the headline brick hazard (B1).
+      await accountManager.drainRefreshes();
+      // 3) Final flush of learned quota. FORCE it: releaseLease() above already
+      //    flipped hasLease=false, and persistQuotaState no-ops without the lease —
+      //    so an unforced call here silently drops the reload's final quota flush.
+      await persistQuotaState(true);
+      // 4) Barrier: ensure every queued config write (a rotated-token persist is
+      //    fire-and-forget) AND state write has actually hit disk before we hand
+      //    off (M3 — otherwise the new worker boots from the invalidated token).
+      await flushConfigWrites();
+      await flushStateWrites();
+
+      if (tui?.running) tui.stop(); // restore terminal before the new worker takes it
+      try { process.send({ type: MSG_RELEASED }); } catch { /* ignore */ }
+
+      // Drain bounded in-flight on EXISTING access tokens (no refresh needed),
+      // then exit(0). The supervisor SIGKILLs us if we outlive its drain cap.
+      const waitForDrain = () => {
+        if (restartController.activeRequests.size === 0) { process.exit(0); return; }
+      };
+      const drainPoll = setInterval(waitForDrain, 200);
+      drainPoll.unref?.();
+      const hardCap = setTimeout(() => {
+        console.error(`[Maxpool] Released worker drain cap reached with ${restartController.activeRequests.size} active; exiting.`);
+        process.exit(0);
+      }, drainTimeoutMs);
+      hardCap.unref?.();
+      waitForDrain();
+    };
+
+    process.on('message', async (msg, handle) => {
+      try {
+        if (msg?.type === MSG_LISTEN && handle) {
+          // Cold start: take the socket and go primary immediately.
+          await listenOnHandle(handle);
+          await becomePrimary({ viaTakeover: false });
+        } else if (msg?.type === MSG_PROBE_READY) {
+          // Headless reload worker: we've booted the new code and restored quota
+          // in memory. Confirm readiness (we are NOT yet accepting / writing).
+          // Test hook: simulate a new-version that fails to boot → forces the
+          // supervisor's rollback (old worker stays primary, zero disruption).
+          if (process.env.MAXPOOL_TEST_FAIL_RELOAD_WORKER === '1') {
+            process.send({ type: MSG_FAILED, reason: 'test-forced failure' });
+          } else {
+            process.send({ type: MSG_READY });
+          }
+        } else if (msg?.type === MSG_TAKEOVER && handle) {
+          // Baton acquire: the old worker already released, so we're the SOLE
+          // acceptor. Start accepting + take the writer lease + TUI. becomePrimary
+          // sends MSG_PRIMARY (the baton waits on it).
+          await listenOnHandle(handle);
+          await becomePrimary({ viaTakeover: true });
+        } else if (msg?.type === MSG_RELEASE) {
+          // Baton release: stop accepting NEW (keep in-flight), retire keep-alive
+          // sockets with Connection: close, stop writing, flush once, drop TUI.
+          await releaseBatonAndDrain();
+        }
+      } catch (err) {
+        // A failed reload worker must NOT exit(1) (kills the supervisor loop).
+        // Report failure so the supervisor rolls back; stay alive harmlessly.
+        console.error(`[Maxpool] Reload worker error: ${err.message}`);
+        try { process.send({ type: MSG_FAILED, reason: err.message }); } catch { /* ignore */ }
+      }
+    });
+  } else {
+    // Direct (non-TTY service) path: bind the port ourselves, exactly as before.
+    const onListenError = err => handleServerListenError(err, host, port);
+    server.once('error', onListenError);
+    server.listen(port, host, () => {
+      server.removeListener('error', onListenError);
+      server.on('error', err => console.error(`[Maxpool] Server error: ${err.message}`));
+      becomePrimary({ viaTakeover: false }).catch(err => console.error(`[Maxpool] ${err.message}`));
+    });
+  }
 
   process.on('SIGINT', () => shutdownGracefully('SIGINT'));
   process.on('SIGTERM', () => shutdownGracefully('SIGTERM'));
+  // SIGHUP requests a seamless reload (the conventional "reload" signal). Under
+  // the supervisor this runs the baton; otherwise it falls back to exit-75.
+  process.on('SIGHUP', () => requestReload());
 }
 
 function logPlainServerStart({ host, port, accounts, threshold, config }) {
@@ -607,7 +1176,7 @@ async function accountsCommand() {
       a.refreshToken = newTokens.refreshToken;
       a.expiresAt = newTokens.expiresAt;
       configDirty = true;
-    } catch (err) {
+    } catch {
       // refresh failed — fetchProfile will report the specific error
     }
   }));

package/src/oauth.js

@@ -4,7 +4,10 @@ import { createInterface } from 'node:readline';
 import http from 'node:http';
 
 const PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
-const DEFAULT_TOKEN_ENDPOINT = 'https://platform.claude.com/v1/oauth/token';
+// Token endpoint is overridable via env so a stub OAuth server can be pointed at
+// for integration tests (e.g. the single-use-rotating-token reload torture test).
+const DEFAULT_TOKEN_ENDPOINT = process.env.MAXPOOL_OAUTH_TOKEN_ENDPOINT
+  || 'https://platform.claude.com/v1/oauth/token';
 const DEFAULT_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 
 /**

package/src/prober.js

@@ -40,20 +40,29 @@ export class Prober {
     }
   }
 
-  stop() {
+  /** Stop scheduling AND await any probe cycle already in flight, so a caller
+   *  (the baton release) can be sure no probe-driven token rotation is pending
+   *  before it hands the writer lease to another worker. */
+  async stop() {
     if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    if (this._inflight) { try { await this._inflight; } catch { /* swallow */ } }
   }
 
-  /** Probe every OAuth account once. Overlapping cycles are skipped. */
-  async probeAll() {
-    if (this._running) return;
+  /** Probe every OAuth account once. Overlapping cycles are skipped. The active
+   *  cycle is tracked on `_inflight` so stop() can await it. */
+  probeAll() {
+    if (this._running) return this._inflight || Promise.resolve();
     this._running = true;
-    try {
-      const accounts = this.am.accounts.filter(a => a.type === 'oauth' && a.credential);
-      await Promise.all(accounts.map(a => this.probeOne(a)));
-    } finally {
-      this._running = false;
-    }
+    this._inflight = (async () => {
+      try {
+        const accounts = this.am.accounts.filter(a => a.type === 'oauth' && a.credential);
+        await Promise.all(accounts.map(a => this.probeOne(a)));
+      } finally {
+        this._running = false;
+        this._inflight = null;
+      }
+    })();
+    return this._inflight;
   }
 
   async probeOne(account) {

package/src/reload-protocol.js

@@ -0,0 +1,121 @@
+// IPC message vocabulary + the supervisor-side baton orchestration for the
+// near-zero-downtime reload (issue #6). Pure logic, no process side-effects, so
+// the baton sequence is unit-testable against fake workers.
+//
+// Roles:
+//   Supervisor — owns the listening socket for life, never closes it, spawns
+//     workers and hands the socket HANDLE to exactly one acceptor at a time.
+//   Worker     — accepts on the shared handle; exactly one worker holds the
+//     WRITER LEASE (refresh/probe/persist) at any instant.
+//
+// The baton (single-writer guarantee): old worker RELEASES (stops accepting +
+// stops writing, flushes once) BEFORE the new worker ACQUIRES. Reads overlap;
+// writes never do.
+
+// Supervisor → worker
+export const MSG_LISTEN = 'listen';       // (with handle) accept on this socket + take TUI/lease
+export const MSG_RELEASE = 'release';     // stop accepting, stop writing, flush, give up TUI
+export const MSG_TAKEOVER = 'takeover';   // (with handle) start accepting + acquire writer lease + TUI
+export const MSG_PROBE_READY = 'probe-ready'; // ask a headless worker to confirm it booted OK
+
+// Worker → supervisor
+export const MSG_RELOAD_REQUEST = 'reload-request'; // primary worker asks for a seamless reload
+export const MSG_READY = 'ready';         // headless worker booted new code successfully
+export const MSG_FAILED = 'failed';       // worker failed to boot/bind/restore
+export const MSG_RELEASED = 'released';   // old worker stopped accepting + writing, flushed
+export const MSG_PRIMARY = 'primary';     // new worker is now sole acceptor + lease holder
+export const MSG_QUOTA_STATE = 'quota-state'; // old worker hands its in-memory quota to supervisor
+
+/**
+ * Outcome codes for a reload attempt, surfaced to the supervisor so it can log
+ * and decide fallback. SWAPPED = fully cut over; ROLLED_BACK = old worker stays
+ * primary (no disruption); FALLBACK = abrupt exit-75 restart path taken.
+ */
+export const RELOAD_SWAPPED = 'swapped';
+export const RELOAD_ROLLED_BACK = 'rolled-back';
+export const RELOAD_FALLBACK = 'fallback';
+
+/**
+ * Drive the baton handshake over two worker "channels" (anything with
+ * .send(msg[,handle]) and an async waitFor(type, timeoutMs) that resolves with
+ * the message payload or rejects on timeout/exit). Returns one of the RELOAD_*
+ * outcomes. The caller (supervisor) owns spawning, killing, reaping and the
+ * actual fallback restart; this function only sequences the protocol and tells
+ * the caller what happened.
+ *
+ * Sequence (matches design step 2a–2e):
+ *   a. new worker already spawned headless (no lease); we ask it to confirm READY
+ *   b. READY fails  → ROLLED_BACK: caller kills new, old stays primary
+ *   c. old RELEASE  → waits RELEASED (old stopped accepting + writing, flushed)
+ *   d. new TAKEOVER → waits PRIMARY (new is sole acceptor + lease holder)
+ *   e. caller drains+reaps old
+ *
+ * Any throw → FALLBACK (caller does the tested abrupt restart). All-or-nothing:
+ * we never leave both accepting or both writing.
+ */
+export async function runReloadBaton({
+  oldWorker,
+  newWorker,
+  handle,
+  prepareHandle = async h => h,
+  readyTimeoutMs = 10_000,
+  releaseTimeoutMs = 20_000,
+  takeoverTimeoutMs = 10_000,
+  log = () => {},
+}) {
+  // (a) Confirm the freshly-spawned headless worker booted the new code.
+  let ready;
+  try {
+    newWorker.send({ type: MSG_PROBE_READY });
+    ready = await newWorker.waitFor([MSG_READY, MSG_FAILED], readyTimeoutMs);
+  } catch (err) {
+    log(`reload: readiness wait failed (${err.message}); rolling back`);
+    return RELOAD_ROLLED_BACK;
+  }
+  // (b) New worker did not come up cleanly → roll back fully, old stays primary.
+  if (!ready || ready.type === MSG_FAILED) {
+    log(`reload: new worker reported failed (${ready?.reason || 'no ready'}); rolling back`);
+    return RELOAD_ROLLED_BACK;
+  }
+
+  // (c) Old worker releases: stop accepting NEW, keep in-flight, stop writing,
+  //     flush config+state ONE final time, drop the TUI. After this point the
+  //     old worker holds no lease and no acceptor — and (single-writer) no
+  //     refresh/prober write is still in flight (it awaits drainRefreshes).
+  try {
+    oldWorker.send({ type: MSG_RELEASE });
+    await oldWorker.waitFor([MSG_RELEASED], releaseTimeoutMs);
+  } catch (err) {
+    // Old worker didn't ack release. We must NOT hand the socket to the new
+    // worker (would risk two acceptors) — fall back to the abrupt path.
+    log(`reload: old worker did not release (${err.message}); falling back`);
+    return RELOAD_FALLBACK;
+  }
+
+  // The old worker has now freed the listening fd. Re-arm the supervisor's own
+  // acceptor over the cutover gap (covers new conns in the OS backlog) and get a
+  // fresh re-sendable handle for the new worker.
+  let liveHandle = handle;
+  try {
+    liveHandle = await prepareHandle(handle);
+  } catch (err) {
+    log(`reload: could not re-arm listening socket (${err.message}); falling back`);
+    return RELOAD_FALLBACK;
+  }
+
+  // (d) New worker takes over: it becomes the SOLE acceptor (old already closed)
+  //     and ACQUIRES the writer lease (refresh/probe/persist re-enabled) + TUI.
+  try {
+    newWorker.send({ type: MSG_TAKEOVER }, liveHandle);
+    await newWorker.waitFor([MSG_PRIMARY], takeoverTimeoutMs);
+  } catch (err) {
+    // The new worker failed to start accepting after the old already released.
+    // Neither is accepting now — fall back so the supervisor force-restarts and
+    // a worker comes back up on the supervisor-owned socket (queued conns drain).
+    log(`reload: new worker did not take over (${err.message}); falling back`);
+    return RELOAD_FALLBACK;
+  }
+
+  log('reload: cutover complete; new worker is primary');
+  return RELOAD_SWAPPED;
+}

package/src/server.js

@@ -51,8 +51,25 @@ export function createProxyServer(accountManager, config, hooks = {}) {
     mkdir(logDir, { recursive: true }).catch(() => {});
   }
 
+  // Reload drain flag. When the worker releases the baton it sets this so every
+  // remaining response carries `Connection: close`, retiring the client's
+  // keep-alive socket instead of letting it pipeline a NEW request onto a worker
+  // that's shutting down. `connection` is hop-by-hop so it's stripped from the
+  // upstream response headers — a setHeader here survives the later writeHead.
+  let draining = false;
+
+  // Identifies the WORKER process that served a response — proves the supervisor
+  // (which holds the socket but does not serve) never swallowed the request. Set
+  // before any writeHead; `x-maxpool-*` is informative-only and stripped from
+  // upstream-bound request headers elsewhere.
+  const workerStamp = String(process.pid);
+
   const server = http.createServer(async (req, res) => {
     try {
+      try { res.setHeader('x-maxpool-worker', workerStamp); } catch { /* headers sent */ }
+      if (draining) {
+        try { res.setHeader('Connection', 'close'); } catch { /* headers may be sent */ }
+      }
       // Auth check — skip for localhost connections
       const clientKey = req.headers['x-api-key'];
       const remoteAddr = req.socket.remoteAddress;
@@ -187,6 +204,11 @@ export function createProxyServer(accountManager, config, hooks = {}) {
     }
   });
 
+  // Begin reload drain: every subsequent response gets `Connection: close` so
+  // keep-alive clients retire their socket and don't pipeline a new request onto
+  // this releasing worker.
+  server.maxpoolBeginDrain = () => { draining = true; };
+
   return server;
 }