herdr-pair

Herdr ペア

1 つの Herdr タブで Claude と Codex をペアにします。タスク、作業の受け入れサイクル、コンテキストの圧縮をまたいで、ペアとその sid を維持します。ユーザーはどちらのペインも読み、途中で発言できます。プロトコルヘッダーと識別子はそのまま保持します。

前提条件

SKILL_DIR にこのスキルのディレクトリを設定し、 PAIR_SCRIPT="$SKILL_DIR/scripts/herdr-pair.mjs" を設定します。必ずこの絶対パスを使用してください。プロジェクトの cwd はインストール済みスキルのパスとは関係ありません。

エージェント自動化コマンド（herdr agent start、 herdr agent prompt）、jq、trash が PATH にあり、 HERDR_ENV=1 が設定されていることを確認します。いずれかが不足している場合は停止し、Herdr のインストール、起動、または更新をユーザーに伝えてください。

Herdr を変更する前に、呼び出し元ペインの証明を読み、実行してください。明示されたタスクのリポジトリを解決し、プロセスの祖先をたどって呼び出し元が一意であることを証明します。祖先がちょうど 1 つのペインに一致しない場合は、会話マーカーにフォールバックします。--tab-id を含む PAIR_PROOF と固定された PAIR_ID が返されます。この証明が厳密に完了しない場合は停止してください。

ガードレール

1. すべてのペイン操作は、トランスクリプトで証明された workspace_id、 tab_id、pane_id、エージェント種別、ターミナル ID、リポジトリの範囲内に限定します。ワークスペース、フォーカス、ラベル、cwd、方向、セッションメタデータ、ペイン番号だけを頼りに検出したペインには決してアクセスしないでください。
2. パートナーとの通信には herdr-pair.mjs send だけを使用します。通常のアシスタント出力は、ヘッダーを含まないユーザーへの引き継ぎにのみ使用します。SendMessage、サブエージェントへのメッセージ送信、ペインへの直接書き込みは、それぞれ別の通信経路です。
3. ファイルスコープごとに、書き込み権限を持つエージェントを 1 つだけ割り当てます。担当者、対象ファイル、禁止する変更、検証方法、停止地点を指定します。引き継ぎがあるまで、パートナーはそのスコープを読み取り専用で扱います。
4. ユーザーが送信したメッセージは、パートナーとのやり取りより優先されます。競合があれば、次の返信で明らかにしてください。パートナーの起動に 1 回失敗したら、その試行を終了します。
5. 作業ステップの合間にはプロンプトに戻り、ペインを長時間のフォアグラウンドループ（スリープとポーリングを繰り返す受信処理、フォアグラウンドでの CI 監視など）に置き続けないでください。ペインが恒常的に処理中だと、パートナーからの受信が滞ります。長時間実行する監視処理はバックグラウンドのターミナルで実行し、このペインはいつでもプロンプトを受け取れる状態にしてください。
6. 意図的にチェックアウトを不整合な状態にするたびに、その旨を通知します。変更を伴うテスト、二分探索、意図的なリバートの前には、対象パスと停止条件を指定した task を送信し、ツリーを復元して検証した後に ready を送信してください。accepted を待つ必要はありません。通知が保護になります。進行中の変更を知ったパートナーは、終了通知が届くまで、そのチェックアウトでのテスト結果を使用不可として扱い、報告せずに質問します。通知できない実験や数分を超える実験は、別のワークツリーで行ってください。

プロトコル

メッセージは次の形式で始まります。

[agent <from> -> <to> kind=<kind> sid=<sid>]
[herdr-pair control seq=<n>: ...]

<body>

ヘルパーが制御行を挿入します。この行には、そのメッセージに対する正確な実行可能な receive コマンドと、送信者を通じて返信するルールが含まれています。モデルのコンテキストが圧縮されたとき、この行が復旧の基点になります。

次の種類を使用します。

• task：作業の分担と書き込み権限を提案または更新します。作業途中で停止する場合は、STOP — <理由> で始めます。
• review：ファイルパスと変更内容の簡潔な要約を添えて、レビューを依頼します。
• question：作業を進める前に確認を求めます。
• ready：変更したファイル、検証結果、残存リスクを報告します。
• accepted：パートナーの ready を受け入れ、作業サイクルを進めます。
• blocked：続行に必要なユーザーの判断を明示します。
• stalemate：同じ意見の相違が 2 回繰り返され、進展がないことを報告します。
• handoff：通常のローカル出力で、制御をユーザーに戻します。

