@allbluecn/web-app 0.23.6 → 0.24.0

package/src/components/layout/sidebar-03/__tests__/user-menu-cloud-logout.test.tsx

@@ -0,0 +1,185 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import type React from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// 桌面登出分支回归哨兵（A9 反向转移编排 + 会话来源判别）：
+// /api/auth/session 改为会回落桌面身份并带 desktopSession 标记后，clientSession
+// 不再为空——旧判据 `bridge && !clientSession` 会把云态登出错走成 authjs signOut
+// （数据留在云属主，桌面再也回不到 guest）。本文件钉死三条分支与编排顺序：
+// ① desktopSession=guest → 本地 guest 登出（不反向转移）
+// ② 无标记（本地 authjs 凭据登录）→ signOut（不反向转移）
+// ③ desktopSession=cloud → 反向转移编排（lock begin → reverse → clear → lock end）
+const H = vi.hoisted(() => ({
+  reload: vi.fn(),
+  queryClient: { clear: vi.fn(), resetQueries: vi.fn() },
+  reverseTransferOwnershipFn: vi.fn(async () => ({ tables: 1, rows: 1 })),
+  logoutRemoteFn: vi.fn(async () => ({ success: true })),
+  signOut: vi.fn(async () => ({ success: true })),
+  transferLock: vi.fn(async (_action?: 'begin' | 'end') => ({ ok: true })),
+  clearCloudSession: vi.fn(async () => ({ ok: true })),
+  // 由各用例覆盖：useSession() 的返回值
+  session: null as unknown,
+}))
+
+const CLOUD_SESSION = {
+  user: { id: 'cloud-1', name: '云用户', email: 'cloud@example.com', role: 'USER', isGuest: false },
+  expires: 'never',
+  desktopSession: 'cloud' as const,
+}
+const GUEST_SESSION = {
+  user: { id: 'local-guest', name: '本地用户', email: 'guest@localhost', role: 'USER', isGuest: true },
+  expires: 'never',
+  desktopSession: 'guest' as const,
+}
+const LOCAL_CREDENTIAL_SESSION = {
+  user: { id: 'authjs-user-1', name: '本地账号', email: 'local@example.com', role: 'USER', isGuest: false },
+  expires: '2026-12-31T00:00:00.000Z',
+}
+
+vi.mock('@/lib/auth/auth-client', () => ({
+  useSession: () => ({ data: H.session }),
+  signOut: H.signOut,
+}))
+vi.mock('@/lib/query-client-seam', () => ({
+  getQueryClient: () => H.queryClient,
+}))
+vi.mock('@/components/ui/sidebar', () => ({
+  SidebarMenu: ({ children }: { children?: React.ReactNode }) => <ul>{children}</ul>,
+  SidebarMenuItem: ({ children }: { children?: React.ReactNode }) => <li>{children}</li>,
+  SidebarMenuButton: ({ children, onClick }: { children?: React.ReactNode; onClick?: () => void }) => (
+    <button onClick={onClick}>{children}</button>
+  ),
+  useSidebar: () => ({ isMobile: false }),
+}))
+vi.mock('@/components/ui/toast', () => ({ toast: { success: vi.fn(), error: vi.fn(), info: vi.fn() } }))
+vi.mock('@/server/serverFns/auth/session', () => ({ logoutRemoteFn: H.logoutRemoteFn }))
+vi.mock('@/server/serverFns/sync/transfer', () => ({
+  reverseTransferOwnershipFn: H.reverseTransferOwnershipFn,
+}))
+vi.mock('@/lib/desktop-bridge-types', () => ({
+  getDesktopBridge: () => ({
+    transferLock: H.transferLock,
+    clearCloudSession: H.clearCloudSession,
+  }),
+}))
+vi.mock('@/components/shared-kit', () => ({
+  UserAvatar: ({ name }: { name?: string }) => <div data-testid="avatar">{name}</div>,
+}))
+vi.mock('@/components/magicui/sparkles-text', () => ({
+  SparklesText: ({ children }: { children?: React.ReactNode }) => <span>{children}</span>,
+}))
+vi.mock('@/components/ui/dropdown-menu', () => ({
+  DropdownMenu: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuTrigger: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuContent: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuGroup: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuItem: ({ children, onClick }: { children?: React.ReactNode; onClick?: () => void }) => (
+    <button type="button" onClick={onClick}>
+      {children}
+    </button>
+  ),
+  DropdownMenuLabel: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuSeparator: () => null,
+}))
+vi.mock('@tanstack/react-router', () => ({
+  useRouter: () => ({
+    navigate: vi.fn(),
+    state: { location: { pathname: '/dashboard', searchStr: '' } },
+  }),
+  useMatches: () => [],
+}))
+
+async function clickLogout() {
+  const { UserMenu } = await import('../user-menu')
+  render(<UserMenu />)
+  fireEvent.click(screen.getByText('退出登录'))
+}
+
+/** transferLock 某次调用的 invocationCallOrder（未调用 → -1） */
+function lockOrder(action: 'begin' | 'end'): number {
+  const idx = H.transferLock.mock.calls.findIndex((call) => call[0] === action)
+  return H.transferLock.mock.invocationCallOrder[idx] ?? -1
+}
+
+describe('UserMenu 桌面登出分支', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    try {
+      Object.defineProperty(window, 'location', {
+        configurable: true,
+        value: { ...window.location, reload: H.reload },
+      })
+    } catch {
+      /* jsdom 限制：后续断言只看转移链路 */
+    }
+  })
+
+  afterEach(() => {
+    cleanup()
+  })
+
+  it('③ desktopSession=cloud：走反向转移编排，不走 authjs signOut，最后整页 reload', async () => {
+    H.session = CLOUD_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.reverseTransferOwnershipFn).toHaveBeenCalledWith({ data: { cloudUserId: 'cloud-1' } })
+    })
+    expect(H.clearCloudSession).toHaveBeenCalledTimes(1)
+    expect(H.logoutRemoteFn).toHaveBeenCalledWith({ data: {} })
+    expect(H.queryClient.clear).toHaveBeenCalledTimes(1)
+    expect(H.signOut).not.toHaveBeenCalled()
+    // ④ 整页 reload（reload 后 getSessionFn 回落 guest 会话）
+    expect(H.reload).toHaveBeenCalledTimes(1)
+  }, 20000)
+
+  it('③ 编排顺序：lock begin → reverse → clearCloudSession → lock end → reload', async () => {
+    H.session = CLOUD_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.reload).toHaveBeenCalledTimes(1)
+    })
+
+    const begin = lockOrder('begin')
+    const end = lockOrder('end')
+    const reverse = H.reverseTransferOwnershipFn.mock.invocationCallOrder[0]!
+    const clear = H.clearCloudSession.mock.invocationCallOrder[0]!
+    const reload = H.reload.mock.invocationCallOrder[0]!
+
+    expect(begin).toBeGreaterThan(0)
+    expect(begin).toBeLessThan(reverse)
+    expect(reverse).toBeLessThan(clear)
+    // 先清云会话再解锁：引擎恢复 tick 前云会话必须已不可用
+    expect(clear).toBeLessThan(end)
+    expect(end).toBeLessThan(reload)
+  }, 20000)
+
+  it('① desktopSession=guest（local-guest）：本地 guest 登出，不触发反向转移', async () => {
+    H.session = GUEST_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.logoutRemoteFn).toHaveBeenCalledWith({ data: {} })
+    })
+    expect(H.reverseTransferOwnershipFn).not.toHaveBeenCalled()
+    expect(H.transferLock).not.toHaveBeenCalled()
+    expect(H.clearCloudSession).not.toHaveBeenCalled()
+    expect(H.queryClient.resetQueries).toHaveBeenCalled()
+    expect(H.reload).toHaveBeenCalledTimes(1)
+    expect(H.signOut).not.toHaveBeenCalled()
+  }, 20000)
+
+  it('② 本地 authjs 凭据登录（无 desktopSession 标记）：走 signOut，不触发反向转移', async () => {
+    H.session = LOCAL_CREDENTIAL_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.signOut).toHaveBeenCalledTimes(1)
+    })
+    expect(H.reverseTransferOwnershipFn).not.toHaveBeenCalled()
+    expect(H.transferLock).not.toHaveBeenCalled()
+    expect(H.clearCloudSession).not.toHaveBeenCalled()
+    expect(H.reload).not.toHaveBeenCalled()
+  }, 20000)
+})

