@allbluecn/web-app 0.23.2 → 0.23.4

package/src/routeTree.gen.ts

@@ -23,6 +23,7 @@ import { Route as LoginLoginRouteRouteImport } from './routes/_login/login/route
 import { Route as LoginRegisterRouteRouteImport } from './routes/_login/register/route'
 import { Route as LoginResetPasswordRouteRouteImport } from './routes/_login/reset-password/route'
 import { Route as LoginVerifyEmailRouteRouteImport } from './routes/_login/verify-email/route'
+import { Route as NavAgentRouteRouteImport } from './routes/_nav/agent/route'
 import { Route as NavAppsRouteRouteImport } from './routes/_nav/apps/route'
 import { Route as NavBugsRouteRouteImport } from './routes/_nav/bugs/route'
 import { Route as NavChangelogRouteRouteImport } from './routes/_nav/changelog/route'
@@ -251,6 +252,13 @@ const LoginVerifyEmailRouteRoute = LoginVerifyEmailRouteRouteImport.update({
 } as any).lazy(() =>
   import('./routes/_login/verify-email/route.lazy').then((d) => d.Route),
 )
+const NavAgentRouteRoute = NavAgentRouteRouteImport.update({
+  id: '/agent',
+  path: '/agent',
+  getParentRoute: () => NavRouteRoute,
+} as any).lazy(() =>
+  import('./routes/_nav/agent/route.lazy').then((d) => d.Route),
+)
 const NavAppsRouteRoute = NavAppsRouteRouteImport.update({
   id: '/apps',
   path: '/apps',
@@ -1123,6 +1131,7 @@ export interface FileRoutesByFullPath {
   '/register': typeof LoginRegisterRouteRoute
   '/reset-password': typeof LoginResetPasswordRouteRoute
   '/verify-email': typeof LoginVerifyEmailRouteRoute
+  '/agent': typeof NavAgentRouteRoute
   '/apps': typeof NavAppsRouteRouteWithChildren
   '/bugs': typeof NavBugsRouteRouteWithChildren
   '/changelog': typeof NavChangelogRouteRoute
@@ -1262,6 +1271,7 @@ export interface FileRoutesByTo {
   '/register': typeof LoginRegisterRouteRoute
   '/reset-password': typeof LoginResetPasswordRouteRoute
   '/verify-email': typeof LoginVerifyEmailRouteRoute
+  '/agent': typeof NavAgentRouteRoute
   '/apps': typeof NavAppsRouteRouteWithChildren
   '/changelog': typeof NavChangelogRouteRoute
   '/dashboard': typeof NavDashboardRouteRoute
@@ -1390,6 +1400,7 @@ export interface FileRoutesById {
   '/_login/register': typeof LoginRegisterRouteRoute
   '/_login/reset-password': typeof LoginResetPasswordRouteRoute
   '/_login/verify-email': typeof LoginVerifyEmailRouteRoute
+  '/_nav/agent': typeof NavAgentRouteRoute
   '/_nav/apps': typeof NavAppsRouteRouteWithChildren
   '/_nav/bugs': typeof NavBugsRouteRouteWithChildren
   '/_nav/changelog': typeof NavChangelogRouteRoute
@@ -1531,6 +1542,7 @@ export interface FileRouteTypes {
     | '/register'
     | '/reset-password'
     | '/verify-email'
+    | '/agent'
     | '/apps'
     | '/bugs'
     | '/changelog'
@@ -1670,6 +1682,7 @@ export interface FileRouteTypes {
     | '/register'
     | '/reset-password'
     | '/verify-email'
+    | '/agent'
     | '/apps'
     | '/changelog'
     | '/dashboard'
@@ -1797,6 +1810,7 @@ export interface FileRouteTypes {
     | '/_login/register'
     | '/_login/reset-password'
     | '/_login/verify-email'
+    | '/_nav/agent'
     | '/_nav/apps'
     | '/_nav/bugs'
     | '/_nav/changelog'
@@ -2059,6 +2073,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LoginVerifyEmailRouteRouteImport
       parentRoute: typeof LoginRouteRoute
     }
+    '/_nav/agent': {
+      id: '/_nav/agent'
+      path: '/agent'
+      fullPath: '/agent'
+      preLoaderRoute: typeof NavAgentRouteRouteImport
+      parentRoute: typeof NavRouteRoute
+    }
     '/_nav/apps': {
       id: '/_nav/apps'
       path: '/apps'
@@ -3351,6 +3372,7 @@ const NavChatRouteWithChildren =
   NavChatRoute._addFileChildren(NavChatRouteChildren)
 
 interface NavRouteRouteChildren {
+  NavAgentRouteRoute: typeof NavAgentRouteRoute
   NavAppsRouteRoute: typeof NavAppsRouteRouteWithChildren
   NavBugsRouteRoute: typeof NavBugsRouteRouteWithChildren
   NavChangelogRouteRoute: typeof NavChangelogRouteRoute
@@ -3372,6 +3394,7 @@ interface NavRouteRouteChildren {
 }
 
 const NavRouteRouteChildren: NavRouteRouteChildren = {
+  NavAgentRouteRoute: NavAgentRouteRoute,
   NavAppsRouteRoute: NavAppsRouteRouteWithChildren,
   NavBugsRouteRoute: NavBugsRouteRouteWithChildren,
   NavChangelogRouteRoute: NavChangelogRouteRoute,

package/src/routes/-tests/agent-gate.test.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手页（/_nav/agent）路由门控（桌面本地优先 P3-B5）：依赖桌面壳
+// AgentService，云 Web / OSS 构建无此页——beforeLoad 以构建期常量
+// isDesktopEdition（VITE_DEPLOY_TARGET）判定，非桌面构建直接 throw notFound
+// （SSR 即 404，无占位闪烁）。运行时的桥探测（useDesktopAgentPresence）另由
+// lib/desktop-agent/__tests__/use-desktop-agent-presence.test.tsx 覆盖。
+// 断言方式同 -edition-routing.test.tsx：直接调 Route.options.beforeLoad。
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+async function importAgentRoute(desktop: boolean) {
+  vi.resetModules()
+  vi.doMock('@/lib/edition-desktop', () => ({ isDesktopEdition: () => desktop }))
+  return import('../_nav/agent/route')
+}
+
+/** beforeLoad 抛出的 notFound 对象（@tanstack/router-core：{ isNotFound: true }） */
+function catchNotFound(fn: () => unknown): { isNotFound?: boolean } | null {
+  try {
+    fn()
+    return null
+  } catch (error) {
+    return error as { isNotFound?: boolean }
+  }
+}
+
+afterEach(() => {
+  vi.doUnmock('@/lib/edition-desktop')
+  vi.resetModules()
+})
+
+describe('/_nav/agent beforeLoad 门控', () => {
+  it('非桌面构建（云 Web / OSS）：throw notFound（页面不存在，SSR 即 404）', async () => {
+    const { Route } = await importAgentRoute(false)
+    const result = catchNotFound(() => Route.options.beforeLoad!({} as never))
+    expect(result?.isNotFound).toBe(true)
+  })
+
+  it('桌面构建：放行（运行时无桥由 lazy 组件的 useDesktopAgentPresence 落到 NotFound）', async () => {
+    const { Route } = await importAgentRoute(true)
+    expect(Route.options.beforeLoad!({} as never)).toBeUndefined()
+  })
+})

package/src/routes/_nav/agent/route.lazy.tsx

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手页（桌面本地优先 P3-B5）：授权目录卡 + agent 对话区。门控说明见
+// 同目录 route.tsx；本文件承担运行时桥探测（mounted 模式：SSR / hydration 首帧
+// 渲染空白、不读 window，挂载后 Electron 恢复页面，无桥即 NotFound）。
+//
+// 双层判定：presence（含 agentPort 装配，见 lib/desktop-agent/availability）决定
+// 页面是否可达；isAgentWorkspaceSupported（B1 三方法）决定目录授权是否可用——
+// 旧壳缺三方法时整页只留升级提示，不渲染对话区（否则对话区「请先添加授权目录」
+// 与卡片「请升级客户端」互相打脸）。
+import { useState } from 'react'
+import { createLazyFileRoute } from '@tanstack/react-router'
+import { useQuery } from '@tanstack/react-query'
+import { AgentChat } from '@/components/desktop-agent/agent-chat'
+import { AgentWorkspaceCard } from '@/components/desktop-agent/agent-workspace-card'
+import { isAgentWorkspaceSupported } from '@/lib/desktop-agent/availability'
+import { useDesktopAgentPresence } from '@/lib/desktop-agent/use-desktop-agent-presence'
+import { desktopAgentWorkspacesQueryOptions } from '@/lib/queries/desktop-agent'
+import { m } from '@/paraglide/messages.js'
+import { NavNotFound } from '../-components/nav-not-found'
+
+export const Route = createLazyFileRoute('/_nav/agent')({
+  component: DesktopAgentRoute,
+})
+
+function DesktopAgentRoute() {
+  const presence = useDesktopAgentPresence()
+  if (presence === 'pending') return null
+  if (presence === 'absent') return <NavNotFound />
+  return <DesktopAgentPage />
+}
+
+function DesktopAgentPage() {
+  const supportsWorkspaces = isAgentWorkspaceSupported()
+  // enabled 与卡片同口径：不支持目录授权时不查清单，避免无效 IPC
+  const { data: workspaces = [] } = useQuery({
+    ...desktopAgentWorkspacesQueryOptions(),
+    enabled: supportsWorkspaces,
+  })
+  const [picked, setPicked] = useState<string | null>(null)
+  const [running, setRunning] = useState(false)
+  // 未选择 / 选中项已被撤销 → 回落清单首项（清单为空则 null，对话区禁用输入）
+  const cwd = picked !== null && workspaces.includes(picked) ? picked : (workspaces[0] ?? null)
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-4 overflow-hidden p-6">
+      <header className="space-y-1">
+        <h1 className="text-lg font-semibold">{m.agent_desktop_title()}</h1>
+        <p className="text-sm text-muted-foreground">{m.agent_desktop_pageDescription()}</p>
+      </header>
+      <div className="flex min-h-0 flex-1 flex-col gap-4 lg:flex-row">
+        <div className="shrink-0 lg:w-80 lg:overflow-y-auto">
+          <AgentWorkspaceCard selected={cwd} onSelect={setPicked} disabled={running} />
+        </div>
+        {/* 旧壳（无目录授权 IPC）只留卡片里的升级提示；否则每个目录一份会话
+            （换目录即新会话，运行中由 disabled 锁定切换） */}
+        {supportsWorkspaces && <AgentChat key={cwd ?? 'none'} cwd={cwd} onRunningChange={setRunning} />}
+      </div>
+    </div>
+  )
+}

package/src/routes/_nav/agent/route.tsx

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手（桌面本地优先 P3-B5）：依赖桌面壳的 AgentService，云 Web / OSS
+// 部署无此页。门控三层，保证「入口可见 ⟹ 页面可达」：
+// ① beforeLoad：构建期常量 isDesktopEdition()（VITE_DEPLOY_TARGET，同构执行、SSR
+//   安全——与 settings/sync、_public/index 的 beforeLoad 同口径），非桌面构建直接
+//   notFound（服务端即 404，无占位闪烁）；
+// ② lazy 组件：挂载后 getDesktopBridge() 运行时探测（useDesktopAgentPresence）——
+//   桌面构建被浏览器直开 backend 端口（无桥）→ NotFound；
+// ③ 侧栏入口：同一 presence 判定条件渲染（app-sidebar）。
+// 无 loader：授权清单走 react-query 工厂（lib/queries/desktop-agent，IPC 数据源）。
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { isDesktopEdition } from '@/lib/edition-desktop'
+
+export const Route = createFileRoute('/_nav/agent')({
+  beforeLoad: () => {
+    if (!isDesktopEdition()) throw notFound()
+  },
+})

package/src/routes/api/sync/account-status.ts

@@ -4,13 +4,13 @@
 
 // account-status 端点（桌面本地优先 P2-A5，迁移设计归属转移前置核对）：桌面端绑定
 // 云账号前探测目标账号是否「空账号」——仅空账号才走归属转移（一期唯一路径）。
-// 空账号口径（复审⑥ P1-9 扩容）：当前用户六表 count 全 0——stories/bugs/testCases
-// /projects 之外计入 knowledgeBases/knowledgeDocuments，防仅有知识库数据的云账号
-// 被误判空而清掉知识库。属主字段：story/bug/testCase → createdById、project →
-// ownerId、knowledgeBase → userId、knowledgeDocument → createdBy（schema 实查）。
+// 六表 count 口径与属主字段实查收敛在 server/sync/account-status.ts 的
+// isAccountEmpty（A8a 抽取，transferOwnershipFn 复核复用同源），此处只做
+// requireAuth + 响应映射。
 import { createFileRoute } from "@tanstack/react-router"
 import { getPrisma } from "@allbluecn/database/get-prisma"
 import { requireAuth, UnauthorizedError } from "@/server/auth-helpers"
+import { isAccountEmpty } from "@/server/sync/account-status"
 
 export const Route = createFileRoute("/api/sync/account-status")({
   server: {
@@ -21,23 +21,7 @@ export const Route = createFileRoute("/api/sync/account-status")({
           const userId = session.user.id
 
           const prisma = await getPrisma()
-          const [stories, bugs, testCases, projects, knowledgeBases, knowledgeDocuments] =
-            await Promise.all([
-              prisma.story.count({ where: { createdById: userId } }),
-              prisma.bug.count({ where: { createdById: userId } }),
-              prisma.testCase.count({ where: { createdById: userId } }),
-              prisma.project.count({ where: { ownerId: userId } }),
-              prisma.knowledgeBase.count({ where: { userId } }),
-              prisma.knowledgeDocument.count({ where: { createdBy: userId } }),
-            ])
-
-          const empty =
-            stories === 0 &&
-            bugs === 0 &&
-            testCases === 0 &&
-            projects === 0 &&
-            knowledgeBases === 0 &&
-            knowledgeDocuments === 0
+          const empty = await isAccountEmpty(prisma, userId)
 
           return Response.json({ empty })
         } catch (e) {

package/src/server/__tests__/exchange-remote-token.test.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// exchangeRemoteTokenFn 双路径落盘测试（A10 修复，控制者核实缺口）：
+// session 块（remote-auth.json 的 session.userId/planName，readRemoteAuth 登录态
+// 唯一依据）必须两条成功路径都写——原先仅降级路径写，生产 SaaS 恒发 signedToken
+// → signedToken 路径云身份 100% 不激活 + 云态写入属主错为 guest。
+// mock 惯例照 desktop-bootstrap.test.ts（csv-export 样板）：createServerFn 捕获器
+// 直调 handler；SaaS fetch 用 vi.stubGlobal 拦截，remote-auth/entitlements-token
+// /rate-limit 全 mock（不真写盘、不真限流）。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const H = vi.hoisted(() => ({
+  writeRemoteAuth: vi.fn(),
+  writeRemoteSession: vi.fn(),
+  generateEntitlementsToken: vi.fn(),
+  checkAuthRateLimit: vi.fn(),
+  fetch: vi.fn(),
+}))
+
+vi.mock('@tanstack/react-start', () => {
+  // 每个 serverFn 实例独立 capture（session.ts 有三个 serverFn，防串号）
+  const createServerFn = () => {
+    const capture: { validator?: unknown; handler?: unknown } = {}
+    const api = {
+      validator: (v: unknown) => {
+        capture.validator = v
+        return api
+      },
+      middleware: () => api,
+      handler: (h: unknown) => {
+        capture.handler = h
+        return async (args?: { data?: unknown }) => {
+          const v = capture.validator as { parse?: (d: unknown) => unknown } | undefined
+          const data = v && typeof v.parse === 'function' ? v.parse(args?.data) : args?.data
+          return (capture.handler as (p: { data?: unknown }) => unknown)({ data })
+        }
+      },
+    }
+    return api
+  }
+  return { createServerFn }
+})
+
+vi.mock('@tanstack/react-start/server', () => ({ getRequest: () => ({}) }))
+
+vi.mock('@/lib/session', () => ({ getCurrentSession: vi.fn(async () => null) }))
+
+vi.mock('@/server/desktop-bootstrap', () => ({ ensureLocalShadowUser: vi.fn() }))
+
+vi.mock('@/server/remote-auth', () => ({
+  readRemoteAuth: vi.fn(async () => null),
+  writeRemoteAuth: H.writeRemoteAuth,
+  writeRemoteSession: H.writeRemoteSession,
+  clearRemoteAuth: vi.fn(),
+}))
+
+vi.mock('@/server/entitlements-token', () => ({
+  generateEntitlementsToken: H.generateEntitlementsToken,
+}))
+
+vi.mock('@/server/middlewares/rate-limit', () => ({ checkAuthRateLimit: H.checkAuthRateLimit }))
+
+import { exchangeRemoteTokenFn } from '../serverFns/auth/session'
+
+describe('exchangeRemoteTokenFn 双路径落盘（A10 修复）', () => {
+  const saved = process.env.DEPLOY_TARGET
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+    vi.stubGlobal('fetch', H.fetch)
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+    if (saved === undefined) delete process.env.DEPLOY_TARGET
+    else process.env.DEPLOY_TARGET = saved
+  })
+
+  it('signedToken 路径（生产 SaaS 恒发）：session 块 + token 双写', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    H.fetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        user: { id: 'cloud-1', name: 'Cloud 用户', email: 'cloud@example.com' },
+        planName: 'pro',
+        features: { sync: true },
+        signedToken: 'signed-abc',
+      }),
+    })
+    const res = await exchangeRemoteTokenFn({ data: { token: 'tok-123' } })
+    expect(res).toEqual({ success: true, userId: 'cloud-1', planName: 'pro' })
+    // 修复断言：session 块必须落盘（缺它 readRemoteAuth 恒 null → 云身份不激活）
+    expect(H.writeRemoteSession).toHaveBeenCalledWith('cloud-1', 'pro', 'tok-123')
+    expect(H.writeRemoteAuth).toHaveBeenCalledWith('signed-abc', 'tok-123')
+    expect(H.generateEntitlementsToken).not.toHaveBeenCalled()
+  })
+
+  it('degraded 路径（本地无签名 secret）：仅写 session 块，不写 writeRemoteAuth', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    H.fetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ user: { id: 'cloud-2' }, planName: 'free' }),
+    })
+    H.generateEntitlementsToken.mockResolvedValue(null)
+    const res = await exchangeRemoteTokenFn({ data: { token: 'tok-456' } })
+    expect(res).toEqual({ success: true, userId: 'cloud-2', planName: 'free', degraded: true })
+    expect(H.writeRemoteSession).toHaveBeenCalledWith('cloud-2', 'free', 'tok-456')
+    expect(H.writeRemoteAuth).not.toHaveBeenCalled()
+  })
+})

