制御と介入

ワークフローを投入したあとは、pause、unpause、kill、recover で、実行の一時停止、一時停止の解除、強制停止、復旧ができます。cdg task view を使うと、タスクのエージェントセッションに入れます。それぞれの操作がどんな場面に向いているか、セッションに入ったあとどうやり取りするかは、介入と制御を参照してください。最後の 2 つの節は、ごく一部の場面でしか使いません。復旧が進まないときに使う 2 つの確認用オプションと、占有されているブランチ名を解放する cdg branch release を扱います。

制御コマンドの構文と適用できる状態

一時停止、一時停止の解除、強制停止、復旧の 4 つのコマンドには、どれもワークフローレベルとタスクレベルの 2 つの書き方があります。ワークフローレベルのコマンドは、ワークフロー内のすべてのタスクに同じ操作を実行します。タスクレベルのコマンドは、指定したタスクだけを処理します。どのコマンドも、特定の状態にあるタスクだけを変更し、それ以外のタスクはそのままにします。

<タスク> には、1 つまたは複数のタスク ID か、タスクセレクターを書きます。ワークフローやタスクを省略したときに何が対象になるかは、範囲の指定と一括制御を参照してください。ワークフローレベルのコマンドには、ワークフロー以外の引数はありません。cdg task kill と cdg task recover には、異常な状況に対処するためのオプションがそれぞれ 1 つあります。復旧が進まないときに使うオプションを参照してください。

制御コマンドが作用するのは、投入済みでまだキューにあるワークフロー、つまり submitted フェーズのワークフローだけです。まだ投入されていないワークフローと、レビューが終了してキューを離れたワークフローに対しては、制御コマンドは実行されません。レビューが終了したワークフローをもう一度実行させたい場合は、レビュー記録をクリアしてから投入します。レビュー記録のクリアと再投入を参照してください。キューにあるワークフローの中でも、実行が終わってレビューを待っている done のタスクと、すでに個別にレビューされたタスクは、これらのコマンドの影響を受けません。done のタスクは、レビューコマンドで処理します。

分離ブランチモードでは、実行が始まったタスクは、レビューされるまで自分のワークスペースと同時実行枠 1 つを占有し続けます。一時停止や強制停止をしても、これらは解放されません。コマンドは、こうしたタスクを処理したあと、占有が続いていることを 1 行で出力します。ほかの独立したタスクを先に実行させたい場合は、このタスクを最後まで実行させてからレビューするか、cdg task review cancel または defer でタスクを終わらせます。

タスクやワークフローが保留または強制停止になっている場合

• killed のタスクは unpause を受け付けない： こうしたタスクはそのまま変わりません。コマンドは Not unpaused と出力し、代わりに cdg task recover を使うよう案内して、終了コード 1 で終了します。複数のタスクを一度に処理した場合、こうしたタスクは結果の一覧に killed (not unpaused, use recover) と表示されます。
• 開始前の準備で止まったタスク： タスクが開始前の準備で止まって on-hold になった場合や、そのあとさらに kill された場合は、原因に対処してから cdg task recover を実行します。CodeDAG は準備をやり直し、新しいエージェントセッションを起動します。もう実行しない場合は、cdg task review cancel または defer でそのまま終わらせます。エージェントは起動したものの、フルアクセスの警告やログインの案内といった起動画面で止まっているところを強制停止されたタスクも、同じ方法で起動し直せます。
• セッションが動いたままの保留タスクを一時停止した場合： Codex のタスクがエージェントセッションの問題で on-hold で止まっていて、セッションはまだ動いている場合、pause を実行するとタスクは paused で止まり、保留の理由はそのまま残ります。一時停止している間は、セッションの中で何が起きても、タスクは paused のままです。unpause を実行すると、タスクは元の保留の状態に戻ります。保留を解除するには、この場合も cdg task recover が必要です。
• ワークフローそのものが保留になっている場合： ワークフローレベルの保留は、cdg dag recover で解除します。理由は、cdg dag status に表示されるワークフローの Reason: 行で確認できます。たとえば、CodeDAG クレジットが足りない、またはログインが必要なために開始できない場合は、startup-gate-blocked です。理由が startup-gate-blocked の場合、この保留が解除されるまで、cdg task recover と 2 つの unpause コマンドはどれも実行を拒否します。原因に対処してから cdg dag recover を実行すると、ワークフローはもう一度開始を試みます。クレジットが二重に差し引かれることはありません。保留の理由ごとの対処手順は、タスクまたはワークフローが on-hold で止まっているを参照してください。

