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。

288 KB
Raw Blame
import { isTeammateTask } from './teammateTaskSource';
import { readTokenSpeedSnapshot, type TokenSpeedSnapshot } from '@cindy/maker-shared/usage-format';
import { historyTurnEnded, nextHistoryCacheReceipt } from '@cindy/maker-shared/message-window';
import { normalizeTaskTags, reconcileTaskTags } from '@cindy/maker-shared';
import {
  createContext,
  createElement,
  useCallback,
  useContext,
  useEffect,
  useLayoutEffect,
  useMemo,
  useRef,
  useSyncExternalStore,
  type ReactNode,
} from 'react';
import { PausableSubscriptions } from './pausableSubscriptions';
import {
  MAKER_EVENT_BATCH_CHANNEL,
  SESSION_ACTIVITY_CHANNEL,
  SESSION_SYNC_CHANNEL,
  expandMakerEventBatchPayload,
  type SessionActivityPayload,
} from '@cindy/device-link';
import {
  applyAgentTaskUpdateEvent,
  isSameAgentTaskAlias,
  normalizeAgentTaskUpdate,
  type AgentTaskUpdate,
} from '@cindy/maker-shared/agent-task';
import type { MobileGoalStatusPayload } from '@cindy/maker-shared/device-link-contract';
import { isRemoteTextDelta, readRemoteTextSnapshot, reconcileRemoteText, consumeRemoteSessionSync } from '@cindy/maker-shared/message-window';
import { applyCodexPlanSnapshotOnDone, markCodexPlanTurnFailed } from '@cindy/maker-shared/message-render';
import {
  buildSessionMessagePreviewIndex,
  sessionRowMessagePreview,
  type RemoteSessionLiveActivity,
} from '@cindy/maker-shared/session-list';
import { buildDeviceIdentity, resolveCanonicalDeviceId } from '@cindy/maker-shared/mobile-home';
import {
  isProductTurnDoneEvent,
  isTurnContinuationBoundaryEvent,
} from '@cindy/maker-shared/turn-continuation';
import { isDefaultDraftSessionTitle } from '@cindy/maker-shared/session-title';
import { CINDY_MAKE_ENABLED, isCindyMakeSource } from '@cindy/maker-shared/cindy-make-feature';
import { EMPTY_INPUT_PROJECTION, normalizeInputProjection } from '@/session/inputProjection';
import { sortPendingInteractions } from '@/session/interactionModel';
import { clearAskUserDraft } from '@/session/interactionDraftStore';
import { applySessionModelPrefPush } from '@/session/sessionModelMirror';
import {
  createLatestWriteGuard,
  createPendingWriteTracker,
  createSessionWriteQueue,
} from '@/session/swipeRowRegistry';
import {
  cacheSessionMessagesIfCurrent,
  cacheSessionListMessage,
  captureSessionMessageCacheWriteAuthority,
  getCachedSessionMessages,
  isSessionMessageCacheWriteAuthorityCurrent,
  replaceCachedSessionMessages,
} from '@/session/mobileSessionMessageCache';
import { readComposerDocumentDraftSync, readComposerDraftSync } from '@/session/composerDraftStore';
import { composerDocumentHasContent } from '@/session/composerDocument';
import { getQuotes } from '@/session/chatQuoteStore';
import {
  sessionMessageLifecycle,
  type SessionMessageAuthority,
  type SessionMessageReclaimReason,
  type SessionMessageUnenteredAuthority,
  type SessionMessageWorkLease,
} from '@/session/sessionMessageLifecycle';
import { classifySessionRetention, type SessionRetentionKind } from '@/session/sessionRetention';
import { clearRemoteHistoryViews, resetRemoteHistoryViews } from '@/session/remoteHistoryViews';
import { clearHistoryDisk } from '@/session/remoteHistoryDiskCache';
import { contentToPreview } from '@/utils/contentPreview';
import type { MobileSystemCardType } from '@/session/systemCard';
import type { InputProjection, PendingInteraction, RemoteMessage, RemoteSession } from '@/session/types';
import { clampLiveRowCreatedAt, compareMessageOrder, MESSAGE_PAGE_SIZE } from '@/session/messagePaging';
import { normalizeRemoteMoney } from '@/session/remoteMoney';
import { projectLargeSettledToolInputs } from '@/session/messageToolPayloadProjection';
import { setRemoteSessionStoreSizeSource } from '@/debug/jankMetrics';

interface DeviceShard {
  deviceId: string;
  deviceName: string;
  sessions: RemoteSession[];
}

export interface RemoteNewMakerWorktreePreference {
  enabled: boolean;
  /**
   * 每次 pull / push / 本机显式点击都递增。新建页用它给在途 one-shot pull 做 fence,
   * 防止较早发出的响应覆盖后来到达的工作端 push 或用户选择。
   */
  revision: number;
}

const EMPTY_NEW_MAKER_WORKTREE_PREFERENCE: RemoteNewMakerWorktreePreference =
  Object.freeze({ enabled: false, revision: 0 });

/**
 * 工作端拥有的 New Maker worktree 源分支镜像。null 表示该 device + canonical
 * baseRepo 尚无显式选择;revision 完全采用工作端快照,手机不自行递增。
 */
export type RemoteNewMakerWorktreeBranchPreference = {
  baseRepo: string;
  sourceBranch: string;
  revision: number;
} | null;

/**
 * 会话元数据在途写登记(app 级单例):首页乐观写(置顶/归档/删除/重命名)begin 时
 * track、settle 时 release;`sessions:patched` push 应用前经 filterPatch 遮蔽在途
 * 字段,防止同字段旧写的 push 回流把本机更新的乐观意图滚回(review P2)。
 */
export const sessionPendingWrites = createPendingWriteTracker();
// List-only previews reuse the existing counted tracker. Raw rows remain available
// to details and metadata reconciliation until archive is actually confirmed.
let sessionListRemovalPreviews = createPendingWriteTracker();

/**
 * 会话元数据写序守卫与出网队列(app 级单例):首页滑动操作与会话详情页菜单是同一组
 * 元数据写的两个入口,写序状态与同字段串行必须**跨页面共享**(review P1:首页置顶
 * 在退避中,进详情页取消置顶——组件实例级守卫感知不到对方,退避恢复后旧写覆盖新写)。
 */
export const sessionMetaWriteGuard = createLatestWriteGuard();
export const sessionMetaWriteQueue = createSessionWriteQueue();

/**
 * 会话元数据写的两个设备 id(首页 / 设备详情 / 会话页菜单 / 协同 Worker 归档共用):
 *  - rpcDeviceId:出网目标,默认取展示用规范 id(re-link 后认领回当前设备);调用方已按
 *    路由连着某台设备(会话页)时传 preferredRpcDeviceId 沿用它;
 *  - shardId:乐观 patch 与失败回滚落的**物理** shard(行真实所在)。re-link 后两者可能
 *    不同:按规范 id 落 shard 会让乐观移行落空、回滚插进另一个 shard 成重复行。
 * 都解析不到时返回 null(调用方按「找不到设备」处理)。
 */
export function resolveSessionWriteDevices(
  sessionId: string,
  session: Pick<RemoteSession, 'canonicalDeviceId' | 'deviceLinkDeviceId'> | null | undefined,
  preferredRpcDeviceId?: string | null,
): { rpcDeviceId: string; shardId: string } | null {
  const indexedDeviceId = sessionDeviceIndex.get(sessionId);
  const rpcDeviceId = preferredRpcDeviceId || session?.canonicalDeviceId || session?.deviceLinkDeviceId
    || indexedDeviceId;
  if (!rpcDeviceId) return null;
  return { rpcDeviceId, shardId: session?.deviceLinkDeviceId || indexedDeviceId || rpcDeviceId };
}

export interface RemoteSessionRunStatus {
  isRunning: boolean;
  /** Terminal failure remains sticky until the next run, even after read acknowledgement. */
  hasTerminalError?: boolean;
  reconnectAttempt: RemoteSessionReconnectAttempt | null;
  sideTaskRunning: boolean;
  startedAt: number | null;
  status: string;
  tokenUsage: number;
  outputTokens: number;
  generationDurationMs: number;
  generationActive: boolean;
  generationReliable: boolean;
  /** 电脑端测得的实时速度(Pi 扩展算法);旧版电脑不发。 */
  tokenSpeed?: TokenSpeedSnapshot;
}

export interface RemoteSessionReconnectAttempt {
  attempt: number;
  maxAttempts: number;
  /**
   * 重试原因。`'overload'` = 上游模型没有可用容量;`'rate-limit'` = Codex daemon
   * 已耗尽内部 retry budget 后的受限外层重投;缺省 / `'reconnect'` = 传输层重连。
   *
   * 刻意复用同一个字段而不是新加一个: 这个 attempt 有 6 处清理点(turn 边界 / 快照 /
   * 收口 / 活动流), 拆成两个字段就得在每处各清一次, 漏一处就会残留一个假状态。
   */
  kind?: 'reconnect' | 'overload' | 'rate-limit';
}

interface SessionMessageSyncMarker {
  messageCount: number | null;
  updatedAt: string;
  preview?: string | null;
}

export interface SetLatestMessageWindowOptions {
  /** 读取发起时捕获的详情代际;失焦或重新聚焦后旧响应必须拒写。 */
  authority?: SessionMessageAuthority;
  /**
   * 本页**上沿之外服务端还有历史**(满页,或被 device-link 裁过行)。
   *
   * 真为真时,早于本页最旧行的缓存段一律不保留 —— 它与本页之间可能隔着从未加载的行,保留就会
   * 在窗口里留下孤岛(详见 `setLatestMessageWindow` 里的说明与 #1222)。调用方用既有的
   * `hasMoreOlderMessages` / `shouldKeepOlderMessagesAffordance` 判定即可,不需要自己数。
   *
   * 省略时按 false 处理(保持旧行为):调用方拿不到分页元信息时不该因此丢历史。
   */
  moreBeyondWindow?: boolean;
}

export interface SessionMessageWriteOptions {
  listMessage?: boolean;
  authority?: SessionMessageAuthority;
  /** 本行是否携带主机时间域的 createdAt;本地临时卡必须显式关闭。 */
  hostTimeAuthoritative?: boolean;
}

interface LivePlanSnapshot {
  content: Record<string, unknown>;
  persistId?: string;
  toolUseId: string;
}

const EMPTY_SESSION_RUN_STATUS: RemoteSessionRunStatus = Object.freeze({
  isRunning: false,
  reconnectAttempt: null,
  sideTaskRunning: false,
  startedAt: null,
  status: '',
  tokenUsage: 0,
  outputTokens: 0,
  generationDurationMs: 0,
  generationActive: false,
  generationReliable: true,
});

const shards = new Map<string, DeviceShard>();
// Per-device list mutation fence. A sessions:list request may start before a live
// sessions:created/patched push and settle after it; that older whole-list snapshot must
// never overwrite the newer push. Epochs stay monotonic across account/store resets.
const deviceSessionListMutationEpochs = new Map<string, number>();
let deviceSessionListMutationEpochFloor = 0;
let nextDeviceSessionListMutationEpoch = 0;

function bumpDeviceSessionListMutationEpoch(deviceId: string): void {
  if (!deviceId) return;
  deviceSessionListMutationEpochs.set(deviceId, ++nextDeviceSessionListMutationEpoch);
}

function readDeviceSessionListMutationEpoch(deviceId: string): number {
  return deviceSessionListMutationEpochs.get(deviceId) ?? deviceSessionListMutationEpochFloor;
}
// 工作端拥有的 New Maker worktree 偏好按设备隔离;这里只是不持久化的显示镜像,
// push 属 sessions topic,无 sessionId。唯一持久副本仍在被控端现有 Cindy 配置里。
const newMakerWorktreePreferences = new Map<string, RemoteNewMakerWorktreePreference>();
// deviceId → canonical baseRepo → 工作端权威分支快照。分支与 checkbox 是两份独立镜像;
// 任一分支 pull / push / write-back 都不得改动 newMakerWorktreePreferences。
const newMakerWorktreeBranchPreferences = new Map<
  string,
  Map<string, Exclude<RemoteNewMakerWorktreeBranchPreference, null>>
>();
const messages = new Map<string, RemoteMessage[]>();
// Rows a never-opened session received from list pushes. While the mirror holds only these,
// it is not a loaded window: opening the task still merges the disk cache underneath them.
const listMessageKeys = new Map<string, Set<string>>();
// The maker event is broadcast before its async DB create/update completes. Keep the latest
// plan snapshot briefly in the session mirror so a late initial `messages:created` row cannot
// overwrite a newer live state with the first stale 0/N snapshot.
const livePlanSnapshots = new Map<string, Map<string, LivePlanSnapshot>>();
const pendingInteractions = new Map<string, PendingInteraction[]>();
// Editing is local to the controller. It must not keep a provider turn alive.
const protectedQuestions = new Map<string, PendingInteraction>();
const visibleInteractionCache = new Map<string, { raw: PendingInteraction[]; protected?: PendingInteraction; result: PendingInteraction[] }>();
/**
 * 这个会话的 pending 列表当前是不是**权威**的(来自被控端的一次全量快照)。
 *
 * 空列表有两种来源,消费方光看 `getPendingInteractions()` 分辨不了:
 * - 权威的空:被控端确认所有请求都已回答 / 撤销;
 * - 非权威的空:`markDeviceOffline` / `removeDevice` 按设计清掉了这份投影(它依赖
 *   实时连接),此刻我们其实不知道被控端还在等什么。
 *
 * 凡是「空快照才能做的清理」都必须先问这里,否则短暂离线会被误判成「都处理完了」。
 * 不能退化成看全局 relay status:目标设备 offline 时 relay 仍可能 online(#1493 review)。
 */
const pendingInteractionsAuthoritative = new Set<string>();
/**
 * 乐观 resolve 在途抑制集合:交互卡批准 / 拒绝已在本地乐观撤卡、被控端还没有
 * 确认的 requestId。这个窗口里权威流(全量快照 setPendingInteractions / push
 * 重放 applyInteractionRequest)可能把同一张卡重新灌回来造成「闪回」——凡在
 * 集合中的 request 一律过滤。失败复原时由 InteractionPanel 显式移除;成功时
 * 转入 confirmedInteractionDismissals 延长抑制(见下)。
 * key = `${sessionId}\u0000${requestId}`。
 */
const inFlightInteractionResolves = new Set<string>();
/**
 * 已确认 dismiss 的延长抑制集合:resolve 成功后**不能立即**解除过滤——在决定
 * 提交前发出、resolve 之后才返回的慢权威读取(syncSession 的 getPendingInteractions,
 * 弱网正是高发场景)仍持有含这张卡的旧快照,直接落地会闪回(codex review P2)。
 * 条目留到「一轮不含该 requestId 的全量快照」到达(被控端已确认移除,自然过期)
 * 才删除;interaction-dismissed push **不**提前回收——push 之后仍可能有更早发出
 * 的在途旧快照晚到(见 applyRemotePush 该分支注释)。
 */
const confirmedInteractionDismissals = new Set<string>();

function interactionResolveKey(sessionId: string, requestId: string): string {
  return `${sessionId}\u0000${requestId}`;
}

/**
 * revision 化交互(当前只有 plugin_setup)的**决定下限**:本端已经对某个 revision
 * 提交过决定后,该 request 还能接受的最低 revision。
 *
 * 只有一个来源:本端对 revision R 提交过决定(plugin_setup 取消)→ 下限抬到 R+1。
 * R 及更旧的快照正是我决定之前的那批,滤掉才不会在决定生效后把卡带回来
 * (取消成功的 dismiss push 先到、取消前发出的慢快照后到)。
 *
 * 为什么不是「取消后无条件抑制该 requestId」(confirmedInteractionDismissals 那种):
 * 这类决定不是终局 —— 被控端按 `expectedRevision` 裁决,对不上时改为重新体检并推
 * 更高 revision 的新快照。无条件抑制会让那张仍需用户处理的卡永久隐身;下限则天然
 * 放行 R+1 及以后的快照。
 *
 * 下限只升不降,也**不按单轮快照回收**:一旦允许回落,晚到的旧快照就又拿回了覆盖权
 * (#530 review)。条目数等于会话里被取消过的 plugin_setup 请求数(极小),随
 * removeDevice / clear 清理。
 *
 * 注意它只管「成员能不能回来」。快照之间的乱序(没有任何决定,单纯弱网早发晚到)由
 * pickFresherInteraction 就地比较 revision 解决,不走这张表。
 */
const interactionRevisionFloors = new Map<string, number>();

/**
 * 合法的交互 revision:非负整数,与被控端对 `expectedRevision` 的要求一致
 * (parseGhostSetupInteractionCommand)。负数 / 小数不参与新旧比较与抑制判定,
 * 免得非法快照混进 revision 语义里(#530 review)。
 */
function interactionRevision(item: PendingInteraction): number | null {
  const revision = item.request.revision;
  return typeof revision === 'number' && Number.isInteger(revision) && revision >= 0 ? revision : null;
}

/**
 * 同一 request 的两份快照取较新者。
 *
 * dedupe 只按 requestId、后写覆盖,所以一份早发晚到的旧快照会把 UI 从 revision 6
 * 换回 4,用户随后点取消还会发出过期的 expectedRevision(#530 review)。成员关系仍
 * 以权威快照为准,这里只保证**内容不回退**。
 */
function pickFresherInteraction(
  incoming: PendingInteraction,
  existing: PendingInteraction | undefined,
): PendingInteraction {
  if (!existing) return incoming;
  const incomingRevision = interactionRevision(incoming);
  const existingRevision = interactionRevision(existing);
  // 手上那份不带 revision(非 revision 化交互)→ 沿用既有的后写覆盖语义。
  if (existingRevision === null) return incoming;
  // 手上那份已进入 revision 语义,而来的一份连 revision 都没有(旧被控端 / 非法
  // 快照)→ 它没有资格覆盖:否则同样会把内容换回旧版本,并让取消发出过期的
  // expectedRevision(#530 review)。
  if (incomingRevision === null) return existing;
  return incomingRevision < existingRevision ? existing : incoming;
}

function isInteractionResolveSuppressed(sessionId: string, item: PendingInteraction): boolean {
  const requestId = item.request.requestId;
  if (typeof requestId !== 'string' || requestId.length === 0) return false;
  const key = interactionResolveKey(sessionId, requestId);
  if (inFlightInteractionResolves.has(key) || confirmedInteractionDismissals.has(key)) return true;
  const floor = interactionRevisionFloors.get(key);
  if (floor === undefined) return false;
  const revision = interactionRevision(item);
  // revision 缺失(旧被控端 / 非法快照)时保守过滤:这个 request 已经进入 revision
  // 语义,一份连 revision 都没有的快照没有资格把它带回来。
  return revision === null || revision < floor;
}

function interactionsByRequestId(list: readonly PendingInteraction[]): Map<string, PendingInteraction> {
  const byId = new Map<string, PendingInteraction>();
  for (const item of list) {
    const requestId = item.request.requestId;
    if (typeof requestId === 'string' && requestId.length > 0) byId.set(requestId, item);
  }
  return byId;
}
const inputProjections = new Map<string, InputProjection>();
/**
 * 新建任务第一帧标题预览。权威行在自动起名写库前仍是 New Maker;入队成功后
 * pendingLocalCreation 必须清掉才能解禁,所以预览不能绑在那根标上。权威标题
 * 一旦离开哨兵(智能标题或用户改名)就让位。
 */
const pendingTitlePreview = new Map<string, string>();
// Projection queries can resolve after a newer push or terminal boundary. Keep
// a monotonic per-session authority epoch so late snapshots cannot overwrite
// current queue / continuation state (mirrors Desktop makerChatStore).
const inputProjectionAuthorityEpochs = new Map<string, number>();
let nextInputProjectionAuthorityEpoch = 0;
let inputProjectionAuthorityEpochFloor = 0;
const inputProjectionRemoteEpochs = new Map<string, number>();
let nextInputProjectionRemoteEpoch = 0;
let inputProjectionRemoteEpochFloor = 0;
const inputProjectionRemoteQueuedEvidence = new Map<string, Map<string, number>>();
const INPUT_PROJECTION_REMOTE_EVIDENCE_LIMIT = 256;
const sessionLiveActivity = new Map<string, RemoteSessionLiveActivity>();
const sessionRunning = new Map<string, boolean>();
const sessionRunStatus = new Map<string, RemoteSessionRunStatus>();
// Pushes can precede the first task list. Keep their provenance until list
// reconciliation can decide whether they belong to the selected task row.
const sessionRuntimeSources = new Map<string, string>();
const sessionInteractionSources = new Map<string, string>();
// `maker:list-active` snapshots race live maker pushes during reconnect hydration. A snapshot
// may clear an older transient reconnect attempt, but must not erase a newer retry event that
// arrived after the request started.
const sessionMakerActivityEpochs = new Map<string, number>();
let makerActivityEpoch = 0;
const sessionMessageSyncMarkers = new Map<string, SessionMessageSyncMarker>();
/**
 * 每会话「已验证连续覆盖区间」:`[since, until]`(闭区间,ISO createdAt)内的**所有**服务端行都在
 * 窗口里 —— 中间没有服务端有、本地没加载的行。缺省(未登记)= 未知,窗口不被信任为连续。
 *
 * 为什么需要它:`setLatestMessageWindow` 判断"要不要保留早于本页的旧段"时,只有两种旧段
 *  - **来源不明的缓存**(冷开 hydrate 的那页):与本页的关系无从确认,本页上沿之外还有服务端历史
 *    时必须丢弃,否则窗口留下孤岛(#1222);
 *  - **已验证连续的历史**(整窗替换的那一页、用户一路「加载更早」翻出来的、以及订阅未断时收到的
 *    实时 push):与本页确实相接。把它一并丢掉会让用户正在看的历史和滚动锚点凭空消失,而且自动
 *    补齐也不会拉回(裁完窗口里已经没有内部跳变可发现了)——#1210 review 实测到的回归。
 * 区间就是区分这两者的那条线:旧行落在 `[since, until]` 内、**且本页最旧行不晚于 `until`**
 * (两段首尾相接)时才保留。
 *
 * 为什么不能只记下界:下界断言的是"从它到**窗口最新端**连续",而"窗口最新端"会被断流期间漏收的
 * 行悄悄作废 —— 旧窗 1–80,断线漏收 81–200,重连后先到一条 push 201,再收到最新页 122–201:
 * 窗口最新端已经跳到 201,下界仍指着 1,旧结论于是给"1–80 + 122–201"这个孤岛背了书。把上界显式
 * 记下来,这类"接不上"就是一次比较(#1210 review)。
 *
 * `liveTailTrusted`:自 `until` 建立以来实时推送链路没断过 —— 只有这时新到的 push 才能把 `until`
 * 往后推(订阅内的推送是顺序且完整的)。它由**权威页落库那一刻订阅是否已 ACK**决定:屏幕侧的
 * `openAndSubscribe` 与 `startFocusedTopicSubscription` 都是 `void subscribe(...)`,刻意不等 ACK
 * (订阅只管之后的推送,不该挡数据读),所以页比订阅先到是常态 —— 这个空窗里被控端写下的行既不会
 * 进这一页、也不会被推过来,之后一条 push 就会把 `until` 抬过它们,而等尾部涨过一页后最新页已不含
 * 那几行,事实自检也发现不了(#1210 review)。反过来重连补齐路径(`rehydrate`)是 `await subscribe`
 * 之后才拉页的,所以那条路径拿到的是可信尾部。
 * 断流(socket 掉线、退后台释放 session 订阅、离开会话取消订阅)一律清掉信任位与 ACK 记录:之后
 * 收到的 push 与 `until` 之间可能漏了任意多行,不能续算。区间本身保留 —— 断流不会让断流前已验证
 * 的那段失效。信任位只能由「ACK 之后落库的权威页」重新点亮(ACK 本身不行:ACK 之前的空窗里可能
 * 已经漏了行,只有新的权威页能重新确定尾部)。
 *
 * 建立 / 扩展点(都对应"服务端一次给出的连续段"或"订阅内的顺序推送"):整窗替换 `setMessages`、
 * 最新窗口 `setLatestMessageWindow`、「加载更早」`mergeEarlierMessages`、实时 push `appendMessage`。
 * 冷开 hydrate 与空洞补齐 `mergeMessages` 刻意不登记:前者来源不明;后者补的是窗口内部的洞,补完
 * 要算准新区间得先确认窗口里没有别的洞——而这正是补齐本身在解决的问题(保守不动的代价是补回来
 * 的段可能在下一次满页同步时被丢弃,下次打开会重新补,方向上是安全的那一侧)。
 * 清空 / rewind / 会话回收一律删除(重置为未知),下次最新窗口同步会重建。被控端提示漏推
 * (`resyncRequired`)只收缩到下界那一点(见 `narrowWindowCoverageToStart`):行没有被改写,只是
 * `until` 不再可信。最新页接不上时,同步方先沿 before 补读到上界再提交(`bridgeLatestMessagePage`),
 * 接上的旧段得以保留;补读不到才按未知处置。
 *
 * 事实自检:最新页若在 `[since, until]` 内带来窗口没有的行,说明旧结论已被服务端事实推翻(桌面侧
 * 改写历史、迟到落库等),当次按"未知"处置,见 `joinableWindowCoverage`。
 */
type SessionWindowCoverage = {
  /** 区间下界(含)。 */
  since: string;
  /** 区间上界(含)。 */
  until: string;
  /** 见上:实时推送链路自 `until` 建立以来未断过,`until` 可被新 push 续推。 */
  liveTailTrusted: boolean;
};
const sessionWindowCoverage = new Map<string, SessionWindowCoverage>();
/**
 * 远端已 ACK「该会话实时流」订阅(topic `session:<id>`)的会话集合。只用来决定新落库的权威页能否
 * 把尾部标成可信(见 `liveTailTrusted`);由 device-link 的订阅 ACK / 释放两侧记账。
 */
const sessionLiveStreamAcked = new Set<string>();

/** 取一批行里最旧的 createdAt(空列表 → undefined)。 */
function oldestCreatedAt(list: readonly RemoteMessage[]): string | undefined {
  let oldest: string | undefined;
  for (const item of list) {
    if (!item.createdAt) continue;
    if (oldest === undefined || item.createdAt.localeCompare(oldest) < 0) oldest = item.createdAt;
  }
  return oldest;
}

/** 取一批行里最新的 createdAt(空列表 → undefined)。 */
function newestCreatedAt(list: readonly RemoteMessage[]): string | undefined {
  let newest: string | undefined;
  for (const item of list) {
    if (!item.createdAt) continue;
    if (newest === undefined || item.createdAt.localeCompare(newest) > 0) newest = item.createdAt;
  }
  return newest;
}

function forgetWindowCoverage(sessionId: string): void {
  sessionWindowCoverage.delete(sessionId);
}

/**
 * 被控端提示漏推(`resyncRequired`):订阅内的推送不再完整,`until` 可能已被漏推之后的 push 越过空洞
 * 往后推,区间内部不能再信。但区间下界那一行确实来自权威页,只保留这一点 —— 下一次最新窗口同步
 * 必须补读到 `since`、用权威页重新覆盖整段后才能相接(见 `latestMessageWindowNeedsBridge`),
 * 补读不到时与整段遗忘相同。整段遗忘会让满页同步直接丢掉用户正在看的旧历史。
 */
function narrowWindowCoverageToStart(sessionId: string): void {
  const current = sessionWindowCoverage.get(sessionId);
  if (!current) return;
  sessionWindowCoverage.set(sessionId, { since: current.since, until: current.since, liveTailTrusted: false });
}

/**
 * 这一页落库时尾部是否可信:订阅已 ACK → 之后的行会被推过来,`until` 可由 push 续推;订阅还没
 * ACK(页比订阅先到,屏幕侧的常态)→ 空窗里被控端写下的行既不在这一页、也不会被推来,尾部不可信。
 */
function liveTailTrustedForPage(sessionId: string): boolean {
  return sessionLiveStreamAcked.has(sessionId);
}

/** 整窗替换:窗口就是这一页,区间即这一页 —— 不与旧结论求并(旧内容已经不在窗口里了)。 */
function coverReplacedWindow(sessionId: string, list: readonly RemoteMessage[]): void {
  const since = oldestCreatedAt(list);
  const until = newestCreatedAt(list);
  if (!since || !until) {
    forgetWindowCoverage(sessionId);
    return;
  }
  sessionWindowCoverage.set(sessionId, {
    since,
    until,
    liveTailTrusted: liveTailTrustedForPage(sessionId),
  });
}

/**
 * 最新页对账后登记:本页自身是连续段。`joined` 是本次**实际采纳**的旧结论(与本页首尾相接、
 * 因此其覆盖的旧段被保留),undefined 表示旧段没被采纳、区间收敛到本页。
 *
 * 保留判据与这里必须用同一个 `joined`:否则"保留了旧段却不声明覆盖它"(下次同步照丢)或"声明了
 * 覆盖却已经把它丢掉"(凭空背书出一个孤岛)两个方向都会让区间与窗口对不上。
 */
function coverLatestPage(
  sessionId: string,
  pageOldest: string,
  pageNewest: string,
  joined: SessionWindowCoverage | undefined,
): void {
  const since = joined && joined.since.localeCompare(pageOldest) < 0 ? joined.since : pageOldest;
  const until = joined && joined.until.localeCompare(pageNewest) > 0 ? joined.until : pageNewest;
  // 采纳的旧结论若已经是可信尾部(它的 until 就是本次上界),沿用它;否则由本页落库时的 ACK 状态决定。
  const inheritsTrustedTail = joined?.liveTailTrusted === true
    && joined.until.localeCompare(pageNewest) >= 0;
  sessionWindowCoverage.set(sessionId, {
    since,
    until,
    liveTailTrusted: inheritsTrustedTail || liveTailTrustedForPage(sessionId),
  });
}

/**
 * 「加载更早」:沿 `before` 从窗口最旧端连续取的一页,把下界前移。
 *
 * 还没有任何结论时(冷开 hydrate 的窗口上翻),这一页只能证明"从它到它接上的那一行"连续 ——
 * `joinsAt` 就是合并前窗口的最旧行;窗口更上面的部分来源仍然不明,上界不能顺手抬到窗口最新端。
 */
function coverEarlierPage(sessionId: string, pageOldest: string, joinsAt: string | undefined): void {
  const current = sessionWindowCoverage.get(sessionId);
  if (current) {
    // A page before an unverified cache island cannot bridge that island to a
    // newer verified window. Only extend coverage through an anchor inside it.
    if (!joinsAt || joinsAt.localeCompare(current.since) < 0
      || joinsAt.localeCompare(current.until) > 0) return;
    if (pageOldest.localeCompare(current.since) < 0) {
      sessionWindowCoverage.set(sessionId, { ...current, since: pageOldest });
    }
    return;
  }
  if (!joinsAt || pageOldest.localeCompare(joinsAt) > 0) return;
  sessionWindowCoverage.set(sessionId, { since: pageOldest, until: joinsAt, liveTailTrusted: false });
}

/** 订阅内到达的实时 push:顺序且完整,可把上界往后推。 */
function coverLiveRow(sessionId: string, message: RemoteMessage): void {
  const current = sessionWindowCoverage.get(sessionId);
  if (!current || !current.liveTailTrusted) return;
  // 本地系统卡(/learn、/context 等)没有服务端对应行:用它推上界等于凭空声明"服务端到这一刻的
  // 行都在窗口里"。
  if (messageKey(message).startsWith('mobile-system-')) return;
  const createdAt = message.createdAt;
  if (!createdAt || createdAt.localeCompare(current.until) <= 0) return;
  sessionWindowCoverage.set(sessionId, { ...current, until: createdAt });
}

/**
 * 实时推送链路中断:ACK 记录作废,上界也不再能被 push 续算(见 `liveTailTrusted`)。区间本身保留。
 * 省略 sessionId = 全部会话(socket 掉线影响所有订阅)。
 */
function noteLiveStreamInterrupted(sessionId?: string): void {
  if (sessionId !== undefined) {
    sessionLiveStreamAcked.delete(sessionId);
    const current = sessionWindowCoverage.get(sessionId);
    if (current?.liveTailTrusted) {
      sessionWindowCoverage.set(sessionId, { ...current, liveTailTrusted: false });
    }
    return;
  }
  sessionLiveStreamAcked.clear();
  for (const [key, current] of sessionWindowCoverage) {
    if (current.liveTailTrusted) {
      sessionWindowCoverage.set(key, { ...current, liveTailTrusted: false });
    }
  }
}

/**
 * 取本次可采纳的旧结论:必须与本页首尾相接(本页最旧行不晚于上界),且没有被本页的事实推翻
 * (本页在区间内带来了窗口里没有的行)。任一不成立 → undefined,按"未知"处置。
 */
function joinableWindowCoverage(
  sessionId: string,
  existingIndex: MessageIdentityIndex,
  latestWindow: readonly RemoteMessage[],
  pageOldest: string,
): SessionWindowCoverage | undefined {
  const coverage = sessionWindowCoverage.get(sessionId);
  if (!coverage) return undefined;
  if (pageOldest.localeCompare(coverage.until) > 0) return undefined;
  for (const item of latestWindow) {
    const createdAt = item.createdAt;
    if (!createdAt) continue;
    if (createdAt.localeCompare(coverage.since) < 0) continue;
    if (createdAt.localeCompare(coverage.until) > 0) continue;
    if (!messageIdentityIndexHas(existingIndex, item)) return undefined;
  }
  return coverage;
}
// Per-session live sub-agent task state, decoded from `agent_task_update` events (live-only,
// never persisted — see @cindy/maker-shared/agent-task). Keyed taskId/parentToolUseId → update.
const sessionTaskUpdates = new Map<string, ReadonlyMap<string, AgentTaskUpdate>>();
// `maker:event` reaches the control phone before the desktop's async DB write completes.
// Keep one temporary assistant row per session and reconcile it with the persisted row by
// clientId/persistId when the database push arrives.
const streamingAssistantClientIds = new Map<string, string>();
// Identities known to be separate from the current anonymous stream: rows present
// at its start, plus persisted rows kept separate from it. Retain until it resolves.
const generatedStreamPriorIdentities = new Map<string, Set<string>>();
// Existing provider item identity can link a legacy delta without persistId to
// its final. null means the anonymous batch did not establish one identity.
const generatedStreamAgentIdentities = new Map<string, {
  agentMessageId: string;
  source: string | null;
  deviceId: string | undefined;
} | null>();
// The same persisted streaming identity can be replayed by a stale transport after
// re-link. Track the transport currently assembling that identity so a device switch
// replaces the stale live text instead of concatenating two transports into one row.
const streamingAssistantDeviceIds = new Map<string, Map<string, string>>();
const pendingLiveAssistantClientIds = new Map<string, Set<string>>();
// 首个 live 行可能早于 getSession / listMessages 到达。此时只能暂用手机时间,待第一份
// 主机时间水位到达后重锚;否则快手机时钟会让短且无 persistId 的旧 live 行长期占据尾部。
// value 记录这条 provisional 回复首次关联到的 userSendAt;重连期间 desktop 若已推进到
// 下一轮,旧回复不能被新轮 user 行认领。null 表示 live 行早于任何 session 元数据到达,
// 首份 userSendAt 会在 recomputeSessions 中完成一次性绑定,之后不再随新轮次前移;若
// null 身份先经历软离线,则禁止用重连后的“首份”元数据绑定,因为它可能已经是下一轮。
type PendingHostAnchorIdentity = {
  bindOnMetadata: boolean;
  /** Transports that have produced this provisional identity. */
  deviceIds: ReadonlySet<string>;
  /**
   * Local maker-turn cohort used only while host session metadata is unavailable.
   * Distinct assistant rows emitted by one running turn share this id, so the first
   * authoritative user row can consume the whole reply block without claiming rows
   * from a later turn. Once sendAt is known it remains as the stronger pre-metadata
   * grouping key; identities created with host metadata use sendAt directly.
   */
  unboundRoundId: number | null;
  sendAt: string | null;
};
const pendingHostAnchorLiveAssistantClientIds = new Map<
  string,
  Map<string, PendingHostAnchorIdentity>
>();
const activePendingHostAnchorRoundIds = new Map<string, number>();
let nextPendingHostAnchorRoundId = 0;
let streamingFallbackSequence = 0;
const GENERATED_FALLBACK_MIN_PREFIX_LENGTH = 12;
const INITIAL_TEXT_DELTA_BATCH_INTERVAL_MS = 32;
const VISIBLE_DETAIL_TEXT_DELTA_BATCH_INTERVAL_MS = 64;
const BACKGROUND_TEXT_DELTA_BATCH_INTERVAL_MS = 96;
const DEVICE_LINK_TRUNCATED_FLAG = '__deviceLinkTruncated';
const pendingTextDeltaBatches = new Map<string, {
  /** Keep deltas as chunks; joining once per flush avoids O(n²) string copies. */
  chunks: string[];
  persistId?: string;
  deviceId?: string;
  agentMeta: Record<string, unknown> | null;
  agentMessageId: string | null;
  source: string | null;
}>();
let textDeltaFlushTimer: ReturnType<typeof setTimeout> | null = null;
let textDeltaFlushDeadlineAt: number | null = null;

