# Verification evidence

验证日期：2026-07-23。

## Automated suites

```text
TypeScript: 11 files, 47 tests passed
Rust: 11 tests passed (protocol validation, aligned renderer, native autofit, render-frame classification, rotation filtering, frame-rate gate, latest-frame output)
TypeScript typecheck: passed
rustfmt: passed
clippy -D warnings: passed
npm audit --omit=dev: 0 vulnerabilities
```

覆盖行为：

- fragmented PIV1 message parsing；
- `rgb0` stride padding；
- true-color half-block mapping；
- canonical config layering, opt-in `videoPath`, `maxHeightPercent` validation, ignored intro files/env, and ordinary unknown-key rejection for `minRows`；
- latest-frame replacement and resize deduplication；
- render-box Widget Interface, zero-row startup, arbitrary FRAME geometry, cached-frame resize reuse, stale-frame rejection, and dismissal；
- startup-only lifecycle gate；
- native 64-byte allocation alignment and header layout；
- 30→15 FPS alternating emit/skip and low-FPS passthrough；
- slow-pipe latest-frame replacement；
- stdin `EPIPE` handling and exact first Widget size；
- Escape/Ctrl+C-only dismissal and character-key passthrough；
- `aboveEditor` Widget placement, layout-available percentage capping, multiline editor sizing, Ghostty output workaround, immediate handler completion, keyed cleanup, and shutdown/config-load race；
- real Pi TUI differential rendering: simultaneous conversation/video updates remain incremental and do not emit a full-screen clear；
- acceptance ANSI phase classification、headless screen/layout replay、native/screen 双重 frame progression、真实 Widget lifecycle、strict machine verdict、deterministic OpenAI SSE/handler drain、PTY input/resize、PIV1 proxy transparency/signal forwarding 和 timeout process-group cleanup。

## Repository acceptance command

仓库现可直接复现真实 Pi TUI 证据：

```bash
npm run acceptance:tui -- \
  --video "/absolute/path/video.mp4" \
  --scenario baseline
```

2026-07-23 在 Pi/Pi TUI 0.81.1、Node.js 25.9.0、Python 3.14.6、libmpv 2.5.0 上用 `--scenario all` 逐个隔离运行全部场景，聚合报告和 7 个场景报告均为 `passed`：

| 场景 | 结果 | 关键证据 |
| --- | --- | --- |
| `baseline` | pass | `maxHeightPercent: 50`、`120x40`，stream phase 内 75 个 PIV1 sequence/3 个 screen signature、16/16 完整视频行、0 streaming clear、0 resize、0 残留。 |
| `resize` | pass | `120x40 -> 160x50`，settled phase 后 12 个 sequence/2 个 screen signature、1 次预期 full redraw、1 条 `resize 160 42`、稳定阶段 0 clear。 |
| `editor-wrap` | pass | stream phase 内 62 个 sequence/2 个 screen signature；500+ 字符使 box `120x32 -> 120x28 -> 120x32`，消息完整到达 provider，streaming clear 为 0。 |
| `eof` | pass | 31.2 秒媒体输出完整 468 个 sequence，END reason 为 `eof`，Widget 移除，0 残留。 |
| `ctrl-c` | pass | 第一次 Ctrl+C END reason 为 `stopped`，`q ACCEPTANCE_CTRL_C_KEPT` 随后完整提交。 |
| `ctrl-d` | pass | 空 editor 触发 Pi code 0 shutdown，真实 `setWidget` mount/remove 各 1 次，END reason 为 `stopped`，0 残留。 |
| `ghostty` | pass | 71 个 sequence；播放期 DEC 2026 marker=0、video-line erase=0；关闭后 marker=2，writer 已恢复。 |

全部场景的 native exit code 均为 0、runtime error events 均为空、真实 `setWidget` mount/remove 均各 1 次，且 owned process 残留均为 0。另在 baseline PTY 启动后直接向 acceptance Node entry 发送 SIGTERM；入口等待 helper 与 owned process group 清理，报告 `interruptedSignal=SIGTERM`、残留 0，并以 code 143 退出。

另以 5.016 秒媒体运行 `eof`，并使用 `/tmp/验收 媒体 空格.mp4` 作为调用路径；preflight、isolated config 和 native argv 均原样保留该中文加空格路径，输出 76 个 sequence 后正常 EOF。缺少 `--video` 时命令非零退出，并生成 `phase: "preflight"` 的失败报告，不会产生伪通过。