package/src/components/layout/sidebar-03/app-sidebar.tsx

@@ -32,7 +32,7 @@ import { NavKnowledge } from "@/components/layout/sidebar-03/nav-knowledge";
 import { NavWorkspace } from "@/components/layout/sidebar-03/nav-workspace";
 import { UserMenu } from "@/components/layout/sidebar-03/user-menu";
 import { AnimatedThemeToggler } from '@/components/magicui/animated-theme-toggler'
-import { desktopAgentRoute, workspaceRoutes } from "@/config/sidebar-routes";
+import { workspaceRoutes } from "@/config/sidebar-routes";
 import type { Route } from "@/config/sidebar-routes";
 import { PresenceAvatarStack } from "@/components/layout/sidebar-03/presence-avatar-stack";
 import { SidebarSearchTrigger } from "@/components/layout/sidebar-03/nav-search-trigger"
@@ -40,7 +40,6 @@ import { NavSecondary } from "@/components/layout/sidebar-03/nav-secondary"
 import { PluginNavItems } from '@/components/plugin-slots/plugin-nav-items'
 import { isDesktopEdition } from "@/lib/edition-desktop";
 import { getDesktopBridge } from "@/lib/desktop-bridge-types";
-import { useDesktopAgentPresence } from "@/lib/desktop-agent/use-desktop-agent-presence";
 
 // presence 渲染工厂（§8.2 消费者两文件之一）：nav-main 按 route.id 查
 // MODULE_ROUTES 得 module key 后回调；module 级单例 map，identity 稳定。
