minion-orchestrator

Minion Orchestrator

契約

Minions は、永続性と可観測性を備えたバックグラウンド処理のための、Postgres ネイティブなジョブキューです。 この単一のスキルで、次の 2 つのレーンを扱います。

• 決定論的なシェルジョブ（gbrain jobs submit shell ...）
• LLM サブエージェントジョブ（gbrain agent run ...）

Minions にルーティングするタイミング：再起動後も維持する必要がある、可観測性を備えた作業、多数の並列タスクに分散させる作業、またはセッションをまたいで保持する作業です。ルーティングポリシーは skills/conventions/subagent-routing.md で定義されています。プロジェクトのデフォルトは pain_triggered（まずネイティブのサブエージェントを使用し、特定の問題シグナルが発生した後に Minions を使用）です。モード A（すべてを Minions 経由で処理）はオプトインです。

保証：

• ジョブはゲートウェイの再起動後も維持されます（Postgres によってバックアップされています）
• すべてのジョブに、構造化された進捗状況、トークン使用量、セッショントランスクリプトが記録されます
• 実行中のエージェントは、受信トレイのメッセージを介して実行中に方向を調整できます
• ジョブはいつでも一時停止、再開、キャンセルできます
• 設定可能な失敗ポリシーを備えた親子 DAG

永続実行の原則（エージェントが従うルーティング規約。機械的な強制はありません。「永続実行」を参照）：

• 約 2 分を超えると予想される操作は、セッション終了時に停止する単独のバックグラウンドシェルではなく、機能ラダーを経由します。
• デッドマンチェックでは、プロセスが終了したかどうかだけではなく、結果がユーザーに報告されたかどうかを確認します。完了イベントが取りこぼされると、ユーザー側からはジョブが停止したように見えます。
• デッドマンは二次的な保険であり、配信を保証するものではありません。発火前にデッドマン自体が停止する可能性があります（スケジューラーの再起動、エントリーの削除など）。バックストップとして、次のターンで gbrain jobs list --status active と最近の完了ジョブを確認し、結果がユーザーに届いていない期限超過の作業を探します。
• デッドマンチェックは冪等です。二重発火や、通常の完了報告と競合する発火では、何も報告されません。まず報告済み状態を確認し、復旧報告にはジョブ ID を付けて重複を検出できるようにします。
• チェックポイントや進捗ファイルは、鮮度を確認した場合にのみ信頼します。古いチェックポイントは永久に「実行中」と読み取られます。タイムスタンプを予想される進捗間隔、および gbrain jobs get <id> と照合してください。

リクエストのルーティング：シェルジョブかサブエージェントか

条件	アクション
ユーザーが決定論的なコマンド／スクリプトの実行を依頼している	シェルジョブ（CLI：gbrain jobs submit shell ...）
ユーザーが「minions で実行」と依頼し、明示的なコマンド／argv を指定している	シェルジョブ（CLI。cmd または argv を含む --params を指定）
ユーザーが調査、推論、反復的なエージェント処理を依頼している	サブエージェントジョブ（CLI：gbrain agent run）
ユーザーがエージェントの方向調整、一時停止、再開を依頼している	サブエージェントのジョブライフサイクルツール（MCP から呼び出し可能）
約 30 秒未満の単純な操作が 1 つだけの場合	まずインライン実行を検討します
再起動後の耐久性／可観測性が必要な場合	Minion ジョブとして送信します
約 2 分を超えると予想される操作	永続実行ラダー（以下）を経由します
並列作業（2 つ以上のストリーム）	gbrain agent run --fanout-manifest、または親エージェント＋子サブエージェント

意図が曖昧な場合は、確認を 1 つだけ尋ねます。 「決定論的なシェルコマンドジョブと、LLM エージェントジョブのどちらをご希望ですか？」

シェルジョブ（決定論的スクリプト）

LLM による推論ループが不要な、再現可能なコマンド実行、ETL の手順、cron 作業、スクリプト化可能なタスクに使用します。

前提条件（最初のシェルジョブを送信する前にお読みください）

