Real Terminal TUI Harness

real-terminal harness 在一个子进程中启动 OpenTUI 聊天界面，在 tmux 可用时通过 tmux 驱动它，必要时回退到 PTY，并将证据存储在 .artifacts/tui-real-terminal/runs 下。

Platform requirements (Windows needs WSL2)

该 harness 通过 tmux 或一个 Unix 伪终端（Python 的 pty module）驱动真实终端。 两者都仅限 Unix：

• pty 仅在 Unix 上随 Python 标准库提供；在原生 Windows 上 import pty 会失败，因此没有 PTY driver。
• tmux 没有原生的 Windows 构建。

此 harness 不支持原生 PowerShell，Windows 用户必须在 WSL2 下运行它。 在一个 WSL2 发行版内，Linux 的 pty/tmux 栈的工作方式与在 Linux 上完全一致：

# In an elevated PowerShell, once:
wsl --install            # installs WSL2 + a default Ubuntu distro

# Then inside the WSL2 shell, install tmux and run the harness:
sudo apt-get update && sudo apt-get install -y tmux
uv run pytest tests/integration/cli/tui_real_terminal -q

当 tmux 与 PTY 都不可用时（例如原生 Windows CI）， probe_terminal_capabilities() 会报告 preferred_driver="none"，并且每个 scenario 测试都会以一个命名了缺失能力的 pytest.skip 原因被跳过——该运行不会 失败。纯逻辑 driver、capability-probe 与 scenario-model 单元测试在每个平台上都会 运行。

Commands

Fast smoke:

uv run pytest tests/integration/cli/tui_real_terminal/test_launch_input_loop.py -q

Full deterministic suite:

uv run pytest tests/integration/cli/tui_real_terminal -q

Manual lab:

uv run python scripts/tui_real_terminal_lab.py --scenario long_streaming --backend opentui

OpenTUI backend path:

uv run pytest tests/integration/cli/tui_real_terminal -q --tui-backend opentui

opentui backend 通过 real-terminal harness 运行确定性的 fake-provider apps。 存在一个受保护的 live-opentui backend，用于手动的真实 CLI smoke 检查：

OPENSQUILLA_TUI_LIVE_REAL=1 uv run pytest \
  tests/integration/cli/tui_real_terminal/test_live_opentui_real_cli.py -q \
  --tui-backend live-opentui --tui-driver tmux

OPENSQUILLA_TUI_LIVE_REAL=1 uv run python scripts/tui_real_terminal_lab.py \
  --scenario live_opentui_architecture_prompt --backend live-opentui

该 live smoke 以 OPENSQUILLA_TUI_BACKEND=opentui 启动 opensquilla chat --standalone，通过 tmux 驱动它，发送一个真实 prompt，并捕获 文本证据。请谨慎使用它，因为它可能会命中已配置的 live provider。

Evidence

每次运行都会写入：

• scenario.json
• terminal.log
• app.log
• transcript.txt
• frames/*.txt
• screenshots/
• result.json
• visual-verdict.json

能力缺失是显式的跳过。确定性的断言失败会阻塞。带 inspect 的 visual verdicts 在不阻塞无关 backend 变更的情况下保留证据。