emrg: TUI exit clears the terminal screen (rant 2026-08-18T11:13:17)

Agent.md

@@ -118,7 +118,7 @@ Community needs voiced in HN agent-UI discussions map directly to EMRG's design:
 pkill -f "emrg.server"; rm -f ~/.emrg/emrgd.port; python -m emrg
 ```
 
-Python: `uv run pytest tests/ -v` (933) — import check: `uv run python -c "from emrg.client.app import run_client"`
+Python: `uv run pytest tests/ -v` (934) — import check: `uv run python -c "from emrg.client.app import run_client"`
 GUI: `cd emrg/gui && npm test` (258: 45 daemon_client + 19 conn-manager + 22 app-commands + 129 renderer smoke + 16 i18n + 7 integration + 3 commands + 8 build-config + 7 gui-state + 2 tool-group) — syntax: `node --check main.js preload.js daemon_client.js renderer/js/*.js`
 CI: `uv run pytest` (ubuntu + **windows-2025 matrix** — Windows pytest 回归在 PR CI 即失败，v0.2.29 教训 #725) + GUI tests + **actionlint workflow lint** (`rhysd/actionlint@v1.7.12` gate, #444 — workflow 解析错误在 PR CI 即失败，如 `if:` secrets 上下文)
 Re-trigger: `scripts/re-trigger-ci.sh [branch]` (workflow_dispatch, #527 — 替代空 commit 重触发：Actions outage 会整段丢弃 push 事件，dispatch 走 API 路径不受影响)

emrg/client/python_tui/terminal.py

@@ -472,6 +472,9 @@ def shutdown(self) -> None:
         if self._raw_mode:
             self._exit_raw_mode()
         sys.stdout.write(CURSOR_SHOW)
+        # rant 2026-08-18T11:13:17：退出时清屏 — 只归位 (0,0) 不清屏会残留界面内容。
+        # 顺序：先清屏再归位（2J 清屏后光标留在末行，需 CURSOR_HOME 回到 (0,0)）。
+        sys.stdout.write(CLEAR_SCREEN)
         sys.stdout.write(CURSOR_HOME)
         sys.stdout.write(RESET_SCROLL_REGION)
         sys.stdout.write("\x1b[?2004l")

tests/test_terminal_render.py

@@ -78,3 +78,19 @@ def test_render_grow_no_clear_screen():
     _set_width(term, 60)
     out = _render(term)
     assert CLEAR_SCREEN not in out
+
+
+def test_shutdown_clears_screen():
+    """退出清屏（rant 2026-08-18T11:13:17）：shutdown() 必须发 CLEAR_SCREEN。
+
+    只归位 (0,0) 不清屏会把 TUI 残留留在终端里（退出后界面内容仍在屏幕上）。
+    """
+    term = Terminal()
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        term.shutdown()
+    out = buf.getvalue()
+    assert CLEAR_SCREEN in out, "shutdown() must emit CLEAR_SCREEN (TUI residual on exit)"
+    # 清屏后归位 (0,0)：CLEAR_SCREEN 之后必须紧跟 CURSOR_HOME
+    from emrg.client.python_tui.output import CURSOR_HOME
+    assert out.index(CLEAR_SCREEN) < out.index(CURSOR_HOME), "clear screen must precede cursor home"