delivery-wait

配信待ち

ワークフローで GitHub の外部状態を待つ必要がある場合は、scripts/delivery_wait.py を実行してください。ハーネスはコマンドの終了を受動的に待機します。モデルのハートビートで待機をシミュレートしてはいけません。

待機の実行

ホストには、1つのコマンドを実行できる時間に制限があり、配信の状態遷移にはそれより長くかかる場合があります。次のルールに従い、状態遷移に必要な時間だけ待機を継続してください。

• ホストがコマンドをバックグラウンドで実行し、終了時にセッションを再開できる場合は、その方法で待機を実行してください。その後、ターンを終了するか、待機中の状態に依存しない作業だけを続けてください。その機能がない場合は、後述の代替手段を使用してください。ブロッキング待機でターンを開いたままにしてはいけません。
• 各実行の --deadline は、1つのコマンドに対するホストの制限時間内に設定し、呼び出し元が状態遷移を諦める時刻は別に保持してください。その時刻より前に timed-out が返された場合は、同じ --state を指定して待機を再実行してください。これは1回の待機を再開する操作であり、ハートビートではありません。
• ヘルパーを単独のコマンドとして実行し、後ろにパイプや別のコマンドを連結しないでください。ホストが報告する終了ステータスが、ヘルパー自体のものになるようにします。ホストの「コマンドが終了しました」という通知が示すのは、コマンドが終了したことだけです。何が起きたかは結果のエンベロープで確認してください。
• 状態ファイルごとに、実行中の待機は1つにしてください。たとえば setsid、nohup、& を使って、待機をホストから切り離してはいけません。切り離されたプロセスでは、セッションを再開できません。
• 待機中は、その待機が対象とする状態を調べないでください。結果に基づいて対応してください。

address-feedback CodeRabbit アダプターの run にも同じルールが適用されます。状態ファイルは保持しません。同じ引数で再実行すると、GitHub からヘッドの状態を読み直します。

長時間実行コマンドと委任されたレーン

コーディネーターとワーカーの両方で、長時間のビルド、テスト、その他のコマンドにも同じターン管理を適用してください。短い確認を超える見込みのコマンドは、ホストの追跡対象となるバックグラウンド実行で開始してください。引き継ぎには、タスクまたはセッション ID、出力先、正確なリビジョン、完了条件、再開時の操作を含めてください。起動の確認は未完了の作業であり、成功を示す証拠ではありません。短いコマンドや範囲を限定した診断チェックは、フォアグラウンドで実行できます。

コマンドが担当レーンのターンをまたいで実行され続け、完了時にそのレーンまたはコーディネーターを再開できることを確認してください。ワーカーが終了したときにフォアグラウンドのコマンドを停止するホストでは、実行を継続できる担当者がコマンドを開始してください。バックグラウンドコマンドと監視の期限を守ってください。監視から出力するのは、意味のある変化または最終結果だけにしてください。変化のない状態をストリーミングすると、ポーリングと同様にモデルが起動します。各状態遷移につき、担当者を1人、実行中の待機を1つにしてください。

コマンド、ワーカー、外部状態遷移だけが残っている場合は、保留状態を記録してターンを終了してください。実行中は独立した作業を続け、その後、依存する作業を再開する前に、返された終了ステータスと結果を確認してください。レーンを維持するために、フォアグラウンドで gh pr checks --watch やスリープループを実行したり、gh pr view を繰り返し実行したり、出力や状態を繰り返し読み取ったりしてはいけません。未完了の作業があるワーカーは、完了したと主張せず、ハンドルと次の状態遷移をコーディネーターに返してください。ポーリングのためだけに別のワーカーを作成してはいけません。

ホストが担当者に通知したり、担当者の処理を再開したりできない場合は、範囲を限定した状態確認を1回行い、その機能がないことと、明示的な次回確認時刻またはイベントを記録して、保留として返してください。指定がある場合は呼び出し元の間隔に従ってください。指定がない場合は、状態遷移の期限を設定したうえで、少なくとも5分後に確認してください。再開した各ターンでは1回だけ確認し、状態に変化がなければ再び待機に入ってください。これはあくまで代替手段です。機能している通知経路を、スケジュールされたポーリングに置き換えてはいけません。コマンドをターンをまたいで実行できない場合は、追跡されないプロセスを起動したり、確認を実行したと主張したりせず、必要な実行機能を呼び出し元に返してください。

入力

呼び出し元は、リポジトリ、想定される識別情報、絶対期限、および任意の状態パスを指定します。このコマンドは、保存済みの状態を最新の GitHub の状態と照合し、関連する変更がない間は待機して、1 つの結果を返して終了します。ワークフロースキルからは --json を使用してください。人間向けの出力は、ターミナルから直接使用するためのものです。スキルのデフォルトの状態ファイルは .agent/waits/ 以下に保存されるため、利用するリポジトリではこのディレクトリを gitignore に追加する必要があります。別のハーネスでは、--state を使って任意の非公開状態パスを指定できます。

呼び出し

wait <kind> --repo <owner/repo> --deadline <ISO 8601> [--interval <seconds>] [--state <path>] [--json] は待機を実行します。inspect <kind> には同じ識別フラグを指定しますが、--deadline、--interval、--state は指定しません。各 kind にはそれぞれ固有の識別フラグが必要です。

