Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

56.4 KB
Raw Blame
import { evictTaskTagCatalog } from '../task-tags/taskTagEvents';
/**
 * useDeviceLinkRemoteProjects —— device-link「自动常驻」接入器(listing tier,push 驱动)。
 * ---------------------------------------------------------------------------
 * 每个窗口各挂一次(remoteProjectsStore 是「每渲染进程一份」的模块级单例,窗口间不共享
 * 内存,故副窗口也得自己镜像一份,否则侧边栏看不到远程项目)。职责:把**同账号 + 在线 +
 * 开了「允许被控」**的设备的会话列表镜像进 remoteProjectsStore → 侧边栏自然出现这些设备的
 * 远程项目(带设备 icon)。
 *
 * 多窗口订阅安全:每个窗口独立 `subscribe`,主进程按窗口对 (deviceId, topic) 引用计数
 * (见 main/device-link/subscriptionRefcount.ts),最后一个窗口释放才真正向 relay
 * unsubscribe —— 关一个窗口不会拆掉其它窗口还在用的订阅。push 本就广播给所有窗口。
 *
 * 控制端纯镜像(被控端 = 单一真相源):
 *  - 设备变合格 → `subscribe(['sessions'])`(订阅被控端会话列表读模型变更)+ **bootstrap 拉一次**
 *    全量(reconcile 规则:先 subscribe 再 snapshot,中间窗口的增量由 push 兜)。
 *  - 之后被控端的 `sessions:patched`(改名/置顶/删/归档/设置)经 push → makerChatStore 路由到
 *    remoteProjectsStore.applyPatch;`sessions:created`(无 row 数据)→ 防抖重拉该设备。
 *  - push 是低延迟主路径;另以低频有界 snapshot 做 anti-entropy,更新窗口内权威状态;
 *    满窗口时保留缺席行并有界轮询其终态,避免误删仍有效的窗口外会话,也让丢失的归档/删除
 *    push 最终收敛。
 *  - 设备瞬时不可达(下线 / relay connecting)→ 保留最近一次快照并标记 disconnected;
 *    明确不合格(关被控 / 被撤销 / 本机禁用控制)→ `unsubscribe` + removeDevice。
 *  - WS 重连 → 对每个合格设备重新 subscribe + 重新 bootstrap(被控端可能重启过、订阅 registry 清空)。
 *
 * 不在本地落库(被控端 DB 才是数据真相);登出 / stopped / 卸载即清空内存镜像。
 *
 * 唯一的盘上痕迹是**非权威冷缓存**:列表快照落在 main 的 userData
 * (`main/device-link/mirrorCacheStore.ts`),仅用于冷启动首屏 —— mount 时
 * `hydrateFromCache` 把上次看到的行画出来并标 disconnected,bootstrap 一到即整片替换;
 * 设备明确离场(撤销 / 关被控 / 禁用控制)时连它的缓存一起清。整棵缓存的删除归 owner
 * 边界(main 的 teardownAuthAccountBoundary),这里只负责作废未落盘的回写。
 */

import { useEffect, useRef } from 'react';
import { isSharedTaskPeer } from '@cindy/device-link';
import { projectScheduleEvent } from '@cindy/maker-shared/schedule-events';
import { historyTurnEnded } from '@cindy/maker-shared/message-window';
import { PROJECT_ALIASES_CHANGED_CHANNEL } from '@cindy/maker-shared/project-alias-sync';
import { useAuth } from '@/contexts/AuthContext';
import { isDeviceLinkRemotePushCurrent } from '@/lib/remoteDataOwnerPushFence';
import { createLogger } from '@/lib/logger';
import { makerChatStore } from '@/lib/makerChatStore';
import {
  requestRemoteSessionStatus,
  remoteProjectsStore,
  retryRemoteSessionStatus,
  setRemoteReseedImpl,
  setRemoteSessionBootstrapRetryImpl,
  type RemoteSessionStatus,
} from './remoteProjectsStore';
import {
  clearRemoteSessionActivity,
  removeRemoteSessionActivityForDevice,
} from './remoteSessionActivityStore';
import { revokedDevicesStore } from './revokedDevicesStore';
import { unresponsiveDevicesStore } from './unresponsiveDevicesStore';
import { subscribeDeviceLinkDeviceRemoval } from './useDeviceLinkDeviceList';
import { collectSessionListSnapshot, refreshRemoteDeviceSessions } from './refreshRemoteSessions';
import {
  cancelSessionListPersist,
  clearCachedDevice,
  clearMirrorCacheAccountState,
  readCachedSessionList,
  scheduleSessionListPersist,
  sessionListOwnerTokensReady,
} from './mirrorCacheClient';
import { prefetchDeviceCapabilities, evictDeviceCapabilities } from '@/hooks/useAgentCapabilities';
import { prefetchDeviceProviders, evictDeviceProviders } from '@/hooks/useDeviceProviders';
import { refreshRemoteCatalogSnapshot } from '@/lib/remoteCatalogSnapshot';
import {
  evictDeviceGitSafetySettings,
  prefetchDeviceGitSafetySettings,
} from '@/hooks/useGitSafetySettings';
import { extractIpcError } from '@/utils/ipcError';
import { remoteProjectAliases } from './remoteProjectAliases';

const log = createLogger('device-link-remote-projects');

/** session-list owner 令牌补读退避:不断恢复,但长期故障时不每 2 秒打一次 IPC。 */
const SESSION_LIST_TOKEN_RETRY_BASE_MS = 2_000;
const SESSION_LIST_TOKEN_RETRY_MAX_MS = 30_000;
/** archived 按需读取失败后自动恢复;独立于 active 的周期 anti-entropy。 */
const ARCHIVED_SESSION_RETRY_BASE_MS = 2_000;
const ARCHIVED_SESSION_RETRY_MAX_MS = 30_000;

/** 返回下一次列表令牌补读的等待时间;账号边界 effect 重建时从 0 重新开始。 */
export function nextSessionListTokenRetryDelay(previousMs: number): number {
  if (!Number.isFinite(previousMs) || previousMs < SESSION_LIST_TOKEN_RETRY_BASE_MS) {
    return SESSION_LIST_TOKEN_RETRY_BASE_MS;
  }
  return Math.min(previousMs * 2, SESSION_LIST_TOKEN_RETRY_MAX_MS);
}

/** 返回 archived 按需读取失败后的下一档退避;持续恢复但封顶 30 秒。 */
export function nextArchivedSessionRetryDelay(previousMs: number): number {
  if (!Number.isFinite(previousMs) || previousMs < ARCHIVED_SESSION_RETRY_BASE_MS) {
    return ARCHIVED_SESSION_RETRY_BASE_MS;
  }
  return Math.min(previousMs * 2, ARCHIVED_SESSION_RETRY_MAX_MS);
}

/**
 * 启动 session-list owner 令牌补读循环。返回清理函数;账号边界 effect 每次重建都会创建新的
 * retryDelayMs,因此新账号从 2 秒重新开始,旧账号的 timer 由 cleanup 取消。
 * 参数只用于确定性单测;生产默认走真实缓存读与 readiness。
 */
export function startSessionListTokenRefresh(
  refresh: () => Promise<unknown> = readCachedSessionList,
  isReady: () => boolean = sessionListOwnerTokensReady,
): () => void {
  let cancelled = false;
  let timer: ReturnType<typeof setTimeout> | null = null;
  let retryDelayMs = 0;
  const refreshUntilReady = async (): Promise<void> => {
    if (cancelled) return;
    await refresh();
    if (cancelled) return;
    if (!isReady()) {
      // 不能设最大次数后永久停掉:此前正是一次补读失败后不恢复,让列表缓存持续停写。
      // 保留无限恢复能力,只把长期故障下的频率从固定 2s 指数退避到最多 30s
      // (review: copilot suppressed)。
      retryDelayMs = nextSessionListTokenRetryDelay(retryDelayMs);
      timer = setTimeout(refreshUntilReady, retryDelayMs);
    }
  };
  void refreshUntilReady();
  return () => {
    cancelled = true;
    if (timer) clearTimeout(timer);
  };
}

