远程控制：终端挂载 workspace bridge 瞬间 relay 停止应答桌面端心跳，30s 后断连循环（3.7.6+ / 与数据量无关）

问题类别 · Category

Bug 反馈（桌面端远程控制 / Web Remote Control · external relay）

涉及的 Agent 框架 · Agent framework

ZCode 桌面端（Electron / macOS arm64）；远程终端为手机 App，桌面版 Chrome 打开 remote/v4 链接可复现同样问题（已排除手机端因素）

严重程度 · Severity

高 —— 远程控制功能在终端挂载后即进入断连循环，基本不可用

复现频率 · Reproducibility

必现（每次终端挂载 workspace bridge 均触发；终端断开时偶发 INTERNAL 错误）

问题描述 · Description

桌面端与 relay（wss://zcode.z.ai/ws）的设备连接，在终端挂载 workspace bridge 的瞬间停止收到心跳 ACK，30 秒后触发 heartbeat ack timeout 断线重连；重连+重放后可短暂恢复，但下一次挂载/会话活动再次触发。终端断开时偶发 device error {"message":"INTERNAL"}。

关键排除项（均已实测验证）：

• 与数据量无关：挂载期间对 en0 出站流量逐秒采样，全程约 0 MB，连接照样在桥接激活 30 秒后死亡
• 桌面端与 relay 为直连（不经过本地代理），MTU 正常（DF ping 1472 通过），系统睡眠已禁用
• 换用全新 deviceSid（重置 webRemoteControlExternalRelayDevice + pass_hash）后，问题从「永久死循环」缓解为「挂载时断 1–2 次后可恢复」，说明服务端会话状态会随使用被污染，但根因仍在服务端

时间线：2026-08-08 ～ 08-12 同一环境重度使用（每日 mobile diagnostic 事件 645/112/296/295/105 次）heartbeat timeout 为 0；08-13 起每次远程会话均超时（每日 7/17/3/45/15 次），跨 3.7.6 / 3.7.7 / 3.8.1 三个版本复现。

复现步骤 · Steps to reproduce

1. 桌面端开启远程控制，等待 waiting_terminal 稳定（此状态下连接可保持数小时不断，心跳正常）
2. 手机 App / Chrome 打开 remote/v4 链接
3. 日志出现 pair 成功 → attaching workspace bridge → workspace bridge active
4. 同一秒起心跳 ACK 停止，30 秒后 heartbeat ack timeout 重连

期望表现 · Expected behavior

终端挂载后 bridge 稳定工作、心跳正常，远程端及时拿到工作区数据与会话流。

实际表现 · Actual behavior

• 手机端频繁报「桌面端响应超时：手机端已经连上 relay，但桌面端没有及时返回工作区数据（Desktop did not respond in time）」
• 会话消息实际已到达桌面端 agent（本地 rollout 文件正常写入、定时任务照常执行），但响应流无法稳定回传，远程端表现为「发消息没有任何响应」

环境 · Environment

• ZCode 版本：v3.8.1（问题自 3.7.6 时代开始出现）
• 系统：macOS（Mac mini M4 Pro / arm64）
• 网络：教育网直连；手机为蜂窝/家庭网络（Chrome 本机复现可排除终端侧网络因素）

关键日志 · Logs（~/.zcode/v2/logs/，路径已脱敏）

# 终端挂载 → 桥接激活 → 30 秒整后死亡（ACK 停止时刻精确等于 bridge active 时刻）
12:50:33.451 workspace bridge active window=1 session=d_7hWB*** bridgeSession=bridge-***
12:51:02.849 external relay heartbeat ack timeout, reconnecting {"state":"paired","staleMs":30001}

# 终端断开时
12:52:19.323 external relay device error {"message":"INTERNAL"}
12:52:19.324 external relay device state {"state":"waiting_terminal"}

# 完整一轮：连接→配对→桥接→死亡→重连（循环）
external relay device state {"state":"authenticating"} → {"state":"paired"}
→ attaching workspace bridge → workspace bridge active
→ (静默 ~30s) → heartbeat ack timeout, reconnecting → 重复

注：已通过「帮助 → 导出日志」导出完整日志包（含上述全部事件）。因其中含本机 API key 等敏感信息不宜公开上传，如需完整日志可通过私渠提供，或以上摘录的时间戳/deviceSid（d_7hWB*** / 原 d_PJZ***）可直接在服务端日志中检索。

提交前确认 · Checklist

• 已搜索现有 issue，确认非重复
• 已阅读 CONTRIBUTING.md

Start by reproducing the remote/v4 flow through waiting_terminal, pairing, and workspace bridge activation, then inspect ~/.zcode/v2/logs for the heartbeat ACK timeout and INTERNAL device error. Compare the relay behavior before and after bridge activation using the exported logs or the provided timestamps; done means the bridge remains active, heartbeat ACKs continue, and the remote session returns workspace data reliably.