• ワーカーは gbrain jobs work --allow-shell-jobs を指定して起動する必要があります（ワーカー上で GBRAIN_ALLOW_SHELL_JOBS=1 をエクスポートする方法でも同じです。ワーカーのディレクトリにある .env では設定できません）。 シェルハンドラーは常に登録されていますが、実行はガードされています。フラグなしのワーカーがシェルジョブを受け取ると、直ちにデッドレターになります（UnrecoverableError が発生し、再試行なしで dead に移動します）。error_text に必要なフラグが示されます。ジョブが waiting のままなら、実行中のワーカーがまったくありません。gbrain jobs supervisor status を確認してください。ゲートは src/core/minions/handlers/shell.ts にあります。
• セキュリティ： GBRAIN_ALLOW_SHELL_JOBS=1 を設定すると、ワーカー上で任意のコマンドを実行できるようになります。共有キューでは、リモートコード実行の攻撃対象領域になります。特権インフラストラクチャの認可として扱ってください。
• 実行モード — どちらかを選択してください：
  • Postgres + デーモン： gbrain jobs work は、キューからジョブを受け取り実行する永続ワーカーを起動します。
  • PGLite + --follow： gbrain jobs submit ... --follow はインラインで実行します。排他的ファイルロックのため、PGLite ではデーモンモードを使用できません。docs/guides/minions-shell-jobs.md を参照してください。
• MCP の境界： シェルジョブの送信は CLI 専用です。MCP 経由で submit_job name="shell" を実行すると、コードが permission_denied の OperationError が発生します。汎用のリモート送信で受け付けられるのは sync、import、lint、lint-fix のみです。エージェントは get_job／list_jobs／get_job_progress でシェルジョブを監視できます（保護されていません）が、送信はできません。オペレーターまたはオートパイロットが送信し、エージェントが監視します。
• セットアップを確認する： 設定後、gbrain jobs stats（CLI）を実行し、ワーカーが登録されてキューを処理していることを確認してください。

送信（CLI、オペレーターまたはオートパイロット）

シェルジョブでは、コマンドを --params に JSON オブジェクトとして指定します。cmd（文字列）または argv（配列）に加えて、cwd と任意の env を指定します。

コマンド文字列形式：

gbrain jobs submit shell --params '{"cmd":"echo hello","cwd":"/abs/path"}'

Argv 形式（シェルによる展開なし）：

gbrain jobs submit shell --params '{"argv":["bash","-lc","echo hello"],"cwd":"/abs/path"}'

PGLite またはその他の単発デプロイでのインライン実行：

gbrain jobs submit shell --params '{"cmd":"echo hello","cwd":"/tmp"}' --follow

gbrain jobs submit --help で表示されるキュー／ライフサイクルのフラグ：--queue、--priority、--delay、--max-attempts、--max-stalled、--backoff-type、--backoff-delay、--backoff-jitter、--timeout-ms、--idempotency-key、--dry-run。

監視（エージェントまたはオペレーター）

次の操作は MCP から呼び出し可能で、エージェントが安全に使用できます。

list_jobs --name shell --status active
get_job ID
get_job_progress ID

get_job で、構造化された結果フィールド（終了コード、stdout／stderr の末尾、試行回数、タイミング）を確認します。ワーカー／キューの健全性ダッシュボード（キューの停止を示すシグナルを含む）には、get_job_stats（MCP）または gbrain jobs stats（CLI）を使用してください。

制御（MCP から呼び出し可能）

cancel_job id=ID
replay_job id=ID

保護されているのはシェルジョブの送信のみで、replay_job は保護されていません。エージェントは CLI にアクセスできなくても、シェルジョブをキャンセルまたは再実行できます。

定期的に実行するシェルワークロードには、重複実行を避けるために冪等性キーを使用してください。

サブエージェントジョブ（LLM オーケストレーション）

自由度の高い推論、ツールを使用した調査、ファンアウトによる統合に使用します。