function streamingAssistantDeviceId(
  sessionId: string,
  clientId: string,
): string | undefined {
  return streamingAssistantDeviceIds.get(sessionId)?.get(clientId);
}

function rememberStreamingAssistantDeviceId(
  sessionId: string,
  clientId: string,
  deviceId: string,
): void {
  const existing = streamingAssistantDeviceIds.get(sessionId) ?? new Map<string, string>();
  existing.set(clientId, deviceId);
  streamingAssistantDeviceIds.set(sessionId, existing);
}

function forgetStreamingAssistantDeviceId(sessionId: string, clientId: string): boolean {
  const existing = streamingAssistantDeviceIds.get(sessionId);
  if (!existing || !existing.delete(clientId)) return false;
  if (existing.size === 0) streamingAssistantDeviceIds.delete(sessionId);
  return true;
}

function clearStreamingAssistantPointer(sessionId: string): boolean {
  generatedStreamPriorIdentities.delete(sessionId);
  generatedStreamAgentIdentities.delete(sessionId);
  return streamingAssistantClientIds.delete(sessionId);
}

function clearStreamingAssistantState(sessionId: string): boolean {
  const clientIdChanged = clearStreamingAssistantPointer(sessionId);
  const deviceIdChanged = streamingAssistantDeviceIds.delete(sessionId);
  return clientIdChanged || deviceIdChanged;
}

// 目标模式状态镜像:null = 已确认无 goal(get-status 拉过 / push 清除);缺项 = 尚未拉取。
const sessionGoalStatus = new Map<string, MobileGoalStatusPayload | null>();
// maker `status` 事件驱动的权威 turn 边界(与 sessionRunning 分开):sessionRunning 还会被
// activity 推送 / 活跃快照置 true,重连或 activity 先到时会污染 false→true 的 turn-start 检测,
// 导致 stale taskUpdates 清理被跳过。孤儿 agent_task 卡的渲染 gate 与 turn-start 清理都只认
// 这份边界,构成闭环:孤儿只在 maker turn 运行中渲染,而 maker turn start 必然先清 stale。
const sessionMakerTurnRunning = new Map<string, boolean>();
const sessionDeviceIndex = new Map<string, string>();
// 已收到 error-persisted 脏信号且缓存消息仍在的会话集合。session 页面监听此 Set,
// 检测到自身 sessionId 被加入时调 load() 触发整窗刷新(含 error 行),避免先清空导致空白帧。
const pendingRefreshSessions = new Set<string>();
const reseedHandlers = new Map<string, Set<() => void>>();
// A whole-list read after app start or a reconnect reseed may follow a gap in live pushes.
// Listeners read changed tasks ahead; ordinary list refreshes while pushes flow do not fire.
const sessionListRefreshListeners = new Set<(deviceId: string, sessionId?: string) => void>();
const sessionRemovalListeners = new Set<(deviceId: string, sessionId: string) => void>();
const sessionListRefreshArmed = new Set<string>();
const sessionListRefreshSeen = new Set<string>();
const subs = new Set<() => void>();
const homeStatusSubs = new Set<() => void>();
const sessionMessagePreviewSubs = new Map<string, Set<() => void>>();
setRemoteSessionStoreSizeSource(() => {
  let total = 0;
  let max = 0;
  for (const list of messages.values()) {
    total += list.length;
    max = Math.max(max, list.length);
  }
  let previewSubscribers = 0;
  for (const listeners of sessionMessagePreviewSubs.values()) previewSubscribers += listeners.size;
  return {
    sessionCount: messages.size,
    messageCount: total,
    maxSessionMessageCount: max,
    subscriberCount: subs.size,
    homeStatusSubscriberCount: homeStatusSubs.size,
    previewSubscriberCount: previewSubscribers,
  };
});
const pendingMessagePreviewSessionIds = new Set<string>();
let homeStatusNotifyPending = false;
let notifyAllMessagePreviewsPending = false;
const emptyMessages: RemoteMessage[] = [];
const emptyPendingInteractions: PendingInteraction[] = [];
const EMPTY_TASK_UPDATES: ReadonlyMap<string, AgentTaskUpdate> = new Map();
const REGULAR_SESSION_GLOBAL_MESSAGE_BUDGET = 800;
const REGULAR_SESSION_GLOBAL_MESSAGE_BYTES_BUDGET = 64 * 1024 * 1024;
const MESSAGE_STRUCTURAL_BYTES_ESTIMATE = 512;
const MESSAGE_BYTES_ESTIMATE_LIMIT = REGULAR_SESSION_GLOBAL_MESSAGE_BYTES_BUDGET + 1;
const messageBytesEstimates = new WeakMap<RemoteMessage, number>();
type MessageListBudgetStats = {
  bytes: number;
  count: number;
  hasIntrinsicProtectedRows: boolean;
};
const messageListBudgetStatsCache = new WeakMap<
  readonly RemoteMessage[],
  MessageListBudgetStats
>();
const sessionLastAccessOrder = new Map<string, number>();
let nextSessionAccessOrder = 0;
/** 用户打开过详情的任务;定时任务进入此集合后按普通任务驻留。 */
const sessionsOpenedInDetail = new Set<string>();
const messageStructureTokens = new WeakMap<readonly RemoteMessage[], object>();
const messageStructureChangedIndexes = new WeakMap<
  readonly RemoteMessage[],
  ReadonlySet<number>
>();
const messageIdentityIndexes = new WeakMap<
  readonly RemoteMessage[],
  ReadonlyMap<string, number>
>();
const messagePreviewCache = new WeakMap<
  readonly RemoteMessage[],
  { preview: string | undefined; liveSession?: RemoteSession }
>();
const EMPTY_MESSAGE_STRUCTURE_TOKEN = Object.freeze({ kind: 'empty-message-structure' });
const emptySessionMessageStructureTokens = new Map<string, object>();
const EMPTY_MESSAGE_STRUCTURE_CHANGED_INDEXES: ReadonlySet<number> = new Set();
let homeStatusVersion = 0;

function messageStructureToken(list: readonly RemoteMessage[]): object {
  if (list.length === 0) return EMPTY_MESSAGE_STRUCTURE_TOKEN;
  return messageStructureTokens.get(list) ?? list;
}

function inheritMessageStructure(
  previous: readonly RemoteMessage[],
  next: readonly RemoteMessage[],
  changedIndex: number,
): void {
  messageStructureTokens.set(next, messageStructureToken(previous));
  const previousChangedIndexes = messageStructureChangedIndexes.get(previous)
    ?? EMPTY_MESSAGE_STRUCTURE_CHANGED_INDEXES;
  if (previousChangedIndexes.has(changedIndex)) {
    messageStructureChangedIndexes.set(next, previousChangedIndexes);
    return;
  }
  messageStructureChangedIndexes.set(next, new Set([
    ...previousChangedIndexes,
    changedIndex,
  ]));
}

function messageIdentityIndex(list: readonly RemoteMessage[]): ReadonlyMap<string, number> {
  const cached = messageIdentityIndexes.get(list);
  if (cached) return cached;
  const index = new Map<string, number>();
  for (let position = 0; position < list.length; position += 1) {
    const message = list[position];
    if (message.id && !index.has(message.id)) index.set(message.id, position);
    if (message.clientId && !index.has(message.clientId)) index.set(message.clientId, position);
  }
  messageIdentityIndexes.set(list, index);
  return index;
}

function inheritMessageIdentityIndex(
  previous: readonly RemoteMessage[],
  next: readonly RemoteMessage[],
  position: number,
): void {
  const cached = messageIdentityIndexes.get(previous);
  if (!cached) return;
  const before = previous[position];
  const after = next[position];
  if (before?.id !== after?.id || before?.clientId !== after?.clientId) return;
  messageIdentityIndexes.set(next, cached);
}

function isIntrinsicMessageWindowProtectedRow(message: RemoteMessage): boolean {
  return messageKey(message).startsWith('mobile-system-')
    || (message.role === 'user' && !message.id);
}

function messageListBudgetStats(list: readonly RemoteMessage[]): MessageListBudgetStats {
  const cached = messageListBudgetStatsCache.get(list);
  if (cached) return cached;
  let bytes = 0;
  let hasIntrinsicProtectedRows = false;
  for (const message of list) {
    bytes += estimateMessageBytes(message);
    hasIntrinsicProtectedRows ||= isIntrinsicMessageWindowProtectedRow(message);
  }
  const stats = { bytes, count: list.length, hasIntrinsicProtectedRows };
  messageListBudgetStatsCache.set(list, stats);
  return stats;
}

function inheritMessageListBudgetStats(
  previous: readonly RemoteMessage[],
  next: readonly RemoteMessage[],
  position: number,
): void {
  const cached = messageListBudgetStatsCache.get(previous);
  if (!cached) return;
  const before = previous[position];
  const after = next[position];
  if (!before || !after) return;
  const beforeIntrinsic = isIntrinsicMessageWindowProtectedRow(before);
  const afterIntrinsic = isIntrinsicMessageWindowProtectedRow(after);
  // Removing the only intrinsic protected row requires a fresh list scan to prove none remain.
  if (beforeIntrinsic && !afterIntrinsic) return;
  messageListBudgetStatsCache.set(next, {
    bytes: cached.bytes - estimateMessageBytes(before) + estimateMessageBytes(after),
    count: cached.count,
    hasIntrinsicProtectedRows: cached.hasIntrinsicProtectedRows || afterIntrinsic,
  });
}

function bumpHomeStatusVersion(): void {
  homeStatusVersion += 1;
  homeStatusNotifyPending = true;
}

function setPendingInteractionState(sessionId: string, next: PendingInteraction[]): void {
  pendingInteractions.set(sessionId, next);
  bumpHomeStatusVersion();
}

function deletePendingInteractionState(sessionId: string): boolean {
  const changed = pendingInteractions.delete(sessionId);
  if (changed) bumpHomeStatusVersion();
  return changed;
}

function deleteSessionLiveActivity(sessionId: string): boolean {
  const changed = sessionLiveActivity.delete(sessionId);
  if (changed) bumpHomeStatusVersion();
  return changed;
}

function sessionById(sessionId: string): RemoteSession | undefined {
  return mergedSessionById.get(sessionId);
}

function retentionForSession(sessionId: string): SessionRetentionKind {
  return classifySessionRetention(sessionById(sessionId), sessionsOpenedInDetail.has(sessionId));
}

function touchSessionAccess(sessionId: string): void {
  sessionLastAccessOrder.set(sessionId, ++nextSessionAccessOrder);
}

/**
 * Budget accounting runs on every regular-session sweep.  Do not serialize the
 * whole payload here: streaming rows replace their object on every flush, so a
 * stringify would allocate a second copy of every large tool result and make
 * the accounting pass itself a noticeable GC source.  This intentionally
 * conservative walk counts primitive payloads and container overhead without
 * materializing a large temporary string.
 */
function estimateValueBytes(value: unknown, maxBytes = MESSAGE_BYTES_ESTIMATE_LIMIT): number {
  type ContainerFrame =
    | { kind: 'array'; value: readonly unknown[]; nextIndex: number }
    | { kind: 'object'; value: Record<string, unknown>; keys: string[]; nextIndex: number };

  if (maxBytes <= 0) return 0;
  const seen = new Set<object>();
  const frames: ContainerFrame[] = [];
  let bytes = 0;
  let current: unknown = value;

  // Walk one child at a time instead of recursively visiting or pushing an
  // entire container. Deep payloads cannot overflow the JS stack, and large
  // arrays do not create a second array-sized work queue just for accounting.
  while (true) {
    if (current == null) {
      // null/undefined carry no payload bytes beyond their container slot.
    } else if (typeof current === 'string') {
      bytes += current.length * 2;
    } else if (typeof current === 'number' || typeof current === 'boolean') {
      bytes += 16;
    } else if (typeof current !== 'object') {
      bytes += 8;
    } else if (!seen.has(current)) {
      seen.add(current);
      if (Array.isArray(current)) {
        bytes += 24;
        if (current.length > 0) {
          bytes += 8;
          frames.push({ kind: 'array', value: current, nextIndex: 1 });
          current = current[0];
          if (bytes >= maxBytes) return maxBytes;
          continue;
        }
      } else {
        const objectValue = current as Record<string, unknown>;
        const keys = Object.keys(objectValue);
        bytes += 32;
        if (keys.length > 0) {
          const key = keys[0]!;
          bytes += 16 + key.length * 2;
          frames.push({ kind: 'object', value: objectValue, keys, nextIndex: 1 });
          current = objectValue[key];
          if (bytes >= maxBytes) return maxBytes;
          continue;
        }
      }
    }

    if (bytes >= maxBytes) return maxBytes;
    let advanced = false;
    while (frames.length > 0) {
      const frame = frames[frames.length - 1]!;
      if (frame.kind === 'array' && frame.nextIndex < frame.value.length) {
        current = frame.value[frame.nextIndex];
        frame.nextIndex += 1;
        bytes += 8;
        advanced = true;
        break;
      }
      if (frame.kind === 'object' && frame.nextIndex < frame.keys.length) {
        const key = frame.keys[frame.nextIndex]!;
        frame.nextIndex += 1;
        current = frame.value[key];
        bytes += 16 + key.length * 2;
        advanced = true;
        break;
      }
      frames.pop();
    }
    if (!advanced) return bytes;
  }
}

function estimateMessageBytes(message: RemoteMessage): number {
  const cached = messageBytesEstimates.get(message);
  if (cached !== undefined) return cached;
  let bytes = MESSAGE_STRUCTURAL_BYTES_ESTIMATE;
  const addValue = (value: unknown): void => {
    if (value == null || bytes >= MESSAGE_BYTES_ESTIMATE_LIMIT) return;
    bytes += estimateValueBytes(value, MESSAGE_BYTES_ESTIMATE_LIMIT - bytes);
  };
  addValue(message.content);
  addValue(message.agentMeta);
  addValue(message.systemCardData);
  messageBytesEstimates.set(message, bytes);
  return bytes;
}

function isMessageWindowProtectedRow(sessionId: string, message: RemoteMessage): boolean {
  if (messageKey(message).startsWith('mobile-system-')) return true;
  if (isPendingLiveAssistantMessage(sessionId, message)) return true;
  return message.role === 'user' && !message.id;
}

/**
 * 软窗口:不可重取的本地/在途行全部保留,剩余额度给最新服务端行。保护行较多时
 * 允许略超上限,数据安全优先于精确条数。
 */
function trimMessageWindow(
  sessionId: string,
  list: readonly RemoteMessage[],
  limit = MESSAGE_PAGE_SIZE,
): RemoteMessage[] {
  if (list.length <= limit) return [...list];
  const protectedRows: RemoteMessage[] = [];
  const evictableRows: RemoteMessage[] = [];
  for (const row of list) {
    if (isMessageWindowProtectedRow(sessionId, row)) protectedRows.push(row);
    else evictableRows.push(row);
  }
  const keepEvictable = Math.max(0, limit - protectedRows.length);
  return normalizeMessages([
    ...protectedRows,
    ...evictableRows.slice(Math.max(0, evictableRows.length - keepEvictable)),
  ]);
}

function hasComposerDraft(sessionId: string): boolean {
  if ((readComposerDraftSync(sessionId) ?? '').trim().length > 0) return true;
  const document = readComposerDocumentDraftSync(sessionId);
  if (document && composerDocumentHasContent(document)) return true;
  return getQuotes(sessionId).length > 0;
}

function sessionStoreProtected(sessionId: string, includeVisible = true): boolean {
  if (includeVisible && sessionMessageLifecycle.isVisible(sessionId)) return true;
  if (readSessionRunStatus(sessionId).isRunning) return true;
  if (sessionMakerTurnRunning.get(sessionId) === true) return true;
  if ((pendingInteractions.get(sessionId)?.length ?? 0) > 0) return true;
  if (protectedQuestions.has(sessionId)) return true;
  if ((inputProjections.get(sessionId)?.pendingQueue.length ?? 0) > 0) return true;
  if (sessionMessageLifecycle.hasLocalWork(sessionId)) return true;
  if (retentionForSession(sessionId) === 'regular' && hasComposerDraft(sessionId)) return true;
  return false;
}

function messageWriteAllowed(
  sessionId: string,
  authority?: SessionMessageAuthority,
): boolean {
  if (authority && (
    authority.sessionId !== sessionId
    || !sessionMessageLifecycle.canCommit(authority)
  )) return false;
  if (
    sessionMessageLifecycle.isVisible(sessionId)
    || sessionMessageLifecycle.hasLocalWork(sessionId)
  ) return true;
  // schedule 从未打开时也不能被全局 push 灌入正文;regular 在详情离场后同样
  // 拒绝旧订阅/流式 flush,未曾打开的普通任务仍保留既有全局镜像行为。
  if (retentionForSession(sessionId) === 'schedule') return false;
  return !sessionMessageLifecycle.hasEntered(sessionId);
}

function listMessageWriteAllowed(sessionId: string, deviceId?: string): boolean {
  const session = mergedSessionById.get(sessionId);
  return !!session && session.deviceLinkDeviceId === deviceId && session.status === 'active'
    && retentionForSession(sessionId) === 'regular';
}

/** Match live state to the same selected host as the merged task row. */
function sessionStateWriteAllowed(sessionId: string, deviceId?: string): boolean {
  const indexedDeviceId = sessionDeviceIndex.get(sessionId);
  return !deviceId || !indexedDeviceId || indexedDeviceId === deviceId
    || mergedSessionById.get(sessionId)?.canonicalDeviceId === deviceId;
}

function sessionStateReadAllowed(sessionId: string, deviceId: string | undefined, sources: Map<string, string>): boolean {
  if (!deviceId) return true;
  if (!sessionStateWriteAllowed(sessionId, deviceId)) return false;
  const source = sources.get(sessionId);
  return !source || source === deviceId || (sessionDeviceIndex.has(sessionId) && sessionStateWriteAllowed(sessionId, source));
}

function clearSourcedSessionState(sessionId: string, sources: Map<string, string>): void {
  sources.delete(sessionId);
  if (sources === sessionInteractionSources) {
    deletePendingInteractionState(sessionId);
    pendingInteractionsAuthoritative.delete(sessionId);
  } else {
    deleteSessionLiveActivity(sessionId);
    writeSessionRunStatus(sessionId, EMPTY_SESSION_RUN_STATUS);
    writeMakerTurnRunning(sessionId, false);
    sessionMakerActivityEpochs.delete(sessionId);
  }
}

function acceptSessionStateSource(
  sessionId: string,
  deviceId: string | undefined,
  sources: Map<string, string>,
): boolean {
  if (!sessionStateWriteAllowed(sessionId, deviceId)) return false;
  if (!deviceId) return true; // Local optimistic updates retain their remote provenance.
  const previous = sources.get(sessionId);
  if (previous && previous !== deviceId && !(sessionDeviceIndex.has(sessionId)
    && sessionStateWriteAllowed(sessionId, previous))) {
    clearSourcedSessionState(sessionId, sources);
    emit();
  }
  sources.set(sessionId, deviceId);
  return true;
}

function normalizeWindowForRetention(
  sessionId: string,
  list: readonly RemoteMessage[],
): RemoteMessage[] {
  return retentionForSession(sessionId) === 'schedule'
    ? trimMessageWindow(sessionId, list)
    : [...list];
}

function clearSessionMessageCache(sessionId: string, deviceId?: string): void {
  const resolvedDeviceId = deviceId ?? sessionDeviceIndex.get(sessionId);
  if (!resolvedDeviceId) return;
  void replaceCachedSessionMessages(resolvedDeviceId, sessionId, []).catch(() => undefined);
}

/** Track list-only rows within the current window; budget/retention trims drop their keys. */
function retainListMessageKeys(sessionId: string, added: string): void {
  const present = new Set((messages.get(sessionId) ?? []).map(messageKey));
  const keys = new Set([...(listMessageKeys.get(sessionId) ?? []), added].filter((key) => present.has(key)));
  if (keys.size > 0) listMessageKeys.set(sessionId, keys);
  else listMessageKeys.delete(sessionId);
}

function invalidateSessionMessageWindowState(
  sessionId: string,
  requestRefresh: boolean,
): boolean {
  let changed = messages.delete(sessionId);
  listMessageKeys.delete(sessionId);
  changed = livePlanSnapshots.delete(sessionId) || changed;
  changed = sessionTaskUpdates.delete(sessionId) || changed;
  changed = sessionParkedTaskUpdates.delete(sessionId) || changed;
  changed = sessionMessageSyncMarkers.delete(sessionId) || changed;
  changed = clearStreamingAssistantState(sessionId) || changed;
  changed = pendingLiveAssistantClientIds.delete(sessionId) || changed;
  changed = pendingHostAnchorLiveAssistantClientIds.delete(sessionId) || changed;
  changed = activePendingHostAnchorRoundIds.delete(sessionId) || changed;
  if (pendingTextDeltaBatches.has(sessionId)) {
    discardPendingTextDelta(sessionId);
    changed = true;
  }
  if (sessionWindowCoverage.has(sessionId)) changed = true;
  forgetWindowCoverage(sessionId);
  changed = sessionLiveStreamAcked.delete(sessionId) || changed;
  sessionLastAccessOrder.delete(sessionId);
  if (requestRefresh && !pendingRefreshSessions.has(sessionId)) {
    pendingRefreshSessions.add(sessionId);
    changed = true;
  } else if (!requestRefresh) {
    changed = pendingRefreshSessions.delete(sessionId) || changed;
  }
  return changed;
}

function removeSessionRuntimeState(sessionId: string): void {
  sessionRuntimeSources.delete(sessionId);
  sessionInteractionSources.delete(sessionId);
  protectedQuestions.delete(sessionId);
  visibleInteractionCache.delete(sessionId);
  void clearHistoryDisk(undefined, sessionId);
  clearRemoteHistoryViews(undefined, sessionId);
  invalidateSessionMessageWindowState(sessionId, false);
  emptySessionMessageStructureTokens.delete(sessionId);
  deletePendingInteractionState(sessionId);
  pendingInteractionsAuthoritative.delete(sessionId);
  inputProjections.delete(sessionId);
  inputProjectionRemoteEpochs.delete(sessionId);
  inputProjectionRemoteQueuedEvidence.delete(sessionId);
  bumpInputProjectionAuthorityEpoch(sessionId);
  deleteSessionLiveActivity(sessionId);
  if (sessionRunning.delete(sessionId)) bumpHomeStatusVersion();
  sessionRunStatus.delete(sessionId);
  sessionMakerActivityEpochs.delete(sessionId);
  sessionMakerTurnRunning.delete(sessionId);
  sessionMessageLifecycle.forget(sessionId);
  sessionsOpenedInDetail.delete(sessionId);
  sessionDeviceIndex.delete(sessionId);
  dropPendingTitlePreview(sessionId);
  // revision 下限按会话回收:它不参与单轮快照回收(那会把覆盖权还给晚到的
  // 旧快照),所以只能在会话本身消失时清,保持有界。
  const sessionPrefix = interactionResolveKey(sessionId, '');
  for (const key of interactionRevisionFloors.keys()) {
    if (key.startsWith(sessionPrefix)) interactionRevisionFloors.delete(key);
  }
}

function discardTransportOwnedPendingSessionState(
  sessionId: string,
  deviceId: string,
): boolean {
  let changed = false;
  const batch = pendingTextDeltaBatches.get(sessionId);
  if (batch?.deviceId === deviceId) {
    discardPendingTextDelta(sessionId);
    changed = true;
  }
  const pendingAnchors = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  const pendingAnchorIds = new Set<string>();
  if (pendingAnchors) {
    for (const [id, identity] of pendingAnchors) {
      if (!identity.deviceIds.has(deviceId)) continue;
      if (identity.deviceIds.size > 1) {
        pendingAnchors.set(id, {
          ...identity,
          deviceIds: new Set([...identity.deviceIds].filter((candidate) => candidate !== deviceId)),
        });
        changed = true;
      } else {
        pendingAnchorIds.add(id);
      }
    }
  }
  const streamingDeviceIds = streamingAssistantDeviceIds.get(sessionId);
  if (streamingDeviceIds) {
    for (const [id, ownerDeviceId] of streamingDeviceIds) {
      if (ownerDeviceId === deviceId) pendingAnchorIds.add(id);
    }
  }
  if (pendingAnchorIds.size === 0) return changed;
  const existingMessages = messages.get(sessionId);
  if (existingMessages && pendingAnchorIds.size > 0) {
    const nextMessages = existingMessages.filter((message) => (
      !pendingAnchorIds.has(message.id) && !pendingAnchorIds.has(message.clientId)
    ));
    if (nextMessages.length !== existingMessages.length) {
      if (nextMessages.length > 0) messages.set(sessionId, nextMessages);
      else {
        messages.delete(sessionId);
        listMessageKeys.delete(sessionId);
      }
      changed = true;
    }
  }
  const pendingLiveIds = pendingLiveAssistantClientIds.get(sessionId);
  if (pendingLiveIds) {
    for (const id of pendingAnchorIds) pendingLiveIds.delete(id);
    if (pendingLiveIds.size === 0) pendingLiveAssistantClientIds.delete(sessionId);
  }
  const streamingClientId = streamingAssistantClientIds.get(sessionId);
  if (streamingClientId && pendingAnchorIds.has(streamingClientId)) {
    clearStreamingAssistantPointer(sessionId);
  }
  for (const id of pendingAnchorIds) forgetStreamingAssistantDeviceId(sessionId, id);
  if (pendingAnchors) {
    for (const id of pendingAnchorIds) pendingAnchors.delete(id);
    if (pendingAnchors.size === 0) {
      pendingHostAnchorLiveAssistantClientIds.delete(sessionId);
      activePendingHostAnchorRoundIds.delete(sessionId);
    } else {
      const activeRoundId = activePendingHostAnchorRoundIds.get(sessionId);
      if (
        activeRoundId !== undefined
        && ![...pendingAnchors.values()].some((identity) => (
          identity.unboundRoundId === activeRoundId
        ))
      ) {
        activePendingHostAnchorRoundIds.delete(sessionId);
      }
    }
  }
  return true;
}

function hasTransportOwnedSessionStateFromOtherDevice(
  sessionId: string,
  deviceId: string,
): boolean {
  const batchDeviceId = pendingTextDeltaBatches.get(sessionId)?.deviceId;
  if (batchDeviceId !== undefined && batchDeviceId !== deviceId) return true;
  const pendingAnchors = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  if (pendingAnchors && [...pendingAnchors.values()].some((identity) => (
    [...identity.deviceIds].some((ownerDeviceId) => ownerDeviceId !== deviceId)
  ))) return true;
  const streamingDeviceIds = streamingAssistantDeviceIds.get(sessionId);
  return streamingDeviceIds
    ? [...streamingDeviceIds.values()].some((ownerDeviceId) => ownerDeviceId !== deviceId)
    : false;
}

function releaseSessionDetailProjections(sessionId: string): boolean {
  let changed = livePlanSnapshots.delete(sessionId);
  changed = sessionTaskUpdates.delete(sessionId) || changed;
  changed = sessionParkedTaskUpdates.delete(sessionId) || changed;
  // Goal status is queried when the context sheet opens; retaining a full
  // status payload for every backgrounded task only keeps detail-only data
  // alive and can show stale state after a long absence.
  changed = sessionGoalStatus.delete(sessionId) || changed;
  changed = inputProjections.delete(sessionId) || changed;
  // 即使投影已经为空也要抬升 authority:离场/LRU 前启动的慢查询不能在下一次
  // 打开同一任务后把旧 pending queue 或 continuation owner 写回来。
  bumpInputProjectionAuthorityEpoch(sessionId);
  return changed;
}

function reclaimScheduleRuntimeMaps(sessionId: string): boolean {
  clearRemoteHistoryViews(undefined, sessionId);
  let changed = invalidateSessionMessageWindowState(sessionId, false);
  changed = releaseSessionDetailProjections(sessionId) || changed;
  return changed;
}

function enforceRegularMessageBudget(): boolean {
  let totalCount = 0;
  let totalBytes = 0;
  const candidates: Array<{
    sessionId: string;
    accessOrder: number;
    count: number;
    bytes: number;
    hasProtectedRows: boolean;
  }> = [];
  for (const [sessionId, list] of messages) {
    if (retentionForSession(sessionId) !== 'regular') continue;
    const stats = messageListBudgetStats(list);
    totalCount += stats.count;
    totalBytes += stats.bytes;
    if (!sessionStoreProtected(sessionId)) {
      candidates.push({
        sessionId,
        accessOrder: sessionLastAccessOrder.get(sessionId) ?? 0,
        count: stats.count,
        bytes: stats.bytes,
        hasProtectedRows: stats.hasIntrinsicProtectedRows
          || (pendingLiveAssistantClientIds.get(sessionId)?.size ?? 0) > 0,
      });
    }
  }
  if (
    totalCount <= REGULAR_SESSION_GLOBAL_MESSAGE_BUDGET
    && totalBytes <= REGULAR_SESSION_GLOBAL_MESSAGE_BYTES_BUDGET
  ) return false;
  candidates.sort((left, right) => left.accessOrder - right.accessOrder);
  let changed = false;
  for (const candidate of candidates) {
    if (
      totalCount <= REGULAR_SESSION_GLOBAL_MESSAGE_BUDGET
      && totalBytes <= REGULAR_SESSION_GLOBAL_MESSAGE_BYTES_BUDGET
    ) break;
    // LRU 是整窗淘汰;只要含无服务端副本/尚未落库的保护行,就跳过整个会话。
    // 标志来自消息数组缓存与 pending identity,不再为每次流式文本重复扫描整窗。
    if (candidate.hasProtectedRows) continue;
    if (!messages.delete(candidate.sessionId)) continue;
    listMessageKeys.delete(candidate.sessionId);
    clearRemoteHistoryViews(undefined, candidate.sessionId);
    pendingMessagePreviewSessionIds.add(candidate.sessionId);
    forgetWindowCoverage(candidate.sessionId);
    sessionLiveStreamAcked.delete(candidate.sessionId);
    releaseSessionDetailProjections(candidate.sessionId);
    totalCount -= candidate.count;
    totalBytes -= candidate.bytes;
    changed = true;
    // 这里只淘汰内存,不删除磁盘缓存。重开仍可乐观 hydrate 最新窗口。
  }
  return changed;
}

/**
 * A regular task nobody is looking at still receives list pushes while it runs,
 * and running tasks are exempt from the global LRU budget. Without a per-task
 * cap that window grows for as long as the app stays alive, and every push
 * copies and re-sorts all of it. Keep only the latest page; reopening the task
 * re-syncs from the host like any other trimmed window.
 */
function hiddenRegularWindowOverCap(sessionId: string, list: readonly RemoteMessage[]): boolean {
  return list.length > MESSAGE_PAGE_SIZE
    && retentionForSession(sessionId) === 'regular'
    && !sessionMessageLifecycle.isVisible(sessionId)
    && !sessionMessageLifecycle.hasLocalWork(sessionId);
}

function applyMessageWriteRetention(sessionId: string): void {
  touchSessionAccess(sessionId);
  const current = messages.get(sessionId);
  if (current && (
    retentionForSession(sessionId) === 'schedule'
    || hiddenRegularWindowOverCap(sessionId, current)
  )) {
    const trimmed = trimMessageWindow(sessionId, current);
    if (!remoteMessageListsEqual(current, trimmed)) {
      forgetWindowCoverage(sessionId);
      messages.set(sessionId, trimmed);
    }
  }
  enforceRegularMessageBudget();
}

let mergedSessions: RemoteSession[] = [];
/** Raw mirrors stay available to transport/reconciliation; UI hooks consume this filtered view. */
let visibleSessions: RemoteSession[] = [];
// Retention and live-row anchoring run for every message write. Looking up each
// cached window in the full list makes bulk hydration approach cubic work.
const mergedSessionById = new Map<string, RemoteSession>();
// List-only projection. Detail consumers keep reading mergedSessions, including
// live usage. Usage pushes must not rebuild Home's grouping/localization tree.
let homeSessions: RemoteSession[] = [];
const SESSION_USAGE_FIELDS = new Set(['totalMoney', 'totalCostUsd', 'totalTokenUsage']);
// These fields cannot change shard ownership, visibility or retention. Timestamps
// still update this task's live-row anchor; titles still reconcile local previews.
const SESSION_METADATA_FIELDS = new Set([...SESSION_USAGE_FIELDS, 'title', 'updatedAt', 'userSendAt']);
const homeSessionProjectionCache = new Map<string, {
  source: RemoteSession;
  projected: RemoteSession;
}>();

function reconcileHomeSessions(): void {
  const activeSessionIds = new Set<string>();
  const next = visibleSessions.map((session) => {
    activeSessionIds.add(session.id);
    const cached = homeSessionProjectionCache.get(session.id);
    if (cached?.source === session) return cached.projected;

    const projected = { ...session };
    delete projected.totalMoney;
    delete projected.totalCostUsd;
    delete projected.totalTokenUsage;
    const stableProjected = cached && remoteSessionEqual(cached.projected, projected)
      ? cached.projected
      : projected;
    homeSessionProjectionCache.set(session.id, { source: session, projected: stableProjected });
    return stableProjected;
  });
  for (const sessionId of homeSessionProjectionCache.keys()) {
    if (!activeSessionIds.has(sessionId)) homeSessionProjectionCache.delete(sessionId);
  }
  if (sameElementRefs(homeSessions, next)) return;
  homeSessions = next;
  bumpHomeStatusVersion();
}
let messageVersion = 0;
let storeVersion = 0;
// A single remote snapshot often updates both the session shard and its
// activity projection. Keep the writes synchronous, but notify subscribers
// once after the snapshot is complete so the home screen does not render the
// same device twice in one turn.
let emitBatchDepth = 0;
let emitBatchPending = false;

type LiveRowCreatedAtAnchor = {
  createdAt: string | undefined;
  /** 会话列表快照可能早于本次发送,只能临时钳制;消息水位才可完成重锚。 */
  provisional: boolean;
};

function liveRowCreatedAtAnchor(sessionId: string): LiveRowCreatedAtAnchor {
  const pendingHostAnchorIds = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  const session = sessionById(sessionId);
  const authoritativeMessages = (messages.get(sessionId) ?? []).filter((message) => {
    const isPendingHostAnchor = pendingHostAnchorIds?.has(message.id) === true
      || pendingHostAnchorIds?.has(message.clientId) === true;
    const isLocalSystemCard = message.systemCardType !== undefined
      && (message.id.startsWith('mobile-system-') || message.clientId.startsWith('mobile-system-'));
    return !isPendingHostAnchor && !isLocalSystemCard;
  });
  const messageWatermark = newestCreatedAt(authoritativeMessages);
  if (messageWatermark) {
    const latestAuthoritativeMessage = authoritativeMessages[authoritativeMessages.length - 1];
    const newerUserSendAt = session?.userSendAt
      && session.userSendAt.localeCompare(messageWatermark) > 0
      ? session.userSendAt
      : undefined;
    return {
      createdAt: newerUserSendAt ?? messageWatermark,
      // user 尾行只有在没有更晚的 session.userSendAt 时才可认作本轮问题;否则它
      // 属于旧轮次,当前 user push 仍在途。assistant / tool 尾行同样只能提供临时时间锚。
      provisional: newerUserSendAt !== undefined || latestAuthoritativeMessage?.role !== 'user',
    };
  }
  return {
    createdAt: session?.userSendAt ?? session?.updatedAt ?? session?.createdAt,
    provisional: true,
  };
}

function latestUserSendAt(sessionId: string): string | undefined {
  return sessionById(sessionId)?.userSendAt ?? undefined;
}

function authoritativeSessionDeviceId(sessionId: string): string | undefined {
  if (!deviceList) return undefined;
  const session = sessionById(sessionId);
  const canonicalDeviceId = session?.canonicalDeviceId;
  if (canonicalDeviceId && deviceList.some((device) => device.deviceId === canonicalDeviceId)) {
    return canonicalDeviceId;
  }
  const indexedDeviceId = sessionDeviceIndex.get(sessionId);
  return indexedDeviceId && deviceList.some((device) => device.deviceId === indexedDeviceId)
    ? indexedDeviceId
    : undefined;
}

function userMessageMatchesLatestSend(sessionId: string, message: RemoteMessage): boolean {
  if (message.role !== 'user') return false;
  const userSendAt = latestUserSendAt(sessionId);
  return Boolean(userSendAt && message.createdAt.localeCompare(userSendAt) >= 0);
}

function userMessageCanConsumePendingLiveReply(
  sessionId: string,
  message: RemoteMessage,
): boolean {
  if (message.role !== 'user') return false;
  const userSendAt = latestUserSendAt(sessionId);
  // Before session metadata arrives, preserve the existing realtime ordering semantics.
  // Once a send marker exists, an older delayed push normally belongs to a previous round.
  // The exception is an unbound reply frozen by an offline transition: only an older user
  // row can identify that reply's original round after reconnect metadata has moved ahead.
  return !userSendAt
    || message.createdAt.localeCompare(userSendAt) >= 0
    || hasOfflineUnboundPendingHostAnchor(sessionId);
}