/** sessions:created reseed 防抖(被控端短时间多次创建会话 / orca 起多 worker 时合并重拉)。 */
const RESEED_DEBOUNCE_MS = 300;
// Limit only the startup route's discovery wait, not the request or peer lifetime.
// Matches the background device directory's 10s budget; late results still apply.
const INITIAL_DISCOVERY_WAIT_MS = 10_000;

/**
 * best-effort push 的窗口内 anti-entropy 周期。列表、置顶、归档/删除走 sessions:patched /
 * created push,自动化索引与绑定走 maker:schedule:event push;周期全量只兜丢失的 push,
 * 窗口外终态按有界轮询分批收敛。重连、熔断恢复、presence 重新合格走 bootstrap 立即重拉,
 * 回到电脑 / 窗口重新可见走 wake 立即对账,都不等这一拍。
 */
const RECONCILE_INTERVAL_MS = 60_000;

/**
 * 对账检查节拍与失败退避基准。sessions 订阅缺口(补订待重试)的设备没有 push 兜底,
 * 每拍都对账并补订;其它设备按 RECONCILE_INTERVAL_MS 才发起全量。
 */
const RECONCILE_TICK_MS = 10_000;

/** 连续失败退避封顶:失败设备最低仍保持约 2 分钟一次的对账,恢复靠 push / 熔断探测先行。 */
const RECONCILE_BACKOFF_MAX_MS = 120_000;

/** 主窗口无人输入超过此时长则停周期对账;连接与 push 进度仍在。 */
export const REMOTE_RECONCILE_USER_IDLE_MS = 5 * 60_000;

/**
 * 主窗口周期对账闸:页面不可见或用户离开电脑后停拉全量列表。
 * 独立侧栏仍走 windowVisible(#4205),不要把这套 idle 叠上去。
 */
export function createRemoteReconcilePresence(opts?: {
  idleMs?: number;
  now?: () => number;
}): {
  isActive(): boolean;
  /** @returns 是否从闲置变为在用,调用方应立刻对账一次。 */
  setVisible(visible: boolean): boolean;
  /** @returns 是否从闲置变为在用,调用方应立刻对账一次。 */
  noteActivity(): boolean;
} {
  const idleMs = opts?.idleMs ?? REMOTE_RECONCILE_USER_IDLE_MS;
  const now = opts?.now ?? Date.now;
  let visible = true;
  let lastActivityAt = now();
  const isActive = () => visible && now() - lastActivityAt < idleMs;
  return {
    isActive,
    setVisible(next) {
      const wasActive = isActive();
      visible = next;
      if (next) lastActivityAt = now();
      return !wasActive && isActive();
    },
    noteActivity() {
      const wasActive = isActive();
      lastActivityAt = now();
      return !wasActive && isActive();
    },
  };
}

type RemoteSessionsRefresh = (deviceId: string, name?: string) => Promise<unknown>;

/**
 * per-device 对账退避账本(纯逻辑,可单测)。
 *
 * 弱网教训(2026-08):固定 10s 无退避的对账循环在链路劣化时永不放慢,叠加超时重试
 * 变成请求风暴。这里按设备记连续失败:失败后下一次尝试推迟 base×2^(n-1)(封顶 maxMs,
 * ±15% 抖动打散多设备齐步),成功即复位;'superseded' / 'revoked' 不计失败——前者是
 * 并发合并的正常路径,后者有自己的终态处理。
 */
export function createReconcileBackoff(opts?: {
  baseMs?: number;
  maxMs?: number;
  /** 抖动注入(测试用;默认 ±15% 随机)。 */
  jitter?: (delayMs: number) => number;
  now?: () => number;
}) {
  const baseMs = opts?.baseMs ?? RECONCILE_INTERVAL_MS;
  const maxMs = opts?.maxMs ?? RECONCILE_BACKOFF_MAX_MS;
  const jitter =
    opts?.jitter ?? ((delay: number) => Math.round(delay * (0.85 + Math.random() * 0.3)));
  const now = opts?.now ?? Date.now;
  const state = new Map<string, { failures: number; nextEligibleAt: number }>();
  return {
    /** 本 tick 是否应该对该设备发起对账。 */
    shouldAttempt(deviceId: string): boolean {
      const entry = state.get(deviceId);
      return !entry || now() >= entry.nextEligibleAt;
    },
    /** 上报一次对账结果。failure 加深退避,success 复位,neutral 不动。 */
    report(deviceId: string, outcome: 'success' | 'failure' | 'neutral'): void {
      if (outcome === 'neutral') return;
      if (outcome === 'success') {
        state.delete(deviceId);
        return;
      }
      const failures = (state.get(deviceId)?.failures ?? 0) + 1;
      const delay = Math.min(baseMs * 2 ** (failures - 1), maxMs);
      // 抖动后再 clamp:maxMs 是硬封顶(review:+15% 抖动曾把封顶档放大到 138s),
      // 负值防御性归零。
      const jittered = Math.min(Math.max(0, jitter(delay)), maxMs);
      state.set(deviceId, { failures, nextEligibleAt: now() + jittered });
    },
    /** 只保留仍合格的设备,防止退避账本随设备增删无界增长。 */
    retainOnly(deviceIds: ReadonlySet<string>): void {
      for (const deviceId of state.keys()) {
        if (!deviceIds.has(deviceId)) state.delete(deviceId);
      }
    },
  };
}

export type ReconcileBackoff = ReturnType<typeof createReconcileBackoff>;

/**
 * 启动 listing tier 的低频有界对账。setInterval 只负责触发;每设备的并发合并与乱序保护
 * 继续由 refreshRemoteDeviceSessions 负责;连续失败的设备按 createReconcileBackoff 放慢
 * (refresh resolve 出的 RefreshResult 用于记账:'gave-up' = 失败,'ok' = 成功,其余中性;
 * reject 一律计失败)。返回清理函数,避免窗口卸载后残留 timer。
 *
 * cadence.tickMs 小于 intervalMs 时按 tick 检查:needsEveryTick 的设备每拍对账,其它设备
 * 距上次周期尝试满 intervalMs 才对账(首次见到的设备刚做过 bootstrap,从此刻起算)。
 * 失败退避与间隔同时生效,取较晚者。不传 cadence 时每拍都到期(原行为)。
 */
