Tuistory 是通过虚拟 PTY 执行终端 TUI 自动化的驱动机制，属于 droid-control 工作流的后台知识，不直接调用。它提供 Playwright 风格的 CLI，可在虚拟 PTY 中启动目标命令，进行文本输入、按键、等待、快照与录制。
用途与场景：常规 TUI 自动化与回归检查、针对虚拟屏幕缓冲区的确定性 wait / wait-idle、获取用户所见文本快照，以及无需证明真实终端键盘编码的场景。若需验证 Ghostty 或 Kitty 对某按键的实际输出，应改用 true-input。
安装：npm install -g tuistory（或 bun add -g tuistory）。可选依赖 tmux（回滚流）、asciinema（录制）、agg（.cast 转 .gif）。
核心用法通过 tctl 完成，例如启动会话：$TCTL launch "droid-dev" -s demo --backend tuistory --repo-root /path/to/worktree --cols 120 --rows 36 --env FORCE_COLOR=3 --env COLORTERM=truecolor，随后可 wait、type、press、snapshot --trim、close。droid-dev 启动必须提供 --repo-root；启动时务必传入颜色环境变量，否则 Node.js 应用会抑制颜色转义码。支持选项包括 --cols、--rows、--cwd、--env、--record。录制须在启动时用 --record 设置，tctl 会将 asciinema rec 包裹在 PTY 外；可对两个 worktree 分别启动会话做前后对比，回放用 asciinema play。仅当需要终端模拟器回滚流时才用 --tmux。
限制与已知死路：不要直接调用 asciinema rec，否则 stdin 转发会中断、按键回显到外层 PTY，且 tuistory 命令找不到会话；不要向原始 tuistory 传 --record、--backend、--repo-root、--env 等 tctl 专有参数，会导致 tuistory-relay 崩溃。仅在 tctl 不可用时，可作为最后手段使用原始 tuistory（仅支持 --cols、--rows、-s，且不支持录制）。