範囲の指定と一括制御

ワークフローレベルの制御コマンドは、一度に複数のワークフローを処理できます。タスクレベルの制御コマンドは、同じワークフローの 1 つまたは複数のタスクを一度に処理します。対象を省略した場合は、どちらもキューの先頭のワークフローに作用します。

ワークフローレベルのコマンドの [ワークフロー...] は省略できます。1 つまたは複数のワークフローを、スペースで区切って書くこともできます。書き方はワークフローを指定するを参照してください。指定するワークフローは、キューにあるものならどれでもかまいません。まだキューで待っていて、開始されていないワークフローも指定できます。こうしたワークフローに対しては、pause と kill の効果は同じです。そのワークフローのタスクがすべて paused になり、順番が来ても開始されず、キューの先頭で止まり続けます。後ろに並んだワークフローも、このワークフローを復旧するか、レビューコマンドで終わらせるまで、一緒に待つことになります。

指定したワークフローの中に、見つからないもの、投入されていないもの、状態を変更できないものがあっても、残りのワークフローには影響しません。コマンドは、こうしたワークフローごとにエラーを 1 件出力し、残りを通常どおり処理して、最後に終了コード 1 で終了します。成功時のサマリーには、成功した数と対象の総数が示されます。たとえば Paused successfully for 1 of 2 workflows: で、一覧表示されるのは成功したワークフローだけです。すべて成功した場合は Paused successfully for all 2 workflows: となり、終了コードは 0 です。unpause と kill のサマリーも同じ形式です。

タスクレベルのコマンドが一度に処理するのは、1 つのワークフローのタスクだけです。このワークフローは -w で指定し、省略した場合はキューの先頭のワークフローになります。タスクそのものにはデフォルト値がなく、必ず書かなければなりません。1 つまたは複数のタスク ID を書くか、タスクセレクターを使って、依存関係をもとにタスクのまとまりを選びます。この 4 つのコマンドでは、どのセレクターにも複数のタスク ID を指定でき、結果はその和集合になります。具体的な書き方は、1 つまたは複数のタスクを指定するとタスクセレクターを参照してください。

セレクターは依存関係だけをもとにタスクを選び、タスクが現在どの状態にあるかは見ません。選ばれたタスクは、それぞれ自分の状態に応じて処理されます。コマンドを適用できるタスクは変更され、適用できないタスクはそのまま残ります。適用できないタスクが含まれていても、処理が中止されることはありません。復旧に関する 2 つのオプションには、別の制限があります。--acknowledge-unconfirmed は一度に 1 つのタスクにしか使えず、--force-owner-release は特定の理由で止まっているタスクだけを処理します。復旧が進まないときに使うオプションを参照してください。

以下の例では、ワークフロー feature がキューの先頭にあり、タスク 2 とタスク 3 はタスク 1 に、タスク 4 はタスク 2 とタスク 3 に、タスク 5 はタスク 4 に依存します。ワークフロー docs はその後ろに並んでいて、まだ開始されていません。

cdg task view

cdg task view は、現在のターミナルをタスクエージェントのネイティブセッションに接続します。セッションは、タスクから特定することも、セッション ID から直接特定することもできます。セッションに入ったあとのプロンプトの送り方と抜け方は、セッションに入る、修正する、抜けるを参照してください。

構文とセッションの特定

cdg task view <タスク ID> [-w <ワークフロー>] [--session-id <セッション ID>] [--recover]
cdg task view --session-id <セッション ID>

