docs: 固化 Webterm PTY 验收规则

.agents/skills/unidesk-webdev/references/playwright.md

@@ -1,7 +1,23 @@
-# Playwright And Fake Server
+# Playwright 与 Fake Server
 
-Use Playwright/fake-server for local reproduction when the real entry or web-probe path needs an isolated fixture.
+- 当真实入口或 web-probe 需要隔离 fixture 时，使用 Playwright 与 fake-server 做本地复现。
 
-- Keep viewport and target URL explicit.
-- Prefer screenshots plus DOM assertions over raw logs.
-- Do not replace real online validation with fake-server evidence when closing user-facing issues.
+- 通用判定：
+  - 视口与目标 URL 必须显式声明；
+  - 优先使用截图与 DOM 断言，不默认输出原始日志；
+  - 关闭用户入口问题时，fake-server 证据不能替代真实在线入口验证。
+
+- xterm canvas 判定：
+  - xterm 使用 canvas renderer 时，不得把 `.xterm-row`、`textContent` 为空判定为终端无输出；
+  - 视觉布局通过截图验证，终端输出语义通过页面加载前安装的只读 WebSocket message recorder 验证；
+  - recorder 只采集当前测试 session 的有界消息：
+    - `session`；
+    - `snapshot`；
+    - `output`；
+  - recorder 不修改 WebSocket 请求、响应或业务状态；
+  - 输入必须从真实 xterm keyboard 或页面虚拟按键进入，禁止用 recorder 或后端直写伪造用户输入；
+  - 输出只返回有界证据：
+    - marker、状态和计数；
+    - 进程组编号和错误布尔值；
+    - artifact 路径；
+  - 禁止回显完整终端内容、cookie、密码、API key 或认证文件。

docs/reference/master-server-ops.md

@@ -136,7 +136,29 @@ changelog。
   - 禁止作为 `oncx` 的 ChatGPT 登录凭据。
 - Webterm：
   - `config/platform-infra/webterm.yaml` 启动 `mycx`；
-  - wrapper path 或启动方式变更必须保留原入口并执行 Webterm launch check。
+  - YAML 是 target、镜像、端口、启动命令、fallback shell、挂载和公网暴露的唯一真相；
+  - 关闭公网暴露：
+    - `publicExposure.enabled: false` 时，DNS、FRP 和 Caddy 字段不参与解析与验证；
+    - `plan`、`status` 和 `validate` 必须明确返回 `skipped`。
+  - target 校验：
+    - 按 YAML 中的实际端口和 `TERMINAL_SHELL` 只读挂载判断；
+    - 禁止把 `7683`、固定挂载数量或其他实例值写入代码门禁。
+  - PTY 所有权：
+    - `nsenter` 或 `chroot` 后必须由唯一的长期交互 Bash 持有 PTY；
+    - 禁止让外层非交互 Bash 等待内层交互 Bash，再在内层退出后创建 fallback shell。
+  - 启动命令中断：
+    - 持有 PTY 的 Bash 必须在启动命令运行期间显式处理 `SIGINT`；
+    - 前台子命令退出后继续执行 fallback，再恢复默认 handler；
+    - fallback shell 必须由原进程 `exec`，禁止创建新的等待层。
+  - Webterm launch check：
+    - wrapper path 或启动方式变更必须保留原入口；
+    - 从真实 Web/xterm 入口启动 `mycx`、发送 `Ctrl+C` 并执行 marker；
+    - 确认会话仍为 `running`；
+    - 确认没有 `initialize_job_control`、`no job control` 或非主动 `logout`。
+  - foreground process group 验证：
+    - 使用 Bash 内建 `read < /proc/$$/stat` 同时读取 `pgrp` 和 `tpgid`；
+    - 禁止用外部 `ps` 读取后直接比较；
+    - `ps` 执行期间会暂时成为 foreground process group，导致错误的不相等结果。
 - Shell startup 文件：
   - 禁止定义同名 function 覆盖这些 executable；
   - 禁止在启动时重新生成 profile 文件；