very-happy-cli 0.2.75 → 0.2.77

package/dist/{types-Dj9JEGDh.mjs → types-D2qSKjsO.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.75";
+var version = "0.2.77";
 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.75",
-	"very-happy-tools-x64-darwin": "0.2.75",
-	"very-happy-tools-arm64-linux": "0.2.75",
-	"very-happy-tools-x64-linux": "0.2.75",
-	"very-happy-tools-arm64-win32": "0.2.75",
-	"very-happy-tools-x64-win32": "0.2.75"
+	"very-happy-tools-arm64-darwin": "0.2.77",
+	"very-happy-tools-x64-darwin": "0.2.77",
+	"very-happy-tools-arm64-linux": "0.2.77",
+	"very-happy-tools-x64-linux": "0.2.77",
+	"very-happy-tools-arm64-win32": "0.2.77",
+	"very-happy-tools-x64-win32": "0.2.77"
 };
 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(),
@@ -1359,6 +1368,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();
@@ -2664,6 +2723,45 @@ class InvalidateSync {
   };
 }
 
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function firstNumber(source, keys) {
+  for (const key of keys) {
+    const value = finiteNonNegative(source[key]);
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function normalizeAgentUsage(raw) {
+  const outer = record(raw);
+  if (!outer) return null;
+  const wrapped = record(outer.totalTokenUsage) ?? record(outer.total_token_usage) ?? record(outer.total) ?? record(outer.usage) ?? outer;
+  const input = firstNumber(wrapped, ["inputTokens", "input_tokens", "input"]);
+  const output = firstNumber(wrapped, ["outputTokens", "output_tokens", "output"]);
+  const cacheRead = firstNumber(wrapped, ["cachedInputTokens", "cached_input_tokens", "cachedReadTokens", "cacheReadInputTokens", "cache_read_input_tokens", "cache_read"]);
+  const cacheCreation = firstNumber(wrapped, ["cacheCreationInputTokens", "cache_creation_input_tokens", "cachedWriteTokens", "cacheWriteInputTokens", "cache_write_input_tokens", "cache_creation"]);
+  const reasoning = firstNumber(wrapped, ["reasoningOutputTokens", "reasoning_output_tokens", "thoughtTokens", "reasoning"]);
+  const explicitTotal = firstNumber(wrapped, ["totalTokens", "total_tokens", "total"]);
+  const fallbackTotal = input !== void 0 || output !== void 0 ? (input ?? 0) + (output ?? 0) : void 0;
+  const total = explicitTotal ?? fallbackTotal;
+  if (total === void 0) return null;
+  return {
+    total,
+    ...input !== void 0 ? { input } : {},
+    ...output !== void 0 ? { output } : {},
+    ...cacheCreation !== void 0 ? { cache_creation: cacheCreation } : {},
+    ...cacheRead !== void 0 ? { cache_read: cacheRead } : {},
+    ...reasoning !== void 0 ? { reasoning } : {}
+  };
+}
+function usageAgentKey(agent) {
+  return agent.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+
 class ApiSessionClient extends EventEmitter {
   token;
   sessionId;
@@ -2704,12 +2802,24 @@ class ApiSessionClient extends EventEmitter {
     startedSubagents: /* @__PURE__ */ new Set(),
     activeSubagents: /* @__PURE__ */ new Set()
   };
+  seenClaudeUsageEvents = /* @__PURE__ */ new Set();
+  claudeUsageTotals = {
+    total: 0,
+    input: 0,
+    output: 0,
+    cache_creation: 0,
+    cache_read: 0,
+    costTotal: 0,
+    costInput: 0,
+    costOutput: 0
+  };
   lastSeq = 0;
   pendingOutbox = [];
   sendSync;
   receiveSync;
   directInboundLocalIds = /* @__PURE__ */ new Set();
   routedInboundLocalIds = /* @__PURE__ */ new Set();
+  handoverInFlight = null;
   constructor(token, session) {
     super();
     this.token = token;
@@ -2729,26 +2839,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();
     });
@@ -2757,12 +2856,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");
@@ -2833,8 +2932,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) {
@@ -3166,7 +3360,8 @@ class ApiSessionClient extends EventEmitter {
     }
     if (body.type === "assistant" && body.message?.usage) {
       try {
-        this.sendUsageData(body.message.usage, body.message.model);
+        const eventId = typeof body.uuid === "string" ? body.uuid : typeof body.message.id === "string" ? body.message.id : void 0;
+        this.sendUsageData(body.message.usage, body.message.model, eventId);
       } catch (error) {
         logger.debug("[SOCKET] Failed to send usage data:", error);
       }
@@ -3317,28 +3512,56 @@ class ApiSessionClient extends EventEmitter {
   /**
    * Send usage data to the server
    */
-  sendUsageData(usage, model) {
+  sendUsageData(usage, model, eventId) {
+    if (eventId && this.seenClaudeUsageEvents.has(eventId)) return;
+    if (eventId) this.seenClaudeUsageEvents.add(eventId);
     const totalTokens = usage.input_tokens + usage.output_tokens + (usage.cache_creation_input_tokens || 0) + (usage.cache_read_input_tokens || 0);
     const costs = calculateCost(usage, model);
+    this.claudeUsageTotals.total += totalTokens;
+    this.claudeUsageTotals.input += usage.input_tokens;
+    this.claudeUsageTotals.output += usage.output_tokens;
+    this.claudeUsageTotals.cache_creation += usage.cache_creation_input_tokens || 0;
+    this.claudeUsageTotals.cache_read += usage.cache_read_input_tokens || 0;
+    this.claudeUsageTotals.costTotal += costs.total;
+    this.claudeUsageTotals.costInput += costs.input;
+    this.claudeUsageTotals.costOutput += costs.output;
     const usageReport = {
+      // Keep the legacy key so upgrading replaces the old last-call row
+      // instead of making old + new clients double-count one session.
       key: "claude-session",
       sessionId: this.sessionId,
       tokens: {
-        total: totalTokens,
-        input: usage.input_tokens,
-        output: usage.output_tokens,
-        cache_creation: usage.cache_creation_input_tokens || 0,
-        cache_read: usage.cache_read_input_tokens || 0
+        total: this.claudeUsageTotals.total,
+        input: this.claudeUsageTotals.input,
+        output: this.claudeUsageTotals.output,
+        cache_creation: this.claudeUsageTotals.cache_creation,
+        cache_read: this.claudeUsageTotals.cache_read
       },
       cost: {
-        total: costs.total,
-        input: costs.input,
-        output: costs.output
+        total: this.claudeUsageTotals.costTotal,
+        input: this.claudeUsageTotals.costInput,
+        output: this.claudeUsageTotals.costOutput
       }
     };
     logger.debugLargeJson("[SOCKET] Sending usage data:", usageReport);
     this.socket.emit("usage-report", usageReport);
   }
+  /** Save a provider's cumulative session snapshot under one upsert key. */
+  sendAgentUsageSnapshot(agent, rawUsage) {
+    const tokens = normalizeAgentUsage(rawUsage);
+    if (!tokens) return false;
+    const usageReport = {
+      key: `usage:${usageAgentKey(agent)}:session`,
+      sessionId: this.sessionId,
+      tokens,
+      // Provider token-count events do not expose reliable billed cost.
+      // The Web treats this sentinel as unknown, not as real $0.00.
+      cost: { total: 0 }
+    };
+    logger.debugLargeJson("[SOCKET] Sending agent usage snapshot:", usageReport);
+    this.socket.emit("usage-report", usageReport);
+    return true;
+  }
   /**
    * Returns the latest session metadata known to the client.
    */
@@ -13006,6 +13229,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
@@ -13466,57 +13690,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) {
@@ -13533,13 +13772,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();
@@ -13573,11 +13882,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) {
@@ -13595,6 +13906,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() {