ユーザー向けのエントリーポイント： gbrain agent run <prompt> は、サブエージェントの作業を送信する標準的な方法です。権限の引き上げに関する処理を担います。subagent と subagent_aggregator は保護されたジョブ名です。リモートエージェントは、設定済みのソース、ツール、スラッグのバインディングを使用する専用の submit_agent 操作を利用します。汎用の submit_job では、これらのジョブ名を受け付けません。

フェーズ 1：送信

gbrain agent run "Research Acme Corp revenue" --tools "search,query"

--tools には、BRAIN_TOOL_ALLOWLIST（src/core/minions/tools/brain-allowlist.tsを参照）の項目からカンマ区切りで指定したサブセットを指定できます：query、search、get_page、 list_pages、get_backlinks、traverse_graph、list_link_sources、 resolve_slugs、get_ingest_log、put_page、add_timeline_entry、 get_recent_salience、find_anomalies。添付ファイル用ツールとローカル専用の操作は利用できません。削除されたツールを参照するジョブを再送信する前に、古いバインディングを更新してください。 リモートのバインディングは空であってはなりません。ローカルのツールリストを明示的に空にすると、ツールは一切付与されません。

ファンアウトマニフェストを使って並列作業を行う場合：

gbrain agent run --fanout-manifest companies.json

マニフェストにはN個の子と1個のアグリゲーターが記述されています。各子は内部でname="subagent"として実行され、アグリゲーターはname="subagent_aggregator"として実行され、すべての子が終了した後に処理を開始します。 src/core/minions/handlers/subagent.tsおよび src/core/minions/handlers/subagent-aggregator.tsを参照してください。

フラグ（src/commands/agent.tsより）：

• --subagent-def <name> — 名前付きサブエージェント定義
• --model <id> — モデルを上書き
• --max-turns <N> — LLMのループ回数の上限
• --tools <csv> — 許可リストに登録された脳ツール（上記を参照）
• --timeout-ms <N> — ジョブごとのハードタイムアウト
• --fanout-manifest <file> — N個の子と1個のアグリゲーター
• --follow / --no-follow — ログをストリーミングして待機（TTYではデフォルトで有効）
• --detach — 送信後、すぐに戻る

キュー／優先度／再試行の調整機能はgbrain agent runでは公開されていません。これらの設定が必要な場合は、gbrain jobs submitを使ってsubagentハンドラーを直接送信してください（CLIの信頼設定が必要です）。

受付制御（v0.46.11.0）。 親のない同一のsubagent送信（同じオーナーレーン、ペイロード、実行オプション）は、既存の待機中ジョブに統合されます。gbrain agent runは一致したジョブIDとともにcoalescedを出力し、submit_agent MCPレスポンスにはcoalesced: trueが含まれます。これを成功として扱い、一致したIDを監視してください。再送信してはなりません。TTL（subagentのデフォルトは48時間。minions.ttl_waiting_hours.<name>）を過ぎても待機中のジョブは、waiting_ttl_expiredのプレフィックスが付いた理由でキャンセルされます。オペレーターが待機数の上限（minions.quota_max_waiting.<name>）を設定している場合、上限を超える送信は、構造化された再試行可能なrate_limitedエラーを返します。再試行の前にバックオフし、gbrain jobs statsでDIVERGENT QUEUEの行を確認してください。

フェーズ 2：監視

list_jobs --status active          # MCP — what's running?
get_job ID                         # MCP — full details + logs + tokens
get_job_progress ID                # MCP — structured progress snapshot
gbrain jobs stats                  # CLI — queue health dashboard
gbrain agent logs ID --follow      # CLI — streaming transcript + heartbeat

進捗には、ステップ数、合計ステップ数、メッセージ、トークン使用量、最後に呼び出されたツールが含まれます。

フェーズ 3：指示

実行中のエージェントの動作を変更するには、メッセージを送信します：

send_job_message id=ID payload={"directive":"focus on revenue, skip headcount"}

エージェントハンドラーは各反復時に受信トレイのメッセージを読み取り、コンテキストとして挿入します。メッセージは確認されます（既読通知が記録されます）。

