dsh-mobile-plugin 0.1.99 → 0.2.0

package/lib/mobile/stats-ledger.cjs

@@ -42,6 +42,15 @@ const MAX_RETIRED = 2000;
 /** 按天的账保留天数（约三年；一天一百多字节，超出的从最老的开始裁）。 */
 const MAX_DAYS = 1100;
 
+/**
+ * 每条会话自己那份「按天用量」保留多少天。
+ *
+ * 它存在只为回答「这张卡片在这个范围里用了多少」：页面的三档范围最大 30 天，
+ * 再留一倍余量足够；更老的日期按天的总账仍然还在，只是卡片不再按那条会话拆得开。
+ * 不封顶的话，两百条会话 × 三年就是一份几十 MB 的 JSON，每次采集都要整份读写。
+ */
+const MAX_DAILY_DAYS = 62;
+
 /**
  * 热力图最多给多少天（52 周）。
  *
@@ -125,6 +134,18 @@ function sanitizeUsage(source) {
   return usage;
 }
 
+/** 上下文构成快照：三条都缺或全 0 就当没有（别在卡片上画一个 0 的环）。 */
+function readComposition(source) {
+  if (!source || typeof source !== 'object') return null;
+  const composition = {
+    systemTokens: num(source.systemTokens),
+    toolsTokens: num(source.toolsTokens),
+    messageTokens: num(source.messageTokens),
+  };
+  if (composition.systemTokens + composition.toolsTokens + composition.messageTokens <= 0) return null;
+  return { ...composition, at: num(source.at) };
+}
+
 function sanitizeLedger(raw) {
   if (!raw || typeof raw !== 'object') return emptyLedger();
   if (raw.version !== VERSION) return emptyLedger();
@@ -141,6 +162,19 @@ function sanitizeLedger(raw) {
   if (raw.sessions && typeof raw.sessions === 'object') {
     for (const [sessionId, value] of Object.entries(raw.sessions)) {
       if (!sessionId || !value || typeof value !== 'object') continue;
+      const daily = {};
+      if (value.daily && typeof value.daily === 'object') {
+        for (const [day, usageOfDay] of Object.entries(value.daily)) {
+          if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !usageOfDay || typeof usageOfDay !== 'object') continue;
+          daily[day] = sanitizeUsage(usageOfDay);
+        }
+      }
+      const billed = sanitizeUsage(value.billed);
+      // 老账本（2026-10-24 之前）没有每条会话的按天用量：把它的历史量记在它最后一次
+      // 活动那天。这跟「首采回填」是同一条近似，也是一次性回填 —— 之后就只记增量。
+      if (Object.keys(daily).length === 0 && billedOf(billed) > 0) {
+        daily[dayKeyOf(num(value.lastAt) || Date.now())] = { ...billed };
+      }
       ledger.sessions[sessionId] = {
         title: typeof value.title === 'string' ? value.title : '',
         workspaceName: typeof value.workspaceName === 'string' ? value.workspaceName : '',
@@ -152,7 +186,11 @@ function sanitizeLedger(raw) {
         gone: value.gone === true,
         // 退场 = 这条卡片已经不在最近 MAX_SESSIONS 里，只留水位与身份。
         retired: value.retired === true,
-        billed: sanitizeUsage(value.billed),
+        billed,
+        // 这条会话自己那份按天用量：卡片上的数字要跟着页面范围走（见 `rangeUsageOf`）。
+        daily,
+        // 最后一次观测到的上下文构成：跟着会话走，不再全局只留一份。
+        composition: readComposition(value.composition),
         // 水位是「宿主那边这条会话的累计值」，缺省为 null 表示还没采过（首采全量入账）。
         watermark: value.watermark && typeof value.watermark === 'object' ? sanitizeUsage(value.watermark) : null,
       };
@@ -160,6 +198,8 @@ function sanitizeLedger(raw) {
   }
 
   if (raw.composition && typeof raw.composition === 'object') {
+    // 老账本只有一份全局构成（每轮被最后读完的那条覆盖）。留着当兜底：
+    // 没有任何一条会话带自己的构成时才用它。
     ledger.composition = {
       systemTokens: num(raw.composition.systemTokens),
       toolsTokens: num(raw.composition.toolsTokens),
@@ -225,12 +265,40 @@ function trim(ledger) {
       for (const id of pool.slice(MAX_RETIRED)) delete ledger.sessions[id];
     }
   }
+  // 每条会话自己那份按天用量也有上限：它只服务「这张卡片在这个范围里用了多少」，
+  // 最老的那些日子从它自己的账上裁掉，按天的总账不动。
+  for (const record of Object.values(ledger.sessions)) {
+    if (!record.daily) continue;
+    const own = Object.keys(record.daily).sort();
+    if (own.length > MAX_DAILY_DAYS) {
+      for (const day of own.slice(0, own.length - MAX_DAILY_DAYS)) delete record.daily[day];
+    }
+  }
   const days = Object.keys(ledger.days).sort();
   if (days.length > MAX_DAYS) {
     for (const day of days.slice(0, days.length - MAX_DAYS)) delete ledger.days[day];
   }
 }
 
+/** 账本里一条会话记录的初始形状（`applyDelta` 与读盘兜底共用一份）。 */
+function emptySession(at) {
+  return {
+    title: '',
+    workspaceName: '',
+    lastText: '',
+    cwd: '',
+    firstAt: at,
+    lastAt: 0,
+    collectedAt: 0,
+    gone: false,
+    retired: false,
+    billed: emptyUsage(),
+    daily: {},
+    composition: null,
+    watermark: null,
+  };
+}
+
 /**
  * 把一次采集到的增量记进账本（纯函数，原地改并返回它）。
  *
@@ -250,20 +318,12 @@ function applyDelta(ledger, entry) {
   // 与 dsh-context 的 requests 口径差不到一条结算的距离。
   day.requests += delta.steps;
 
-  const record = ledger.sessions[sessionId] || (ledger.sessions[sessionId] = {
-    title: '',
-    workspaceName: '',
-    lastText: '',
-    cwd: '',
-    firstAt: at,
-    lastAt: 0,
-    collectedAt: 0,
-    gone: false,
-    retired: false,
-    billed: emptyUsage(),
-    watermark: null,
-  });
+  const record = ledger.sessions[sessionId] || (ledger.sessions[sessionId] = emptySession(at));
   for (const key of USAGE_KEYS) record.billed[key] += delta[key];
+  // 这条会话自己那份按天用量：卡片的数字要跟页面范围走，所以增量在「记哪一天」这件事上
+  // 必须和按天的总账记在同一个日期上（首采回填也是同一天）。
+  const ownDay = record.daily[date] || (record.daily[date] = emptyUsage());
+  for (const key of USAGE_KEYS) ownDay[key] += delta[key];
   record.lastAt = Math.max(record.lastAt, at);
   if (!record.firstAt) record.firstAt = at;
   // 退场的卡片又有了新用量：回到列表里来（水位一直在，所以这次只记增量）。
@@ -283,11 +343,33 @@ function billedOf(usage) {
   return num(usage.uncachedInputTokens) + num(usage.cacheReadTokens) + num(usage.cacheWriteTokens) + num(usage.outputTokens);
 }
 
+/**
+ * 一条会话在 [startDay, today] 里的用量。
+ *
+ * `startDay` 为 null（`all`）时直接用记录里的累计值 —— 累计值是权威，而它那份按天用量
+ * 只保留最近 `MAX_DAILY_DAYS` 天。
+ */
+function usageInRange(record, startDay, today) {
+  const billed = record.billed || emptyUsage();
+  if (!startDay) return sanitizeUsage(billed);
+  const usage = emptyUsage();
+  const daily = record.daily || {};
+  for (const [day, value] of Object.entries(daily)) {
+    if (day < startDay || day > today) continue;
+    for (const key of USAGE_KEYS) usage[key] += num(value[key]);
+  }
+  return usage;
+}
+
 /**
  * 按范围折算成 App 要的总览（纯函数）。
  *
  * 逐日序列会把范围内**每一天都列出来**（没有活动的补 0）：柱状图靠它保持等距，
  * 由页面决定怎么省略日期标签。
+ *
+ * 三块口径必须对得上（2026-10-24 改）：`kpi` 是范围内总量，`sessions` 里的每张卡片是
+ * **这条会话在同一个范围里**的用量，`retired` / `untracked` 把不在卡片上的那部分明说出来 ——
+ * 卡片加起来永远解释不了总量，是这个页面被读成「数据对不上」的根源。
  */
 function summarize(ledger, range, now) {
   const today = dayKeyOf(now);
@@ -336,6 +418,7 @@ function summarize(ledger, range, now) {
     if (point.requests > 0 || point.turns > 0) kpi.days += 1;
   }
   kpi.activeMs = kpi.llmMs + kpi.toolMs;
+  const rangeBilled = billedOf(kpi);
 
   // 热力图给足最近 52 周（364 天）：手机上只画得下 8 周，iPad 横屏能摊到三十周上下 ——
   // 窗口由页面按自己的宽度截最后几周，宿主这边一律给满，否则宽屏想多画也没有数据。
@@ -346,20 +429,42 @@ function summarize(ledger, range, now) {
     heatmap.push({ day, tokens: source ? billedOf(source) : 0 });
   }
 
-  const rangeStartAt = startDay ? new Date(`${startDay}T00:00:00`).getTime() : 0;
   const sessions = [];
+  let retiredSessions = 0;
+  let retiredBilled = 0;
+  // 构成快照取「最近有动作的那条会话」：每轮只在不是同一条时换，不再被并发读完的最后一条覆盖。
+  let composition = null;
+  let compositionSession = null;
   for (const [sessionId, record] of Object.entries(ledger.sessions)) {
-    // 退场记录只留水位，不上卡片：它的量早就记在按天的账上了。
-    if (record.retired === true) continue;
-    if (rangeStartAt > 0 && num(record.lastAt) < rangeStartAt) continue;
+    const usage = usageInRange(record, startDay, today);
+    if (record.retired === true) {
+      // 退场记录只留水位，不上卡片：它的量早就记在按天的账上了。范围里有量时在汇总行报个数。
+      const billed = billedOf(usage);
+      if (billed > 0) {
+        retiredSessions += 1;
+        retiredBilled += billed;
+      }
+      continue;
+    }
+    if (record.composition && num(record.lastAt) > num(compositionSession && compositionSession.lastAt)) {
+      composition = {
+        systemTokens: num(record.composition.systemTokens),
+        toolsTokens: num(record.composition.toolsTokens),
+        messageTokens: num(record.composition.messageTokens),
+      };
+      compositionSession = { lastAt: num(record.lastAt), sessionId, title: record.title || '' };
+    }
+    const billedTokens = billedOf(usage);
+    // 范围内一个 token、一轮都没有的会话不上卡片：切到「近 7 天」时老会话不该占着位置。
+    if (billedTokens === 0 && num(usage.turns) === 0) continue;
     sessions.push({
       sessionId,
       title: record.title || '',
       ...(record.workspaceName ? { workspaceName: record.workspaceName } : {}),
       ...(record.cwd ? { cwd: record.cwd } : {}),
       ...(record.lastText ? { lastText: record.lastText } : {}),
-      billedTokens: billedOf(record.billed),
-      turns: num(record.billed.turns),
+      billedTokens,
+      turns: num(usage.turns),
       lastAt: num(record.lastAt),
       ...(record.gone ? { gone: true } : {}),
     });
@@ -373,13 +478,25 @@ function summarize(ledger, range, now) {
   });
   kpi.sessions = sessions.length;
 
+  // 卡片 + 退场合计之后仍然少的那一截：老版本把整条记录删掉过（水位与明细都没了），
+  // 按天的账上却还留着那些天。明说出来，别让用户自己拿计算器发现差额。
+  // 只报量、不报条数 —— 那些会话连记录都没了，条数是编不出来的。
+  const tracked = sessions.reduce((sum, row) => sum + row.billedTokens, 0) + retiredBilled;
+  const untrackedBilled = Math.max(0, rangeBilled - tracked);
+
+  // 没有任何一条会话带自己的构成时（升级前的老账本），退回那份全局快照。
+  if (!composition && ledger.composition) composition = { ...ledger.composition };
+
   return {
     generatedAt: now,
     range,
     kpi,
     days,
     heatmap,
-    ...(ledger.composition ? { composition: ledger.composition } : {}),
+    ...(composition ? { composition } : {}),
+    ...(compositionSession ? { compositionSessionId: compositionSession.sessionId } : {}),
+    retired: { sessions: retiredSessions, tokens: retiredBilled },
+    untrackedBilled,
     sessions,
   };
 }
@@ -389,6 +506,7 @@ module.exports = {
   MAX_SESSIONS,
   MAX_RETIRED,
   MAX_DAYS,
+  MAX_DAILY_DAYS,
   HEATMAP_DAYS,
   LAST_TEXT_MAX,
   stateFile,
@@ -403,5 +521,6 @@ module.exports = {
   startDayOf,
   emptyUsage,
   billedOf,
+  usageInRange,
   num,
 };

package/lib/mobile/stream-registry.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * 按设备登记的 SSE 流。
+ *
+ * token 换了只保证**下一次请求**被拒；一条已经开着的流不会自己断，被踢的手机还能继续收
+ * 消息，直到它自己重连。不做这一步，「单台吊销」就只完成了一半。
+ *
+ * 登记表按 deviceId 分组：同一台手机可能同时开着两条流（会话流 + 设备级事件流），
+ * 两台手机之间互不影响。收流由吊销那条路径调 `drop`，逐条 `end()` 掉。
+ *
+ * 这里**不做超时与配额**：宿主本来就是给自己那几台设备推东西，流的上限由它们自己的
+ * 打开次数决定，加一层闸只会把「手机连着却收不到」变成一种新的失败形态。
+ */
+const streams = new Map();
+
+/**
+ * 登记一条流。
+ *
+ * @param {string} deviceId 设备 id（凭据记录上的 `deviceId`）
+ * @param {object} res 这条流的响应对象（只需要 `end` 与 `destroy`）
+ * @returns {() => void} 注销函数；流自己关掉时调用，避免表越攒越大
+ */
+function track(deviceId, res) {
+  const key = typeof deviceId === 'string' ? deviceId : '';
+  if (!key || !res) return () => {};
+  let set = streams.get(key);
+  if (!set) {
+    set = new Set();
+    streams.set(key, set);
+  }
+  set.add(res);
+  return () => {
+    const current = streams.get(key);
+    if (!current) return;
+    current.delete(res);
+    if (current.size === 0) streams.delete(key);
+  };
+}
+
+/**
+ * 收掉这台设备上所有已建立的流。
+ *
+ * 先 `end()` 再 `destroy()`：`end` 让对端看到正常的流结束（App 会在下一次请求上收到
+ * `device-revoked`，而不是一个「网络出错」）；对已经卡住的连接 `destroy` 是兜底。
+ *
+ * @returns {number} 实际收掉了多少条
+ */
+function drop(deviceId) {
+  const key = typeof deviceId === 'string' ? deviceId : '';
+  const set = streams.get(key);
+  if (!set) return 0;
+  streams.delete(key);
+  let closed = 0;
+  for (const res of set) {
+    closed += 1;
+    try { res.end?.(); } catch { /* 对端已经走了 */ }
+    try { res.destroy?.(); } catch { /* 同上 */ }
+  }
+  return closed;
+}
+
+/** 测试与自检用：当前登记了多少条流。 */
+function size() {
+  let total = 0;
+  for (const set of streams.values()) total += set.size;
+  return total;
+}
+
+/** 测试用：清空登记表。 */
+function reset() { streams.clear(); }
+
+module.exports = { track, drop, size, reset };

package/lib/mobile/stream.js

@@ -24,6 +24,9 @@
  */
 
 const { sendJson } = require('../shared/http-util');
+const e2ee = require('../shared/e2ee');
+const { headerOf, wrapper, signedPath } = require('../shared/e2ee-request');
+const { ACCEPT_ENC_HEADER, compressPlain } = require('../shared/e2ee-plain');
 const {
   writeSse: sharedWriteSse,
   waitForDrain,
@@ -36,6 +39,9 @@ const { unwrap } = require('./envelope.js');
 const { normalizeJobs } = require('./jobs.js');
 const approvals = require('./approvals.js');
 const questions = require('./questions.js');
+const streamRegistry = require('./stream-registry.js');
+const { credentialsEntry } = require('../shared/credentials-entry.js');
+const { viaChannel } = require('../shared/via-header');
 
 // Android React Native's XHR may buffer tiny chunked responses until its
 // internal progress threshold. Keep each window of records padded past that
@@ -54,6 +60,24 @@ const SSE_FLUSH_PADDING_BYTES = 2048;
 const SSE_PAD_MIN_INTERVAL_MS = 120;
 const REPLAY_WINDOW = 3000; // 断线补偿回放的最大事件数
 
+/**
+ * 一次断线重放最多灌多少字节。
+ *
+ * `REPLAY_WINDOW` 按事件条数限量，挡不住「几百条事件、每个都带大附件」的会话：实测有
+ * 一条会话单次重放 36MB，同一个游标被反复重放一天烧掉 450MB。到了这条线就不补了，
+ * 改成让客户端去按页拉权威历史 —— 那条路一页两百条、实测几十 KB，便宜一个数量级。
+ */
+const REPLAY_MAX_BYTES = 512 * 1024;
+
+/**
+ * 缺口超过这个跨度就干脆不回放。
+ *
+ * 客户端落后得这么远时，把窗口整个灌过去再让它去拉历史，等于同一段内容走了两遍
+ * （App 收到 resync 帧本来就会做一次全量 authoritative 拉取）。这个值远小于
+ * `REPLAY_WINDOW`：只补「刚刚断线这几下」的缺口，剩下的交给分页历史。
+ */
+const REPLAY_MAX_GAP = 200;
+
 /**
  * keepalive 节奏，同时也是 `session/heartbeat` 的间隔。
  *
@@ -136,6 +160,9 @@ function writeSse(res, payload, frame, options = {}) {
     // 回放也不覆盖这一段）。它一次审批也就一两帧，不是撑爆写队列的那类帧。
     // 心跳同理必须保住：丢了它，App 会把一条健康的流判成死链（见 isLivenessHeartbeat）。
     shedWhenBuffered: (value) => !isApprovalPayload(value) && !isLivenessHeartbeat(value) && shedWithoutSeq(value),
+    // 协议 v2：每帧一条独立密文（§8.3(5)）。封装器由开流那一处给 —— 它才知道这条流的
+    // 请求 ts / nonce 与帧序号（AAD 要绑这三样）。
+    sealFrame: typeof options.sealFrame === 'function' ? options.sealFrame : null,
   });
 }
 
@@ -191,6 +218,35 @@ function parseResumeSeq(req, sessionId) {
  * SSE：订阅宿主事件流，仅转发目标会话的 session/event 帧（增量事件），
  * 每 15s 发一行注释保持连接；客户端断开即取消订阅。
  */
+/**
+ * 造这条流的帧封装器（§8.3(5)）。
+ *
+ * AAD 绑「路径 + 请求的 ts/nonce + 帧序号」：前三个把这一帧钉死在这条流上（别的流、
+ * 上一次连接都塞不进来），帧序号再挡住「把上一段流的帧插到这一段里」，顺带让客户端能发现丢帧。
+ *
+ * 帧序号从 1 起、宿主自己数、不进明文。
+ *
+ * 逐帧也先压再封（`x-dsh-accept-enc` 带 `g` 时）：一轮流式回复里带完整正文的
+ * `assistant/message` 常常几十 KB，草稿增量里的中文也压得很动，而每帧压一次的开销
+ * 远小于它省下的字节。小于阈值（1KB）的帧不压，信封形状与原来逐字节一致。
+ *
+ * @returns {null | ((payload: unknown) => { v: number, z?: string, n: string, c: string })}
+ */
+function createFrameSealer(req) {
+  const opened = req && req.__dshE2ee;
+  if (!opened || !opened.keys || !opened.req) return null;
+  const { keys, req: request } = opened;
+  const path = signedPath(req);
+  const acceptEnc = headerOf(req, ACCEPT_ENC_HEADER);
+  let seq = 0;
+  return (payload) => {
+    seq += 1;
+    const { payload: plain, z } = compressPlain(Buffer.from(JSON.stringify(payload), 'utf8'), acceptEnc);
+    const sealed = e2ee.seal(keys.down, plain, e2ee.sseAad(path, request.ts, request.nonce, seq));
+    return wrapper(sealed, z);
+  };
+}
+
 async function handleStream(ctx, req, res) {
   const url = new URL(req.url, 'http://x');
   const sessionId = url.searchParams.get('sessionId');
@@ -202,22 +258,37 @@ async function handleStream(ctx, req, res) {
   const streamAddress = typeof parentSessionId === 'string' && parentSessionId
     ? { sessionId, parentSessionId, ...(mode === 'one-shot' || mode === 'continuable' ? { mode } : {}) }
     : { sessionId };
+  // 协议 v2：这条流要逐帧封装。`req.__dshE2ee` 由 `createGuarded` 在解封请求时挂上。
+  // **要在 writeHead 之前算**：`X-Dsh-Proto: 2` 只能在头发出去之前声明，写过头再
+  // `setHeader` 是无效的（Node 会静默忽略），客户端就永远不知道帧是信封。
+  const sealFrame = createFrameSealer(req);
+  const head = {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+    'content-encoding': 'identity',
+    ...(sealFrame ? { 'x-dsh-proto': '2' } : {}),
+  };
   try {
-    res.writeHead(200, {
-      'content-type': 'text/event-stream; charset=utf-8',
-      'cache-control': 'no-cache',
-      connection: 'keep-alive',
-      'x-accel-buffering': 'no',
-      'content-encoding': 'identity',
-    });
+    res.writeHead(200, head);
   } catch (error) { logStream(sessionId, 'writeHead failed', error); return; }
   res.write(': connected\n\n');
   const ac = new AbortController();
-  res.on('close', () => ac.abort());
+  // 按设备登记这条流：吊销时宿主主动断它（§3.3）。没有这一步，被踢的手机还能继续
+  // 收消息，直到它自己重连 —— 「单台吊销」就只生效了一半。
+  const untrack = streamRegistry.track(req.__dshRecord && req.__dshRecord.deviceId, res);
+  res.on('close', () => { untrack(); ac.abort(); });
   // 与设备级流（mobile/events.js）对齐：写坏掉的连接不该让 'error' 在 res 上无人接住
   // 而变成未捕获异常，那时 aborted 仍是 false，收尾分支会以为客户端还在、白写一帧 resync。
   res.on('error', () => ac.abort());
+
   const keepAlive = setInterval(() => {
+    // 开着流但没轮询的会话也要算「在线」（§3.4）：只靠请求命中来记「最近连接」的话，
+    // 一条长对话流开着、列表不轮询，面板上那台设备会被误判成离线。
+    if (req.__dshRecord) {
+      try { credentialsEntry().touch(req.__dshRecord, { channel: viaChannel(req) }); } catch { /* 记账失败不影响流 */ }
+    }
     try {
       res.write(': keepalive\n\n');
     } catch (error) {
@@ -232,7 +303,7 @@ async function handleStream(ctx, req, res) {
     // 注释行客户端看不见，所以每一拍再补一帧数据心跳：App 靠「最近真的收到过帧」判断
     // 这条流还在说话（见 app 侧 services/viewmodels/stream-liveness.ts）。写不出去同样
     // 说明客户端已经不在，按上面那条路径收尾。
-    if (!writeSse(res, { type: 'session/heartbeat', sessionId, at: Date.now() }).ok) {
+    if (!writeSse(res, { type: 'session/heartbeat', sessionId, at: Date.now() }, null, { sealFrame }).ok) {
       logStream(sessionId, 'heartbeat write failed', null);
       clearInterval(keepAlive);
       ac.abort();
@@ -247,11 +318,11 @@ async function handleStream(ctx, req, res) {
   // 审批卡由审批桥在帧循环之外推进这条连接：宿主那半条通道（`approval/request` 钩子）
   // 跟 mux 帧流没关系，见 mobile/approvals.js。接入时它会把仍然可作答的卡补发一遍。
   const detachApprovals = approvals.attachSession(sessionId, (frame) => {
-    writeSse(res, frame, { payload: frame });
+    writeSse(res, frame, { payload: frame }, { sealFrame });
   });
   // 提问卡同理（见 mobile/questions.js）：`user-questions/request` 钩子与 mux 帧流无关。
   const detachQuestions = questions.attachSession(sessionId, (frame) => {
-    writeSse(res, frame, { payload: frame });
+    writeSse(res, frame, { payload: frame }, { sealFrame });
   });
 
   const resumeSeq = parseResumeSeq(req, sessionId);
@@ -276,11 +347,11 @@ async function handleStream(ctx, req, res) {
 
     // 断线续传：回放 history 中 seq > resumeSeq 的事件（收敛状态）。
     if (resumeSeq != null && resumeSeq > 0) {
-      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); }, streamAddress);
+      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); }, streamAddress, sealFrame);
       if (replay.gap && !ac.signal.aborted) {
         const value = { type: 'session/resync-required', sessionId, resumeSeq, oldestSeq: replay.oldestSeq };
         // 旧实现在这里直接 `return`：既不清 keepAlive 也不 end，漏出一条永不收尾的连接。
-        if (!writeSse(res, value, { payload: value }).ok) clientGone = true;
+        if (!writeSse(res, value, { payload: value }, { sealFrame }).ok) clientGone = true;
       }
     }
 
@@ -289,7 +360,7 @@ async function handleStream(ctx, req, res) {
       // 「需要等 drain」这一步是这次 OOM 的正解 —— 写不动就停手，等底层消化完再继续，
       // 而不是把帧继续往内存里塞。
       const push = async (payload, frameArg) => {
-        const sent = writeSse(res, payload, frameArg);
+        const sent = writeSse(res, payload, frameArg, { sealFrame });
         if (sent.shed) return 'shed';
         if (!sent.ok) return 'closed';
         if (sent.needDrain) {
@@ -355,7 +426,7 @@ async function handleStream(ctx, req, res) {
       // 明确告诉客户端「流到此为止，请带 lastSeq 重连」：它会走已验证可用的 replay
       // 路径补上缺口，而不是把静默断流当成正常状态。
       if (!ac.signal.aborted && !clientGone) {
-        writeSse(res, { type: 'session/resync-required', sessionId, oldestSeq: lastDeliveredSeq + 1, final: true });
+        writeSse(res, { type: 'session/resync-required', sessionId, oldestSeq: lastDeliveredSeq + 1, final: true }, null, { sealFrame });
       }
       res.end();
       logStream(sessionId, `stream closed (loopEnded=${loopEnded}, aborted=${ac.signal.aborted}, clientGone=${clientGone}, deliveredSeq=${lastDeliveredSeq})`, null);
@@ -370,7 +441,7 @@ async function handleStream(ctx, req, res) {
  * 从会话 history 回放 seq > sinceSeq 的事件（升序），逐个经附件解析后写 SSE。
  * 通过 onDelivered(seq) 回报已交付的最大 seq，供上层去重。
  */
-async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, address) {
+async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, address, sealFrame = null) {
   try {
     // 子会话的重放也要带父会话（同 historyAddress 的口径），否则宿主回 agent-busy，
     // 这条断线续传静默退化成「后面缺一段」。
@@ -393,6 +464,14 @@ async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, a
         return e && Number.isFinite(e.seq) && e.seq > sinceSeq;
       })
       .sort((a, b) => ((a?.event || a).seq) - ((b?.event || b).seq));
+    // 落后太远就别在流里补了：这一段客户端本来就要靠权威历史重拉一遍，再从流里灌一遍
+    // 是同一份内容走两趟。空回放 + 报缺口，让 App 走分页历史那条便宜的路。
+    const farBehind = Boolean(candidates.length) && (candidates[candidates.length - 1].event || candidates[candidates.length - 1]).seq - sinceSeq > REPLAY_MAX_GAP;
+    if (gap || farBehind) {
+      logStream(sessionId, `replay skipped (gap=${gap} farBehind=${farBehind} cursor=${sinceSeq} newest=${(candidates[candidates.length - 1]?.event || candidates[candidates.length - 1])?.seq})`, null);
+      return { gap: true, oldestSeq: oldestSeq ?? sinceSeq + 1 };
+    }
+    let written = 0;
     for (const entry of candidates) {
       if (signal.aborted) break;
       const e = entry?.event || entry;
@@ -402,11 +481,17 @@ async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, a
       const payload = { type: 'session/event', sessionId, event };
       // 成批灌入：这一节几百条连着写，逐条补满 2048 字节注释等于给一次重连凭空加几 MB
       // （见 writeSse 的 options.burst）。
-      const sent = writeSse(res, event, { payload }, { burst: true });
+      const sent = writeSse(res, event, { payload }, { burst: true, sealFrame });
       if (!sent.ok) break;
+      written += (sent.bytes ?? 0);
       // 回放是「一次性灌几千条」，最容易把写队列撑爆：写不动就在这里等，别一口气塞完。
       if (sent.needDrain && !(await waitForDrain(res, signal))) break;
       if (Number.isFinite(event.seq)) onDelivered(event.seq);
+      // 字节到顶也一样：剩下的交给分页历史，别再灌。
+      if (written >= REPLAY_MAX_BYTES) {
+        logStream(sessionId, `replay truncated at ${written}B (cursor=${sinceSeq})`, null);
+        break;
+      }
     }
     return { gap, oldestSeq };
   } catch (error) { /* 回放尽力而为；失败不阻塞实时流 */
@@ -415,4 +500,4 @@ async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, a
   }
 }
 
-module.exports = { handleStream, parseResumeSeq };
+module.exports = { handleStream, parseResumeSeq, createFrameSealer };