export function startRemoteSessionsReconciler(
  getEligibleDevices: () => Iterable<readonly [string, string]>,
  refresh: RemoteSessionsRefresh = refreshRemoteDeviceSessions,
  intervalMs = RECONCILE_INTERVAL_MS,
  backoff: ReconcileBackoff = createReconcileBackoff({ baseMs: intervalMs }),
  isActive: () => boolean = () => true,
  cadence?: {
    tickMs: number;
    needsEveryTick?: (deviceId: string) => boolean;
    now?: () => number;
  },
): { stop: () => void; wake: () => void } {
  const tickMs = Math.min(cadence?.tickMs ?? intervalMs, intervalMs);
  const now = cadence?.now ?? Date.now;
  /** 上次周期尝试时刻;容差半拍,避免 setInterval 抖动把 60s 拖成 70s。 */
  const lastAttemptAt = new Map<string, number>();
  const isDue = (deviceId: string): boolean => {
    if (tickMs >= intervalMs || cadence?.needsEveryTick?.(deviceId)) return true;
    const last = lastAttemptAt.get(deviceId);
    if (last === undefined) {
      lastAttemptAt.set(deviceId, now());
      return false;
    }
    return now() - last >= intervalMs - tickMs / 2;
  };
  // 单次刷新可能横跨多个 tick(弱网下超时链 >10s);weak coalescing 会让后续 tick 拿到
  // 同一个在途 Promise,若每个 tick 都挂 then,一次 gave-up 会被重复记账、退避直接跳档
  // (review P2)。per-device 在途标记保证一次合并请求只记一次。
  const inFlight = new Set<string>();
  let stopped = false;
  const runPass = (opts?: { ignoreBackoff?: boolean }) => {
    // Hidden auxiliary windows retain their push mirror and failure backoff, but do no polling.
    if (stopped || !isActive()) return;
    const seen = new Set<string>();
    for (const [deviceId, name] of getEligibleDevices()) {
      seen.add(deviceId);
      if (inFlight.has(deviceId)) continue;
      if (!opts?.ignoreBackoff && (!isDue(deviceId) || !backoff.shouldAttempt(deviceId))) continue;
      lastAttemptAt.set(deviceId, now());
      inFlight.add(deviceId);
      void refresh(deviceId, name)
        .then((result) => {
          if (stopped) return;
          backoff.report(
            deviceId,
            result === 'gave-up' ? 'failure' : result === 'ok' ? 'success' : 'neutral',
          );
        })
        .catch((err) => {
          if (stopped) return;
          backoff.report(deviceId, 'failure');
          log.debug(`periodic sessions reconcile failed for ${deviceId.slice(0, 8)}`, err);
        })
        .finally(() => {
          inFlight.delete(deviceId);
        });
    }
    backoff.retainOnly(seen);
    for (const deviceId of lastAttemptAt.keys()) {
      if (!seen.has(deviceId)) lastAttemptAt.delete(deviceId);
    }
  };
  const timer = setInterval(runPass, tickMs);
  return {
    stop() {
      stopped = true;
      clearInterval(timer);
      inFlight.clear();
    },
    // 从闲置回到在用:立刻对账,不等下一拍,也不吃失败退避。闲着不加 30 分钟兜底。
    wake() {
      runPass({ ignoreBackoff: true });
    },
  };
}

type BootstrapMode = 'full' | 'resubscribe';

type IneligibleRemoteProjectAction = 'disconnect' | 'remove' | 'ignore';

export function resolveIneligibleRemoteProjectAction(input: {
  wasEligible: boolean;
  hasCachedShard: boolean;
  isSelf: boolean;
  online: boolean;
  remoteControlEnabled: boolean;
  disabledControl: boolean;
}): IneligibleRemoteProjectAction {
  if (!input.wasEligible && !input.hasCachedShard) return 'ignore';
  if (input.isSelf || input.disabledControl) return 'remove';
  // Offline rows can report remoteControlEnabled=false even when the peer did not explicitly disable
  // remote control. Treat that as a transient disconnect; only an online false bit is authoritative.
  if (!input.online) return 'disconnect';
  if (!input.remoteControlEnabled) return 'remove';
  return 'remove';
}