// 当前权威设备列表(由首页从设备列表 API reconcile 后注入)。每次重算会话时基于它 + 当前 shards(stale 侧)
// 重建身份索引,用于给会话算展示用 canonicalDeviceId(把 re-link 后残留 stale shard 认领回当前设备);
// 为 null 时不归一,安全退化。
const EMPTY_DEVICE_IDENTITY: readonly { deviceId: string; name: string }[] = [];
let deviceList: readonly { deviceId: string; name: string }[] | null = null;
let conversationSearchDeviceModels: readonly {
  canOpen: boolean;
  deviceId: string;
  name: string | null;
  state: string;
}[] = [];

function emitNow(): void {
  const notifyHomeStatus = homeStatusNotifyPending;
  const notifyAllMessagePreviews = notifyAllMessagePreviewsPending;
  const changedPreviewSessionIds = [...pendingMessagePreviewSessionIds];
  homeStatusNotifyPending = false;
  notifyAllMessagePreviewsPending = false;
  pendingMessagePreviewSessionIds.clear();
  storeVersion += 1;
  for (const sub of subs) sub();
  if (notifyHomeStatus) {
    for (const sub of homeStatusSubs) sub();
  }
  const previewCallbacks = new Set<() => void>();
  if (notifyAllMessagePreviews) {
    for (const sessionSubs of sessionMessagePreviewSubs.values()) {
      for (const sub of sessionSubs) previewCallbacks.add(sub);
    }
  } else {
    for (const sessionId of changedPreviewSessionIds) {
      for (const sub of sessionMessagePreviewSubs.get(sessionId) ?? []) {
        previewCallbacks.add(sub);
      }
    }
  }
  for (const sub of previewCallbacks) sub();
}

function emit(): void {
  if (emitBatchDepth > 0) {
    emitBatchPending = true;
    return;
  }
  emitNow();
}

function batch<T>(work: () => T): T {
  emitBatchDepth += 1;
  try {
    return work();
  } finally {
    emitBatchDepth -= 1;
    if (emitBatchDepth === 0 && emitBatchPending) {
      emitBatchPending = false;
      emitNow();
    }
  }
}

function bumpInputProjectionAuthorityEpoch(sessionId: string): number {
  const epoch = ++nextInputProjectionAuthorityEpoch;
  inputProjectionAuthorityEpochs.set(sessionId, epoch);
  return epoch;
}

function recordInputProjectionRemoteEvidence(sessionId: string, clientIds: Iterable<string>, settled = false): void {
  const epoch = ++nextInputProjectionRemoteEpoch;
  inputProjectionRemoteEpochs.set(sessionId, epoch);
  let evidence = inputProjectionRemoteQueuedEvidence.get(sessionId);
  for (const clientId of clientIds) {
    inputProjectionRemoteQueuedEvidence.set(sessionId, evidence ??= new Map<string, number>());
    evidence.delete(clientId);
    evidence.set(clientId, settled ? -epoch : epoch);
  }
  while (evidence && evidence.size > INPUT_PROJECTION_REMOTE_EVIDENCE_LIMIT) evidence.delete(evidence.keys().next().value!);
}

function settleInputProjectionClientIds(
  sessionId: string,
  settledClientIds: ReadonlySet<string>,
): boolean {
  if (settledClientIds.size === 0) return false;
  recordInputProjectionRemoteEvidence(sessionId, settledClientIds, true);
  const current = inputProjections.get(sessionId);
  const pendingQueue = current?.pendingQueue.filter(
    (item) => !settledClientIds.has(item.clientId),
  );
  const projectionChanged = Boolean(current && pendingQueue?.length !== current.pendingQueue.length);
  if (!projectionChanged || !current || !pendingQueue) return false;
  inputProjections.set(sessionId, { ...current, pendingQueue });
  bumpInputProjectionAuthorityEpoch(sessionId);
  return true;
}

function settleInputProjectionFromMessages(
  sessionId: string, list: readonly RemoteMessage[],
): boolean {
  const tracked = new Set(inputProjections.get(sessionId)?.pendingQueue.map((item) => item.clientId) ?? []);
  for (const [clientId, epoch] of inputProjectionRemoteQueuedEvidence.get(sessionId) ?? []) if (epoch > 0) tracked.add(clientId);
  if (tracked.size === 0) return false;
  const settled = new Set(list
    .filter((message) => message.role === 'user' && tracked.has(message.clientId))
    .map((message) => message.clientId));
  return settleInputProjectionClientIds(sessionId, settled);
}

function invalidateInputProjectionForOffline(sessionId: string): boolean {
  recordInputProjectionRemoteEvidence(sessionId, []);
  return inputProjections.delete(sessionId);
}

function commitInputProjection(sessionId: string, next: InputProjection): boolean {
  if (deepValueEqual(inputProjections.get(sessionId) ?? EMPTY_INPUT_PROJECTION, next)) {
    if (next.pendingQueue.length === 0) sessionMessageLifecycle.retryPendingReclaim(sessionId);
    return false;
  }
  inputProjections.set(sessionId, next);
  if (next.pendingQueue.length === 0) sessionMessageLifecycle.retryPendingReclaim(sessionId);
  emit();
  return true;
}

function recomputeSessions(): void {
  const previousRetention = new Map(
    mergedSessions.map((session) => [session.id, retentionForSession(session.id)] as const),
  );
  sessionDeviceIndex.clear();
  // 跨 shard 去重 + 设备身份归一化。re-link 后同一 session.id 可能同时存在于 stale / current 两个 shard;
  // 保留「物理 deviceId 是当前已知设备」的那条(current shard 优先,它路由正确且是真身),都不是已知设备
  // 时保留先遇到的。canonicalDeviceId 写展示用规范 id(认领回当前设备),deviceLinkDeviceId 保物理不动。
  // sessionDeviceIndex 记保留条的物理 shard —— applySessionPatch / 活动推送按真实来源设备路由。
  // 每次重算都基于当前设备列表 + 当前 shards(stale 侧)重建身份索引:认领要求当前设备侧名字唯一 + stale 侧
  // 同名也唯一(避免把两台同名旧机并到一台当前设备),placeholder 名(unknown / no)不参与匹配。
  const identity = deviceList
    ? buildDeviceIdentity(deviceList, [...shards.values()].map((s) => ({ deviceId: s.deviceId, name: s.deviceName })))
    : null;
  const byId = new Map<string, { session: RemoteSession; physicalDeviceId: string; known: boolean }>();
  for (const shard of shards.values()) {
    const canonicalDeviceId = identity
      ? resolveCanonicalDeviceId(shard.deviceId, shard.deviceName, identity) ?? shard.deviceId
      : shard.deviceId;
    const known = identity ? identity.knownDeviceIds.has(shard.deviceId) : false;
    for (const session of shard.sessions) {
      const existing = byId.get(session.id);
      // 已有记录时,只有「当前 shard 已知、而已存条来自未知 shard」才覆盖(current 顶掉 stale);否则保留先到。
      if (existing && !(known && !existing.known)) continue;
      byId.set(session.id, {
        session: session.canonicalDeviceId === canonicalDeviceId ? session : { ...session, canonicalDeviceId },
        physicalDeviceId: shard.deviceId,
        known,
      });
    }
  }
  // 引用调和:与上一轮 mergedSessions 逐会话浅比较,内容未变的保留旧对象引用。
  // 每次重算若无脑换新引用(尤其身份归一化分支的 {...session, canonicalDeviceId} 会给
  // 所有会话铸新对象),首页/设备详情页会话行的 memo 全部失效——一次 store 更新 =
  // 全列表重渲染;桌面端活跃期 push 高频触发重算,渲染队列滚雪球把 JS 线程打满
  // 10~90s(2026-07-18 风暴 trace 实锤,React DevTools 逐行供词:item.session
  // "referentially unequal but deeply equal, consider memoization")。
  const prevById = new Map(mergedSessions.map((s) => [s.id, s]));
  const next: RemoteSession[] = [];
  for (const { session, physicalDeviceId } of byId.values()) {
    const prev = prevById.get(session.id);
    const projected = applyPendingTitlePreview(session);
    const same = prev !== undefined && remoteSessionEqual(prev, projected);
    if (!same) pendingMessagePreviewSessionIds.add(session.id);
    next.push(same ? prev : projected);
    sessionDeviceIndex.set(session.id, physicalDeviceId);
  }
  for (const sessionId of [...sessionLiveActivity.keys()]) {
    if (!sessionDeviceIndex.has(sessionId)) deleteSessionLiveActivity(sessionId);
  }
  // 预览不因列表短暂缺席回收:旧 sessions:list 可能在远端建会话前发出、入队成功后才回来。
  // 权威标题落地、明确失败撤回、归档/删除、设备移除、clear() 才会丢掉。
  // 数组级同样调和:全部元素引用与序都未变时保留旧数组引用——useRemoteSessions 的
  // useSyncExternalStore 快照经 Object.is 即可短路,消费屏对无关 emit 零重渲染。
  const sessionsChanged = !sameElementRefs(mergedSessions, next);
  if (sessionsChanged) mergedSessions = next;
  reconcileVisibleSessions();
  mergedSessionById.clear();
  for (const session of mergedSessions) mergedSessionById.set(session.id, session);
  for (const sources of [sessionRuntimeSources, sessionInteractionSources]) {
    for (const [sessionId, deviceId] of sources) {
      if (sessionDeviceIndex.has(sessionId) && !sessionStateWriteAllowed(sessionId, deviceId)) {
        clearSourcedSessionState(sessionId, sources);
      }
    }
  }
  // Usage-only patches bypass this projection and cannot change Home fields.
  // Reuse the list comparison above to skip its scan and allocations entirely.
  if (sessionsChanged) reconcileHomeSessions();
  let liveRowsReanchored = false;
  for (const session of mergedSessions) {
    bindPendingHostAnchorSendAt(session.id, session.userSendAt);
    liveRowsReanchored = reanchorPendingLiveAssistantRows(
      session.id,
      session.userSendAt ?? session.updatedAt ?? session.createdAt,
      { consumePending: false },
    ) || liveRowsReanchored;
    const nextRetention = retentionForSession(session.id);
    if (nextRetention !== 'schedule' || previousRetention.get(session.id) === 'schedule') continue;
    // source 晚到后立即切断旧缓存路径。旧 hydrate / debounce 回调还会在提交前
    // 二次检查 retention;这里的串行删除负责收掉已经开始的旧写。
    clearSessionMessageCache(session.id, session.deviceLinkDeviceId);
    const current = messages.get(session.id);
    if (!current) continue;
    if (sessionMessageLifecycle.isVisible(session.id)) {
      const trimmed = trimMessageWindow(session.id, current);
      if (!remoteMessageListsEqual(current, trimmed)) {
        messages.set(session.id, trimmed);
        forgetWindowCoverage(session.id);
        bumpMessageVersion(session.id);
      }
    } else {
      sessionMessageLifecycle.leave(session.id, 'session-switch');
    }
  }
  if (liveRowsReanchored) bumpMessageVersion();
  emit();
}

/** 数组元素引用逐位相等(长度 + Object.is)。 */
function sameElementRefs<T>(a: readonly T[], b: readonly T[]): boolean {
  if (a.length !== b.length) return false;
  for (let i = 0; i < a.length; i += 1) {
    if (!Object.is(a[i], b[i])) return false;
  }
  return true;
}

function reconcileVisibleSessions(): void {
  const next = mergedSessions.filter((session) => session.source !== 'side-chat'
    && (session.source !== 'bot' || isTeammateTask(session))
    && sessionListRemovalPreviews.pendingFields(session.id).length === 0
    && (CINDY_MAKE_ENABLED || !isCindyMakeSource(session.source)));
  if (!sameElementRefs(visibleSessions, next)) visibleSessions = next;
}

function stamp(session: RemoteSession, deviceId: string, deviceName: string): RemoteSession {
  return { ...session, deviceLinkDeviceId: deviceId, deviceLinkDeviceName: deviceName };
}

function dropPendingTitlePreview(sessionId: string): void {
  pendingTitlePreview.delete(sessionId);
}

function isDraftSentinelTitle(title: string | undefined): boolean {
  return !title
    || isDefaultDraftSessionTitle(title)
    || title === 'New remote session';
}

function applyPendingTitlePreview(session: RemoteSession): RemoteSession {
  const preview = pendingTitlePreview.get(session.id);
  if (!preview) return session;
  // 分片里可能已经是乐观原文(合成行),也可能仍是哨兵。只有权威标题变成
  // 另一串(智能标题 / 用户改名)才让位;不能把「分片 == 预览」当成终态丢掉。
  if (isDraftSentinelTitle(session.title) || session.title === preview) {
    return session.title === preview ? session : { ...session, title: preview };
  }
  dropPendingTitlePreview(session.id);
  return session;
}

/**
 * 老 Desktop 的 SQLite session 快照不包含 main 内存里的 pending Agent intent / runtime
 * projection。全量列表 / getSession 对账只能刷新它实际携带的字段,不能顺手抹掉已由 push /
 * 权威查询写入的运行时镜像;新 Desktop 显式携带这些字段时仍优先(包括 null)。
 */
function preserveSessionRuntimeFields(
  fresh: RemoteSession,
  local: RemoteSession | undefined,
): RemoteSession {
  if (!local) return fresh;
  let next = fresh;
  for (const key of [
    'companion',
    'taskTeammate',
    'agentSwitchIntent',
    'runtimeGeneration',
    'runtimeBaseline',
    'runtimeEffective',
    'runtimePending',
  ] as const) {
    if (!Object.prototype.hasOwnProperty.call(fresh, key) && local[key] !== undefined) {
      next = { ...next, [key]: local[key] };
    }
  }
  return next;
}

function normalizeMessages(list: readonly RemoteMessage[]): RemoteMessage[] {
  return projectLargeSettledToolInputs([...list].sort(compareMessageOrder));
}

function messageKey(message: RemoteMessage): string {
  return message.id || message.clientId || `${message.role}:${message.createdAt}`;
}

function rememberLivePlanSnapshot(sessionId: string, snapshot: LivePlanSnapshot): void {
  let sessionSnapshots = livePlanSnapshots.get(sessionId);
  if (!sessionSnapshots) {
    sessionSnapshots = new Map();
    livePlanSnapshots.set(sessionId, sessionSnapshots);
  }
  sessionSnapshots.set(`tool:${snapshot.toolUseId}`, snapshot);
  if (snapshot.persistId) sessionSnapshots.set(`persist:${snapshot.persistId}`, snapshot);
}

function rememberLivePlanContent(
  sessionId: string,
  toolUseId: string,
  content: Record<string, unknown>,
): void {
  const previous = livePlanSnapshots.get(sessionId)?.get(`tool:${toolUseId}`);
  rememberLivePlanSnapshot(sessionId, {
    content,
    toolUseId,
    ...(previous?.persistId ? { persistId: previous.persistId } : {}),
  });
}

function overlayLivePlanSnapshot(sessionId: string, message: RemoteMessage): RemoteMessage {
  if (message.role !== 'tool_use') return message;
  const sessionSnapshots = livePlanSnapshots.get(sessionId);
  if (!sessionSnapshots) return message;
  const contentToolUseId = readString(message.content, 'toolUseId');
  const snapshot = sessionSnapshots.get(`persist:${message.id}`)
    ?? sessionSnapshots.get(`persist:${message.clientId}`)
    ?? (message.toolUseId ? sessionSnapshots.get(`tool:${message.toolUseId}`) : undefined)
    ?? (contentToolUseId ? sessionSnapshots.get(`tool:${contentToolUseId}`) : undefined);
  return snapshot
    ? { ...message, content: snapshot.content, toolUseId: snapshot.toolUseId }
    : message;
}

function completeLivePlanSnapshotOnDone(
  sessionId: string,
  snapshot: unknown,
  turnId: string | null,
  terminalStatus: string | null,
  cancelled: boolean,
): boolean {
  if (!turnId) return false;
  const toolUseId = `plan:${turnId}`;
  const liveSnapshot = livePlanSnapshots.get(sessionId)?.get(`tool:${toolUseId}`);
  if (!liveSnapshot) return false;

  const completed = applyCodexPlanSnapshotOnDone(
    [{ role: 'tool_use', toolUseId, content: liveSnapshot.content }],
    snapshot,
    turnId,
    terminalStatus,
    undefined,
    cancelled,
  );
  const content = completed.messages[0]?.content;
  if (!completed.changed || !isRecord(content)) return false;
  rememberLivePlanContent(sessionId, toolUseId, content);
  return true;
}

/** End any pre-compaction streaming rows without changing the overall running turn. */
function finishMessageStreamingAtCompactBoundary(message: RemoteMessage): RemoteMessage {
  let agentMeta = message.agentMeta;
  let content = message.content;
  let changed = false;
  if (agentMeta?.isStreaming === true || agentMeta?.streaming === true) {
    agentMeta = { ...agentMeta, isStreaming: false, streaming: false };
    changed = true;
  }
  if (isRecord(content) && (content.isStreaming === true || content.streaming === true)) {
    content = { ...content, isStreaming: false, streaming: false };
    changed = true;
  }
  return changed ? { ...message, agentMeta, content } : message;
}

/** Apply a repeated Codex plan snapshot to the one persisted tool row used by desktop. */
interface LivePlanToolUseResult {
  handled: boolean;
  changed: boolean;
}

function applyLivePlanToolUseMessage(
  sessionId: string,
  event: Record<string, unknown>,
  persistId?: string,
): LivePlanToolUseResult {
  const data = isRecord(event.data) ? event.data : {};
  if (readString(data, 'toolName') !== 'update_plan') return { handled: false, changed: false };

  const toolUseId = readString(data, 'toolUseId');
  if (!toolUseId) return { handled: true, changed: false };
  const content = {
    toolUseId,
    toolName: 'update_plan',
    input: data.input,
  };
  rememberLivePlanSnapshot(sessionId, { content, persistId, toolUseId });
  const existing = messages.get(sessionId) ?? [];
  const targetIndex = existing.findIndex((message) => {
    if (message.role !== 'tool_use') return false;
    if (persistId && (message.id === persistId || message.clientId === persistId)) return true;
    if (message.toolUseId === toolUseId) return true;
    return readString(message.content, 'toolUseId') === toolUseId;
  });
  if (targetIndex < 0) return { handled: true, changed: false };

  const current = existing[targetIndex];
  if (current.toolUseId === toolUseId && deepValueEqual(current.content, content)) {
    return { handled: true, changed: false };
  }

  const next = [...existing];
  next[targetIndex] = { ...current, content, toolUseId };
  messages.set(sessionId, next);
  bumpMessageVersion(sessionId);
  return { handled: true, changed: true };
}

/**
 * 同 key 消息合并时优先保留内容完整的一侧:被控端结果帧超限会把历史行内容截成
 * 占位串并打 agentMeta.remoteContentTruncated 标记(device-link dispatch),这种
 * 截断行不能覆盖已通过实时 push 拿到的完整内容;反向(完整行到达)照常覆盖。
 */
function preferCompleteMessage(existing: RemoteMessage | undefined, incoming: RemoteMessage): RemoteMessage {
  if (!existing) return incoming;
  const incomingTruncated = incoming.agentMeta?.remoteContentTruncated === true;
  const existingTruncated = existing.agentMeta?.remoteContentTruncated === true;
  if (!incomingTruncated || existingTruncated) return incoming;
  // Keep the complete payload, but do not throw away newer authoritative metadata
  // (for example an Agent/Task terminal state patched after the original push).
  return {
    ...existing,
    createdAt: incoming.createdAt,
    agentMeta: {
      ...(existing.agentMeta ?? {}),
      ...(incoming.agentMeta ?? {}),
      remoteContentTruncated: false,
    },
  };
}

function messageIdentityMatches(a: RemoteMessage, b: RemoteMessage): boolean {
  return Boolean(
    (a.id && b.id && a.id === b.id)
      || (a.clientId && b.clientId && a.clientId === b.clientId),
  );
}

function findMessageByIdentity(list: readonly RemoteMessage[], target: RemoteMessage): RemoteMessage | undefined {
  return list.find((item) => messageIdentityMatches(item, target));
}

function findMessageMergeKey(byKey: ReadonlyMap<string, RemoteMessage>, target: RemoteMessage): string | null {
  const directKey = messageKey(target);
  if (byKey.has(directKey)) return directKey;
  for (const [key, item] of byKey) {
    if (messageIdentityMatches(item, target)) return key;
  }
  return null;
}

/**
 * 「这一行在不在那一批里」的线性判据。`messageKey` 是常态路径;单独的 id / clientId 集合保留
 * clientId→id 迁移那一档,不必退回 O(n×m) 嵌套扫描。
 *
 * 交集探测(`messageWindowsOverlap`)与覆盖区间的事实自检(`joinableWindowCoverage`)问的是同一件
 * 事,共用这一份索引 —— 两处各写一遍迟早会在迁移档上分叉。
 */
type MessageIdentityIndex = {
  keys: Set<string>;
  ids: Set<string>;
  clientIds: Set<string>;
};

function buildMessageIdentityIndex(list: readonly RemoteMessage[]): MessageIdentityIndex {
  const index: MessageIdentityIndex = { keys: new Set(), ids: new Set(), clientIds: new Set() };
  for (const message of list) {
    index.keys.add(messageKey(message));
    if (message.id) index.ids.add(message.id);
    if (message.clientId) index.clientIds.add(message.clientId);
  }
  return index;
}

function messageIdentityIndexHas(index: MessageIdentityIndex, message: RemoteMessage): boolean {
  return index.keys.has(messageKey(message))
    || (message.id ? index.ids.has(message.id) : false)
    || (message.clientId ? index.clientIds.has(message.clientId) : false);
}

function messageWindowsOverlap(a: readonly RemoteMessage[], b: readonly RemoteMessage[]): boolean {
  const index = buildMessageIdentityIndex(a);
  return b.some((message) => messageIdentityIndexHas(index, message));
}

function streamingMeta(meta: Record<string, unknown> | null | undefined): Record<string, unknown> {
  return { ...(meta ?? {}), isStreaming: true };
}

function clearStreamingMeta(meta: Record<string, unknown> | null): Record<string, unknown> | null {
  if (!meta) return null;
  const next = { ...meta };
  delete next.isStreaming;
  delete next.streaming;
  return Object.keys(next).length > 0 ? next : null;
}

function isGeneratedStreamingClientId(clientId: string | null | undefined): boolean {
  return typeof clientId === 'string' && clientId.startsWith('mobile-stream-');
}

function rememberPendingLiveAssistantClientId(sessionId: string, clientId: string | null | undefined): void {
  if (!clientId) return;
  const existing = pendingLiveAssistantClientIds.get(sessionId) ?? new Set<string>();
  existing.add(clientId);
  pendingLiveAssistantClientIds.set(sessionId, existing);
}

function rememberPendingHostAnchorLiveAssistantClientId(
  sessionId: string,
  clientId: string | null | undefined,
  sendAt: string | null = latestUserSendAt(sessionId) ?? null,
  bindOnMetadata = true,
  deviceIds?: string | readonly string[],
  unboundRoundId?: number | null,
): void {
  if (!clientId) return;
  const existing = pendingHostAnchorLiveAssistantClientIds.get(sessionId)
    ?? new Map<string, PendingHostAnchorIdentity>();
  const nextDeviceIds = typeof deviceIds === 'string'
    ? [deviceIds]
    : deviceIds ?? [];
  if (!existing.has(clientId)) {
    let resolvedRoundId = unboundRoundId;
    if (resolvedRoundId === undefined) {
      if (sendAt !== null) {
        resolvedRoundId = null;
      } else if (sessionMakerTurnRunning.get(sessionId) === true) {
        resolvedRoundId = activePendingHostAnchorRoundIds.get(sessionId);
        if (resolvedRoundId === undefined) {
          resolvedRoundId = ++nextPendingHostAnchorRoundId;
          activePendingHostAnchorRoundIds.set(sessionId, resolvedRoundId);
        }
      } else {
        // Older producers may omit maker status boundaries. Preserve their historical
        // one-row-per-user fallback instead of grouping unrelated unbound replies.
        resolvedRoundId = ++nextPendingHostAnchorRoundId;
      }
    }
    existing.set(clientId, {
      bindOnMetadata,
      deviceIds: new Set(nextDeviceIds),
      sendAt,
      unboundRoundId: resolvedRoundId,
    });
  } else if (nextDeviceIds.length > 0) {
    const identity = existing.get(clientId);
    if (identity && nextDeviceIds.some((deviceId) => !identity.deviceIds.has(deviceId))) {
      existing.set(clientId, {
        ...identity,
        deviceIds: new Set([...identity.deviceIds, ...nextDeviceIds]),
      });
    }
  }
  pendingHostAnchorLiveAssistantClientIds.set(sessionId, existing);
}

function pendingHostAnchorIdentity(
  sessionId: string,
  ...ids: Array<string | null | undefined>
): PendingHostAnchorIdentity | undefined {
  const existing = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  if (!existing) return undefined;
  for (const id of ids) {
    if (id && existing.has(id)) return existing.get(id);
  }
  return undefined;
}

function bindPendingHostAnchorSendAt(sessionId: string, sendAt: string | null | undefined): void {
  if (!sendAt) return;
  const existing = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  if (!existing) return;
  for (const [id, identity] of existing) {
    if (identity.sendAt === null && identity.bindOnMetadata) {
      existing.set(id, { ...identity, sendAt });
    }
  }
}

function freezeUnboundPendingHostAnchorsForOffline(sessionId: string, deviceId: string): boolean {
  const existing = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  if (!existing) return false;
  let changed = false;
  for (const [id, identity] of existing) {
    if (!identity.deviceIds.has(deviceId)) continue;
    if (identity.sendAt !== null || !identity.bindOnMetadata) continue;
    existing.set(id, { ...identity, bindOnMetadata: false });
    changed = true;
  }
  return changed;
}

function hasOfflineUnboundPendingHostAnchor(sessionId: string): boolean {
  const existing = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  return existing
    ? [...existing.values()].some((identity) => (
      identity.sendAt === null && !identity.bindOnMetadata
    ))
    : false;
}

function forgetPendingLiveAssistantClientId(sessionId: string, clientId: string | null | undefined): void {
  if (!clientId) return;
  const existing = pendingLiveAssistantClientIds.get(sessionId);
  if (existing) {
    existing.delete(clientId);
    if (existing.size === 0) pendingLiveAssistantClientIds.delete(sessionId);
  }
  const pendingHostAnchorIds = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  if (pendingHostAnchorIds) {
    pendingHostAnchorIds.delete(clientId);
    if (pendingHostAnchorIds.size === 0) {
      pendingHostAnchorLiveAssistantClientIds.delete(sessionId);
    }
  }
  forgetStreamingAssistantDeviceId(sessionId, clientId);
}

function forgetPendingLiveAssistantMessageIdentity(
  sessionId: string,
  ...ids: Array<string | null | undefined>
): void {
  for (const id of ids) forgetPendingLiveAssistantClientId(sessionId, id);
}

function forgetGeneratedPendingLiveAssistantClientIds(sessionId: string): void {
  const existing = pendingLiveAssistantClientIds.get(sessionId);
  if (!existing) return;
  for (const id of [...existing]) {
    if (isGeneratedStreamingClientId(id)) forgetPendingLiveAssistantClientId(sessionId, id);
  }
}

function reanchorPendingLiveAssistantRows(
  sessionId: string,
  hostCreatedAtWatermark: string | undefined,
  options: {
    /** 快照默认只临时重锚;实时消息或已匹配最新 userSendAt 的窗口才可消费身份。 */
    consumePending?: boolean;
    /** user 行与 live 回复同戳时,明确把回复放在触发它的 user 行之后。 */
    afterMessage?: RemoteMessage;
    /** 权威窗口可一次带回多轮 user;从窗口尾部向前与 pending 回复按序一对一配对。 */
    afterMessages?: readonly RemoteMessage[];
    /** 权威窗口已覆盖到会话起点;否则最旧 user 可能已被窗口上沿截断。 */
    afterMessagesStartIsComplete?: boolean;
    /** 已知本轮发送标记时,实时 user push 也只认领最新的 pending 回复。 */
    pairPendingFromEnd?: boolean;
  } = {},
): boolean {
  if (!hostCreatedAtWatermark) return false;
  const pendingIds = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
  if (!pendingIds || pendingIds.size === 0) return false;
  const existing = messages.get(sessionId);
  if (!existing) return false;
  const pendingRows: Array<{
    identity: PendingHostAnchorIdentity;
    message: RemoteMessage;
  }> = [];
  for (const [pendingId, identity] of pendingIds) {
    const match = existing.find((message) => (
      message.role === 'assistant'
      && (message.id === pendingId || message.clientId === pendingId)
    ));
    if (match && !pendingRows.some((row) => row.message === match)) {
      pendingRows.push({ message: match, identity });
    }
  }
  const afterMessages = options.afterMessages
    ?? (options.afterMessage ? [options.afterMessage] : []);
  const pairsPendingFromEnd = options.afterMessages !== undefined
    || options.pairPendingFromEnd === true;
  const latestSendAt = latestUserSendAt(sessionId);
  const knownSendAts = [...new Set([
    ...pendingRows
      .map((row) => row.identity.sendAt)
      .filter((sendAt): sendAt is string => sendAt !== null),
    ...afterMessages
      .filter((message) => message.role === 'user')
      .map((message) => message.createdAt),
    ...(latestSendAt ? [latestSendAt] : []),
  ])].sort((left, right) => left.localeCompare(right));
  const hasOfflineUnboundPendingRow = pendingRows.some((row) => (
    row.identity.sendAt === null && !row.identity.bindOnMetadata
  ));
  const pendingRowCanPairMessage = (
    row: (typeof pendingRows)[number],
    message: RemoteMessage,
  ): boolean => {
    const rowSendAt = row.identity.sendAt;
    if (
      hasOfflineUnboundPendingRow
      && latestSendAt
      && message.createdAt.localeCompare(latestSendAt) < 0
    ) {
      return rowSendAt === null && !row.identity.bindOnMetadata;
    }
    if (rowSendAt === null && !row.identity.bindOnMetadata) {
      return Boolean(latestSendAt && message.createdAt.localeCompare(latestSendAt) < 0);
    }
    if (!rowSendAt || !latestSendAt || rowSendAt.localeCompare(latestSendAt) >= 0) return true;
    const nextSendAt = knownSendAts.find((sendAt) => sendAt.localeCompare(rowSendAt) > 0);
    return message.createdAt.localeCompare(rowSendAt) >= 0
      && (!nextSendAt || message.createdAt.localeCompare(nextSendAt) < 0);
  };
  const pairs: Array<{
    pendingRow: (typeof pendingRows)[number];
    afterMessage: RemoteMessage;
  }> = [];
  const pairsOfflineUnboundFromStart = options.afterMessages === undefined
    && afterMessages.length === 1
    && afterMessages[0].role === 'user'
    && hasOfflineUnboundPendingRow
    && Boolean(latestSendAt)
    && afterMessages[0].createdAt.localeCompare(latestSendAt ?? '') < 0;
  const offlineUnboundRoundGroups = new Map<
    number,
    Array<(typeof pendingRows)[number]>
  >();
  for (const row of pendingRows) {
    if (
      row.identity.sendAt !== null
      || row.identity.bindOnMetadata
      || row.identity.unboundRoundId === null
    ) continue;
    const group = offlineUnboundRoundGroups.get(row.identity.unboundRoundId) ?? [];
    group.push(row);
    offlineUnboundRoundGroups.set(row.identity.unboundRoundId, group);
  }
  const orderedOfflineUnboundRoundGroups = [...offlineUnboundRoundGroups]
    .sort(([leftRoundId], [rightRoundId]) => leftRoundId - rightRoundId)
    .map(([, rows]) => rows);
  const reconnectWindowUsers = afterMessages.filter((message) => (
    message.role === 'user'
    && (!latestSendAt || message.createdAt.localeCompare(latestSendAt) <= 0)
  ));
  const pairsOfflineUnboundWindowInOrder = options.afterMessages !== undefined
    && orderedOfflineUnboundRoundGroups.length > 1
    && orderedOfflineUnboundRoundGroups.reduce((count, rows) => count + rows.length, 0)
      === pendingRows.length
    && reconnectWindowUsers.length > 0;
  // A bounded latest window represents the newest user rows, so pair it with the
  // newest pending replies. Realtime pushes do the same once the latest send marker
  // is known, except delayed users restoring multiple offline-unbound rounds: those
  // must consume the oldest eligible cohort first to preserve arrival order.
  if (pairsPendingFromEnd && pairsOfflineUnboundWindowInOrder) {
    // A reconnect window can deliver several delayed users in one authoritative page.
    // Pair only when that page accounts for every offline cohort; a truncated latest
    // suffix cannot prove whether its first user belongs to the oldest pending round.
    if (
      options.afterMessagesStartIsComplete === true
      && reconnectWindowUsers.length === orderedOfflineUnboundRoundGroups.length
    ) {
      const pairedUsers = reconnectWindowUsers;
      for (let index = 0; index < orderedOfflineUnboundRoundGroups.length; index += 1) {
        for (const pendingRow of orderedOfflineUnboundRoundGroups[index]) {
          pairs.push({ pendingRow, afterMessage: pairedUsers[index] });
        }
      }
    }
  } else if (pairsPendingFromEnd && pairsOfflineUnboundFromStart) {
    const afterMessage = afterMessages[0];
    const pendingRow = pendingRows
      .filter((row) => pendingRowCanPairMessage(row, afterMessage))
      .reduce<(typeof pendingRows)[number] | undefined>((oldest, row) => {
        if (!oldest) return row;
        const oldestRoundId = oldest.identity.unboundRoundId ?? Number.MAX_SAFE_INTEGER;
        const rowRoundId = row.identity.unboundRoundId ?? Number.MAX_SAFE_INTEGER;
        return rowRoundId < oldestRoundId ? row : oldest;
      }, undefined);
    if (pendingRow) pairs.push({ pendingRow, afterMessage });
  } else if (pairsPendingFromEnd) {
    let maxRowIndex = pendingRows.length - 1;
    for (let afterIndex = afterMessages.length - 1; afterIndex >= 0 && maxRowIndex >= 0; afterIndex -= 1) {
      let matchedRowIndex = -1;
      for (let rowIndex = maxRowIndex; rowIndex >= 0; rowIndex -= 1) {
        if (pendingRowCanPairMessage(pendingRows[rowIndex], afterMessages[afterIndex])) {
          matchedRowIndex = rowIndex;
          break;
        }
      }
      if (matchedRowIndex < 0) continue;
      pairs.unshift({
        pendingRow: pendingRows[matchedRowIndex],
        afterMessage: afterMessages[afterIndex],
      });
      maxRowIndex = matchedRowIndex - 1;
    }
  } else {
    const pairCount = Math.min(pendingRows.length, afterMessages.length);
    for (let index = 0; index < pairCount; index += 1) {
      pairs.push({ pendingRow: pendingRows[index], afterMessage: afterMessages[index] });
    }
  }
  // A single realtime/latest-window user row identifies one send round. All live
  // assistant blocks carrying that non-null send marker belong after the same user;
  // move them as one ordered block instead of consuming only the last block.
  if (afterMessages.length === 1 && pairs.length === 1) {
    const groupedIdentity = pairs[0].pendingRow.identity;
    if (groupedIdentity.unboundRoundId !== null || groupedIdentity.sendAt !== null) {
      const afterMessage = afterMessages[0];
      const groupedRows = pendingRows.filter((row) => (
        (groupedIdentity.unboundRoundId !== null
          ? row.identity.unboundRoundId === groupedIdentity.unboundRoundId
          : row.identity.sendAt === groupedIdentity.sendAt)
        && pendingRowCanPairMessage(row, afterMessage)
      ));
      pairs.splice(0, pairs.length, ...groupedRows.map((pendingRow) => ({
        pendingRow,
        afterMessage,
      })));
    }
  }
  const pairedCreatedAtById = new Map<string, string>();
  for (const pair of pairs) {
    const pendingRow = pair.pendingRow.message;
    const createdAt = pair.afterMessage.createdAt;
    pairedCreatedAtById.set(pendingRow.id, createdAt);
    pairedCreatedAtById.set(pendingRow.clientId, createdAt);
  }
  const reanchored = existing.map((message) => {
    if (
      message.role !== 'assistant'
      || (!pendingIds.has(message.id) && !pendingIds.has(message.clientId))
    ) return message;
    const pairedCreatedAt = pairedCreatedAtById.get(message.id)
      ?? pairedCreatedAtById.get(message.clientId);
    if (pairsPendingFromEnd && pairedCreatedAt === undefined) return message;
    const pendingIdentity = pendingHostAnchorIdentity(sessionId, message.id, message.clientId);
    if (
      pairedCreatedAt === undefined
      && pendingIdentity?.sendAt === null
      && !pendingIdentity.bindOnMetadata
    ) return message;
    if (
      pairedCreatedAt === undefined
      && pendingIdentity?.sendAt
      && latestSendAt
      && pendingIdentity.sendAt.localeCompare(latestSendAt) < 0
      && hostCreatedAtWatermark.localeCompare(latestSendAt) >= 0
    ) return message;
    const createdAt = pairedCreatedAt ?? hostCreatedAtWatermark;
    return message.createdAt === createdAt ? message : { ...message, createdAt };
  });
  let next = normalizeMessages(reanchored);
  const pairGroups: Array<{
    afterMessage: RemoteMessage;
    pendingRows: Array<(typeof pendingRows)[number]>;
  }> = [];
  for (const pair of pairs) {
    const group = pairGroups.find((candidate) => (
      messageIdentityMatches(candidate.afterMessage, pair.afterMessage)
    ));
    if (group) group.pendingRows.push(pair.pendingRow);
    else pairGroups.push({ afterMessage: pair.afterMessage, pendingRows: [pair.pendingRow] });
  }
  const consumedPendingRows: RemoteMessage[] = [];
  for (const group of pairGroups) {
    const groupedRows = next.filter((message) => group.pendingRows.some((row) => (
      messageIdentityMatches(message, row.message)
    )));
    if (groupedRows.length === 0) continue;
    const withoutPending = next.filter((message) => !group.pendingRows.some((row) => messageIdentityMatches(message, row.message)
    ));
    const anchorIndex = withoutPending.findIndex((message) =>
      messageIdentityMatches(message, group.afterMessage));
    if (anchorIndex < 0) continue;
    next = [
      ...withoutPending.slice(0, anchorIndex + 1),
      ...groupedRows,
      ...withoutPending.slice(anchorIndex + 1),
    ];
    consumedPendingRows.push(...groupedRows);
  }
  if (options.consumePending !== false) {
    if (afterMessages.length > 0) {
      for (const pendingRow of consumedPendingRows) {
        pendingIds.delete(pendingRow.id);
        pendingIds.delete(pendingRow.clientId);
      }
      if (pendingIds.size === 0) {
        pendingHostAnchorLiveAssistantClientIds.delete(sessionId);
      }
    } else {
      pendingHostAnchorLiveAssistantClientIds.delete(sessionId);
    }
  }
  if (remoteMessageListsEqual(existing, next)) return false;
  messages.set(sessionId, next);
  return true;
}