コマンドがどのセッションに入るかは、タスクの状況によって決まります。タスクが実行中の場合や、止まったあともセッションが開いたままの場合、コマンドはその動いているセッションに接続します。タスクが完了済み、またはレビューが終了していて、セッションも終了している場合は、エージェント自身の再開機能を使って、タスクの元の作業ディレクトリでそのセッションを開き直します。それまでの会話はすべて残っています。タスクがまだキューにあるのに、セッションがもう動いていない場合は、先にタスクを復旧しないとセッションに入れません。ルールは、後述の「前提条件」を参照してください。

終了したセッションを開き直すには、セッション ID が必要です。CodeDAG は通常、セッション ID を自動的に記録します。記録できなかった場合、コマンドは --session-id を付けるよう案内します。Codex のタスクでは、セッション ID を自動で抽出できなかったという警告も、ログに 1 件出ます。セッション ID は、エージェント自身の記録から確認できます。たとえば、Codex が終了時に出力する codex resume <セッション ID> という案内です。

# タスク 3 のセッション ID が記録されていない場合に、自分で指定する
cdg task view 3 -w feature --session-id <セッション ID>

セッション ID しかわからず、どのワークフローのものかわからない場合は、タスク ID と -w を省略できます。

cdg task view --session-id <セッション ID>

この場合、CodeDAG は、キューにあるワークフローとレビュー済みのワークフローから、このセッションを使っているタスクを探します。見つかったのがキューを離れたタスクであれば、そのタスクの元の作業ディレクトリでセッションを開きます。キューにあるアクティブなタスクであれば、タスク ID を指定した場合と同じルールで処理し、復旧が必要なときは同じように先に尋ねます。複数見つかった場合、コマンドはタスク ID と -w を付けるよう求めます。1 つも見つからなかった場合は、現在のディレクトリで、このセッション ID のセッションをそのまま開きます。

前提条件

cdg task view には、実際の対話型ターミナルが必要です。このコマンドは、キー入力をそのままエージェントのネイティブ画面に渡します。そのため、スクリプト、CI、エージェントのシェルツールのような、対話型ターミナルのない環境では正常に使えません。その場合に代わりに使える方法は、監視と修正の方法を選ぶを参照してください。

タスクの実行がすでに始まっている必要があります。まだ開始されていないタスクにはセッションがないため、コマンドは Task has not started yet. と出力して終了します。セッションには入らず、--session-id を付けるよう求めることもありません。上流を待っているタスク、開始前の準備で止まったタスク、一度も開始されないまま一時停止または強制停止されたタスクは、どれもこれに当たります。

タスクが止まっていて、そのエージェントセッションも動いていない場合、セッションに入るには、先にタスクを復旧する必要があります。復旧するとタスクは実行を続けるため、コマンドは先に一度尋ねます。対象になるのは、killed、paused、保留（on-hold）のタスクと、working または draining と表示されたままで、ワーカープロセスがすでに終了しているタスクです。コマンドはまずこの点を説明し、続いて、デフォルトが No の確認を表示します。

Task 3 is killed and its Agent session is not running.
Entering the session requires recovering the task, which resumes its execution.
To read what the task has done without resuming it, run 'cdg task logs 3 -w feature'.
? Recover the task and enter its session? › No / Yes

Yes を選ぶと、コマンドは cdg task recover と同じルールでタスクを復旧し、復旧後のセッションの準備ができてから接続します。No を選ぶと、コマンドは Operation cancelled. と出力して終了し、タスクもキューもそのまま変わりません。対話型ターミナルがない場合、コマンドはこの質問を表示せず、エラーを出して終了コード 1 で終了します。この場合に復旧するには、--recover を付けます。

先に cdg task recover を実行していて、タスクが on-hold (agent-recovery-queued) と表示されている場合は、復旧がすでに順番待ちになっています。コマンドは尋ねることなく、復旧後のセッションの準備ができてからセッションに入ります。

