# Monitor

長時間実行されるスクリプトからイベントをストリーミングするバックグラウンドモニターを起動します。標準出力の各行が通知になります——作業を続けながら、イベントがチャットに届きます。

## 使用タイミング

- デプロイ実行中にログファイルのエラー、警告、クラッシュシグネチャを継続的に追跡する
- リモート API、PR、CI パイプラインを 30 秒ごとにポーリングして新しいステータスイベントを取得する
- ファイルシステムのディレクトリやビルド出力の変化をリアルタイムで監視する
- 多くの反復にわたって特定の条件を待機する（例：トレーニングステップのマイルストーンやキューの消化）
- 単純な「完了まで待機」には**使用しない** — その場合は `run_in_background` 付きの `Bash` を使用する。プロセス終了時に完了通知が 1 回届く

## パラメータ

- `command`（文字列、必須）：実行するシェルコマンドまたはスクリプト。標準出力に書き込まれた各行が独立した通知イベントになる。プロセス終了でモニターが終わる。
- `description`（文字列、必須）：各通知に表示される短い可読ラベル。具体的に書くこと——「deploy.log のエラー」は「ログを監視中」より適切。どのモニターが発火したかを識別するためのラベル。
- `timeout_ms`（数値、デフォルト `300000`、最大 `3600000`）：強制終了の期限（ミリ秒）。この時間を超えるとプロセスが終了される。`persistent: true` の場合は無視される。
- `persistent`（ブール値、デフォルト `false`）：`true` にするとモニターはタイムアウトなしでセッションの間中実行される。`TaskStop` で明示的に停止する。

## 例

### 例 1：ログファイルのエラーとクラッシュを追跡する

この例はすべての終端状態をカバーする：成功マーカー、トレースバック、一般的なエラーキーワード、OOM による強制終了、予期しないプロセス終了。

```bash
tail -F /var/log/deploy.log | grep -E --line-buffered \
  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
```

すべてのパイプで `grep --line-buffered` を使用すること。使用しないと OS が 4 KB ブロック単位で出力をバッファリングし、イベントが数分遅延する。交替パターンは成功パス（`deployed`）と失敗パス（`Traceback`、`Error`、`FAILED`、`Killed`、`OOM`）の両方をカバーする。成功マーカーだけを監視するモニターはクラッシュ時に沈黙する——沈黙は「まだ実行中」と区別がつかない。

### 例 2：リモート API を 30 秒ごとにポーリングする

```bash
while true; do
  curl -sf "https://api.example.com/status" || true
  sleep 30
done | grep --line-buffered -E "completed|failed|error"
```

`|| true` は一時的なネットワーク障害でループが終了するのを防ぐ。レート制限を避けるため、リモート API には 30 秒以上のポーリング間隔が適切。grep パターンを調整して成功と失敗の両方のレスポンスをキャプチャし、API 側のエラーが沈黙でマスクされないようにする。

## 注意事項

- **パイプでは常に `grep --line-buffered` を使用すること。** 使用しないと、OS が 4 KB ブロックが満たされるまで出力を蓄積するため、パイプバッファリングによりイベントが数分遅延する。`--line-buffered` は各行の後に強制フラッシュする。
- **フィルターは成功と失敗の両方のシグネチャをカバーすること。** 成功マーカーのみを監視するモニターはクラッシュ、ハング、予期しない終了時に沈黙する。交替パターンを広げる：成功キーワードに加え、`Error`、`Traceback`、`FAILED`、`Killed`、`OOM` などの終端状態マーカーを含める。
- **リモート API のポーリング間隔は 30 秒以上にすること。** 外部サービスへの高頻度ポーリングはレート制限エラーや禁止のリスクがある。ローカルのファイルシステムやプロセスチェックには 0.5〜1 秒が適切。
- **セッション全体の監視には `persistent: true` を使用すること。** デフォルトの `timeout_ms` は 300 000 ミリ秒（5 分）でプロセスが終了される。明示的に停止するまで実行し続けるには `persistent: true` を設定し、完了したら `TaskStop` を呼び出す。
- **イベント過多による自動停止。** 標準出力の各行が会話メッセージになる。フィルターが広すぎて大量のイベントが発生すると、モニターは自動停止される。より厳密な `grep` パターンで再起動すること。200 ミリ秒以内に届いた複数行は 1 つの通知にまとめられる。
