sync: update from private repo (6c4d482)

docs/tools/ssh-console-tools.md

@@ -127,6 +127,46 @@ Return (kind=scrollback):
 
 text は ANSI escape strip 済み (色 / cursor 移動シーケンスを除去)。raw が必要な場合は audit log を参照。
 
+## SshConsoleRun
+
+**通常のコマンドは SshConsoleRun を使う。** raw SshConsoleSend は対話操作 (vim/REPL/sudo/TUI) と本当の中断専用。長いコマンドを Ctrl-C で殺さないこと。Ctrl-C は confirm_interrupt:true が必要。
+
+シェルコマンドを実行し、**完了まで blocking して** `{done, exit_code, output}` を返す。`SshConsoleSend` のように「画面取得のタイミングを気にしてから結果を読む」作業が不要で、終了コードも自動取得できる。
+
+| Param | Required | Description |
+|---|---|---|
+| `command` | yes | 実行するシェルコマンド |
+| `connection_id` | no | UUID。**省略時はこの task の active session を自動採用 (推奨)** |
+| `timeout_ms` | no | タイムアウト (ms)。デフォルト 120000 (2分)、最大 600000 (10分)。タイムアウト時もコマンドは kill されない |
+| `idle_ms` | no | 出力が `idle_ms` ms 途切れたら早期終了と判定する。0=無効 (デフォルト) |
+
+Return:
+```json
+{
+  "done": true,
+  "exit_code": 0,
+  "output": "... コマンドの出力 ..."
+}
+```
+
+`done: false` はタイムアウトで終了したケース。`exit_code` は shell が返した終了コード (非 0 はエラー)。
+
+### SshConsoleRun vs SshConsoleSend の使い分け
+
+| 用途 | 使うツール |
+|---|---|
+| 通常のシェルコマンド (ls, grep, systemctl, make, ...) | **SshConsoleRun** |
+| 対話的 TUI (vim, top, htop, tmux, ...) | SshConsoleSend + SshConsoleSnapshot |
+| REPL / sudo パスワード入力 | SshConsoleSend |
+| プロセス中断 (Ctrl-C) | SshConsoleSend({input: "\\x03", confirm_interrupt: true}) |
+| 長時間バックグラウンドを待つ | SshConsoleRun({timeout_ms: 300000}) |
+
+### よくある間違い
+
+- 長時間コマンドに `timeout_ms` を指定し忘れる → デフォルト 2 分でタイムアウト。`timeout_ms` を伸ばすこと
+- コマンドが止まらないからと安易に Ctrl-C を送る → `confirm_interrupt:true` を付けた SshConsoleSend が必要。**SshConsoleRun の途中で別の SshConsoleSend を送ってはいけない**
+- `done: false` を無視してそのまま次に進む → コマンドはまだ動いている可能性がある。SshConsoleSnapshot で状態確認
+
 ## エラー時のリカバリ
 
 | エラー | 対応 |