メッセージを送信できるのは、親ジョブまたは管理者だけです（送信者の検証）。

フェーズ 4：ライフサイクル

pause_job id=ID                    # freeze without losing state
resume_job id=ID                   # pick up where it left off
cancel_job id=ID                   # hard stop
replay_job id=ID                   # re-run with same or modified params
replay_job id=ID data_overrides={"depth":"deep"}  # replay with changes

すべてのライフサイクル操作はMCPから呼び出せます。

フェーズ 5：結果の確認

get_job ID                         # result, token counts, transcript

トークンの計上：すべてのジョブでtokens_input、tokens_output、tokens_cache_readが追跡されます。子のトークン数は、完了時に自動的に親へ集計されます。

Durable execution（2 分を超える操作）

バックグラウンドシェルは、セッションのコンパクション、ハーネスの再起動、ツールのタイムアウトによって、何の通知もなく終了します。長時間かかる gbrain の操作（extract all、embed --stale、全件の sync --all）は、日常的に 10〜60 分実行され、これらの制限時間をすべて超えます。処理が継続できた場合でも、完了イベントが取りこぼされることがあり（ワーカーの再起動、通知の消失など）、完了した結果が報告されないまま、ユーザーは何も起きていないように感じます。Durable execution はその両方をカバーします。処理が継続し、結果が確実に報告されます。

約 2 分を超えると予想される操作は、デプロイ環境が対応する最も高い段階を経由させてください。これはエージェントが従うハーネスのルーティング規約であり、機械的な保証ではありません。このスキルが禁止しない限り、通常のバックグラウンドシェルを止めるものはありません。

有料の処理は、送信前に同意を得てください。 ジョブはターミナルなしで実行されるため、有料コマンド（embed --stale や、モデルプロバイダーを呼び出すその他のコマンド）は、ユーザーの承認をすでに得ていない場合、終了コード 3 と同意のペイロードを返して停止します。まず会話の中で承認を得てください。コマンドのプレビュー（例：gbrain embed --stale --dry-run）を実行して見積もりを伝え、ユーザーの同意を得てから、その承認を送信するコマンドに含めます（ユーザーが承認した上限額を指定した gbrain embed --stale --yes --max-usd <cap>）。または、ユーザーが gbrain config set consent.preapprove.paid.max_usd_per_run <usd> で設定した継続的な承認を利用します。ユーザーの返答なしに --yes を追加してはいけません。ジョブが終了コード 3 または confirmation_required コードで終了した場合は、そのメッセージをユーザーに伝えて停止してください。--yes を付けて再送信してはいけません。

段階 1 — Minion ジョブ + デッドマン（Postgres + ワーカー）

必要条件：Postgres エンジン、稼働中の gbrain jobs work ワーカー、そしてシェルレーンを使う場合は --allow-shell-jobs（またはワーカー上でエクスポートされた GBRAIN_ALLOW_SHELL_JOBS=1）を指定して起動したワーカー。上記の前提条件もすべて適用されます。フラグのデフォルトは OFF であり、シェルの送信は MCP の信頼境界をまたぐため CLI 専用です。また、PGLite にはワーカーデーモンがありません（段階 3 を参照）。このセクションの内容によって、その条件が緩和されることはありません。

1. ジョブとして送信し、再起動後も処理が継続するようにします。

   gbrain jobs submit shell \
     --timeout-ms 3600000 \
     --params '{"cmd":"gbrain extract all","cwd":"/abs/path","inherit":["database_url"]}'
   

   LLM の判断を必要とする処理は、代わりにサブエージェントレーン（上記の gbrain agent run）を使用します。送信したエージェントジョブの状態を確認しないのは、監視されていないシェルジョブと同じ不具合です。

2. 同じアクションブロック内でデッドマンを設定します（以下のパターンを参照）。デッドマンを設定せずに送信するのは、典型的な片手落ちの修正です。ジョブは継続しても、無通知の問題は解消されません。

段階 2 — cron で確認する進捗ファイル（エージェントを起動するスケジューラーなし）

