zterm-mobile-dev

name	zterm-mobile-dev
description	审计、开发和验证 zterm Android 客户端；按当前架构、最新目标和 owner 选择门禁，区分源码、设备与 OTA 证据。

zterm-mobile Dev Skill

当前入口与适用范围

• 仓库相对路径均以 zterm 根目录解释；从本 skill 到根目录为 ../../..。
• 最新架构目标：runtime-memory-truth。记忆入口：memory/index.md；按条目 source_refs 核对实现。目标不是已交付状态。
• 本 skill 的旧功能规格、状态机和经验只辅助定位；产品/协议/owner 不在此重复冻结。对应真源为 spec、architecture、shared protocol、registry 与上述最新 decision。
• 纯审计或文档修复：只做读源、真实界面观察、文档/链接/命令校验与 review；不因此构建 APK、修改 buildNumber、安装或发布。
• UI 解耦审计追踪 App -> slot -> component/controller -> business owner；检查状态归属和实际 I/O，不能用 slot wrapper 的无 import 测试证明下游纯投影。
• UI 设计审计使用 frontend-ui-reference / impeccable：实际手机与大屏、键盘开关、长名称、加载/空/错误、触摸目标与读屏；记录 APK/viewport/截图，区分源码发现与运行态复现。
• 完成适用验证后按全局 review 路由使用 AGY；只有 controller PASS 才算通过。review 不自动授权 commit/push/发布。独立工作树内保护其他 worker 的改动。

项目概要

• 目标: zterm Android 客户端，通过 Tailscale 访问本地 Mac/PC
• 技术栈: Capacitor + React + @jsonstudio/wtermmod-react (WASM 终端)
• 服务端: WebSocket → tmux 桥接（本地 Mac/PC 运行）
• 核心功能: 多 terminal Tab、主机管理、后台保活、WebDAV 同步

---

一、必读文档顺序

每次开发前必须按顺序阅读：

1. ~/.codex/AGENTS.md               → 全局入口、硬护栏
2. ~/.codex/USER.md                 → 用户偏好（称呼 Jason）
3. coding-principals/SKILL.md       → 开发方法论
4. android/docs/spec.md     → 项目范围与验收
5. android/docs/architecture.md → 模块边界与数据流
   android/docs/audits/2026-07-02-architecture-boundary-remediation.md → owner 边界
   android/docs/decisions/2026-09-05-runtime-memory-truth.md → 当前实现与最新目标
   android/memory/index.md → 相关最新条目与 source_refs
6. android/docs/decisions/0001-cross-platform-layout-profile.md → 跨尺寸布局 / Mac 共享壳决策
7. android/docs/decisions/2026-04-23-terminal-head-buffer-render-truth.md → terminal head / sparse buffer / render / UI 真源
8. android/docs/dev-workflow.md → 执行门禁与验证
9. android/task.md          → 当前任务板
10. android/docs/ui-slices.md → 页面切片与 ownership
11. 本 SKILL.md                     → 项目约束、可复用门禁

---

二、项目特有约束

2.1 禁止修改的代码

• 不直接把 runtime 源码复制进 zterm
• runtime 发布包的真源在 ../wterm，需要改底层时去 fork repo 改
• 不修改 mac/、win/ 下其他客户端骨架
• 不在 app repo 内复制 runtime 源码；runtime 变更改 ../wterm
• skill / 文档 / AGENTS 真源以 zterm 命名，不再沿用 wterm-mobile-* 旧命名
• 按消融原则比较删除、复用与直接实现；只保留一个语义 owner

2.2 真源分工

• spec.md：产品范围与验收
• architecture.md：模块边界、数据流、ownership
• docs/decisions/0001-cross-platform-layout-profile.md：跨尺寸布局 / Mac 共享壳唯一决策
• dev-workflow.md：执行顺序、验证门禁、证据要求
• ui-slices.md：页面级切片与文件 ownership
• task.md：当前任务状态
• CACHE.md：本轮短期上下文
• MEMORY.md：长期可复用经验
• evidence/：截图、日志、APK、真机证据
  • 说明：android/evidence/ 是本地证据仓，默认不进 Git 主线；Git 中只保留目录说明文件

2.2.1 Android 交付包硬门禁