開始または再開

1. 次を実行します。 node "$PAIR_SCRIPT" discover "${PAIR_ID[@]}"。 相手のエージェントが存在しない場合は、次を一度だけ実行します。 node "$PAIR_SCRIPT" spawn "${PAIR_ID[@]}"。 候補が複数ある場合、または起動に失敗した場合は停止します。
2. node "$PAIR_SCRIPT" init "${PAIR_ID[@]}" を実行します。 タブ単位の新しいセッションを作成するか、 既存の正確なライブセッションを冪等に再開します。 正確な sid を PAIR_SID として記録します。すべての送信は この値に紐付けられるため、同じ種類の別のペインが他のタブのセッションを 借用することはできません。
3. 最初の task をヘルパー経由で送信します。パートナーは対等です。 スコープの分割案を提示してください。スコープごとに書き込みリースを1つ割り当て、 各パートナーがそれぞれのスコープを実装し、相手の ready をレビューする形にします。 独立して作業するのに十分なコンテキストを含め、パートナーが実装を始める前に 承諾するか、別案を提示するようにしてください。独立したスコープのないタスクでは、 リースを1つ割り当てます。リースの保持者が作業を進め、パートナーがレビューします。 リースはタスクごとに交代します。

完了条件は、対象のタブに検証済みのセッションが1つあり、最初のタスクの 受領記録があることです。スキルの再読み込みやコンパクションの際も、必ずそのセッションを再開します。

送信

本文のみを一時ファイルに書き込み、次を実行します。

BODY=$(mktemp); trap 'trash "$BODY"' EXIT
# Write the partner message body to "$BODY".
node "$PAIR_SCRIPT" send "${PAIR_ID[@]}" --sid "$PAIR_SID" \
  --kind "$KIND" --body-file "$BODY"

送信側は、作業中のパートナーに短い猶予を与えた後、いずれにしても送信します。 Herdr 0.8.0 での測定では、Claude はターンの途中でのプロンプトを一括で受け付けますが、 Codex への複数行プロンプトには、引き続き Enter が必要です。パートナーが作業中の場合、 ヘルパーはヘッダー、制御行、本文を含む agent prompt を1回だけ送信し、 その後、安全のため Enter のループを実行します。表示上の到着確認と 全体の再送は行いません。この状態には信頼できる入力欄の信号がなく、 再送するとキューに入った本文が重複する可能性があるためです。 session.json 内の正確なシーケンスを証明できるのは receive だけです。 その ACK がなければ、受領記録には配信が証明されていないと記載されます。

パートナーがアイドル状態の場合、ヘルパーは入力欄を使って到着を確認します。 貼り付けが届かなかった場合と、すでに送信済みの場合は見た目が同じなので、 まず入力欄の変化を確認する必要があります。その後、入力欄からテキストが消えるまで Enter を送信し、完全な再送を1回行います。それでも配信を証明できない場合は、 明確に失敗を報告します。どちらの経路でも、シーケンス ACK によって 送信直後の中断からすぐに復旧できます。

• receipt=acknowledged：パートナーがこのメッセージに対して receive を実行しました。
• receipt=pending-partner-may-be-busy-do-not-retry：メッセージは届いており、 パートナーは作業中です。キューには入っていますが、まだ ACK はありません。再送しないでください。 後で node "$PAIR_SCRIPT" reconcile を実行します。状態が進むのは ACK の後だけです。
• receipt=unproven-working-inspect-that-pane-then-reconcile：パートナーは作業中で、 プロンプトを1回と Enter による保護を受け取りましたが、期限までに ACK を返しませんでした。 ヘルパーには、プロンプトがキューに入ったのか、通知なく破棄されたのかを判別できません。 予約が保留中の間は再送しないでください。エージェントの処理が落ち着いてから確認し、 reconcile を実行するか、配信されていないことを確認してから再試行できるよう保留を解除してください。
• receipt=lost-partner-idle-inspect-that-pane-then-reconcile：パートナーはアイドル状態で、 ACK がありません。メッセージは届いていません。そのペインを読み、メッセージがないことを確認してから、 以下の手順で保留中の配信を解除してください。よくある原因は本文が長すぎることです。 長い本文は、ファイルパスを示す短いメッセージとして送信してください。
• 予約後にゼロ以外の終了コードが返された場合は、転送エラーです。ACK によって reconcile できるよう、 保留中の予約は残ります。確認せずに、配信済みと主張したり、予約を解除したりしないでください。

