pueue-job-orchestration

Pueue ジョブオーケストレーション

汎用 CLI テレメトリレイヤーとジョブ管理機能です。pueue 経由で実行されるすべてのコマンドについて、正確な実行時間、終了コードの取得、標準出力／標準エラーの完全なログ、環境のスナップショット、完了時のコールバックを記録します。

自己進化するスキル：このスキルは使用を通じて改善されます。指示が間違っている、パラメーターが変わっている、または回避策が必要だった場合は、後回しにせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。

概要

Pueue は、シェルコマンドのキューを管理する Rust 製 CLI ツールです。次の機能を提供します。

• デーモンによる永続化 - SSH の切断、クラッシュ、再起動後も実行を継続します
• ディスクベースのキュー - 障害が発生しても自動的に再開します
• グループベースの並列処理 - グループごとに同時実行するジョブ数を制御します
• 簡単な障害回復 - 失敗したジョブを 1 つのコマンドで再起動できます
• 完全なテレメトリ - タスクごとに実行時間、終了コード、標準出力／標準エラーのログ、環境のスナップショットを記録します

Pueue 経由で実行するタイミング

操作	Pueue 経由で実行する？	理由
30 秒を超えるコマンド	常に	テレメトリ、永続化、ログの取得
バッチ処理（3 項目超）	常に	並列処理の制御、障害の分離
ビルド／テストのパイプライン	推奨	--after DAG、グループの監視
データ処理	常に	チェックポイントからの再開、状態管理
単発の簡単なコマンド（5 秒未満）	任意	オーバーヘッドは約 100ms ですが、ログを取得できます
対話型コマンド（エディター、REPL）	決して実行しない	Pueue は stdin との対話を処理できません

このスキルを使用するタイミング

ユーザーが次の内容に言及した場合は、このスキルを使用してください。

トリガー	例
でのタスク実行	「これを で実行して」
長時間実行されるデータ処理	「すべてのシンボルのキャッシュを作成して」
バッチ／並列処理	「この 70 件のジョブを処理して」
SSH によるリモート実行	「これを GPU サーバーで一晩実行して」
キャッシュの作成	「ClickHouse のキャッシュを埋めて」
Pueue の機能	「コールバックを設定して」「このジョブを遅らせて」

クイックリファレンス

ステータスの確認

# Local
pueue status

# Remote (<gpu-host>)
ssh <gpu-host> "~/.local/bin/pueue status"

ジョブのキューへの追加

# Local (with working directory)
pueue add -w ~/project -- python long_running_script.py

# Local (simple)
pueue add -- python long_running_script.py

# Remote (<gpu-host>)
ssh <gpu-host> "~/.local/bin/pueue add -w ~/project -- uv run python script.py"

# With group (for parallelism control)
pueue add --group p1 --label "BTCUSDT@1000" -w ~/project -- python populate.py --symbol BTCUSDT

ジョブの監視

pueue follow <id>         # Watch job output in real-time
pueue log <id>            # View completed job output
pueue log <id> --full     # Full output (not truncated)

ジョブの管理

pueue restart <id>         # ⚠ Creates NEW task (see warning below)
pueue restart --in-place <id>  # Restarts task in-place (no new ID)
pueue restart --all-failed # ⚠ Restarts ALL failed across ALL groups
pueue kill <id>            # Kill running job
pueue clean                # Remove completed jobs from list
pueue reset                # Clear all jobs (use with caution)

重大な警告 — pueue restart の動作：

pueue restart <id> は、タスクをその場で再起動しません。元のコマンドをコピーした、新しい ID のまったく新しいタスクを作成します。元のタスクは Done／Failed のまま残ります。ループ内や自律エージェントが使用すると、タスク数が指数関数的に増加します。2026-03-04 のインシデントでは、エージェントが失敗したタスクに対して pueue restart を呼び出し、ジョブ数が 60 件から約 12,800 件に増加しました。