エージェントを起動できるスケジューラーがないものの、ホストに通常の crontab がある場合（または処理がキューの外で実行される場合）：処理が進むにつれて進捗／ハートビートファイルに書き込むようにします（キュー内のジョブでは get_job_progress を利用できます）。そのうえで、ファイルの更新状況を想定される進捗間隔と比較する、定期的なホスト cron のチェックを登録します。エージェントも次のターンの開始時に確認します。チェックポイントの更新が止まっている場合は「実行中」ではなく、停滞中を意味します。更新状況の比較こそが、この段階の要です。

段階 3 — フォアグラウンド実行 + 出力のバッファリング（PGLite／ワーカーなし／スケジューラーなし）

操作をフォアグラウンドでインライン実行します。PGLite では gbrain jobs submit ... --follow を使うか、コマンドをそのまま実行し、出力をすべてファイルにバッファリングして、skills/conventions/exec-output.md に従って範囲を限定したスライスを読み取ります。長時間のコマンドの後にツールの結果が空でも、それはシェルの停止ではなく、出力の切り詰めです。この段階には無通知での終了を防ぐ仕組みがないため、操作をフォアグラウンドで実行し、最後まで対応してください。ここでバックグラウンド実行にすると、この段階の梯子が防ごうとしているまさにその障害が再発します。

デッドマンパターン

予想完了時刻に余裕時間を加えた時点で起動し、単なるプロセスの終了ではなく、結果が報告済みかを確認する、1回限りの自己削除型スケジュールチェックです。ジョブの送信と同じアクションブロック内で（送信後ではなく、「覚えていたら」でもなく）設定してください。

1. expected_minutes は正直に見積もり、切り上げます。
2. 期限 = 現在時刻 + 見積もり + 余裕時間。ここで margin = max(10 min, 50% of estimate) です。再起動によって配信が遅れます。短すぎると誤検知し、数時間遅れでは意味がありません。
3. ホストで利用できる任意の1回限りのスケジューラーを使ってチェックを作成します。実行後に削除される仕組みのハーネス用 cron ツール、at、または最初の起動時にチェック自身が削除する crontab エントリを使えます。チェックの指示：
   • 結果がすでにユーザーに報告されているか確認します。gbrain jobs get <id> でジョブの状態を確認し、報告済みかどうかのチェックでは、完了メッセージが実際にユーザーへ届いたかを確認します。
   • 報告済み → 何もせず、通知もせず、自己削除します。
   • 完了しているが未報告（イベントが取りこぼされた）→ gbrain jobs get <id> で結果を取得し、ジョブ ID を付けて復旧レポートをただちに投稿します。
   • まだ実行中 → 新しい ETA を記載した1行のステータスを投稿し、元の見積もりの +50% の時点に、フォローアップ用デッドマンを1つ設定します。フォローアップは最大1回です。無限に連鎖させてはいけません。
   • 停止／失敗 → 停止前に出力した内容（gbrain jobs get <id> の stderr_tail）を報告し、gbrain jobs retry <id> を提案します。
4. 通常完了時に解除します。 完了を受け取って報告したら、デッドマンを削除します。それでも起動した場合は、報告済みかどうかのチェックによって何もせず終了します。二重の備えです。

このパターンで対処すべき障害モード（Contract と Anti-Patterns にも反映）：デッドマン自体が起動前に停止するケース（次のターンの期限超過スイープを最後の備えとする二段構えの保険）、二重起動（冪等な報告済みチェックとジョブ ID 付きレポートで対処）、古いチェックポイント（「まだ実行中」と判断する前に鮮度を確認）。

パターンとともに読み込まれる評価コントラクトでは、デッドマンの導入を次の基準で評価します。

• ARMED_ON_SPAWN — 長時間ジョブの送信と同じアクションブロック内で作成されていますか？
• SELF_DELETING — 1回限りで、問題がなければ通知しませんか？
• DETECTS_SWALLOWED — ジョブの終了だけでなく、結果が報告済みかを確認していますか？
• RECOVERS — イベントが取りこぼされた場合、出力を取得して復旧レポートを投稿しますか？
• RIGHT_DEADLINE — 適切な余裕時間を加えた予想完了時刻になっており、誤検知も数時間の遅れもありませんか？

