fix: verify supervised update handoff in UI

shakkernerd · shakkernerd · commit 862790fbd7f4 · 2026-06-11T02:18:47.000+01:00
diff --git a/ui/src/ui/app-channels.test.ts b/ui/src/ui/app-channels.test.ts
@@ -73,6 +73,7 @@ function createHost(request: ReturnType<typeof vi.fn> = vi.fn()): ChannelsAction
     nostrProfileAccountId: null,
     nostrProfileFormState: null,
     pendingUpdateExpectedVersion: null,
+    pendingUpdateHandoff: false,
     settings: {},
     updateStatusBanner: null,
     updateRunning: false,
diff --git a/ui/src/ui/app-gateway-chat-load.node.test.ts b/ui/src/ui/app-gateway-chat-load.node.test.ts
@@ -209,6 +209,7 @@ function createHost(tab: Tab) {
     assistantAgentId: null,
     serverVersion: null,
     pendingUpdateExpectedVersion: null,
+    pendingUpdateHandoff: false,
     updateStatusBanner: null,
     sessionKey: "main",
     chatRunId: null,
diff --git a/ui/src/ui/app-gateway.node.test.ts b/ui/src/ui/app-gateway.node.test.ts
@@ -185,6 +185,7 @@ function createHost(): TestGatewayHost {
     localMediaPreviewRoots: [],
     serverVersion: null,
     pendingUpdateExpectedVersion: null,
+    pendingUpdateHandoff: false,
     updateStatusBanner: null,
     sessionKey: "main",
     chatMessages: [],
@@ -532,6 +533,92 @@ describe("connectGateway", () => {
     await vi.waitFor(() => {
       expect(host.pendingUpdateExpectedVersion).toBeNull();
     });
+    expect(host.pendingUpdateHandoff).toBe(false);
+    expect(host.updateStatusBanner).toBeNull();
+  });
+
+  it("clears managed-service handoff verification when update status completes", async () => {
+    const host = createHost();
+    host.pendingUpdateHandoff = true;
+
+    connectGateway(host);
+    const client = requireGatewayClient();
+    client.request.mockImplementation(async (method: string) => {
+      if (method === "update.status") {
+        return {
+          sentinel: {
+            kind: "update",
+            status: "ok",
+            stats: {
+              after: { version: "2.0.0" },
+            },
+          },
+        };
+      }
+      return {};
+    });
+
+    client.emitHello({
+      type: "hello-ok",
+      protocol: 4,
+      server: { version: "2.0.0" },
+      auth: { role: "operator", scopes: [] },
+      snapshot: {},
+    });
+
+    await vi.waitFor(() => {
+      expect(host.pendingUpdateHandoff).toBe(false);
+    });
+    expect(host.pendingUpdateExpectedVersion).toBeNull();
+    expect(host.updateStatusBanner).toBeNull();
+  });
+
+  it("keeps polling while managed-service handoff restart health is pending", async () => {
+    const host = createHost();
+    host.pendingUpdateHandoff = true;
+
+    connectGateway(host);
+    const client = requireGatewayClient();
+    let updateStatusCalls = 0;
+    client.request.mockImplementation(async (method: string) => {
+      if (method === "update.status") {
+        updateStatusCalls += 1;
+        if (updateStatusCalls === 1) {
+          return {
+            sentinel: {
+              kind: "update",
+              status: "skipped",
+              stats: {
+                reason: "restart-health-pending",
+              },
+            },
+          };
+        }
+        return {
+          sentinel: {
+            kind: "update",
+            status: "ok",
+            stats: {
+              after: { version: "2.0.0" },
+            },
+          },
+        };
+      }
+      return {};
+    });
+
+    client.emitHello({
+      type: "hello-ok",
+      protocol: 4,
+      server: { version: "2.0.0" },
+      auth: { role: "operator", scopes: [] },
+      snapshot: {},
+    });
+
+    await vi.waitFor(() => {
+      expect(updateStatusCalls).toBeGreaterThanOrEqual(2);
+      expect(host.pendingUpdateHandoff).toBe(false);
+    });
     expect(host.updateStatusBanner).toBeNull();
   });
 
@@ -566,6 +653,7 @@ describe("connectGateway", () => {
 
     await vi.waitFor(() => {
       expect(host.pendingUpdateExpectedVersion).toBeNull();
+      expect(host.pendingUpdateHandoff).toBe(false);
       expect(host.updateStatusBanner).toEqual({
         tone: "danger",
         text: "Update installed but running version did not change — restart may have been blocked. Expected v2.0.0, running v1.0.0.",
@@ -605,13 +693,52 @@ describe("connectGateway", () => {
 
     await vi.waitFor(() => {
       expect(host.pendingUpdateExpectedVersion).toBeNull();
+      expect(host.pendingUpdateHandoff).toBe(false);
       expect(host.updateStatusBanner).toEqual({
         tone: "danger",
         text: "Update error: restart-unhealthy. The replacement process never became healthy and the previous process stayed up.",
       });
     });
   });
 
+  it("surfaces managed-service handoff failures even without a final version", async () => {
+    const host = createHost();
+    host.pendingUpdateHandoff = true;
+
+    connectGateway(host);
+    const client = requireGatewayClient();
+    client.request.mockImplementation(async (method: string) => {
+      if (method === "update.status") {
+        return {
+          sentinel: {
+            kind: "update",
+            status: "error",
+            stats: {
+              reason: "managed-service-handoff-failed",
+            },
+          },
+        };
+      }
+      return {};
+    });
+
+    client.emitHello({
+      type: "hello-ok",
+      protocol: 4,
+      server: { version: "1.0.0" },
+      auth: { role: "operator", scopes: [] },
+      snapshot: {},
+    });
+
+    await vi.waitFor(() => {
+      expect(host.pendingUpdateHandoff).toBe(false);
+      expect(host.updateStatusBanner).toEqual({
+        tone: "danger",
+        text: "Update error: managed-service-handoff-failed. Check the gateway logs for the replacement failure.",
+      });
+    });
+  });
+
   it("ignores stale client onClose callbacks after reconnect", () => {
     const host = createHost();
 
diff --git a/ui/src/ui/app-gateway.ts b/ui/src/ui/app-gateway.ts
@@ -132,6 +132,7 @@ type GatewayHost = {
   assistantAgentId: string | null;
   serverVersion: string | null;
   pendingUpdateExpectedVersion: string | null;
+  pendingUpdateHandoff: boolean;
   updateStatusBanner: { tone: "danger" | "warn" | "info"; text: string } | null;
   sessionKey: string;
   sessionsShowArchived: boolean;
@@ -179,6 +180,12 @@ type GatewayHostWithSideResults = GatewayHost & {
 const SESSIONS_CHANGED_RELOAD_DEBOUNCE_MS = 5_000;
 const DEFERRED_SESSION_MESSAGE_REPLAY_POLL_MS = 250;
 const DEFERRED_SESSION_MESSAGE_REPLAY_TIMEOUT_MS = 10_000;
+const UPDATE_HANDOFF_STARTED_REASON = "managed-service-handoff-started";
+const UPDATE_RESTART_HEALTH_PENDING_REASON = "restart-health-pending";
+const PENDING_UPDATE_HANDOFF_REASONS = new Set([
+  UPDATE_HANDOFF_STARTED_REASON,
+  UPDATE_RESTART_HEALTH_PENDING_REASON,
+]);
 
 function enqueueApprovalRequest(host: GatewayHost, entry: ExecApprovalRequest | null) {
   if (!entry) {
@@ -281,12 +288,35 @@ function resolvePostRestartUpdateBanner(reason: string | null | undefined): {
   };
 }
 
+function resolvePendingUpdateHandoffTimeoutBanner(): {
+  tone: "danger";
+  text: string;
+} {
+  return {
+    tone: "danger",
+    text: "Update handoff started, but completion was not reported after reconnect. Run `openclaw update status` for the final result.",
+  };
+}
+
+function isPendingUpdateHandoffSentinel(
+  sentinel: UpdateRestartStatusResponse["sentinel"],
+): boolean {
+  const reason = sentinel?.stats?.reason;
+  return (
+    sentinel?.kind === "update" &&
+    sentinel.status === "skipped" &&
+    typeof reason === "string" &&
+    PENDING_UPDATE_HANDOFF_REASONS.has(reason)
+  );
+}
+
 async function verifyPendingUpdateVersion(
   host: GatewayHost,
   client: GatewayBrowserClient,
 ): Promise<void> {
   const expectedVersion = host.pendingUpdateExpectedVersion?.trim();
-  if (!expectedVersion) {
+  const pendingHandoff = host.pendingUpdateHandoff;
+  if (!expectedVersion && !pendingHandoff) {
     return;
   }
   const deadline = Date.now() + 10_000;
@@ -298,14 +328,33 @@ async function verifyPendingUpdateVersion(
       response = null;
     }
     const sentinel = response?.sentinel;
+    if (isPendingUpdateHandoffSentinel(sentinel)) {
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 250);
+      });
+      continue;
+    }
+    if (sentinel?.kind === "update" && sentinel.status && sentinel.status !== "ok") {
+      host.pendingUpdateExpectedVersion = null;
+      host.pendingUpdateHandoff = false;
+      host.updateStatusBanner = resolvePostRestartUpdateBanner(sentinel.stats?.reason ?? null);
+      return;
+    }
     const actualVersion = sentinel?.stats?.after?.version?.trim() || null;
+    if (
+      sentinel?.kind === "update" &&
+      sentinel.status === "ok" &&
+      !actualVersion &&
+      !expectedVersion
+    ) {
+      host.pendingUpdateExpectedVersion = null;
+      host.pendingUpdateHandoff = false;
+      return;
+    }
     if (sentinel?.kind === "update" && actualVersion) {
       host.pendingUpdateExpectedVersion = null;
-      if (sentinel.status && sentinel.status !== "ok") {
-        host.updateStatusBanner = resolvePostRestartUpdateBanner(sentinel.stats?.reason ?? null);
-        return;
-      }
-      if (actualVersion !== expectedVersion) {
+      host.pendingUpdateHandoff = false;
+      if (expectedVersion && actualVersion !== expectedVersion) {
         host.updateStatusBanner = resolveUpdateVerificationBanner({
           expectedVersion,
           actualVersion,
@@ -322,11 +371,14 @@ async function verifyPendingUpdateVersion(
   }
   const currentVersion = host.hello?.server?.version?.trim() || null;
   host.pendingUpdateExpectedVersion = null;
-  if (currentVersion !== expectedVersion) {
+  host.pendingUpdateHandoff = false;
+  if (expectedVersion && currentVersion !== expectedVersion) {
     host.updateStatusBanner = resolveUpdateVerificationBanner({
       expectedVersion,
       actualVersion: currentVersion,
     });
+  } else if (pendingHandoff) {
+    host.updateStatusBanner = resolvePendingUpdateHandoffTimeoutBanner();
   }
 }
 
diff --git a/ui/src/ui/app-view-state.ts b/ui/src/ui/app-view-state.ts
@@ -234,6 +234,7 @@ export type AppViewState = {
   configActiveSection: string | null;
   configActiveSubsection: string | null;
   pendingUpdateExpectedVersion: string | null;
+  pendingUpdateHandoff: boolean;
   updateStatusBanner: { tone: "danger" | "warn" | "info"; text: string } | null;
   communicationsFormMode: "form" | "raw";
   communicationsSearchQuery: string;
diff --git a/ui/src/ui/app.ts b/ui/src/ui/app.ts
@@ -404,6 +404,7 @@ export class OpenClawApp extends LitElement {
   @state() configActiveSection: string | null = null;
   @state() configActiveSubsection: string | null = null;
   @state() pendingUpdateExpectedVersion: string | null = null;
+  @state() pendingUpdateHandoff = false;
   @state() updateStatusBanner: { tone: "danger" | "warn" | "info"; text: string } | null = null;
   @state() communicationsFormMode: "form" | "raw" = "form";
   @state() communicationsSearchQuery = "";
diff --git a/ui/src/ui/controllers/agents.test.ts b/ui/src/ui/controllers/agents.test.ts
@@ -77,6 +77,7 @@ function createSaveState(): {
       configActiveSection: null,
       configActiveSubsection: null,
       pendingUpdateExpectedVersion: null,
+      pendingUpdateHandoff: false,
       updateStatusBanner: null,
       lastError: null,
     },
diff --git a/ui/src/ui/controllers/config.test.ts b/ui/src/ui/controllers/config.test.ts
@@ -45,6 +45,7 @@ function createState(): ConfigState {
     connected: false,
     lastError: null,
     pendingUpdateExpectedVersion: null,
+    pendingUpdateHandoff: false,
     updateStatusBanner: null,
     updateRunning: false,
   };
@@ -1157,6 +1158,27 @@ describe("runUpdate", () => {
     await runUpdate(state);
 
     expect(state.pendingUpdateExpectedVersion).toBe("2.0.0");
+    expect(state.pendingUpdateHandoff).toBe(false);
+    expect(state.updateStatusBanner).toBeNull();
+  });
+
+  it("tracks managed-service handoff updates for reconnect verification", async () => {
+    const request = vi.fn().mockResolvedValue({
+      ok: true,
+      result: {
+        status: "skipped",
+        reason: "managed-service-handoff-started",
+      },
+      handoff: { status: "started" },
+    });
+    const state = createState();
+    state.connected = true;
+    state.client = { request } as unknown as ConfigState["client"];
+
+    await runUpdate(state);
+
+    expect(state.pendingUpdateExpectedVersion).toBeNull();
+    expect(state.pendingUpdateHandoff).toBe(true);
     expect(state.updateStatusBanner).toBeNull();
   });
 });
diff --git a/ui/src/ui/controllers/config.ts b/ui/src/ui/controllers/config.ts