function retireGeneratedStreamingFallback(sessionId: string): void {
  const current = streamingAssistantClientIds.get(sessionId);
  if (isGeneratedStreamingClientId(current)) clearStreamingAssistantPointer(sessionId);
  forgetGeneratedPendingLiveAssistantClientIds(sessionId);
}

function isPersistedAssistantMessage(message: RemoteMessage): boolean {
  return message.role === 'assistant'
    && message.agentMeta?.isStreaming !== true
    && !isGeneratedStreamingClientId(message.id)
    && !isGeneratedStreamingClientId(message.clientId)
    && Boolean(message.id || message.clientId);
}

function findPendingGeneratedStreamingFallbackIndex(
  sessionId: string,
  existing: readonly RemoteMessage[],
): number {
  const pendingIds = pendingLiveAssistantClientIds.get(sessionId);
  if (!pendingIds || pendingIds.size === 0) return -1;
  for (let index = existing.length - 1; index >= 0; index -= 1) {
    const message = existing[index];
    if (
      message.role === 'assistant'
      && isGeneratedStreamingClientId(message.id)
      && pendingIds.has(message.id)
    ) {
      return index;
    }
    if (
      message.role === 'assistant'
      && isGeneratedStreamingClientId(message.clientId)
      && pendingIds.has(message.clientId)
    ) {
      return index;
    }
  }
  return -1;
}

function generatedFallbackMatchesPersistedMessage(
  fallback: RemoteMessage,
  persisted: RemoteMessage,
): boolean {
  const liveText = contentToPreview(fallback.content);
  const persistedText = contentToPreview(persisted.content);
  if (!liveText || !persistedText) return false;
  // A short common prefix is not enough evidence: a delayed row from an older
  // assistant block can easily start with the same token (for example `Sure`).
  // Only let a persisted row retire a generated fallback when the DB row is an
  // authoritative continuation with enough accumulated text to make the prefix
  // unambiguous. Never replace a longer live row with a shorter persisted prefix.
  return liveText.length >= GENERATED_FALLBACK_MIN_PREFIX_LENGTH
    && persistedText.startsWith(liveText);
}

interface StreamingClientIdResolution {
  clientId: string;
  changed: boolean;
}

function migrateGeneratedStreamingClientId(sessionId: string, generatedClientId: string, persistId: string): boolean {
  generatedStreamPriorIdentities.delete(sessionId);
  generatedStreamAgentIdentities.delete(sessionId);
  streamingAssistantClientIds.set(sessionId, persistId);

  const hadPendingLiveId = pendingLiveAssistantClientIds.get(sessionId)?.has(generatedClientId) === true;
  const streamingDeviceId = streamingAssistantDeviceId(sessionId, generatedClientId);
  const neededHostAnchor = pendingHostAnchorLiveAssistantClientIds
    .get(sessionId)
    ?.has(generatedClientId) === true;
  const hostAnchorIdentity = pendingHostAnchorIdentity(sessionId, generatedClientId);
  forgetPendingLiveAssistantClientId(sessionId, generatedClientId);
  if (hadPendingLiveId) rememberPendingLiveAssistantClientId(sessionId, persistId);
  if (streamingDeviceId) {
    rememberStreamingAssistantDeviceId(sessionId, persistId, streamingDeviceId);
  }
  if (neededHostAnchor && hostAnchorIdentity) {
    rememberPendingHostAnchorLiveAssistantClientId(
      sessionId,
      persistId,
      hostAnchorIdentity.sendAt,
      hostAnchorIdentity.bindOnMetadata,
      [...hostAnchorIdentity.deviceIds],
      hostAnchorIdentity.unboundRoundId,
    );
  }

  const existing = messages.get(sessionId);
  if (!existing) return false;
  const generatedIndex = existing.findIndex((message) => (
    message.role === 'assistant'
      && (message.id === generatedClientId || message.clientId === generatedClientId)
  ));
  if (generatedIndex < 0) return false;

  const migrated = {
    ...existing[generatedIndex],
    id: existing[generatedIndex].id === generatedClientId ? persistId : existing[generatedIndex].id,
    clientId: persistId,
  };
  const targetIndex = existing.findIndex((message, index) => (
    index !== generatedIndex && messageIdentityMatches(message, migrated)
  ));
  const next = existing.slice();
  if (targetIndex >= 0) next.splice(generatedIndex, 1);
  else next[generatedIndex] = migrated;
  messages.set(sessionId, normalizeMessages(next));
  bumpMessageVersion(sessionId);
  return true;
}

function excludeFromGeneratedStream(sessionId: string, ...ids: (string | undefined)[]): void {
  const identities = generatedStreamPriorIdentities.get(sessionId);
  if (!identities) return;
  for (const id of ids) if (id) identities.add(id);
}

function streamingClientIdFor(sessionId: string, persistId: string | undefined): StreamingClientIdResolution {
  const normalizedPersistId = persistId?.trim();
  if (normalizedPersistId) {
    const existing = streamingAssistantClientIds.get(sessionId);
    if (existing && isGeneratedStreamingClientId(existing)) {
      return {
        clientId: normalizedPersistId,
        changed: migrateGeneratedStreamingClientId(sessionId, existing, normalizedPersistId),
      };
    }
    generatedStreamPriorIdentities.delete(sessionId);
    generatedStreamAgentIdentities.delete(sessionId);
    streamingAssistantClientIds.set(sessionId, normalizedPersistId);
    return { clientId: normalizedPersistId, changed: false };
  }
  const existing = streamingAssistantClientIds.get(sessionId);
  if (existing) return { clientId: existing, changed: false };
  const generated = `mobile-stream-${++streamingFallbackSequence}`;
  generatedStreamPriorIdentities.set(sessionId, new Set(
    (messages.get(sessionId) ?? []).flatMap((row) => [row.id, row.clientId].filter((id): id is string => Boolean(id))),
  ));
  streamingAssistantClientIds.set(sessionId, generated);
  return { clientId: generated, changed: false };
}

function upsertMessage(
  sessionId: string,
  message: RemoteMessage,
  options: {
    /** Caller already resolved this exact identity in the current message array. */
    knownIndex?: number;
    retirePendingAssistantIdentityOnEqual?: boolean;
    /** An older final with no proven link must not retire an anonymous new stream. */
    preserveGeneratedStreamingFallback?: boolean;
    /** A streaming text replacement changes row content but not list structure or identities. */
    preserveStructureOnReplace?: boolean;
    /** Streaming replacement preserves the already sorted message order. */
    preserveOrderOnReplace?: boolean;
  } = {},
): boolean {
  const existing = messages.get(sessionId) ?? [];
  const priorIdentities = generatedStreamPriorIdentities.get(sessionId);
  let preservesGeneratedStream = options.preserveGeneratedStreamingFallback === true
    || priorIdentities?.has(message.id) === true
    || (message.clientId ? priorIdentities?.has(message.clientId) === true : false);
  const candidateIndex = options.knownIndex ?? -1;
  const index = candidateIndex >= 0
    && candidateIndex < existing.length
    && messageIdentityMatches(existing[candidateIndex], message)
    ? candidateIndex
    : existing.findIndex((item) => messageIdentityMatches(item, message));
  let fallbackIndex = -1;
  if (index < 0 && isPersistedAssistantMessage(message)) {
    fallbackIndex = findPendingGeneratedStreamingFallbackIndex(sessionId, existing);
    if (
      fallbackIndex >= 0
      && !preservesGeneratedStream
      && generatedFallbackMatchesPersistedMessage(existing[fallbackIndex], message)
    ) {
      // A producer without persistId creates a temporary mobile-stream-* row. The
      // matching DB create is authoritative even though its id cannot match that row.
      const next = existing.slice();
      next[fallbackIndex] = message;
      messages.set(sessionId, normalizeMessages(next));
      applyMessageWriteRetention(sessionId);
      retireGeneratedStreamingFallback(sessionId);
      bumpMessageVersion(sessionId);
      return true;
    }
  }
  if (isPersistedAssistantMessage(message)
    && isGeneratedStreamingClientId(streamingAssistantClientIds.get(sessionId))) {
    // This row did not merge with the live fallback. Keep that separation on replay.
    excludeFromGeneratedStream(sessionId, message.id, message.clientId);
    preservesGeneratedStream = true;
  }
  if (index < 0) {
    messages.set(sessionId, normalizeMessages([...existing, message]));
    applyMessageWriteRetention(sessionId);
    if (isPersistedAssistantMessage(message) && fallbackIndex < 0 && !preservesGeneratedStream) {
      retireGeneratedStreamingFallback(sessionId);
    }
    bumpMessageVersion(sessionId);
    return true;
  }
  const replacement = preferCompleteMessage(existing[index], message);
  if (remoteMessageEqual(existing[index], replacement)) {
    if (
      message.role !== 'assistant'
      || options.retirePendingAssistantIdentityOnEqual !== true
    ) return false;
    const hadPendingIdentity = isPendingLiveAssistantMessage(sessionId, existing[index])
      || pendingHostAnchorIdentity(
        sessionId,
        existing[index].id,
        existing[index].clientId,
        message.id,
        message.clientId,
      ) !== undefined;
    forgetPendingLiveAssistantMessageIdentity(
      sessionId,
      existing[index].id,
      existing[index].clientId,
      message.id,
      message.clientId,
    );
    if (isPersistedAssistantMessage(message) && !preservesGeneratedStream) retireGeneratedStreamingFallback(sessionId);
    return hadPendingIdentity;
  }
  const next = existing.slice();
  next[index] = replacement;
  // A live delta only changes content/metadata; sorting the whole window on
  // every 32 ms flush needlessly allocates and scans all rows.  Callers that
  // replace an authoritative row keep the historical normalization path.
  const committed = options.preserveOrderOnReplace ? next : normalizeMessages(next);
  if (options.preserveStructureOnReplace) inheritMessageStructure(existing, committed, index);
  if (options.preserveOrderOnReplace) {
    inheritMessageIdentityIndex(existing, committed, index);
    inheritMessageListBudgetStats(existing, committed, index);
  }
  messages.set(sessionId, committed);
  applyMessageWriteRetention(sessionId);
  if (message.role === 'assistant') {
    forgetPendingLiveAssistantMessageIdentity(
      sessionId,
      existing[index]?.id,
      existing[index]?.clientId,
      message.id,
      message.clientId,
    );
    if (isPersistedAssistantMessage(message) && !preservesGeneratedStream) retireGeneratedStreamingFallback(sessionId);
  }
  bumpMessageVersion(sessionId);
  return true;
}

function findMessageIndexByIdentity(
  list: readonly RemoteMessage[],
  id: string,
): number {
  const tailIndex = list.length - 1;
  const tail = list[tailIndex];
  if (tail && (tail.id === id || tail.clientId === id)) return tailIndex;
  return messageIdentityIndex(list).get(id) ?? -1;
}

function applyRemoteTextEvent(
  sessionId: string,
  event: Record<string, unknown>,
  persistId?: string,
  deviceId?: string,
): boolean {
  const previous = messages.get(sessionId);
  const changed = mergeRemoteTextEvent(sessionId, event, persistId, deviceId);
  const list = messages.get(sessionId);
  if (list && list !== previous) {
    // Cache provenance with the extracted text, not with a lingering streaming
    // pointer. Any later session metadata makes this live preview yield to Host.
    messagePreviewCache.set(list, {
      preview: buildSessionMessagePreviewIndex([sessionId], () => list).get(sessionId),
      liveSession: sessionById(sessionId),
    });
  }
  return changed;
}

function mergeRemoteTextEvent(
  sessionId: string,
  event: Record<string, unknown>,
  persistId?: string,
  deviceId?: string,
): boolean {
  const data = isRecord(event.data) ? event.data : null;
  const text = typeof data?.text === 'string' ? data.text : '';
  const isFinal = data?.isFinal === true;
  // Legacy hosts already send isFullText on final events. Keep their existing
  // reconciliation semantics; only the new in-flight snapshot replaces text.
  const snapshot = readRemoteTextSnapshot(event);
  if (snapshot?.truncated) return false;
  const isFullText = snapshot !== undefined;
  const snapshotCreatedAt = snapshot?.createdAt;
  if (!text) return false;

  const authoritativeDeviceId = authoritativeSessionDeviceId(sessionId);
  const currentMessages = messages.get(sessionId) ?? [];
  const hasAuthoritativePendingAssembly = authoritativeDeviceId !== undefined
    && [...(streamingAssistantDeviceIds.get(sessionId) ?? [])].some(([ownedClientId, ownerDeviceId]) => {
      if (ownerDeviceId !== authoritativeDeviceId) return false;
      const ownedIndex = findMessageIndexByIdentity(currentMessages, ownedClientId);
      const ownedMessage = ownedIndex >= 0 ? currentMessages[ownedIndex] : undefined;
      if (!ownedMessage || !isPendingLiveAssistantMessage(sessionId, ownedMessage)) return false;
      const ownedHostAnchorIdentity = pendingHostAnchorIdentity(
        sessionId,
        ownedMessage.id,
        ownedMessage.clientId,
        ownedClientId,
      );
      return !(
        ownedHostAnchorIdentity?.bindOnMetadata === false
        && ownedHostAnchorIdentity.deviceIds.has(ownerDeviceId)
      );
    });
  const rejectsBeforeClientIdMutation = deviceId !== undefined
    && authoritativeDeviceId !== undefined
    && deviceId !== authoritativeDeviceId
    && hasAuthoritativePendingAssembly;
  if (rejectsBeforeClientIdMutation) return false;

  const previousStreamingClientId = streamingAssistantClientIds.get(sessionId);
  const normalizedPersistId = persistId?.trim();
  // A completed older item may deliver its full text after a newer stream has
  // started. Its exact row owns this correction, not the current stream pointer.
  const priorIdentities = generatedStreamPriorIdentities.get(sessionId);
  const finalReusesExistingItem = isFinal && data?.isFullText === true && normalizedPersistId
    && (priorIdentities?.has(normalizedPersistId) === true
      || currentMessages.some((row) => row.role === 'assistant'
        && (row.clientId === normalizedPersistId || row.id === normalizedPersistId)));
  const itemBoundaryClientId = !finalReusesExistingItem && normalizedPersistId
    && previousStreamingClientId
    && !isGeneratedStreamingClientId(previousStreamingClientId)
    && previousStreamingClientId !== normalizedPersistId
    ? previousStreamingClientId
    : undefined;
  // A DB/history arrival alone cannot identify an anonymous stream. A final
  // carrying the same provider item from the same transport can, even when the
  // text is short or the authoritative final corrects it to a different prefix.
  const hasGeneratedStream = isGeneratedStreamingClientId(previousStreamingClientId);
  const agentMessageId = data ? readString(data, 'agentMessageId') : null;
  const source = readString(event, 'source');
  const generatedIdentity = generatedStreamAgentIdentities.get(sessionId);
  const finalIdentifiesGeneratedStream = hasGeneratedStream && isFinal && data?.isFullText === true
    && agentMessageId && generatedIdentity?.agentMessageId === agentMessageId
    && generatedIdentity.source === source && generatedIdentity.deviceId === deviceId;
  const clientIdResolution = finalReusesExistingItem && normalizedPersistId && !finalIdentifiesGeneratedStream
    ? { clientId: normalizedPersistId, changed: false }
    : streamingClientIdFor(sessionId, persistId);
  const { clientId } = clientIdResolution;
  if (!isFinal && isGeneratedStreamingClientId(clientId)) {
    if (!generatedStreamAgentIdentities.has(sessionId)) {
      generatedStreamAgentIdentities.set(sessionId, agentMessageId ? { agentMessageId, source, deviceId } : null);
    } else if (generatedIdentity && (generatedIdentity.agentMessageId !== agentMessageId
      || generatedIdentity.source !== source || generatedIdentity.deviceId !== deviceId)) {
      generatedStreamAgentIdentities.set(sessionId, null);
    }
  }
  const previousStreamingDeviceId = streamingAssistantDeviceId(sessionId, clientId);
  const currentAfterClientIdResolution = messages.get(sessionId) ?? [];
  const matchedExistingIndex = findMessageIndexByIdentity(currentAfterClientIdResolution, clientId);
  const matchedExisting = matchedExistingIndex >= 0
    ? currentAfterClientIdResolution[matchedExistingIndex]
    : undefined;
  const matchedHostAnchorIdentity = matchedExisting
    ? pendingHostAnchorIdentity(
        sessionId,
        matchedExisting.id,
        matchedExisting.clientId,
        clientId,
      )
    : undefined;
  const previousTransportWasSoftOffline = previousStreamingDeviceId !== undefined
    && matchedHostAnchorIdentity?.bindOnMetadata === false
    && matchedHostAnchorIdentity.deviceIds.has(previousStreamingDeviceId);
  const matchedExistingIsPending = matchedExisting !== undefined
    && isPendingLiveAssistantMessage(sessionId, matchedExisting);
  const matchedExistingIsPersisted = matchedExisting !== undefined
    && !matchedExistingIsPending
    && isPersistedAssistantMessage(matchedExisting);
  // A DB row is stronger than an earlier subscription snapshot still in flight.
  if (isFullText && matchedExistingIsPersisted) return clientIdResolution.changed;
  const rejectsNonAuthoritativeTransportReplay = deviceId !== undefined
    && authoritativeDeviceId !== undefined
    && deviceId !== authoritativeDeviceId
    && (
      matchedExistingIsPersisted
      || (
        previousStreamingDeviceId !== undefined
        && previousStreamingDeviceId !== deviceId
        && previousStreamingDeviceId === authoritativeDeviceId
        && !previousTransportWasSoftOffline
        && matchedExistingIsPending
      )
    );
  if (rejectsNonAuthoritativeTransportReplay) return clientIdResolution.changed;
  const itemBoundaryChanged = itemBoundaryClientId
    ? finalizeRemoteStreamingMessageByClientId(sessionId, itemBoundaryClientId)
    : false;
  const resetsTransportAssembly = previousStreamingDeviceId !== undefined
    && deviceId !== undefined
    && previousStreamingDeviceId !== deviceId
    && matchedExisting !== undefined
    && isPendingLiveAssistantMessage(sessionId, matchedExisting);
  const resetHostAnchorIdentity = resetsTransportAssembly
    ? pendingHostAnchorIdentity(
        sessionId,
        matchedExisting.id,
        matchedExisting.clientId,
        clientId,
      )
    : undefined;
  const existing = resetsTransportAssembly ? undefined : matchedExisting;
  const finalTextWasTruncated = isFinal && (
    hasDeviceLinkTruncationMarker(event) || hasDeviceLinkTruncationMarker(data)
  );
  if (isFinal && !existing) {
    // Device-clock stamp on a brand-new live row: anchor it to the newest known message,
    // or to host-domain session activity when the message window is still empty. Otherwise
    // an ahead device clock can dominate the first later host-persisted row.
    const hostCreatedAtAnchor = liveRowCreatedAtAnchor(sessionId);
    const createdAt = clampLiveRowCreatedAt(
      new Date().toISOString(),
      hostCreatedAtAnchor.createdAt,
    );
    const changed = upsertMessage(sessionId, {
      id: clientId,
      clientId,
      sessionId,
      role: 'assistant',
      content: text,
      toolUseId: null,
      agentMeta: isRecord(event.agentMeta) ? event.agentMeta : null,
      createdAt,
    });
    if (resetsTransportAssembly && !changed) {
      forgetPendingLiveAssistantMessageIdentity(
        sessionId,
        matchedExisting.id,
        matchedExisting.clientId,
        clientId,
      );
    }
    if (changed || resetsTransportAssembly) {
      rememberPendingLiveAssistantClientId(sessionId, clientId);
      if (hostCreatedAtAnchor.provisional || resetHostAnchorIdentity) {
        rememberPendingHostAnchorLiveAssistantClientId(
          sessionId,
          clientId,
          resetHostAnchorIdentity?.sendAt,
          resetHostAnchorIdentity?.bindOnMetadata ?? true,
          deviceId,
          resetHostAnchorIdentity?.unboundRoundId,
        );
      }
    }
    if (
      deviceId !== undefined
      && pendingLiveAssistantClientIds.get(sessionId)?.has(clientId) === true
    ) {
      rememberStreamingAssistantDeviceId(sessionId, clientId, deviceId);
    }
    return changed || clientIdResolution.changed || itemBoundaryChanged;
  }

  const currentText = existing ? contentToPreview(existing.content) : '';
  const nextText = isFinal
    ? (finalTextWasTruncated && existing
      ? currentText
      : data?.isFullText === true
        ? text
        : existing && currentText
        ? (text.startsWith(currentText)
          ? text
          : currentText.startsWith(text)
            ? currentText
            : `${currentText}${text}`)
        : text)
    : reconcileRemoteText(currentText, text, { snapshot: isFullText, durable: matchedExistingIsPersisted,
      truncated: hasDeviceLinkTruncationMarker(event) || hasDeviceLinkTruncationMarker(data) });
  const nextMeta = isFinal
    ? (isRecord(event.agentMeta)
      ? { ...(existing?.agentMeta ?? {}), ...event.agentMeta }
      : existing?.agentMeta ?? null)
    : streamingMeta(isRecord(event.agentMeta)
      ? { ...(existing?.agentMeta ?? {}), ...event.agentMeta }
      : existing?.agentMeta);
  const hostCreatedAtAnchor = existing ? undefined : liveRowCreatedAtAnchor(sessionId);
  const needsHostAnchor = snapshotCreatedAt ? false : existing
    ? [existing.id, existing.clientId, clientId].some((id) => (
      Boolean(id) && pendingHostAnchorLiveAssistantClientIds.get(sessionId)?.has(id) === true
    ))
    : hostCreatedAtAnchor?.provisional === true || resetHostAnchorIdentity !== undefined;
  const hostAnchorIdentity = existing
    ? pendingHostAnchorIdentity(sessionId, existing.id, existing.clientId, clientId)
    : resetHostAnchorIdentity;
  // A subscription snapshot knows the block's real host time. An earlier
  // provisional row may be anchored to old history, so repair its position too.
  const changesCreatedAt = snapshotCreatedAt !== undefined && snapshotCreatedAt !== existing?.createdAt;
  const changed = upsertMessage(sessionId, {
    id: existing?.id ?? clientId,
    clientId,
    sessionId,
    role: 'assistant',
    content: nextText,
    toolUseId: null,
    agentMeta: nextMeta,
    // Existing rows keep their already-stamped createdAt unchanged (it may already be a
    // clamped value from the first delta). Only a brand-new row's fresh device-clock stamp
    // needs the clamp — see clampLiveRowCreatedAt doc comment in messagePaging.ts.
    createdAt: snapshotCreatedAt ?? existing?.createdAt ?? clampLiveRowCreatedAt(
      new Date().toISOString(),
      hostCreatedAtAnchor?.createdAt,
    ),
  }, {
    knownIndex: matchedExistingIndex,
    preserveGeneratedStreamingFallback: Boolean(finalReusesExistingItem && hasGeneratedStream && !finalIdentifiesGeneratedStream),
    preserveOrderOnReplace: !changesCreatedAt,
    preserveStructureOnReplace: !isFinal && existing !== undefined && !changesCreatedAt,
  });
  if (resetsTransportAssembly && !changed) {
    forgetPendingLiveAssistantMessageIdentity(
      sessionId,
      matchedExisting.id,
      matchedExisting.clientId,
      clientId,
    );
  }
  if (changed || resetsTransportAssembly) {
    rememberPendingLiveAssistantClientId(sessionId, clientId);
  }
  if (snapshotCreatedAt) {
    // An identical snapshot can make upsert a no-op. Its authoritative time
    // still retires any provisional anchor, without retiring the live identity.
    const anchors = pendingHostAnchorLiveAssistantClientIds.get(sessionId);
    for (const id of [existing?.id, existing?.clientId, clientId]) {
      if (id) anchors?.delete(id);
    }
    if (anchors?.size === 0) pendingHostAnchorLiveAssistantClientIds.delete(sessionId);
  }
  // upsertMessage intentionally clears pending reconciliation identities when it
  // replaces an assistant row. A live delta/final is not host-authoritative, so
  // carry the provisional anchor forward until metadata or a persisted row lands.
  // Even an unchanged replay can add a second transport owner for the same identity.
  if (needsHostAnchor) {
    rememberPendingHostAnchorLiveAssistantClientId(
      sessionId,
      clientId,
      hostAnchorIdentity?.sendAt ?? latestUserSendAt(sessionId) ?? null,
      hostAnchorIdentity?.bindOnMetadata ?? true,
      deviceId,
      hostAnchorIdentity?.unboundRoundId,
    );
  }
  if (
    deviceId !== undefined
    && pendingLiveAssistantClientIds.get(sessionId)?.has(clientId) === true
  ) {
    rememberStreamingAssistantDeviceId(sessionId, clientId, deviceId);
  }
  return changed || clientIdResolution.changed || itemBoundaryChanged;
}

function isRemoteTextDeltaEvent(event: Record<string, unknown>): boolean {
  return isRemoteTextDelta(event);
}

function enqueueRemoteTextDelta(
  sessionId: string,
  event: Record<string, unknown>,
  persistId?: string,
  deviceId?: string,
): boolean {
  const data = isRecord(event.data) ? event.data : null;
  const text = typeof data?.text === 'string' ? data.text : '';
  if (!text) return false;

  let changed = false;
  const existing = pendingTextDeltaBatches.get(sessionId);
  if (
    existing
    && (
      (existing.persistId && persistId && existing.persistId !== persistId)
      || existing.deviceId !== deviceId
    )
  ) {
    changed = flushPendingTextDelta(sessionId);
  }
  const current = pendingTextDeltaBatches.get(sessionId);
  const incomingMeta = isRecord(event.agentMeta) ? event.agentMeta : null;
  const agentMessageId = data ? readString(data, 'agentMessageId') : null;
  const source = readString(event, 'source');
  if (current) {
    current.chunks.push(text);
    if (current.agentMessageId !== agentMessageId || current.source !== source) current.agentMessageId = null;
    if (incomingMeta) current.agentMeta = { ...(current.agentMeta ?? {}), ...incomingMeta };
    if (!current.persistId) current.persistId = persistId;
    if (current.deviceId === undefined) current.deviceId = deviceId;
  } else {
    pendingTextDeltaBatches.set(sessionId, {
      chunks: [text],
      persistId,
      deviceId,
      agentMeta: incomingMeta,
      agentMessageId,
      source,
    });
  }
  scheduleTextDeltaFlush(sessionId);
  return changed;
}

function flushPendingTextDelta(sessionId: string): boolean {
  const batch = pendingTextDeltaBatches.get(sessionId);
  if (!batch) return false;
  pendingTextDeltaBatches.delete(sessionId);
  if (pendingTextDeltaBatches.size === 0) clearTextDeltaFlushTimer();
  return applyRemoteTextEvent(
    sessionId,
    {
      type: 'text',
      data: { text: batch.chunks.join(''), isFinal: false, agentMessageId: batch.agentMessageId },
      ...(batch.source ? { source: batch.source } : {}),
      ...(batch.agentMeta ? { agentMeta: batch.agentMeta } : {}),
    },
    batch.persistId,
    batch.deviceId,
  );
}

function flushAndFinalizeRemoteStreamingMessages(
  sessionId: string,
  boundaryAgentMeta?: Record<string, unknown> | null,
): boolean {
  let changed = flushPendingTextDelta(sessionId);
  changed = finalizeRemoteStreamingMessages(sessionId, boundaryAgentMeta) || changed;
  return changed;
}

function hasLiveAssistantMessage(sessionId: string): boolean {
  return (messages.get(sessionId) ?? []).some((message) => (
    isPendingLiveAssistantMessage(sessionId, message)
  ));
}

function isPendingLiveAssistantMessage(
  sessionId: string,
  message: RemoteMessage,
): boolean {
  const pendingLiveIds = pendingLiveAssistantClientIds.get(sessionId);
  return message.role === 'assistant'
    && pendingLiveIds !== undefined
    && (pendingLiveIds.has(message.clientId) || pendingLiveIds.has(message.id));
}

function flushPendingTextDeltas(): void {
  let changed = false;
  for (const sessionId of [...pendingTextDeltaBatches.keys()]) {
    changed = flushPendingTextDelta(sessionId) || changed;
  }
  if (changed) emit();
}

function scheduleTextDeltaFlush(sessionId: string): void {
  const hasFlushedLiveAssistant = (pendingLiveAssistantClientIds.get(sessionId)?.size ?? 0) > 0;
  const delayMs = !hasFlushedLiveAssistant
    ? INITIAL_TEXT_DELTA_BATCH_INTERVAL_MS
    : sessionMessageLifecycle.isVisible(sessionId)
      ? VISIBLE_DETAIL_TEXT_DELTA_BATCH_INTERVAL_MS
      : BACKGROUND_TEXT_DELTA_BATCH_INTERVAL_MS;
  const deadlineAt = Date.now() + delayMs;
  if (
    textDeltaFlushTimer !== null
    && textDeltaFlushDeadlineAt !== null
    && textDeltaFlushDeadlineAt <= deadlineAt
  ) return;
  if (textDeltaFlushTimer !== null) clearTimeout(textDeltaFlushTimer);
  textDeltaFlushDeadlineAt = deadlineAt;
  textDeltaFlushTimer = setTimeout(() => {
    textDeltaFlushTimer = null;
    textDeltaFlushDeadlineAt = null;
    flushPendingTextDeltas();
  }, Math.max(0, deadlineAt - Date.now()));
}

function clearTextDeltaFlushTimer(): void {
  if (textDeltaFlushTimer === null) return;
  clearTimeout(textDeltaFlushTimer);
  textDeltaFlushTimer = null;
  textDeltaFlushDeadlineAt = null;
}

function discardPendingTextDelta(sessionId: string): void {
  pendingTextDeltaBatches.delete(sessionId);
  if (pendingTextDeltaBatches.size === 0) clearTextDeltaFlushTimer();
}

function finalizeRemoteStreamingMessageByClientId(
  sessionId: string,
  clientId: string,
): boolean {
  const existing = messages.get(sessionId);
  if (!existing) return false;
  let changed = false;
  const next = existing.map((message) => {
    if (
      message.role !== 'assistant'
      || message.agentMeta?.isStreaming !== true
      || (message.id !== clientId && message.clientId !== clientId)
    ) return message;
    changed = true;
    return { ...message, agentMeta: clearStreamingMeta(message.agentMeta) };
  });
  if (!changed) return false;
  const preview = messagePreviewCache.get(existing);
  if (preview) messagePreviewCache.set(next, preview);
  messages.set(sessionId, next);
  bumpMessageVersion(sessionId);
  return true;
}

function finalizeRemoteStreamingMessages(
  sessionId: string,
  boundaryAgentMeta?: Record<string, unknown> | null,
): boolean {
  clearStreamingAssistantPointer(sessionId);
  const existing = messages.get(sessionId);
  if (!existing) return false;
  let changed = false;
  const next = existing.map((message) => {
    if (message.role !== 'assistant' || message.agentMeta?.isStreaming !== true) return message;
    changed = true;
    // Match desktop persistence semantics: metadata already observed on the
    // streaming block wins, while metadata carried only by the boundary event
    // fills missing fields (parentUuid/uuid are needed for rewind/fork).
    const mergedMeta = boundaryAgentMeta
      ? { ...boundaryAgentMeta, ...(message.agentMeta ?? {}) }
      : message.agentMeta;
    return { ...message, agentMeta: clearStreamingMeta(mergedMeta) };
  });
  if (!changed) return false;
  const preview = messagePreviewCache.get(existing);
  if (preview) messagePreviewCache.set(next, preview);
  messages.set(sessionId, next);
  bumpMessageVersion(sessionId);
  return true;
}

function bumpMessageVersion(sessionId?: string): void {
  messageVersion += 1;
  if (sessionId === undefined) notifyAllMessagePreviewsPending = true;
  else pendingMessagePreviewSessionIds.add(sessionId);
}

// turn start 时暂存的 running codex collab worker 条目:map key → update。核心不变量是
// 「孤儿卡只渲染当前 maker turn 边界打开之后到达的 update(post-boundary evidence)」——
// 错过终态推送的 stale running 与活 worker 在数据上不可区分,任何按新鲜度/宽限的近似都
// 留有重放窗口。暂存条目不出现在 getSessionTaskUpdates(不渲染、inline 也不吃,inline 卡
// 状态由持久化的 tool_use/tool_result 自行推断);边界后收到同任务的新 update 即被召回参
// 与 merge(保住 title/description 等历史字段);到下一次 turn start 仍未被召回的直接丢弃
// (跨两个边界无任何存活证据)。live-only,随 removeDevice / clear 一起清。
const sessionParkedTaskUpdates = new Map<string, Map<string, AgentTaskUpdate>>();

// maker turn 边界 false→true 时的清扫:每个 turn 的 live task 状态从零开始。claude
// Task/Agent 子代理不跨 turn,残留即 stale,直接清;终态条目的 spawn tool_use / tool_result
// 已持久化,inline 渲染可接管,直接清;running codex collab worker(跑在独立会话、跨 turn
// 存活,update 推到主会话事件流——codex 的 agent_task_update 只由 collab:* 工具产生,见
// codex translator 的 handleCollabAgentToolCall)挪进暂存区等待 post-boundary 存活证据,
// 活 worker 的下一条 update 会立即召回它,卡片仅在边界到该条 update 之间短暂缺席。
function sweepStaleTaskUpdates(sessionId: string): boolean {
  // 上一轮暂存的条目到此作废:跨两个边界都没有等到任何新 update,判死。
  sessionParkedTaskUpdates.delete(sessionId);
  const map = sessionTaskUpdates.get(sessionId);
  if (!map || map.size === 0) return false;
  const parked = new Map<string, AgentTaskUpdate>();
  for (const [key, update] of map) {
    if (update.provider === 'codex' && update.status === 'running') parked.set(key, update);
  }
  if (parked.size > 0) sessionParkedTaskUpdates.set(sessionId, parked);
  sessionTaskUpdates.delete(sessionId);
  return true;
}

// 暂存召回:边界后到达的 update 是同任务仍存活的证据。把暂存里按 alias 匹配的历史条目
// 取回并入 prevMap,让 applyAgentTaskUpdateEvent 的 merge 吃到历史字段;未匹配的留在暂存。
function recallParkedTaskUpdates(
  sessionId: string,
  data: unknown,
  source: 'claude-code' | 'codex' | 'pi' | undefined,
  prevMap: ReadonlyMap<string, AgentTaskUpdate> | undefined,
): ReadonlyMap<string, AgentTaskUpdate> | undefined {
  const parkedMap = sessionParkedTaskUpdates.get(sessionId);
  if (!parkedMap || parkedMap.size === 0) return prevMap;
  const probe = normalizeAgentTaskUpdate(data, source);
  if (!probe) return prevMap;
  let recalled: Map<string, AgentTaskUpdate> | null = null;
  for (const [key, parked] of parkedMap) {
    if (!isSameAgentTaskAlias(parked, probe)) continue;
    if (!recalled) recalled = new Map(prevMap ?? []);
    recalled.set(key, parked);
    parkedMap.delete(key);
  }
  if (parkedMap.size === 0) sessionParkedTaskUpdates.delete(sessionId);
  return recalled ?? prevMap;
}

/**
 * `markDeviceOffline` / `markDevicesOffline` 共用的清扫主体:逐台执行离线清理,
 * 返回是否有任何投影变化。调用方负责决定 emit 一次(批量)还是逐台 emit。
 */