• 本次适用的架构、map、构建、验证与发布门禁按代码缺陷处理；Collab/Memory/Guidance 缺失不阻断独立开发。共享写入无归属或互斥时，仅阻断受影响操作。禁止绕过必需 gate 或伪造证据。
• 每次 Android 功能修复 / bug 修复 / renderer / daemon-client 协议 / UI 行为改动，只要需要 Jason 复测或会影响真机行为，完成前必须构建可升级 APK 包。
• 例外：desktop.remote_window_stream 的视频主链尚未完成时，不为中间态 catalog / overlay shell / debug 诊断改动反复构建 APK；先完成真实远程视频（ScreenCaptureKit/WebRTC frame stream 可见）并通过对应 gates，再构建 APK 给 Jason 测。除非 Jason 明确要求止血包或升级恢复包，否则不要在远程视频完成前编包。
• 默认命令：pnpm --dir android run build:android。
• 设备数据保护是 Android 测试的硬门禁：安装新 APK 前必须保留当前应用数据，使用 adb install -r 或应用内 OTA；禁止用 adb uninstall、adb shell pm clear、删除应用数据目录或任何等价操作来解决版本覆盖/降级/测试问题。只有 Jason 明确授权且已完成配置导出或可验证备份后，才允许执行不可逆的数据清理。
• 每次真机测试前，先确认配置恢复路径：优先使用应用内“导出配置”生成的 zterm-config.json，并保存导出文件路径、时间和 SHA-256；没有导出/备份证据就不能卸载、清数据或覆盖测试设备。测试只需要新数据时，使用独立设备、独立 Android 用户或 Jason 明确批准的隔离测试环境。
• 覆盖安装后必须核对 package:dataDir、firstInstallTime/lastUpdateTime 和关键配置仍可读取；若配置缺失，立即停止后续安装/发布动作并报告，不得静默重置、重新初始化或把空配置当作成功。
• .build-meta.json 是持久化版本真源，禁止手工编辑、跳号、回退或为了绕过 Android 版本检查抬高 buildNumber。版本分配只能由 scripts/bump-build-version.mjs 完成；构建前后记录 buildNumber、APK 内 versionName/versionCode、manifest 和 SHA-256，发现不一致必须停止。
• OTA 发布是不可逆的外部状态变更：构建、bundle verify、三通道 GET/HEAD/hash 校验只能证明产物正确，不等于获得发布授权。没有 Jason 的明确发布授权，不得执行 Relay scp、覆盖 latest.json、发布 stable channel 或重启生产服务。
• 构建结果必须进入升级通道：android/update-dist/latest.json、android/update-dist/zterm-<version>.apk、android/update-dist/zterm-latest-debug.apk、~/.zterm/updates/latest.json、~/.zterm/updates/zterm-<version>.apk sha/version 对齐。
• 获授权的 Android 发布闭环必须覆盖本机、Tailscale daemon 与配置的 public Relay update route；先读取当时端口、地址、manifest URL，再验证 GET/HEAD、版本与 APK 下载 SHA-256。超时先诊断唯一服务 owner，仅在已有重启授权时做 service-scoped restart；不得用旧地址或自动重启代替现场证据。
• 汇报时必须给出 versionName、versionCode、APK 路径和 sha256；不能只说测试通过。
• Android 回退发布必须使用同一正常构建号的子版本槽：正常版 0.1.3.N，回退版 0.1.3.N.1，下一正常版 0.1.3.N+1；APK 内必须同时满足 versionCode(N) < versionCode(N.1) < versionCode(N+1)。禁止用 bit 30、固定高位或任何会让后续正常版永久低于回退版的 namespace。发布前必须用 apkanalyzer 读取实际 APK 的 versionName/，并在不带 的真实设备上验证 normal N -> rollback N.1 -> normal N+1 可依次覆盖安装；manifest 文件名或 JSON 声明不能代替 APK 内 manifest 证据。

2.2.1a Module / Edge 架构门禁

• 跨 daemon/client/shared/relay/release/observability 的改动，先落 android/docs/resource-registry.json、android/docs/module-registry.json、android/docs/edge-registry.json，再同步 android/docs/function-map.md、android/docs/wiki/mainline-call-map.json、android/docs/wiki/mainline-source.md，最后改 runtime。
• docs/modules/project-modules.md 是人读模块图；module-registry.json 是模块真源；edge-registry.json 是唯一允许跨模块资源边。找不到唯一 module_id / edge_id 时，不准直接补 runtime patch。
• 连接抽象必须走 client.daemon_connection：同一 daemon target 一个 client physical connection；tmux session 是 client.terminal_channel_mux 里的 channel，不是 socket owner；heartbeat 是 target-level，不是 session-level。
• createClientDaemonConnection() 只能在 transport owner 层创建：session-context-infra-facade-runtime.ts 负责共享 read/send owner，session-context-transport-orchestration-runtime.ts 只允许创建带 openSessionTargetTransport 的 mux open owner。public facade / interaction / lifecycle / message assemblies 只能消费已注入的 daemonConnection，禁止各自 new wrapper 或保留 daemonConnection || raw socket 双路径。
• queueSessionTransportOpenIntentRuntime() 只允许走 mux opener；缺少 openSessionMuxChannelByIntent 必须显式失败并删除 pending intent，禁止回退到 ensureControlTransportForSessionOpen 或其他 legacy session-ticket socket。
• getSessionTransportResource() 只要 session 已有 mux channel，就不得用 runtime.activeSocket 冒充有效连接；channel 未 ready 时资源 socket 必须保持空，等待同一 physical transport 上的 mux-ready。
• daemon 侧连接入口走 daemon.connection_gateway / daemon.transport_subscriber，不得保存 client active tab、foreground/background、viewport、renderer follow/reading、UI projection truth。
• Relay 只走 relay.peer_lease 和 resource.transport_target；不得保存 terminal channel、transport subscriber、tmux、mirror、active tab、UI truth。
• 这类变更必须跑 pnpm --dir android run test:feature-registry -- --reporter dot，其中包含 src/lib/module-registry-truth.test.ts 和 src/lib/edge-registry-truth.test.ts。

2.2.1b File-transfer 吞吐与字节真相

• 页面文件入口只消费 file-browser owner 绑定的 session port；不得在 TerminalPage 用 active-session ref 路由文件 wire。异步上传捕获一次 sender，后续 UI 切换不能改变该操作的发送目标；按 android/docs/audits/2026-09-05-file-browser-session-port.md 跑跨 rerender 回归。
• 文件同步 wire frame 保持 16 KiB；上传只能由 sendBoundedFileUploadChunks 使用 cumulative ACK 的固定窗口推进，禁止 UI stop-and-wait、无界 burst 或 caller 自定义窗口。下载 native bridge 只能由 writeFileTransferChunkBatches 聚合写入，禁止恢复逐 wire chunk bridge 调用。
• android/contracts/file-transfer-throughput.json 是上传窗口和 native batch 上限的唯一机器真源。TypeScript 直接导入，Android Gradle 从同一 JSON 生成 BuildConfig；禁止 TS/Java 分别维护数字。pnpm --dir android run test:file-transfer:throughput 必须同时跑 TS/module loopback 与 StorageFileWriteLogicTest，并真实接入 prebuild 和 CI。
• module loopback 的 SHA-256 只证明算法与字节顺序，不是产品速度闭环。声称上下行提速前必须在真实 transport + online ADB 上复用已有 daemon/session，对同一确定性文件记录双向 bytes/duration/throughput 和两端 SHA-256；资源用完精确清理。没有 online ADB 时明确保留缺口，不重启含其他未审查 worktree 改动的生产 daemon。
• 已安装 APK 的 native plugin 面必须单独实测：通过 WebView CDP 调用 StoragePermission.writeFileChunks({ path, chunks, append }) 并 stat 校验落盘字节后，才允许跑下载持久化测速；源码/Gradle 单测绿但设备返回 UNIMPLEMENTED 时，下载产品 E2E 仍为红。