完整 Interface、artifact 和权限边界见 [`acceptance.md`](acceptance.md)。

## Native media probe

真实素材探针：

```text
video: H.264 1280x720 30.000 FPS
render box: 80x40
output: rgb0 71x40 at 15 FPS frame budget
frames: 30
pixel range: 0-255
non-black channels: 255,582
audio: AAC 44100Hz stereo
output backend: coreaudio
exit: 0
```

当前 probe 对 1280×720@30 FPS 和 1920×1080@25 FPS 两段真实素材均输出 30 帧并命中 `71×40`；同一 libmpv handle 分别初始化 CoreAudio 44.1 kHz 和 48 kHz stereo。Native 探针 CPU：0.19s user + 0.06s system / 3.65s wall，约占一个 CPU core 的 7%。此前的大面积压力测试在 160×50 终端取 8 个一秒样本：Pi/Node + native 平均 16.1%、峰值 22.1%；在 240×70 终端取 5 个样本：平均 29.4%、峰值 31.6%。两组均低于 80% 阈值。

## Pi TUI end-to-end

使用 pseudo-terminal 启动真实 Pi 0.81.1：

```bash
PI_TUI_WRITE_LOG=/tmp/pi-video-tui-tui.log \
PI_OFFLINE=1 \
pi --offline --no-extensions -e ./src/index.ts
```

视频播放期间向 Pi 输入 `qINPUT_KEPT`，画面继续播放；随后按 Ctrl+C 关闭视频并追加 `_AFTER`。最终 editor 中 `qINPUT_KEPT_AFTER` 完整可见，证明 `q` 不会跳过，且播放 listener 消费 Ctrl+C 时不会清空 Pi 输入。结果：

```text
Pi exit code: 0
TUI log bytes: 7,744,799
qINPUT_KEPT visible during playback: true
video active after q: true
qINPUT_KEPT_AFTER preserved after Ctrl+C: true
video removed after Ctrl+C: true
half-block characters: 201,840
24-bit color sequences: 404,683
alternate-screen enter sequences: 0
playback/config/protocol errors: 0
remaining pi-video-tui-native processes: 0
```

另在视频播放中对空 editor 发送 Ctrl+D，Pi 通过 `session_shutdown` 正常退出且 sidecar 已释放。播放期间提交 `/reload` 也会移除旧 Widget 并将 sidecar 降到 0；新 session 的 reason 为 `reload`，不会重复播放。

本次回归使用本地确定性 provider 在真实 Pi 0.81.1 PTY 中持续发送 assistant tokens，同时输入普通字符、`q` 和 Enter。最初未保留 conversation 空间的 `120×40` 场景产生 119 次 `CSI 2J/H/3J` 整屏 clear；固定 1/8 预算原型随后证明 extension-only cap 可以让普通流式更新保持增量。最终实现改为用户配置的 `maxHeightPercent`，不再硬编码该预算。

最终 50% 验收中，`120×40` 的最大 box 为 `120×32` pixels（16 terminal rows）；resize 到 `160×50` 后为 `160×42`（21 rows）。整个 resize 只发生 1 次预期整屏 redraw 和 1 条 `resize 160 42`，settled phase 后 12 个 native sequence/2 个 screen signature 继续推进且稳定阶段 0 clear。

输入额外 500+ 字符并按 Enter 提交时，box 只发生 `120×32 -> 120×28 -> 120×32` 两次有效 resize，整段 streaming clear 为 0，完整消息到达 provider。Ctrl+C 路径中第一次 Ctrl+C 只关闭视频；空 editor Ctrl+D 完成 code 0 teardown。中文加空格路径、自然 EOF、Ghostty writer restoration 和所有场景的零残留均由同一仓库验收命令覆盖。

任意比例 fixtures 继续通过直接 render-box 回归：在 `160×86` box 中得到 4:3 `114×86`、9:16 `48×86`、21:9 `158×68`、container-metadata-rotated 3:4 `64×86`，全部水平居中。另验证 1:1 `86×86`、SAR 16:15 的 720×576 素材输出 4:3 `114×86`，以及同一 SAR 素材叠加 container rotation 后在 80×40 box 输出 3:4 `30×40`。每类检查 10 个纯白 framebuffer，四边最小亮度均为 255，确认没有 letterbox；90/180/270° 四色象限的方向均正确；180° `--max-frames 1` 首帧重复 100 次均已是正确方向，验证 unpause 不会越过异步 rotation command barrier。尝试扩大 21:9 surface 到 `159×68` 或 `160×68` 时边缘亮度会降到 0，因此 `158×68` 是当前 half-block 量化下的最大无整像素黑边尺寸。