function sweepDevicesOffline(deviceIds: readonly string[]): boolean {
  let changed = false;
  const idSet = new Set(deviceIds);
  if (idSet.size === 0) return false;
  // A first text delta can still be waiting in the 32ms batch before any session
  // metadata/index exists. Flush batches from this transport first so they create a
  // device-owned host anchor, then freeze that identity before reconnect metadata can
  // bind it to a newer send round.
  for (const [sessionId, batch] of [...pendingTextDeltaBatches]) {
    if (batch.deviceId === undefined || !idSet.has(batch.deviceId)) continue;
    changed = flushAndFinalizeRemoteStreamingMessages(sessionId) || changed;
    changed = clearStreamingAssistantPointer(sessionId) || changed;
    changed = freezeUnboundPendingHostAnchorsForOffline(sessionId, batch.deviceId) || changed;
  }
  for (const [sessionId, indexedDeviceId] of sessionDeviceIndex) {
    if (!idSet.has(indexedDeviceId)) continue;
    if (sessionMessageSyncMarkers.delete(sessionId)) {
      bumpMessageVersion(sessionId);
      changed = true;
    }
    changed = livePlanSnapshots.delete(sessionId) || changed;
    changed = pendingRefreshSessions.delete(sessionId) || changed;
    changed = deletePendingInteractionState(sessionId) || changed;
    // 投影没了,这份(空)列表就不再权威:重连拿到全量快照前不许据此做清理。
    changed = pendingInteractionsAuthoritative.delete(sessionId) || changed;
    changed = invalidateInputProjectionForOffline(sessionId) || changed;
    bumpInputProjectionAuthorityEpoch(sessionId);
    changed = deleteSessionLiveActivity(sessionId) || changed;
    changed = sessionGoalStatus.delete(sessionId) || changed;
    changed = sessionTaskUpdates.delete(sessionId) || changed;
    changed = sessionParkedTaskUpdates.delete(sessionId) || changed;
    changed = sessionMakerActivityEpochs.delete(sessionId) || changed;
    changed = flushAndFinalizeRemoteStreamingMessages(sessionId) || changed;
    changed = clearStreamingAssistantPointer(sessionId) || changed;
    // The message window survives a soft offline transition, so both pending
    // identities must survive too: one protects the live row during latest-window
    // reconciliation, and the other lets a reconnecting authoritative user row
    // restore question → reply order. Persisted reconciliation, explicit window
    // invalidation, or actual device removal will retire them.
    changed = freezeUnboundPendingHostAnchorsForOffline(sessionId, indexedDeviceId) || changed;
    changed = writeMakerTurnRunning(sessionId, false) || changed;
    changed = writeSessionRunStatus(sessionId, EMPTY_SESSION_RUN_STATUS) || changed;
  }
  for (const [sessionId, pendingAnchors] of pendingHostAnchorLiveAssistantClientIds) {
    for (const identity of pendingAnchors.values()) {
      for (const deviceId of identity.deviceIds) {
        if (!idSet.has(deviceId)) continue;
        changed = freezeUnboundPendingHostAnchorsForOffline(sessionId, deviceId) || changed;
      }
    }
  }
  return changed;
}

function cleanupRemovedSession(deviceId: string, sessionId: string, deleted: boolean): void {
  protectedQuestions.delete(sessionId);
  visibleInteractionCache.delete(sessionId);
  void clearHistoryDisk(deviceId, sessionId);
  clearRemoteHistoryViews(deviceId, sessionId);
  deleteSessionLiveActivity(sessionId);
  dropPendingTitlePreview(sessionId);
  let messageStateChanged = invalidateSessionMessageWindowState(sessionId, false);
  messageStateChanged = releaseSessionDetailProjections(sessionId) || messageStateChanged;
  sessionMessageLifecycle.forget(sessionId);
  sessionsOpenedInDetail.delete(sessionId);
  if (deleted) clearSessionMessageCache(sessionId, deviceId);
  if (messageStateChanged) bumpMessageVersion(sessionId);
}

