stuck-crewmate-recovery

行き詰まったクルーメイトの復旧

セッション開始時のダイジェストで、通常の直接レポートのエンドポイントが停止している、またはメタデータにウィンドウがないと報告された場合や、直接レポートが古い状態になっている、ループしている、何度も混乱している、ブリーフにすでに答えがある質問をしている、応答しない、あるいは指示が反映されなかった場合に、このプレイブックを使用してください。 プルリクエストがすでにマージされたワーカーについて、レポートが古い、またはエンドポイントが停止している場合は、復旧の対象ではありません。作業は完了しているため、このプレイブックではなく、通常のティアダウン（firstmate では AGENTS.md のセクション 7、supervision ブランチでは bin/fm-branch-prompt.sh のマージ済み作業ルール）でタスクを終了してください。--force は使用しないでください。

ボードをホストするワーカーを復旧する場合は、docs/configuration.md に記載されたクルーがホストする Lavish ボードの契約に従ってください。

ワーカーへの割り込み、停止、再起動には bin/fm-control.sh <task-id> interrupt|exit|relaunch を使用してください。このコマンドは記録されたランタイムを自身で特定し、各操作を検証し、ティアダウンや破棄は決して行いません（docs/agent-control.md）。 この制御プレーンの対象は、このホームで実行中のワーカーです。別の場所に配置された secondmate は名前を指定して拒否され、代わりに secondmate-provisioning を使って調整されます。 再開コマンドやハーネス固有のスキル呼び出しを行う前、およびアダプター固有の挙動が関係する場合は、harness-adapters を読み込んでください。 対象ウィンドウのハーネスは state/<id>.meta の harness= に記録されています。

管理された承認フェイルオーバー

バイパス中に Codex のコマンド承認プロンプトが表示された場合、またはバイパスセッションで Claude のポリシー拒否が発生した場合は、ワーカーの権限設定を所有ホームで変更してワーカーを再起動することについて、キャプテンに明示的な承認を求めてください。 明示的な承認を得た後に限り、harness-adapters を読み込み、FM_HOME=<owning-home> bin/fm-approval-failover.sh apply <id> を使用してください。このスクリプトのヘッダーに、永続的な設定と保護された復旧の手順が記載されています。自動検出は行いません。 保存されたモデルレビュー済みの対処法と実際の復旧結果を報告し、明示的な設定と作業を維持してください。ベンダーのポリシーを変更したり、承認プロンプトやフックの信頼確認プロンプトに回答したりしてはいけません。 backend=t3code のワーカーは、すでに T3 の full-access ランタイムモードで実行されているため、このコマンドは変更を加える前に処理を拒否します。保留中のリクエストは T3 Code 自体で承認するか（T3 の保留中リクエストの手順）、作業を別のバックエンドに移してください。

応答不能になった通常の直接レポートのセッション開始時の整合性確認

この手順は、通常の kind=ship および kind=scout の直接レポートを対象とします。 kind=secondmate の復旧には、代わりに secondmate-provisioning を読み込んでください。

リモートの secondmate の場合、fm-crew-state と fm-peek は fm-on.sh 経由で実際のリモートエンドポイントを読み取ります。また、fm-send は、確認待ちの steer が配信済みであれば配信済みとして報告します（契約の詳細は各コマンドのヘッダーを参照してください）。unknown-remote の読み取り結果や到達不能なホストのエラーは、リモートの状態を読み取れなかったことを意味するだけであり、相手が停止していることや送信に失敗したことを示すものではありません。 本当に応答不能になったリモートの相手を復旧する場合は、必ず bin/fm-spawn.sh <id> --secondmate を使用してください。raw herdr のペインを閉じたり強制終了したりする操作は行わないでください。エンドポイントのバインドが失われます。

