very-happy-cli 0.2.76 → 0.2.78

package/dist/{spawn-BEwPBgbi.mjs → spawn-Da-94Ejo.mjs}

@@ -1,8 +1,8 @@
 import chalk from 'chalk';
 import { readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { c as checkIfDaemonRunningAndCleanupStaleState, s as spawnDaemonSession, a as sessionWebUrl, w as waitForSessionKey, b as sendUserMessage } from './index-DBO5ydFO.mjs';
-import { l as logger } from './types-kLTNjWVl.mjs';
+import { c as checkIfDaemonRunningAndCleanupStaleState, s as spawnDaemonSession, a as sessionWebUrl, w as waitForSessionKey, b as sendUserMessage } from './index-w0zkr6EM.mjs';
+import { l as logger } from './types-Clmu74iY.mjs';
 import 'node:os';
 import 'node:crypto';
 import 'cross-spawn';

package/dist/{types-kLTNjWVl.mjs → types-Clmu74iY.mjs}

@@ -29,7 +29,7 @@ import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
 import { Expo } from 'expo-server-sdk';
 
 var name = "very-happy-cli";
-var version = "0.2.76";
+var version = "0.2.78";
 var description = "Remote multi-agent workspace CLI with deep Claude integration, native terminal streaming, and self-hosting.";
 var author = "Kirill Dubovitskiy";
 var contributors = [
@@ -142,12 +142,12 @@ var dependencies = {
 	zod: "^4.0.0"
 };
 var optionalDependencies = {
-	"very-happy-tools-arm64-darwin": "0.2.76",
-	"very-happy-tools-x64-darwin": "0.2.76",
-	"very-happy-tools-arm64-linux": "0.2.76",
-	"very-happy-tools-x64-linux": "0.2.76",
-	"very-happy-tools-arm64-win32": "0.2.76",
-	"very-happy-tools-x64-win32": "0.2.76"
+	"very-happy-tools-arm64-darwin": "0.2.78",
+	"very-happy-tools-x64-darwin": "0.2.78",
+	"very-happy-tools-arm64-linux": "0.2.78",
+	"very-happy-tools-x64-linux": "0.2.78",
+	"very-happy-tools-arm64-win32": "0.2.78",
+	"very-happy-tools-x64-win32": "0.2.78"
 };
 var devDependencies = {
 	"@slopus/happy-wire": "workspace:*",
@@ -896,6 +896,15 @@ z$1.object({
   region: z$1.string().min(1).max(64),
   version: z$1.string().min(1).max(64)
 });
+const ReleaseSlotSchema = z$1.enum(["blue", "green"]);
+const ReleaseDrainNoticeSchema = z$1.object({
+  epoch: z$1.string().regex(/^[A-Za-z0-9._-]{8,128}$/),
+  fromRelease: z$1.string().regex(/^[0-9a-f]{40}$/),
+  toRelease: z$1.string().regex(/^[0-9a-f]{40}$/),
+  candidateSlot: ReleaseSlotSchema,
+  deadline: z$1.number().int().positive(),
+  mode: z$1.literal("make-before-break")
+});
 
 z$1.object({
   host: z$1.string(),
@@ -929,6 +938,9 @@ const CliUpdateStateSchema = z$1.object({
 const WebTerminalListItemSchema = z$1.object({
   id: z$1.string(),
   title: z$1.string().optional(),
+  /** New daemons always send an array (including []); absence identifies an
+   * old daemon that cannot persist terminal tags. */
+  tags: z$1.array(z$1.string()).optional(),
   cwd: z$1.string().optional(),
   createdAt: z$1.number().optional(),
   activityAt: z$1.number().optional(),
@@ -1359,6 +1371,56 @@ class RpcHandlerManager {
       socket.emit("rpc-register", { method: prefixedMethod });
     }
   }
+  /**
+   * Attach a candidate transport and wait until the server confirms every
+   * method before a release handover closes the old transport.
+   */
+  async onSocketConnectAndWait(socket, timeoutMs = 1e4) {
+    this.sockets.add(socket);
+    const pending = new Set(this.handlers.keys());
+    const acknowledged = /* @__PURE__ */ new Set();
+    await new Promise((resolve, reject) => {
+      let settleTimer = null;
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`RPC registration timed out (${pending.size} pending)`));
+      }, timeoutMs);
+      timer.unref?.();
+      const maybeSettle = () => {
+        if (pending.size > 0 || settleTimer) return;
+        settleTimer = setTimeout(() => {
+          settleTimer = null;
+          for (const prefixedMethod of this.handlers.keys()) {
+            if (acknowledged.has(prefixedMethod) || pending.has(prefixedMethod)) continue;
+            pending.add(prefixedMethod);
+            socket.emit("rpc-register", { method: prefixedMethod });
+          }
+          if (pending.size === 0) {
+            cleanup();
+            resolve();
+          }
+        }, 0);
+        settleTimer.unref?.();
+      };
+      const onRegistered = (data) => {
+        if (typeof data?.method !== "string") return;
+        acknowledged.add(data.method);
+        pending.delete(data.method);
+        maybeSettle();
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        if (settleTimer) clearTimeout(settleTimer);
+        socket.off("rpc-registered", onRegistered);
+      };
+      socket.on("rpc-registered", onRegistered);
+      for (const prefixedMethod of pending) socket.emit("rpc-register", { method: prefixedMethod });
+      maybeSettle();
+    }).catch((error) => {
+      this.sockets.delete(socket);
+      throw error;
+    });
+  }
   onSocketDisconnect(socket) {
     if (socket) this.sockets.delete(socket);
     else this.sockets.clear();
@@ -2760,6 +2822,7 @@ class ApiSessionClient extends EventEmitter {
   receiveSync;
   directInboundLocalIds = /* @__PURE__ */ new Set();
   routedInboundLocalIds = /* @__PURE__ */ new Set();
+  handoverInFlight = null;
   constructor(token, session) {
     super();
     this.token = token;
@@ -2779,26 +2842,15 @@ class ApiSessionClient extends EventEmitter {
       logger: (msg, data) => logger.debug(msg, data)
     });
     registerCommonHandlers(this.rpcHandlerManager, this.metadata.path);
-    this.socket = io(configuration.serverUrl, {
-      auth: {
-        token: this.token,
-        clientType: "session-scoped",
-        sessionId: this.sessionId,
-        happyClient: `cli-coding-session/${configuration.currentCliVersion}`
-      },
-      path: "/v1/updates",
-      reconnection: false,
-      transports: ["websocket"],
-      withCredentials: true,
-      autoConnect: false
-    });
+    this.socket = this.createControlSocket();
+    const controlSocket = this.socket;
     this.socket.on("connect", () => {
       logger.debug("Socket connected successfully");
       if (this.reconnectInterval) {
         clearInterval(this.reconnectInterval);
         this.reconnectInterval = null;
       }
-      this.rpcHandlerManager.onSocketConnect(this.socket);
+      this.rpcHandlerManager.onSocketConnect(controlSocket);
       this.receiveSync.invalidate();
       void this.connectSessionRelay();
     });
@@ -2807,12 +2859,12 @@ class ApiSessionClient extends EventEmitter {
     });
     this.socket.on("disconnect", (reason) => {
       logger.debug(`[API] Socket disconnected: ${reason}`);
-      this.rpcHandlerManager.onSocketDisconnect();
+      this.rpcHandlerManager.onSocketDisconnect(controlSocket);
       this.startSmartReconnect();
     });
     this.socket.on("connect_error", (error) => {
       logger.debug("[API] Socket connection error:", error);
-      this.rpcHandlerManager.onSocketDisconnect();
+      this.rpcHandlerManager.onSocketDisconnect(controlSocket);
       if (error.message === "Session archived") {
         logger.debug("[API] Archived session rejected during reconnect; exiting");
         this.emit("archived");
@@ -2883,8 +2935,103 @@ class ApiSessionClient extends EventEmitter {
     this.socket.on("error", (error) => {
       logger.debug("[API] Socket error:", error);
     });
+    this.socket.on("server-draining", (data) => {
+      const parsed = ReleaseDrainNoticeSchema.safeParse(data);
+      if (!parsed.success || parsed.data.deadline <= Date.now()) return;
+      void this.startReleaseHandover(parsed.data);
+    });
     this.socket.connect();
   }
+  createControlSocket(handover) {
+    return io(configuration.serverUrl, {
+      auth: {
+        token: this.token,
+        clientType: "session-scoped",
+        sessionId: this.sessionId,
+        happyClient: `cli-coding-session/${configuration.currentCliVersion}`,
+        ...handover ? { handoverEpoch: handover.epoch } : {}
+      },
+      ...handover ? { query: { vh_slot: handover.candidateSlot }, forceNew: true } : {},
+      path: "/v1/updates",
+      reconnection: false,
+      transports: ["websocket"],
+      withCredentials: true,
+      autoConnect: false
+    });
+  }
+  startReleaseHandover(notice) {
+    if (this.handoverInFlight) return this.handoverInFlight;
+    this.handoverInFlight = this.releaseHandover(notice).finally(() => {
+      this.handoverInFlight = null;
+    });
+    return this.handoverInFlight;
+  }
+  async releaseHandover(notice) {
+    const startedAt = Date.now();
+    const previous = this.socket;
+    const candidate = this.createControlSocket(notice);
+    const transferredListeners = /* @__PURE__ */ new Map();
+    for (const listener of previous.listeners("rpc-request")) candidate.on("rpc-request", listener);
+    const timeoutMs = Math.max(1, Math.min(1e4, notice.deadline - Date.now()));
+    try {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("release handover timeout")), timeoutMs);
+        candidate.once("connect", () => {
+          clearTimeout(timer);
+          resolve();
+        });
+        candidate.once("connect_error", (error) => {
+          clearTimeout(timer);
+          reject(error);
+        });
+        candidate.connect();
+      });
+      await this.rpcHandlerManager.onSocketConnectAndWait(candidate, timeoutMs);
+      if (this.socket !== previous) {
+        this.rpcHandlerManager.onSocketDisconnect(candidate);
+        candidate.close();
+        return;
+      }
+      for (const event of ["session-archive", "update", "error", "server-draining"]) {
+        const listeners = previous.listeners(event);
+        previous.removeAllListeners(event);
+        for (const listener of listeners) candidate.on(event, listener);
+        transferredListeners.set(event, listeners);
+      }
+      this.socket = candidate;
+      candidate.on("connect", () => {
+        if (this.reconnectInterval) {
+          clearInterval(this.reconnectInterval);
+          this.reconnectInterval = null;
+        }
+        this.rpcHandlerManager.onSocketConnect(candidate);
+        this.receiveSync.invalidate();
+      });
+      candidate.on("disconnect", () => {
+        this.rpcHandlerManager.onSocketDisconnect(candidate);
+        this.startSmartReconnect();
+      });
+      candidate.on("connect_error", () => {
+        this.rpcHandlerManager.onSocketDisconnect(candidate);
+        this.startSmartReconnect();
+      });
+      this.receiveSync.invalidate();
+      candidate.emit("release-handover-result", { result: "success", durationMs: Date.now() - startedAt });
+      this.rpcHandlerManager.onSocketDisconnect(previous);
+      previous.removeAllListeners("disconnect");
+      previous.close();
+    } catch (error) {
+      if (this.socket === candidate) this.socket = previous;
+      for (const [event, listeners] of transferredListeners) {
+        candidate.removeAllListeners(event);
+        for (const listener of listeners) previous.on(event, listener);
+      }
+      this.rpcHandlerManager.onSocketDisconnect(candidate);
+      candidate.close();
+      if (previous.connected) previous.emit("release-handover-result", { result: "failed", durationMs: Date.now() - startedAt });
+      logger.debug(`[API] Release handover failed: ${error instanceof Error ? error.message : error}`);
+    }
+  }
   onUserMessage(callback) {
     this.pendingMessageCallback = callback;
     while (this.pendingMessages.length > 0) {
@@ -9642,6 +9789,7 @@ function terminalListSignature(items) {
   const canon = [...items].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map((t) => [
     t.id,
     t.title ?? "",
+    t.tags ?? [],
     t.cwd ?? "",
     t.createdAt ?? 0,
     Math.floor((t.activityAt ?? 0) / ACTIVITY_SIGNATURE_BUCKET_MS),
@@ -9675,6 +9823,7 @@ const LIST_SESSIONS_FORMAT = [
   "#{pane_current_path}",
   "#{@vh_title}",
   "#{@vh_title_manual}",
+  "#{@vh_tags}",
   // B-121: the control-mode client has no `pty.process`, so the agent-state
   // fast path lost its live `#{pane_current_command}` equivalent. Carry it in
   // the ONE list-sessions call the tracker already makes — the value goes
@@ -9689,8 +9838,8 @@ const LIST_SESSIONS_FORMAT = [
 function parseSessionListLine(line) {
   if (!line) return void 0;
   const parts = line.split(LIST_FIELD_SEP);
-  if (parts.length < 8) return void 0;
-  const [name, created, activity, cwd, vhTitle, manual, paneCommand] = parts;
+  if (parts.length < 9) return void 0;
+  const [name, created, activity, cwd, vhTitle, manual, vhTags, paneCommand] = parts;
   if (!name) return void 0;
   return {
     name,
@@ -9699,12 +9848,40 @@ function parseSessionListLine(line) {
     cwd: cwd || void 0,
     vhTitle: vhTitle.trim() || void 0,
     manual: manual.trim().length > 0,
+    tags: parseTerminalTags(vhTags),
     paneCurrentCommand: paneCommand.trim() || void 0,
     // pane_title is last, so anything after field 8 is title content that
     // contained the separator — rejoin it rather than dropping it.
-    paneTitle: parts.slice(7).join(LIST_FIELD_SEP) || void 0
+    paneTitle: parts.slice(8).join(LIST_FIELD_SEP) || void 0
   };
 }
+const TERMINAL_TAG_MAX_COUNT = 64;
+const TERMINAL_TAG_MAX_LENGTH = 24;
+const TERMINAL_TAGS_MAX_BYTES = 4096;
+function validateTerminalTags(value) {
+  if (!Array.isArray(value) || value.length > TERMINAL_TAG_MAX_COUNT) return void 0;
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const valueTag of value) {
+    if (typeof valueTag !== "string") return void 0;
+    const tag = valueTag.trim().replace(/^#+/, "").trim().replace(/\s+/g, "-").slice(0, TERMINAL_TAG_MAX_LENGTH);
+    if (!tag || tag !== valueTag) return void 0;
+    const key = tag.toLowerCase();
+    if (seen.has(key)) return void 0;
+    seen.add(key);
+    out.push(tag);
+  }
+  if (Buffer.byteLength(JSON.stringify(out), "utf8") > TERMINAL_TAGS_MAX_BYTES) return void 0;
+  return out;
+}
+function parseTerminalTags(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return [];
+  try {
+    return validateTerminalTags(JSON.parse(raw)) ?? [];
+  } catch {
+    return [];
+  }
+}
 function classifyPane(currentCommand, tail) {
   const cmd = (currentCommand || "").trim().replace(/^-/, "").toLowerCase();
   const isShell = SHELL_COMMANDS.has(cmd);
@@ -11137,6 +11314,8 @@ class WebTerminalManager {
         out.push({
           id,
           title,
+          // Always include [] so Web can feature-detect tag support.
+          tags: s.tags,
           cwd: s.cwd,
           createdAt: s.created,
           // tmux last-activity (epoch s) → ms; optional so old daemons
@@ -11314,6 +11493,25 @@ class WebTerminalManager {
       return false;
     }
   }
+  /** Persist terminal tags in tmux, parallel to @vh_title. */
+  setTags(terminalId, tags) {
+    if (!isTmuxAvailable()) return false;
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(terminalId)) return false;
+    const valid = validateTerminalTags(tags);
+    if (!valid) return false;
+    const name = `vh-${terminalId}`;
+    try {
+      const r = spawnSync("tmux", ["set-option", "-t", name, "@vh_tags", JSON.stringify(valid)], {
+        stdio: "ignore",
+        env: ptyEnv()
+      });
+      if (r.status !== 0) return false;
+      this.kickListRefresh();
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }
 
 const TMUX_TIMEOUT_MS = 3e3;
@@ -13085,6 +13283,7 @@ class ApiMachineClient {
   stopSessionHandler = null;
   listTrackedSessionIds = null;
   reconnectInterval = null;
+  handoverInFlight = null;
   // Terminals negotiated with `encStream` protect the live byte payload with
   // the per-machine key. This keeps it opaque to passive storage/forwarding
   // paths, but is not an operator trust boundary: the trusted relay can
@@ -13261,6 +13460,16 @@ class ApiMachineClient {
       }
       return { type: "success" };
     });
+    this.rpcHandlerManager.registerHandler("set-terminal-tags", async (params) => {
+      const { terminalId, tags } = params || {};
+      if (!terminalId || !Array.isArray(tags)) {
+        throw new Error("terminalId and tags are required");
+      }
+      if (!this.webTerminal.setTags(terminalId, tags)) {
+        throw new Error("Failed to set terminal tags (invalid tags, tmux unavailable, or session gone)");
+      }
+      return { type: "success" };
+    });
     this.rpcHandlerManager.registerHandler("stop-session", (params) => {
       const { sessionId } = params || {};
       if (!sessionId) {
@@ -13545,57 +13754,72 @@ class ApiMachineClient {
   connect() {
     const serverUrl = configuration.serverUrl.replace(/^http/, "ws");
     logger.debug(`[API MACHINE] Connecting to ${serverUrl}`);
-    this.socket = io(serverUrl, {
+    this.socket = this.createControlSocket();
+    const controlSocket = this.socket;
+    this.bindRealtimeHandlers(controlSocket, "control");
+    controlSocket.on("connect", () => {
+      if (this.socket !== controlSocket) return;
+      this.activateControlSocket(controlSocket);
+    });
+    controlSocket.on("disconnect", (reason) => {
+      logger.debug(`[API MACHINE] Disconnected from server \u2014 reason: ${reason}`);
+      this.rpcHandlerManager.onSocketDisconnect(controlSocket);
+      if (!this.relaySocket?.connected) this.webTerminal.resetSubscribers();
+      this.stopKeepAlive();
+      if (this.socket === controlSocket) this.startSmartReconnect();
+    });
+    this.bindControlDataHandlers(controlSocket);
+  }
+  createControlSocket(handover) {
+    const serverUrl = configuration.serverUrl.replace(/^http/, "ws");
+    return io(serverUrl, {
       transports: ["websocket"],
       auth: {
         token: this.token,
         clientType: "machine-scoped",
         machineId: this.machine.id,
-        happyClient: `cli-daemon/${configuration.currentCliVersion}`
+        happyClient: `cli-daemon/${configuration.currentCliVersion}`,
+        ...handover ? { handoverEpoch: handover.epoch } : {}
       },
+      ...handover ? { query: { vh_slot: handover.candidateSlot }, forceNew: true } : {},
       path: "/v1/updates",
-      reconnection: false
-    });
-    this.bindRealtimeHandlers(this.socket, "control");
-    this.socket.on("connect", () => {
-      logger.debug("[API MACHINE] Connected to server");
-      if (this.reconnectInterval) {
-        clearInterval(this.reconnectInterval);
-        this.reconnectInterval = null;
-      }
-      const initialTerminals = this.webTerminal.buildTerminalList();
-      this.webTerminal.primeListSignature(initialTerminals);
-      this.updateDaemonState((state) => {
-        const now = Date.now();
-        const currentState = withCurrentCliUpdateState(state, this.cliUpdateState);
-        return {
-          ...currentState,
-          status: "running",
-          pid: process.pid,
-          httpPort: this.machine.daemonState?.httpPort,
-          startedAt: now,
-          webTerminals: { updatedAt: now, terminals: initialTerminals },
-          // B-084: closed records survive daemon restarts (persisted
-          // in closed-terminals.json), so the connect snapshot ships
-          // them too — not just the incremental pushes.
-          closedTerminals: this.webTerminal.getClosedTerminals()
-        };
-      });
-      this.webTerminal.startListTracking((terminals) => this.pushTerminalList(terminals));
-      this.rpcHandlerManager.onSocketConnect(this.socket);
-      this.syncResumeSessionRpcRegistration();
-      this.startKeepAlive();
-      void this.reconcileArchivedSessions();
-      void this.refreshRelayConnection();
+      reconnection: false,
+      ...handover ? { autoConnect: false } : {}
     });
-    this.socket.on("disconnect", (reason) => {
-      logger.debug(`[API MACHINE] Disconnected from server \u2014 reason: ${reason}`);
-      this.rpcHandlerManager.onSocketDisconnect(this.socket);
-      if (!this.relaySocket?.connected) this.webTerminal.resetSubscribers();
-      this.stopKeepAlive();
-      this.startSmartReconnect();
+  }
+  activateControlSocket(socket, rpcAlreadyRegistered = false) {
+    logger.debug("[API MACHINE] Connected to server");
+    if (this.reconnectInterval) {
+      clearInterval(this.reconnectInterval);
+      this.reconnectInterval = null;
+    }
+    const initialTerminals = this.webTerminal.buildTerminalList();
+    this.webTerminal.primeListSignature(initialTerminals);
+    this.updateDaemonState((state) => {
+      const now = Date.now();
+      const currentState = withCurrentCliUpdateState(state, this.cliUpdateState);
+      return {
+        ...currentState,
+        status: "running",
+        pid: process.pid,
+        httpPort: this.machine.daemonState?.httpPort,
+        startedAt: now,
+        webTerminals: { updatedAt: now, terminals: initialTerminals },
+        // B-084: closed records survive daemon restarts (persisted
+        // in closed-terminals.json), so the connect snapshot ships
+        // them too — not just the incremental pushes.
+        closedTerminals: this.webTerminal.getClosedTerminals()
+      };
     });
-    this.socket.on("update", (data) => {
+    this.webTerminal.startListTracking((terminals) => this.pushTerminalList(terminals));
+    if (!rpcAlreadyRegistered) this.rpcHandlerManager.onSocketConnect(socket);
+    this.syncResumeSessionRpcRegistration();
+    this.startKeepAlive();
+    void this.reconcileArchivedSessions();
+    void this.refreshRelayConnection();
+  }
+  bindControlDataHandlers(socket) {
+    socket.on("update", (data) => {
       if (data.body.t === "update-machine" && data.body.machineId === this.machine.id) {
         const update = data.body;
         if (update.metadata) {
@@ -13612,13 +13836,83 @@ class ApiMachineClient {
         logger.debug(`[API MACHINE] Received unknown update type: ${data.body.t}`);
       }
     });
-    this.socket.on("connect_error", (error) => {
+    socket.on("connect_error", (error) => {
       logger.debug(`[API MACHINE] Connection error: ${error.message}`);
-      this.startSmartReconnect();
+      if (this.socket === socket) this.startSmartReconnect();
     });
-    this.socket.io.on("error", (error) => {
+    socket.io.on("error", (error) => {
       logger.debug("[API MACHINE] Socket error:", error);
     });
+    socket.on("server-draining", (data) => {
+      if (this.socket !== socket) return;
+      const parsed = ReleaseDrainNoticeSchema.safeParse(data);
+      if (!parsed.success || parsed.data.deadline <= Date.now()) return;
+      void this.startReleaseHandover(parsed.data);
+    });
+  }
+  startReleaseHandover(notice) {
+    if (this.handoverInFlight) return this.handoverInFlight;
+    this.handoverInFlight = this.releaseHandover(notice).finally(() => {
+      this.handoverInFlight = null;
+    });
+    return this.handoverInFlight;
+  }
+  async releaseHandover(notice) {
+    const startedAt = Date.now();
+    const previous = this.socket;
+    const candidate = this.createControlSocket(notice);
+    let commandsTransferred = false;
+    this.bindRpcRequestHandler(candidate, "control");
+    const timeoutMs = Math.max(1, Math.min(1e4, notice.deadline - Date.now()));
+    try {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("release handover timeout")), timeoutMs);
+        candidate.once("connect", () => {
+          clearTimeout(timer);
+          resolve();
+        });
+        candidate.once("connect_error", (error) => {
+          clearTimeout(timer);
+          reject(error);
+        });
+        candidate.connect();
+      });
+      await this.rpcHandlerManager.onSocketConnectAndWait(candidate, timeoutMs);
+      if (this.socket !== previous) {
+        this.rpcHandlerManager.onSocketDisconnect(candidate);
+        candidate.close();
+        return;
+      }
+      this.unbindMachineCommandHandlers(previous);
+      this.bindMachineCommandHandlers(candidate);
+      commandsTransferred = true;
+      this.bindControlDataHandlers(candidate);
+      this.socket = candidate;
+      candidate.on("connect", () => {
+        if (this.socket === candidate) this.activateControlSocket(candidate);
+      });
+      candidate.on("disconnect", () => {
+        this.rpcHandlerManager.onSocketDisconnect(candidate);
+        if (!this.relaySocket?.connected) this.webTerminal.resetSubscribers();
+        this.stopKeepAlive();
+        if (this.socket === candidate) this.startSmartReconnect();
+      });
+      this.activateControlSocket(candidate, true);
+      candidate.emit("release-handover-result", { result: "success", durationMs: Date.now() - startedAt });
+      this.rpcHandlerManager.onSocketDisconnect(previous);
+      previous.removeAllListeners("disconnect");
+      previous.close();
+    } catch (error) {
+      if (this.socket === candidate) this.socket = previous;
+      if (commandsTransferred) {
+        this.unbindMachineCommandHandlers(candidate);
+        this.bindMachineCommandHandlers(previous);
+      }
+      this.rpcHandlerManager.onSocketDisconnect(candidate);
+      candidate.close();
+      if (previous.connected) previous.emit("release-handover-result", { result: "failed", durationMs: Date.now() - startedAt });
+      logger.debug(`[API MACHINE] Release handover failed: ${error instanceof Error ? error.message : error}`);
+    }
   }
   startKeepAlive() {
     this.stopKeepAlive();
@@ -13652,11 +13946,13 @@ class ApiMachineClient {
     }, 2e4);
     logger.debug("[API MACHINE] Keep-alive started (20s interval)");
   }
-  bindRealtimeHandlers(socket, transport) {
+  bindRpcRequestHandler(socket, transport) {
     socket.on("rpc-request", async (data, callback) => {
       logger.debugLargeJson(`[API MACHINE] Received RPC request via ${transport}:`, data);
       callback(await this.rpcHandlerManager.handleRequest(data));
     });
+  }
+  bindMachineCommandHandlers(socket) {
     socket.on("terminal-input", (data) => {
       let payload = data.data;
       if (data.enc) {
@@ -13674,6 +13970,16 @@ class ApiMachineClient {
       logger.debug(`[API MACHINE] Server archived session ${data.sessionId}; local process stopped=${stopped}`);
     });
   }
+  unbindMachineCommandHandlers(socket) {
+    socket.removeAllListeners("terminal-input");
+    socket.removeAllListeners("terminal-resize");
+    socket.removeAllListeners("terminal-close");
+    socket.removeAllListeners("session-archive");
+  }
+  bindRealtimeHandlers(socket, transport) {
+    this.bindRpcRequestHandler(socket, transport);
+    this.bindMachineCommandHandlers(socket);
+  }
   /** Reconcile commands missed while the daemon was offline. The server
    * returns only ids owned by this account and durably archived in the DB. */
   async reconcileArchivedSessions() {