重大な不合格条件：ユーザー向けの長時間処理にデッドマンが設定されていないこと、完了が通常どおり届いたのにデッドマンが不要な通知を投稿すること、スケジューラーのエントリの代わりに sleep やポーリングループでタイマーを模倣すること（プロセスがスリープ中にセッションが終了すると、そのプロセスも停止します。まさに防ぐべき障害です）。

順序制御とロック

メンテナンス操作はロック（sync、embed、extract、integrity）を共有します。順番に連鎖させて実行してください。ジョブ1を送信してデッドマンを設定し、完了したらジョブ2を送信して次のデッドマンを設定します。最後に gbrain doctor を実行し、健全性の変化を報告します。ジョブが処理中に停止した場合、ロックは TTL で期限切れになります（有効で最近更新されたロック保持者はスティール猶予によって保護されます）。キューを「詰まり解消」するためにロック行を手動で削除してはいけません。

代表的な長時間処理

所要時間はコーパスのサイズによって変わります。これらは --timeout-ms の桁数を見積もるための目安であり、保証値ではありません。

操作	典型的な所要時間	推奨 --timeout-ms
extract all	大規模な brain で30～60分	3600000
embed --stale	5～30分（不足件数に応じて変動）	1800000
sync --all	5～20分	1200000
integrity auto	10～30分	1800000
dream	5～15分	900000

付録：コンテンツアドレス方式のステージチェックポイント

中間処理のコストが高い複数ステージのパイプライン（extract → score → explain → render → verify。score ステージでは実際に LLM の利用料が発生します）では、各ステージをコンテンツアドレス方式のチェックポイントにすることで、クラッシュ、deadman による再試行、または replay_job の際に、再度費用をかけるのではなく再開できるようにします。

• 各ステージのキーは、そのステージ固有のロジック、パラメーター、上流のアーティファクトのハッシュに基づいて生成します。アーティファクトは、コンテンツハッシュをアドレスとして、パイプラインの作業ツリーにある .cache/ ディレクトリに保存します。
• ウォーム実行では何も行われません。すべてのキーが一致すれば、再計算は発生せず、パイプライン全体を 1 秒未満で再生できます。
• 無効化は正しく連鎖します。パラメーターの変更やロジックの編集によってステージのキーが変わり、そのステージと、上流のハッシュが変化したすべての下流ステージが再計算されます。ステージ自身のソースもキーに含めてください。含めないと、ロジックを編集しても古いアーティファクトが気づかれないまま再利用されます。
• 来歴を記録します。実行ごとの来歴ファイルに各ステージのキー、入力、出力、計算日時を記録することで、すべてのアーティファクトの生成元となった正確なロジックとデータをたどれるようにし、「どのステージが、なぜ再計算されたのか」という問いにいつでも答えられるようにします。
• 復元時に整合性を検証します。実際のアーティファクトと記録済みのチェックサムを照合します。不一致があれば再計算するか、キャッシュから復元します。黙って再利用してはいけません。

評価項目：IDEMPOTENT（ウォーム実行では何も再計算されない）、CORRECT_BUSTING（変更によって影響を受けるステージだけが再計算される）、PROVENANCE（すべてのアーティファクトの来歴として、ロジック、パラメーター、上流の情報がたどれる）、INTEGRITY（破損したアーティファクトが検出され、黙って再利用されない）。

これはラダーに取って代わるのではなく、ラダーと組み合わせて使います。ラダーはパイプラインの実行と状況報告を継続し、ステージチェックポイントは再試行のコストを抑えます。1 つのステージでわずかでも LLM の利用料が発生する場合は、両者を組み合わせてください。

出力形式

ジョブのステータスをユーザーに報告する場合：

Job #ID (name) — status
Progress: step/total — last action
Tokens: input_count in / output_count out (+ cache_read cached)
Runtime: Xs
Children: N pending, M completed