ダイジェストのエンドポイント結果は、存在のシグナルとして扱い、タスクの作業や検証実行が失われた証拠とはみなさないでください。 再起動を決める前に、bin/fm-crew-state.sh <id> で対象の現在の状態を読み取ってください。 crew のブランチと現在のコードに一致する、ミスのない実行があれば、エンドポイントが停止していても、その実行を引き続き正とします。終了済みまたは一時停止中の実行は通常のライフサイクルに沿って処理し、実行中のものは重複ワーカーを作成せず、そのまま監督を続けてください。

タスクに対応する正とみなせる実行がない場合は、記録されたバックエンドとワークツリーの一覧だけを調べてください。 treehouse がバックエンドの tmux、herdr、zellij、cmux、Paseo、Rex、t3code、または tern のタスクでは treehouse status を使用し、Orca のタスクでは記録された orca_worktree_id= と terminal= を使用してください。 ほかのホームのエンドポイントを網羅的に調べたり、一致するウィンドウラベルから所有者を推測したりしないでください。

再起動する前に、記録されたタスクを所有する稼働中のエージェントがいないことと、既存のワークツリーを引き続き利用できることを確認してください。 コミットされていない変更とコミットを維持し、同じタスク ID を使用して、同じブリーフに簡潔な進捗メモを添え、既存のワークツリー内で記録済みのハーネスを再開または再起動してください。 HERDR エンドポイントが単にアイドル状態なのではなく、Herdr の churn によってペインまたはワークスペースが削除されて消失した場合は、同じ再起動で復旧できます。既存のワークツリー内に新しいエンドポイントが1つ作成され、タスクの記録がそのエンドポイントに再バインドされます。特別な対応は不要で、ワークツリーにも変更はありません（docs/agent-control.md「エンドポイントが消失したタスクの再取得」）。 この再起動では、再バインドの前にエンドポイントが削除済みであることを確認します。そのため、停止しただけの Herdr サーバーは複製されず、再び採用されます。 tmux では再取得できません。タスクの記録にはエンドポイントのソケット ID がなく、そのため missing ウィンドウが、この席からアクセスできない tmux サーバー上にあるものと区別できません。どちらの場合も exit と relaunch は拒否されます。 T3 Code では代替の再起動はできません。スレッドには会話が保持されるため、ターンまたはプロバイダーを変更すれば同じエージェントを継続できます。タスクの記録とワークツリーを維持し、再起動を試みるのではなく、docs/t3code-backend.md に従ってください。 再起動によってこれらの拒否を回避しようとしないでください。記録されたタスクを維持し、バックエンドの復旧契約に従ってください。 この再取得操作を実行できるのは、そのタスクを所有するホームだけです。例外は secondmate のみで、上記のとおり bin/fm-spawn.sh <id> --secondmate で復旧してください。 記録されたワークツリーの状況が確認できていない間は、新しい汎用 spawn を使用しないでください。別のワークツリーを割り当てると、1つのタスクが2つのコピーに分かれるおそれがあります。 ワークツリーまたは所有者の整合性を安全に確認できない場合は、すべての状態を変更せずに維持し、矛盾する証拠とともにタスクが失敗またはブロックされたことを報告してください。

パイプラインが停止したと言い張る、稼働中のクルーメイト

これは、前述のデッドエンドポイントのケースとは逆です。ワーカーは稼働しており、停止したと判断したパイプラインも、通常は稼働しています。 drive 呼び出しは次のゲートまたは結果が出るまでブロックされるため、ハーネスが1つのコマンドを実行させる時間をはるかに超えることがあります。一方、デーモンは応答をすぐに受け付け、バックグラウンドでラウンドを実行します。 そのため、タイムアウト、強制終了、またはエラーになったクルーメイトの drive 呼び出しは、応答を受け取れなかった読み取り処理で待機したままになります。そこから「デーモンが落ちている」と結論づけても、それは証拠ではなく推測です。

その主張を信じる前に、次の2つの信頼できる情報源を自分で確認してください。

1. ソケットについては no-mistakes daemon status。
2. 実行については no-mistakes axi status --run <id>。または bin/fm-crew-state.sh <id>。こちらはすでにこの矛盾を考慮し、ソケットに関するものではないデーモンまたはタイムアウトの blocked: 行が、直近のアクティビティを伴う実行中または修正中の実行と食い違う場合、その実行は稼働中であり、その行は古い情報だと報告します。