• checks-terminal：--pr <number>、--head <sha>、および --all-workflows、期待されるチェックコンテキストごとに 1 つの --check <name>、またはその両方が必要です。どちらも指定せずに実行すると、待機せずに運用上のエラーで終了します。
  • --all-workflows ではチェック名は不要です。指定された head と完全に一致するすべての GitHub Actions ワークフロー実行と、各実行の最新の試行に含まれるすべてのジョブを検索します。実行がない場合、またはいずれかの実行やジョブがキュー待ち、進行中、待機中、保留中、または要求済みの場合は待機します。いずれかの実行やジョブが失敗、キャンセル、タイムアウト、アクション要求、またはその他の成功以外の結論で終了すると、すぐに changed を報告します。すべての実行とジョブが成功、スキップ、または中立で終了し、1 インターバルを置いた連続 2 回の観測で同じ全体状況が確認された場合にのみ satisfied を報告します。後から追加されたマトリックスステージや needs ステージのジョブがある場合、その実行は進行中のままです。別の実行が終了した後に開始された実行は、2 回目の観測で検出されます。inspect では全体状況が安定していることを確認できないため、すべて成功したスナップショットに対して satisfied ではなく waiting を報告します。
  • --all-workflows の対象には、コミットステータスや CodeRabbit、Vercel など他のアプリによるチェック実行は含まれません。呼び出し元が必要とするものごとに --check を追加してください。その場合、待機ではそれらのコンテキストの成功も必要になります。
  • 名前を指定したチェックは、成功、スキップ、または中立で終了すると合格します。名前を指定したチェックのいずれかがそれ以外の結果で終了すると、残りがまだ実行中でも、待機はすぐに changed を報告します。同じ名前を持つチェック実行は、ソースごとに 1 つとして数えます。ソースはそのアプリであり、GitHub Actions の場合はワークフローとトリガーイベントも含まれます。そのため、push と pull_request の両方で実行されるワークフローでは、両方の実行が合格する必要があります。同じソースからは最新のチェック スイートのみが対象となるため、最初に開始された実行がどれであっても、再実行、新しい実行によってキャンセルされた実行、または編集後の再チェックが古い実行に置き換わります。コミットステータスは最新の状態が対象です。
  • --check のみを指定した場合、head に対して他のものが実行中であっても、名前を指定したコンテキストのみを判定します。リポジトリの必須ステータスチェックなど、期待されるセット全体が分かっている場合にのみ使用してください。待機時に表示されるチェックはそのセット全体ではありません。ワークフローではジョブが段階的に追加されるためです。
• pr-merged：--pr <number> と --head <sha> が必要です。プルリクエストがマージされずにクローズされた場合、changed を報告します。
• workflow-terminal：--run-id <id> と --head <sha> が必要です。プルリクエストにチェックが表示されない、ディスパッチされた実行などに使用します。
• tag-target：--tag <name> と --head <sha> が必要です。
• release-assets：--tag <name>、--head <sha>、および必須アセットごとに 1 つの --asset <name> が必要です。
• wake-at（wait のみ）：--deadline のみが必要です。状態ファイルは保持しないため、--state は効果がありません。

--checkpoint フラグはありません。状態のパスには --state を指定します。省略した場合、コマンドは kind と識別情報からデフォルトのパスを導出します。

inspect と wait はどちらも --rest-page-size <1..100> を受け付けます（デフォルト：100）。GitHub が大きな REST ページを返せない場合は、より小さい値を指定してください。この設定はワークフロー実行、ジョブ、およびチェックとステータスの REST フォールバックに適用されます。すべてのページが読み込まれ、完全なワークフロー全体状況の確認が引き続き必要です。このオプションは GraphQL クエリや保存済みの待機識別情報を変更しないため、既存の待機は異なる REST ページサイズで再開できます。

結果

--json は、state に結果を含む単一のエンベロープを出力します。待機していた事実が成立したことを示すのは satisfied だけです。changed は、チェックまたはワークフローが成功以外の終端結果に達したか、その他の関連する状態が変化したことを意味します。判断する前に内容を確認してください。invalidated は、想定していた head、ref、または保存済みの識別情報が一致しなくなったことを意味します。timed-out は期限が過ぎたこと、cancelled は待機が中断されたことを意味します。これらは終了コード 0 を返し、operational-error は終了コード 2 を返します。inspect は waiting を報告することもあります。

単一の信頼できる配信スナップショットには inspect を使い、状態の遷移を待つには wait を使います。対応する述語は、完全一致の head チェック、プルリクエストのマージ、ワークフローの完了、タグの対象、リリースアセット、絶対時刻での起動です。想定していた head または ref が変わると、待機は無効になり、暗黙に変更後の値を追跡することはありません。GitHub が引き続き信頼できる情報源です。チェックポイントには正規化された識別情報と観測結果が含まれ、認証情報、コメント本文の生データ、API ペイロードの生データは含まれません。

ヘルパーは認証済みの gh トランスポートを使用します。GraphQL を優先します。REST へのフォールバックは、GraphQL がレート制限されていて、REST でも同じ事実を確認できる場合、または GitHub がその事実を REST 経由でのみ公開している場合に限って使用されます。