• 本当に再起動する必要がある場合は、--in-place を使用してください：pueue restart --in-place <id>
• 再起動する前に確認してください：pueue log <id> を読み、失敗が継続する原因（データ不足、不正な引数など）がないか確認してください。再試行しても解決しません
• --group フィルターなしで --all-failed を使用しないでください。全グループの失敗したタスクがすべて再起動されます

ホストの設定

ホスト	場所	GPU	並列処理グループ
	~/.local/bin/pueue	RTX 4090	p1 (16), p2 (2), p3 (3), p4 (1)
gpu-host-2	~/.local/bin/pueue	RTX 2080 Ti	p1 (8), p2 (2)
ローカル（macOS）	/opt/homebrew/bin/pueue	N/A	default

主なワークフロー

1. リモートジョブを 1 件キューに追加する

# Step 1: Verify daemon is running
ssh <gpu-host> "~/.local/bin/pueue status"

# Step 2: Queue the job
ssh <gpu-host> "~/.local/bin/pueue add --label 'my-job' -- cd ~/project && uv run python script.py"

# Step 3: Monitor progress
ssh <gpu-host> "~/.local/bin/pueue follow <id>"

2. バッチジョブの送信（複数のシンボル）

レンジバーカッシュの作成など、同様のバッチ処理を行う場合：

# Use the pueue-populate.sh script
ssh <gpu-host> "cd ~/rangebar-py && ./scripts/pueue-populate.sh setup"   # One-time
ssh <gpu-host> "cd ~/rangebar-py && ./scripts/pueue-populate.sh phase1"  # Queue Phase 1
ssh <gpu-host> "cd ~/rangebar-py && ./scripts/pueue-populate.sh status"  # Check progress

3. 並列処理グループの設定

# Create groups with different parallelism limits
pueue group add fast      # Create 'fast' group
pueue parallel 4 --group fast  # Allow 4 parallel jobs

pueue group add slow
pueue parallel 1 --group slow  # Sequential execution

# Queue jobs to specific groups
pueue add --group fast -- echo "fast job"
pueue add --group slow -- echo "slow job"

4. 失敗したジョブの処理

# Check what failed
pueue status | grep Failed

# View error output FIRST (distinguish transient vs persistent)
pueue log <id>

# Restart specific job IN-PLACE (no new task created)
pueue restart --in-place <id>

# ⚠ NEVER blindly restart all failed — classify failures first
# pueue restart --all-failed  # DANGEROUS: no group filter, creates duplicates

再起動前の失敗の分類：終了コード 1（アプリケーションエラー）は、解消されない可能性があります（データ不足、引数の誤りなど、成功する見込みがありません）。終了コード 137（OOM）または 143（SIGTERM）は、一時的な問題の可能性があります。再起動する前に、必ず pueue log を確認してください。

トラブルシューティング

問題	原因	解決策
pueue: command not found	PATH に含まれていない	フルパスを使用します：~/.local/bin/pueue
Connection refused	デーモンが起動していない	pueued -d で起動します
ジョブが Queued のままになる	グループが一時停止中、または上限に達している	pueue status を確認し、pueue start を実行します
SSH の切断によってジョブが終了する	Pueue を使用していない	SSH から直接実行するのではなく、Pueue 経由でキューに追加します
ジョブがすぐに失敗する	作業ディレクトリが間違っている	pueue add -w /path を使用するか、cd /path && pueue add を実行します

優先度スケジューリング（--priority）

優先度の数値が高いほど、キューに空きができたときに先に実行されます：

# Urgent validation (runs before queued lower-priority jobs)
pueue add --priority 10 -- python validate_critical.py

# Normal compute (default priority is 0)
pueue add -- python train_model.py

# Low-priority background task
pueue add --priority -5 -- python cleanup_logs.py

優先度が影響するのは、空きスロットを待機中のキュー内のジョブのみです。実行中のジョブはプリエンプトされません。

タスクごとの環境変数の上書き（pueue env）

stash 済みまたはキュー内のタスクに環境変数を追加または上書きします：

# Create a stashed job
JOB_ID=$(pueue add --stashed --print-task-id -- python train.py)