daemon status で接続拒否またはソケットの欠落が確認された場合、それはデーモン停止の確かな証拠です。永続化された実行記録に「実行中」または「修正中」と記されていても、必ずエスカレーションしてください。その記録は、デーモン終了後に古い情報になっている可能性があります。 それ以外の場合、実行が最近のアクティビティを伴って「実行中」または「修正中」であれば、その主張は誤りです。クルーメイト自身のワークツリーから no-mistakes axi run で再接続するよう案内してください。実行の HEAD が一致する限り安全で、冪等です。また、タイムアウトはデーモンの停止を意味しないと伝えてください。 この場合、キャプテンには何も連絡しません。

クルーメイトの主張を理由に、共有デーモンを再起動、停止、更新してはいけません。 共有デーモンは1つのインスタンスで、すべてのレーンとホームにサービスを提供しているため、再起動するとほかのレーンで進行中の実行が停止します。デーモン停止の判定に該当するのは、ソケット接続の拒否またはソケットの欠落が確認された場合だけです。その判定、またはデーモンエラーを示す失敗した実行記録を、キャプテンにエスカレーションしてください。

ライブエンドポイントのエスカレーション

次の順にエスカレーションします。

1. ペインを確認し、タスクの指示受信トレイ（state/<id>.inbox/）で未処理の *.msg レコードを確認します。未読の先任者の指示を示す古い起床通知がある場合、ワーカーは永続化された指示を確認していません。レコード自体に、意図された内容がそのまま示されています。 ワーカーの現在の状態が paused: と宣言された待機である場合、ワーカーは何を待っているかを示しただけです。そのため、たとえば自身のバックグラウンドジョブの終了レコードやプロセスなど、示された条件を確認します。その条件がすでに解消されている場合は、待機状態を正常として報告させるのではなく、結果を読んで再開するよう指示します。
2. クルーメイトが、すでにブリーフに回答がある質問を待っている場合は、T3 ランタイムリクエストに対する T3 の保留中リクエストの手順に従います。 ペインバックエンドでは、アクティブな先任者のセッションから FM_HOME=<this-firstmate-home> bin/fm-send.sh を使って、1 行で回答します。ただし、FM_HOME がすでにアクティブな先任者のホームに設定されている場合を除きます。
3. クルーメイトが混乱している、または同じことを繰り返している場合は、FM_HOME=<this-firstmate-home> bin/fm-control.sh <task-id> interrupt で割り込み、その後 fm-send を使って修正内容を 1 行で伝えます。
4. 方向を修正してもクルーメイトが本当に行き詰まり、バックエンドが置き換えに対応している場合は、FM_HOME=<this-firstmate-home> bin/fm-control.sh <task-id> relaunch --note '<progress so far>' で再起動します。これによりエージェントが停止し、ブリーフとそのメモが同じローカルコピー内の置き換え先に引き継がれます。置き換え先を起動できない場合は、以前のレコードが復元されます。 T3 Code では再起動せず、タスクを維持し、現在のサーバー状態とともに停止中のスレッドを報告して、オペレーターによる対応を待ちます。 ワーカーを別のランタイムで再開する場合は、同じコマンドに --harness、--model、または --effort を渡します。 本当に行き詰まっているとは、同じことを繰り返す、応答しない、同じ障害を繰り返す、または完全に停止している状態を指します。 コンテキストの読み取り値が低いだけでは、行き詰まっているとはいえません。最新のハーネスは自動的にコンパクションを行い、処理を続けます。 ワークツリーとコミットは保持されるため、再起動にかかるコストは低いです。
5. 2 回目の再起動も失敗した場合は、バックログに failed と記録し、AGENTS.md のセクション 9 に従って、失敗の内容、保持された作業、その影響を簡潔にキャプテンへ伝えます。対応にパスが必要な場合を除き、メタデータ、ハーネス、ウィンドウ、ワークツリーには触れないでください。