# Patch 4b：Run SSE Replay（进行中，禁止合并 main / 上 103）

> **状态：代码 + 单测已完成（2026-07-06）；Finish 竞态见 [h5-finish-before-run-gate-20260706.md](./h5-finish-before-run-gate-20260706.md)。禁止 merge main / 上 103。**

## 目标

解决 H5 run SSE 重连丢状态问题：

- 使用已有 `h5_agent_run_events.id` 作为 SSE `id:` cursor
- 客户端 `Last-Event-ID` 重连后从 DB 补发 missed events
- 状态变更时写入 `run_snapshot` 事件，保证 sessionId 回填可回放

## 开关

```bash
# 服务端（默认 0 = 旧 poll-only 行为）
MEMIND_RUN_STREAM_REPLAY=1

# 本地验证
MEMIND_RUN_STREAM_REPLAY=1 pnpm dev
```

客户端 `subscribeAgentRunEvents` 已支持 `Last-Event-ID` + 断线重连（与 session stream 一致）。

## 改动文件

| 文件 | 说明 |
|------|------|
| `agent-run-stream.mjs` | replay 纯函数、flag |
| `agent-run-gateway.mjs` | `listRunEventsForUser`、`appendRunSnapshot` |
| `agent-run-routes.mjs` | replay 模式 SSE handler |
| `src/api/client.ts` | run SSE Last-Event-ID + 重连 |
| `agent-run-stream.test.mjs` | 单测 |
| `agent-run-routes.test.mjs` | replay SSE handler 用例 |
| `agent-run-gateway.test.mjs` | replay cursor / cursorMiss / run_snapshot 用例 |

## 2026-07-06 补充

- 修复 `listRunEventsForUser` 误返回 `cursorMiss: false`（ stale `Last-Event-ID` 无法触发全量补发）
- gateway 新增 3 项 replay 单测（51 pass 合计）

## 本地测试清单（合并/发布前必跑）

```bash
npm run verify:h5-session-patches
# 或分项：
node --test agent-run-stream.test.mjs agent-run-routes.test.mjs agent-run-gateway.test.mjs
npm run verify:goosed-proxy-boundary
```

手工：

1. `MEMIND_RUN_STREAM_REPLAY=1 pnpm dev`
2. 发起 agent run，DevTools 观察 `/agent/runs/:id/events` 含 `id:` 行
3. 模拟断网/刷新，确认重连后仍能收到 `sessionId` 与 terminal `succeeded`

## 与 Patch 4a 关系

- Patch 4a：taxonomy shadow（已完成）
- Patch 4b：run replay（本文件）
- Session stream replay 仍为后续项，不在 4b 范围