2.2.2 Remote-window 输入 / 粘贴 / 码率规则

• macOS Screen Recording 权限、install preflight 和 remote-window capture 必须共用安装态 zterm-daemon 这一唯一 TCC/可执行主体：preflight 只运行 ZTERM_DAEMON_NATIVE --permission-probe，runtime 只运行同一二进制的 remote-window-capture 子命令。权限检查只允许一次 CGPreflightScreenCaptureAccess()；禁止 CGRequestScreenCaptureAccess()、等待/轮询/重试。禁止 Remote Capture app bundle、独立 raw helper、ZTERM_DAEMON_CAPTURE_NATIVE、Node 运行时编译或 screenshot fallback。缺权限/缺 capability 必须立即返回 typed error 并停止；不得切换主体或降级成功。
• Remote-window image paste 的路由真源只能是 Android active focus context：remote-window context active 才允许发送 pasteTarget.kind=remote-window；terminal surface focus 必须清掉 context；否则同一 QuickBar image action 保持 terminal Ctrl+V paste path。daemon 不猜焦点，不按 app title/window list 自行决定投递目标。
• Remote-window 粘贴执行必须复用 file-transfer paste-image owner 写 macOS clipboard；remote-window target 只追加 Command+V 注入，terminal target 只追加 terminal Ctrl+V。禁止新增第二套图片上传或 clipboard 流水线。
• Remote-window 质量是 stream-local typed control profile，不是 Mbps preset：默认 smooth、可选 quality，profile 同时拥有 bitrate、capture dimensions、FPS、max frame age、interaction burst 和 overview budget。客户端唯一状态是 applied/desired/inFlight/queuedLatest/cooldown，始终 single-flight + latest-wins；相同 profile 全链 no-op，rejected/busy/timeout 必须离开 requested。daemon 先做 exact diff：bitrate-only 只改现有 sender encodings；cadence/dimensions/filter 只更新现有 SCStream configuration/contentFilter；quality update 的 stop/start capture 调用数必须为 0。空 encodings、in-place update 或 rollback 失败显式返回 typed failure，不伪造 encoding、不保留 partial applied、不重建 peer/receiver/session transport。
• Remote-window 自适应必须把 network、host capture/encode、Android decode/render、latency-only 分成独立 typed facts：累计 counters 先转 sample delta；连续两样本或严重 backlog 才单步降一级；稳定 12 秒单步恢复；apply 后跳过两个 stats 样本。网络先小步减 bitrate，CPU/render 先降 capture dimensions，latency-only 先丢过期连续态；qualityLimitationReason !== none 不能直接判网络弱，禁止 /4 bitrate 或 /2 FPS 断崖。quality/retry/revision/health/telemetry 走 control/debug side-channel，绝不能进入视频 frame 或 input action metadata。
• Remote-window focus canvas 只能由 requestVideoFrameCallback/decoded frame id 驱动，一张 frame 最多一次 drawImage；overview/thumb 使用自己的 decoded callback 和 profile cadence，生产环境不保留 display-rAF 绘制 fallback。daemon focus/overview capture/convert 各最多一个 pending latest frame，新帧覆盖旧 pending，超过 profile maxFrameAge 直接丢；禁止增加 queue depth。若 bounded RGBA path 无法同时通过 smooth 1280-long-edge@45/p95<=100ms 与 quality 1920-long-edge@30/p95<=180ms，必须实现唯一 native media path 并物理删除 production RGBA stdout，禁止双 production path。
• Remote-window WebRTC sender 质量闭环必须证明真实 video track。当前 @roamhq/wrtc 里 会在真实 Android recvonly offer 下生成 answer，ScreenCaptureKit 首帧和 都不能证明 Android 会收到 ；stream start 必须优先用 或其他已验证会生成 的路径，等 answer/localDescription 落地后再尝试修改已有 sender encodings。没有 encodings 或 抛错时只能显式报告 quality update unsupported，不能伪造成功，也不能为码率控制牺牲 video track。Live probe 必须处理 daemon ICE candidate，等待 事件并输出 ；offer/answer、、或只看 都不能单独证明 Android/receiver 视频可见。同一桌面窗口的 ScreenCaptureKit / WebRTC live probe 必须串行运行；并发 raw+mux 或同目标多 stream 容易让 catalog/capture 首帧 timeout，不能作为产品红证据。

2.3 旧文档处理

• android/note.md 是 agent 自己看的工作台，不是主真源
• 探索过程里的高信号发现、假设、踩坑和回归锁定要写进去；不要把完整流程说明塞进 note

2.4 不在本项目范围

• screen 集成（用户自行管理）
• Tailscale 客户端集成（用户已有 Tailscale App）
• 密钥导入/生成（后续扩展）
• 数据加密存储（后续扩展）
• 生物识别解锁（后续扩展）

2.5 服务端位置

• WebSocket 服务端必须运行在本地 Mac/PC（不是手机）
• 手机端纯客户端角色

2.6 UI 参考图规则

• UI 开发前先冻结主参考图与次参考图
• 先对齐信息结构和交互结构，再做视觉细节
• 当前项目的主 UI 主线是：Connections 页 + 终端页，不是网页式主机列表页
• Jason 当前已明确认可的视觉真方向：简洁、闭合、分区明确的 capsule/block UI。后续按钮、快捷栏、卡片、面板默认优先使用低噪声配色 + 清晰边界 + 成组区域 + 闭合块状设计，除非该页面有明确反例需求。

2.7 页面级切片规则

• 页面级重构先看 docs/ui-slices.md
• App Shell、Connections、Connection Properties、Terminal 必须分层
• 不跨页混改；先壳后功能，先 ownership 后细节

2.8 卡片与预览区规则

