corral-launch-agents

Corral でエージェントを起動する

Corral の実際の launch パイプラインを通じてエージェントを起動します。Corral にブランチ、ワークツリー、Herdr ワークスペース、ペイン、エージェントプロセス、メタデータ、永続化されたタスクレコードを作成させてください。この一連の処理を、Git や Herdr のコマンドを直接使って再現しないでください。

リクエストの対象を特定する

実行する前に、次の対象を区別します。

• 特定のリポジトリ： --repo でチェックアウトのパスを渡します。Corral がプライマリチェックアウトを特定し、新しいワークツリーを作成します。
• 特定の新しいワークツリーの場所： --worktree-path も渡します。指定先は Corral が新しく作成するチェックアウトの場所であり、既存の Herdr ワークスペース ID ではありません。
• 既存の Corral／Herdr エージェント、または再開可能な CLI セッション： Corral のタスクを新たに起動しないでください。代わりに herdr と該当するハーネススキルを使用します。
• 既存の外部ワークツリー： ユーザーが取り込みを依頼した場合に限り、Corral による取り込みを使用します。起動すると、必ず新しいタスク／ワークツリーが作成されます。

起動は状態を変更する操作として扱います。ユーザーが起動を依頼した場合に限り実行してください。調査、説明、またはドライランの依頼は、起動の許可にはなりません。

既存の Cursor CLI セッションを再開する

Corral の起動ヘルパーは、セッションの再開には適していません。herdr と cursor-cli のスキルを読み込んでから、次の手順を実行します。

1. 指定された Herdr セッション、プライマリリポジトリのチェックアウト、元のリンク済みワークツリー、正確な Cursor チャット ID を特定します。
2. 空ではないチャットだけを選択します。ディレクトリの更新時刻ではなく、meta.json の updatedAtMs またはトランスクリプトの更新時刻を使用します。親チャットとレビュー用サブエージェントを区別します。
3. まず稼働中のペインを確認します。同じチャット ID を2つのペインで同時に再開しないでください。既存のペインを再利用します。 誤って作成されたトップレベルのワークスペースでチャットが開いている場合は、未送信の下書きがなく、アイドル状態であることを確認してから、そのワークスペースだけを閉じます。ワークツリーは削除しないでください。
4. リポジトリのメタデータを指定して、既存のリンク済みワークツリーを再度開きます。

herdr --session "$SESSION" worktree open \
  --cwd "$PRIMARY_CHECKOUT" \
  --path "$WORKTREE_PATH" \
  --label "$WORKTREE_NAME" \
  --no-focus

これにより既存のパスが開きます。Git ワークツリーや Corral タスクは作成されません。ワークツリー名を維持したまま、リポジトリの下にワークツリーをまとめられるため、これは Corral 互換のレイアウトとして必須です。結果が already_open: true の場合は、そのリンク済みワークスペースを再利用します。Git ワークツリーのメタデータがなく、トップレベルのスペースが作成される workspace create は使用しないでください。プライマリワークスペースの下で tab create を使用するのも避けてください。リンク済みワークツリーのエントリではなく、リポジトリ名が表示されます。

5. 結果から root_pane.pane_id を取得し、プロンプトを送信せずに正確なチャットを再開します。

herdr --session "$SESSION" pane run "$PANE_ID" \
  "cursor-agent --yolo --trust --resume $CHAT_ID"

6. ワークスペースの checkout_path、repo_root、共有の repo_key、is_linked_worktree: true を確認します。続いて、履歴を確認します。

herdr --session "$SESSION" workspace list
herdr --session "$SESSION" agent wait "$PANE_ID" --until idle --timeout 30000
herdr --session "$SESSION" pane read "$PANE_ID" \
  --source recent-unwrapped \
  --lines 200

ターミナルのタイトル、会話の末尾、foreground_cwd を確認します。再開時に復元されるのは会話履歴であり、以前のプロセス環境ではありません。

Corral による取り込みは別の操作であり、通常は必要ありません。外部の既存ワークツリーを永続化された Corral タスクに変えるよう、ユーザーが明示的に依頼した場合に限り使用します。Herdr のグループ化を復元したり、CLI チャットを再開したりするだけのために取り込まないでください。

ヘルパーを使用する

マシン上のパスをハードコーディングせずに、インストール済みのスキルディレクトリを特定します。

