feat: M3 mosh 挂起→恢复<3s（唤醒脉冲 + 会话状态机三相）

- SessionMachine 加 mosh 三相(moshActive/moshParked/moshResuming)+看门狗兜底，
  mosh 接管即拆 SSH、后台冻结不重建、前台唤醒脉冲等 SSP 续（+5 单测）
- bridge.go: Node.WakeUp()(tsnet InjectEvent+MagicSock.Rebind/ReSTUN) +
  MoshRelay.Rebind()(同端口重开 loopback、泵按 socket 生成容错)
- iosclient.cc: g_mosh_last_heard 探针(导出 mosh_last_heard_ms) + SIGCONT 全屏重绘
- MoshSession: nudge()(SIGCONT) + lastHeardMs()；SSHTerminalModel 前台脉冲三连
  + healthy 轮询 + beginBackgroundTask；URL scheme 供无头前台唤醒
- 验证(vohive-vm over tsnet)：15s 冻结→前台 wake pulse→1.3s recovered，<3s

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/HANDOFF.md

@@ -6,7 +6,7 @@
 ---
 
 ## 0. 一句话现状
-一个**原生 iPad SSH 终端**已可用并真机验证：libghostty 渲染 + 键盘输入 + SSH 直连 + **SSH-over-tsnet(Tailscale 用户态)** + **tmux -CC 原生 tab** + **mosh(LAN 直连已端到端验证)** + 断线自动重连。四大核心需求（libghostty/tailscale/tmux/**mosh 均已验证**）。仅在 iOS 模拟器验证（未上真机/未签名/未提交 git）。
+一个**原生 iPad SSH 终端**已可用并真机验证：libghostty 渲染 + 键盘输入 + SSH 直连 + **SSH-over-tsnet(Tailscale 用户态)** + **tmux -CC 原生 tab** + **mosh(LAN + over-tsnet 均已端到端验证)** + 断线自动重连 + **mosh 挂起→恢复<3s(M3)**。四大核心需求（libghostty/tailscale/tmux/**mosh 均已验证**）。仅在 iOS 模拟器验证（未上真机/未签名）。
 > **mosh 状态（2026-07-24 全部验证通过）**：mosh(C++,blinksh/ios)+protobuf-lite 交叉编译成 `MoshCore.xcframework`（CommonCrypto 后端，含 arm64 模拟器 slice）；tsnet 桥加 UDP relay(`StartMoshRelay`)；`MoshSession`(pipe↔FILE*/pthread/SIGWINCH)+`MoshConnectScanner`(TXCore,39 单测)+`SSHTerminalModel` 编排（SSH 引导 mosh-server→解析 MOSH CONNECT→接管）。
 > - **LAN 直连端到端验证**（192.168.9.199）：mosh-server 存活 104s≫60s 无客户端超时+子 shell+心跳=真连。
 > - **mosh over tsnet 端到端验证**（vohive-vm 100.69.201.101）：app 日志 `parsed MOSH CONNECT port=60002`→`relay up localPort=63542`→`activateMosh started`；屏幕渲染远端 shell 且无 mosh 断连 overlay=relay UDP 双向流通。**R1(tsnet UDP 数据报语义) 证伪**。
@@ -41,20 +41,21 @@
 | dial 重试打磨 | ✅ | `TsnetManager.dialFD` 6 次退避重试，解决 tsnet 首连路径预热超时 |
 | **R5** Go+gvisor+C+++Swift 同进程 | ✅ retire | 全程真机无崩溃 |
 | **M2** mosh | ✅ 完成（LAN + tsnet 均验证） | libmoshios(C++)+protobuf-lite→`MoshCore.xcframework`；UDP relay over tsnet；**LAN 直连 + mosh-over-tsnet 均端到端验证通过**（R1 证伪） |
-| **M3** 生命周期深化 | ◻️ 部分 | 前后台 FSM 已做；mosh 快速恢复 + tmux 兜底 待做 |
+| **M3** 生命周期深化 | ✅ mosh 快恢复（真机深挂起待补） | scenePhase FSM + **mosh 挂起→恢复<3s 已验证**（模拟器：15/30s 冻结→前台，wake pulse→1.3s 收到服务器包，"已恢复"）；冷启动重连(SSP 序号+key 持久化)划入 M4/M5 |
 | **M4** 安全 | ◻️ 未做 | **当前 SSH 接受任意 host key**(见 SSHSession TODO)；known_hosts 固定 + Secure Enclave 密钥 待做 |
 | **M5** 合规提审 | ⏸️ 暂缓 | 用户指示暂缓 |
 
 ## 5. 代码地图与数据流
 - `packages/TXCore/Sources/TXCore/`
   - `Tmux/TmuxControlParser.swift` `TmuxEvent.swift` `TmuxIDs.swift` `TmuxOutputDecoder.swift` `TmuxLayout.swift` `TmuxControlSequence.swift`（DCS 检测）—— 纯解析，35 单测在 `Tests/`。