• Connections 卡片的 preview 区在没有真实 preview 时，不要回退渲染 subtitle
• preview 和摘要信息必须分层：上半区负责 preview / 占位，下半区负责 title / subtitle / action
• 否则同一 host 摘要会在卡片内重复出现，容易被误判成渲染 bug

2.9 连接模型拆分规则

• mobile 的连接真源必须显式区分 bridgeHost / bridgePort / sessionName；禁止再用 host/username 混装 server 与 tmux session 语义
• Android Home 必须把三类入口独立投影：current-process active Sessions、saved direct/Tailscale Hosts、optional Relay account/directory。Relay 未登录、登录失败或退出登录不得隐藏、禁用或删除前两类；Relay directory 只补 route/device candidates，不得成为 saved Host/Tailscale truth owner。
• Android Home 只投影 route-aware saved Host 与 online Relay directory，保留 saved row 身份并发出 session-open intent；自动路由目标与迁移差距以 runtime-memory-truth decision 为准。禁止 UI 决定 route order、让 directory 替换 saved Host truth，或把 TURN-only 成功冒充 UDP/P2P。
• Relay directory 投影到 Home / drawer / picker target 时只允许 online daemon device：daemon.connected=true 且 daemon.hostId 非空。rtc-device-*、client-only、disconnected/stale daemon records 即使携带旧 endpoint/session snapshots，也只能作为 account directory fact，禁止出现在 connectable server rows、drawer host rail 或 target lookup。
• Relay 登录态不能成为 Session Picker 的全局模式开关：即使账号下有在线 daemon，直接 Tailscale/bridge target 仍必须能输入、选择 saved server、用 bridgeHost + authToken live fetch sessions。只有当前 target 自身带 relay-rtc candidates / relay identity 时，才允许按 Relay target 处理；显式 transportMode='webrtc' / relay-route target 禁止在 buildBridgeTargetFromHost() 中自动解析 direct endpoint 填入 bridgeHost。
• Relay directory 的 direct endpoints 也是 daemon identity alias：drawer host rail / side peek / server identity projection 必须把 100.x:3333、IPv4/IPv6/wsUrl direct rows canonicalize 到同一 daemon.hostId，否则同一 daemon 会显示成“名字 0 sessions + IP 有 sessions”。alias 只能用于 UI 分组身份，不能替代 transport route truth。
• 生产 Relay directory 可能只发布 relay-rtc:<hostId>，没有 Tailscale/direct endpoint。修 drawer duplicate host 时不能只看 endpoint alias；必须同时验证 saved/Home server alias input，以及 rtc-only directory session catalog 的唯一匹配路径。只有一个 Relay daemon catalog 完整包含该 direct SessionGroup 的非 missing session 名称时才可 canonicalize；多个 daemon 都匹配时保持分离并显式暴露，禁止猜测合并。
• Terminal drawer 的 refresh / quick-new / catalog open 发出 route-aware target intent，路由选择交唯一 connection owner。按最新 decision 验证各层实际尝试顺序及 direct/Relay 证据；不能再按旧 Tailscale-before-UDP 规则验收目标。
• Terminal drawer catalog 若命中已打开的旧 direct/Tailscale session，也不能直接 switchSession 绕过 route owner；当 online Relay catalog 唯一 owns 该 daemon 时，点击该 row 必须继续走 session-open owner，用 route-aware target 复用并升级现有 session transport truth，禁止生成第二个同 tmux open tab。
• 如果同一个 session 因 direct/Tailscale 与 Relay route 切换而重新打开，session-open owner 必须先用当前 route-aware Host 重新 createSession(..., { sessionId: existingId, activate: false })，再做 explicit-resume；只切 open-tab/UI 但不重绑 transport truth 视为假修复。

2.10 daemon 收敛规则

• server 侧启动入口要收敛成单一 daemon CLI，默认监听地址/端口由统一配置真源决定（当前 0.0.0.0:3333）
• relay/account 配置必须走全局发行包入口：目标由 zterm-daemon configure-relay 写入 ~/.zterm/config.toml；现有 ~/.zterm/config.json 必须经校验、原子写入和 read-back comparison 一次性迁移，迁移成功后不得继续作为 runtime fallback。daemon 只读取配置，不承载账号 UX，禁止硬编码 Relay URL 或把手工改散落配置当成最终交付。
• daemon 全局安装的稳定入口必须由包内脚本自固化：npm postinstall / service runner 要自动生成 ~/.local/bin/zterm-daemon 与 ~/.local/bin/wterm，写入前先清旧 symlink/file，released runner 读 config 前要迁移旧 ~/.wterm -> ~/.zterm。如果只靠手工修 PATH、手工挪目录或改已安装文件，视为未修真源。
• relay account directory 发布必须来自 daemon truth：relay-ready 后由 daemon relay host client 发布 directory-update，session catalog 只能来自 tmux 枚举；枚举失败必须显式报错，禁止把失败伪造成空 sessions 的成功目录。
• Relay directory direct endpoints 必须端到端保留 daemon authToken。若本机 daemon 日志显示 auth=config 且发布多条 endpoint，但生产 /api/auth/me 只回少量 endpoint 或 hasAuthToken=false，先查生产 /usr/lib/node_modules/@jsonstudio/zterm-relay-server/runtime/server.cjs 是否包含 authToken，再升级 @jsonstudio/zterm-relay-server 并 service-scoped restart zterm-traversal-relay.service。禁止先在 Android route/UI 层补第二套 token fallback。
• Relay directory direct endpoint 与 saved host 指向同一 path + host:port 时，directory endpoint 的新 daemon auth token 必须先进入 traversal plan 并按 endpoint identity 去重；禁止按带 token 的完整 URL 去重，否则 stale saved token 会和 fresh directory token 并存，Auto 首连先撞 Unauthorized bridge token。
• rtc-direct 的 data channel open 不是最终 route success；必须有短稳定窗口，窗口内 close 要作为该 candidate 失败并继续尝试 rtc-relay。TURN-only rtc-relay 可直接发布 open。禁止把 transient direct open 投给上层后中断 Auto 链路。
• reliable input 发送后 sentAt !== null 表示 seq 已在途等待 ACK；禁止固定 timer 重发同 seq。只有 daemon 明确 retryable NACK 才能清 sentAt 并重发，否则弱网 ACK 延迟会变成用户输入重复。
• 配置迁移实现前，release daemon support 脚本仍读取 ~/.zterm/config.json 并按字段合并 zterm.android.daemon 与 legacy mobile.daemon，空的新字段不能遮住旧 token；这只是当前兼容事实。目标迁移完成后只读取 ~/.zterm/config.toml。全局安装后必须验证 auth=config、无 token WS 拒绝、有 token WS 能 list-sessions。
• relay smoke / 真实链路里 client device 与 daemon device 必须使用不同 ；复用同一 id 会让 client metadata 覆盖 daemon directory identity，造成 account directory 假状态。