CORRAL_LAUNCH_SKILL_DIR="${AGENT_SKILLS_DIR:-$HOME/.agents/skills}/corral-launch-agents"
CORRAL_LAUNCH_HELPER="$CORRAL_LAUNCH_SKILL_DIR/scripts/corral_agents.py"

まず事前チェックを実行します。指定された Herdr セッションが分かっている場合は、必ず渡してください。

python3 "$CORRAL_LAUNCH_HELPER" doctor --session corral
python3 "$CORRAL_LAUNCH_HELPER" list-presets --session corral --agent pi

セッションが停止している場合は、そのことを明確に伝えます。Herdr セッションを黙って開始、停止、または削除しないでください。

何かを作成する前に、実際に起動する内容でドライランを実行します。

python3 "$CORRAL_LAUNCH_HELPER" launch \
  --session corral \
  --repo <repository-checkout> \
  --task "<task title>" \
  --preset pi \
  --priority 2 \
  --prompt "<task prompt>" \
  --no-focus \
  --dry-run

解決されたセッション、プリセット、リポジトリ、ワークツリーの保存先、ベース、優先度、ダーティチェックアウトのポリシー、プロンプトの長さを確認します。そのうえで、起動が許可されている場合に限り、--dry-run を付けずに再実行します。

新しいワークツリーのディレクトリを正確に指定するには、次を追加します。

--worktree-path <new-worktree-path>

複数のエージェントを起動するには、JSON タスクファイルを指定して batch を使用します。Corral 自体は多くのランチャープロセスを許可しますが、準備パイプラインの同時実行数は3件までです。バッチ起動の前に、references/batch-launches.md を読んでください。

起動のたびに確認する

ヘルパーは、Corral がワークツリーを作成し、Herdr が対話型エージェントを検出した後にのみ戻ります。永続化された状態と稼働中の状態を確認してください。

python3 "$CORRAL_LAUNCH_HELPER" status \
  --session corral \
  --task "<task title>" \
  --live

Corral のタスク ID、タイトル、優先度、プリセット、ワークツリーのパス、ペイン ID、永続化された起動ステータス、稼働中の Herdr エージェントのステータスを報告してください。ワークツリーの作成後に起動が失敗した場合は、診断のため失敗したタスクとワークツリーを保持し、自動的にクリーンアップしないでください。

安全規則

• ユーザーの明示的な承諾なしに --allow-dirty を渡さないでください。これはプライマリチェックアウトの未コミットの変更をコピーするものではなく、それらを含めずに処理を続行するだけです。
• Corral のスモークテスト以外では、--mock-state を使用しないでください。
• API キーをコマンド引数、プロンプト、出力、プリセットファイルに記載しないでください。プロバイダーの通常の認証情報ストアまたは環境変数を使用してください。
• 内容を確認するだけの目的で presets.toml を編集しないでください。将来の起動に影響するため、プリセットの追加や変更を行う前に確認してください。
• Corral のプリセットでは、Pi の --print、RPC モード、エクスポート、モデル一覧表示の各コマンドを使用しないでください。Corral と Herdr は、長時間稼働する対話型 TUI を想定しています。
• バッチによってユーザーがアクティブにしているペインのフォーカスを奪わないよう、自動化では --no-focus を優先してください。
• Corral の実行に使われているものと同じ Herdr バイナリ／セッションを使用してください。異なるバイナリやセッションを使うと、誤ったランタイムを対象にする可能性があります。

詳細なリファレンスを読む

• トラブルシューティング、プリセットの変更、生の Corral CLI の使用、または一般的でないランタイムパスの処理を行う前に、references/corral-design1.md を読んでください。アーキテクチャ、すべてのネイティブ起動オプション、プリセットのフィールド、環境変数、状態モデル、エラーについて説明しています。
• Pi のプロバイダー／モデル／思考／セッション／ツール／スキルのオプションを選択する前、または用途に特化した Pi プリセットを作成する前に、references/pi-agent.md を読んでください。
• ファイルから複数のエージェントを起動する前に、references/batch-launches.md を読んでください。

ヘルパーのオプションを確認するには、次を実行してください。

python3 "$CORRAL_LAUNCH_HELPER" --help
python3 "$CORRAL_LAUNCH_HELPER" launch --help