保留（on-hold）のタスクのうち、次の 2 種類は、復旧しなくてもセッションに入れます。1 つは、セッションがまだ動いているタスクで、コマンドはそのまま接続します。セッションに入っても、保留は解除されません。タスクが止まる原因になった問題をセッションの中で解決したあと、cdg task recover を実行して初めて、タスクは続行されます。もう 1 つは、merge-conflict で止まっているタスクです。コマンドがそのマージコンフリクトのセッションを開き直すので、そこで手作業で解決できます。タスクの状態は変わりません。

復旧が進まないときに使うオプション

--acknowledge-unconfirmed と --force-owner-release は、どちらも確認のためのオプションで、タスクがそれぞれに対応する保留の理由で止まっているときにだけ使います。どちらの場合も、CodeDAG は、タスクの前回の実行が完全に終わったかどうかを確認できません。同じタスクが二重に実行されたり、出どころのわからない変更が残ったりしないように、オプションなしの recover はタスクを on-hold のままにします。状況を確かめたうえで、オプションを付けて明示的に確認してください。

--acknowledge-unconfirmed

cdg task recover <タスク ID> -w <ワークフロー> --acknowledge-unconfirmed

このオプションは Codex のタスク専用で、最終的にどうなったかを確かめようのないサブエージェントを通すために使います。CodeDAG は、タスクが起動したすべてのサブエージェントが終了したことを確認して初めて、タスクが完了したと判定します。あるサブエージェントが、CodeDAG の読み取れるセッション記録を残していない場合、そのサブエージェントが終了したかどうかも、何をしたかも確認できないため、タスクは保留になります。オプションなしの recover が通すのは、記録を確認できるサブエージェントだけで、このサブエージェントは通しません。

この状況になると、cdg task status <タスク ID> -w <ワークフロー> の Diagnostic: にそのサブエージェントが表示され、state=unconfirmed と示されます。オプションなしで cdg task recover を実行しても、タスクは on-hold で止まったままで、コマンドは、状況を確かめてからこのオプションを使うよう案内します。

確認する前に、このサブエージェントの前回の実行が何を残したかを確かめます。

• タスクのワークスペースに、想定外の変更がないこと。ワークスペースで git status と git diff を実行して確認できます。
• まだ動いているサブエージェントがなく、サブエージェントが起動してまだ動いているコマンドもないこと。cdg task view でタスクのセッションに入り、Codex の現在の画面を見て確認できます。

確認すると、CodeDAG は、表示されていたサブエージェントを終了したものとして扱い、タスクが完了したかどうかを判定し直します。メインセッションの作業がすでに終わっていれば、タスクは通常の流れで完了し、そのあと自動承認されるか、レビューを待ちます。まだ終わっていなければ、タスクは実行を続けます。この確認が対象にするのは、その時点で表示されていたサブエージェントだけです。そのあとで、確認できないサブエージェントがまた現れた場合、タスクは再び保留になります。

このオプションで復旧できるタスクは、1 つのコマンドにつき 1 つだけです。複数のタスクが選ばれている場合、コマンドはエラーになります。cdg dag recover には、このオプションはありません。

--force-owner-release

cdg task kill <タスク ID> -w <ワークフロー> --force-owner-release
cdg task recover <タスク ID> -w <ワークフロー>

このオプションが必要になるのは、タスクが agent-worker-liveness-unknown で止まっているときだけです。理由は、cdg task status <タスク ID> -w <ワークフロー> の Reason: 行で確認できます。この理由は、CodeDAG が記録しているワーカープロセスのプロセス ID でまだプロセスが動いているものの、それが当初このタスクを実行していたプロセスだとは確認できないことを表します。1 つのタスクで 2 つのエージェントが同時に作業することを避けるため、この場合、recover は新しい実行を開始せず、タスクは on-hold で止まったままになります。

使う前に、元のタスクが本当に実行を続けていないことを確認します。

• cdg task view <タスク ID> -w <ワークフロー> で元のセッションに接続しようとすると、コマンドが Cannot reach the existing session of task … というエラーを出すこと。接続できる場合は、セッションがまだ動いているので、解放しないでください。
• cdg task logs <タスク ID> -w <ワークフロー> -f でしばらく様子を見ても、ログに新しい出力がないこと。
• タスクのワークスペースにあるファイルが変化しなくなっていること。時間をおいてもう一度 git status を実行し、比べて確認できます。