export function useDeviceLinkRemoteProjects(
  periodicReconcileActive = true,
  windowRole: 'main' | 'sidebar' = 'main',
): void {
  const { isAuthenticated, deviceId: selfDeviceId, dataOwnerId } = useAuth();
  const periodicReconcileActiveRef = useRef(periodicReconcileActive);
  periodicReconcileActiveRef.current = periodicReconcileActive;
  const mainPresenceRef = useRef(
    windowRole === 'main' ? createRemoteReconcilePresence() : null,
  );
  const wakeRemoteReconcileRef = useRef<() => void>(() => undefined);
  const periodicReconcileWasActiveRef = useRef(periodicReconcileActive);
  useEffect(() => {
    const wasActive = periodicReconcileWasActiveRef.current;
    periodicReconcileWasActiveRef.current = periodicReconcileActive;
    // 独立侧栏重新可见:隐藏期间暂停的对账与跳过的自动化事件立即补上,与主窗口
    // visibilitychange 的 wake 同口径,不等周期一拍。
    if (periodicReconcileActive && !wasActive) wakeRemoteReconcileRef.current();
  }, [periodicReconcileActive]);
  useEffect(() => {
    const gate = mainPresenceRef.current;
    if (windowRole !== 'main' || !gate) return undefined;
    const syncVisible = () => {
      if (gate.setVisible(document.visibilityState === 'visible')) wakeRemoteReconcileRef.current();
    };
    const note = () => {
      if (gate.noteActivity()) wakeRemoteReconcileRef.current();
    };
    syncVisible();
    document.addEventListener('visibilitychange', syncVisible);
    window.addEventListener('pointerdown', note);
    window.addEventListener('keydown', note);
    return () => {
      document.removeEventListener('visibilitychange', syncVisible);
      window.removeEventListener('pointerdown', note);
      window.removeEventListener('keydown', note);
    };
  }, [windowRole]);

  // 账号边界真正由 dataOwnerId 界定:登出 / 切账号都必然改变它。**不能只靠 !isAuthenticated** ——
  // 运行时替换刷新路径可以在不经过 signed-out 的情况下直接把新 owner 发布出来,那时本 effect
  // 若只依赖 isAuthenticated / deviceId 不会重跑,旧的 owner token 残留会一直传给 store 被
  // fail-closed 拒写,新账号冷缓存停止更新直到重挂载(review: codex P1)。因此单独挂一个
  // dataOwnerId 依赖的 effect,owner 一换就清 mirror 状态。
  // dataOwnerId 是 owner 边界的真源(runtime 替换刷新可跳过 signed-out 直接换 owner)。
  const ownerBoundaryGeneration = `${dataOwnerId ?? ''}`;
  useEffect(() => {
    clearMirrorCacheAccountState();
    remoteProjectAliases.clear();
    // 清完必须**主动补读 session-list** 直到拿到新账号的 owner 锚点:
    //  1. 主 effect 只依赖 isAuthenticated / selfDeviceId,A→B 直接切换(两者都不变)时不会
    //     重跑,而读 session-list 的调用挂在主 effect 里 —— 不补读的话 B 的排程回写会一直
    //     带 undefined 被 main fail-closed 丢弃(review: Greptile P1);
    //  2. 补读可能因待清队列 / owner 边界复核 / 瞬时 IPC 错误失败,失败后**重试**直到锚点
    //     就位 —— 否则订阅仍持续排程 undefined 写入,冷缓存停写到重挂载(本线程)。
    // 账号在重试期间再次变化时,effect 重跑清掉定时器,旧账号的重试不再继续。
    // local mode 也有 `local-v1` data owner,但没有 Device Link capability;只看 dataOwnerId
    // 会让跳过登录的客户端无限重试一个必然被 main 以 PERMISSION_DENIED 拒绝的 IPC。
    if (!isAuthenticated || !dataOwnerId) return;
    return startSessionListTokenRefresh();
  }, [ownerBoundaryGeneration, isAuthenticated]);

  useEffect(() => {
    if (!isAuthenticated || !selfDeviceId) {
      // 同 'stopped' / unmount:cancel 在 clear 之后,免得 clear 的同步通知又排一次回写。
      remoteProjectsStore.clear();
      remoteProjectAliases.clear();
      cancelSessionListPersist();
      // 登出分支:上面的 dataOwnerId effect 已清 mirror 状态,这里补 cancel 去抖回写。
      return;
    }

    let disposed = false;
    const finishInitialDiscovery = remoteProjectsStore.beginInitialDiscovery();
    const initialDiscoveryTimer = setTimeout(finishInitialDiscovery, INITIAL_DISCOVERY_WAIT_MS);
    /**
     * 「已明确离场、不许被冷缓存种回来」的设备 id。删除 / 撤销访问 / 关闭被控 / 本机停用控制
     * 路径都会往里加 —— 它们清盘是异步的,而 mount 时那次 readCachedSessionList 可能早已
     * 读到旧快照(review: codex P1)。
     */
    const cacheHydrationBlocked = new Set<string>();
    let directoryGeneration = 0;
    /** relay 在线时才跑 anti-entropy;初始状态未知时保守暂停,避免离线失败重试。 */
    let linkOnline: boolean | null = null;
    /** push 一旦到达即权威:迟到的 getState 快照不得覆盖更新的 link status。 */
    let linkStatusPushSeen = false;
    /** 当前合格设备:deviceId → 友好名 */
    const eligible = new Map<string, string>();
    /** 本机主动关闭控制的目标设备(控制端本地偏好)。 */
    let disabledControlDeviceIds = new Set<string>();
    let controlTargetPushSeen = false;
    /** sessions:created / archived 按需加载的 per-device+status 防抖 timer */
    const reseedTimers = new Map<string, ReturnType<typeof setTimeout>>();
    /** archived 读取终态失败后的 per-device 自动重试。 */
    const archivedRetryTimers = new Map<string, ReturnType<typeof setTimeout>>();
    const archivedRetryDelayMs = new Map<string, number>();
    /**
     * 每设备一条串行任务:full = subscribe + 拉列表 + 预取;resubscribe = 只补 sessions 订阅。
     * 补订也走这里,保证同一设备同一时刻只有一路 subscribe,迟到结果由 lifecycleEpoch 挡掉。
     */
    const bootstrapTasks = new Map<
      string,
      {
        promise: Promise<void>;
        rerun: boolean;
        name: string;
        lifecycleEpoch: number;
        mode: BootstrapMode;
      }
    >();
    /**
     * sessions 订阅瞬时失败(如重连瞬间 DEVICE_LINK_BUSY)、待周期对账补订的设备。
     * 列表靠周期 sessions:list 仍会刷新,但运行活动(侧栏运行图标、灵动岛)只走 sessions push;
     * 不补订就会一直「列表可见、运行状态全无」,直到下一次重连 / 熔断恢复重跑 bootstrap。
     */
    const sessionsSubscribeRetry = new Set<string>();

    /** 隧道调用是否因「访问权限已被撤销」失败(被控端逐设备黑名单)。 */
    const isAccessRevoked = (err: unknown): boolean =>
      extractIpcError(err)?.code === 'DEVICE_LINK_ACCESS_REVOKED';
    /** 被控端明确不支持 / 已关闭被控时,重试 sessions 订阅没有意义。 */
    const isPermanentSubscribeError = (err: unknown): boolean => {
      const code = extractIpcError(err)?.code;
      return (
        code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED' ||
        code === 'DEVICE_LINK_REMOTE_DISABLED' ||
        code === 'DEVICE_LINK_VERSION_MISMATCH'
      );
    };

    const cancelDeviceReseeds = (deviceId: string): void => {
      for (const [key, pending] of reseedTimers) {
        if (!key.startsWith(`${deviceId}\u0000`)) continue;
        clearTimeout(pending);
        reseedTimers.delete(key);
      }
    };

    const clearArchivedSessionRetry = (deviceId: string): void => {
      const timer = archivedRetryTimers.get(deviceId);
      if (timer) clearTimeout(timer);
      archivedRetryTimers.delete(deviceId);
      archivedRetryDelayMs.delete(deviceId);
    };

    const clearAllArchivedSessionRetries = (): void => {
      for (const timer of archivedRetryTimers.values()) clearTimeout(timer);
      archivedRetryTimers.clear();
      archivedRetryDelayMs.clear();
    };

    const scheduleArchivedSessionRetry = (deviceId: string): void => {
      if (disposed || !eligible.has(deviceId) || archivedRetryTimers.has(deviceId)) return;
      const delay = nextArchivedSessionRetryDelay(archivedRetryDelayMs.get(deviceId) ?? 0);
      archivedRetryDelayMs.set(deviceId, delay);
      archivedRetryTimers.set(
        deviceId,
        setTimeout(() => {
          archivedRetryTimers.delete(deviceId);
          if (disposed || !eligible.has(deviceId) || !linkOnline) return;
          retryRemoteSessionStatus(deviceId, 'archived');
        }, delay),
      );
    };

    /**
     * 被某被控端撤销访问权限:移出合格集 + 记入 revokedDevicesStore(设置页显示「已撤销」)+
     * 移除其项目/对话 + 驱逐远端快照缓存。该设备 presence 仍在线/允许被控,故下次 presence 会再
     * subscribeAndBootstrap 重试 —— 被控端恢复后即自动接回。
     */
    const handleRevoked = (deviceId: string): void => {
      cancelDeviceReseeds(deviceId);
      evictTaskTagCatalog(deviceId);
      clearArchivedSessionRetry(deviceId);
      eligible.delete(deviceId);
      sessionsSubscribeRetry.delete(deviceId);
      revokedDevicesStore.markRevoked(deviceId);
      remoteProjectsStore.removeDevice(deviceId);
      remoteProjectAliases.remove(deviceId);
      removeRemoteSessionActivityForDevice(deviceId);
      // 被控端明确拒绝我们:盘上那份镜像缓存也不该留(尊重对方的拒绝,不在本机留副本)。
      cacheHydrationBlocked.add(deviceId);
      clearCachedDevice(deviceId);
      evictDeviceCapabilities(deviceId);
      evictDeviceProviders(deviceId);
      evictDeviceGitSafetySettings(deviceId);
    };

    /**
     * 订阅 sessions topic(push 驱动列表)+ bootstrap 拉一次全量。subscribe 失败不阻断
     * bootstrap(暂时退化为「快照可见、live 更新缺失」);瞬时失败记入 sessionsSubscribeRetry,
     * 由周期对账补订,永久不支持的被控端不重试。
     * 任一步返回 ACCESS_REVOKED → 标记已撤销并移除该设备;全程无撤销 → 清掉残留标记(恢复收尾)。
     */
    const canBootstrap = (deviceId: string, lifecycleEpoch: number): boolean =>
      !disposed && linkOnline !== false && eligible.has(deviceId) && !unresponsiveDevicesStore.has(deviceId) &&
      remoteProjectsStore.getDeviceLifecycleEpoch(deviceId) === lifecycleEpoch;
    const refreshAliases = (deviceId: string, invalidate = false): Promise<void> => {
      const lifecycleEpoch = remoteProjectsStore.getDeviceLifecycleEpoch(deviceId);
      return remoteProjectAliases.refresh(deviceId, () => canBootstrap(deviceId, lifecycleEpoch), invalidate);
    };
    const runSubscribeAndBootstrap = async (
      deviceId: string,
      name: string,
      lifecycleEpoch: number,
      mode: BootstrapMode,
    ): Promise<void> => {
      if (!canBootstrap(deviceId, lifecycleEpoch)) return;
      if (mode === 'full') {
        log.debug(`sessions refresh trigger=bootstrap window=${windowRole} peer=${deviceId.slice(0, 8)} visible=${periodicReconcileActiveRef.current}`);
        // 新一轮 bootstrap 是有意义的重试:即使还保留旧 shard 也要显式进入
        // loading,直到本轮落下 snapshot 或再次终态失败。补订不进 loading:列表一直可用。
        remoteProjectsStore.markBootstrapLoading(deviceId);
      }
      const canContinue = (): boolean => {
        if (canBootstrap(deviceId, lifecycleEpoch)) return true;
        // An open circuit can interrupt bootstrap between reads. Settle its
        // loading marker without clearing the last successful mirror.
        if (!disposed && eligible.has(deviceId) && unresponsiveDevicesStore.has(deviceId)
          && remoteProjectsStore.getDeviceLifecycleEpoch(deviceId) === lifecycleEpoch) {
          remoteProjectsStore.markBootstrapFailed(deviceId);
        }
        return false;
      };
      try {
        await window.electronAPI.deviceLink.subscribe(deviceId, ['sessions']);
        if (sessionsSubscribeRetry.delete(deviceId) && mode === 'resubscribe') {
          log.debug(`subscribe(sessions) recovered for ${deviceId.slice(0, 8)}`);
        }
      } catch (err) {
        if (!canContinue()) return;
        if (isAccessRevoked(err)) return void handleRevoked(deviceId);
        if (isPermanentSubscribeError(err)) sessionsSubscribeRetry.delete(deviceId);
        else sessionsSubscribeRetry.add(deviceId);
        if (!disposed) log.debug(`subscribe(sessions) failed for ${deviceId.slice(0, 8)}`, err);
      }
      // 补订成功后被控端会定向重放当前活动快照,运行图标与灵动岛随之恢复;列表由周期对账负责。
      if (mode === 'resubscribe') return;
      if (!canContinue()) return;
      // bootstrap 期间被撤销(subscribe 成功、list 被拒)→ refreshRemoteDeviceSessions 返 'revoked'
      // (而非静默 give-up)→ 这里 handleRevoked,而不是继续预取能力 / 清撤销标记无视拒绝。
      void refreshAliases(deviceId);
      const result = await refreshRemoteDeviceSessions(deviceId, name, { scope: 'both' });
      if (!canContinue()) return;
      if (result === 'revoked') return void handleRevoked(deviceId);
      if (result === 'gave-up') {
        // 永久错误(如旧被控端 CHANNEL_NOT_ALLOWED)或瞬态重试耗尽:不是权威空列表,
        // 即使还有旧 shard 也必须标明本轮读取失败,不能把缓存伪装成刚返回的结果。
        // superseded 表示断连 / 清理使请求失效,必须等重连,不能误记成终态失败。
        remoteProjectsStore.markBootstrapFailed(deviceId);
      } else if (result === 'superseded') {
        // 断连或另一轮 refresh 会使本次快照失效;不要让本轮遗留的 loading
        // 永久遮住侧边栏。连接恢复时 presence/status 会再次触发 bootstrap。
        remoteProjectsStore.clearBootstrapLoading(deviceId);
      }
      // 预取被控端能力(model/effort/fast/permission/fork/rewind),使首次打开远程会话时
      // 模型下拉等不为空、modelDefinitions 同步层已热。成功后逐项预取,避免弱网突发。
      if (result === 'ok') {
        await prefetchDeviceCapabilities(deviceId);
        if (!canBootstrap(deviceId, lifecycleEpoch)) return;
        await prefetchDeviceProviders(deviceId);
        if (!canBootstrap(deviceId, lifecycleEpoch)) return;
        await prefetchDeviceGitSafetySettings(deviceId);
        if (!canBootstrap(deviceId, lifecycleEpoch)) return;
        // Bootstrap follows a gap in live pushes (start, reconnect). Read changed tasks ahead
        // so opening them shows what the list already shows; one window does it for all.
        if (windowRole === 'main') void makerChatStore.prefetchRemoteHistories(deviceId);
      }
      // 未被撤销(ok 或普通失败):清掉可能残留的「已撤销」标记(被控端恢复 → 自动接回的收尾)。
      revokedDevicesStore.clearRevoked(deviceId);
    };

    const subscribeAndBootstrap = (
      deviceId: string,
      name: string,
      refreshAfterCurrent = false,
      mode: BootstrapMode = 'full',
    ): Promise<void> => {
      const lifecycleEpoch = remoteProjectsStore.getDeviceLifecycleEpoch(deviceId);
      const existing = bootstrapTasks.get(deviceId);
      if (existing) {
        existing.name = name;
        // Repeated discovery notifications share the current bootstrap. A real
        // recovery/user retry still requests one fresh follow-up, as does a new lifecycle.
        existing.rerun ||= refreshAfterCurrent || existing.lifecycleEpoch !== lifecycleEpoch;
        existing.lifecycleEpoch = lifecycleEpoch;
        // A full bootstrap requested while only a resubscribe runs must still run in full.
        if (mode === 'full' && existing.mode === 'resubscribe') {
          existing.rerun = true;
          existing.mode = 'full';
        }
        return existing.promise;
      }

      const task = { promise: Promise.resolve(), rerun: false, name, lifecycleEpoch, mode };
      task.promise = (async () => {
        try {
          do {
            task.rerun = false;
            await runSubscribeAndBootstrap(deviceId, task.name, task.lifecycleEpoch, task.mode);
          } while (canBootstrap(deviceId, task.lifecycleEpoch) && task.rerun);
        } finally {
          if (bootstrapTasks.get(deviceId) === task) bootstrapTasks.delete(deviceId);
        }
      })();
      bootstrapTasks.set(deviceId, task);
      return task.promise;
    };

    const applyDevice = (d: {
      deviceId: string;
      name: string;
      online: boolean;
      remoteControlEnabled: boolean;
      isSelf: boolean;
    }): void => {
      const ok =
        !d.isSelf &&
        d.online &&
        d.remoteControlEnabled &&
        !disabledControlDeviceIds.has(d.deviceId);
      if (ok) {
        // Confirmed offline waits for the online reseed. Unknown retains the existing
        // bootstrap fallback when getState fails and no subsequent status push arrives.
        if (linkOnline === false) return;
        const prevName = eligible.get(d.deviceId);
        const wasEligible = prevName !== undefined;
        eligible.set(d.deviceId, d.name);
        if (!wasEligible) {
          void subscribeAndBootstrap(d.deviceId, d.name); // 变合格:订阅 + 首拉
        } else if (prevName !== d.name) {
          // 已合格设备的 presence-changed 带来新设备名:重打 store 分片,让本窗口侧边栏即时更新。
          // renameDevice 只由**发起改名**的那个窗口调;其它窗口/设备仅收 presence-changed,
          // 不在此对齐就会一直显示旧名(直到设备移除 / 新 snapshot 替换)。同名时 renameDevice 内部 no-op。
          remoteProjectsStore.renameDevice(d.deviceId, d.name);
        }
      } else {
        const wasEligible = eligible.delete(d.deviceId);
        sessionsSubscribeRetry.delete(d.deviceId);
        const action = resolveIneligibleRemoteProjectAction({
          wasEligible,
          hasCachedShard: remoteProjectsStore.hasDevice(d.deviceId),
          isSelf: d.isSelf,
          online: d.online,
          remoteControlEnabled: d.remoteControlEnabled,
          disabledControl: disabledControlDeviceIds.has(d.deviceId),
        });
        if (action === 'ignore') return;
        cancelDeviceReseeds(d.deviceId);
        clearArchivedSessionRetry(d.deviceId);
        if (wasEligible) {
          window.electronAPI.deviceLink.unsubscribe(d.deviceId, ['sessions']).catch(() => {});
        }
        if (action === 'disconnect') {
          remoteProjectsStore.markDeviceDisconnected(d.deviceId);
          remoteProjectAliases.suspend(d.deviceId);
        } else {
          remoteProjectsStore.removeDevice(d.deviceId);
          remoteProjectAliases.remove(d.deviceId);
          removeRemoteSessionActivityForDevice(d.deviceId);
          // 设备明确离场(关被控 / 本机禁用控制 / 是自己):它的冷缓存一起清掉,
          // 否则下次冷启动会把一台已经不该出现的设备画回侧边栏。
          cacheHydrationBlocked.add(d.deviceId);
          clearCachedDevice(d.deviceId);
        }
        evictDeviceCapabilities(d.deviceId);
        evictDeviceProviders(d.deviceId);
        evictDeviceGitSafetySettings(d.deviceId);
      }
    };

    /** 全量重播(初始 + WS 重连):listDevices 带 isSelf,权威。 */
    const reseed = (): Promise<void> => {
      const generation = directoryGeneration;
      return window.electronAPI.deviceLink
        .listDevices()
        .then(({ devices }) => {
          if (disposed || generation !== directoryGeneration) return;
          for (const d of devices) {
            applyDevice({
              deviceId: d.deviceId,
              name: d.name,
              online: d.online,
              remoteControlEnabled: d.remoteControlEnabled,
              isSelf: d.isSelf,
            });
          }
          // 权威列表里**根本没有**的分片必须在这里收掉:applyDevice 只对返回的设备跑,
          // 账号里已删除的设备(冷启动时由缓存种进来的)否则永远没人评估,会作为
          // disconnected 项目常驻侧边栏,还会被后续快照一直写回盘(review: codex P1)。
          // 只在 listDevices **成功**时做(catch 分支不清):拿不到权威集合就不能判定缺席。
          // eligible 里的设备豁免 —— 它们由 presence 事件管理,listDevices 偶发缺项不该误删。
          //
          // 必须遍历 `getAllDeviceIds()`:缓存种入的分片一律标 disconnected,而
          // `getDeviceIds()` 只返回 connected —— 用它的话这个收敛循环恰好**永远看不到**
          // 要收的那些分片(review: codex 指出上一轮的修复因此无效)。
          const authoritative = new Set(devices.map((d) => d.deviceId));
          for (const deviceId of remoteProjectsStore.getAllDeviceIds()) {
            // SharedTask shards are reconciled against membership, not the own-device directory.
            if (isSharedTaskPeer(deviceId)) continue;
            if (authoritative.has(deviceId) || eligible.has(deviceId)) continue;
            log.debug(`removing cached shard absent from listDevices: ${deviceId.slice(0, 8)}`);
            cancelDeviceReseeds(deviceId);
            clearArchivedSessionRetry(deviceId);
            remoteProjectsStore.removeDevice(deviceId);
            remoteProjectAliases.remove(deviceId);
            removeRemoteSessionActivityForDevice(deviceId);
            // 权威列表里没有它 = 明确离场,和撤销 / 关被控同一档:登记进 hydration 黑名单,
            // 否则在途的那次 readCachedSessionList 落地后又把它种回来,而紧随的 reseed 在
            // listDevices 离线时纠正不了(review: codex P1)。
            cacheHydrationBlocked.add(deviceId);
            clearCachedDevice(deviceId);
          }
        })
        .catch((err) => log.debug('listDevices reseed failed', err));
    };

    // 冷启动首屏:用上次落盘的列表快照把侧边栏画出来(标 disconnected),不等 bootstrap 往返。
    // 已有分片的设备不覆盖;紧随其后的 bootstrap 用权威列表整片替换。
    //
    // 种入后**必须再 reseed 一次**:合格性判定(applyDevice → resolveIneligibleRemoteProjectAction)
    // 依赖 `hasCachedShard`,而这次种入是异步的,很可能落在初始 reseed 之后 —— 那一轮看到
    // 的是"没有分片"于是判 ignore,种进来的设备就没人再评估。app 关闭期间对端关掉被控 /
    // 账号里删掉设备的情形,都靠补这一轮收敛(reseed 末尾还会清掉权威列表中缺席的分片)。
    // 仍在 listDevices 里但离线的设备照既有语义保留为 disconnected —— 与「断连保留最近
    // 一次快照让 All Sessions 稳定」一致,不是本次引入的行为。
    const initialCacheRead = readCachedSessionList().then((devices) => {
      if (disposed || devices.length === 0) return;
      // 读快照这一跳期间被**明确移除**的设备(撤销访问 / 关闭被控 / 本机停用控制)不许种回来:
      // 那些路径已经删了分片并清了盘,而这次种入拿的是它们之前读到的旧快照;紧随的 reseed
      // 在 listDevices 离线时也纠正不了,于是那台设备会一直留在侧边栏(review: codex P1)。
      const usable = devices.filter((device) => !cacheHydrationBlocked.has(device.deviceId));
      if (usable.length === 0) return;
      remoteProjectsStore.hydrateFromCache(usable);
      return reseed();
    }).catch((err) => log.debug('initial remote cache read failed', err));

    // 用户点击失败态重试 → 重走 subscribe + bootstrap,恢复 loading 与完整重试语义。
    setRemoteSessionBootstrapRetryImpl((deviceId) => {
      const name = eligible.get(deviceId);
      if (!name || disposed) return;
      void subscribeAndBootstrap(deviceId, name, true);
    });

    // sessions:created / applyPatch 状态迁移 / 侧栏归档筛选 → 按设备+状态防抖重拉。
    setRemoteReseedImpl((deviceId, status: RemoteSessionStatus) => {
      const name = eligible.get(deviceId);
      if (!name || disposed) {
        if (status === 'archived') {
          clearArchivedSessionRetry(deviceId);
          remoteProjectsStore.clearSessionStatusLoading(deviceId, status);
        }
        return;
      }
      const timerKey = `${deviceId}\u0000${status}`;
      const prev = reseedTimers.get(timerKey);
      if (prev) clearTimeout(prev);
      reseedTimers.set(
        timerKey,
        setTimeout(() => {
          reseedTimers.delete(timerKey);
          if (!disposed && linkOnline && eligible.has(deviceId)) {
            void refreshRemoteDeviceSessions(deviceId, name, {
              snapshotMode: 'merge',
              status,
            }).then((result) => {
              if (result === 'revoked' && !disposed) {
                handleRevoked(deviceId);
              } else if (result === 'gave-up' && status === 'archived') {
                remoteProjectsStore.markSessionStatusFailed(deviceId, status);
                scheduleArchivedSessionRetry(deviceId);
              } else if (result === 'superseded' && status === 'archived') {
                clearArchivedSessionRetry(deviceId);
                remoteProjectsStore.clearSessionStatusLoading(deviceId, status);
              } else if (result === 'ok' && status === 'archived') {
                clearArchivedSessionRetry(deviceId);
              }
            });
          } else if (status === 'archived') {
            clearArchivedSessionRetry(deviceId);
            remoteProjectsStore.clearSessionStatusLoading(deviceId, status);
          }
        }, RESEED_DEBOUNCE_MS),
      );
    });
    const periodicReconcile = startRemoteSessionsReconciler(
      () => (linkOnline ? [...eligible].filter(([id]) => !unresponsiveDevicesStore.has(id)) : []),
      async (deviceId, name) => {
        log.debug(`sessions refresh trigger=periodic window=${windowRole} peer=${deviceId.slice(0, 8)} visible=${periodicReconcileActiveRef.current}`);
        if (sessionsSubscribeRetry.has(deviceId)) {
          // 与 bootstrap 同一串行任务:在途的 bootstrap 直接复用,不并发第二路 subscribe。
          await subscribeAndBootstrap(deviceId, name ?? eligible.get(deviceId) ?? deviceId, false, 'resubscribe');
          if (disposed || !eligible.has(deviceId)) return 'superseded';
        }
        // sessions:list 是 200 条有界窗口;refresh 层会保留窗口外 active 行,并有界补查
        // 缺席缓存 id 的终态,不能直接把响应缺席解释成删除。
        void refreshAliases(deviceId);
        const result = await refreshRemoteDeviceSessions(deviceId, name, {
          scope: 'both',
          snapshotMode: 'merge',
          coalescingMode: 'weak',
        });
        if (result === 'revoked' && !disposed) handleRevoked(deviceId);
        // 回传结果供 reconciler 的失败退避记账('gave-up' 加深退避,'ok' 复位)。
        return result;
      },
      RECONCILE_INTERVAL_MS,
      // 失败退避阶梯沿用 10s 基准;健康设备另受 60s 间隔约束。
      createReconcileBackoff({ baseMs: RECONCILE_TICK_MS }),
      () => periodicReconcileActiveRef.current && (mainPresenceRef.current?.isActive() ?? true),
      // sessions 订阅缺口没有 push 兜底:保持每拍补订 + 对账。
      { tickMs: RECONCILE_TICK_MS, needsEveryTick: (deviceId) => sessionsSubscribeRetry.has(deviceId) },
    );
    wakeRemoteReconcileRef.current = periodicReconcile.wake;

    // 目标设备「无响应」熔断翻转(main 权威):镜像给 UI;恢复时重跑 subscribe+bootstrap
    // ——熔断 open 期间的订阅 / 首拉都被快速失败挡掉了,恢复必须主动补,不能等用户手点。
    // push 一旦到达即权威,但只对**它自己那台设备**权威:迟到的 getState 快照按设备合并,
    // 未被 push 覆盖的设备仍取快照值 —— 整份丢弃会让「A 设备先来一条 push」掩盖掉
    // 快照里 B 设备的 unresponsive 初值,B 在下一次熔断翻转前一直假装 connected(review P1)。
    const responsivenessPushedDeviceIds = new Set<string>();
    const offResponsiveness = window.electronAPI.deviceLink.onResponsivenessChanged((p) => {
      if (disposed) return;
      responsivenessPushedDeviceIds.add(p.deviceId);
      unresponsiveDevicesStore.apply(p.deviceId, p.unresponsive);
      if (!p.unresponsive && p.recovered !== false) {
        const name = eligible.get(p.deviceId);
        if (name) void subscribeAndBootstrap(p.deviceId, name, true);
      }
    });

    const initialDirectoryRead = window.electronAPI.deviceLink
      .getState()
      .then((state) => {
        if (disposed) return;
        if (!linkStatusPushSeen) linkOnline = state.linkStatus === 'online';
        // Presence can start bootstrap before this initial snapshot settles.
        // Reuse disconnect cleanup to clear loading and invalidate in-flight snapshots.
        if (!linkStatusPushSeen && !linkOnline) {
          remoteProjectsStore.markAllDisconnected();
          for (const deviceId of eligible.keys()) remoteProjectAliases.suspend(deviceId);
        }
        if (!controlTargetPushSeen) disabledControlDeviceIds = new Set(state.disabledControlDeviceIds ?? []);
        // 「无响应」熔断镜像的初值:按设备合并,已被 push 覆盖的设备以 push 为准
        // (store 初始为空,快照只需补写 unresponsive 的未覆盖设备)。
        for (const deviceId of state.unresponsiveDeviceIds ?? []) {
          if (!responsivenessPushedDeviceIds.has(deviceId)) {
            unresponsiveDevicesStore.apply(deviceId, true);
          }
        }
        return reseed();
      })
      .catch((err) => {
        log.debug('getState before device-link reseed failed', err);
        if (!disposed) return reseed();
      });

    // Neither an empty bootstrap set nor the first completed read alone proves
    // the remembered remote task is absent. Per-device loading takes over once
    // discovery starts bootstrap; failures and cleanup must release this gate.
    void Promise.allSettled([initialCacheRead, initialDirectoryRead]).then(() => {
      clearTimeout(initialDiscoveryTimer);
      finishInitialDiscovery();
    });

    const offPresence = window.electronAPI.deviceLink.onPresenceChanged((snap) => {
      applyDevice({
        deviceId: snap.deviceId,
        name: snap.deviceName,
        online: snap.online,
        remoteControlEnabled: snap.remoteControlEnabled,
        isSelf: snap.deviceId === selfDeviceId,
      });
    });

    // 被控端 active-catalog 变化:供应商目录与 capabilities.availableModels 必须同代刷新。
    // 两套缓存订阅会把完整结果原子推给已挂载选择器,刷新期间保留旧列表避免空白跳变。
    const offRemotePush = window.electronAPI.deviceLink.onRemotePush((push, localOwnerStamp) => {
      if (disposed || !eligible.has(push.deviceId)) return;
      if (push.channel === PROJECT_ALIASES_CHANGED_CHANNEL) {
        const lifecycleEpoch = remoteProjectsStore.getDeviceLifecycleEpoch(push.deviceId);
        if (remoteProjectAliases.acceptChanged(push.deviceId, push.ownerStamp, localOwnerStamp,
          () => canBootstrap(push.deviceId, lifecycleEpoch))) void refreshAliases(push.deviceId, true);
        return;
      }
      if (!isDeviceLinkRemotePushCurrent(push, localOwnerStamp)) return;
      if (windowRole === 'main' && push.channel === 'local-db:sessions:patched') {
        const payload = push.payload as { sessionId?: string; patch?: { lastTurnEndedAt?: unknown } } | null;
        if (typeof payload?.sessionId === 'string' && payload.patch && historyTurnEnded({}, payload.patch)) {
          const sessionId = payload.sessionId;
          // Let the ordinary push router apply metadata first, independent of
          // listener registration order. Only this completed task is eligible.
          queueMicrotask(() => {
            if (!disposed && eligible.has(push.deviceId) && isDeviceLinkRemotePushCurrent(push, localOwnerStamp)) {
              void makerChatStore.prefetchRemoteHistories(push.deviceId, new Set([sessionId]));
            }
          });
        }
      }
      if (push.channel === 'maker:schedule:event') {
        // 推送照收;闲着不跟事件去拉整份自动化索引。人回来 / 窗口重新可见时 wake 用 scope both 补上。
        const watching =
          periodicReconcileActiveRef.current && (mainPresenceRef.current?.isActive() ?? true);
        if (!watching) return;
        // 与手机同一份事件投影:运行诊断、静默提醒这类不改索引的事件不重拉,
        // 否则 run 进行期间高频推送会反复取消在途的列表 / 索引读取。
        const { refresh } = projectScheduleEvent(push.payload);
        if (!refresh.sessionIndex && !refresh.scheduleList && !refresh.unreadSummary) return;
        void refreshRemoteDeviceSessions(push.deviceId, eligible.get(push.deviceId), { scope: 'schedule' }).then((result) => {
          if (result === 'revoked' && !disposed) handleRevoked(push.deviceId);
        });
        return;
      }
      if (push.channel !== 'maker:provider:changed') return;
      void refreshRemoteCatalogSnapshot(push.deviceId);
    });

    // WS 重连后:presence 重新对齐 + 对每个已合格设备重新 subscribe + 重新 bootstrap
    // (被控端可能重启过、订阅 registry 清空,这步重建订阅;reseed 补新设备)。
    const offStatus = window.electronAPI.deviceLink.onStatusChanged((p) => {
      const wasOnline = linkOnline;
      linkStatusPushSeen = true;
      linkOnline = p.status === 'online';
      if (p.status !== 'online') {
        clearAllArchivedSessionRetries();
        for (const deviceId of eligible.keys()) remoteProjectAliases.suspend(deviceId);
        // relay 瞬时重连(connecting):保留远程会话镜像,只标记 disconnected,让 All Sessions
        // 不因网络抖动反复增删/重排。eligible 保留不动 → 重连 online 时下面的分支自动
        // 重 subscribe+bootstrap。stopped(登出 / 停服)才清空。
        if (p.status === 'connecting') {
          remoteProjectsStore.markAllDisconnected();
          return;
        }
        // 顺序要紧:cancel 必须在 clear **之后**。`clear()` 在 shards 非空时会同步通知
        // 订阅者,而此刻 offShardChange 仍挂着 → 它立刻排一个去抖回写;1200ms 后 shards
        // 已空,整份快照被写成 [],main 侧据此把 session-list.json 删掉。于是「relay 停服
        // (非登出)」会在约 1.2s 后抹掉侧边栏冷缓存 —— 而「停服后重启、relay 仍未恢复」
        // 正是这份缓存要解决的场景(review: P2)。整体删除只归 owner 边界的 clearAll。
        clearTimeout(initialDiscoveryTimer);
        remoteProjectsStore.clear();
        remoteProjectAliases.clear();
        cancelSessionListPersist();
        clearRemoteSessionActivity();
        // 'stopped'(登出 / 停服)还要清掉「已撤销」标记:否则切换栏的 buildSwitcherDevices 仍会拿
        // revoked 集合单独撑起一颗 rejected chip,停服后切换栏残留陈旧被拒 chip。'connecting' 是瞬态
        // 重连,被拒状态应跨重连保留(正常在线期一直可见),故不清。登出 unmount 时的 clearAll 仍是兜底。
        if (p.status === 'stopped') revokedDevicesStore.clearAll();
        return;
      }
      if (wasOnline) return;
      for (const [deviceId, name] of eligible) void subscribeAndBootstrap(deviceId, name);
      reseed();
    });

    // 控制端:被某被控端撤销访问权限(收到其 link-close('revoked'))→ 立即移除 + 标记已撤销。
    const offAccessRevoked = window.electronAPI.deviceLink.onAccessRevoked((p) => {
      if (!disposed) handleRevoked(p.deviceId);
    });

    // A peer reset can lose invalidations while relay presence stays online.
    const offPeerReset = window.electronAPI.deviceLink.onPeerLinkReset?.(({ deviceId }) => {
      remoteProjectAliases.suspend(deviceId);
      if (!disposed) void refreshAliases(deviceId);
    });

    const offControlTarget = window.electronAPI.deviceLink.onControlTargetChanged((p) => {
      if (disposed) return;
      controlTargetPushSeen = true;
      disabledControlDeviceIds = new Set(p.disabledControlDeviceIds ?? []);
      if (!p.enabled) {
        cancelDeviceReseeds(p.deviceId);
        remoteProjectAliases.remove(p.deviceId);
        clearArchivedSessionRetry(p.deviceId);
        const wasEligible = eligible.delete(p.deviceId);
        if (wasEligible) {
          window.electronAPI.deviceLink.unsubscribe(p.deviceId, ['sessions']).catch(() => {});
        }
        if (wasEligible || remoteProjectsStore.hasDevice(p.deviceId)) {
          remoteProjectsStore.removeDevice(p.deviceId);
          removeRemoteSessionActivityForDevice(p.deviceId);
          evictDeviceCapabilities(p.deviceId);
          evictDeviceProviders(p.deviceId);
          evictDeviceGitSafetySettings(p.deviceId);
        }
        // 本机关掉「控制这台设备」→ 盘上那份镜像缓存也要清。只清内存分片的话,下次冷启动
        // hydrateFromCache 会把这台已经明确禁用控制的设备连着它的会话画回侧边栏
        // (review: greptile)。放在 if 外面:即使此刻内存里没有分片(本次会话从未连上它),
        // 盘上仍可能留着上一次运行写下的缓存。
        cacheHydrationBlocked.add(p.deviceId);
        clearCachedDevice(p.deviceId);
        return;
      }
      reseed();
    });

    // 设备改名:服务端 REST 改名不广播 presence,接入器对齐缓存名(store 分片由 renameDevice 即时改)。
    const offRename = remoteProjectsStore.subscribeRename((deviceId, name) => {
      if (eligible.has(deviceId)) eligible.set(deviceId, name);
    });

    const offRemoval = subscribeDeviceLinkDeviceRemoval((deviceId) => {
      // Deletion is authoritative even if the directory is unavailable or a cold read is in flight.
      directoryGeneration += 1;
      cacheHydrationBlocked.add(deviceId);
      clearCachedDevice(deviceId);
      cancelDeviceReseeds(deviceId);
      clearArchivedSessionRetry(deviceId);
      sessionsSubscribeRetry.delete(deviceId);
      remoteProjectAliases.remove(deviceId);
      if (eligible.delete(deviceId)) {
        window.electronAPI.deviceLink.unsubscribe(deviceId, ['sessions']).catch(() => {});
      }
      removeRemoteSessionActivityForDevice(deviceId);
      evictTaskTagCatalog(deviceId);
      evictDeviceCapabilities(deviceId);
      evictDeviceProviders(deviceId);
      evictDeviceGitSafetySettings(deviceId);
    });

    // 冷缓存回写由「分片变更」驱动,而不是只在一次成功 refresh 之后:
    // 被控端推来的 archived / deleted 增量(applyPatch)只改内存,若 app 在下一次周期对账
    // 之前退出,下次离线冷启动就会把那条已归档 / 已删除的会话又 hydrate 回侧边栏
    // (review: codex P1)。订阅覆盖所有 mutation(snapshot / patch / 改名 / 断连 / 移除),
    // 去抖 1200ms 合并高频变更,main 侧还有内容指纹去重 —— 内容没变根本不落盘。
    const offShardChange = remoteProjectsStore.subscribe(() => {
      if (disposed) return;
      scheduleSessionListPersist(collectSessionListSnapshot);
    });

    return () => {
      disposed = true;
      clearTimeout(initialDiscoveryTimer);
      setRemoteReseedImpl(null);
      setRemoteSessionBootstrapRetryImpl(null);
      wakeRemoteReconcileRef.current = () => undefined;
      periodicReconcile.stop();
      for (const t of reseedTimers.values()) clearTimeout(t);
      reseedTimers.clear();
      clearAllArchivedSessionRetries();
      bootstrapTasks.clear();
      offPresence();
      offRemotePush();
      offStatus();
      offAccessRevoked();
      offPeerReset?.();
      offControlTarget();
      offRename();
      offRemoval();
      offShardChange();
      offResponsiveness();
      unresponsiveDevicesStore.clearAll();
      // best-effort 取消所有订阅(被控端 presence-offline 也会兜底清僵尸订阅)+ 驱逐远端快照缓存。
      for (const deviceId of eligible.keys()) {
        window.electronAPI.deviceLink.unsubscribe(deviceId, ['sessions']).catch(() => {});
        evictDeviceCapabilities(deviceId);
        evictDeviceProviders(deviceId);
        evictDeviceGitSafetySettings(deviceId);
      }
      // 卸载可能只是关了个窗口(镜像是每渲染进程一份),盘上缓存**不动** ——
      // 只作废尚未落盘的回写,免得它把正在清空的分片写回去。
      // cancel 放在 clear 之后(同 'stopped' 分支):这里 offShardChange 已退订,clear 通知不到
      // 任何订阅者,但顺序保持一致,免得将来有人在两者之间插入新的订阅。
      remoteProjectsStore.clear();
      remoteProjectAliases.clear();
      cancelSessionListPersist();
      clearRemoteSessionActivity();
      revokedDevicesStore.clearAll();
    };
  }, [isAuthenticated, selfDeviceId, windowRole]);
}