libmpv 现在 paused 启动；load、rotation、unpause 使用 render-thread-safe `mpv_command_async`，延迟失败由 event thread 的 `COMMAND_REPLY` 处理。1 秒 10 FPS 的 container-rotation fixture 输出完整 10 帧；另一个 1 秒 10 FPS fixture 连续自然 EOF 100 次均严格输出 10 帧；geometry 前的 update 保持排队；unpause 后第一个 `PRESENT` 发布一次，`NEXT_FRAME_INFO` 再排除后续 `REDRAW/REPEAT`，确认 startup/EOF redraw 不再造成 9/11 帧。修复前 rotation 路径只输出 7 帧。audio-only fixture 以 `media has no playable video track` 明确失败，不再以无 READY/FRAME 的成功 EOF 结束。启动瞬间 stop 连续运行 30 次，最慢 495 ms，残留 sidecar 为 0。

对 `117×66`、`152×86`、`85×48`、`160×90` 四组 framebuffer 各检查 30 帧，四组均没有整像素黑边。另检查完整源视频的 468 帧及 8 个 libmpv 时间分段共 480 帧，均没有孤立黑横线，确认故障发生在 framebuffer 之后。

Ghostty 1.3.1 的 DEC 2026 incremental-update 压力循环并行播放 8 个时间分段，每段抓取 70 个彩色 TUI 快照。修复前检测到 6 条内部黑横线；视频期间移除 sync 标记及视频行前冗余 `CSI 2K` 后为 0。最终用 80.213 秒素材再抓取 160 个彩色 TUI 快照，孤立横线仍为 0，`qINPUT_KEPT` 和 Escape 清理均通过。该行为与 Ghostty 已知的 [DEC 2026 incremental rendering corruption](https://github.com/ghostty-org/ghostty/discussions/11002) 一致。

本次 layout 回归另以 `TERM_PROGRAM=ghostty` 运行真实 Pi PTY：182 个相关快照为 0 次整屏 clear，播放区间内 DEC 2026 marker 和视频行 `CSI 2K` 均为 0；视频关闭后出现 4 个 DEC 2026 marker，证明 terminal writer 已恢复。尝试启动独立 Ghostty Metal 窗口复测时被 macOS 的外部脚本执行确认框拦截，且当前进程没有辅助功能权限，因此没有把该次窗口截图计入新视觉证据。

这些序列来自 Pi renderer 的最终输出。sidecar stdout 被 Node pipe 捕获并只含 PIV1 binary frames，因此该证据区分了“Pi Widget 合成”与“mpv 直接接管终端”。

## Package discovery and failure recovery

使用隔离的 `PI_CODING_AGENT_DIR` 执行 `pi install /absolute/path/to/pi-video-tui` 后，不传 `-e` 启动 Pi。package manifest 自动发现扩展并正常渲染视频，退出码 0，错误数 0，残留 sidecar 数 0。

另将约 417 KB 的 `0.2.0` tarball 安装到全新 production npm 项目。tarball 中 `target/` 文件数为 0，`postinstall` 从随包 Rust 源码成功生成可执行 sidecar，并链接 `/opt/homebrew/opt/mpv/lib/libmpv.2.dylib`；再以安装目录作为 `pi -e` package 启动真实 PTY，渲染 22,400 个 half-block，退出码 0，extension error 与残留进程组均为 0。

随后在隔离用户配置中指定不存在的视频路径。扩展显示 `video is not accessible`，没有启动 sidecar；输入的 `ERROR_MARKER` 进入 Pi editor，证明配置/文件错误不会阻塞会话。

## Natural EOF and Pi recovery

另一次 pseudo-terminal 会话未发送跳过键，完整播放 31.2 秒视频。第 29 秒画面仍存在，第 34 秒 Widget 已自动移除；随后 `EOF_WIDGET_MARKER` 正常进入 Pi editor。会话退出码为 0，且没有 alternate-screen 序列、播放错误或残留 sidecar。

```text
Pi exit code: 0
TUI log bytes: 69,828,100
video active at 29 seconds: true
video removed at 34 seconds: true
EOF_WIDGET_MARKER accepted by Pi editor: true
half-block characters: 1,843,800
alternate-screen enter sequences: 0
playback/config/protocol errors: 0
remaining pi-video-tui-native processes: 0
```