-  - `Session/SessionMachine.swift` —— `reduce(event)->[Effect]` 会话状态机（指数退避重连/后台冻结/前台恢复）。
+  - `Session/SessionMachine.swift` —— `reduce(event)->[Effect]` 会话状态机（指数退避重连/后台冻结/前台恢复）。**M3 加 mosh 三相** `moshActive/moshParked/moshResuming` + 事件 `moshEstablished/moshHealthy/moshExited/resumeWatchdogFired` + 效果 `nudgeResume/scheduleResumeWatchdog/teardownMosh`：mosh 接管即拆 SSH、后台冻结不重建、前台打唤醒脉冲等 SSP 续、两次脉冲无效兜底全量重建。
 - `packages/TXTransport/Sources/`
   - `TXTransport/Transport.swift`（协议+SSHConfig+SSHError）、`SSHSession.swift`（libssh2；`preconnectedFD` 支持外部 fd；事件循环 poll+非阻塞）。
   - `TXTransport/MoshSession.swift`（M2）：驱动 `mosh_main`；pipe↔FILE* 桥（in/out）、Foundation.Thread 跑阻塞主循环+`pthread_self()` 供 `pthread_kill(SIGWINCH)` resize、忽略 SIGPIPE、setenv UTF-8 locale。
   - `CSSH/`（C target：libssh2 头 + modulemap，供 `import CSSH`）、`CSSHCore`（binaryTarget，library-only）。
   - `CMosh/`（C target：`moshiosbridge.h`(mosh_main)+modulemap+占位 shim.c，供 `import CMosh`）、`MoshCore`（binaryTarget，library-only）；TXTransport 链 `libc++`/`libz`（mosh 是 C++ 且 compressor 用 zlib；CommonCrypto 属 libSystem 自动解析）。
   - `TXCore/Mosh/MoshConnect.swift`：`MoshConnectScanner` 流式扫描 `MOSH CONNECT <port> <key>`（注意 Swift 视 `\r\n` 为单 Character，行尾判定须用 `isNewline`）。
+- **M3 快恢复链**：`bridge.go` 加 `Node.WakeUp()`(tsnet `InjectEvent`+`MagicSock.Rebind/ReSTUN`) 与 `MoshRelay.Rebind()`(同端口重开 loopback、泵按 socket 生成容错)；`iosclient.cc` 加 `g_mosh_last_heard`(收到服务器包即更新，导出 `mosh_last_heard_ms()`) 并恢复 SIGCONT 全屏重绘；`MoshSession.nudge()`(SIGCONT) + `lastHeardMs()`；`SSHTerminalModel` 前台执行"唤醒脉冲三连"(WakeUp+Rebind+nudge)+healthy 轮询(探针增长→`moshHealthy`)+恢复看门狗+`beginBackgroundTask`。
 - `apps/TerminalX/iOS/`
   - `SSHTerminalModel.swift` —— 核心编排：`OutputGate`(surface-ready 缓冲)、`TransportHolder`、`TsnetManager`(tsnet 节点 up/dial+重试)、`TsnetError`、`TmuxRouter`(raw/gateway 字节分流)、状态机驱动 startSession(直连/tsnet 分支)、`autoConnectIfConfigured`(启动参数)。
   - `ContentView.swift` —— 分支：`tmuxController != nil`→`TmuxTabbedView`(tab 条+活动窗口)；否则 `RawTerminalView`；`TsnetProbeView`(纯自检)；`ConnectionForm`。
@@ -74,8 +75,9 @@
 
 ## 7. 下一步建议（按价值）
 1. **M2 mosh 打磨**（功能已通，打磨项）：`activateMosh` 写死 80x24 初值（靠首次 resize 纠正）；SSH 会话在 mosh 接管后保持 idle 未关（占一条连接）；`MoshSession.close()` 后 mosh 线程可能滞留（阻塞主循环，见 TODO）；moshiosbridge.cc 顶部 `fwrite("Hello from the Bridge!")` 调试行可清理；`SSHTerminalModel` 里 `NSLog("MOSHDBG …")` 诊断日志可按需保留/删除；mosh-server 引导后远端会累积 detached 会话（`mosh-server new` 每次新建），可考虑复用或清理。**挂起→恢复<3s 门（M3）待专门测**。
-3. **tmux 多 pane 分屏**：`TmuxLayout` 已能解析布局树 → 把 window 内多 pane 渲染成 SwiftUI 分屏（每 pane 一 surface）。
-4. **M4 安全**：known_hosts 固定 + SE 密钥。
+3. **M3 真机深挂起补测**：模拟器不复现 socket defunct、且看门狗会杀掉被 `kill -STOP` 冻结过久的 app（>~30s 概率被杀），故 WG 密钥过期(>180s)/DERP 死链/socket defunct 路径需**真机锁屏数分钟**用例补测（`MoshRelay.Rebind`/`hop_port` 的正确性靠代码 + 真机）。
+4. **tmux 多 pane 分屏**：`TmuxLayout` 已能解析布局树 → 把 window 内多 pane 渲染成 SwiftUI 分屏（每 pane 一 surface）。
+5. **M4 安全 + 冷启动 mosh 重连**：known_hosts 固定 + SE 密钥；mosh 进程死后重连原 detached 会话需持久化 MOSH_KEY+port 且改 mosh 序列化 SSP 序号/终端状态（Blink 式，大活）。
 5. **产品化**：主机列表持久化(Keychain)、多标签(非 tmux)、软键盘运维工具栏(GhosttyKit 内建，接线即可)。
 
 ## 8. 测试资源（用户提供，**凭据勿写入仓库/勿硬编码**，每次向用户索取）