@@ -48,16 +47,10 @@ const routes: Route[] = workspaceRoutes.map((route) => ({
   ...route,
   presence: (module: string) => <PresenceAvatarStack module={module} />,
 }));
-// 桌面壳追加本地文件助手入口（P3-B5）：module 级常量保 identity 稳定
-const routesWithDesktopAgent: Route[] = [...routes, desktopAgentRoute];
 
 export function DashboardSidebar() {
   const { state } = useSidebar();
   const isCollapsed = state === "collapsed";
-  // 本地文件助手入口门控（与 /_nav/agent 路由同源判定）：SSR / hydration 首帧恒
-  // pending（不渲染该项，首帧一致），挂载后桌面壳恢复；云 Web / OSS 恒不可见
-  const desktopAgentPresence = useDesktopAgentPresence();
-  const navRoutes = desktopAgentPresence === "present" ? routesWithDesktopAgent : routes;
   // 桌面壳（Electron hiddenInset）：红绿灯悬浮在窗口左上角，顶栏重排为
   // 「第一行红绿灯让位 + 右侧按钮组（整行可拖动窗口）、第二行 logo」。
   // web/云端 SaaS 布局不变（isDesktopEdition 为构建期常量，死分支消除）。
@@ -156,7 +149,7 @@ export function DashboardSidebar() {
         )}
       </SidebarHeader>
       <SidebarContent className="gap-4 px-2 py-4">
-        <DashboardNavigation routes={navRoutes} />
+        <DashboardNavigation routes={routes} />
         <NavWorkspace />
         <NavKnowledge />
         <PluginNavItems />

package/src/components/layout/sidebar-03/user-menu.tsx

@@ -23,11 +23,10 @@ import {
   Settings,
   Users,
 } from "lucide-react";
-import type { QueryClient } from "@tanstack/react-query";
 import { logoutRemoteFn } from '@/server/serverFns/auth/session'
 import { reverseTransferOwnershipFn } from '@/server/serverFns/sync/transfer'
 import { getDesktopBridge } from '@/lib/desktop-bridge-types'
