fix: isolate visual tool failures from agent runs

docs/regression-guards/h5-session-stream-replay.md

@@ -16,10 +16,27 @@ Portal 对 SSE 帧使用本地持久化游标。该游标可能是 Portal 生成
 4. 本地重放最后一条已经是 `Finish` 或 `Error` 时，不再连接 Goose。
 5. 重放不得破坏现有消息 ID 合并、Finish 幂等计费和 MindSpace Finish 同步守卫。
 
+## 视觉工具故障旁路
+
+文本模型可能在会话历史中遇到 `read_image` 返回的图片块，并以
+`unknown variant image_url, expected text` 拒绝整次请求。图片检查属于可选增强，
+不得因此中断页面编辑、写文件、发布或其它文本主任务。
+
+必须保留：
+
+1. 将该上游错误分类为 `SESSION_VISUAL_CONTEXT_UNSUPPORTED`，不得作为普通瞬时错误盲重试。
+2. 用干净会话恢复可见文本上下文，并移除新会话策略中的 `read_image`，明确要求 Agent 跳过视觉检查、继续主任务。
+3. 一次执行中允许先恢复污染的工具历史，再单独进行一次视觉降级恢复；两个原因不得共用同一个“一次性恢复”开关。
+4. 普通重试前必须取消旧会话的活动请求，避免后续请求被 `Session already has an active request` 锁死。
+5. 视觉降级只影响当前恢复会话，不得全局关闭图片能力，也不得删减其它开发工具或数据能力。
+
 ## 关键路径
 
 - `session-stream.mjs`
 - `session-stream-store.mjs`
+- `session-reply-wait.mjs`
+- `agent-run-gateway.mjs`
+- `capabilities.mjs`
 - `tkmind-proxy.mjs`
 - `server/portal-session-routes.mjs`（Portal Session 路由、流中 public HTML 落盘与 Finish 后同步）
 - `src/hooks/useTKMindChat.ts`
@@ -29,6 +46,7 @@ Portal 对 SSE 帧使用本地持久化游标。该游标可能是 Portal 生成
 ```bash
 node --test session-stream.test.mjs session-stream-store.test.mjs chat-agent-run-gate.test.mjs
 node --test --test-name-pattern='proxySessionEvents' tkmind-proxy.test.mjs
+node --test session-reply-wait.test.mjs capabilities.test.mjs agent-run-gateway.test.mjs tkmind-proxy.test.mjs
 npm run verify:h5-session-patches
 node --test billing-session-concurrency.test.mjs
 ```
@@ -39,3 +57,6 @@ node --test billing-session-concurrency.test.mjs
 - 有映射时，Portal 游标正确转换成 Goose 游标。
 - 多轮会话中选择最新可映射的上游游标，不被上一轮 Finish 截断。
 - Finish 重放不重复扣费，消息合并与页面同步守卫继续通过。
+- `image_url` 不兼容时切换到无 `read_image` 的干净会话，并继续文本主任务。
+- 工具历史恢复后仍可执行一次独立的视觉降级恢复。
+- 瞬时重试前先取消旧请求，避免活动请求冲突。