完了を報告する場合：

Job #ID completed in Xs
Tokens used: input / output / cache_read
Result: <summary>

バッチのステータス（親ジョブと子ジョブ）を報告する場合：

Parent #ID — waiting-children
  #A subagent(Acme) — active, 3/5 steps, 2.5k tokens
  #B subagent(Beta) — completed, 1.8k tokens
  #C subagent(Gamma) — paused
Total tokens so far: 4.3k

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、通知ブロックについては、エージェントオペレータープロトコルに従ってください。このスキル固有の事項は次のとおりです。

• 保護されたジョブに対する gbrain jobs submit の MCP 経由の実行が permission_denied を返す場合、brain ホスト上の信頼されたローカル CLI から実行する必要があります。ユーザーにその旨を伝えてください。
• シェルジョブが error_text に示されたフラグ（シェルジョブが無効）とともに即座にデッドレターになった場合は、ホストオペレーターが設定すべき環境変数フラグをユーザーに伝えてください。再試行してはいけません。
• 送信上限に達して rate_limited が返された場合は、指定された時間だけ待ってから再送信してください。それまで追加の送信を並行して行ってはいけません。
• ワーカーがいない状態でジョブが waiting のままの場合は、再送信する前にワーカーが登録されていることを確認してください（gbrain jobs get <id>）。

抗パターン

• 単一の検索クエリのために Minion を起動しないでください（検索ツールを直接使用してください）
• 結果を確認せずに、ジョブを投げっぱなしにしないでください
• 先に gbrain jobs stats を確認せずに、5 個を超えるエージェントを同時に起動しないでください
• 送信結果が coalesced の場合は再送信しないでください。作業はすでにキューに入っています。代わりに、対応するジョブ ID を監視してください
• サブエージェントの作業では、Minions が利用可能な場合に runtime: "subagent" を指定して sessions_spawn を使わないでください（代わりに gbrain agent run を使用してください）
• get_job を短い間隔で繰り返しポーリングしないでください（軽量な確認には get_job_progress を使用してください）
• 約 2 分を超えると予想される操作を、バックグラウンドシェルでそのまま実行しないでください。セッション終了時に停止します。Durable execution ladder を経由してください
• デッドマンや実際に実行されるスケジュール済みチェックを設定せずに、「完了したら報告します」と言わないでください
• 完了が正常に届いた場合にデッドマンが不要な通知を投稿しないようにしてください。報告済み状態を確認し、通知せず、自身を削除してください
• sleep やポーリングループでデッドマンのタイマーを模倣しないでください。スリープ中のプロセスはセッション終了時に停止します。まさにその失敗を防ぐための仕組みです
• チェックポイントや進捗ファイルは、鮮度を確認せずに信用しないでください。古いチェックポイントは、いつまでも「実行中」と示すことがあります
• ロックを取得するメンテナンス操作（sync、embed、extract、integrity）を同時に実行しないでください。また、ロックを解除するためにロック行を手動で削除しないでください（ロックは TTL で期限切れになります）

使用するツール

• バックグラウンドジョブを送信 — submit_job（MCP：docs/guides/authorization-upgrade.md の契約に基づく sync、import、lint、lint-fix のみ。シェルジョブではローカル CLI を、リモートサブエージェントでは submit_agent を使用）
• ジョブの詳細を取得 — get_job（MCP）
• フィルターを指定してジョブを一覧表示 — list_jobs（MCP）
• ジョブをキャンセル — cancel_job（MCP）
• ジョブを一時停止 — pause_job（MCP）
• 一時停止したジョブを再開 — resume_job（MCP）
• 完了／失敗したジョブを再実行 — replay_job（MCP）
• サイドチャネルメッセージを送信 — send_job_message（MCP）
• 構造化された進捗を取得 — get_job_progress（MCP）
• キューの統計情報 — get_job_stats（MCP。HTTP 経由では管理者スコープが必要です。このセクションの他のジョブ操作と同様です。停止状態のキューを示すサイレントハルトシグナルを含みます）、または gbrain jobs stats（CLI）