2.10.1 Remote window video hard gates

• desktop.remote_window_stream 的视频真源只允许来自 daemon/native ScreenCaptureKit -> WebRTC。Android <video> 只能消费 negotiated MediaStream；禁止用 screenshot loop、terminal mirror、client sparse buffer、static/mock receiver 冒充视频。
• ScreenCaptureKit crop frame 可能是奇数宽高。daemon I420 buffer 必须按 width * height + ceil(width/2) * ceil(height/2) * 2 分配；禁止用 floor(width * height * 1.5)。此类错误会让 @roamhq/wrtc 抛 byteLength 异常并杀掉 daemon，Android 现场表现为 Remote window stream start timed out。
• capture onFrame -> rgbaToI420 -> RTCVideoSource.onFrame 必须包在 stream owner 的错误收口内：失败时 stop capture、stop track、close peer、发 explicit stopped/error status，禁止异常穿透到 launchd 进程。
• 视频闭环不能只看 catalog、单测或 <video>.readyState。最低黑盒 gate 是受控 AppKit/窗口 marker 通过 Android WebView canvas 采样到预期颜色；同时确认 daemon /health PID 没变、stream stop 后 capture 子进程清理干净。
• daemon 运行日志路径以 launchd plist 为准；当前全局服务 stderr/stdout 在 ~/.wterm/logs/launchd-stderr.log / launchd-stdout.log，不要只看旧 ~/.zterm/logs。
• remote-window catalog 的 partial source error 不是阻塞弹窗：只要 targets 非空，picker 不显示 iTerm2/source partial error 条；只在无可选目标或顶层失败时显式显示错误。
• remote-window floating stream 不隐藏 QuickBar；只有 picker 和 fullscreen 抑制 QuickBar/IME/body-subscription。浮动预览按 manifest/capture aspect ratio 定尺寸并从边缘等比 resize，入口悬浮标可拖动且不得合成 click，浮窗本体移动只属于 toolbar 并完整处理 pointer capture/up/cancel。Fullscreen 必须有显式按钮、Back/minimize 回浮窗、pinch zoom 和双指本地 pan；最小只能回到 aspect-fit，不显示 minimap。视频 surface 的单指在 floating、1x fullscreen、zoomed fullscreen 都保留远端 Direct Touch scroll/hold-drag/tap 语义，不得被容器 pan 抢走。
• remote-window fullscreen zoom 后只有“双指同向移动”或显式 hand/pan mode 能平移本地容器；单指移动继续实时远端 pixel scroll，单指 tap/hold-drag/right-click 继续远端。Pinch/双指 pan 抬起一指后不得把剩余指自动降级为 local pan 或远端 click；本轮 pair gesture 结束并清理，新的 pointer sequence 才重新仲裁。Android native WebView built-in zoom 必须关闭，避免抢走自定义 pinch。
• remote-window fullscreen 默认 aspect-fit 完整显示；“填满”语义是向 daemon 发送所选远端目标窗口的 window-resize 请求，不是本地 aspect-fill cover/crop，也不是按手机绝对分辨率设置远端窗口。Android 必须用当前 fullscreen 可用显示容器 aspect ratio 和远端窗口当前 desktop width 计算目标 height；daemon 必须完成 AX window resize、原地 ScreenCaptureKit.updateConfiguration，并用 target/capture ACK 回写新 truth；Android 只能在 ACK 后更新本地 projection。禁止为了填满屏幕本地拉伸/裁切冒充 resize，也禁止改 tmux width、terminal mirror 或 renderer。
• remote-window 视频是独立 WebRTC peer connection，但 ICE 配置必须从当前 session traversal route 派生：rtc-direct 用 STUN-only direct ICE，rtc-relay 用 Relay TURN ICE。5G/Relay 下禁止让 remote-window video 用空 ICE 启动，也禁止失败后假装截图/terminal buffer 视频成功。

2.11 Drawer / sheet 交互收口

