agent-shim 11.62.3 → 11.63.0

package/dist/index.mjs

@@ -3901,12 +3901,13 @@ function pruneDeadFrontDoorSessions(fs14, sessionsDir, listed, isRunning) {
   }
   return removed;
 }
-var FRONT_DOOR_PROTOCOL, FrontDoorSessionSchema, FrontDoorStateSchema, MAX_TCP_PORT, FrontDoorDirectRecordSchema, RECORD_TEMPORARY_FILE;
+var FRONT_DOOR_PROTOCOL, FRONT_DOOR_HANDOVER_PROTOCOL, FrontDoorSessionSchema, FrontDoorStateSchema, MAX_TCP_PORT, FrontDoorDirectRecordSchema, RECORD_TEMPORARY_FILE;
 var init_state = __esm({
   "src/frontdoor/state.ts"() {
     "use strict";
     init_schema();
-    FRONT_DOOR_PROTOCOL = 5;
+    FRONT_DOOR_PROTOCOL = 6;
+    FRONT_DOOR_HANDOVER_PROTOCOL = 6;
     FrontDoorSessionSchema = z5.strictObject({ pid: z5.number().int().positive(), startedAt: z5.number(), token: z5.string().min(1), supervisorPid: z5.number().int().positive().optional(), sessionId: z5.string().min(1).optional(), models: ModelsConfigSchema.optional() });
     FrontDoorStateSchema = z5.strictObject({
       /**
@@ -4003,18 +4004,24 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
     ...lastConnectPort === void 0 ? {} : { lastConnectPort },
     ...lastDirectPort === void 0 ? {} : { lastDirectPort }
   });
+  const { predecessor } = ports;
+  const sourceOf = (listener, preferredPort) => predecessor === void 0 ? { preferredPort } : { inherit: async () => await predecessor.take(listener) };
   const fail = (message) => {
     ports.closeRcStreamHub();
-    writeFrontDoorState(fs14, paths.frontdoorStateFile, { lastError: message, ...sticky() });
-    fs14.removeRecursive(paths.frontdoorLockFile);
+    if (predecessor === void 0) {
+      writeFrontDoorState(fs14, paths.frontdoorStateFile, { lastError: message, ...sticky() });
+      fs14.removeRecursive(paths.frontdoorLockFile);
+    }
     ports.log(`agent-shim frontdoor supervisor: ${message}`);
     return 1;
   };
-  writeFrontDoorState(fs14, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, ...sticky() });
+  if (predecessor === void 0) {
+    writeFrontDoorState(fs14, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, ...sticky() });
+  }
   const previousSticky = lastPort;
   let http3;
   try {
-    http3 = await ports.startProviderListener(lastPort);
+    http3 = await ports.startProviderListener(sourceOf("provider", lastPort));
   } catch (error) {
     ports.doorHealth.listenerFailed("provider", error instanceof Error ? error.message : String(error));
     return fail(`could not start the provider listener: ${error instanceof Error ? error.message : String(error)}`);
@@ -4026,7 +4033,7 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
   const previousStickyConnect = lastConnectPort;
   let connect3;
   try {
-    connect3 = await ports.startConnectListener(lastConnectPort);
+    connect3 = await ports.startConnectListener(sourceOf("connect", lastConnectPort));
   } catch (error) {
     await http3.close();
     ports.doorHealth.listenerFailed("connect", error instanceof Error ? error.message : String(error));
@@ -4039,7 +4046,7 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
   const previousStickyDirect = lastDirectPort;
   let direct;
   try {
-    direct = await ports.startDirectListener(lastDirectPort);
+    direct = await ports.startDirectListener(sourceOf("direct", lastDirectPort));
   } catch (error) {
     await connect3.close();
     await http3.close();
@@ -4053,8 +4060,12 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
   writeFrontDoorDirectRecord(fs14, paths.frontdoorDirectRecordsDir, { pid: ports.ownPid, directPort: direct.port });
   writeFrontDoorState(fs14, paths.frontdoorStateFile, { protocol: FRONT_DOOR_PROTOCOL, supervisorPid: ports.ownPid, port: http3.port, connectPort: connect3.port, directPort: direct.port, ...sticky() });
   ports.doorHealth.generation({ providerPort: http3.port, connectPort: connect3.port, directPort: direct.port });
-  fs14.removeRecursive(paths.frontdoorLockFile);
-  ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: front door on 127.0.0.1:${String(http3.port)}, CONNECT surface on 127.0.0.1:${String(connect3.port)}`);
+  if (predecessor === void 0) {
+    fs14.removeRecursive(paths.frontdoorLockFile);
+  } else {
+    predecessor.serving();
+  }
+  ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: front door on 127.0.0.1:${String(http3.port)}, CONNECT surface on 127.0.0.1:${String(connect3.port)}${predecessor === void 0 ? "" : ", taken over from the door it replaced"}`);
   const watchdog = ports.startWatchdog?.();
   let idleSince;
   let ticks = 0;
@@ -4074,14 +4085,16 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
         resolve();
       };
       ports.retire?.addEventListener("abort", wake, { once: true });
+      ports.handover?.requested.addEventListener("abort", wake, { once: true });
       void ports.sleep(FRONTDOOR_POLL_MS).then(() => {
         ports.retire?.removeEventListener("abort", wake);
+        ports.handover?.requested.removeEventListener("abort", wake);
         resolve();
       });
     });
   };
   const retireByDrain = async () => {
-    ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: asked to exit; releasing the front door's addresses and finishing the connections it carries`);
+    ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: releasing the front door's addresses and finishing the connections it carries`);
     watchdog?.stop();
     ports.stopBackgroundWork?.();
     const drained = [direct.drain(), connect3.drain(), http3.drain()];
@@ -4096,6 +4109,17 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
     ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: the connections this door carried have ended; exiting`);
     return 0;
   };
+  const handOverThenDrain = async (run) => {
+    ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: asked to hand the front door's listeners to a successor; accepting on them until it serves`);
+    const outcome = await run({ provider: http3.listening, connect: connect3.listening, direct: direct.listening });
+    if (outcome.ok) {
+      ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: successor ${String(outcome.successorPid)} serves the front door's listeners`);
+      ports.doorHealth.superseded(outcome.successorPid);
+    } else {
+      ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: the handover failed (${outcome.reason}); retiring by drain so a successor is started on the released addresses`);
+    }
+    return await retireByDrain();
+  };
   const closeServing = async () => {
     watchdog?.stop();
     await direct.close();
@@ -4113,8 +4137,12 @@ async function serveFrontDoor(idleShutdownMinutes, ports, options) {
   };
   for (; ; ) {
     if (ports.retire?.aborted === true) {
+      ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: asked to exit`);
       return await retireByDrain();
     }
+    if (ports.handover?.requested.aborted === true && supersededBy === void 0) {
+      return await handOverThenDrain(ports.handover.run);
+    }
     if (options.tickLimit !== void 0 && ticks >= options.tickLimit) {
       watchdog?.stop();
       return FRONTDOOR_SUPERVISOR_STILL_RUNNING;
@@ -4252,8 +4280,10 @@ function caParses(ca) {
     return false;
   }
 }
-async function startConnectServer(config, effects, preferredPort) {
+async function startConnectServer(config, effects, source) {
   const tunnelTokens = /* @__PURE__ */ new WeakMap();
+  const ledger = createConnectionLedger(config.limits, config.isLiveCapability);
+  const lateSessionDeadlines = /* @__PURE__ */ new WeakMap();
   const onUpgrade = (host) => (request4, socket, head) => {
     config.capture?.upgrade(request4);
     if (head.length > 0) {
@@ -4275,6 +4305,12 @@ ${request4.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `$
       return { host, serveSecure: serveSecure2, tlsAcceptor: tlsAcceptor2 };
     }
     const handleHostRequest = async (request4, response) => {
+      if (ledger.retiring()) {
+        clearTimeout(lateSessionDeadlines.get(request4.socket));
+        response.once("close", () => {
+          request4.socket.end();
+        });
+      }
       if (config.localSurface !== void 0 && await config.localSurface.serve(host, request4, response)) {
         return;
       }
@@ -4294,13 +4330,19 @@ ${request4.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `$
     const httpSession = effects.createHttpSession(handler, onUpgrade(host));
     const serveSecure = (secure, capability) => {
       tunnelTokens.set(secure, capability);
+      if (ledger.retiring()) {
+        const deadline = setTimeout(() => {
+          secure.destroy();
+        }, config.limits.headDeadlineMs);
+        deadline.unref();
+        lateSessionDeadlines.set(secure, deadline);
+      }
       httpSession.serve(secure);
     };
     const tlsAcceptor = effects.createTlsAcceptor(config.leafFor(host), serveSecure);
     return { host, serveSecure, httpSession, tlsAcceptor };
   });
-  const ledger = createConnectionLedger(config.limits, config.isLiveCapability);
-  const listener = await effects.listenLoopback(preferredPort, (socket) => {
+  const listener = await effects.listenLoopback(source, (socket) => {
     handleConnect(socket, { config, effects, sessions, ledger });
   });
   const apiSession = sessions.find((session) => session.host === config.routedHost);
@@ -4313,7 +4355,7 @@ ${request4.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `$
     }
     session.serveSecure(secure, config.transparentCapability ?? "");
   });
-  const transparent = config.transparentPort === void 0 || apiSession === void 0 ? void 0 : await effects.listenLoopback(config.transparentPort, (socket) => {
+  const transparent = config.transparentPort === void 0 || apiSession === void 0 ? void 0 : await effects.listenLoopback({ preferredPort: config.transparentPort }, (socket) => {
     sniAcceptor.accept(socket);
   });
   const closeSurface = async () => {
@@ -4328,6 +4370,7 @@ ${request4.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `$
   };
   return {
     port: listener.port,
+    listening: listener.listening,
     ...transparent === void 0 ? {} : { transparentPort: transparent.port },
     openTunnels: ledger.openTunnels,
     drain: async () => {
@@ -4344,7 +4387,9 @@ function createConnectionLedger(limits, isLiveCapability2) {
   const authenticated = /* @__PURE__ */ new Map();
   let tunnels = 0;
   const blind = /* @__PURE__ */ new Set();
-  let onNoBlindTunnels;
+  const live = /* @__PURE__ */ new Set();
+  let retiring = false;
+  let onNoConnections;
   const leavePending = (socket) => {
     const deadline = pending.get(socket);
     if (deadline !== void 0) {
@@ -4376,20 +4421,19 @@ function createConnectionLedger(limits, isLiveCapability2) {
           refuse(socket, REFUSAL.requestTimeout);
         }, limits.headDeadlineMs)
       );
+      live.add(socket);
       socket.once("close", () => {
         leavePending(socket);
+        live.delete(socket);
+        if (live.size === 0) {
+          onNoConnections?.();
+        }
       });
     },
     headReceived: leavePending,
     openTunnels: () => tunnels,
     retire: async () => {
-      for (const socket of pending.keys()) {
-        socket.destroy();
-      }
-      for (const deadline of pending.values()) {
-        clearTimeout(deadline);
-      }
-      pending.clear();
+      retiring = true;
       for (const sockets of authenticated.values()) {
         for (const socket of sockets) {
           if (!blind.has(socket)) {
@@ -4397,12 +4441,13 @@ function createConnectionLedger(limits, isLiveCapability2) {
           }
         }
       }
-      if (blind.size > 0) {
+      if (live.size > 0) {
         await new Promise((resolve) => {
-          onNoBlindTunnels = resolve;
+          onNoConnections = resolve;
         });
       }
     },
+    retiring: () => retiring,
     establish: (socket, capability, kind) => {
       if (tunnels >= limits.maxTunnels) {
         return false;
@@ -4417,9 +4462,6 @@ function createConnectionLedger(limits, isLiveCapability2) {
       socket.once("close", () => {
         tunnels -= 1;
         blind.delete(socket);
-        if (blind.size === 0) {
-          onNoBlindTunnels?.();
-        }
         sockets.delete(socket);
         if (sockets.size === 0 && authenticated.get(capability) === sockets) {
           authenticated.delete(capability);
@@ -4627,7 +4669,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "agent-shim",
-      version: "11.62.3",
+      version: "11.63.0",
       description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
       license: "MIT",
       author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -10154,7 +10196,8 @@ var init_replacement = __esm({
 import { randomUUID as randomUUID3 } from "node:crypto";
 function ensureFrontDoor(params) {
   const { paths, ports } = params;
-  const deadline = ports.now() + FRONTDOOR_START_TIMEOUT_MS;
+  const startedAt = ports.now();
+  let deadline = startedAt + FRONTDOOR_START_TIMEOUT_MS;
   let spawned = false;
   let replaced = false;
   const distrusted = /* @__PURE__ */ new Set();
@@ -10194,6 +10237,19 @@ function ensureFrontDoor(params) {
       ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
     }
   };
+  const handOverAndAwait = (supervisorPid, doorProtocol, reason, request4) => {
+    recordReplacement(supervisorPid, doorProtocol, reason, "SIGUSR2");
+    request4(supervisorPid);
+    const waitEnds = ports.now() + FRONTDOOR_START_TIMEOUT_MS + FRONTDOOR_EXIT_GRACE_MS;
+    deadline += FRONTDOOR_START_TIMEOUT_MS + FRONTDOOR_EXIT_GRACE_MS;
+    while (ports.isRunning(supervisorPid) && readFrontDoorState(ports.fs, paths.frontdoorStateFile)?.supervisorPid === supervisorPid) {
+      if (ports.now() >= waitEnds) {
+        stopAndAwaitExit(supervisorPid, doorProtocol, reason, `the front door (pid ${String(supervisorPid)}) did not act on a request to hand its listeners over, and did not exit when asked to`);
+        return;
+      }
+      ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
+    }
+  };
   for (; ; ) {
     const state = readFrontDoorState(ports.fs, paths.frontdoorStateFile);
     const supervisorPid = state?.supervisorPid;
@@ -10207,12 +10263,16 @@ function ensureFrontDoor(params) {
         const verdict = verifyWithRetry(state.port);
         const doorProtocol = state.protocol ?? 0;
         if (verdict.ok && !replaced && !spawned && (params.replace !== void 0 || doorProtocol < FRONT_DOOR_PROTOCOL)) {
-          stopAndAwaitExit(
-            supervisorPid,
-            doorProtocol,
-            params.replace ?? "protocol-older",
-            `the front door (pid ${String(supervisorPid)}, protocol ${String(doorProtocol)}; this launcher speaks protocol ${String(FRONT_DOOR_PROTOCOL)}) was asked to be replaced and did not exit`
-          );
+          if (params.replace !== void 0 && doorProtocol >= FRONT_DOOR_HANDOVER_PROTOCOL && ports.requestHandover !== void 0 && ports.isFrontDoorSupervisor(supervisorPid)) {
+            handOverAndAwait(supervisorPid, doorProtocol, params.replace, ports.requestHandover);
+          } else {
+            stopAndAwaitExit(
+              supervisorPid,
+              doorProtocol,
+              params.replace ?? "protocol-older",
+              `the front door (pid ${String(supervisorPid)}, protocol ${String(doorProtocol)}; this launcher speaks protocol ${String(FRONT_DOOR_PROTOCOL)}) was asked to be replaced and did not exit`
+            );
+          }
           replaced = true;
           continue;
         }
@@ -10264,7 +10324,7 @@ function ensureFrontDoor(params) {
     if (ports.now() >= deadline) {
       const lastError = state?.lastError;
       throw new FrontDoorStartError(
-        `the front door did not become ready within ${String(FRONTDOOR_START_TIMEOUT_MS)}ms` + (lastError === void 0 ? "" : ` (last error: ${lastError})`) + (lastRejection === void 0 ? "" : ` (${lastRejection})`) + (busyDoor === void 0 ? "" : `. It was not replaced because ${String(busyDoor.sessions)} live session(s) are using it and would lose their connections; run \`agent-shim frontdoor restart\` to replace it deliberately`) + `. Daemon log: ${paths.frontdoorLogPath}`
+        `the front door did not become ready within ${String(deadline - startedAt)}ms` + (lastError === void 0 ? "" : ` (last error: ${lastError})`) + (lastRejection === void 0 ? "" : ` (${lastRejection})`) + (busyDoor === void 0 ? "" : `. It was not replaced because ${String(busyDoor.sessions)} live session(s) are using it and would lose their connections; run \`agent-shim frontdoor restart\` to replace it deliberately`) + `. Daemon log: ${paths.frontdoorLogPath}`
       );
     }
     ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
@@ -11907,6 +11967,12 @@ function realEnsurePorts(paths, spawnDaemon) {
     killSupervisor: (pid) => {
       process.kill(pid, "SIGKILL");
     },
+    // Windows has no user signals (Node refuses to send one), so a replacement there keeps the stop-and-start path.
+    ...process.platform === "win32" ? {} : {
+      requestHandover: (pid) => {
+        process.kill(pid, "SIGUSR2");
+      }
+    },
     // Read fresh for each probe: a replacement supervisor may have regenerated an unparseable CA, and the probe must trust exactly what the serving door's leaf chains to.
     verifyListener: (port) => probeFrontDoorSync(port, fs13.readFileSync(paths.frontdoorCaCertFile, "utf8"))
   };
@@ -14336,7 +14402,7 @@ function realRcStreamDial(target = { host: CONNECT_INTERCEPT_HOST, port: HTTPS_P
 function realConnectEffects(ports = DOOR_SOURCE_PORTS) {
   const plainAgent = new ExemptHttpAgent(ports);
   const tlsAgent = new ExemptTlsAgent(ports);
-  const listenOnce = async (port, onSocket) => await new Promise((resolve, reject) => {
+  const listenOnce = async (target, onSocket) => await new Promise((resolve, reject) => {
     const accepted = /* @__PURE__ */ new Set();
     const server = net2.createServer((socket) => {
       accepted.add(socket);
@@ -14346,7 +14412,7 @@ function realConnectEffects(ports = DOOR_SOURCE_PORTS) {
       onSocket(socket);
     });
     server.once("error", reject);
-    server.listen(port, "127.0.0.1", () => {
+    const onListening = () => {
       const address = server.address();
       const bound = typeof address === "object" && address !== null ? address.port : 0;
       if (bound === 0) {
@@ -14355,6 +14421,7 @@ function realConnectEffects(ports = DOOR_SOURCE_PORTS) {
       }
       resolve({
         port: bound,
+        listening: server,
         // The listening socket is released by `close` at once; the connections already accepted are untouched and keep the server's `close` callback pending until they end.
         stopAccepting: () => {
           server.close();
@@ -14370,10 +14437,19 @@ function realConnectEffects(ports = DOOR_SOURCE_PORTS) {
           });
         }
       });
-    });
+    };
+    if (typeof target === "number") {
+      server.listen(target, "127.0.0.1", onListening);
+    } else {
+      server.listen(target, onListening);
+    }
   });
   return {
-    listenLoopback: async (preferredPort, onSocket) => {
+    listenLoopback: async (source, onSocket) => {
+      if ("inherit" in source) {
+        return await listenOnce(await source.inherit(), onSocket);
+      }
+      const { preferredPort } = source;
       if (preferredPort !== void 0) {
         try {
           return await listenOnce(preferredPort, onSocket);

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ import * as zod from 'zod';
 import { z } from 'zod';
 import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
 import * as net from 'node:net';
+import net__default from 'node:net';
 import { Duplex, Readable } from 'node:stream';
 import * as _orpc_client from '@orpc/client';
 import * as zod_v4_core from 'zod/v4/core';
@@ -5785,6 +5786,42 @@ interface ConnectCapture {
     readonly upgrade: (request: CapturedRequestShape) => void;
 }
 
+/**
+ * The listening-socket handover between a serving front door and the successor it starts for a planned replacement (`agent-shim frontdoor restart`, `agent-shim update --restart-door`), so the sticky addresses never stop accepting: the kernel's accept queue for each listener is held by the old door until the successor holds it too, and only then does the old door stop accepting and drain.
+ *
+ * The two doors speak over the IPC channel Node opens between a parent and the child it spawns with one, and each listening socket crosses it as a handle attached to a message (`child.send(message, server)`), which is the only way Node passes a listening socket between processes. The successor asks for each listener only once its own server for that listener is built, and adopts the handle in the same turn the message is delivered in: Node starts accepting on a received listening handle inside a server of its own before it hands the handle over, and a connection accepted there before the successor's server adopts it would reach a server with no connection listener and hang. Asking per listener keeps every adoption inside one delivery.
+ *
+ * The exchange, in order: the successor sends `take` naming one listener; the old door answers with `listener` naming it and carrying the handle; once the successor has adopted all three and recorded itself as the owner in the state file, it sends `serving` and ends the channel. The old door then drains exactly as it does on `SIGTERM`. Any other outcome (the successor exits or ends the channel early, sends something this release cannot read, or is still not serving when the budget ends) ends the successor if it is still running and leaves the old door to drain the ordinary way, so the replacement still happens, through the path that has a gap.
+ */
+/** Where a listener's socket comes from: bound afresh, preferring the sticky port and taking any free one when it is held, or adopted from the door being replaced. */
+type ListenSource = {
+    readonly preferredPort: number | undefined;
+} | {
+    readonly inherit: () => Promise<net__default.Server>;
+};
+/** The listeners a door hands over: the HTTPS provider listener, the CONNECT surface, and the plain-HTTP direct listener. */
+declare const HANDOVER_LISTENERS: readonly ["provider", "connect", "direct"];
+type HandoverListenerName = (typeof HANDOVER_LISTENERS)[number];
+/** The listening sockets a door hands over, one per listener. */
+type HandoverSockets = Readonly<Record<HandoverListenerName, net__default.Server>>;
+/** How a handover ended, as the old door sees it. */
+type HandoverOutcome = {
+    readonly ok: true;
+    readonly successorPid: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** What a successor door does with the channel to the door it replaces: take each listener's socket, then report that it serves. */
+interface Predecessor {
+    /**
+     * Asks for one listener's socket and resolves with it in the turn the old door's answer is delivered in, so the caller's continuation (which must adopt it at once, see the module comment) runs before the event loop can accept a connection on it. Rejects when the channel ends first or the answer cannot be read.
+     */
+    readonly take: (listener: HandoverListenerName) => Promise<net__default.Server>;
+    /** Tells the old door this door accepts on every listener and owns the state file, then ends the channel. */
+    readonly serving: () => void;
+}
+
 /**
  * The front door's CONNECT surface, so an OAuth session can have agent-shim's routing AND Claude Code's Remote Control at once: Remote Control refuses any `ANTHROPIC_BASE_URL` other than the real API, but happily honours `HTTPS_PROXY`, so OAuth launches route at the proxy layer instead.
  *
@@ -5892,6 +5929,8 @@ type ConnectRequestHandler = (request: IncomingMessage, response: ServerResponse
 /** A bound loopback listener and how to stop it. */
 interface ConnectListenerHandle {
     readonly port: number;
+    /** The listening socket itself, which a planned replacement hands to the successor door (see `./handover.ts`). */
+    readonly listening: net.Server;
     /** Stops accepting and releases the port at once, leaving every connection already accepted open: a successor can bind the same port while they finish. */
     readonly stopAccepting: () => void;
     /** Stops accepting, ends every live connection, and resolves once the port is released. */
@@ -5920,8 +5959,8 @@ interface HttpParserSession {
  * Every effect the MITM proxy performs, injected so the routing decisions and lifecycle run against fakes in unit tests (the SupervisorPorts pattern): TCP listening, TLS termination, HTTP parsing, plain TCP tunnels, and request forwarding. The real implementation is `realConnectEffects`; the TLS round-trip test uses it with redirected targets.
  */
 interface ConnectEffects {
-    /** Binds a loopback TCP listener; `preferredPort` is tried first and any free port used when it is taken (bind, do not probe: check-then-bind races). Resolves with the bound port and a close handle. */
-    readonly listenLoopback: (preferredPort: number | undefined, onSocket: (socket: net.Socket) => void) => Promise<ConnectListenerHandle>;
+    /** Binds a loopback TCP listener, or adopts the one `source` inherits from the door being replaced; a bound one tries the preferred port first and uses any free port when it is taken (bind, do not probe: check-then-bind races). Resolves with the bound port and a close handle. */
+    readonly listenLoopback: (source: ListenSource, onSocket: (socket: net.Socket) => void) => Promise<ConnectListenerHandle>;
     /** Builds the TLS terminator for one leaf, handing each successfully handshaked session to `onSecure` together with the context its `accept` call carried. `alpnProtocols`, when given, is advertised during the handshake, which is how a tap host's session can offer HTTP/2 the way its real server does. */
     readonly createTlsAcceptor: (leaf: LeafCert, onSecure: (secure: net.Socket, context: string) => void, alpnProtocols?: readonly string[]) => TlsAcceptor;
     /** Builds the transparent surface's TLS terminator: one handshake whose SNI name selects which served host's leaf answers it, so a connection redirected from any of the hosts sharing the redirected address is terminated as the host it named. A name the surface does not serve is answered with no certificate at all (a client that sends no SNI never reaches the selection and finds no default certificate either), because the only leaf that could answer such a name is another host's, which the client's own hostname check would reject anyway. No ALPN is offered: node's TLS server negotiates ALPN from the listener's own options and ignores protocols named on an SNI-selected secure context, and the API host's terminated session is parsed as HTTP/1.1, which a negotiated `h2` would strand. */
@@ -5975,12 +6014,14 @@ interface ConnectServerConfig {
 /** A running connect surface. */
 interface ConnectServerHandle {
     readonly port: number;
+    /** The CONNECT listener's listening socket, which a planned replacement hands to the successor door (see `./handover.ts`). The transparent listener is not handed over: it exists only when the door's own environment asks for it, which a successor decides for itself. */
+    readonly listening: net.Server;
     /** The transparent listener's port, when one was requested: what an operating-system redirect should point at. */
     readonly transparentPort?: number;
     /** How many authenticated connections (blind tunnels and terminated sessions together) are open now: what closing this surface, or exiting its process, drops. */
     readonly openTunnels: () => number;
     /**
-     * Retires the surface without cutting off the tunnels it carries: the port is released at once so a successor can bind it, every connection that is not a blind tunnel (the terminated sessions, which carry this door's own routing state, and connections still waiting for their head) is ended, and the blind tunnels, which are byte pumps to hosts the door never looks into, keep running until they end by themselves or their launch ends. Resolves when the last has, with the surface fully closed.
+     * Retires the surface without cutting off the tunnels it carries: the port is released at once so a successor can bind it, the terminated sessions (which carry this door's own routing state) are ended so their clients reconnect to the successor, and the blind tunnels, which are byte pumps to hosts the door never looks into, keep running until they end by themselves or their launch ends. A connection the listener accepted before it stopped but whose head has not arrived yet is still answered: its blind tunnel runs like any other, its terminated session serves one request and ends, and one whose head never comes is refused at its deadline. Resolves when the last connection has closed, with the surface fully closed.
      */
     readonly drain: () => Promise<void>;
     /** Stops the listener, drops every live tunnel and terminated session, and resolves once the port is released. */
@@ -6002,7 +6043,7 @@ interface ConnectLocalSurface {
  *
  * The connection flow: read the CONNECT head within the deadline (never more of the stream than that, so an early ClientHello glued to the head is pushed back with `unshift` and still seen by whatever consumes the socket next), authenticate it, then either blind-tunnel the target or terminate its TLS and parse HTTP on the session. Every network effect flows through `effects`; nothing here touches the network or filesystem itself.
  */
-declare function startConnectServer(config: ConnectServerConfig, effects: ConnectEffects, preferredPort: number | undefined): Promise<ConnectServerHandle>;
+declare function startConnectServer(config: ConnectServerConfig, effects: ConnectEffects, source: ListenSource): Promise<ConnectServerHandle>;
 /** The real `ConnectCertStore` on the filesystem: `ca.pem` world-readable (it is public material), `ca.key` mode 0600 exactly, chmod'ed after the write because a create's mode bits pass through the process umask. */
 declare function realConnectCertStore(paths: {
     readonly frontdoorCaDir: string;
@@ -23843,6 +23884,10 @@ interface EnsureFrontDoorPorts {
     readonly verifyListener: (port: number) => ListenerVerdict;
     /** Asks a running front-door supervisor to exit, without waiting for it to: the caller polls `isRunning`. Only ever called for a pid whose recorded listener has just authenticated as agent-shim's own, or whose process is agent-shim's front-door supervisor (`isFrontDoorSupervisor`). */
     readonly stopSupervisor: (pid: number) => void;
+    /**
+     * Asks a running front-door supervisor to hand its listening sockets to a successor it starts itself (see `./handover.ts`), without waiting for it to: the caller polls the state file for the successor. Only ever called for a pid whose listener has just authenticated, whose recorded protocol is `FRONT_DOOR_HANDOVER_PROTOCOL` or later, and whose process is agent-shim's own front-door supervisor, the process that installs the handler for the request. Absent where the platform has no way to deliver the request (Windows, which has no user signals), so every replacement there takes the stop-and-start path.
+     */
+    readonly requestHandover?: (pid: number) => void;
     /** Appends one line to the front door's own log. Called before every signal sent to a door, so the door's log names the cause of its own exit. */
     readonly recordReplacement: (line: string) => void;
     /** Ends a supervisor that did not exit when asked to, without giving it the chance to refuse: a door whose event loop is blocked never runs its signal handler. Called only for a pid `isFrontDoorSupervisor` has just confirmed, after `stopSupervisor` and a grace period. */
@@ -23878,6 +23923,8 @@ interface DoorWatchdog {
 /** A bound front-door listener in this process, and how to stop it. */
 interface FrontDoorListenerHandle {
     readonly port: number;
+    /** The listening socket itself, which a planned replacement hands to the successor door (see `./handover.ts`). */
+    readonly listening: net__default.Server;
     /** Stops accepting, ends every live connection, and resolves once the port is released. */
     readonly close: () => Promise<void>;
     /** Releases the port at once (before the first await) and leaves the work already in progress to finish; resolves when the listener has nothing left to carry. */
@@ -23911,17 +23958,17 @@ interface FrontDoorSupervisorPorts {
      */
     readonly runningAmong: (pids: readonly number[]) => Promise<ReadonlySet<number>>;
     /**
-     * Starts the provider listener in this process on `preferredPort` (falling back to any free port when the sticky one is taken, decided at bind time rather than by a racy check-then-bind probe) and resolves once it has bound and answered its own health probe over TLS. This is the HTTPS listener every provider session's base URL points at, serving a loopback leaf signed by agent-shim's CA.
+     * Starts the provider listener in this process from `source`: bound on its preferred port (falling back to any free port when the sticky one is taken, decided at bind time rather than by a racy check-then-bind probe), or adopted from the door this one replaces. Resolves once it accepts and has answered its own health probe over TLS. This is the HTTPS listener every provider session's base URL points at, serving a loopback leaf signed by agent-shim's CA.
      */
-    readonly startProviderListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    readonly startProviderListener: (source: ListenSource) => Promise<FrontDoorListenerHandle>;
     /**
-     * Starts the CONNECT surface in this process on `preferredPort` (same bind-time fallback): the TLS-terminating listener an OAuth session's HTTPS_PROXY points at. Bound before any state names it, so an OAuth launch never finds one listener up without the other.
+     * Starts the CONNECT surface in this process from `source` (same bind-time fallback, or adopted): the TLS-terminating listener an OAuth session's HTTPS_PROXY points at. Bound before any state names it, so an OAuth launch never finds one listener up without the other.
      */
-    readonly startConnectListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    readonly startConnectListener: (source: ListenSource) => Promise<FrontDoorListenerHandle>;
     /**
-     * Starts the direct listener on `preferredPort` (same bind-time fallback): the same routes as the provider listener, minus the headroom hop, over plain HTTP because headroom is what connects to it. Headroom forwards routed traffic back here, which is what keeps the hop from looping, and the port is sticky like the others because headroom's allowlist admits its exact origin. It admits only the hop's own requests and holds no credential until it redeems one from the hop's custody.
+     * Starts the direct listener from `source` (same bind-time fallback, or adopted): the same routes as the provider listener, minus the headroom hop, over plain HTTP because headroom is what connects to it. Headroom forwards routed traffic back here, which is what keeps the hop from looping, and the port is sticky like the others because headroom's allowlist admits its exact origin. It admits only the hop's own requests and holds no credential until it redeems one from the hop's custody.
      */
-    readonly startDirectListener: (preferredPort: number | undefined) => Promise<FrontDoorListenerHandle>;
+    readonly startDirectListener: (source: ListenSource) => Promise<FrontDoorListenerHandle>;
     /**
      * Stops the Remote Control stream hub: persists every live attachment's sequence cursor synchronously, then frees the dials. Called exactly once on every exit the supervisor owns, after every listener has stopped accepting. A closing exit has every listener down by then; a drain still has responses settling, which is safe because the hub refuses to attach once it is closed (otherwise the reconcile after an observed exchange would re-attach a stream the close had just ended).
      */
@@ -23934,6 +23981,17 @@ interface FrontDoorSupervisorPorts {
      * Aborted when the process is asked to exit (the CLI's `__frontdoor-supervisor` aborts it on its first SIGTERM or SIGINT). The door then retires by draining: it releases its listening addresses at once, so a successor can bind the same sticky ports, ends what holds its own routing state, and stays up only as long as the connections it still carries (blind tunnels, a response being streamed) take to end. Optional for a host that decides when the door stops by other means.
      */
     readonly retire?: AbortSignal;
+    /**
+     * A planned replacement that keeps every address accepting (see `./handover.ts`): `requested` is aborted when a launcher asks this door to hand its listeners to a successor (the CLI's `__frontdoor-supervisor` aborts it on `SIGUSR2`), and `run` starts the successor, hands it the three listening sockets and resolves once it serves them or with why it did not. The door keeps accepting throughout and drains afterwards either way, so a failed handover still ends in the ordinary replacement. Optional because only a door whose process can start a successor of itself can offer it.
+     */
+    readonly handover?: {
+        readonly requested: AbortSignal;
+        readonly run: (sockets: HandoverSockets) => Promise<HandoverOutcome>;
+    };
+    /**
+     * The door this one replaces through a handover, when it was started for one: its listeners are adopted from that door's sockets instead of bound, the state file is not written until this door accepts on all three (the old door owns it and keeps serving until then), and the old door is told once this door serves. Absent for every other start.
+     */
+    readonly predecessor?: Predecessor;
     /** Stops the work the door runs on its own account rather than for a request (the usage, window, job and catalogue keepers), called once when a drain begins so the successor's are the only ones acting. Optional because a host without such work has nothing to stop. */
     readonly stopBackgroundWork?: () => void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "11.62.3",
+  "version": "11.63.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",