# Set environment variables (NOTE: separate args, NOT KEY=VALUE)
pueue env set "$JOB_ID" BATCH_SIZE 64
pueue env set "$JOB_ID" LEARNING_RATE 0.001

# Enqueue when ready
pueue enqueue "$JOB_ID"

構文：pueue env set <id> KEY VALUE — キーと値は、それぞれ別の位置引数として指定します。

制約：stash 済みまたはキュー内のタスクでのみ機能します。実行中のタスクの環境変数は変更できません。

プロジェクトの .env との関係：python-dotenv が読み込む .env は、引き続きデフォルト環境の SSoT です。設定ファイルを変更せずに一時的な上書き（例：ハイパーパラメーターのスイープ）を行う場合にのみ、pueue env set を使用してください。

ブロッキング待機（pueue wait）

タスクが完了するまでブロックして待機します。スクリプトではポーリングループより簡単です：

# Wait for specific task
pueue wait 42

# Wait for all tasks in a group
pueue wait --group mygroup

# Wait for ALL tasks across all groups
pueue wait --all

# Wait quietly (no progress output)
pueue wait 42 --quiet

# Wait for tasks to reach a specific status
pueue wait --status queued

スクリプトへの組み込みパターン

# Queue -> wait -> process results
TASK_ID=$(pueue add --print-task-id -- python etl_pipeline.py)
pueue wait "$TASK_ID" --quiet
EXIT_CODE=$(pueue status --json | jq -r ".tasks[\"$TASK_ID\"].status.Done.result" 2>/dev/null)
if [ "$EXIT_CODE" = "Success" ]; then
    echo "Pipeline succeeded"
    pueue log "$TASK_ID" --full
else
    echo "Pipeline failed"
    pueue log "$TASK_ID" --full >&2
fi

---

関連 CLI ツール（）

監視と通知に使える、軽量な CLI ツールが 4 つあり、pueue を補完します。すべて に /usr/local/bin/（noti、mprocs）または apt（ntfy、task-spooler）経由でインストールされています。

noti — 任意のコマンドを Telegram 通知でラップ

「これが終わったら通知して」という一度限りのワークフローに最適です。Telegram をネイティブサポートしています。

# Wrap any command — sends Telegram when it finishes
noti -g moon run kintsugi:catchup

# With execution time in message
noti -g -e python long_script.py

# Custom title/message
noti -g -t "Deploy done" -m "<gpu-host> updated" moon run deploy:<gpu-host>

設定：~/.config/noti/noti.yaml と、~/.bashrc の環境変数 NOTI_TELEGRAM_TOKEN、NOTI_TELEGRAM_CHAT_ID、NOTI_DEFAULT=telegram。

ntfy — スクリプト／コールバックからのプッシュ通知

スクリプト、pueue コールバック、または curl のワンライナーからのプログラムによる通知に最適です。

# One-liner from any script
ntfy pub --title "Backfill done" odb-alerts "BTCUSDT@500 complete"

# With priority and tags
ntfy pub --priority high --tags "warning" odb-alerts "Job failed"

# curl variant (works anywhere, no binary needed)
curl -d "Backup finished" ntfy.sh/my-topic

# Subscribe to topic (poll mode)
ntfy sub --poll odb-alerts

Pueue コールバックとの統合 — ~/.config/pueue/pueue.yml に追加します：

callback: 'ntfy pub --title "pueue: {{label}}" --tags "{{status}}" odb-alerts "Task #{{id}} {{status}} ({{command}})"'

mprocs — マルチプロセス TUI

複数のプロセスを横並びで監視する、対話型 SSH セッションに最適です。

# Watch multiple pueue jobs in split panes
mprocs "pueue follow 3" "pueue follow 7" "pueue follow 8"

# Monitor services
mprocs "journalctl -fu opendeviationbar-sidecar" "journalctl -fu opendeviationbar-kintsugi"

対話型 TTY が必要です（スクリプト経由ではなく、SSH で直接接続してください）。