export const remoteSessionStore = {
  /** Coalesce notifications for one logically atomic remote snapshot. */
  batch<T>(work: () => T): T {
    return batch(work);
  },

  /**
   * 新建任务第一帧标题预览。只盖哨兵,权威标题一旦离开哨兵就让位。
   * 失败撤回走 {@link clearPendingTitlePreview}。
   */
  setPendingTitlePreview(sessionId: string, title: string): void {
    const next = title.trim();
    if (!sessionId || !next) return;
    if (pendingTitlePreview.get(sessionId) === next) return;
    pendingTitlePreview.set(sessionId, next);
    recomputeSessions();
  },

  clearPendingTitlePreview(sessionId: string): void {
    if (!sessionId || !pendingTitlePreview.has(sessionId)) return;
    dropPendingTitlePreview(sessionId);
    recomputeSessions();
  },

  /**
   * 读当前权威设备身份列表(setDeviceIdentity 注入的那份;未注入过为空)。
   * 会话页抽屉等在首页之外调 buildMobileHomePresentation 时传入,保证展示归一化
   * (canonicalDeviceId 认领)与首页/本 store 同一口径——不传 devices 的空列表会把
   * store 已算好的规范 id 覆盖成仅凭会话内嵌名字推出的弱结果(re-link 后路由错设备)。
   */
  getDeviceIdentity(): readonly { deviceId: string; name: string }[] {
    return deviceList ?? EMPTY_DEVICE_IDENTITY;
  },

  getConversationSearchDeviceModels(): readonly {
    canOpen: boolean;
    deviceId: string;
    name: string | null;
    state: string;
  }[] {
    return conversationSearchDeviceModels;
  },

  setConversationSearchDeviceModels(models: readonly {
    canOpen: boolean;
    deviceId: string;
    name: string | null;
    state: string;
  }[]): void {
    if (conversationSearchDeviceModelsEqual(conversationSearchDeviceModels, models)) return;
    conversationSearchDeviceModels = models.map((item) => ({
      canOpen: item.canOpen,
      deviceId: item.deviceId,
      name: item.name,
      state: item.state,
    }));
    emit();
  },

  getSessionRetention(sessionId: string): SessionRetentionKind {
    return retentionForSession(sessionId);
  },

  enterSessionMessageDetail(sessionId: string): SessionMessageAuthority {
    const retentionBefore = retentionForSession(sessionId);
    sessionsOpenedInDetail.add(sessionId);
    const authority = sessionMessageLifecycle.enter(sessionId);
    touchSessionAccess(sessionId);
    if (enforceRegularMessageBudget() || retentionBefore !== retentionForSession(sessionId)) {
      bumpMessageVersion();
      emit();
    }
    return authority;
  },

  leaveSessionMessageDetail(
    sessionId: string,
    reason: SessionMessageReclaimReason,
    authority?: SessionMessageAuthority | null,
  ): boolean {
    const left = sessionMessageLifecycle.leave(sessionId, reason, authority);
    if (left) {
      noteLiveStreamInterrupted(sessionId);
      discardPendingTextDelta(sessionId);
    }
    return left;
  },

  /**
   * rewind 等远端权威改写后,目标详情已不再拥有可证明正确的连续窗口。
   * 清内存与磁盘预览并登记一次刷新;页面可见时立即 load,隐藏时下次打开再拉。
   */
  invalidateSessionMessageWindow(sessionId: string, deviceId?: string): void {
    const removedDraft = protectedQuestions.delete(sessionId);
    visibleInteractionCache.delete(sessionId);
    void clearHistoryDisk(deviceId, sessionId);
    resetRemoteHistoryViews(deviceId, sessionId);
    const changed = invalidateSessionMessageWindowState(sessionId, true) || removedDraft;
    clearSessionMessageCache(sessionId, deviceId);
    if (changed) {
      bumpMessageVersion(sessionId);
      emit();
    }
  },

  captureSessionMessageAuthority(sessionId: string): SessionMessageAuthority {
    return sessionMessageLifecycle.capture(sessionId);
  },

  isSessionMessageAuthorityCurrent(authority: SessionMessageAuthority): boolean {
    return sessionMessageLifecycle.canCommit(authority);
  },

  isSessionMessageDetailVisible(sessionId: string): boolean {
    return sessionMessageLifecycle.isVisible(sessionId);
  },

  hasSessionMessageDetailEntered(sessionId: string): boolean {
    return sessionMessageLifecycle.hasEntered(sessionId);
  },

  captureUnenteredSessionMessageAuthority(sessionId: string): SessionMessageUnenteredAuthority {
    return sessionMessageLifecycle.captureUnentered(sessionId);
  },

  canCommitUnenteredSessionMessageWindow(
    authority: SessionMessageUnenteredAuthority,
    deviceId: string,
  ): boolean {
    return retentionForSession(authority.sessionId) === 'regular'
      && sessionDeviceIndex.get(authority.sessionId) === deviceId
      && sessionMessageLifecycle.canCommitUnentered(authority);
  },

  acquireSessionMessageWork(sessionId: string, active = false): SessionMessageWorkLease {
    return sessionMessageLifecycle.acquireWork(sessionId, active);
  },

  releaseSessionRuntimeState(
    sessionId: string,
    options: { reason: SessionMessageReclaimReason },
  ): boolean {
    if (!sessionId || sessionMessageLifecycle.isVisible(sessionId)) return true;
    if (sessionStoreProtected(sessionId, false)) return false;
    if (retentionForSession(sessionId) === 'schedule') {
      const changed = reclaimScheduleRuntimeMaps(sessionId);
      clearSessionMessageCache(sessionId);
      if (changed) {
        bumpMessageVersion(sessionId);
        emit();
      }
      return true;
    }

    const current = messages.get(sessionId);
    let changed = releaseSessionDetailProjections(sessionId);
    if (current && current.length > MESSAGE_PAGE_SIZE) {
      const compacted = trimMessageWindow(sessionId, current);
      if (!remoteMessageListsEqual(current, compacted)) {
        messages.set(sessionId, compacted);
        forgetWindowCoverage(sessionId);
        changed = true;
      }
    }
    changed = enforceRegularMessageBudget() || changed;
    if (changed) {
      bumpMessageVersion();
      emit();
    }
    void options.reason;
    return true;
  },

  // 注入当前权威设备列表(首页从 /api/device-link/devices reconcile 后调用),用于设备身份归一化。
  // 仅在身份索引实际变化时重算,避免每次设备列表引用变动都刷新全部会话。
  setDeviceIdentity(devices: readonly { deviceId: string; name: string }[]): void {
    if (deviceListsEqual(deviceList, devices)) return;
    deviceList = devices.map((d) => ({ deviceId: d.deviceId, name: d.name }));
    recomputeSessions();
  },

  setDeviceSessions(deviceId: string, deviceName: string, rawSessions: readonly RemoteSession[]): void {
    if (!sessionListRefreshSeen.has(deviceId) || sessionListRefreshArmed.has(deviceId)) {
      sessionListRefreshSeen.add(deviceId);
      sessionListRefreshArmed.delete(deviceId);
      for (const listener of sessionListRefreshListeners) listener(deviceId);
    }
    let nextSessions = rawSessions.map((s) => stamp(s, deviceId, deviceName));
    const existing = shards.get(deviceId);
    if (existing) {
      const localById = new Map(existing.sessions.map((session) => [session.id, session]));
      nextSessions = nextSessions.map((session) => preserveSessionRuntimeFields(
        session,
        localById.get(session.id),
      ));
    }
    // 在途乐观创建行保护:pendingLocalCreation 行由 newSessionCreation 管线负责生命
    // 周期(enqueue 落定清标 / 失败撤行),全量列表对账不能越权处置——(a) 比被控端
    // 建成更早发出的旧列表不含该 id,直接替换会让刚进入的会话从列表消失;(b) 建成后
    // enqueue 落定前的新列表含该 id 但无标,直接替换会提前解开禁发通道。缓存 hydrate
    // 白名单不含此标(mobileHomeListCache.coerceCachedSession),标只存在于本进程内存,
    // 不会出现「无管线接管的孤儿标」。
    const pendingRows = existing?.sessions.filter((s) => s.pendingLocalCreation === true) ?? [];
    if (pendingRows.length > 0) {
      const pendingIds = new Set(pendingRows.map((s) => s.id));
      const nextIds = new Set(nextSessions.map((s) => s.id));
      nextSessions = nextSessions.map((s) => (pendingIds.has(s.id) ? { ...s, pendingLocalCreation: true } : s));
      const missingRows = pendingRows.filter((s) => !nextIds.has(s.id));
      if (missingRows.length > 0) nextSessions = [...missingRows, ...nextSessions];
    }
    // 在途元数据写保护(review P1):重连触发的全量对账 / reseed 拉到的可能是被控端
    // 尚未处理本机写的旧快照,整表替换不得冲掉乐观意图——
    //  - 行仍在本地:在途字段用本地当前值覆盖快照值(其余字段照常吃快照);
    //  - 行已被本地乐观移出(归档/删除在途):不随旧快照复活,终态由该写的结局负责
    //    (失败回滚 upsert 插回 + reseed;成功后新快照自然无此行)。
    nextSessions = nextSessions.flatMap((s) => {
      const pendingFields = sessionPendingWrites.pendingFields(s.id);
      if (pendingFields.length === 0) return [s];
      const local = existing?.sessions.find((row) => row.id === s.id);
      if (!local) return [];
      const overlay: Record<string, unknown> = {};
      for (const field of pendingFields) {
        const localValue = (local as unknown as Record<string, unknown>)[field];
        overlay[field] = localValue;
        // overlay 藏起的权威快照值与 push 遮蔽同样可能是外部并发更新:差异留痕,
        // 由对应写的结局 consume 后 reseed 收敛(review P2)。
        sessionPendingWrites.noteMaskedValue(
          s.id,
          field,
          (s as unknown as Record<string, unknown>)[field],
          localValue,
        );
      }
      return [{ ...s, ...overlay } as RemoteSession];
    });
    // 对称保护(review P2):restore 在途把行乐观加回了当前列表,旧快照(被控端未
    // 处理该写)不含它——status 在途且本地有行、快照缺失时保留本地行,终态由该写
    // 的结局负责(成功后新快照自然包含;失败回滚还原 status,applySessionPatch 会
    // 把行移出)。其它字段在途的缺失行照常吃快照删除(外部删除是权威)。
    {
      const snapshotIds = new Set(nextSessions.map((s) => s.id));
      const pendingStatusRows = (existing?.sessions ?? []).filter((row) =>
        !snapshotIds.has(row.id) && (sessionPendingWrites.pendingFields(row.id).includes('status')
          // These details are deliberately omitted from the host's ordinary task list.
          || (row.source === 'side-chat' && (row.status === 'active' || row.status === 'archived'))));
      if (pendingStatusRows.length > 0) nextSessions = [...pendingStatusRows, ...nextSessions];
    }
    if (
      existing
      && existing.deviceName === deviceName
      && remoteSessionListsEqual(existing.sessions, nextSessions)
    ) {
      return;
    }
    shards.set(deviceId, { deviceId, deviceName, sessions: nextSessions });
    recomputeSessions();
  },

  // 单条详情/发件箱恢复不代表整份首页列表已经加载。首轮列表尚未到达时,缓存可以
  // 补齐缺失行,但已有行始终优先。收到列表或列表变更后不再种入旧快照(含权威空列表、
  // 归档/删除与设备移除),复用现有列表刷新记录和 mutation fence。
  hydrateDeviceSessionsIfEmpty(deviceId: string, deviceName: string, rawSessions: readonly RemoteSession[]): void {
    if (!deviceId || rawSessions.length === 0 || sessionListRefreshSeen.has(deviceId)
      || deviceSessionListMutationEpochs.has(deviceId)) return;
    const existing = shards.get(deviceId);
    const existingIds = new Set(existing?.sessions.map((session) => session.id));
    const missing = rawSessions.filter((session) => !existingIds.has(session.id)
      && sessionPendingWrites.pendingFields(session.id).length === 0);
    if (missing.length === 0) return;
    const currentDeviceName = existing?.deviceName ?? deviceName;
    shards.set(deviceId, {
      deviceId,
      deviceName: currentDeviceName,
      // cacheSeeded 打标:缓存行字段经瘦身/截断(240 字符),只能撑首屏渲染与跳转,
      // 不能作为发送参数;会话页据此在 fresh 元数据到达前禁发(codex review R15)。
      // fresh 路径(setDeviceSessions / upsertDeviceSession)用服务器新对象,天然无标自净。
      sessions: [...(existing?.sessions ?? []), ...missing.map((s) =>
        stamp({ ...s, cacheSeeded: true }, deviceId, currentDeviceName))],
    });
    recomputeSessions();
  },

  upsertDeviceSession(deviceId: string, deviceName: string, rawSession: RemoteSession): void {
    let stamped = stamp(rawSession, deviceId, deviceName);
    const shard = shards.get(deviceId);
    const existing = shard?.sessions.find((s) => s.id === rawSession.id);
    // 在途元数据写保护(与 setDeviceSessions 同口径):单条读回(会话页 getSession、资源页、
    // 发件箱回包)可能是被控端尚未处理本机写的旧值——
    //  - 行已被本地乐观移出且 status 在途(归档/删除):不插回,终态由该写的结局负责;
    //  - 行仍在本地:在途字段用本地当前值覆盖,差异留痕由该写的结局 consume 后 reseed。
    // 写失败的整行回滚必须先 release 自己的在途登记再 upsert,否则会被这里当成旧读回挡掉。
    const pendingFields = sessionPendingWrites.pendingFields(rawSession.id);
    if (pendingFields.length > 0) {
      if (!existing) {
        if (pendingFields.includes('status')) return;
      } else {
        const overlay: Record<string, unknown> = {};
        for (const field of pendingFields) {
          const localValue = (existing as unknown as Record<string, unknown>)[field];
          overlay[field] = localValue;
          sessionPendingWrites.noteMaskedValue(
            rawSession.id,
            field,
            (stamped as unknown as Record<string, unknown>)[field],
            localValue,
          );
        }
        stamped = { ...stamped, ...overlay } as RemoteSession;
      }
    }
    if (!shard) {
      shards.set(deviceId, { deviceId, deviceName, sessions: [stamped] });
      recomputeSessions();
      return;
    }
    const next = shard.sessions.filter((s) => s.id !== rawSession.id);
    stamped = preserveSessionRuntimeFields(stamped, existing);
    if (
      existing
      && shard.deviceName === deviceName
      && remoteSessionEqual(existing, stamped)
      && shard.sessions[0]?.id === rawSession.id
    ) {
      return;
    }
    shard.deviceName = deviceName;
    shard.sessions = [stamped, ...next];
    recomputeSessions();
  },

  renameDevice(deviceId: string, deviceName: string): void {
    const shard = shards.get(deviceId);
    if (!shard || shard.deviceName === deviceName) return;
    shard.deviceName = deviceName;
    shard.sessions = shard.sessions.map((session) => stamp(session, deviceId, deviceName));
    recomputeSessions();
  },

  /** Hide only the list projection; release never restores an old metadata snapshot. */
  beginSessionListRemovalPreview(sessionId: string): () => void {
    const release = sessionListRemovalPreviews.track(sessionId, ['status']);
    const refresh = () => {
      reconcileVisibleSessions();
      reconcileHomeSessions();
      emit();
    };
    refresh();
    return () => { release(); refresh(); };
  },

  applySessionPatch(deviceId: string, sessionId: string, patch: Partial<RemoteSession>): void {
    // Local optimistic removals must fence a late startup cache just like remote pushes,
    // even when the removed row has not reached this shard yet.
    if (patch.status === 'deleted' || patch.status === 'archived') bumpDeviceSessionListMutationEpoch(deviceId);
    const shard = shards.get(deviceId);
    const idx = shard?.sessions.findIndex((s) => s.id === sessionId) ?? -1;
    if (!shard || idx === -1) {
      if (patch.status === 'deleted' || patch.status === 'archived') {
        sessionRemovalListeners.forEach(listener => listener(deviceId, sessionId));
      }
      // Separate host-owned lists can include children never opened in this mirror.
      // Terminal changes invalidate those lists just as unseen creations do.
      if (patch.status === 'active' || patch.status === 'deleted' || patch.status === 'archived') {
        reseedHandlers.get(deviceId)?.forEach((handler) => handler());
      }
      return;
    }
    let shouldReseedAfterPatch = false;
    const turnEnded = historyTurnEnded(shard.sessions[idx], patch);
    if (patch.status === 'deleted' || patch.status === 'archived') {
      shard.sessions = shard.sessions.filter((s) => s.id !== sessionId);
      cleanupRemovedSession(deviceId, sessionId, patch.status === 'deleted');
    } else {
      const wasPinned = shard.sessions[idx].pinnedAt != null;
      const unpinned = Object.prototype.hasOwnProperty.call(patch, 'pinnedAt') && patch.pinnedAt == null;
      const patched = preserveSessionRuntimeFields(
        { ...shard.sessions[idx], ...patch } as RemoteSession,
        shard.sessions[idx],
      );
      if (remoteSessionEqual(shard.sessions[idx], patched)) return;
      shard.sessions = shard.sessions.map((s) => (s.id === sessionId ? patched : s));
      if (Object.keys(patch).every((key) => SESSION_USAGE_FIELDS.has(key))) {
        // Usage cannot change routing, retention, previews, grouping or unread.
        // Preserve the canonical shard winner and notify detail selectors only.
        if (sessionDeviceIndex.get(sessionId) === deviceId) {
          mergedSessions = mergedSessions.map((session) => {
            if (session.id !== sessionId) return session;
            const updated = { ...session, ...patch };
            mergedSessionById.set(sessionId, updated);
            return updated;
          });
          reconcileVisibleSessions();
        }
        emit();
        return;
      }
      if (Object.keys(patch).every((key) => SESSION_METADATA_FIELDS.has(key))) {
        const previous = mergedSessionById.get(sessionId);
        if (previous && sessionDeviceIndex.get(sessionId) === deviceId) {
          const updated = applyPendingTitlePreview({ ...patched, canonicalDeviceId: previous.canonicalDeviceId });
          if (!remoteSessionEqual(previous, updated)) {
            mergedSessions = mergedSessions.map((session) => session.id === sessionId ? updated : session);
            mergedSessionById.set(sessionId, updated);
            pendingMessagePreviewSessionIds.add(sessionId);
            reconcileVisibleSessions();
            reconcileHomeSessions();
          }
          bindPendingHostAnchorSendAt(sessionId, updated.userSendAt);
          if (reanchorPendingLiveAssistantRows(sessionId,
            updated.userSendAt ?? updated.updatedAt ?? updated.createdAt, { consumePending: false })) {
            bumpMessageVersion();
          }
        }
        emit();
        return;
      }
      shouldReseedAfterPatch = wasPinned && unpinned;
    }
    recomputeSessions();
    if (patch.status === 'deleted' || patch.status === 'archived') {
      sessionRemovalListeners.forEach(listener => listener(deviceId, sessionId));
    }
    if (turnEnded && patch.status !== 'deleted' && patch.status !== 'archived') {
      for (const listener of sessionListRefreshListeners) listener(deviceId, sessionId);
    }
    if (shouldReseedAfterPatch) this.requestReseed(deviceId);
  },

  setMessages(
    sessionId: string,
    list: readonly RemoteMessage[],
    options: SessionMessageWriteOptions = {},
  ): void {
    if (!messageWriteAllowed(sessionId, options.authority)) return;
    const textFlushed = flushPendingTextDelta(sessionId);
    const next = normalizeWindowForRetention(sessionId, normalizeMessages(list));
    const projectionSettled = settleInputProjectionFromMessages(sessionId, next);
    // 记账在相等早退**之前**:这一页是服务端一次给出的连续段,它带来的连续性结论与"窗口内容有没有
    // 变"无关。冷开缓存恰好与服务端最新页逐行相同时(常态)若被早退跳过,这次权威响应就白来了 ——
    // 之后会话涨过一页、再遇一次满页重连刷新,本可保留的历史会被当成来源不明全丢(#1210 review)。
    coverReplacedWindow(sessionId, next);
    if (next.length === 0) clearSessionMessageCache(sessionId);
    if (remoteMessageListsEqual(messages.get(sessionId) ?? emptyMessages, next)) {
      if (textFlushed || projectionSettled) emit();
      return;
    }
    messages.set(sessionId, next);
    applyMessageWriteRetention(sessionId);
    bumpMessageVersion(sessionId);
    emit();
  },

  // 乐观 hydrate:仅当该会话当前还没有任何消息时,用本地缓存(冷开预览)种入。
  // 「if empty」是关键不变量——fresh 数据若已先到则不覆盖;fresh 之后到也会按 messageKey 对账替换。
  hydrateMessagesIfEmpty(
    sessionId: string,
    list: readonly RemoteMessage[],
    options: SessionMessageWriteOptions = {},
  ): void {
    // schedule 从不读取长期完整消息缓存,即使当前详情可见也不例外。
    if (retentionForSession(sessionId) === 'schedule') return;
    if (!messageWriteAllowed(sessionId, options.authority)) return;
    const textFlushed = flushPendingTextDelta(sessionId);
    const existing = messages.get(sessionId) ?? [];
    const listKeys = listMessageKeys.get(sessionId);
    listMessageKeys.delete(sessionId);
    const listOnly = existing.length > 0 && !!listKeys
      && existing.every((message) => listKeys.has(messageKey(message)));
    if (existing.length > 0 && !listOnly) {
      if (textFlushed) emit();
      return;
    }
    const existingKeys = new Set(existing.map(messageKey));
    const next = normalizeMessages([...list.filter((message) => !existingKeys.has(messageKey(message))), ...existing]);
    if (next.length === 0) {
      if (textFlushed) emit();
      return;
    }
    messages.set(sessionId, next);
    applyMessageWriteRetention(sessionId);
    bumpMessageVersion(sessionId);
    emit();
  },

  /**
   * 这一页最新窗口是否值得先往前补读:满页、窗口里有已验证连续段,但本页最旧行晚于该段上界 ——
   * 直接提交时 `joinableWindowCoverage` 判不相接,`setLatestMessageWindow` 会丢掉整段旧历史。
   * 补读到本页最旧行不晚于上界后就能相接(区间内的事实自检仍由提交时判定)。schedule 窗口本就
   * 按条数裁剪,不补读。
   */
  latestMessageWindowNeedsBridge(
    sessionId: string,
    list: readonly RemoteMessage[],
    moreBeyondWindow: boolean,
  ): boolean {
    if (!moreBeyondWindow || retentionForSession(sessionId) === 'schedule') return false;
    if ((messages.get(sessionId) ?? []).length === 0) return false;
    const coverage = sessionWindowCoverage.get(sessionId);
    const pageOldest = oldestCreatedAt(list);
    return coverage !== undefined
      && pageOldest !== undefined
      && pageOldest.localeCompare(coverage.until) > 0;
  },

  setLatestMessageWindow(
    sessionId: string,
    list: readonly RemoteMessage[],
    options: SetLatestMessageWindowOptions = {},
  ): boolean {
    if (!messageWriteAllowed(sessionId, options.authority)) return false;
    const textFlushed = flushPendingTextDelta(sessionId);
    const latestWindow = normalizeWindowForRetention(sessionId, normalizeMessages(list));
    const projectionSettled = settleInputProjectionFromMessages(sessionId, latestWindow);
    if (latestWindow.length === 0) {
      // 空窗口仍需保留本地系统卡(mobile-system-*):新会话首条消息发出后服务端
      // 消息列表可能仍为空,下一次 setLatestMessageWindow 传空数组不能把刚追加的
      // 本地卡擦掉。
      const existing = messages.get(sessionId) ?? [];
      // A live assistant row is not yet represented in the DB window. Do not erase it
      // while the persistence push is still in flight.
      if (hasLiveAssistantMessage(sessionId)) {
        if (textFlushed || projectionSettled) emit();
        return false;
      }
      const preserved = existing.filter((item) => messageKey(item).startsWith('mobile-system-'));
      const next = preserved.length > 0 ? preserved : [];
      if (!remoteMessageListsEqual(existing, next)) {
        // 服务端行被清空(只余本地卡):旧覆盖区间连同它背书的那些行一起没了,不能留着背书。
        forgetWindowCoverage(sessionId);
        messages.set(sessionId, next);
        applyMessageWriteRetention(sessionId);
        if (next.length === 0) clearSessionMessageCache(sessionId);
        bumpMessageVersion(sessionId);
        emit();
      } else if (textFlushed || projectionSettled) {
        emit();
      }
      return true;
    }

    const latestOldestCreatedAt = latestWindow[0].createdAt;
    const latestNewestCreatedAt = latestWindow[latestWindow.length - 1].createdAt;
    const currentCoverage = sessionWindowCoverage.get(sessionId);
    if (currentCoverage && latestNewestCreatedAt.localeCompare(currentCoverage.since) < 0) {
      // Concurrent latest reads (detail + reconnect) can finish in reverse order.
      // An entirely older page cannot describe the current tail. Joining it to
      // retained newer rows, then trusting live pushes, would certify the gap.
      // Rewind/clear invalidates coverage explicitly, so it does not use this path.
      if (textFlushed || projectionSettled) emit();
      return false;
    }
    // A triggering user row must be inserted before its live assistant reply is
    // tied to the same host timestamp. Other authoritative tail rows keep the
    // existing live-before-persisted arrival order when their timestamps tie.
    const latestTailMessage = latestWindow[latestWindow.length - 1];
    const latestTailIsUser = latestTailMessage.role === 'user';
    const latestSendAt = latestUserSendAt(sessionId);
    const latestTailMatchesSend = userMessageMatchesLatestSend(sessionId, latestTailMessage);
    const latestTailIsKnownStaleUser = latestTailIsUser
      && latestSendAt !== undefined
      && !latestTailMatchesSend;
    const reanchorAfterMerge = latestTailIsUser && !latestTailIsKnownStaleUser;
    // A latest-window request may have started before the current send. Only a user tail
    // at/after the session's send marker may move or finish this pending identity; an older
    // user tail belongs to a previous round and leaves the current reply untouched.
    const consumeReanchorAfterMerge = reanchorAfterMerge && latestTailMatchesSend;
    const reanchorAfterMessages = consumeReanchorAfterMerge
      ? latestWindow.filter((message) => message.role === 'user')
      : undefined;
    const liveRowsReanchoredBeforeMerge = !reanchorAfterMerge
      && !latestTailIsKnownStaleUser
      && reanchorPendingLiveAssistantRows(
        sessionId,
        latestNewestCreatedAt,
        { consumePending: false },
      );
    const existing = messages.get(sessionId) ?? [];
    const existingIdentityIndex = buildMessageIdentityIndex(existing);
    const hasOverlap = latestWindow.some((item) => messageIdentityIndexHas(existingIdentityIndex, item));
    const byKey = new Map<string, RemoteMessage>();
    // 截断保护的比较基准必须覆盖全部 existing 行:下面的循环只把窗口外(更新/更旧)
    // 的行 seed 进 byKey,窗口内重叠的完整行若不在基准里,payload 超限的窗口刷新
    // (remoteContentTruncated)会拿 undefined 比较而照样覆盖它们。
    const existingByKey = new Map(existing.map((item) => [messageKey(item), item] as const));

    // A latest-page sync is authoritative for the tail of the conversation.
    // Only keep older cached pages when they overlap that page; otherwise stale
    // old windows can be rendered as if they were adjacent to fresh pushes.
    //
    // 「有交集」这个判据不足以保证**连续**:交集只说明两段有共同的行,不排除更早那一段与本页
    // 之间还隔着服务端仍有、本地从未加载的行。于是窗口会留下"首段 + 尾段"的孤岛,中间几百行
    // 缺失(手机端实测:整场会话的 6 轮对话在界面上凭空消失)。
    //
    // `moreBeyondWindow` 是调用方给的结构信号:本页是满页、或被 device-link 裁过行 —— 两者都
    // 意味着**本页上沿之外服务端还有历史**。这时任何早于本页最旧行的缓存段都无法确认与本页
    // 相接,一律丢弃,窗口于是始终是"某点 → 最新"的连续区间。代价是用户可见的历史变少(丢掉的
    // 是不可信的那一段),「加载更早」入口仍在、可以按连续分页重新取回。
    //
    // 反之本页不满页时,服务端从会话起点到最新已经全给了,不存在中间缺口,旧段照原判据保留。
    //
    // 为什么不靠时间阈值判断空洞:那只能发现"两侧间隔很久"的孤岛。断连期间漏收几十上百条、
    // 而它们在半小时内快速产生时(一个长 turn 里的连续工具调用就是),两侧间隔根本不大,检测不到
    // (#1222)。从源头保证连续区间才覆盖得住。
    //
    // 例外(#1210 review):已验证连续的历史(整窗替换的那页、用户一路「加载更早」翻出来的、订阅
    // 未断时收到的实时 push)与本页确实相接 —— 它由 `sessionWindowCoverage` 的覆盖区间标出。把这种
    // 段也丢掉会让用户正在看的历史与滚动锚点凭空消失,而且补齐不会拉回它(裁完已无内部跳变可
    // 发现)。所以判据是"在已验证覆盖区间内、且本页与该区间首尾相接 → 保留;否则才按
    // moreBeyondWindow 处置"。
    const keepUnverifiedOlderPages = hasOverlap && options.moreBeyondWindow !== true;
    // 相接与否是一次判断,保留判据与下面的记账共用它:两处分开算迟早会让区间与窗口对不上。
    const joinedCoverage = joinableWindowCoverage(
      sessionId,
      existingIdentityIndex,
      latestWindow,
      latestOldestCreatedAt,
    );
    for (const item of existing) {
      const createdAt = item.createdAt;
      const isNewerThanLatestPage = createdAt.localeCompare(latestNewestCreatedAt) >= 0;
      const isVerifiedContiguous = joinedCoverage !== undefined
        && createdAt.localeCompare(joinedCoverage.since) >= 0;
      const isOlderLoadedPage = createdAt.localeCompare(latestOldestCreatedAt) < 0
        && (isVerifiedContiguous || keepUnverifiedOlderPages);
      // 本地系统卡(/learn、/context 等)没有服务端对应行:不管时序落在窗口哪里都
      // 不会出现在 latestKeys 里,若不单独保留会被 window 刷新时静默丢弃。
      const isLocalSystemCard = messageKey(item).startsWith('mobile-system-');
      const isPendingLiveAssistant = isPendingLiveAssistantMessage(sessionId, item);
      if (
        isNewerThanLatestPage
        || isOlderLoadedPage
        || isLocalSystemCard
        || isPendingLiveAssistant
      ) {
        byKey.set(messageKey(item), item);
      }
    }
    for (const rawItem of latestWindow) {
      const item = overlayLivePlanSnapshot(sessionId, rawItem);
      if (isPersistedAssistantMessage(item)) {
        const fallbackIndex = findPendingGeneratedStreamingFallbackIndex(sessionId, existing);
        const fallback = fallbackIndex >= 0 ? existing[fallbackIndex] : undefined;
        const priorIdentities = generatedStreamPriorIdentities.get(sessionId);
        const knownSeparateIdentity = priorIdentities?.has(item.id) === true
          || (item.clientId ? priorIdentities?.has(item.clientId) === true : false)
          || messageIdentityIndexHas(existingIdentityIndex, item);
        if (fallback && !knownSeparateIdentity && generatedFallbackMatchesPersistedMessage(fallback, item)) {
          // History sync may be the first place the authoritative DB identity
          // arrives. Remove the generated key before inserting the persisted row;
          // otherwise the newer temporary row is kept as a tail and the DB row
          // becomes a duplicate assistant bubble.
          byKey.delete(messageKey(fallback));
          const directKey = messageKey(item);
          const existingMatch = byKey.get(directKey) ?? findMessageByIdentity(existing, item);
          byKey.set(directKey, preferCompleteMessage(existingMatch, item));
          forgetPendingLiveAssistantMessageIdentity(
            sessionId,
            fallback.id,
            fallback.clientId,
            item.id,
            item.clientId,
          );
          retireGeneratedStreamingFallback(sessionId);
          continue;
        }
      }
      if (isPersistedAssistantMessage(item)) excludeFromGeneratedStream(sessionId, item.id, item.clientId);
      const directKey = messageKey(item);
      const identityKey = findMessageMergeKey(byKey, item);
      const key = identityKey ?? directKey;
      const existingMatch = byKey.get(key)
        ?? existingByKey.get(directKey)
        ?? findMessageByIdentity(existing, item);
      byKey.set(key, preferCompleteMessage(existingMatch, item));
      if (item.role === 'assistant') {
        forgetPendingLiveAssistantMessageIdentity(
          sessionId,
          key,
          existingMatch?.id,
          existingMatch?.clientId,
          item.id,
          item.clientId,
        );
      }
    }

    const next = normalizeWindowForRetention(sessionId, normalizeMessages([...byKey.values()]));
    // 记账在相等早退**之前**(同 setMessages):这一页是服务端一次给出的连续段,它带来的结论与
    // "窗口内容有没有变"无关。被早退跳过时这次权威响应就白来了(#1210 review)。
    coverLatestPage(sessionId, latestOldestCreatedAt, latestNewestCreatedAt, joinedCoverage);
    if (remoteMessageListsEqual(existing, next)) {
      const liveRowsReanchoredAfterMerge = reanchorAfterMerge
        && reanchorPendingLiveAssistantRows(
          sessionId,
          latestNewestCreatedAt,
          {
            afterMessage: consumeReanchorAfterMerge ? undefined : latestTailMessage,
            afterMessages: reanchorAfterMessages,
            afterMessagesStartIsComplete: options.moreBeyondWindow !== true,
            consumePending: consumeReanchorAfterMerge,
          },
        );
      if (liveRowsReanchoredBeforeMerge || liveRowsReanchoredAfterMerge) bumpMessageVersion(sessionId);
      if (textFlushed || liveRowsReanchoredBeforeMerge || liveRowsReanchoredAfterMerge) emit();
      return true;
    }
    messages.set(sessionId, next);
    if (reanchorAfterMerge) {
      reanchorPendingLiveAssistantRows(
        sessionId,
        latestNewestCreatedAt,
        {
          afterMessage: consumeReanchorAfterMerge ? undefined : latestTailMessage,
          afterMessages: reanchorAfterMessages,
          afterMessagesStartIsComplete: options.moreBeyondWindow !== true,
          consumePending: consumeReanchorAfterMerge,
        },
      );
    }
    applyMessageWriteRetention(sessionId);
    bumpMessageVersion(sessionId);
    emit();
    return true;
  },

  markSessionMessagesSynced(sessionId: string, session: Pick<RemoteSession, '_count' | 'updatedAt' | 'preview'>): void {
    if (!sessionId) return;
    if (this.isSessionMessageWindowSynced(sessionId, session)
      && sessionMessageSyncMarkers.get(sessionId)?.preview === session.preview) return;
    sessionMessageSyncMarkers.set(sessionId, buildSessionMessageSyncMarker(session));
    bumpMessageVersion(sessionId);
    emit();
  },

  isSessionMessageWindowSynced(sessionId: string, session: Pick<RemoteSession, '_count' | 'updatedAt'>): boolean {
    const marker = sessionMessageSyncMarkers.get(sessionId);
    if (!marker) return false;
    return sessionMessageSyncMarkersEqual(marker, buildSessionMessageSyncMarker(session));
  },

  /** session 页面检测自身是否需要整窗刷新(收到 error-persisted 但消息未被清空)。 */
  hasPendingRefresh(sessionId: string): boolean {
    return pendingRefreshSessions.has(sessionId);
  },

  /** 消费 pending refresh 标记,返回 true 表示确实有待刷新,由调用方触发 load()。 */
  consumePendingRefresh(sessionId: string): boolean {
    if (!pendingRefreshSessions.has(sessionId)) return false;
    pendingRefreshSessions.delete(sessionId);
    // A history read already in flight when the dirty push arrived may have
    // reinstalled its older marker. The queued repair must still read history.
    if (sessionMessageSyncMarkers.delete(sessionId)) {
      bumpMessageVersion(sessionId);
      emit();
    }
    return true;
  },

  mergeMessages(
    sessionId: string,
    list: readonly RemoteMessage[],
    options: SessionMessageWriteOptions = {},
  ): void {
    if (!messageWriteAllowed(sessionId, options.authority)) return;
    const textFlushed = flushPendingTextDelta(sessionId);
    const projectionSettled = settleInputProjectionFromMessages(sessionId, list);
    const byKey = new Map<string, RemoteMessage>();
    for (const item of messages.get(sessionId) ?? []) {
      byKey.set(messageKey(item), item);
    }
    for (const rawItem of list) {
      const item = overlayLivePlanSnapshot(sessionId, rawItem);
      const identityKey = findMessageMergeKey(byKey, item);
      const key = identityKey ?? messageKey(item);
      const existingMatch = byKey.get(key);
      byKey.set(key, preferCompleteMessage(existingMatch, item));
      if (item.role === 'assistant') {
        forgetPendingLiveAssistantMessageIdentity(
          sessionId,
          key,
          existingMatch?.id,
          existingMatch?.clientId,
          item.id,
          item.clientId,
        );
      }
    }
    const next = normalizeWindowForRetention(sessionId, normalizeMessages([...byKey.values()]));
    if (remoteMessageListsEqual(messages.get(sessionId) ?? emptyMessages, next)) {
      if (textFlushed || projectionSettled) emit();
      return;
    }
    messages.set(sessionId, next);
    applyMessageWriteRetention(sessionId);
    bumpMessageVersion(sessionId);
    emit();
  },

  /**
   * 「加载更早」拉回的一页:沿 `before` 游标**从窗口最旧端连续**往前取,所以它与既有窗口相接。
   *
   * 与 `mergeMessages` 的唯一差别是它会把「已验证连续」覆盖区间的下界前移到这一页的最旧行
   * (见 `sessionWindowCoverage`):这样后续满页的最新窗口同步就不会把用户一路翻出来的历史
   * 当成来源不明的缓存丢掉(#1210 review 实测到的回归)。
   *
   * 只有真正沿窗口最旧端连续翻页的调用方可以用它;补内部空洞请继续用 `mergeMessages`。
   */
  mergeEarlierMessages(
    sessionId: string,
    list: readonly RemoteMessage[],
    options: SessionMessageWriteOptions & { before?: string } = {},
  ): boolean {
    if (retentionForSession(sessionId) === 'schedule') return false;
    if (!messageWriteAllowed(sessionId, options.authority)) return false;
    const current = messages.get(sessionId) ?? emptyMessages;
    const anchor = options.before ? current.find((row) => row.id === options.before) : undefined;
    // A latest-window refresh can remove the request's anchor without changing
    // detail authority. Joining that old page to the NEW oldest row invents a
    // contiguous interval across missing history. Let the caller retry from the
    // current window instead, and do not let a stale empty page close pagination.
    if (options.before && !anchor) return false;
    // 合并前窗口的最旧行 = 这一页接上的那一行,尚无结论时它就是区间上界(见 coverEarlierPage)。
    const joinsAt = anchor?.createdAt ?? oldestCreatedAt(current);
    this.mergeMessages(sessionId, list, options);
    const pageOldest = oldestCreatedAt(list);
    if (pageOldest) coverEarlierPage(sessionId, pageOldest, joinsAt);
    return true;
  },

  appendMessage(
    sessionId: string,
    message: RemoteMessage,
    options: SessionMessageWriteOptions = {},
  ): void {
    if (!options.listMessage && !messageWriteAllowed(sessionId, options.authority)) return;
    let changed = flushPendingTextDelta(sessionId);
    changed = settleInputProjectionFromMessages(sessionId, [message]) || changed;
    const reanchorAfterMessage = options.hostTimeAuthoritative !== false && message.role === 'user';
    const userCanReanchorPendingLiveReply = reanchorAfterMessage
      && userMessageCanConsumePendingLiveReply(sessionId, message);
    if (
      options.hostTimeAuthoritative !== false
      && !reanchorAfterMessage
      && reanchorPendingLiveAssistantRows(
        sessionId,
        message.createdAt,
        { consumePending: false },
      )
    ) {
      bumpMessageVersion(sessionId);
      changed = true;
    }
    changed = upsertMessage(
      sessionId,
      overlayLivePlanSnapshot(sessionId, message),
      { retirePendingAssistantIdentityOnEqual: options.hostTimeAuthoritative !== false },
    ) || changed;
    if (
      userCanReanchorPendingLiveReply
      && reanchorPendingLiveAssistantRows(
        sessionId,
        message.createdAt,
        {
          afterMessage: message,
          consumePending: true,
          pairPendingFromEnd: latestUserSendAt(sessionId) !== undefined,
        },
      )
    ) {
      bumpMessageVersion(sessionId);
      changed = true;
    }
    // 订阅内到达的实时行可以把覆盖区间的上界往后推;断流后收到的不行(见 liveTailTrusted)。
    coverLiveRow(sessionId, message);
    if (changed) {
      applyMessageWriteRetention(sessionId);
      emit();
    }
    if (options.listMessage) retainListMessageKeys(sessionId, messageKey(message));
  },

  /**
   * 该会话的实时流订阅已被远端 ACK。只影响**此后**落库的权威页能否把尾部标成可信 —— ACK 之前的
   * 空窗里可能已经漏了行,所以 ACK 本身不点亮既有区间的信任位(见 `sessionWindowCoverage`)。
   */
  noteLiveStreamAcked(sessionId: string): void {
    if (sessionId) sessionLiveStreamAcked.add(sessionId);
  },

  /**
   * 实时推送链路中断:socket 掉线(省略 sessionId = 全部会话)、退后台释放 `session:<id>` 订阅、
   * 或离开会话取消订阅。此后到达的 push 与覆盖区间上界之间可能漏了任意多行,不能再续算
   * (见 `sessionWindowCoverage` 的 `liveTailTrusted`)。
   */
  noteLiveStreamInterrupted(sessionId?: string): void {
    noteLiveStreamInterrupted(sessionId);
  },

  /**
   * 被控端已原子清除一轮消息后,按稳定 clientId 集合移除控制端镜像。
   * 同时失效 latest-window marker;sessions patch 与 deletion push 无顺序保证,
   * 不能让旧 marker 把已变更的窗口误判为已同步。
   */
  removeMessages(sessionId: string, clientIds: readonly string[], deviceId?: string): void {
    const deletedClientIds = new Set(clientIds.filter(Boolean));
    if (!sessionId || deletedClientIds.size === 0) return;
    void clearHistoryDisk(deviceId, sessionId);
    const tracked = new Set(inputProjections.get(sessionId)?.pendingQueue.map((item) => item.clientId) ?? []);
    for (const [clientId, epoch] of inputProjectionRemoteQueuedEvidence.get(sessionId) ?? []) if (epoch > 0) tracked.add(clientId);
    const settled = new Set([...deletedClientIds].filter((clientId) => tracked.has(clientId)));
    const projectionSettled = settleInputProjectionClientIds(sessionId, settled);
    const existing = messages.get(sessionId) ?? emptyMessages;
    const removed = existing.filter((message) => (
      deletedClientIds.has(message.clientId) || deletedClientIds.has(message.id)
    ));
    const next = existing.filter((message) => (
      !deletedClientIds.has(message.clientId) && !deletedClientIds.has(message.id)
    ));
    const syncMarkerChanged = sessionMessageSyncMarkers.delete(sessionId);
    // 连续性结论随窗口一起失效:rewind 可能删掉中间的行,清空/回收更是整窗重来。
    // 重置为未知,下一次最新窗口同步会重建(见 sessionWindowCoverage)。
    forgetWindowCoverage(sessionId);
    const messagesChanged = next.length !== existing.length;
    if (messagesChanged) messages.set(sessionId, next);
    const deletedTaskAliases = new Set<string>(deletedClientIds);
    for (const message of removed) {
      if (message.toolUseId) deletedTaskAliases.add(message.toolUseId);
      const parentToolUseId = message.agentMeta?.parentUuid;
      if (typeof parentToolUseId === 'string') deletedTaskAliases.add(parentToolUseId);
    }
    let tasksChanged = false;
    for (const taskMap of [sessionTaskUpdates, sessionParkedTaskUpdates]) {
      const existingTasks = taskMap.get(sessionId);
      if (!existingTasks) continue;
      const nextTasks = new Map<string, AgentTaskUpdate>();
      for (const [key, task] of existingTasks) {
        if (
          deletedTaskAliases.has(key) ||
          deletedTaskAliases.has(task.taskId) ||
          (task.parentToolUseId !== undefined &&
            deletedTaskAliases.has(task.parentToolUseId))
        ) {
          continue;
        }
        nextTasks.set(key, task);
      }
      if (nextTasks.size !== existingTasks.size) {
        tasksChanged = true;
        if (nextTasks.size === 0) taskMap.delete(sessionId);
        else taskMap.set(sessionId, nextTasks);
      }
    }
    for (const deletedClientId of deletedClientIds) {
      forgetPendingLiveAssistantMessageIdentity(sessionId, deletedClientId);
    }
    // 磁盘窗口可能在 regular LRU 后仍存在,即使当前内存里找不到被删行,也必须
    // 失效缓存,避免下次 hydrate 把远端已删除的正文复活。显式替换会推进 cache
    // epoch,使更晚触发的旧 debounce/unmount flush 失去提交资格。
    if (retentionForSession(sessionId) === 'schedule' || !messagesChanged) {
      clearSessionMessageCache(sessionId, deviceId);
    } else {
      const resolvedDeviceId = deviceId ?? sessionDeviceIndex.get(sessionId);
      if (resolvedDeviceId) {
        void replaceCachedSessionMessages(resolvedDeviceId, sessionId, next).catch(() => undefined);
      }
    }
    if (messagesChanged) {
      applyMessageWriteRetention(sessionId);
    }
    resetRemoteHistoryViews(deviceId, sessionId);
    if (!messagesChanged && !tasksChanged && !projectionSettled && !syncMarkerChanged) return;
    bumpMessageVersion(sessionId);
    emit();
  },

  /** 旧调用点兼容:精确移除一个 clientId。 */
  removeMessage(sessionId: string, clientId: string, deviceId?: string): void {
    this.removeMessages(sessionId, [clientId], deviceId);
  },

  appendLocalSystemCard(
    sessionId: string,
    cardType: MobileSystemCardType,
    data: Record<string, unknown> = {},
    createdAt = new Date(),
  ): string {
    const clientId = `mobile-system-${cardType}-${createdAt.getTime()}-${Math.random().toString(36).slice(2, 8)}`;
    this.appendMessage(sessionId, {
      id: clientId,
      clientId,
      sessionId,
      role: 'system',
      content: '',
      toolUseId: null,
      agentMeta: null,
      createdAt: createdAt.toISOString(),
      systemCardType: cardType,
      systemCardData: data,
    }, { hostTimeAuthoritative: false });
    return clientId;
  },

  patchMessageAgentMeta(sessionId: string, clientId: string, patch: Record<string, unknown>): void {
    const existing = messages.get(sessionId);
    if (!existing) return;
    let changed = false;
    const next = existing.map((message) => {
      if (message.clientId !== clientId && message.id !== clientId) return message;
      changed = true;
      return { ...message, agentMeta: { ...(message.agentMeta ?? {}), ...patch } };
    });
    if (!changed) return;
    messages.set(sessionId, next);
    emit();
  },

  setPendingInteractions(
    sessionId: string,
    list: readonly PendingInteraction[],
    options: { finalizeStreaming?: boolean; deviceId?: string } = {},
  ): void {
    if (!acceptSessionStateSource(sessionId, options.deviceId, sessionInteractionSources)) return;
    // 已确认 dismiss 的延长抑制条目按「缺席即过期」回收:本轮快照不含该
    // requestId = 被控端已确认移除,慢的旧快照此后不可能再带着它(权威读取按
    // 请求序返回),条目可以安全解除;仍含 = 这是 resolve 前发出的旧快照,保留
    // 抑制继续过滤(codex review P2「早发晚到」闪回)。
    const sessionPrefix = interactionResolveKey(sessionId, '');
    const presentIds = new Set(list
      .map((item) => item.request.requestId)
      .filter((id): id is string => typeof id === 'string' && id.length > 0));
    for (const key of [...confirmedInteractionDismissals]) {
      if (!key.startsWith(sessionPrefix)) continue;
      if (!presentIds.has(key.slice(sessionPrefix.length))) confirmedInteractionDismissals.delete(key);
    }
    // 全量快照也要过在途抑制:决定已乐观提交、被控端还没确认时,快照仍会带着
    // 这张卡,不过滤就闪回。成员关系仍以本轮快照为准(缺席 = 被控端已移除),但
    // revision 化的条目取较新者,避免早发晚到的旧快照把内容换回旧版本。
    const currentByRequestId = interactionsByRequestId(pendingInteractions.get(sessionId) ?? emptyPendingInteractions);
    const next = dedupeInteractions(list
      .filter((item) => !isInteractionResolveSuppressed(sessionId, item))
      .map((item) => {
        const requestId = item.request.requestId;
        return pickFresherInteraction(
          item,
          typeof requestId === 'string' ? currentByRequestId.get(requestId) : undefined,
        );
      }));
    // Only a reconnect snapshot that actually restores a visible pending card may
    // finalize streaming. A snapshot containing only an already-dismissed stale
    // request must not close the current assistant row.
    const streamingChanged = options.finalizeStreaming === true && next.length > 0
      ? flushAndFinalizeRemoteStreamingMessages(sessionId)
      : false;
    // 权威性先落:哪怕内容一字未变(典型是重连后的 [] → []),消费方也必须知道
    // 「这份空列表已经被被控端确认过」——否则离线期收起态的清理永远等不到时机
    // (#1493 review)。因此 authority 的翻转本身就是一次需要通知的变化。
    const authorityChanged = !pendingInteractionsAuthoritative.has(sessionId);
    pendingInteractionsAuthoritative.add(sessionId);
    if (next.length === 0) sessionMessageLifecycle.retryPendingReclaim(sessionId);
    if (deepValueEqual(pendingInteractions.get(sessionId) ?? emptyPendingInteractions, next)) {
      if (streamingChanged || authorityChanged) emit();
      return;
    }
    setPendingInteractionState(sessionId, next);
    emit();
  },

  setInputProjection(sessionId: string, projection: unknown): void {
    const next = normalizeInputProjection(projection, sessionId);
    bumpInputProjectionAuthorityEpoch(sessionId);
    recordInputProjectionRemoteEvidence(sessionId, next.pendingQueue.map((item) => item.clientId));
    commitInputProjection(sessionId, next);
  },

  /** Apply local UI state without claiming that the controlled device accepted it. */
  setInputProjectionOptimistically(sessionId: string, projection: unknown): void {
    const next = normalizeInputProjection(projection, sessionId);
    bumpInputProjectionAuthorityEpoch(sessionId);
    commitInputProjection(sessionId, next);
  },

  captureInputProjectionAuthorityEpoch(sessionId: string): number {
    return inputProjectionAuthorityEpochs.get(sessionId) ?? inputProjectionAuthorityEpochFloor;
  },

  captureInputProjectionRemoteEpoch(sessionId: string): number {
    return inputProjectionRemoteEpochs.get(sessionId) ?? inputProjectionRemoteEpochFloor;
  },

  hasAuthoritativeQueuedItemSince(sessionId: string, clientId: string, expectedRemoteEpoch: number): boolean {
    return Math.abs(inputProjectionRemoteQueuedEvidence.get(sessionId)?.get(clientId) ?? 0)
      > expectedRemoteEpoch;
  },

  setInputProjectionIfCurrent(
    sessionId: string,
    projection: unknown,
    expectedEpoch: number,
    expectedRemoteEpoch?: number,
    acceptedClientId?: string,
  ): boolean {
    const remoteEpoch = inputProjectionRemoteEpochs.get(sessionId) ?? inputProjectionRemoteEpochFloor;
    const currentEpoch = inputProjectionAuthorityEpochs.get(sessionId) ?? inputProjectionAuthorityEpochFloor;
    const authorityStale = currentEpoch !== expectedEpoch;
    const remoteStale = expectedRemoteEpoch !== undefined && remoteEpoch !== expectedRemoteEpoch;
    if (authorityStale || remoteStale) {
      if (acceptedClientId) {
        recordInputProjectionRemoteEvidence(sessionId, [acceptedClientId]);
      }
      return false;
    }
    const next = normalizeInputProjection(projection, sessionId);
    const queuedClientIds = new Set(next.pendingQueue.map((item) => item.clientId));
    if (acceptedClientId) queuedClientIds.add(acceptedClientId);
    recordInputProjectionRemoteEvidence(sessionId, queuedClientIds);
    bumpInputProjectionAuthorityEpoch(sessionId);
    commitInputProjection(sessionId, next);
    return true;
  },

  invalidateInputProjectionAuthority(sessionId: string): void {
    bumpInputProjectionAuthorityEpoch(sessionId);
  },

  setSessionRunning(
    sessionId: string,
    running: boolean,
    boundaryAgentMeta?: Record<string, unknown> | null,
  ): void {
    if (!sessionId) return;
    recordInputProjectionRemoteEvidence(sessionId, []);
    // A maker turn boundary supersedes any projection query that started
    // before it. This is the terminal fence for late owner snapshots.
    bumpInputProjectionAuthorityEpoch(sessionId);
    // The terminal event is also authoritative for the continuation owner. A
    // paired projection clear push may be lost during a disconnect, so clear a
    // known owner here instead of leaving the mobile row live until rehydrate.
    let continuationOwnerCleared = false;
    if (!running) {
      const currentProjection = inputProjections.get(sessionId);
      if (currentProjection?.continuationTurnClientId) {
        const nextProjection: InputProjection = {
          ...currentProjection,
          continuationTurnClientId: null,
        };
        continuationOwnerCleared = !deepValueEqual(currentProjection, nextProjection);
        if (continuationOwnerCleared) inputProjections.set(sessionId, nextProjection);
      }
    }
    // 本方法只被 maker 权威信号调用(done / terminal error / status-changed closed),
    // 与 maker turn 边界同步;activity / 快照流走 writeSessionRunStatus,不经过这里。
    // 边界变化必须独立参与 emit 判定:activity 流可能已把宽 run status 置 false,此时
    // writeSessionRunStatus 无变化,若不 emit,useSessionMakerTurnRunning 的订阅者会卡旧值。
    const streamingChanged = running
      ? false
      : flushAndFinalizeRemoteStreamingMessages(sessionId, boundaryAgentMeta);
    const turnBoundaryChanged = writeMakerTurnRunning(sessionId, running);
    const current = readSessionRunStatus(sessionId);
    const next = clearLiveGenerationOnWideRunStart(current, {
      ...current,
      isRunning: running,
      reconnectAttempt: running ? current.reconnectAttempt : null,
      sideTaskRunning: running ? current.sideTaskRunning : false,
      startedAt: running ? (current.startedAt ?? Date.now()) : null,
    });
    if (writeSessionRunStatus(sessionId, next)
      || turnBoundaryChanged
      || streamingChanged
      || continuationOwnerCleared) emit();
  },

  captureActiveSessionSnapshotEpoch(): number {
    return makerActivityEpoch;
  },

  captureDeviceSessionListMutationEpoch(deviceId: string): number {
    return readDeviceSessionListMutationEpoch(deviceId);
  },

  isDeviceSessionListMutationEpochCurrent(deviceId: string, epoch: number): boolean {
    return readDeviceSessionListMutationEpoch(deviceId) === epoch;
  },

  setActiveSessionSnapshots(
    deviceId: string,
    response: unknown,
    activityEpochAtFetchStart = makerActivityEpoch,
  ): void {
    // Only the opted-in v2 envelope asserts a complete runtime list. Legacy
    // arrays can come from old hosts, where absence must retain its old meaning.
    const completeResponse = isRecord(response) && response.format === 'active-sessions-v2'
      && Array.isArray(response.sessions) ? response : null;
    const list: readonly unknown[] = completeResponse
      ? completeResponse.sessions as unknown[]
      : (Array.isArray(response) ? response : []);
    const snapshotStates = new Map<string, {
      running: boolean;
      activityPhase: string | null;
      activityAttention: unknown;
    }>();
    for (const item of list) {
      if (!isRecord(item)) continue;
      const sessionId = readString(item, 'sessionId');
      if (sessionId && typeof item.isTurnRunning === 'boolean') {
        if (!sessionStateWriteAllowed(sessionId, deviceId)) continue;
        snapshotStates.set(sessionId, {
          running: item.isTurnRunning,
          activityPhase: readString(item, 'activityPhase'),
          activityAttention: item.activityAttention,
        });
      }
    }
    let changed = false;
    for (const [sessionId, { running, activityPhase, activityAttention }] of snapshotStates) {
      acceptSessionStateSource(sessionId, deviceId, sessionRuntimeSources);
      if (!running) {
        changed = flushAndFinalizeRemoteStreamingMessages(sessionId) || changed;
        changed = writeMakerTurnRunning(sessionId, false) || changed;
      }
      const current = readSessionRunStatus(sessionId);
      const hasNewerMakerActivity = (sessionMakerActivityEpochs.get(sessionId) ?? 0)
        > activityEpochAtFetchStart;
      // A fresh host snapshot can repair a missed activity clear while the phone was
      // backgrounded. Old hosts omit these optional fields, so keep their push-only path.
      if (!hasNewerMakerActivity && typeof activityAttention === 'boolean'
        && (isRemoteSessionLiveActivityPhase(activityPhase) || activityPhase === 'idle')) {
        if (activityPhase === 'running' || activityPhase === 'needs-interaction'
          || (activityAttention && activityPhase !== 'idle')) {
          const previous = sessionLiveActivity.get(sessionId);
          changed = writeSessionLiveActivity(sessionId, {
            sessionId,
            phase: activityPhase,
            compactDetail: previous?.phase === activityPhase ? previous.compactDetail : '',
            workingPhase: previous?.phase === activityPhase ? previous.workingPhase : undefined,
            interactionKind: previous?.phase === activityPhase ? previous.interactionKind : undefined,
            attention: activityAttention,
          }) || changed;
        } else {
          changed = deleteSessionLiveActivity(sessionId) || changed;
        }
      }
      const next = clearLiveGenerationOnWideRunStart(current, {
        ...current,
        isRunning: running,
        reconnectAttempt: running && hasNewerMakerActivity ? current.reconnectAttempt : null,
        sideTaskRunning: running ? current.sideTaskRunning : false,
        startedAt: running ? (current.startedAt ?? Date.now()) : null,
      });
      changed = writeSessionRunStatus(sessionId, next) || changed;
    }
    if (completeResponse) {
      for (const sessionId of sessionDeviceIndex.keys()) {
        if (!sessionStateWriteAllowed(sessionId, deviceId) || snapshotStates.has(sessionId)
          || (sessionMakerActivityEpochs.get(sessionId) ?? 0) > activityEpochAtFetchStart) continue;
        // A runtime absent from a complete host snapshot has ended. Do not
        // discard a newer live push that arrived while this read was in flight.
        changed = flushAndFinalizeRemoteStreamingMessages(sessionId) || changed;
        changed = writeMakerTurnRunning(sessionId, false) || changed;
        changed = deleteSessionLiveActivity(sessionId) || changed;
        const current = readSessionRunStatus(sessionId);
        changed = writeSessionRunStatus(sessionId, {
          ...current,
          isRunning: false,
          reconnectAttempt: null,
          sideTaskRunning: false,
          startedAt: null,
        }) || changed;
      }
    }
    if (changed) emit();
  },

  applyInteractionRequest(sessionId: string, item: PendingInteraction): void {
    // push 重放 / reseed 在乐观提交窗口内不得复活这张卡(见 inFlightInteractionResolves);
    // 本端已对某 revision 做过决定时,更旧的快照也不得把它带回来(见 interactionRevisionFloors)。
    if (isInteractionResolveSuppressed(sessionId, item)) return;
    const streamingChanged = flushAndFinalizeRemoteStreamingMessages(sessionId);
    const reconnectCleared = clearSessionReconnectAttempt(sessionId);
    const existing = pendingInteractions.get(sessionId) ?? [];
    // 早发晚到的旧 push 不得把手上更新的那份换回旧版本。
    const requestId = item.request.requestId;
    const fresher = pickFresherInteraction(
      item,
      typeof requestId === 'string' && requestId.length > 0
        ? existing.find((candidate) => candidate.request.requestId === requestId)
        : undefined,
    );
    const next = dedupeInteractions([...existing, fresher]);
    if (deepValueEqual(existing, next)) {
      if (streamingChanged || reconnectCleared) emit();
      return;
    }
    setPendingInteractionState(sessionId, next);
    emit();
  },

  dismissInteraction(sessionId: string, requestId: string): void {
    const existing = pendingInteractions.get(sessionId) ?? [];
    const next = existing.filter((i) => i.request.requestId !== requestId);
    if (next.length === existing.length) return;
    setPendingInteractionState(sessionId, next);
    if (next.length === 0) sessionMessageLifecycle.retryPendingReclaim(sessionId);
    emit();
  },

  /**
   * 交互卡乐观 dismiss(批准 / 拒绝点击即撤卡):撤卡 + 登记在途抑制,让权威流
   * 在被控端确认前无法把同一张卡灌回来。结果落定后必须调 settleOptimistic-
   * InteractionDismiss 收口,否则该 requestId 的卡被永久抑制。
   */
  beginOptimisticInteractionDismiss(sessionId: string, requestId: string): void {
    if (!requestId) return;
    inFlightInteractionResolves.add(interactionResolveKey(sessionId, requestId));
    this.dismissInteraction(sessionId, requestId);
  },

  /**
   * 乐观 dismiss 收口:失败(restore)解除抑制并把原卡复原回面板供重试;成功
   * (confirmed)**不立即解除**——转入延长抑制集合,挡「resolve 前发出、resolve
   * 后才返回」的慢权威快照(否则旧快照会把已解决的卡灌回面板闪回),条目仅由
   * setPendingInteractions 的「缺席即过期」回收。
   */
  settleOptimisticInteractionDismiss(
    sessionId: string,
    requestId: string,
    outcome: { kind: 'confirmed' } | { kind: 'restore'; item: PendingInteraction },
  ): void {
    const key = interactionResolveKey(sessionId, requestId);
    inFlightInteractionResolves.delete(key);
    if (outcome.kind === 'restore') {
      this.applyInteractionRequest(sessionId, outcome.item);
    } else {
      confirmedInteractionDismissals.add(key);
    }
  },

  /**
   * 非乐观提交(revision 化交互,当前只有 plugin_setup)的收口:不撤卡,只把下限
   * 抬到 revision+1,让本次决定作用的那份快照及更旧的都失去覆盖权。
   *
   * 为什么不能复用 settleOptimisticInteractionDismiss 的 confirmed:那是无条件
   * 抑制该 requestId,而这里的决定可能没生效(被控端按 expectedRevision 裁决,
   * 对不上就改为重新体检并推更高 revision),无条件抑制会让卡永久隐身。判据见
   * interactionRevisionFloors。
   */
  markInteractionRevisionResolved(sessionId: string, requestId: string, revision: number): void {
    // 同 interactionRevision:只接受非负整数,与被控端 expectedRevision 契约一致。
    if (!requestId || !Number.isInteger(revision) || revision < 0) return;
    const key = interactionResolveKey(sessionId, requestId);
    const floor = revision + 1;
    const current = interactionRevisionFloors.get(key);
    // 只升不降:重复取消 / 乱序收口都不能把下限拉回去。
    if (current !== undefined && current >= floor) return;
    interactionRevisionFloors.set(key, floor);
    // 下限只挡「后来写入」的过期快照,列表里可能已经躺着一份:dismiss push 早于
    // resolve promise 落定时,一份在途旧快照能在这个方法跑到之前把 revision R 重新
    // 填回去。不一起清掉,那张卡会继续显示,而对它点取消只是「看起来成功」的
    // no-op(被控端已 complete,resolve 不再受理)。见 #530 review。
    const existing = pendingInteractions.get(sessionId);
    if (!existing?.length) return;
    const next = existing.filter((item) => item.request.requestId !== requestId
      || !isInteractionResolveSuppressed(sessionId, item));
    if (next.length === existing.length) return;
    setPendingInteractionState(sessionId, next);
    if (next.length === 0) sessionMessageLifecycle.retryPendingReclaim(sessionId);
    emit();
  },

  /**
   * 单条 maker:event push payload 的消费(逐帧与微批拆包**共用**唯一实现——
   * 两条路径若各自解析,批的语义就会随逐帧演进而漂移)。
   */
  applyMakerEventPush(payload: Record<string, unknown>, deviceId?: string): void {
    const sessionId = readString(payload, 'sessionId');
    const event = isRecord(payload.event) ? payload.event : null;
    const persistId = readString(payload, 'persistId') ?? undefined;
    const fromList = payload.listMessage === true;
    if (fromList && (!sessionId || !listMessageWriteAllowed(sessionId, deviceId))) return;
    if (sessionId && event) this.applyMakerEvent(sessionId, event, persistId, deviceId, fromList);
  },

  applyRemotePush(deviceId: string, channel: string, payload: unknown): void {
    if (channel === SESSION_SYNC_CHANNEL) {
      consumeRemoteSessionSync(payload, {
        applyEvent: (event) => this.applyRemotePush(deviceId, 'maker:event', {
          ...event, ...(isRecord(payload) && payload.listMessage === true ? { listMessage: true } : {}),
        }),
        invalidateHistory: (sessionId) => {
          sessionMessageSyncMarkers.delete(sessionId);
          narrowWindowCoverageToStart(sessionId);
          pendingRefreshSessions.add(sessionId);
          bumpMessageVersion(sessionId);
          emit();
        },
      });
      return;
    }
    if (channel === SESSION_ACTIVITY_CHANNEL) {
      this.applySessionActivity(deviceId, payload);
      return;
    }
    if (channel === 'maker:new-maker-draft:changed') {
      const enabled = readPushedNewMakerWorktreeEnabled(payload);
      if (enabled !== null) this.setNewMakerWorktreePreference(deviceId, enabled);
      return;
    }
    if (channel === 'maker:new-maker-worktree-branch:changed') {
      const snapshot = readPushedNewMakerWorktreeBranchPreference(payload);
      if (snapshot !== null) this.setNewMakerWorktreeBranchPreference(deviceId, snapshot);
      return;
    }
    if (channel === 'local-db:sessions:created') {
      bumpDeviceSessionListMutationEpoch(deviceId);
      reseedHandlers.get(deviceId)?.forEach((handler) => handler());
      return;
    }
    if (channel === 'maker:session-model-pref:changed') {
      // 被控端会话「非选中模型」effort/fast 变更(被控端本地改 / 应用了任一控制端写穿)→
      // 刷新会话模型列表镜像(payload 自带 sessionId,镜像按会话隔离,非法 payload 静默忽略)。
      applySessionModelPrefPush(payload);
      return;
    }
    if (channel === 'local-db:task-tags:changed' && isRecord(payload)) {
      bumpDeviceSessionListMutationEpoch(deviceId);
      const shard = shards.get(deviceId);
      if (!shard) return;
      const catalog = normalizeTaskTags(payload.tags, 256);
      shard.sessions = shard.sessions.map((session) => ({
        ...session,
        tags: reconcileTaskTags(session.tags, catalog),
      }));
      recomputeSessions();
      return;
    }
    if (channel === 'local-db:sessions:patched' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const patch = isRecord(payload.patch) ? payload.patch : null;
      if (sessionId && patch) {
        bumpDeviceSessionListMutationEpoch(deviceId);
        // 遮蔽本机在途写的字段:旧写的无差别 push 回流不得滚回更新的乐观意图,
        // 被遮字段的终态由对应写的对账 / 后续 push 收敛;全部被遮时跳过应用。
        // localRow 供差异留痕判定:本笔 echo push(同值)不留痕,避免每次成功写
        // 都误触发 reseed(review P2)。
        const localRow = shards.get(deviceId)?.sessions.find((s) => s.id === sessionId);
        const filtered = sessionPendingWrites.filterPatch(
          sessionId,
          patch,
          localRow as unknown as Record<string, unknown> | undefined,
        );
        if (Object.keys(filtered).length > 0) {
          this.applySessionPatch(deviceId, sessionId, filtered as Partial<RemoteSession>);
        }
      }
      return;
    }
    if (channel === 'local-db:messages:created' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const message = isRecord(payload.message) ? (payload.message as unknown as RemoteMessage) : null;
      const fromList = payload.listMessage === true;
      if (fromList && (!sessionId || !listMessageWriteAllowed(sessionId, deviceId))) return;
      if (sessionId && message) {
        const received = fromList ? { ...message, cacheReceipt: nextHistoryCacheReceipt() } : message;
        this.appendMessage(sessionId, received, { listMessage: fromList });
        if (fromList) void cacheSessionListMessage(deviceId, sessionId, received);
      }
      return;
    }
    if (channel === 'local-db:messages:deleted' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const clientId = readString(payload, 'clientId');
      const clientIds = Array.isArray(payload.clientIds)
        ? payload.clientIds.filter((value): value is string =>
            typeof value === 'string' && value.length > 0,
          )
        : clientId
          ? [clientId]
          : [];
      if (sessionId && clientIds.length > 0) {
        this.removeMessages(sessionId, clientIds, deviceId);
      }
      return;
    }
    if (channel === 'local-db:session:error-persisted' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      if (sessionId) {
        if (messages.has(sessionId)) {
          // 会话有缓存消息:保留消息(避免先清空导致空白帧),仅失效 sync marker + 标记待刷新。
          // session 页面监听到 pendingRefreshSessions 变化后调 load(),走 reopen 路径:
          // sync marker 已失效 → metaChanged=true → 拉最新消息窗口(含 error 行)整窗替换。
          sessionMessageSyncMarkers.delete(sessionId);
          // 连续性结论随窗口一起失效:rewind 可能删掉中间的行,清空/回收更是整窗重来。
          // 重置为未知,下一次最新窗口同步会重建(见 sessionWindowCoverage)。
          forgetWindowCoverage(sessionId);
          pendingRefreshSessions.add(sessionId);
        } else {
          // 未缓存:清 sync marker + 标记待刷新。
          // 若 session 页面正在首次 listMessages(messages 尚未填充),需要 pendingRefreshSessions
          // 保证:即使那次 in-flight 请求的响应在 error 行写入之前发出(返回旧历史),
          // session 页面挂载/useSyncExternalStore 检测到 pending 后仍会重新调 load(),
          // 触发同步失效 → metaChanged=true → 整窗替换,error 卡正常浮现。
          messages.delete(sessionId);
          listMessageKeys.delete(sessionId);
          sessionMessageSyncMarkers.delete(sessionId);
          // 连续性结论随窗口一起失效:rewind 可能删掉中间的行,清空/回收更是整窗重来。
          // 重置为未知,下一次最新窗口同步会重建(见 sessionWindowCoverage)。
          forgetWindowCoverage(sessionId);
          pendingRefreshSessions.add(sessionId);
        }
        bumpMessageVersion(sessionId);
        emit();
      }
      return;
    }
    if (channel === 'maker:event' && isRecord(payload)) {
      this.applyMakerEventPush(payload, deviceId);
      return;
    }
    // 微批帧:被控端把同一会话的连续 maker:event 合并成一帧(能力协商见
    // CONTROLLER_CAPABILITY_MAKER_EVENT_BATCH_V1)。逐条按原顺序走与逐帧**完全
    // 相同**的处理路径——批只是传输层的聚合,不引入新的应用语义;单条形状不符
    // 时跳过该条而不丢整批。
    if (channel === MAKER_EVENT_BATCH_CHANNEL) {
      // 拆包与 fail-closed 的 topic 隔离判据在共享包里(desktop 作为控制端时也用
      // 同一份,见 expandMakerEventBatchPayload 注释)。
      for (const event of expandMakerEventBatchPayload(payload)) {
        if (!isRecord(event)) continue;
        this.applyMakerEventPush(event, deviceId);
      }
      return;
    }
    if (channel === 'maker:status-changed' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const status = readString(payload, 'status');
      if (sessionId && status === 'closed' && acceptSessionStateSource(sessionId, deviceId, sessionRuntimeSources)) this.setSessionRunning(sessionId, false);
      return;
    }
    if (channel === 'usage:message-turn-cost' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const clientId = readString(payload, 'clientId');
      const turnMoney = normalizeRemoteMoney(payload.turnMoney);
      const turnCostUsd = readNumber(payload, 'turnCostUsd');
      // 用量明细与金额各自独立:桌面算不出报价时只推 turnUsageDetails,操作行据此
      // 退回显示本轮 token(与 messageNormalize.readTurnCost 同口径)。
      const turnUsageDetails = isRecord(payload.turnUsageDetails)
        ? payload.turnUsageDetails
        : undefined;
      // 用户轮累计与当前 segment 金额是两个独立事实:自动续跑的收尾轮只带 userTurnMoney
      // (前面的 segment 记了账、收尾这个缺报价)。所以独立投影,由
      // messageNormalize.readTurnCost 单点决定操作行显示哪一个
      // (不变量正本见 apps/desktop/src/shared/turnCostPayload.ts)。
      const userTurnMoney = normalizeRemoteMoney(payload.userTurnMoney);
      const userTurnCostUsd = readNumber(payload, 'userTurnCostUsd');
      const userTurnCostIsEstimate = payload.userTurnCostIsEstimate === true;
      const basePatch: Record<string, unknown> = {
        ...(turnUsageDetails ? { turnUsageDetails } : {}),
      };
      if (userTurnMoney && userTurnMoney.amount > 0) {
        basePatch.userTurnCost = userTurnMoney;
        if (userTurnMoney.currency === 'USD') {
          basePatch.userTurnCostUsd = userTurnMoney.amount;
        }
        basePatch.userTurnCostIsEstimate =
          userTurnCostIsEstimate || userTurnMoney.kind === 'value-estimate';
      } else if (userTurnCostUsd !== null && userTurnCostUsd > 0) {
        basePatch.userTurnCostUsd = userTurnCostUsd;
        basePatch.userTurnCostIsEstimate = userTurnCostIsEstimate;
      }
      if (sessionId && clientId && turnMoney && turnMoney.amount > 0) {
        this.patchMessageAgentMeta(sessionId, clientId, {
          ...basePatch,
          turnCost: turnMoney,
          ...(turnMoney.currency === 'USD' ? { turnCostUsd: turnMoney.amount } : {}),
          turnCostIsEstimate: turnMoney.kind === 'value-estimate',
        });
      } else if (sessionId && clientId && turnCostUsd !== null && turnCostUsd > 0) {
        this.patchMessageAgentMeta(sessionId, clientId, {
          ...basePatch,
          turnCostUsd,
          turnCostIsEstimate: payload.turnCostIsEstimate === true,
        });
      } else if (sessionId && clientId && Object.keys(basePatch).length > 0) {
        this.patchMessageAgentMeta(sessionId, clientId, basePatch);
      }
      return;
    }
    if (channel === 'usage:session-spend-changed' && isRecord(payload)) {
      // session 终身累计 cost 镜像:被控端 sessionSpendBroadcaster 走裸 UPDATE、不发
      // sessions:patched,这条(sessions topic,列表订阅常开)是唯一更新通道;不处理则
      // 会话菜单用量摘要停在旧值直到 reseed。readNumber 已挡 NaN,负数不入镜像。
      const sessionId = readString(payload, 'sessionId');
      const totalMoney = normalizeRemoteMoney(payload.totalMoney);
      const totalCostUsd = readNumber(payload, 'totalCostUsd');
      if (sessionId && totalMoney) {
        bumpDeviceSessionListMutationEpoch(deviceId);
        this.applySessionPatch(deviceId, sessionId, {
          totalMoney,
          ...(totalMoney.currency === 'USD' ? { totalCostUsd: totalMoney.amount } : {}),
        });
      } else if (sessionId && totalCostUsd !== null && totalCostUsd >= 0) {
        bumpDeviceSessionListMutationEpoch(deviceId);
        this.applySessionPatch(deviceId, sessionId, { totalCostUsd });
      }
      return;
    }
    if (channel === 'usage:session-tokens-changed' && isRecord(payload)) {
      // 同上:session 终身累计 token 镜像。
      const sessionId = readString(payload, 'sessionId');
      const totalTokens = readNumber(payload, 'totalTokens');
      if (sessionId && totalTokens !== null && totalTokens >= 0) {
        bumpDeviceSessionListMutationEpoch(deviceId);
        this.applySessionPatch(deviceId, sessionId, { totalTokenUsage: totalTokens });
      }
      return;
    }
    if (channel === 'usage:message-model-mismatch' && isRecord(payload)) {
      // 本轮模型降级标记(桌面被控端 turn 结束检测命中时推送):patch 进
      // agent_meta,messageNormalize 的 readModelMismatch 据此渲染降级提示行。
      const sessionId = readString(payload, 'sessionId');
      const clientId = readString(payload, 'clientId');
      const mm = isRecord(payload.modelMismatch) ? payload.modelMismatch : null;
      const selected = mm ? readString(mm, 'selected') : null;
      const actual = mm ? readString(mm, 'actual') : null;
      if (sessionId && clientId && selected && actual) {
        this.patchMessageAgentMeta(sessionId, clientId, {
          modelMismatch: { selected, actual },
        });
      }
      return;
    }
    if (channel === 'maker:interaction-request' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const request = isRecord(payload.request) ? payload.request : null;
      if (sessionId && request && acceptSessionStateSource(sessionId, deviceId, sessionInteractionSources)) {
        this.applyInteractionRequest(sessionId, {
          request: request as PendingInteraction['request'],
          persistId: readString(payload, 'persistId') ?? undefined,
        });
      }
      return;
    }
    if (channel === 'maker:interaction-dismissed' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      const requestId = readString(payload, 'requestId');
      if (sessionId && requestId && acceptSessionStateSource(sessionId, deviceId, sessionInteractionSources)) {
        if (payload.reason === 'resolved' && !(isRecord(payload.decision) && payload.decision.dismissed === true)) {
          this.confirmProtectedQuestion(sessionId, requestId);
        }
        // 注意:这里**不**提前回收延长抑制条目——push 到达只说明被控端已确认,
        // 不排除仍有「决定提交前发出、此刻还在途」的旧 getPendingInteractions
        // 快照晚于本 push 返回(弱网高发);提前回收会让那份旧快照把已解决的卡
        // 灌回面板闪回(codex review P2)。条目一律等 setPendingInteractions 的
        // 「缺席即过期」自然回收。
        this.dismissInteraction(sessionId, requestId);
      }
      return;
    }
    if (channel === 'maker:input:projection' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      if (sessionId) this.setInputProjection(sessionId, payload);
      return;
    }
    if (channel === 'maker:goal:status-changed' && isRecord(payload)) {
      const sessionId = readString(payload, 'sessionId');
      if (sessionId) {
        this.setGoalStatus(
          sessionId,
          isRecord(payload.goal) ? (payload.goal as unknown as MobileGoalStatusPayload) : null,
        );
      }
    }
  },

  setGoalStatus(sessionId: string, goal: MobileGoalStatusPayload | null): void {
    const existing = sessionGoalStatus.get(sessionId);
    if (sessionGoalStatus.has(sessionId) && deepValueEqual(existing, goal)) return;
    sessionGoalStatus.set(sessionId, goal);
    emit();
  },

  applySessionActivity(deviceId: string, payload: unknown): void {
    if (!isRecord(payload)) return;
    const sessionId = readString(payload, 'sessionId');
    const phase = readString(payload, 'phase');
    if (!sessionId || !isRemoteSessionLiveActivityPhase(phase)
      || !acceptSessionStateSource(sessionId, deviceId, sessionRuntimeSources)) return;
    markSessionMakerActivity(sessionId);
    const compactDetail = typeof payload.compactDetail === 'string' ? payload.compactDetail : '';
    let changed = false;
    if (phase === 'running' || phase === 'needs-interaction') {
      const next: RemoteSessionLiveActivity = {
        sessionId,
        phase,
        compactDetail,
        workingPhase: readString(payload, 'workingPhase') ?? undefined,
        interactionKind: readString(payload, 'interactionKind') ?? undefined,
        attention: payload.attention === true,
      };
      changed = writeSessionLiveActivity(sessionId, next) || changed;
      const current = readSessionRunStatus(sessionId);
      changed = writeSessionRunStatus(sessionId, clearLiveGenerationOnWideRunStart(current, {
        ...current,
        isRunning: true,
        sideTaskRunning: current.sideTaskRunning,
        startedAt: current.startedAt ?? Date.now(),
      })) || changed;
      if (phase === 'needs-interaction') {
        changed = flushAndFinalizeRemoteStreamingMessages(sessionId) || changed;
      }
    } else {
      // completed / error 的未读态(attention=true)保留 liveActivity 条目 —— 会话行
      // 右侧状态槽靠 phase+attention 点亮完成绿点 / 出错红点(与桌面侧栏同语义);
      // 已读(attention=false,桌面侧真实展示后 relay 会重发)或收尾包才删除条目。
      // isRunning 等运行态照常收敛,不受保留影响。
      if (payload.attention === true) {
        changed = writeSessionLiveActivity(sessionId, {
          sessionId,
          phase,
          compactDetail,
          interactionKind: readString(payload, 'interactionKind') ?? undefined,
          attention: true,
        }) || changed;
      } else {
        changed = deleteSessionLiveActivity(sessionId) || changed;
      }
      // 权威 idle 恢复路径(completed / error 活动推送)同步关闭 maker turn 边界(只关不开):
      // 后台/断连错过终态 maker 事件后,边界会卡在 true、孤儿渲染 gate 常开,stale 得以重放。
      changed = flushAndFinalizeRemoteStreamingMessages(sessionId) || changed;
      changed = writeMakerTurnRunning(sessionId, false) || changed;
      const current = readSessionRunStatus(sessionId);
      changed = writeSessionRunStatus(sessionId, {
        ...current,
        isRunning: false,
        ...(phase === 'error' ? { hasTerminalError: true } : {}),
        reconnectAttempt: null,
        sideTaskRunning: false,
        startedAt: null,
      }) || changed;
    }
    if (changed) emit();
  },

  applyMakerEvent(
    sessionId: string,
    event: Record<string, unknown>,
    persistId?: string,
    deviceId?: string,
    fromList = false,
  ): void {
    const type = readString(event, 'type');
    // Text has its own transport replacement/retention rules; only fence the
    // runtime signals here, so reconnecting transports keep their existing data path.
    if ((type === 'status' || type === 'done' || type === 'error')
      && !acceptSessionStateSource(sessionId, deviceId, sessionRuntimeSources)) return;
    markSessionMakerActivity(sessionId);
    const reconnectCleared = type !== null && type !== 'error' && type !== 'done'
      ? clearSessionReconnectAttempt(sessionId)
      : false;
    const fullMessageWriteAllowed = fromList || messageWriteAllowed(sessionId);
    if (type === 'text') {
      if (!fullMessageWriteAllowed) {
        if (reconnectCleared) emit();
        return;
      }
      if (isRemoteTextDeltaEvent(event)) {
        if (enqueueRemoteTextDelta(sessionId, event, persistId, deviceId) || reconnectCleared) emit();
        return;
      }
      let changed = flushPendingTextDelta(sessionId);
      changed = applyRemoteTextEvent(sessionId, event, persistId, deviceId) || changed;
      changed = reconnectCleared || changed;
      if (changed) emit();
      return;
    }

    // setSessionRunning owns the final flush/finalize and run-state transition;
    // keeping the done path in one call avoids notifying subscribers twice.
    if (
      isProductTurnDoneEvent(event)
      || (!isTurnContinuationBoundaryEvent(event) && isTerminalMakerErrorEvent(event))
    ) {
      let terminalPlanChanged = false;
      if (fullMessageWriteAllowed && type === 'done' && readString(event, 'source') === 'codex') {
        const data = isRecord(event.data) ? event.data : null;
        const rawTurn = isRecord(data?.raw) ? data.raw : null;
        const turnId = readString(rawTurn, 'id');
        const turnStatus = readString(rawTurn, 'status');
        const turnCancelled = data?.cancelled === true;
        const currentMessages = messages.get(sessionId) ?? [];
        const completed = applyCodexPlanSnapshotOnDone(
          currentMessages,
          data?.plan,
          turnId,
          turnStatus,
          undefined,
          turnCancelled,
        );
        completeLivePlanSnapshotOnDone(
          sessionId,
          data?.plan,
          turnId,
          turnStatus,
          turnCancelled,
        );
        terminalPlanChanged = completed.changed;
        if (completed.changed) {
          messages.set(sessionId, [...completed.messages]);
          const completedMessage = completed.messages.find((message) => {
            if (message.toolUseId === completed.toolUseId) return true;
            return readString(message.content, 'toolUseId') === completed.toolUseId;
          });
          if (completed.toolUseId && isRecord(completedMessage?.content)) {
            rememberLivePlanContent(
              sessionId,
              completed.toolUseId,
              completedMessage.content,
            );
          }
        }
      } else if (fullMessageWriteAllowed && readString(event, 'source') === 'codex') {
        // 没有 done 的 codex 终态 error:这一轮的计划行等不到章,也等不到
        // persistCodexPlanOnDone 的 turnCompleted:false。与 desktop renderer 的
        // markCodexPlanTurnFailed 同款补印记,否则全勾完的失败计划会按旧数据
        // 兜底退场——任务还活着,用户正要接着指挥。
        const currentMessages = messages.get(sessionId) ?? [];
        const failed = markCodexPlanTurnFailed(currentMessages);
        terminalPlanChanged = failed.changed;
        if (failed.changed) {
          messages.set(sessionId, [...failed.messages]);
          const failedMessage = failed.messages.find((message) => {
            if (message.toolUseId === failed.toolUseId) return true;
            return readString(message.content, 'toolUseId') === failed.toolUseId;
          });
          // 印记也要进 live-plan 缓存:overlayLivePlanSnapshot 用缓存内容整体
          // 替换 content,缓存不补就会把 main 随后广播的落库 turnCompleted:false
          // 盖回去,本连接周期内再也纠不回来。
          if (failed.toolUseId && isRecord(failedMessage?.content)) {
            rememberLivePlanContent(sessionId, failed.toolUseId, failedMessage.content);
          }
        }
      }
      const terminalErrorChanged = isTerminalMakerErrorEvent(event)
        && writeSessionRunStatus(sessionId, {
          ...readSessionRunStatus(sessionId),
          hasTerminalError: true,
        });
      this.setSessionRunning(
        sessionId,
        false,
        isRecord(event.agentMeta) ? event.agentMeta : null,
      );
      if (terminalPlanChanged) {
        bumpMessageVersion(sessionId);
      }
      if (terminalPlanChanged || terminalErrorChanged) emit();
      return;
    }

    const textFlushed = fullMessageWriteAllowed ? flushPendingTextDelta(sessionId) : false;
    if (type === 'error') {
      const data = isRecord(event.data) ? event.data : null;
      const reconnectAttempt = data?.willRetry === true
        ? parseReconnectAttemptMessage(
            readString(data, 'message') ?? '',
            readString(data, 'reason'),
          )
        : null;
      const current = readSessionRunStatus(sessionId);
      const changed = writeSessionRunStatus(sessionId, {
        ...current,
        isRunning: true,
        reconnectAttempt,
        startedAt: current.startedAt ?? Date.now(),
      });
      if (changed || textFlushed) emit();
      return;
    }
    if (type === 'tool_use') {
      if (!fullMessageWriteAllowed) {
        if (reconnectCleared) emit();
        return;
      }
      // Finalize before applying update_plan so its row update and the streaming
      // row transition are published in one snapshot notification.
      const streamingChanged = finalizeRemoteStreamingMessages(
        sessionId,
        isRecord(event.agentMeta) ? event.agentMeta : null,
      );
      const livePlan = applyLivePlanToolUseMessage(sessionId, event, persistId);
      if (livePlan.handled) {
        if (textFlushed || streamingChanged || livePlan.changed || reconnectCleared) emit();
        return;
      }
      if (textFlushed || streamingChanged || reconnectCleared) emit();
      return;
    }
    if (type === 'agent_task_update') {
      if (!fullMessageWriteAllowed) {
        if (reconnectCleared) emit();
        return;
      }
      const rawSource = readString(event, 'source');
      const source = rawSource === 'codex' || rawSource === 'claude-code' || rawSource === 'pi'
        ? rawSource
        : undefined;
      const next = applyAgentTaskUpdateEvent(
        recallParkedTaskUpdates(sessionId, event.data, source, sessionTaskUpdates.get(sessionId)),
        event.data,
        source,
        new Date().toISOString(),
      );
      if (next) {
        sessionTaskUpdates.set(sessionId, next);
        emit();
      } else if (textFlushed || reconnectCleared) {
        emit();
      }
      return;
    }
    if (type === 'compact_boundary') {
      if (!fullMessageWriteAllowed) {
        if (reconnectCleared) emit();
        return;
      }
      const data = isRecord(event.data) ? event.data : {};
      const boundaryId = readString(data, 'boundaryId');
      // 新 producer 都会给 provider boundaryId;兼容旧事件时以完整 data 的 canonical
      // fingerprint 生成可重放身份,不能再用随机 id(同一 replay 会错误结束新工作)。
      const clientId = boundaryId
        ? `mobile-system-compact:${boundaryId}`
        : `mobile-system-compact:fallback:${compactBoundaryFingerprint(data)}`;
      const existing = messages.get(sessionId) ?? [];
      // Transcript replay and the live stream may forward the same provider boundary.
      // De-duplicate before finalizing, otherwise a replay could end post-compact work.
      if (existing.some((message) => messageKey(message) === clientId)) {
        if (textFlushed || reconnectCleared) emit();
        return;
      }
      const backgroundCompact = readString(event, 'turnScope') === 'background';
      // Background compact belongs to the previous idle cycle. Finalizing here
      // would seal a product turn that started after compaction_start.
      if (!backgroundCompact) {
        clearStreamingAssistantPointer(sessionId);
      }
      const nextMessages = backgroundCompact
        ? existing
        : existing.map(finishMessageStreamingAtCompactBoundary);
      const createdAt = new Date().toISOString();
      messages.set(sessionId, normalizeMessages([
        ...nextMessages,
        {
          id: clientId,
          clientId,
          sessionId,
          role: 'assistant',
          content: '',
          toolUseId: null,
          agentMeta: null,
          createdAt,
          systemCardType: 'compact',
          systemCardData: data,
        },
      ]));
      bumpMessageVersion(sessionId);
      emit();
      return;
    }
    if (type === 'status') {
      const data = isRecord(event.data) ? event.data : null;
      const current = readSessionRunStatus(sessionId);
      if (readString(event, 'turnScope') === 'background') {
        const rawStatus = readString(data, 'status') ?? '';
        const status =
          !rawStatus || (rawStatus === 'Done' && current.isRunning)
            ? current.status
            : rawStatus;
        const changed = writeSessionRunStatus(sessionId, { ...current, status });
        if (changed || textFlushed || reconnectCleared) emit();
        return;
      }
      const isRunning = typeof data?.isRunning === 'boolean' ? data.isRunning : current.isRunning;
      if (!isRunning && isTurnContinuationBoundaryEvent(event)) {
        // A claimed status(false) closes only the provider SDK segment. Keep the
        // mobile product turn and its streaming projection alive until an
        // unclaimed terminal event arrives, matching the desktop lifecycle.
        if (textFlushed || reconnectCleared) emit();
        return;
      }
      const rawTokenUsage = readNumber(data, 'tokenUsage');
      const rawStatus = readString(data, 'status');
      // turn-start 检测用 maker 自己的边界(不用 current.isRunning):activity 推送 / 活跃
      // 快照会先把 sessionRunning 置 true,重连场景首个 status 到达时宽状态已是 true,按它
      // 判定会漏掉真 turn start,stale 清理被跳过。
      const isTurnStart = isRunning && sessionMakerTurnRunning.get(sessionId) !== true;
      const turnBoundaryChanged = writeMakerTurnRunning(sessionId, isRunning);
      const tokenUsage = rawTokenUsage !== null && rawTokenUsage > 0
        ? rawTokenUsage
        : (isTurnStart ? 0 : current.tokenUsage);
      const rawOutputTokens = readNumber(data, 'outputTokens');
      const rawGenerationDurationMs = readNumber(data, 'generationDurationMs');
      const hasLiveFields =
        rawOutputTokens !== null ||
        rawGenerationDurationMs !== null ||
        typeof data?.generationActive === 'boolean' ||
        typeof data?.generationReliable === 'boolean';
      // turn 边界清的是上一轮残留,不是本条 status 自带的 live 字段。
      // 重连/前台恢复会先清 maker-turn,活跃快照只恢复宽 isRunning,于是下一条
      // 用量刷新被当成 isTurnStart;若这里无条件归零,权威 output / duration
      // 会被丢掉,紧接着的终态也来不及再显示 tok/s。
      const outputTokens = rawOutputTokens !== null
        ? rawOutputTokens
        : (isTurnStart ? 0 : current.outputTokens);
      const generationDurationMs = rawGenerationDurationMs !== null
        ? rawGenerationDurationMs
        : (isTurnStart ? 0 : current.generationDurationMs);
      const generationActive = !isRunning
        ? false
        : typeof data?.generationActive === 'boolean'
          ? data.generationActive
          : (isTurnStart || hasLiveFields ? false : current.generationActive);
      const generationReliable = typeof data?.generationReliable === 'boolean'
        ? data.generationReliable
        : (isTurnStart ? true : current.generationReliable);
      // 速度属于产生它的那一轮:新一轮清掉,没带字段的帧沿用最近一次(含收尾平均)。
      // 标记不可靠又不带速度的帧,表示电脑端撤回了速度(休眠/时钟异常)。
      const tokenSpeed = readTokenSpeedSnapshot(data?.tokenSpeed)
        ?? (isTurnStart || data?.generationReliable === false ? undefined : current.tokenSpeed);
      // maker turn 边界 false→true 时清掉上一轮残留的 live task updates:它们是 turn 级
      // live 状态,残留到下一轮会被渲染层的孤儿兜底当作"仍在运行的子 agent"追加到消息流
      // 末尾(桌面端靠 idle demote / clear 清,手机 store 是常驻单例,只能在 turn 边界收口)。
      // side task 拉起(skipTurnReset)不豁免:边界置 true 即打开孤儿渲染 gate,不清扫会让
      // 残留立刻重放;而选择性 sweep 本身保留 running codex worker(side task 主体),对
      // side task 无误伤。本轮真实存活的任务也会随后续 update 重建。
      let taskUpdatesCleared = false;
      if (isTurnStart) {
        taskUpdatesCleared = sweepStaleTaskUpdates(sessionId);
      }
      let streamingChanged = false;
      if (!isRunning) {
        streamingChanged = finalizeRemoteStreamingMessages(
          sessionId,
          isRecord(event.agentMeta) ? event.agentMeta : null,
        );
      }
      const next: RemoteSessionRunStatus = {
        isRunning,
        ...(current.hasTerminalError !== undefined ? { hasTerminalError: current.hasTerminalError } : {}),
        reconnectAttempt: null,
        sideTaskRunning: isRunning ? data?.skipTurnReset === true : false,
        startedAt: isRunning ? (current.startedAt ?? Date.now()) : null,
        status: rawStatus ?? current.status,
        tokenUsage,
        outputTokens,
        generationDurationMs,
        generationActive,
        generationReliable,
        tokenSpeed,
      };
      if (
        writeSessionRunStatus(sessionId, next)
        || taskUpdatesCleared
        || turnBoundaryChanged
        || textFlushed
        || streamingChanged
        || reconnectCleared
      ) emit();
      return;
    }
    if (textFlushed || reconnectCleared) emit();
  },

  /**
   * 短暂离线只失效依赖实时连接的投影,保留 shard / session / messages / 路由索引。
   * 恢复后会话页因此走 reopen(旧内容立即可见),而 marker 已删除会强制后台核对
   * 最新消息窗口,不会把断线前缓存误判为 fresh。
   */
  markDeviceOffline(deviceId: string): void {
    if (!sweepDevicesOffline([deviceId])) return;
    emit();
  },

  /**
   * 批量离线:同一波(如 presence 整批离线)只 emit 一次。逐台 markDeviceOffline
   * 时每台各 notify 一轮,叠加 schedule store 的逐台失效,设备数超过 React 嵌套
   * 更新上限即致命退出(2026-09-10 Android 冷启动,40/80 台隔离复现)。
   */
  markDevicesOffline(deviceIds: readonly string[]): void {
    if (!sweepDevicesOffline(deviceIds)) return;
    emit();
  },

  removeDevice(deviceId: string): void {
    void clearHistoryDisk(deviceId);
    clearRemoteHistoryViews(deviceId);
    bumpDeviceSessionListMutationEpoch(deviceId);
    const hadShard = shards.delete(deviceId);
    const hadWorktreePreference = newMakerWorktreePreferences.delete(deviceId);
    const hadWorktreeBranchPreferences = newMakerWorktreeBranchPreferences.delete(deviceId);
    // A maker event may precede the session list, so transport-owned batches, host anchors,
    // and streaming identities are also authoritative ownership evidence. Sweep their sessions
    // even when no shard or sessionDeviceIndex entry exists yet; otherwise the 32ms timer can
    // recreate messages after hard removal, or an already-flushed live row can survive.
    const indexedDeviceSessionIds = new Set<string>();
    const transportOwnedSessionIds = new Set<string>();
    for (const [sessionId, indexedDeviceId] of sessionDeviceIndex) {
      if (indexedDeviceId === deviceId) indexedDeviceSessionIds.add(sessionId);
    }
    for (const [sessionId, batch] of pendingTextDeltaBatches) {
      if (batch.deviceId === deviceId) transportOwnedSessionIds.add(sessionId);
    }
    for (const [sessionId, pendingAnchors] of pendingHostAnchorLiveAssistantClientIds) {
      if ([...pendingAnchors.values()].some((identity) => identity.deviceIds.has(deviceId))) {
        transportOwnedSessionIds.add(sessionId);
      }
    }
    for (const [sessionId, streamingDeviceIds] of streamingAssistantDeviceIds) {
      if ([...streamingDeviceIds.values()].some((ownerDeviceId) => ownerDeviceId === deviceId)) {
        transportOwnedSessionIds.add(sessionId);
      }
    }
    let removedTransportState = false;
    for (const sessionId of indexedDeviceSessionIds) {
      // Keep the authority reset explicit in this hard-remove boundary: consumers must
      // never interpret the now-empty interaction list as an authoritative snapshot.
      pendingInteractionsAuthoritative.delete(sessionId);
      if (hasTransportOwnedSessionStateFromOtherDevice(sessionId, deviceId)) {
        // The stale shard may still own sessionDeviceIndex while a re-linked transport has
        // already started streaming before its own session list arrives. Preserve that
        // replacement batch/row and remove only state owned by the stale transport.
        sessionDeviceIndex.delete(sessionId);
        removedTransportState = discardTransportOwnedPendingSessionState(
          sessionId,
          deviceId,
        ) || removedTransportState;
        continue;
      }
      removeSessionRuntimeState(sessionId);
    }
    for (const sessionId of transportOwnedSessionIds) {
      if (indexedDeviceSessionIds.has(sessionId)) continue;
      // A re-linked current shard may already own the same session id. In that case
      // remove only the stale transport's provisional rows/batch and keep the current
      // device's authoritative window and runtime projections intact. The same precise
      // cleanup also preserves a second pre-metadata transport when no shard exists yet.
      removedTransportState = discardTransportOwnedPendingSessionState(
        sessionId,
        deviceId,
      ) || removedTransportState;
      if (
        !sessionDeviceIndex.has(sessionId)
        && !pendingTextDeltaBatches.has(sessionId)
        && !pendingHostAnchorLiveAssistantClientIds.has(sessionId)
        && !streamingAssistantDeviceIds.has(sessionId)
      ) {
        pendingInteractionsAuthoritative.delete(sessionId);
        removeSessionRuntimeState(sessionId);
        removedTransportState = true;
      }
    }
    const removedSession = indexedDeviceSessionIds.size > 0 || removedTransportState;
    if (
      !hadShard
      && !removedSession
      && !hadWorktreePreference
      && !hadWorktreeBranchPreferences
    ) return;
    bumpMessageVersion();
    recomputeSessions();
  },

  clear(): void {
    clearRemoteHistoryViews();
    deviceSessionListMutationEpochFloor = ++nextDeviceSessionListMutationEpoch;
    deviceSessionListMutationEpochs.clear();
    shards.clear();
    newMakerWorktreePreferences.clear();
    newMakerWorktreeBranchPreferences.clear();
    messages.clear();
    listMessageKeys.clear();
    emptySessionMessageStructureTokens.clear();
    livePlanSnapshots.clear();
    protectedQuestions.clear();
    visibleInteractionCache.clear();
    if (pendingInteractions.size > 0) {
      pendingInteractions.clear();
      bumpHomeStatusVersion();
    }
    pendingInteractionsAuthoritative.clear();
    inFlightInteractionResolves.clear();
    confirmedInteractionDismissals.clear();
    interactionRevisionFloors.clear();
    inputProjections.clear();
    inputProjectionAuthorityEpochFloor = ++nextInputProjectionAuthorityEpoch;
    inputProjectionAuthorityEpochs.clear();
    inputProjectionRemoteEpochFloor = ++nextInputProjectionRemoteEpoch;
    inputProjectionRemoteEpochs.clear();
    inputProjectionRemoteQueuedEvidence.clear();
    // Keep authority tombstones monotonic across a global store reset so an
    // old in-flight query cannot be accepted after the session is recreated.
    if (sessionLiveActivity.size > 0 || sessionRunning.size > 0) {
      sessionLiveActivity.clear();
      sessionRunning.clear();
      bumpHomeStatusVersion();
    }
    sessionRunStatus.clear();
    sessionRuntimeSources.clear();
    sessionInteractionSources.clear();
    sessionMakerActivityEpochs.clear();
    makerActivityEpoch = 0;
    sessionMessageSyncMarkers.clear();
    sessionWindowCoverage.clear();
    sessionLiveStreamAcked.clear();
    sessionTaskUpdates.clear();
    streamingAssistantClientIds.clear();
    generatedStreamPriorIdentities.clear();
    generatedStreamAgentIdentities.clear();
    streamingAssistantDeviceIds.clear();
    pendingLiveAssistantClientIds.clear();
    pendingHostAnchorLiveAssistantClientIds.clear();
    activePendingHostAnchorRoundIds.clear();
    nextPendingHostAnchorRoundId = 0;
    pendingTextDeltaBatches.clear();
    clearTextDeltaFlushTimer();
    sessionMakerTurnRunning.clear();
    sessionParkedTaskUpdates.clear();
    sessionMessageLifecycle.reset();
    sessionLastAccessOrder.clear();
    nextSessionAccessOrder = 0;
    sessionsOpenedInDetail.clear();
    sessionDeviceIndex.clear();
    reseedHandlers.clear();
    sessionListRefreshArmed.clear();
    sessionListRefreshSeen.clear();
    pendingTitlePreview.clear();
    sessionListRemovalPreviews = createPendingWriteTracker();
    mergedSessions = [];
    visibleSessions = [];
    mergedSessionById.clear();
    homeSessionProjectionCache.clear();
    if (homeSessions.length > 0) {
      homeSessions = [];
      bumpHomeStatusVersion();
    }
    deviceList = null;
    bumpMessageVersion();
    emit();
  },

  // Register a reseed handler for a device. Returns an unregister fn that removes only THIS
  // handler — multiple screens (Home + device detail) can subscribe the same device
  // concurrently without one's unmount clobbering the other's subscription.
  registerReseedHandler(deviceId: string, handler: () => void): () => void {
    let set = reseedHandlers.get(deviceId);
    if (!set) {
      set = new Set();
      reseedHandlers.set(deviceId, set);
    }
    set.add(handler);
    return () => {
      const current = reseedHandlers.get(deviceId);
      if (!current) return;
      current.delete(handler);
      if (current.size === 0) reseedHandlers.delete(deviceId);
    };
  },

  requestReseed(deviceId: string): void {
    sessionListRefreshArmed.add(deviceId);
    reseedHandlers.get(deviceId)?.forEach((handler) => handler());
  },

  /** First/reconnected lists, or a specific task whose durable turn just ended. */
  onSessionHistoryPrefetchRequested(listener: (deviceId: string, sessionId?: string) => void): () => void {
    sessionListRefreshListeners.add(listener);
    return () => { sessionListRefreshListeners.delete(listener); };
  },

  /** Explicit lifecycle changes only: a missing snapshot or disconnect is not deletion. */
  onSessionRemoved(listener: (deviceId: string, sessionId: string) => void): () => void {
    sessionRemovalListeners.add(listener);
    return () => { sessionRemovalListeners.delete(listener); };
  },

  getSessionDeviceId(sessionId: string): string | undefined {
    return sessionDeviceIndex.get(sessionId);
  },

  getSessions(): RemoteSession[] {
    return mergedSessions;
  },

  getVisibleSessions(): RemoteSession[] {
    return visibleSessions;
  },

  getHomeSessions(): RemoteSession[] {
    return homeSessions;
  },

  getMessages(sessionId: string): RemoteMessage[] {
    return messages.get(sessionId) ?? emptyMessages;
  },

  /**
   * Stable across ordinary streaming text replacements. Consumers use this to keep structural
   * transcript projections out of the per-token render path. Any append, prepend, reset, final
   * transition, or authoritative rewrite naturally receives a new token.
   */
  getSessionMessageStructureToken(sessionId: string): object {
    const list = messages.get(sessionId) ?? emptyMessages;
    if (list.length > 0) return messageStructureToken(list);
    const existing = emptySessionMessageStructureTokens.get(sessionId);
    if (existing) return existing;
    const token = Object.freeze({ kind: 'empty-message-structure', sessionId });
    emptySessionMessageStructureTokens.set(sessionId, token);
    return token;
  },

  /** Distinct content-only replacement positions accumulated under the current structure token. */
  getSessionMessageStructureChangedIndexes(sessionId: string): ReadonlySet<number> {
    return messageStructureChangedIndexes.get(messages.get(sessionId) ?? emptyMessages)
      ?? EMPTY_MESSAGE_STRUCTURE_CHANGED_INDEXES;
  },

  /** Latest loaded user/assistant preview, cached by the session's message-array identity. */
  getSessionMessagePreview(sessionId: string): string | undefined {
    const list = messages.get(sessionId) ?? emptyMessages;
    const cached = messagePreviewCache.get(list);
    if (cached) return cached.preview;
    const preview = buildSessionMessagePreviewIndex([sessionId], () => list).get(sessionId);
    messagePreviewCache.set(list, { preview });
    return preview;
  },

  /** Lists must not let an old message mirror hide fresh history-view metadata. */
  getSessionListMessagePreview(sessionId: string, session = sessionById(sessionId)): string | undefined {
    const loaded = this.getSessionMessagePreview(sessionId);
    if (!session || (this.isSessionMessageWindowSynced(sessionId, session)
      && sessionMessageSyncMarkers.get(sessionId)?.preview === session.preview)) return loaded;
    // Only text received against the current metadata may outrun its preview.
    // A missed done event must not let an old stream win after foreground refresh.
    const cached = messagePreviewCache.get(messages.get(sessionId) ?? emptyMessages);
    if (cached?.liveSession === session) return loaded;
    return sessionRowMessagePreview(session) ?? (typeof session.preview === 'string' ? '' : loaded);
  },

  getSessionListMessagePreviewIndex(sessions: readonly RemoteSession[]): Map<string, string> {
    const index = new Map<string, string>();
    for (const session of sessions) {
      const preview = this.getSessionListMessagePreview(session.id, session);
      if (preview) index.set(session.id, preview);
    }
    return index;
  },

  getMessageVersion(): number {
    return messageVersion;
  },

  getStoreVersion(): number {
    return storeVersion;
  },

  getHomeStatusVersion(): number {
    return homeStatusVersion;
  },

  setNewMakerWorktreePreference(deviceId: string, enabled: boolean): void {
    if (!deviceId) return;
    const current = newMakerWorktreePreferences.get(deviceId);
    newMakerWorktreePreferences.set(deviceId, {
      enabled,
      revision: (current?.revision ?? 0) + 1,
    });
    // 同值 push 仍需推进 revision:它可能比在途 pull 更新,必须让旧响应失去写权。
    emit();
  },

  getNewMakerWorktreePreference(
    deviceId: string | null | undefined,
  ): RemoteNewMakerWorktreePreference {
    if (!deviceId) return EMPTY_NEW_MAKER_WORKTREE_PREFERENCE;
    return newMakerWorktreePreferences.get(deviceId)
      ?? EMPTY_NEW_MAKER_WORKTREE_PREFERENCE;
  },

  setNewMakerWorktreeBranchPreference(
    deviceId: string,
    snapshot: RemoteNewMakerWorktreeBranchPreference,
  ): void {
    if (!deviceId || snapshot === null) return;
    const baseRepo = snapshot.baseRepo.trim();
    const sourceBranch = snapshot.sourceBranch.trim();
    if (
      !baseRepo
      || !sourceBranch
      || !Number.isInteger(snapshot.revision)
      || snapshot.revision < 0
    ) return;

    let byRepo = newMakerWorktreeBranchPreferences.get(deviceId);
    const current = byRepo?.get(baseRepo);
    if (current) {
      // revision 由 host 按 canonical repo 单调递增。旧快照不能覆盖;相等只接受
      // 完全相同的幂等 echo,同 revision 的冲突值也必须拒绝。
      if (snapshot.revision < current.revision) return;
      if (snapshot.revision === current.revision) return;
    }
    if (!byRepo) {
      byRepo = new Map();
      newMakerWorktreeBranchPreferences.set(deviceId, byRepo);
    }
    byRepo.set(baseRepo, {
      baseRepo,
      sourceBranch,
      revision: snapshot.revision,
    });
    // 同一 sourceBranch 的新 host revision 也必须发布:它给在途 pull / apply 回包做 fence。
    emit();
  },

  /**
   * GET 的 null 是工作端对该 repo「当前没有偏好」的权威回答,不是漏包。
   * 桌面进程重启后 host revision 会从头开始;先删掉手机保存的旧高 revision,
   * 后续 rev1 snapshot / push 才有资格成为新进程的真相。
   */
  clearNewMakerWorktreeBranchPreference(
    deviceId: string,
    baseRepo: string,
  ): void {
    const normalizedBaseRepo = baseRepo.trim();
    if (!deviceId || !normalizedBaseRepo) return;
    const byRepo = newMakerWorktreeBranchPreferences.get(deviceId);
    if (!byRepo?.delete(normalizedBaseRepo)) return;
    if (byRepo.size === 0) newMakerWorktreeBranchPreferences.delete(deviceId);
    emit();
  },

  getNewMakerWorktreeBranchPreference(
    deviceId: string | null | undefined,
    baseRepo: string | null | undefined,
  ): RemoteNewMakerWorktreeBranchPreference {
    if (!deviceId || !baseRepo?.trim()) return null;
    return newMakerWorktreeBranchPreferences.get(deviceId)?.get(baseRepo.trim()) ?? null;
  },

  getPendingInteractions(sessionId: string, deviceId?: string): PendingInteraction[] {
    if (!sessionStateReadAllowed(sessionId, deviceId, sessionInteractionSources)) return emptyPendingInteractions;
    return pendingInteractions.get(sessionId) ?? emptyPendingInteractions;
  },

  protectAsyncQuestion(sessionId: string, item: PendingInteraction): void {
    if (item.request.kind !== 'ask_user_question' || item.request.delivery !== 'async') return;
    if (protectedQuestions.get(sessionId)?.request.requestId === item.request.requestId) return;
    protectedQuestions.set(sessionId, { ...item, retainedDraft: true });
    emit();
  },

  releaseProtectedQuestion(sessionId: string, requestId: string): void {
    if (protectedQuestions.get(sessionId)?.request.requestId !== requestId) return;
    protectedQuestions.delete(sessionId);
    visibleInteractionCache.delete(sessionId);
    emit();
  },

  /** Both the resolve receipt and a resolved push complete the same draft. */
  confirmProtectedQuestion(sessionId: string, requestId: string): void {
    if (protectedQuestions.get(sessionId)?.request.requestId !== requestId) return;
    // Register the existing stale-snapshot suppression before publishing removal.
    this.settleOptimisticInteractionDismiss(sessionId, requestId, { kind: 'confirmed' });
    clearAskUserDraft(requestId);
    this.dismissInteraction(sessionId, requestId);
    this.releaseProtectedQuestion(sessionId, requestId);
  },

  getVisiblePendingInteractions(sessionId: string): PendingInteraction[] {
    const raw = this.getPendingInteractions(sessionId);
    const retained = protectedQuestions.get(sessionId);
    if (!retained) return raw;
    const cached = visibleInteractionCache.get(sessionId);
    if (cached?.raw === raw && cached.protected === retained) return cached.result;
    const result = [retained, ...raw.filter((item) => item.request.requestId !== retained.request.requestId)];
    visibleInteractionCache.set(sessionId, { raw, protected: retained, result });
    return result;
  },

  /**
   * pending 列表当前是否权威(见 pendingInteractionsAuthoritative 的注释)。
   * 空列表要用来做清理判断时必须先问这里。
   */
  hasAuthoritativePendingInteractions(sessionId: string): boolean {
    return pendingInteractionsAuthoritative.has(sessionId);
  },

  getInputProjection(sessionId: string): InputProjection {
    return inputProjections.get(sessionId) ?? EMPTY_INPUT_PROJECTION;
  },

  getSessionLiveActivity(sessionId: string, deviceId?: string): RemoteSessionLiveActivity | null {
    if (!sessionStateReadAllowed(sessionId, deviceId, sessionRuntimeSources)) return null;
    return sessionLiveActivity.get(sessionId) ?? null;
  },

  isSessionRunning(sessionId: string, deviceId?: string): boolean {
    return sessionStateReadAllowed(sessionId, deviceId, sessionRuntimeSources) && sessionRunning.get(sessionId) === true;
  },

  getSessionRunStatus(sessionId: string): RemoteSessionRunStatus {
    return readSessionRunStatus(sessionId);
  },

  getSessionTaskUpdates(sessionId: string): ReadonlyMap<string, AgentTaskUpdate> {
    return sessionTaskUpdates.get(sessionId) ?? EMPTY_TASK_UPDATES;
  },

  // undefined = 尚未拉取(unknown),null = 已确认无 goal——两者必须区分:压平成 null 会让
  // 目标视图在首次快照未返回时就放行创建,把被控端已有目标静默覆盖。
  getGoalStatus(sessionId: string): MobileGoalStatusPayload | null | undefined {
    return sessionGoalStatus.get(sessionId);
  },

  // maker status 驱动的权威 turn 边界(不含 activity / 快照流的宽 running)。孤儿 agent_task
  // 卡的渲染 gate 用它:与 turn-start 清理同源,保证「渲染开启时 map 必已清过 stale」。
  isSessionMakerTurnRunning(sessionId: string): boolean {
    return sessionMakerTurnRunning.get(sessionId) === true;
  },

  subscribe(cb: () => void): () => void {
    subs.add(cb);
    return () => subs.delete(cb);
  },

  subscribeHomeStatus(cb: () => void): () => void {
    homeStatusSubs.add(cb);
    return () => homeStatusSubs.delete(cb);
  },

  subscribeSessionMessagePreview(sessionId: string, cb: () => void): () => void {
    const listeners = sessionMessagePreviewSubs.get(sessionId) ?? new Set<() => void>();
    listeners.add(cb);
    sessionMessagePreviewSubs.set(sessionId, listeners);
    return () => {
      listeners.delete(cb);
      if (listeners.size === 0) sessionMessagePreviewSubs.delete(sessionId);
    };
  },
};

