tui-troubleshooting

TUI のトラブルシューティング：フリーズ、ハング、画面の空白化、ターミナル状態の破損

ユーザーから TUI が「フリーズした」「ハングした」「ターミナルが真っ白になった」「入力を受け付けなくなった」「ターミナルが壊れたままになった」「あるターミナルでは動くが、別のターミナルでは動かない」と報告された場合は、このスキルを使用してください。原因が判明するまでは、ターミナルのライフサイクルに関する障害として扱ってください。

最初の応答でのルール

表面的なチェックリストを提示しないでください。障害の種類を特定し、起動とクリーンアップの順序を調べ、具体的なライフサイクル上のバグを探してください。

1. アプリは raw モード、代替画面、マウス、フォーカス、またはブラケット付きペーストを有効にしますか？
2. 通常終了、Ctrl-C、例外、パニック、Promise の拒否、早期リターンのそれぞれで、すべてのモードが復元されますか？
3. ターミナルのセットアップ後も stdin から入力が流れていますか？
4. 非同期処理や入力を待つ前に、アプリは少なくとも 1 フレームを描画してフラッシュしますか？
5. ログ、stderr、バックグラウンドタスク、子プロセスが同じターミナル画面に書き込む可能性はありますか？
6. バグは tmux、SSH、Windows/ConPTY、CI、または TTY ではないパイプでのみ再現しますか？

発生頻度の高いフリーズ原因

特殊なターミナルプロトコルの問題より先に、次の原因を優先して確認してください。

• raw モードを復元していない。 エコーが無効になり、行編集もできなくなるため、クラッシュや早期リターンの後にシェルがフリーズしたように見えます。
• 一時停止した stdin を再開していない。 Node では、process.stdin.pause() の後に resume() せず raw モードにすると、data イベントが発生しません。UI は応答を永久に待ち続ける可能性があります。
• 初回描画がない。 アプリが代替画面や raw モードに切り替えて非同期のステータス確認を開始しても、初期フレームをフラッシュしないため、ユーザーには空白の画面が表示されます。
• 起動時の処理がブロッキングしている。 最初の描画より前に同期的なファイル、ネットワーク、またはプロセス呼び出しを行うと、イベントループや描画ループが停止します。
• 入力モードが一致していない。 stdin が raw モードなのに行単位の入力を待っている、または cooked モードや一時停止中なのに raw キーイベントを待っている状態です。
• クリーンアップによるモードの漏れ。 終了後も代替画面、マウスレポート、フォーカスイベント、またはブラケット付きペーストが有効なままになります。

最小限の診断方針

次の情報を求めるか、確認してください。

• 言語／フレームワークとターミナルライブラリ。
• プロセス開始から初回描画までの起動シーケンス。
• クリーンアップ、ガード、finally、defer、Drop、atexit、シグナルハンドラー。
• stdin/stdout/stderr が TTY かどうか。
• ローカル、SSH 経由、tmux/screen/Zellij 内、Windows 上、または CI で問題が発生するか。
• raw モードでのターミナルの症状：エコーが無効、カーソルが非表示、代替画面が空白、ペースト用のラッパー、マウスクリックが無視される、シーケンスが文字化けする。

ユーザー向けの復旧コマンド

ターミナルが操作不能になった場合は、詳しいデバッグに進む前に、復旧方法をユーザーに伝えてください。

stty sane
reset
printf '\033[?1049l\033[?25h\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?1004l\033[0m'

Windows PowerShell では、子プロセスによって ConPTY の状態が壊れた場合、タブを閉じるのが最も手早い復旧方法となることがあります。

推奨する修正パターン

すべての TUI で、ライフサイクルを単一の管理主体に担わせてください。

1. TTY であることを確認するか、非 TUI モードを選択します。
2. 最初にクリーンアップガードを設定します。
3. 代替画面／raw モードと、必要に応じてマウス／ペースト／フォーカスの各モードを有効にします。
4. raw キーイベントが必要な場合は、stdin を再開／ref します。
5. すぐに初期フレームを描画してフラッシュします。
6. 初回描画の後に非同期処理を開始します。
7. ログを、制御中のターミナル画面以外に出力します。
8. モードを逆順に、必ず 1 回だけ復元します。

参考ファイル

• references/freeze-hang-diagnosis.md - 起動時および実行中のハングについて、根本原因、症状、診断方法、修正例、予防パターンを説明します。
• references/terminal-state-corruption.md - 画面の文字化け、色の異常、カーソルの不具合、不完全な描画、書き込みの混在、リサイズと描画の競合を扱います。
• references/diagnostic-playbook.md - フリーズ、ターミナル状態の異常、入力がない問題、SSH/tmux、Windows、文字化けした出力について、具体的なコマンドを含む判断フローを示します。