task-spooler（tsp）— 最もシンプルなジョブキュー

pueue のグループ設定を行わずに、手軽に逐次／並列タスクを実行する場合に最適です。

# Queue tasks (default: 1 parallel)
tsp python train.py
tsp python validate.py

# Set parallel slots
tsp -S 3

# List queue
tsp -l

# View job output
tsp -c 0

# Combine with noti
tsp bash -c 'python train.py && noti -g -m "training done"'

ツールの選択ガイド

Need to...
├── Get notified when a command finishes? → noti -g <command>
├── Send notification from a script/callback? → ntfy pub topic "msg"
├── Watch multiple logs/processes live? → mprocs "cmd1" "cmd2"
├── Quick sequential queue (no groups needed)? → tsp <command>
└── Persistent queue with groups, priorities? → pueue add <command>

---

詳細リファレンス

トピック	リファレンス
インストール（macOS、Linux、systemd、launchd）	インストールガイド
本番環境での教訓：--after によるチェーン処理、フォレンジック監査、年ごとの並列化、パイプラインの監視	本番環境での教訓
状態の肥大化防止、一括 xargs -P 送信、2 層アーキテクチャ（30 万件以上のジョブ）、クラッシュ復旧	状態管理と一括送信
ClickHouse のスレッド調整、並列度の算出式、実行中の調整	ClickHouse の調整
コールバックフック、テンプレート変数、遅延スケジューリング（--delay）	コールバックとスケジューリング
python-dotenv によるシークレット管理パターン、rangebar-py との連携	環境とシークレット
Claude Code との連携、同期ラッパー、テレメトリークエリ	Claude Code との連携
すべての pueue.yml 設定（共有、クライアント、デーモン、プロファイル）	Pueue 設定リファレンス

---

Pueue と Temporal：どちらを使うべきか

耐久性と重複排除が必要な、構造化された反復可能なワークフローには、Temporal（pip install temporalio、brew install temporal）を検討してください。

項目	Pueue	Temporal
最適な用途	アドホックなシェルコマンド、SSH リモートジョブ	構造化された反復可能なワークフロー
セットアップ	単一のバイナリ、インフラ不要	サーバー＋データベース（開発環境：temporal server start-dev）
重複排除	なし — restart は新しいタスクを作成します	ワークフロー ID の一意性（組み込み）
再試行ポリシー	なし — 手動または外部エージェント	アクティビティごと：最大試行回数、バックオフ、再試行不可のエラー
並列度	pueue parallel N --group G	ワーカーの max_concurrent_activities=N
可視性	pueue status（テキスト形式、規模が大きくなると性能が低下）	ページネーション、検索、イベント履歴を備えた Web UI

推奨：アドホックな作業には pueue を使い続けてください。重複排除と再試行ポリシーが重要になったら、構造化されたパイプラインを Temporal に移行してください。両方に適用される不変条件については、devops-tools:distributed-job-safety を参照してください。

---

関連項目

• フック：itp-hooks/posttooluse-reminder.ts - 検出された長時間実行コマンドで Pueue を使うよう促します
• リファレンス：Pueue GitHub
• 関連ツール：noti（コマンドラッパー → Telegram）、ntfy（パブサブ通知）、mprocs（マルチプロセス TUI）、task-spooler（最小限のジョブキュー）
• 最先端の代替手段：Temporal — 重複排除、再試行、可視性を標準搭載した、耐久性のあるワークフローオーケストレーション
• Issue：rangebar-py#77 - 元の実装
• Issue：rangebar-py#88 - 本番環境へのデプロイで得られた教訓

実行後の振り返り

このスキルの実行後、終了する前に以下を確認してください。

1. コマンドは成功しましたか？ — 失敗した場合は、原因となった手順またはエラーの表を修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、それに合わせて使用例とパラメーターの表を更新してください。
3. 回避策が必要でしたか？ — 即興で対応した場合（異なるフラグや追加手順など）は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実在し、再現可能な場合にのみ更新してください。推測に基づく変更は避けてください。