確認により、保留中のメッセージがパートナーに届いていないと証明できた場合は、 明示的なユーザーの承認を得て、その配信だけを解除します。

node "$PAIR_SCRIPT" reconcile "${PAIR_ID[@]}" --sid "<sid>" \
  --clear-pending true

圧縮後の受信と復旧

受信した [agent ...] トラフィックについて：

1. [herdr-pair control ...] にある正確なコマンドを実行します。このコマンドは --sid、--from、--seq を指定して receive を呼び出し、現在のタブとのバインドを検証して、受信確認を永続化します。
2. メッセージを処理し、返信本文を一時ファイルに書き込んでから、node "$PAIR_SCRIPT" send ... を実行します。

receive がシーケンスを記録し、返信に受信確認が記録されたら完了です。失敗した場合は、ヘッダーのないトランスポートレポートをユーザーに提示します。圧縮後は、コントロール行と検証済みセッションからペイン ID、sid、タスクのステータス、終了状態を再構築します。

作業サイクルと永続化

有用な成果物を生み出している間は作業を続けます。新しいコード、テスト結果、決定、または選択肢の絞り込みがない状態が 5 ターン連続した場合は、handoff が必要です。実質的な進展があればカウントをリセットします。事実に関する意見の不一致は、膠着状態になる前に、直接的な証拠または焦点を絞ったテストを 1 つ用いて解決します。同じ判断を 2 回繰り返しても進展がなければ、stalemate を送信します。

accepted ステータスが 2 つ揃うと、1 回の作業サイクルが完了します。開始者はユーザーにローカルで引き継ぎを行い、結果、検証の証拠、未解決の問題、および引き続きアクティブなペアの各ペイン、ワークツリー、またはウォッチャーをすべて明記します。両方のエージェントは待機状態になれます。次のタスクは同じペアと sid を再開します。セッションはアクティブなままです。

blocked と stalemate の場合も、セッションを削除せずに引き継ぎます。検証済みのアクティブなペアで作業サイクルのカウンターとステータスをクリアする場合に限り、node "$PAIR_SCRIPT" reset "${PAIR_ID[@]}" を使用します。ID と配信履歴は保持されます。

ユーザーがペアの終了を明示的に求めた場合に限り、セッションを終了して破棄します。

node "$PAIR_SCRIPT" end "${PAIR_ID[@]}" --sid "<sid>"

スクリプトは sid、ワークスペース、タブ、参加者を独自に検証し、配信が保留中の場合は処理を拒否します（ACK を待つか、確認済みのクリア手順を使用してください）。古いペイン ID やパートナーの不在により再開できない場合は、不一致を説明し、明示的なユーザーの承認を得た場合に限り end "${PAIR_ID[@]}" --sid "<sid>" --stale true を使用します。古い状態を終了して保留中の状態を破棄できるのは、パートナーのペインがなくなっている場合、その記録済みバインドが古くなっている場合、またはフォアグラウンドのエージェントプロセス／リポジトリが一致しなくなっている場合だけです。Herdr タブを閉じると、ペインは通常どおり終了します。古い状態が別のタブに引き継がれることはありません。

ワークベンチタブ

長時間稼働する共有プロセスのために別のタブが必要な場合に限り、references/workbench-tab.md を読みます。

非推奨

このスキルは凍結されています。後継は同じリポジトリ内の pair スキルです。このスキルは Herdr バックエンドをバイト単位でそのまま維持し、Herdr の外でペアリングするためのヘッドレスバックエンドを追加しています。新しい作業では pair をインストールしてください。既存のインストールが引き続き動作するよう、herdr-pair はここに残されています。