sessionMessageLifecycle.setReclaimer((sessionId, reason) =>
  remoteSessionStore.releaseSessionRuntimeState(sessionId, { reason }));

function dedupeInteractions(list: readonly PendingInteraction[]): PendingInteraction[] {
  const byId = new Map<string, PendingInteraction>();
  for (const item of list) {
    byId.set(interactionDedupeKey(item), item);
  }
  return sortPendingInteractions([...byId.values()]);
}

function remoteSessionListsEqual(a: readonly RemoteSession[], b: readonly RemoteSession[]): boolean {
  return recordListsEqual(a, b, remoteSessionEqual);
}

function remoteMessageListsEqual(a: readonly RemoteMessage[], b: readonly RemoteMessage[]): boolean {
  return recordListsEqual(a, b, remoteMessageEqual);
}

function recordListsEqual<T>(
  a: readonly T[],
  b: readonly T[],
  equal: (left: T, right: T) => boolean,
): boolean {
  if (a === b) return true;
  if (a.length !== b.length) return false;
  for (let i = 0; i < a.length; i += 1) {
    if (!equal(a[i], b[i])) return false;
  }
  return true;
}

function remoteSessionEqual(a: RemoteSession, b: RemoteSession): boolean {
  return shallowRecordEqual(a as unknown as Record<string, unknown>, b as unknown as Record<string, unknown>);
}