• 抽屉底部这类单按钮动作只保留一个语义 owner，不要在同一按钮上同时挂 pointerup / touchend / click 再加时间戳去重。
• touch / pointer 只适合手势关闭、拖拽、滑动判定；如果按钮点击在真机上失效，先收敛成单一语义路径，再补回 regression test。
• Android WebView 会在一次 touch 序列结束后合成 click，如果 drawer/sheet 在 release 后才出现在手指下面，这个合成 click 可能命中新出现的 row。任何 row selection 都必须要求 press ownership 从同一 row 内开始；没有 matching row press 的 pointer click 必须丢弃。keyboard/accessibility detail=0 仍允许。
• 抽屉 remote-only catalog row 的点击不是普通 local row switch：session-open owner 必须返回 materialized local sessionId，TerminalPage 只消费这个 id 去更新 focused session-group viewport slot；禁止把 remote:<owner>::session:<name> placeholder 当 active truth，也禁止在 drawer/UI 里新增重连或 transport fallback。回归要模拟 first tap -> owner returns id -> parent rerender with active Session -> center TerminalView 直接渲染新 session，不需要第二次点击。
• 抽屉预览多选里的 remote-only catalog row 也必须走同一 materialize 主线，但要以 background mode 打开：handleOpenGroupSession(..., { activate:false, navigate:false })。预览 selection storage 只存返回的本地 sessionId target；打开失败显式报错，不存 remote:<owner>::session:<name> placeholder，不切真实 shell。
• mirror-fixed 下 renderer 横向裁切平移优先于 shell 抽屉/tab 手势：非左侧热区（包括右侧与中间）的横向拖动都归 TerminalView crop pan；外层 drawer swipe 只允许左侧热区 + previous 方向。禁止因为 fixed 模式需要抽屉入口而重新启用左右两侧 tab swipe。
• mirror-fixed 的手势优先级不能只看起点热区：若当前 horizontal offset 大于 0，右滑仍能真实回移 renderer，TerminalView 必须消费并 stopPropagation() 整次横滑；只有 offset 在手势开始前已为 0，左缘右滑才允许交给 drawer。反模式是子级只 preventDefault() 但让父级 touchend 继续解析成 previous。
• Android drawer 左侧热区当前固定为 64 CSS px：56px 是允许的边缘样本，88px 必须归 mirror-fixed crop pan。96px 在约 347px 宽的手机 viewport 上过宽，会把视觉上已经离开左边缘的右滑误判成抽屉。改热区时必须保留 56px 正向 + 88px 反向成对 gate，并用真机确认非边缘右滑同时满足 drawer hidden 与 fixed offset 变化。
• 抽屉打开、catalog refresh、foreground audit 发现 stale persisted tab 时，不得把 stale tab 提升 active 或 materialize transport；只能更新 catalog/audit truth。若看到缺失 session 错误污染当前界面，先查 open_tab -> active_session 是否被 UI 合成 click 推进，再查 transport error projection。
• Android WebView 的 TerminalSessionDrawer 底部 New Session 例外：真机不能依赖 click 或 pointerup；用按钮自身单一 touchend owner，并 截断父级 drawer 手势。

2.12 Android IME 特殊键门禁

• Android 输入法特殊键必须同时覆盖两条路径：ImeAnchor backspace 事件路径，以及 ImeAnchor key payload 路径。
• native keyCode 必须显式归一：KEYCODE_DEL -> Backspace、KEYCODE_FORWARD_DEL -> Delete、KEYCODE_ESCAPE -> Escape；JS 层再统一映射到终端序列并路由到当前 active session。

2.13 Android WeType / OPlus IME ghost shown 排障

• 触发信号：zterm ImeAnchor 日志显示 showSoftInput(...)=true、onCreateInputConnection() 命中，dumpsys input_method 显示 mServedView=ImeAnchorEditText、mInputShown=true、mIsInputViewShown=true，但截图无键盘且 contentTopInsets 仍接近屏幕底部 / 导航栏（例如 2505）。
• 判断动作：立即用同一台设备、同一默认 IME，在系统 Settings 搜索框这类普通 EditText 做对照。若普通文本框也显示 mInputShown=true / mIsInputViewShown=true 但无键盘，先判定为 IME 进程全局 ghost shown，不再继续改 zterm anchor / renderer / tmux。
• 恢复动作：允许使用明确包级命令 adb shell am force-stop com.tencent.wetype 复位 WeType；这是单包复位，不是 broad kill。复位后重新点击 zterm 键盘按钮，必须用截图和 dumpsys input_method 验证真实键盘窗口展开，contentTopInsets 应变成真实键盘顶部（例如 1509）。
• 反模式：不要把 mInputShown=true 当成视觉闭环；不要用 toggleSoftInput()、重复 guard、renderer reflow、tmux resize、IME 高度猜测或 WebView 清缓存去补偿 WeType ghost 状态。
• 回归测试不能只测中文/文本提交；至少锁 Escape / Backspace / Delete / Ctrl+C。

2.14 Android IME 显隐与底部对齐

• 不主动拉起 IME：terminal mount、terminal tap、session switch、quick editor blur 都不得调用 native show；只有 QuickBar 键盘按钮是 show/hide intent owner。
• QuickBar 键盘按钮是严格 toggle：按下前先读取 native ImeAnchor.getState().keyboardVisible；visible 时 hide，不 visible 时 show。不要用本地 requested flag 或 keyboardInset 猜测显隐。
• toggle show 前必须先把 active renderer 从 reading 对齐回 follow/bottom，再延迟调用 ImeAnchor.show()；native keyboardState(visible=true) 到达后，如果本次是 terminal keyboard request，也要再做一次 follow/bottom realign，覆盖 IME 上台导致的 visual viewport 缩高。否则滚到历史区后键盘上台会裁切到旧 viewport，表现为输入区/底部缺失。
• IME 只允许 UI shell 做裁切/预留：stage reserve = measured QuickBar chrome + IME lift，QuickBar shell 用同一份 IME lift；TerminalView 不接收 IME layout token、不触发 upstream resize、不改 daemon/tmux geometry。
• native ImeAnchorEditText 必须保持可服务输入法的真实 rect，但 cursor 不可见；若截图出现额外蓝色/灰色 native 光标，先查 anchor setCursorVisible(false)。

---

2.15 Session Picker 统一入口规则