実行すると、タスクは killed になります。CodeDAG は元のプロセスにシグナルを一切送らず、新しい実行も開始しません。そのプロセスの確認を待つのをやめるだけです。コマンドは、元のプロセスがまだ動いている可能性があることを知らせます。続いて cdg task recover を実行すると、CodeDAG は新しいプロセスで元のエージェントセッションを再開し、タスクは実行を続けます。

このオプションを付けた cdg task kill は、この理由で止まっているタスクだけを処理します。同じコマンドで選ばれたほかのタスクは、強制停止されません。

cdg branch release

cdg branch release <ブランチ名...>

cdg branch release は、CodeDAG の同期リポジトリが占有しているブランチ名を解放します。clone をレプリカにしているプロジェクトでは、同期リポジトリ（リモート codedag-mirror）を介して、ワークスペースの間でブランチを共有します。そこに残っているブランチが、あるタスクの branchName と同じ名前の場合、ワークフローはその名前を使えず、実行がそのタスクまで進んだところで、タスクは on-hold（branch-name-conflict）で止まります。

解放の際、コマンドは同期リポジトリからそのブランチを削除し、続いて、登録済みの各ワークスペースにある、そのブランチへのリモート追跡参照を削除します。各ワークスペースにある同じ名前のローカルブランチは解放の対象外で、自分で削除するか名前を変更する必要があります。コマンドは、ローカルブランチが残っているワークスペースを 1 つずつ表示します。キューもタスクの状態も変更されません。

ブランチ名は、スペースで区切って一度に複数指定できます。重複した名前は 1 回だけ処理されます。コマンドは、プロジェクト内の登録済みのいずれかのワークスペースで実行します。指定したブランチは、先にまとめてチェックされ、1 つでも解放できないものがあれば、どれも解放されません。次のいずれかに当てはまるブランチは、解放されません。

• まだ使われているブランチ： キューにあるワークフローの統合ブランチ、またはキューにあるタスクがすでにチェックアウトしているタスクブランチ。そのワークフローのレビューが終了して、キューを離れるまで待つ必要があります。
• スナップショットブランチ： レビューで保存されたスナップショットブランチ。そのワークフローがまだキューにあるかどうかは問いません。その時点のコードを保存しているため、解放すると取り出せなくなります。
• タスクの結果を保持している唯一の参照： 同期リポジトリの中で、あるタスクの結果のコミットにたどり着けるのがこのブランチだけになっている場合。コマンドのメッセージでは、merge source と呼ばれます。タスクの結果は通常、CodeDAG 自身の参照によって保持されているため、この条件に当てはまるのは、その参照が失われている場合だけです。

同じ名前のブランチのために止まったタスクは、「まだ使われている」には当たりません。解放は、まさにそのタスクに名前を空けるための操作です。解放に成功した場合と、同期リポジトリにもともとそのブランチがない場合、終了コードは 0 です。そのため、同じコマンドを繰り返し実行できます。上の拒否条件に当てはまる場合、ブランチ名が不正な場合、コマンドを初期化済みのプロジェクトの外で実行した場合は、終了コードが 1 になり、どの参照も変更されません。

解放のあと、コマンドは、このブランチ名のために止まっていたタスクについて、cdg task recover の案内を表示します。そのとおりに実行すると、タスクはこのブランチで起動し直されます。いずれかのワークスペースに同じ名前のローカルブランチが残っている場合、コマンドはこの案内を表示しません。先に、ローカルブランチを削除するか、名前を変更してください。

関連ページ

• 介入と制御：一時停止、強制停止、復旧がそれぞれどんな場面に向いているか、セッションに入ったあとで方向を修正し、抜ける方法。
• レビュー：実行が終わったタスクとワークフローに結論を出す方法と、レビューの前に実行中のタスクを止める方法。
• トラブルシューティング：タスクまたはワークフローが on-hold で止まったときに、理由に応じて対処してから復旧する方法。