function remoteMessageEqual(a: RemoteMessage, b: RemoteMessage): boolean {
  return shallowRecordEqual(a as unknown as Record<string, unknown>, b as unknown as Record<string, unknown>);
}

function deviceListsEqual(
  a: readonly { deviceId: string; name: string }[] | null,
  b: readonly { deviceId: string; name: string }[],
): boolean {
  if (!a || a.length !== b.length) return false;
  for (let i = 0; i < a.length; i += 1) {
    if (a[i].deviceId !== b[i].deviceId || a[i].name !== b[i].name) return false;
  }
  return true;
}

function conversationSearchDeviceModelsEqual(
  a: readonly { canOpen: boolean; deviceId: string; name: string | null; state: string }[],
  b: readonly { canOpen: boolean; deviceId: string; name: string | null; state: string }[],
): boolean {
  if (a.length !== b.length) return false;
  for (let i = 0; i < a.length; i += 1) {
    if (
      a[i].deviceId !== b[i].deviceId
      || a[i].name !== b[i].name
      || a[i].canOpen !== b[i].canOpen
      || a[i].state !== b[i].state
    ) {
      return false;
    }
  }
  return true;
}

function readSessionRunStatus(sessionId: string): RemoteSessionRunStatus {
  return sessionRunStatus.get(sessionId) ?? EMPTY_SESSION_RUN_STATUS;
}

function clearSessionReconnectAttempt(sessionId: string): boolean {
  const current = readSessionRunStatus(sessionId);
  if (!current.reconnectAttempt) return false;
  return writeSessionRunStatus(sessionId, { ...current, reconnectAttempt: null });
}

function markSessionMakerActivity(sessionId: string): void {
  makerActivityEpoch += 1;
  sessionMakerActivityEpochs.set(sessionId, makerActivityEpoch);
}

function parseAttemptPair(
  match: RegExpExecArray | null,
): { attempt: number; maxAttempts: number } | null {
  if (!match) return null;
  const attempt = Number(match[1]);
  const maxAttempts = Number(match[2]);
  if (
    !Number.isSafeInteger(attempt)
    || !Number.isSafeInteger(maxAttempts)
    || attempt < 1
    || maxAttempts < attempt
  ) {
    return null;
  }
  return { attempt, maxAttempts };
}

/**
 * 非终止 error 的 message → 重试进度。
 *
 * 三类各有自己的标记:
 *  - 传输层重连: `Reconnecting... N/M`;
 *  - 上游过载退避重投: `(auto-retry N/M)`(maker-core 的
 *    agents/shared/overload-error.ts 统一后缀, Codex 与 Claude 两侧同款)。
 *  - daemon 终态 429 外层重投: reason=`terminal-rate-limit-retry` +
 *    `(rate-limit-retry N/M)`;reason 与 marker 必须同时命中。
 *
 * 过载 marker 不认的话, 整个退避窗口(交互式最长约 30s)手机端只显示笼统的「思考中」, 用户看不出
 * 是在等上游容量(review #844 codex P1)。这里刻意在 mobile 侧独立实现一份判定, 与
 * renderer 的 utils/overloadError.ts 同规 —— maker-core 是 desktop/node 侧包, 不跨
 * bundle 共享。
 */
const TERMINAL_RATE_LIMIT_RETRY_REASON = 'terminal-rate-limit-retry';

function parseReconnectAttemptMessage(
  message: string,
  reason?: string | null,
): RemoteSessionReconnectAttempt | null {
  if (reason === TERMINAL_RATE_LIMIT_RETRY_REASON) {
    const rateLimit = parseAttemptPair(
      /\(rate-limit-retry\s+(\d+)\s*\/\s*(\d+)\)\s*$/i.exec(message),
    );
    return rateLimit ? { ...rateLimit, kind: 'rate-limit' } : null;
  }
  const reconnect = parseAttemptPair(
    /\bReconnecting(?:\.{3}|…)\s*(\d+)\s*\/\s*(\d+)\b/i.exec(message),
  );
  // 重连保持不带 kind: 既有投影/用例把它当 { attempt, maxAttempts } 精确比较, 而
  // 「缺省即 reconnect」本来就是这个字段的语义(见类型注释)。
  if (reconnect) return reconnect;
  const overload = parseAttemptPair(/\(auto-retry\s+(\d+)\s*\/\s*(\d+)\)\s*$/i.exec(message));
  if (overload) return { ...overload, kind: 'overload' };
  return null;
}

// 写 maker turn 边界,返回是否实际变化——变化必须参与调用方的 emit 判定(宽 run status
// 可能已被 activity / 快照流改到相同值,单靠 writeSessionRunStatus 的返回值会漏通知)。
function clearLiveGenerationOnWideRunStart(
  current: RemoteSessionRunStatus,
  next: RemoteSessionRunStatus,
): RemoteSessionRunStatus {
  if (current.isRunning || !next.isRunning) return next;
  // Activity / snapshot / setSessionRunning can flip the wide running flag
  // before the next maker status. Leftover tok/s belongs to the previous
  // turn and must not flash. Maker status still writes authoritative live
  // fields afterwards (including reconnect first-status).
  return {
    ...next,
    outputTokens: 0,
    tokenSpeed: undefined,
    generationDurationMs: 0,
    generationActive: false,
    generationReliable: true,
  };
}

function writeMakerTurnRunning(sessionId: string, running: boolean): boolean {
  const prev = sessionMakerTurnRunning.get(sessionId) === true;
  if (!running) activePendingHostAnchorRoundIds.delete(sessionId);
  if (running === prev) return false;
  if (running) sessionMakerTurnRunning.set(sessionId, true);
  else {
    sessionMakerTurnRunning.delete(sessionId);
    sessionMessageLifecycle.retryPendingReclaim(sessionId);
  }
  return true;
}

function writeSessionRunStatus(sessionId: string, next: RemoteSessionRunStatus): boolean {
  const current = readSessionRunStatus(sessionId);
  if (next.isRunning && !current.isRunning && current.hasTerminalError) {
    next = { ...next, hasTerminalError: false };
  }
  if (shallowRecordEqual(current as unknown as Record<string, unknown>, next as unknown as Record<string, unknown>)) {
    return false;
  }
  const wasRunning = sessionRunning.get(sessionId) === true;
  sessionRunStatus.set(sessionId, next);
  if (next.isRunning) sessionRunning.set(sessionId, true);
  else {
    sessionRunning.delete(sessionId);
    sessionMessageLifecycle.retryPendingReclaim(sessionId);
  }
  if (wasRunning !== next.isRunning) bumpHomeStatusVersion();
  return true;
}

function buildSessionMessageSyncMarker(session: Pick<RemoteSession, '_count' | 'updatedAt' | 'preview'>): SessionMessageSyncMarker {
  const count = session._count?.messages;
  return {
    updatedAt: session.updatedAt,
    preview: session.preview,
    messageCount: typeof count === 'number' && Number.isFinite(count) ? count : null,
  };
}

function sessionMessageSyncMarkersEqual(
  marker: SessionMessageSyncMarker,
  next: SessionMessageSyncMarker,
): boolean {
  if (marker.updatedAt !== next.updatedAt) return false;
  if (next.messageCount === null) return true;
  return marker.messageCount === next.messageCount;
}

function writeSessionLiveActivity(sessionId: string, next: RemoteSessionLiveActivity): boolean {
  const current = sessionLiveActivity.get(sessionId);
  if (current && shallowRecordEqual(
    current as unknown as Record<string, unknown>,
    next as unknown as Record<string, unknown>,
  )) {
    return false;
  }
  sessionLiveActivity.set(sessionId, next);
  bumpHomeStatusVersion();
  return true;
}

function isRemoteSessionLiveActivityPhase(value: string | null): value is SessionActivityPayload['phase'] {
  return value === 'running' || value === 'needs-interaction' || value === 'completed' || value === 'error';
}

function isTerminalMakerErrorEvent(event: Record<string, unknown>): boolean {
  if (readString(event, 'type') !== 'error') return false;
  const data = isRecord(event.data) ? event.data : null;
  if (!data) return true;
  if (typeof data.isTerminal === 'boolean') return data.isTerminal;
  if (typeof data.willRetry === 'boolean') return !data.willRetry;
  return true;
}

function shallowRecordEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
  if (a === b) return true;
  const aKeys = Object.keys(a);
  const bKeys = Object.keys(b);
  if (aKeys.length !== bKeys.length) return false;
  for (const key of aKeys) {
    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
    if (!deepValueEqual(a[key], b[key])) return false;
  }
  return true;
}

function deepValueEqual(a: unknown, b: unknown): boolean {
  if (Object.is(a, b)) return true;
  if (Array.isArray(a) || isRecord(a)) {
    return safeStableStringify(a) === safeStableStringify(b);
  }
  if (Array.isArray(b) || isRecord(b)) return false;
  return false;
}

function interactionDedupeKey(item: PendingInteraction): string {
  const requestId = item.request.requestId;
  if (typeof requestId === 'string' && requestId.length > 0) return `request:${requestId}`;
  if (item.persistId) return `persist:${item.persistId}`;
  return `request-shape:${safeStableStringify(item.request)}`;
}

function safeStableStringify(value: unknown): string {
  try {
    return JSON.stringify(value);
  } catch {
    return String(value);
  }
}

/** 旧 compact_boundary 没有 provider id 时的确定性 replay identity。 */
function compactBoundaryFingerprint(data: Record<string, unknown>): string {
  const canonical = canonicalJson(data);
  return `${fnv1aHex(canonical, 0x811c9dc5)}${fnv1aHex(canonical, 0x9e3779b9)}`;
}

function canonicalJson(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
  if (isRecord(value)) {
    return `{${Object.keys(value)
      .sort()
      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
      .join(',')}}`;
  }
  return JSON.stringify(value) ?? String(value);
}

function fnv1aHex(value: string, seed: number): string {
  let hash = seed >>> 0;
  for (let index = 0; index < value.length; index += 1) {
    hash ^= value.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash.toString(16).padStart(8, '0');
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return !!value && typeof value === 'object' && !Array.isArray(value);
}

function readPushedNewMakerWorktreeEnabled(payload: unknown): boolean | null {
  if (!isRecord(payload)) return null;
  for (const slot of ['claudeCode', 'codex'] as const) {
    const defaults = payload[slot];
    if (!isRecord(defaults)) continue;
    const enabled = defaults.worktreeEnabled;
    if (typeof enabled === 'boolean') return enabled;
  }
  return null;
}

function readPushedNewMakerWorktreeBranchPreference(
  payload: unknown,
): RemoteNewMakerWorktreeBranchPreference {
  if (!isRecord(payload)) return null;
  const baseRepo = payload.baseRepo;
  const sourceBranch = payload.sourceBranch;
  const revision = payload.revision;
  if (
    typeof baseRepo !== 'string'
    || !baseRepo.trim()
    || typeof sourceBranch !== 'string'
    || !sourceBranch.trim()
    || !Number.isInteger(revision)
    || (revision as number) < 0
  ) return null;
  return {
    baseRepo: baseRepo.trim(),
    sourceBranch: sourceBranch.trim(),
    revision: revision as number,
  };
}

function hasDeviceLinkTruncationMarker(value: Record<string, unknown> | null): boolean {
  return value?.[DEVICE_LINK_TRUNCATED_FLAG] === true;
}

function readString(value: unknown, key: string): string | null {
  const raw = isRecord(value) ? value[key] : null;
  return typeof raw === 'string' && raw.length > 0 ? raw : null;
}

function readNumber(value: unknown, key: string): number | null {
  const raw = isRecord(value) ? value[key] : null;
  return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
}

const RemoteSessionStoreSubscriptionContext = createContext<PausableSubscriptions | null>(null);

/**
 * Keep a mounted route's remote-session projection stable while it is covered by another screen.
 * The store itself keeps receiving data; consumers resubscribe and jump to the latest snapshot when
 * the route regains focus. This preserves native list state without rendering hidden row trees for
 * every streaming token.
 */
export function RemoteSessionStoreSubscriptionGate({
  children,
  enabled,
}: {
  children: ReactNode;
  enabled: boolean;
}) {
  const gateRef = useRef<PausableSubscriptions | null>(null);
  if (!gateRef.current) gateRef.current = new PausableSubscriptions(enabled);
  const gate = gateRef.current;
  useLayoutEffect(() => {
    gate.setEnabled(enabled);
    return () => gate.setEnabled(false);
  }, [gate, enabled]);
  return createElement(
    RemoteSessionStoreSubscriptionContext.Provider,
    { value: gate },
    children,
  );
}

const NOOP_SUBSCRIBE = () => () => undefined;

/**
 * Visibility of the surrounding route (RemoteSessionStoreSubscriptionGate). Covered routes keep
 * their rows mounted without re-rendering them, so side effects such as remote polling must
 * check `isActive()` before running and use `onResume` to catch up when the route is shown again.
 */
export function useRemoteSessionStoreVisibility(): {
  isActive: () => boolean;
  onResume: (callback: () => void) => () => void;
} {
  const gate = useContext(RemoteSessionStoreSubscriptionContext);
  return useMemo(() => ({
    isActive: () => (gate ? gate.enabled : true),
    onResume: (callback: () => void) => (gate ? gate.subscribe(NOOP_SUBSCRIBE, callback) : () => undefined),
  }), [gate]);
}

function usePausableRemoteSessionStoreSnapshot<T>(
  identity: unknown,
  getSnapshot: () => T,
  subscribe: (cb: () => void) => () => void = remoteSessionStore.subscribe,
): T {
  const gate = useContext(RemoteSessionStoreSubscriptionContext);
  const frozenSnapshotRef = useRef<{ identity: unknown; value: T } | null>(null);
  const readSnapshot = useCallback(() => {
    const frozen = frozenSnapshotRef.current;
    if (!gate || gate.enabled || frozen === null || !Object.is(frozen.identity, identity)) {
      const next = { identity, value: getSnapshot() };
      frozenSnapshotRef.current = next;
      return next.value;
    }
    return frozen.value;
  }, [gate, getSnapshot, identity]);
  const subscribeWhileActive = useCallback(
    (notify: () => void) => gate ? gate.subscribe(subscribe, notify) : subscribe(notify),
    [gate, subscribe],
  );
  return useSyncExternalStore(
    subscribeWhileActive,
    readSnapshot,
  );
}

export function useRemoteSessions(): RemoteSession[] {
  return usePausableRemoteSessionStoreSnapshot('sessions', remoteSessionStore.getVisibleSessions);
}

/** Link chips observe only their visible targets, not every task's activity. */
export function useRemoteSessionTitles(ids: readonly string[]): Record<string, string> | undefined {
  const read = useCallback(() => {
    if (ids.length === 0) return undefined;
    const sessions = remoteSessionStore.getVisibleSessions();
    const titles: Record<string, string> = {};
    for (const id of ids) {
      const title = sessions.find((session) => session.id === id)?.title?.trim();
      if (title) titles[id] = title;
    }
    return Object.keys(titles).length > 0 ? JSON.stringify(titles) : undefined;
  }, [ids]);
  // A primitive snapshot stays equal on unrelated pushes. Reuse the route's
  // subscription gate so covered conversations remain frozen until resumed.
  const json = usePausableRemoteSessionStoreSnapshot(
    read, read, ids.length > 0 ? remoteSessionStore.subscribe : NOOP_SUBSCRIBE,
  );
  return useMemo(() => json === undefined ? undefined : JSON.parse(json) as Record<string, string>, [json]);
}

/** A hidden child can be opened without making it an ordinary Home list row. */
export function useRemoteSessionDetail(deviceId: string, sessionId: string): RemoteSession | null {
  const read = useCallback(() => remoteSessionStore.getSessions().find(session =>
    session.id === sessionId && session.deviceLinkDeviceId === deviceId) ?? null,
  [deviceId, sessionId]);
  return usePausableRemoteSessionStoreSnapshot(read, read);
}

/** Home rows/actions do not consume usage; session details must use useRemoteSessions. */
export function useRemoteHomeSessions(): RemoteSession[] {
  return usePausableRemoteSessionStoreSnapshot(
    'home-sessions', remoteSessionStore.getHomeSessions, remoteSessionStore.subscribeHomeStatus,
  );
}

export type RemoteSessionUsage = Pick<RemoteSession, 'totalMoney' | 'totalCostUsd' | 'totalTokenUsage'>;
const EMPTY_SESSION_USAGE: RemoteSessionUsage = {};

function sessionUsageEqual(a: RemoteSessionUsage, b: RemoteSessionUsage): boolean {
  return a.totalTokenUsage === b.totalTokenUsage
    && a.totalCostUsd === b.totalCostUsd
    && a.totalMoney?.amount === b.totalMoney?.amount
    && a.totalMoney?.currency === b.totalMoney?.currency
    && a.totalMoney?.kind === b.totalMoney?.kind
    && a.totalMoney?.approximate === b.totalMoney?.approximate;
}

/**
 * One task's live usage for list rows. Home projections strip usage so usage pushes do not
 * rebuild grouping; a row that displays tokens or cost subscribes here instead and only
 * re-renders when its own numbers change.
 */
export function useRemoteSessionUsage(sessionId: string, enabled = true): RemoteSessionUsage {
  const previousRef = useRef<RemoteSessionUsage>(EMPTY_SESSION_USAGE);
  const readUsage = useCallback(() => {
    const session = enabled ? sessionById(sessionId) : undefined;
    const next: RemoteSessionUsage = session
      ? { totalCostUsd: session.totalCostUsd, totalMoney: session.totalMoney, totalTokenUsage: session.totalTokenUsage }
      : EMPTY_SESSION_USAGE;
    if (sessionUsageEqual(previousRef.current, next)) return previousRef.current;
    previousRef.current = next;
    return next;
  }, [enabled, sessionId]);
  return usePausableRemoteSessionStoreSnapshot(readUsage, readUsage);
}

/** Device identity can change without changing any session's reconciled reference. */
export function useRemoteDeviceIdentity() {
  return usePausableRemoteSessionStoreSnapshot('device-identity', remoteSessionStore.getDeviceIdentity);
}

/** Search reachability changes independently of message and home-status updates. */
export function useRemoteConversationSearchDeviceModels() {
  return usePausableRemoteSessionStoreSnapshot(
    'conversation-search-devices',
    remoteSessionStore.getConversationSearchDeviceModels,
  );
}

/** Subscribe to one session's message mirror without triggering cache hydration side effects. */
export function useRemoteSessionMessages(sessionId: string): RemoteMessage[] {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getMessages(sessionId),
  );
}

/** Subscribe to one session's loaded message preview without waking the home-list root. */
export function useRemoteSessionMessagePreview(sessionId: string): string | undefined {
  const subscribe = useCallback(
    (cb: () => void) => remoteSessionStore.subscribeSessionMessagePreview(sessionId, cb),
    [sessionId],
  );
  return usePausableRemoteSessionStoreSnapshot(
    `message-preview:${sessionId}`,
    useCallback(() => remoteSessionStore.getSessionListMessagePreview(sessionId), [sessionId]),
    subscribe,
  );
}

// 本地「最近消息」缓存持久化的去抖间隔:消息流式更新很频繁,只在静默一小段后落盘一次。
const SESSION_MESSAGE_CACHE_PERSIST_DEBOUNCE_MS = 600;

export function useSessionMessages(sessionId: string, deviceId?: string): RemoteMessage[] {
  const messages = useRemoteSessionMessages(sessionId);
  useSessionMessageCacheSync(sessionId, deviceId, messages);
  return messages;
}

// 数据层接线:首次访问某 (deviceId, sessionId) 时从本地缓存乐观 hydrate;消息更新后去抖持久化。
// 写在 store 层(非 render 层),屏幕只管把已有的 deviceId 传进来。
function useSessionMessageCacheSync(
  sessionId: string,
  deviceId: string | undefined,
  messages: RemoteMessage[],
): void {
  const hydratedKeyRef = useRef<string | null>(null);
  const persistTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const retention = useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getSessionRetention(sessionId),
  );
  const authoritySnapshot = useSyncExternalStore(
    sessionMessageLifecycle.subscribe,
    () => sessionMessageLifecycle.getSnapshot(sessionId),
  );
  // 持久化在定时器回调里读最新值,避免把每次渲染的 messages 都闭包进 timer。
  const ctxRef = useRef<{ deviceId?: string; sessionId: string; messages: RemoteMessage[] }>({
    deviceId,
    sessionId,
    messages,
  });
  ctxRef.current = { deviceId, sessionId, messages };

  // 乐观 hydrate:每个 (deviceId, sessionId) 只跑一次;缓存回来时若 store 仍为空才种入。
  useEffect(() => {
    if (!deviceId || !sessionId || retention !== 'regular') return;
    const authority = remoteSessionStore.captureSessionMessageAuthority(sessionId);
    if (!remoteSessionStore.isSessionMessageAuthorityCurrent(authority)) return;
    const cacheAuthority = captureSessionMessageCacheWriteAuthority(deviceId, sessionId);
    if (!cacheAuthority) return;
    const key = `${deviceId}::${sessionId}`;
    if (hydratedKeyRef.current === key) return;
    hydratedKeyRef.current = key;
    let cancelled = false;
    void getCachedSessionMessages(deviceId, sessionId)
      .then((cached) => {
        if (cancelled || cached.length === 0) return;
        // 消息 authority 只表示页面仍是同一详情代际;权威空窗口、删除、rewind 或
        // schedule 改判不会撤销页面本身。缓存 key epoch 必须另行校验,防止这些
        // 事件发生前启动的旧 getItem 在清空后把已删除正文重新 hydrate 回内存。
        if (!isSessionMessageCacheWriteAuthorityCurrent(cacheAuthority)) return;
        if (remoteSessionStore.getSessionRetention(sessionId) !== 'regular') return;
        if (!remoteSessionStore.isSessionMessageAuthorityCurrent(authority)) return;
        remoteSessionStore.hydrateMessagesIfEmpty(sessionId, cached, { authority });
      })
      .catch(() => undefined);
    return () => {
      cancelled = true;
      if (hydratedKeyRef.current === key) hydratedKeyRef.current = null;
    };
  }, [authoritySnapshot, deviceId, retention, sessionId]);

  // schedule 不读写长期完整消息缓存。分类晚到时也会走这条定点删除;缓存模块
  // 对同 key 串行,能保证删除排在已经开始的旧写之后。
  useEffect(() => {
    if (!deviceId || !sessionId || retention !== 'schedule') return;
    if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
    persistTimerRef.current = null;
    void replaceCachedSessionMessages(deviceId, sessionId, []).catch(() => undefined);
  }, [deviceId, retention, sessionId]);

  // 去抖持久化:messages 变化时重排定时器,静默后落盘最新快照。
  useEffect(() => {
    if (persistTimerRef.current) clearTimeout(persistTimerRef.current);
    persistTimerRef.current = null;
    if (!deviceId || !sessionId || retention !== 'regular') return;
    const key = `${deviceId}::${sessionId}`;
    // 空内存可能只是 regular LRU 淘汰,绝不能据此删除磁盘缓存。真正的远端
    // 删除由 removeMessages / 权威空窗显式处理。
    if (messages.length === 0) return;
    const cacheAuthority = captureSessionMessageCacheWriteAuthority(deviceId, sessionId);
    persistTimerRef.current = setTimeout(() => {
      persistTimerRef.current = null;
      const ctx = ctxRef.current;
      if (!ctx.deviceId || !ctx.sessionId || ctx.messages.length === 0) return;
      if (`${ctx.deviceId}::${ctx.sessionId}` !== key) return;
      if (remoteSessionStore.getSessionRetention(ctx.sessionId) !== 'regular') return;
      void cacheSessionMessagesIfCurrent(cacheAuthority, ctx.messages).catch(() => undefined);
    }, SESSION_MESSAGE_CACHE_PERSIST_DEBOUNCE_MS);
  }, [deviceId, messages, retention, sessionId]);

  // 卸载时把尚未落盘的最新快照立即 flush(防止快速返回导致最后一次更新丢失)。
  useEffect(() => () => {
    if (!persistTimerRef.current) return;
    clearTimeout(persistTimerRef.current);
    persistTimerRef.current = null;
    const ctx = ctxRef.current;
    if (!ctx.deviceId || !ctx.sessionId) return;
    if (remoteSessionStore.getSessionRetention(ctx.sessionId) !== 'regular') return;
    // Store ingress can precede the last React render. A fresh write authority
    // must use fresh rows, never the render snapshot from before an outbox handoff.
    const latestMessages = remoteSessionStore.getMessages(ctx.sessionId);
    if (latestMessages.length === 0) return;
    const cacheAuthority = captureSessionMessageCacheWriteAuthority(ctx.deviceId, ctx.sessionId);
    void cacheSessionMessagesIfCurrent(cacheAuthority, latestMessages).catch(() => undefined);
  }, []);
}

export function useRemoteMessageVersion(enabled = true): number {
  return usePausableRemoteSessionStoreSnapshot(
    enabled ? 'message-version' : 'message-version-disabled',
    useCallback(
      () => enabled ? remoteSessionStore.getMessageVersion() : 0,
      [enabled],
    ),
  );
}

/** Home-list invalidation for pending/live/running state; ordinary text deltas do not advance it. */
export function useRemoteHomeStatusVersion(): number {
  return usePausableRemoteSessionStoreSnapshot(
    'home-status-version',
    remoteSessionStore.getHomeStatusVersion,
    remoteSessionStore.subscribeHomeStatus,
  );
}

export function useRemoteSessionStoreVersion(): number {
  return usePausableRemoteSessionStoreSnapshot(
    'store-version',
    remoteSessionStore.getStoreVersion,
  );
}

export function useRemoteNewMakerWorktreePreference(
  deviceId: string | null | undefined,
): RemoteNewMakerWorktreePreference {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getNewMakerWorktreePreference(deviceId),
  );
}

export function useRemoteNewMakerWorktreeBranchPreference(
  deviceId: string | null | undefined,
  baseRepo: string | null | undefined,
): RemoteNewMakerWorktreeBranchPreference {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getNewMakerWorktreeBranchPreference(deviceId, baseRepo),
  );
}

export function useSessionPendingInteractions(sessionId: string): PendingInteraction[] {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getVisiblePendingInteractions(sessionId),
  );
}

export function useSessionPendingInteractionsAuthoritative(sessionId: string): boolean {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.hasAuthoritativePendingInteractions(sessionId),
  );
}

export function useSessionInputProjection(sessionId: string): InputProjection {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getInputProjection(sessionId),
  );
}

export function useSessionRunning(sessionId: string): boolean {
  return usePausableRemoteSessionStoreSnapshot(
    sessionId,
    () => remoteSessionStore.isSessionRunning(sessionId),
    remoteSessionStore.subscribeHomeStatus,
  );
}

export function useSessionRunStatus(sessionId: string): RemoteSessionRunStatus {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getSessionRunStatus(sessionId),
  );
}

export function useSessionTaskUpdates(sessionId: string): ReadonlyMap<string, AgentTaskUpdate> {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getSessionTaskUpdates(sessionId),
  );
}

/** 目标模式状态镜像(undefined = 尚未拉取,null = 已确认无 goal;页面打开时用 goal.getStatus 补一次拉取)。 */
export function useSessionGoalStatus(sessionId: string): MobileGoalStatusPayload | null | undefined {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.getGoalStatus(sessionId),
  );
}

export function useSessionMakerTurnRunning(sessionId: string): boolean {
  return useSyncExternalStore(
    remoteSessionStore.subscribe,
    () => remoteSessionStore.isSessionMakerTurnRunning(sessionId),
  );
}