• New connection 入口必须先进入 session picker：先列历史连接，再列当前 tmux sessions，最后才是 clean session / full form
• session picker 顶部必须支持手动输入 Tailscale IP / token，并在输入后立即尝试拉 tmux sessions
• session picker 打开时若已有明确 bridgeHost + authToken，必须自动刷新 tmux sessions；不要要求每次人工点击 Connect
• tmux session 列表需要支持最小 CRUD（list/create/rename/kill）以及 multi-select 直接开多个 tabs
• terminal 顶部 + 的长按必须复用同一个 session picker，用于 quick new tab；普通点击再回 Connections
• quick-tab picker 只允许一份 session row projection：daemon tmux session 顺序为主，open tab 状态贴在同一行；daemon refresh 未返回但仍在 OPEN_TABS 的本地 tab 只能追加为 not-reported row，不得隐藏或自动关闭。
• session picker 的 row projection 现在对所有模式都必须合并 open tab，不只 quick-tab；daemon 成功枚举后目标 owner 下未被报告的本地 open tab 应显式关闭，避免双列表和 stale tab。
• OPEN_TABS 已打开 tab 不得按 semantic reuse key 自动合并/替换/删除；同名 tmux session 的 runtime duplicate 只能作为 transport fact，不能顶替 persisted open tab 的 sessionId。saved tab list 导入可做 import-only semantic 去重。
• Terminal drawer 不能维护第二份远端 session 列表；打开抽屉时按稳定 hostKey 触发 fetchTmuxSessions()，结果必须回写同一个 sessionGroups catalog，再由 drawer 投影 remote-only rows。禁止让 drawer effect 依赖整个投影列表，否则 catalog 更新会反复触发枚举。
• 抽屉 / session picker 的远端刷新只允许更新 session catalog / audit fact，不得把 stale persisted open tab 自动推进 transport reconnect，也不得把非 active、非 live 的 tmux_session_unavailable 投影成全局错误 banner。routecodex 这类本地 OPEN_TABS 中的过期 session，若 tmux truth 已不存在，只能表现为缺失事实或 idle closed shell，不能影响当前 session。

2.14 Bridge Auth 规则

• daemon / websocket bridge 必须支持共享 token 鉴权；当前 server 真源是迁移前的 JSON 配置，目标真源是 ~/.zterm/config.toml，WTERM_MOBILE_AUTH_TOKEN 只作为显式 override
• client 的 remembered server / host / picker target 都要携带 authToken，并在 websocket 连接阶段透传
• 验证时必须补一条“无 token 失败 / 正确 token 成功”的证据

2.15 跨尺寸布局统一规则

• phone / tablet / foldable / split-screen / future Mac 只允许共享一套 layout profile 真源；禁止在 ConnectionsPage / ConnectionPropertiesPage / TerminalPage 各自散落 breakpoint
• 大屏效果优先通过 单行多列 + 垂直分屏 的 phone-sized pane 编排获得统一体验；不要先做 desktop-only 页面再回头兼容 mobile
• future Mac 复用 shared app-layer 的页面、会话、存储和 layout primitives；平台壳只补窗口 / 菜单 / 快捷键 / 原生输入差异
• 触发信号：一旦需求里出现 pad / foldable / split-screen / Mac / 多 pane / 多 active tab，就先回到 0001-cross-platform-layout-profile.md 冻结设计，再进入实现
• Jason 当前新增冻结：统一布局默认是一行多列，不以上下堆叠多 pane 作为主方案
• 多 pane 性能规则：active pane 走 active freshness lane；passive visible panes 只能由 lifecycle owner 按 round-robin 一次 tick 刷一个 stale pane，禁止同一 tick 对所有 passive panes 同时 ensureActiveSessionFresh() 造成刷新风暴。
• 多 session split 规则：从单个 session 开 split 时允许生成编号明确的 empty pane；empty pane 点击只打开 scoped session picker，不伪造 session / transport / buffer truth。已有 pane/tab 的长按或右键菜单必须提供 更改 Pn Session 和显式 移到 Pn，移动只改 workspace projection，不能关闭 session 或新建 transport。
• 桌面 packaged/dev 验证若需要重开 ZTerm.app，必须先退出旧实例，再打开新实例；不要直接 open -n 叠多个 app 进程污染证据
• 若参考 Tabby 一类桌面终端，借用的是紧凑 chrome / 顶部状态 tab strip / 左侧 profile rail / 右侧 inspector 的壳层组织；tab strip 至少要承载真实 target / inspector 状态，不能只是静态装饰
• 若桌面端继续推进多 tab，当前最小真边界应优先写成 single runtime · multi tabs：可以维护多个 open target tab，但同一时刻只允许一个 live websocket/runtime；不要把“可切换 tabs”误报成“并发多 live sessions”
• Jason 新冻结：桌面右侧不要先做抽屉；应收成“固定左 rail + 右侧按比例切 multiple vertical panes”的 split workspace，优先给 1 / 2 / 3 preset，风格靠近 iTerm2/Tabby，但不要上来做自由拖拽
• 新冻结：mobile session group 必须拆成两份真相：抽屉显示的 top / center / bottom 是用户显式分配的固定槽位，点击 peek 不得改写；stage 只基于当前 focus slot 计算 viewport projection。focus=top 时 viewport 为 empty / top / center，focus=bottom 时 viewport 为 center / bottom / empty，focus=center 时 viewport 等于固定槽位。focus 必须存 slot name，不能存 session id。抽屉点击 session 只替换当前 focus 槽位：focus=bottom 替换 bottom，focus=top 替换 top，focus=center 替换 center。禁止自动从 session 列表补邻居成 wheel，也禁止点击后循环轮转三槽位。抽屉长按/右键是唯一的槽位分配入口，打开 slot menu 后必须 suppress 下一次 click，避免菜单和 session 激活同时发生。
• mobile session group 的边界可见性必须走共享 projection helper：竖向 top/center/bottom 与未来横向 left/center/right 都先映射到 before/center/after 边界模型。focus 在 before/top 边界时隐藏 before/top peek；focus 在 after/bottom 边界时隐藏 after/bottom peek；center 才显示两侧。UI shell 只消费 projection，不得自己补 top/bottom 或 left/right 局部判断。
• 1946 现场证伪：不要在未完成完整状态机审计前改 TerminalPageStageShell 的 sessionGroupVisible 条件、不要加 “center-only 不进 group”、不要让横屏强行进入 horizontal group、不要调整抽屉选择 session 的切换顺序；这些会破坏竖屏上中下显示和上下滚动。竖屏恢复包必须回到 1945 行为： 才走当前 mobile group stage。

2.16 File Sync 枚举与排序边界