package/src/server/__tests__/remote-auth.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
 import { promises as fs } from "node:fs"
 import os from "node:os"
 import path from "node:path"
@@ -70,3 +70,133 @@ describe("remote-auth（Electron fs 持久层）", () => {
     expect(await readRemoteAuth()).toBeNull()
   })
 })
+
+// ---------- A12 desktop codec 接缝（safeStorage 透明加解密） ----------
+
+// stub codec（Pro 域 entry.cjs/main.ts 注入的 globalThis.__allblueDesktopCodec
+// 同契约形态：XOR 对称可逆，密文经 enc:v1: 前缀 + base64 落盘，与真实现等价）
+function stubCodec() {
+  const KEY = 0x5a
+  const xor = (b: Buffer) => Buffer.from([...b].map((x) => x ^ KEY))
+  return {
+    encrypt: async (plain: string) => `enc:v1:${xor(Buffer.from(plain, "utf8")).toString("base64")}`,
+    decrypt: async (raw: string) => {
+      if (!raw.startsWith("enc:v1:")) return raw
+      return xor(Buffer.from(raw.slice("enc:v1:".length), "base64")).toString("utf8")
+    },
+  }
+}
+
+describe("remote-auth desktop codec 接缝（A12）", () => {
+  let dir: string
+  const saved: Record<string, string | undefined> = {}
+  const savedCodec = { value: undefined as unknown }
+
+  beforeEach(async () => {
+    for (const k of ENV_KEYS) saved[k] = process.env[k]
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), "remote-auth-codec-test-"))
+    process.env.DESKTOP_USER_DATA_DIR = dir
+    process.env.DEPLOY_TARGET = "desktop"
+    savedCodec.value = globalThis.__allblueDesktopCodec
+  })
+
+  afterEach(async () => {
+    globalThis.__allblueDesktopCodec = savedCodec.value as typeof globalThis.__allblueDesktopCodec
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k]
+      else process.env[k] = saved[k]
+    }
+    await fs.rm(dir, { recursive: true, force: true })
+  })
+
+  it("codec 注入：密文落盘（磁盘字节不含明文 token）且读回一致", async () => {
+    globalThis.__allblueDesktopCodec = stubCodec()
+    await writeRemoteAuth("tok-1", "stale-st")
+    await writeRemoteSession("user-1", "pro", "fresh-st")
+    const raw = await fs.readFile(path.join(dir, "remote-auth.json"), "utf8")
+    expect(raw.startsWith("enc:v1:")).toBe(true)
+    expect(raw).not.toContain("fresh-st")
+    expect(raw).not.toContain("stale-st")
+    expect(raw).not.toContain("tok-1")
+    expect(raw).not.toContain("sessionToken")
+    expect(() => JSON.parse(raw)).toThrow()
+    // roundtrip：读回一致
+    expect(await readRemoteAuth()).toMatchObject({
+      userId: "user-1",
+      planName: "pro",
+      sessionToken: "fresh-st",
+    })
+  })
+
+  it("codec 注入但磁盘为旧明文：按明文读取（平滑迁移，无前缀直通）", async () => {
+    globalThis.__allblueDesktopCodec = stubCodec()
+    const legacy = JSON.stringify({
+      session: { userId: "user-1", planName: "pro", sessionToken: "legacy-st" },
+    })
+    await fs.writeFile(path.join(dir, "remote-auth.json"), legacy, "utf8")
+    expect(await readRemoteAuth()).toMatchObject({ sessionToken: "legacy-st" })
+  })
+
+  it("无 codec：行为不变——明文落盘（现状回归锚，逐字节兼容）", async () => {
+    globalThis.__allblueDesktopCodec = undefined
+    await writeRemoteAuth("tok-1")
+    await writeRemoteSession("user-1", "pro", "fresh-st")
+    const raw = await fs.readFile(path.join(dir, "remote-auth.json"), "utf8")
+    const parsed = JSON.parse(raw) as { session?: { sessionToken?: string } }
+    expect(parsed.session?.sessionToken).toBe("fresh-st") // 明文形态 = 现状
+    expect(await readRemoteAuth()).toMatchObject({ sessionToken: "fresh-st" })
+  })
+
+  it("codec 降级形态（encrypt 返回无前缀明文）：不二次加前缀、明文落盘可读回", async () => {
+    // safeStorage 不可用降级由 Pro 域算子收敛为「原样明文」输出——接缝必须
+    // 原样落盘，不得对降级明文再补前缀（否则读回解密必败）
+    globalThis.__allblueDesktopCodec = {
+      encrypt: async (p: string) => p,
+      decrypt: async (r: string) => r,
+    }
+    await writeRemoteSession("user-1", "pro", "fresh-st")
+    const raw = await fs.readFile(path.join(dir, "remote-auth.json"), "utf8")
+    expect(raw.startsWith("enc:v1:")).toBe(false)
+    expect((JSON.parse(raw) as { session?: { sessionToken?: string } }).session?.sessionToken).toBe(
+      "fresh-st",
+    )
+    expect(await readRemoteAuth()).toMatchObject({ sessionToken: "fresh-st" })
+  })
+
+  it("密文文件但 codec 缺失（独立预检分支）：warn + null（视为未登录，下次写入自愈）", async () => {
+    // 旧壳读到新格式 / 异常态：磁盘密文在场、globalThis codec 未注入——
+    // readFile 显式预检 + warn + null，不抛错反噬调用方。warn 断言钉死独立
+    // 预检分支（防空转：无预检时 JSON.parse 抛错同样落 catch → null，结果
+    // 相同但丢诊断信号）
+    globalThis.__allblueDesktopCodec = undefined
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+    try {
+      await fs.writeFile(
+        path.join(dir, "remote-auth.json"),
+        `enc:v1:${Buffer.from('{"session":{"userId":"user-1"}}').toString("base64")}`,
+        "utf8",
+      )
+      expect(await readRemoteAuth()).toBeNull()
+      expect(
+        warnSpy.mock.calls.some((args) => String(args[0]).includes("codec 未注入")),
+      ).toBe(true)
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it("密文在场但 decrypt 抛错（IPC 失败/密文损坏）：catch 吞错 → null", async () => {
+    globalThis.__allblueDesktopCodec = {
+      encrypt: async (p: string) => `enc:v1:${Buffer.from(p).toString("base64")}`,
+      decrypt: async () => {
+        throw new Error("codec rpc 超时")
+      },
+    }
+    await fs.writeFile(
+      path.join(dir, "remote-auth.json"),
+      `enc:v1:${Buffer.from("garbage-not-json").toString("base64")}`,
+      "utf8",
+    )
+    expect(await readRemoteAuth()).toBeNull()
+  })
+})

package/src/server/desktop-bootstrap.ts

@@ -25,6 +25,7 @@
 
 import { randomUUID } from 'node:crypto'
 import { prisma } from '@allbluecn/database'
+import type { Prisma } from '@allbluecn/database'
 import { ensureBuiltinIndependentProject } from '@/server/builtin-project'
 import {
   GUEST_EMAIL,
@@ -54,7 +55,24 @@ function shadowBgColor(seed: string): string {
 export async function ensureLocalShadowUser(): Promise<string> {
   if (!isDesktopServer()) return GUEST_USER_ID
 
-  await prisma.user.upsert({
+  await ensureLocalShadowUserWith(prisma)
+
+  await ensureBuiltinIndependentProject(GUEST_USER_ID)
+  return GUEST_USER_ID
+}
+
+/**
+ * 影子用户 upsert 主体（可传事务客户端，A9 抽取）：公开无参包装
+ * （ensureLocalShadowUser）的语义不变，反向转移（ownership-transfer 的
+ * reverseTransferOwnership）在**同一事务内**调本函数重建 guest 行——原实现
+ * 直用模块级 prisma 单例，事务内调用会绕过 tx（属主翻转引用的 FK 目标必须与
+ * 翻转同事务存在，否则并发删除/回滚会留孤儿）。
+ * 只含 users 行 upsert：内置独立项目走 ensureBuiltinIndependentProject（模块级
+ * prisma），由登出后的 getSessionFn guest 分支懒补（项目行经反向转移已回 guest
+ * 属主，通常已存在）。
+ */
+export async function ensureLocalShadowUserWith(tx: Prisma.TransactionClient): Promise<string> {
+  await tx.user.upsert({
     where: { id: GUEST_USER_ID },
     create: {
       id: GUEST_USER_ID,
@@ -68,7 +86,5 @@ export async function ensureLocalShadowUser(): Promise<string> {
     },
     update: {},
   })
-
-  await ensureBuiltinIndependentProject(GUEST_USER_ID)
   return GUEST_USER_ID
 }

package/src/server/desktop-session-merge.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 桌面轻量云身份组装（桌面本地优先 P2 / A10）：RemoteAuthData → Session 的
+// 单一组装点 + getCurrentSession 的桌面回落入口。独立模块原因：lib/session
+// 的回落需要组装函数，而 lib/session 不得 import serverFns/**（serverFns/
+// auth/session 反向 import lib/session，会成环）——故从 serverFns/auth/
+// session.ts 抽出 buildRemoteSession 共享（字段逐字一致，两处不再漂移）。
+// 本模块保持纯数据组装 + remote-auth 纯 fs 读取（node:fs + env 守卫），
+// 无 prisma/server 重依赖链；lib/session 对本模块的单条 import 经 eslint
+// 文件级豁免放行（apps/web/eslint.config.mjs）。
+import { DEFAULT_AI_MODEL, DEFAULT_AI_PROVIDER } from '@/lib/ai/default-model'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { readRemoteAuth } from '@/server/remote-auth'
+import type { RemoteAuthData } from '@/server/remote-auth'
+import type { Session } from '@/lib/session'
+
+export function buildRemoteSession(data: RemoteAuthData): Session {
+  return {
+    user: {
+      id: data.userId,
+      name: data.username ?? data.userId,
+      email: data.email,
+      role: (data.role ?? 'USER') as 'USER' | 'ADMIN' | 'SUPER_ADMIN',
+      isGuest: false,
+      // 云端头像透传（SaaS desktop-callback 下发；缺省回落首字母，修复桌面端
+      // 当前用户头像不显示）
+      avatarConfig: data.avatarConfig,
+      bgShape: data.bgShape,
+      bgColor: data.bgColor,
+      aiProvider: DEFAULT_AI_PROVIDER,
+      aiModel: DEFAULT_AI_MODEL,
+      hasAiKey: false,
+    },
+    expires: 'never',
+  }
+}
+
+/**
+ * getCurrentSession 的桌面回落段（优先级链：authjs session → desktop
+ * remoteAuth → null）：authjs session 无效且为 desktop 部署时，读
+ * remote-auth.json 组装轻量云身份（user.id = 云 userId）。desktop 判定
+ * 先于 fs 读取（非 desktop 恒 null、零 IO），调用方无需重复判定。
+ */
+export async function getDesktopRemoteSession(): Promise<Session | null> {
+  if (!isDesktopServer()) return null
+  const remoteAuth = await readRemoteAuth()
+  if (!remoteAuth) return null
+  return buildRemoteSession(remoteAuth)
+}