-import type { DesktopBridgeApi } from '@/lib/desktop-bridge-types'
+import { runDesktopLogout } from '@/lib/desktop-logout'
 import { toast } from '@/components/ui/toast'
 
 import {
@@ -54,53 +53,29 @@ import { SparklesText } from "@/components/magicui/sparkles-text";
 import { m } from "@/paraglide/messages.js";
 
 /**
- * 桌面云态登出（桌面本地优先 P2-A9 反向转移编排，裁定顺序）：登出 = 把云身份名下
- * 数据翻回 guest（数据保留本机），双会话清理后回到 guest 态。
- * ① 置转移锁（transferLock，复用 bind 锁文件——引擎每 tick 判定同源，「转移进行中
- *   引擎勿 tick」；旧壳无此 IPC 优雅降级：反向转移单事务自身原子，锁为双保险）；
- * ② reverseTransferOwnershipFn（serverFn：校验 remoteAuth/会话本人 → 单事务
- *   cloud→guest + outbox/row_state 同事务清空防反向 op 上云 + 重建 guest 行；
- *   事务提交后 server 侧已清 remote-auth——崩窗口收敛，A8b 发现 2 的镜像）；
- * ③ 双会话清理：logoutRemoteFn（幂等 re-clear remote-auth）+ clearCloudSession
- *   （清 cloud-session.json，引擎 guest 守卫回 idle）→ 清锁（先清云会话再解锁，
- *   引擎恢复 tick 前云会话已不可用）；
- * ④ queryClient.clear() + 整页 reload——reload 后 getSessionFn 回落 guest 会话。
- * 失败路径（锁失败 / 转移失败）：解锁 + toast sync_logout_failed + 不 reload（留在
- * 云态可重试；转移失败单事务已回滚，数据仍是云属主，重试幂等）。模块内局部函数
- * （非导出）：本文件唯一导出是 UserMenu 组件，勿破坏 Fast Refresh 纯组件边界。
+ * 桌面云态登出（P2-A9 反向转移）：编排本体在 `@/lib/desktop-logout`（可测纯函数，
+ * 失败路径/调用顺序由单测钉死），此处只做**依赖装配**——bridge IPC、serverFn、
+ * queryClient 清空与整页 reload。顺序与失败语义见该模块文件头注释。
  */
 async function desktopCloudLogout(
-  bridge: DesktopBridgeApi,
+  bridge: NonNullable<ReturnType<typeof getDesktopBridge>>,
   cloudUserId: string,
-  queryClient: QueryClient,
+  queryClient: { clear: () => void },
 ): Promise<void> {
-  toast.info(m.sync_logout_in_progress());
-  // ① 转移锁
-  let lock: { ok: boolean; error?: string } = { ok: true };
-  try {
-    lock = bridge.transferLock ? await bridge.transferLock("begin") : { ok: true };
-  } catch {
-    lock = { ok: false };
-  }
-  if (!lock.ok) {
-    toast.error(m.sync_logout_failed());
-    return;
-  }
-  // ② 反向转移（失败：单事务回滚留在云态，解锁可重试）
-  try {
-    await reverseTransferOwnershipFn({ data: { cloudUserId } });
-  } catch {
-    try { await bridge.transferLock?.("end"); } catch { /* 尽力而为 */ }
-    toast.error(m.sync_logout_failed());
-    return;
-  }
-  // ③ 双会话清理（均幂等 best-effort：serverFn 已清 remote-auth，此处兜底）
-  try { await logoutRemoteFn({ data: {} }); } catch { /* 尽力而为 */ }
-  try { await bridge.clearCloudSession?.(); } catch { /* 尽力而为 */ }
-  try { await bridge.transferLock?.("end"); } catch { /* 尽力而为 */ }
-  // ④ 缓存清空 + 整页刷新（reload 后 desktop-state 回 guest）
-  queryClient.clear();
-  window.location.reload();
+  await runDesktopLogout(cloudUserId, {
+    // 旧壳无 transferLock IPC：省略 = 置锁成功 / 解锁 no-op（反向转移单事务自身原子）
+    lock: bridge.transferLock ? () => bridge.transferLock!("begin") : undefined,
+    unlock: bridge.transferLock ? () => bridge.transferLock!("end") : undefined,
+    transfer: (id) => reverseTransferOwnershipFn({ data: { cloudUserId: id } }),
+    logoutRemote: () => logoutRemoteFn({ data: {} }),
+    clearCloudSession: bridge.clearCloudSession ? () => bridge.clearCloudSession!() : undefined,
+    clearQueries: () => queryClient.clear(),
+    reload: () => window.location.reload(),
+    notify: (notice) => {
+      if (notice === "in-progress") toast.info(m.sync_logout_in_progress());
+      else toast.error(m.sync_logout_failed());
+    },
+  });
 }
 
 export function UserMenu() {
@@ -137,12 +112,14 @@ export function UserMenu() {
       window.location.reload();
       return;
     }
-    // 桌面云态（A9）：桌面壳存在且无本地 authjs 会话（clientSession 为空）＝当前
-    // 会话是 remote-auth 回落的轻量云身份，登出走反向转移编排（数据翻回 guest）。
-    // 本地凭据登录（clientSession 非空）与 web 照旧走 signOut 链——云身份回落仅在
-    // authjs 会话无效时生效，clientSession 为空是云态判别式。
+    // 桌面云态（A9）：桌面壳存在且会话来自云端回落＝当前身份是 remote-auth
+    // 的轻量云身份，登出走反向转移编排（数据翻回 guest）。
+    // 判据演进（桌面 guest 会话修复）：/api/auth/session 现会回落桌面身份并在
+    // 响应里带 desktopSession 标记，clientSession 不再为空——以标记为准；旧后端
+    // （无标记）保留「clientSession 为空」兜底。本地 authjs 凭据登录（无标记、
+    // clientSession 非空）与 web 照旧走 signOut 链。
     const bridge = getDesktopBridge();
-    if (bridge && !clientSession && user?.id) {
+    if (bridge && (!clientSession || clientSession.desktopSession === 'cloud') && user?.id) {
       await desktopCloudLogout(bridge, user.id, queryClient);
       return;
     }

package/src/components/shared-kit/auth/auth-client.ts

@@ -36,6 +36,10 @@ export interface Session {
     timezone?: string | null
   }
   expires: string
+  /** 桌面端会话来源标记（仅 /api/auth/session 的桌面回落响应携带）：
+   *  guest = 本地影子用户，cloud = remote-auth 云身份。web 部署与本地
+   *  authjs 凭据登录无此字段——云态登出编排（user-menu）据此区分二者。 */
+  desktopSession?: 'guest' | 'cloud'
 }
 
 export function useSession() {

package/src/config/sidebar-routes.tsx

@@ -26,7 +26,6 @@ import {
   Bug,
   PenTool,
   ListTodo,
-  FolderSearch,
 } from "lucide-react";
 
 export type RouteSubItem = {
@@ -102,15 +101,3 @@ export const workspaceRoutes: Route[] = [
     link: "/tasks",
   },
 ];
-
-/**
- * 本地文件助手（桌面本地优先 P3-B5）：依赖桌面壳 AgentService，不进上方常驻列表——
- * app-sidebar 经 useDesktopAgentPresence（桌面构建 + desktopBridge，mounted 模式）
- * 判定后条件追加，云 Web / OSS 恒不可见（与 /_nav/agent 路由门控同源）。
- */
-export const desktopAgentRoute: Route = {
-  id: "desktop-agent",
-  title: m.agent_desktop_title,
-  icon: <FolderSearch className="size-4" />,
-  link: "/agent",
-};

package/src/lib/__tests__/desktop-logout.test.ts

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 桌面云态登出编排单测（A9 反向转移）：钉死调用顺序与失败路径语义。
+// 编排是纯依赖注入函数（无 React / i18n / DOM），此处全部替身驱动，测的是
+// 「顺序、短路、best-effort 不阻塞」三件事，而不是各依赖自身实现。
+import { describe, expect, it, vi } from 'vitest'
+import { runDesktopLogout, type DesktopLogoutDeps } from '../desktop-logout'
+
+type Log = string[]
+
+/** 记录调用顺序的替身工厂（同一 Log 数组串起全部依赖） */
+function makeDeps(
+  log: Log,
+  overrides: Partial<DesktopLogoutDeps> = {},
+): DesktopLogoutDeps {
+  return {
+    lock: async () => {
+      log.push('lock')
+      return { ok: true }
+    },
+    transfer: async (userId) => {
+      log.push(`transfer:${userId}`)
+    },
+    logoutRemote: async () => {
+      log.push('logoutRemote')
+    },
+    clearCloudSession: async () => {
+      log.push('clearCloudSession')
+    },
+    unlock: async () => {
+      log.push('unlock')
+    },
+    clearQueries: () => {
+      log.push('clearQueries')
+    },
+    reload: () => {
+      log.push('reload')
+    },
+    ...overrides,
+  }
+}
+
+describe('runDesktopLogout —— 成功路径', () => {
+  it('调用顺序严格：lock → transfer → logoutRemote → clearCloudSession → unlock → clearQueries → reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout('cloud-user-1', makeDeps(log))
+
+    expect(status).toBe('done')
+    expect(log).toEqual([
+      'lock',
+      'transfer:cloud-user-1',
+      'logoutRemote',
+      'clearCloudSession',
+      'unlock',
+      'clearQueries',
+      'reload',
+    ])
+  })
+
+  it('notify 先发 in-progress，成功路径不发 failed', async () => {
+    const notices: string[] = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps([], { notify: (n) => notices.push(n) }),
+    )
+
+    expect(status).toBe('done')
+    expect(notices).toEqual(['in-progress'])
+  })
+
+  it('旧壳（无 transferLock / clearCloudSession IPC）：缺省即视为成功，仍走完并 reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        lock: undefined,
+        unlock: undefined,
+        clearCloudSession: undefined,
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log).toEqual(['transfer:u', 'logoutRemote', 'clearQueries', 'reload'])
+  })
+})
+
+describe('runDesktopLogout —— 失败路径（留在云态可重试）', () => {
+  it('置锁返回 ok=false → 不转移、不 reload，通知 failed', async () => {
+    const log: Log = []
+    const notices: string[] = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        lock: async () => ({ ok: false, error: 'locked' }),
+        notify: (n) => notices.push(n),
+      }),
+    )
+
+    expect(status).toBe('lock-failed')
+    expect(log).toEqual([])
+    expect(notices).toEqual(['in-progress', 'failed'])
+  })
+
+  it('置锁抛错 → 与 ok=false 同判（不转移、不 reload）', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        lock: async () => {
+          throw new Error('ipc down')
+        },
+      }),
+    )
+
+    expect(status).toBe('lock-failed')
+    expect(log).toEqual([])
+  })
+
+  it('转移失败 → 尽力解锁 + 通知 failed + 不 reload、不清缓存、不清双会话（保留云态可重试）', async () => {
+    const log: Log = []
+    const notices: string[] = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        transfer: async () => {
+          log.push('transfer')
+          throw new Error('transfer failed')
+        },
+        notify: (n) => notices.push(n),
+      }),
+    )
+
+    expect(status).toBe('transfer-failed')
+    expect(log).toEqual(['lock', 'transfer', 'unlock'])
+    expect(notices).toEqual(['in-progress', 'failed'])
+  })
+
+  it('转移失败且解锁也抛错 → 不误报状态、不 reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        transfer: async () => {
+          throw new Error('transfer failed')
+        },
+        unlock: async () => {
+          log.push('unlock')
+          throw new Error('unlock failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('transfer-failed')
+    expect(log).toEqual(['lock', 'unlock'])
+  })
+})
+
+describe('runDesktopLogout —— best-effort 不阻塞（既有实现语义）', () => {
+  it('解锁抛错 → 仍有 clearQueries + reload（reload 后引擎按 guest 守卫重判）', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        unlock: async () => {
+          log.push('unlock')
+          throw new Error('unlock failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log).toEqual([
+      'lock',
+      'transfer:u',
+      'logoutRemote',
+      'clearCloudSession',
+      'unlock',
+      'clearQueries',
+      'reload',
+    ])
+  })
+
+  it('清云会话失败 → 不阻塞解锁 / 清缓存 / reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        clearCloudSession: async () => {
+          log.push('clearCloudSession')
+          throw new Error('clear failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log.slice(-4)).toEqual(['clearCloudSession', 'unlock', 'clearQueries', 'reload'])
+    expect(log).toContain('clearQueries')
+  })
+
+  it('清 remote-auth 失败 → 不阻塞后续（云会话清理由 serverFn 侧完成）', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        logoutRemote: async () => {
+          log.push('logoutRemote')
+          throw new Error('logout remote failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log.slice(-3)).toEqual(['unlock', 'clearQueries', 'reload'])
+  })
+})
+
+describe('runDesktopLogout —— 依赖调用次数', () => {
+  it('成功路径每个依赖恰好一次；notify 只在最前发一次 in-progress', async () => {
+    const spy = {
+      lock: vi.fn(async () => ({ ok: true })),
+      transfer: vi.fn(async () => undefined),
+      logoutRemote: vi.fn(async () => undefined),
+      clearCloudSession: vi.fn(async () => ({ ok: true })),
+      unlock: vi.fn(async () => undefined),
+      clearQueries: vi.fn(),
+      reload: vi.fn(),
+      notify: vi.fn(),
+    }
+    await runDesktopLogout('cloud', spy)
+
+    for (const fn of [spy.lock, spy.transfer, spy.logoutRemote, spy.clearCloudSession, spy.unlock, spy.clearQueries, spy.reload]) {
+      expect(fn).toHaveBeenCalledTimes(1)
+    }
+    expect(spy.notify).toHaveBeenCalledTimes(1)
+    expect(spy.notify).toHaveBeenCalledWith('in-progress')
+  })
+})