corral-launch-agents

Corral 启动 Agent

通过 Corral 真正的 launch 流程启动 Agent。让 Corral 创建分支、工作树、Herdr 工作区、窗格、Agent 进程、元数据和持久化任务记录。不要用原始 Git 或 Herdr 命令重新执行这一流程。

解析请求

操作前，区分以下目标：

• 指定仓库： 使用 --repo 传入其检出路径。Corral 会解析主检出，并创建一个全新的工作树。
• 指定新工作树位置： 还要传入 --worktree-path。目标位置用于创建新的 Corral 检出；它不是现有的 Herdr 工作区 ID。
• 现有的 Corral/Herdr Agent 或可恢复的 CLI 会话： 不要再启动另一个 Corral 任务。改用 herdr 和相关的运行框架技能。
• 现有的外部工作树： 只有在用户要求接管时，才使用 Corral 接管功能。启动操作始终会创建新任务和工作树。

启动会改变状态。只有用户要求启动时才执行；检查、说明或试运行请求并未授权启动。

重新打开现有的 Cursor CLI 会话

Corral 的启动助手不适用于恢复会话。加载 herdr 和 cursor-cli 技能，然后：

1. 确认指定的 Herdr 会话、主仓库检出、原始关联工作树以及准确的 Cursor 聊天 ID。
2. 只选择非空聊天。使用 meta.json 中的 updatedAtMs 或对话记录更新时间，而不是目录修改时间。区分父聊天和审查子 Agent。
3. 先检查正在运行的窗格。绝不要在两个窗格中同时恢复同一个聊天 ID；应复用现有窗格。 如果聊天在错误创建的顶层工作区中打开，请确认其处于空闲状态且没有未发送的草稿，只关闭该工作区，绝不要删除工作树。
4. 使用仓库元数据重新打开现有关联工作树：

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

这会打开现有路径；不会创建 Git 工作树或 Corral 任务。这是 Corral 兼容的必需布局：它会将工作树归到相应仓库之下，同时保留工作树名称。如果结果显示 already_open: true，请复用该关联工作区。不要使用 workspace create；它缺少 Git 工作树元数据，并会创建顶层空间。不要在主工作区下使用 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>

要启动多个 Agent，请使用带有 JSON 任务文件的 batch。Corral 本身允许启动许多进程，但准备流程最多同时运行三个任务。批量启动前，请阅读references/batch-launches.md。

验证每次启动

此 helper 会在 Corral 创建 worktree 且 Herdr 检测到交互式 Agent 后才返回。请验证持久化状态和实时状态：

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

报告 Corral 任务 ID、标题、优先级、预设、worktree 路径、窗格 ID、持久化的启动状态，以及 Herdr Agent 的实时状态。如果启动在创建 worktree 后失败，请保留失败的任务和 worktree 以供诊断；不要自动清理。

安全规则

• 未获得用户明确同意，绝不传递 --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。
• 在从文件启动多个 Agent 之前，请阅读 references/batch-launches.md。

如需查看 helper 选项，请运行：

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