• Android 11+ 本地文件同步必须走 native storage owner；FileTransferSheet 只消费 StoragePermissionPlugin 返回的目录事实，不得在 UI 或 native 枚举层按扩展名、图片类型、隐藏文件名做过滤。
• 文件排序只属于 UI projection：按名称/修改时间、正序/倒序可以在列表投影层切换；不得把排序/过滤状态写回本地 storage owner 或 daemon 文件真源。
• 远端文件列表若协议仍带 showHidden，客户端必须请求完整列表；禁止用默认隐藏文件过滤制造“目录成功但文件消失”的假状态。
• File Sync 的上传语义只负责把本地文件写入远端目标目录并回报 file-upload-complete；禁止把上传后的远端路径写入 tmux、quick input、composer 或任何对话输入框。
• File Sync 上传和本地文件预览不得先用 native readFile() 把整文件转成单个 base64 送进 WebView；上传必须从 native storage owner 逐块 readFileChunk(path, offset, length) 读取，再发送既有 file-upload-start/chunk/end；本地 Markdown 预览也必须 bounded chunk 读取并截断显示。Native 纯读 helper 返回 bytes/bytesRead/eof，Capacitor plugin 才用 android.util.Base64.NO_WRAP 编码，避免大文件 OOM/WebView crash，也避免 minSdk 24 依赖 java.util.Base64。
• File Sync 仍崩而 whole-file read/OOM 路径已排除时，先查 WebView/native bridge 侧 listener churn。useOpenTabLifecycleEffects 的 Capacitor App.addListener('appStateChange') 只能注册一次；render-changing callbacks 必须走 latest ref，sync sheet state change 不得反复 remove/add native listener。回归 gate 是 src/hooks/useOpenTabLifecycleEffects.test.tsx 加 App.dynamic-refresh appState listener 测试，再看真机 logcat 是否仍有 add/remove flood。
• File Sync 下载保存不得把整文件 base64 合并后一次性跨 JS/native bridge 写盘；必须按 file-download-chunk 分块写入 native storage，并在完成后用 stat 校验本地字节数等于远端 totalBytes，失败必须显式进入 transfer error。
• Session resume/switch 入口必须先提交 open-tab active truth，再由同一 switchRuntime: 'explicit-resume' 推进 transport；禁止 resumeActiveSessionTransport() 成功后提前 return，否则首次点击只开连接不切 UI，必须二次点击才可见。

2.17 Loop Governance 初始化规则

• 项目 recurring loop 的唯一入口是 android/docs/loops/LOOP.md，机器真源是 android/docs/loops/loop-manifest.json。
• 当前只允许 zterm.daily-triage 以 L1 report-only 运行：只读项目真源、报告、追加 run log；禁止 product code edits、daemon start/stop、stage/commit、push/merge。
• loop 发现项必须绑定 feature_id、owner、required gate 和 mainline_call_id；mainline_call_id 必须反查到 docs/wiki/mainline-call-map.json 的真实 edge_id。
• 升级到 L2 前必须先有多次 L1 低误报 run history、唯一 owner、required gates、maker/checker 分离和 Jason 明确批准；L3 unattended 默认关闭。
• 任何 loop governance 变更必须跑 pnpm --dir android run test:feature-registry -- --reporter dot，其中 src/lib/loop-governance-truth.test.ts 会锁住 L1 禁动作、kill switch、manifest 和 mainline call ID。

三、开发闭环流程

3.0 测试闭环分层规则

Android / daemon / shared / Mac 任一 terminal 主链改动，都必须按影响面选择验证层级，不能用低层 gate 冒充高层完成。

L0 架构与静态 gate

• 证明：feature owner、function map、类型、禁止路径扫描没有明显破坏。
• 不证明：真实 daemon/tmux/client/UI 可用。
• 常用命令：pnpm --dir android run test:feature-registry -- --reporter dot、pnpm --dir android exec tsc -p tsconfig.json --noEmit --pretty false。

L1 Android client 单元/集成 gate

• 证明：open-tab restore/resume、SessionContext transport、buffer worker、TerminalPage/TerminalView 局部语义正确。
• 不证明：真实 daemon/tmux 或真机 WebView 已闭环。
• 要求：涉及状态机、retry、timeout、错误投影、IME、renderer 可见窗口时，必须有正向和反向测试。

L2 daemon/tmux 真回环

• 证明：当前 daemon 能真实启动，tmux oracle 与 daemon mirror/client replay 一致。
• 默认命令：pnpm --dir android run daemon:mirror:close-loop。
• 不证明：本地客户端入口一定连得上。

L3 本地客户端核心连接 gate

• 证明：仓库内本地 client transport/runtime 能连。若 Mac client 可用，必须跑 Mac gate，不能只用 daemon probe。
• 默认命令：pnpm --dir mac test -- --reporter dot 与 pnpm --dir mac run type-check。
• 覆盖面：remote daemon bridge-transport、local tmux local-tmux-transport、terminal-runtime、workbench active target。
• 不证明：Android 真机或 Mac packaged app 运行态已经正常。

L4 Android UI / WebView gate

• 证明：TerminalPage、IME、drawer、pane、renderer shell 在 Android/WebView 语义下成立。
• 若问题是键盘、容器上抬、输入法特殊键、touch、drawer、可视窗口，不能只跑 L2/L3。

L5 APK / 真机 / 发布态 gate

• 证明：真实安装态和用户路径可用。
• 需要 APK smoke、真实设备、daemon debug、截图/logcat/evidence 中至少与本轮问题相关的证据。

汇报要求：

• 必须列出已跑到哪一层，以及没跑到的层级为什么不在本轮范围。
• 不能把“daemon/tmux 真回环通过”写成本地客户端正常。
• 不能把“Mac client 核心测试通过”写成 Android 真机正常。

3.1 流程图

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ 1.规划  │───▶│ 2.开发  │───▶│ 3.测试  │───▶│ 4.提交  │───▶│ 5.沉淀  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