orca-orchestrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orca orchestration runbook

Orca编排运行手册

Drive a supervised multi-agent run on Orca from the orchestrator cockpit. The orchestrator is the DAG driver: it dispatches only ready tasks, watches every worker settle with

worker_done

, unblocks dependents only after their parent's green PR is merged, and gates on failures. It never schedules workers itself — Orca does not infer placement or conflicts. The agents choose placement; the orchestrator decides what runs when.

Re-orient first if you are in a fresh session (

/orca-resume

). Confirm the worktree guardrail first: you must be in the primary worktree (see

/orca-setup

) — never coordinate from a task branch.

从编排器控制台在Orca上驱动受监督的多Agent运行。编排器是 DAG驱动程序：它仅分发就绪任务，监控每个工作者通过

worker_done

完成任务，仅在父任务的绿色PR合并后才解除子任务的阻塞，并拦截失败任务。它从不自行调度工作者——Orca不会推断部署位置或冲突。由Agent选择部署位置；编排器决定什么任务在何时运行。

如果是新会话，请先重新定位（

/orca-resume

）。首先确认工作树防护：你必须处于主工作树（查看

/orca-setup

）——绝不要从任务分支进行协调。

Two entry paths

两种入口路径

Planned run (recommended):
```
/orca-plan
```
→
```
/orca-tasks
```
produced a Run and its Tasks. You bind that Run and drive it.
Quick path: a small 1-2 task job that skipped planning.
```
run-create
```
+
```
task-create
```
directly from the objective, then drive identically.

规划运行（推荐）：
```
/orca-plan
```
→
```
/orca-tasks
```
生成一个Run及其任务。你需要绑定该Run并驱动它运行。
快速路径：跳过规划的小型1-2个任务作业。直接根据目标执行
```
run-create
```
+
```
task-create
```
，然后以相同方式驱动运行。

Load the guides before any command

在执行任何命令前加载指南

text

orca skills get orchestration
orca skills get orca-cli

Read them before running anything. Prefer

--json

for agent-driven calls. Never guess subcommands or flags from memory.

text

orca skills get orchestration
orca skills get orca-cli

在运行任何命令前阅读这些指南。对于Agent驱动的调用，优先使用

--json

参数。绝不要凭记忆猜测子命令或标志。

Pre-flight

预检查

Verify the primary worktree:
```
orca worktree current --json
```
→
```
isMainWorktree
```
must be
```
true
```
, or the run is being coordinated from a task branch. Stop and move to the cockpit worktree if not.
Verify the setup marker exists (
```
docs/agents/setup.md
```
), else route to
```
/orca-setup
```
.

Bind the Run (planned path):

bash

orca orchestration run-use --id <run_id> --json

or create it (quick path):

orca orchestration run-create --objective "<objective>" --json

验证主工作树：
```
orca worktree current --json
```
→
```
isMainWorktree
```
必须为
```
true
```
，否则运行是从任务分支进行协调的。如果不是，请停止操作并切换到控制台工作树。
验证设置标记是否存在（
```
docs/agents/setup.md
```
），否则跳转至
```
/orca-setup
```
。

绑定Run（规划路径）：

bash

orca orchestration run-use --id <run_id> --json

或者创建Run（快速路径）：

orca orchestration run-create --objective "<objective>" --json

。

The DAG loop

DAG循环

Sweep what is ready to run:
bash
```
orca orchestration task-list --run <run_id> --ready --json
```
Every
```
ready
```
task has all its blockers merged on
```
main
```
. Dispatch each ready task to a worker in its own worktree — one task = one branch = one worktree, never the primary.
Create the task worktree first, then launch the
```
worker
```
profile in it, then bind the dispatch (the
```
worker
```
profile is selected through config, not
```
--agent
```
, because opencode's
```
-a <agent>
```
is broken in TUI mode):
bash
```
# independent (no blockers) → top-level worktree; dependent → child worktree
orca worktree create --name <slug> --no-parent --setup run --json
# or: orca worktree create --name <slug> --parent-worktree active --setup run --json
orca terminal create --worktree id:<newWorktreeId> --title <slug> --command "OPENCODE_CONFIG_CONTENT='{\"default_agent\":\"worker\"}' opencode --auto -m <model>" --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration worker-start --task <task_id> --terminal <handle> --worktree id:<newWorktreeId> --json
```
Use a fresh terminal per worker (one worktree = one branch = one worker). Reuse a worker terminal only for an immediate follow-up Task on the same worktree, and only when the plan allows it. Tasks the plan marked
```
isolated: no
```
are the sole exception to the worktree rule — they run in the primary worktree and must be declared before dispatch.
Note: the bare
```
worktree create
```
above (no
```
--agent
```
) may open a fallback shell alongside the later
```
terminal create
```
. Target only the agent handle; close a fallback shell only after
```
orca terminal list --worktree id:<id> --json
```
confirms it is an unused shell.
Alternative — composed launch: when the agent is not opencode (e.g. Claude Code) and its
```
worker
```
profile can be the launched agent,
```
worker-start
```
can create the worktree and launch in one call:
```
orca orchestration worker-start --task <task_id> --worktree new-top-level --name <slug> --agent <tui> --json
```
. Only use this when the launched TUI actually runs the permissive
```
worker
```
profile — otherwise the run stalls on permission prompts.
Wait in rolling windows and process every message before acknowledging:
bash
```
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
```
A timeout or
```
{count:0}
```
is a checkpoint, not a worker failure. Keep waiting until every dispatch settles; workers routinely run 15-60 minutes.

On each
worker_done
, settle it before acknowledging the Delivery:

succeeded

→ the worker already verified the tests are green (CI for github,

uv run pytest

/equivalent for local). Merge the task branch, then clean up the task worktree, then re-sweep:

bash

# github tracker: merge the PR (auto or via the user's review gate)
gh pr merge <pr_number> --squash --delete-branch
# local-only (linear tracker, no remote): merge the branch into main in the cockpit
#   git merge --squash <task-branch> && git push (if a remote exists)
orca orchestration worker-release --dispatch <dispatch_id> --json
orca worktree rm --worktree <task_worktree_id> --force --json
# linear tracker: move the linked issue to Done explicitly — merge does not do it
#   orca linear status set <issue_key> --to "Done" --workspace <workspace_id> --json

Merging unblocks dependents: after cleanup, run

task-list --ready

again and dispatch what is newly ready. The worker merged nothing itself — the coordinator owns the merge. An

external_terminal

worker stays live after

worker-release

: close it with

orca terminal close --terminal <handle>

(see hard-won notes).

failed

→ never redispatch silently. Mark the task failed, block its dependents, and raise a decision gate to the user:

bash

orca orchestration task-update --id <task_id> --status failed --json
# dependents are blocked by the failure — surface them via gate
orca orchestration gate-create --task <dependent_id> --question "<task> failed; retry bounded (worker-start --retry-of), fix forward, or abandon?" --options '["retry","fix-forward","abandon"]' --json

The recommended option is a single bounded retry: create a fresh worktree/terminal (same recipe as step 1) and bind

worker-start --task <id> --terminal <handle> --worktree <sel> --retry-of <failed_dispatch_id> --json

. Your call through the gate decides.

Acknowledge only after every message and release/merge/gate decision is handled:

bash

orca orchestration check --ack <delivery_id> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

Repeat until
```
task-list
```
shows every task
```
completed
```
and no dispatch is unsettled.

扫描就绪可运行的任务：
bash
```
orca orchestration task-list --run <run_id> --ready --json
```
每个
```
ready
```
任务的所有阻塞项都已合并到
```
main
```
分支。将每个就绪任务分发到独立工作树中的工作者—— 一个任务 = 一个分支 = 一个工作树，绝不要使用主工作树。
先创建任务工作树，然后在其中启动
```
worker
```
配置文件，再绑定分发（
```
worker
```
配置文件通过配置选择，而非
```
--agent
```
参数，因为opencode的
```
-a <agent>
```
在TUI模式下存在问题）：
bash
```
# 独立任务（无阻塞项）→ 顶级工作树；依赖任务 → 子工作树
orca worktree create --name <slug> --no-parent --setup run --json
# 或者：orca worktree create --name <slug> --parent-worktree active --setup run --json
orca terminal create --worktree id:<newWorktreeId> --title <slug> --command "OPENCODE_CONFIG_CONTENT='{\"default_agent\":\"worker\"}' opencode --auto -m <model>" --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration worker-start --task <task_id> --terminal <handle> --worktree id:<newWorktreeId> --json
```
每个工作者使用一个全新终端（一个工作树 = 一个分支 = 一个工作者）。仅当计划允许时，才可在同一工作树上为后续任务重用工作者终端。计划标记为
```
isolated: no
```
的任务是工作树规则的唯一例外—— 它们在主工作树中运行，且必须在分发前声明。
注意：上面的
```
worktree create
```
命令（不带
```
--agent
```
）可能会在后续
```
terminal create
```
之外打开一个备用shell。仅针对Agent句柄操作；只有在
```
orca terminal list --worktree id:<id> --json
```
确认它是未使用的shell后，才可关闭备用shell。
**替代方案——组合启动：**当Agent不是opencode（例如Claude Code）且其
```
worker
```
配置文件可作为启动的Agent时，
```
worker-start
```
可一次性创建工作树并启动：
```
orca orchestration worker-start --task <task_id> --worktree new-top-level --name <slug> --agent <tui> --json
```
。仅当启动的TUI实际运行宽松的
```
worker
```
配置文件时才使用此方法——否则运行会因权限提示而停滞。
滚动窗口等待，并在确认前处理所有消息：
bash
```
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
```
超时或
```
{count:0}
```
是检查点，而非工作者失败。持续等待直到所有分发任务完成；工作者通常运行15-60分钟。

针对每个
worker_done
，在确认交付前完成处理：

succeeded

→ 工作者已验证测试通过（GitHub的CI，本地的

uv run pytest

/等效命令）。合并任务分支，然后清理任务工作树，再重新扫描：

bash

# GitHub追踪器：合并PR（自动或通过用户审核关卡）
gh pr merge <pr_number> --squash --delete-branch
# 仅本地（线性追踪器，无远程）：在控制台将任务分支合并到main
#   git merge --squash <task-branch> && git push（如果存在远程仓库）
orca orchestration worker-release --dispatch <dispatch_id> --json
orca worktree rm --worktree <task_worktree_id> --force --json
# 线性追踪器：显式将关联问题移至Done状态——合并操作不会自动完成
#   orca linear status set <issue_key> --to "Done" --workspace <workspace_id> --json

合并操作会解除子任务的阻塞：清理完成后，再次运行

task-list --ready

并分发新就绪的任务。工作者本身不会执行合并——协调器负责合并操作。

external_terminal

工作者在

worker-release

后会保持活跃：使用

orca terminal close --terminal <handle>

关闭它（参见经验总结）。

failed

→ 绝不要静默重新分发。标记任务失败，阻塞其子任务，并向用户发起决策关卡：

bash

orca orchestration task-update --id <task_id> --status failed --json
# 子任务会因失败被阻塞——通过关卡展示它们
orca orchestration gate-create --task <dependent_id> --question "<task>失败；是否进行有限重试（worker-start --retry-of）、向前修复或放弃？" --options '["retry","fix-forward","abandon"]' --json

推荐选项是单次有限重试：创建新的工作树/终端（与步骤1相同的流程）并绑定

worker-start --task <id> --terminal <handle> --worktree <sel> --retry-of <failed_dispatch_id> --json

。通过关卡做出决策。

仅在处理完所有消息以及释放/合并/关卡决策后进行确认：

bash

orca orchestration check --ack <delivery_id> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

重复上述步骤，直到
```
task-list
```
显示所有任务为
```
completed
```
且没有未完成的分发任务。

Watchdog: worker finished but no worker_done

看门狗：工作者已完成但未发送worker_done

A worker can finish its work and idle at the prompt without sending

worker_done

. When a wait window times out, inspect each unsettled dispatch instead of waiting blindly:

orca orchestration worker-read --dispatch <id> --json

and

orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json

If the worker is idle and its last message shows the work done (branch pushed, CI green, PR ready, final summary) but no

worker_done

arrived, re-inject the finalization from the worker's own terminal — the authority must come from there:

bash

orca terminal send --terminal <handle> --text 'orca orchestration send --type worker_done --subject "<status>" --body "<done, found, left>" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded --files-modified "path/a" --json' --enter --json

then continue

check --wait

If it still does not settle, recover manually:

orca orchestration task-update --id <task_id> --status completed

then

orca orchestration worker-release --dispatch <dispatch_id> --json

Never stop, close, or kill a worker because of a timeout, TUI idle, heartbeat, or status — those mean alive, not done. Never leave a settled worker live: reuse, retain only at the user's request, or

worker-release

工作者可能完成工作后在提示符处闲置，却未发送

worker_done

。当等待窗口超时时，请检查每个未完成的分发任务，而非盲目等待：

执行

orca orchestration worker-read --dispatch <id> --json

和

orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json

。

如果工作者处于闲置状态，且其最后一条消息显示工作已完成（分支推送、CI通过、PR就绪、最终总结）但未收到

worker_done

，则从工作者自身终端重新注入完成指令——权限必须来自该终端：

bash

orca terminal send --terminal <handle> --text 'orca orchestration send --type worker_done --subject "<status>" --body "<done, found, left>" --task-id <task_id> --dispatch-id <dispatch_id> --outcome succeeded --files-modified "path/a" --json' --enter --json

然后继续执行

check --wait

。

如果仍未完成，则手动恢复：

orca orchestration task-update --id <task_id> --status completed

然后

orca orchestration worker-release --dispatch <dispatch_id> --json

。

绝不要因超时、TUI闲置、心跳或状态而停止、关闭或终止工作者——这些状态表示工作者仍在运行，而非已完成。绝不要让已完成的工作者保持活跃：重用、仅在用户请求时保留，或执行

worker-release

。

Merge policy

合并策略

CI green is the gate. Nothing red merges — better to test and fix than merge and break.
github tracker: squash-merge the PR (
```
gh pr merge --squash --delete-branch
```
) once green.
linear tracker with no remote: the worker's tests are the gate; merge the task branch into the cockpit
```
main
```
locally (
```
git merge --squash <task-branch>
```
), push if a remote exists.
The coordinator merges, the worker never does. The merge is what unblocks dependents, so merge promptly after a
```
succeeded
```
report — a dependent blocked on an unmerged parent looks identical to a stuck run.

CI通过是关卡。任何失败的任务都不会合并——测试并修复比合并后破坏更好。
GitHub追踪器：CI通过后，压缩合并PR（
```
gh pr merge --squash --delete-branch
```
）。
线性追踪器（无远程）：工作者的测试是关卡；在控制台将任务分支本地合并到
```
main
```
（
```
git merge --squash <task-branch>
```
），如果存在远程仓库则推送。
由协调器执行合并，工作者绝不执行。合并操作会解除子任务的阻塞，因此在收到
```
succeeded
```
报告后请及时合并——因父任务未合并而阻塞的子任务看起来与停滞的运行完全相同。

Hard-won notes

经验总结

opencode's
```
-a <agent>
```
is broken in TUI mode (prints help and exits) → pass the agent with
```
OPENCODE_CONFIG_CONTENT='{"default_agent":"worker"}'
```
and add
```
--auto
```
as a safety net:
bash
```
OPENCODE_CONFIG_CONTENT='{"default_agent":"worker"}' opencode --auto -m <model>
```
```
worker-start --agent <tui>
```
launches the named TUI app; it does not select the permissive
```
worker
```
profile. For opencode, select the profile with
```
OPENCODE_CONFIG_CONTENT
```
and bind via
```
--terminal
```
(see the DAG loop).

worker-start --terminal <handle>

requires

--worktree

to match the terminal's worktree, or it fails with

terminal_worktree_mismatch

opencode defaults to prompting (
```
ask
```
) for
```
external_directory
```
and
```
doom_loop
```
; the
```
worker
```
agent auto-allows them so unattended runs never stall on a permission prompt.
```
worker_done
```
must come from the worker's own terminal with the injected
```
--task-id
```
/
```
--dispatch-id
```
; it marks the task and dispatch complete automatically — do not follow it with a manual
```
task-update
```
(except in recovery).
```
worker-start
```
```
--worktree new-child
```
/
```
new-top-level
```
creates a fresh worktree + branch and does not rerun setup. Do not reuse the primary worktree for tasks.
A worker launched through
```
terminal create
```
(custom argv /
```
OPENCODE_CONFIG_CONTENT
```
) is an
```
external_terminal
```
: after
```
worker-release
```
returns
```
retained / external_terminal
```
, close the worker terminal yourself (
```
orca terminal close --terminal <handle>
```
) — Orca does not close terminals it did not create through
```
worker-start
```
.
Tracker updates after merge are not automatic:
```
gh pr merge
```
closes the GitHub issue on its own, but Linear does not move the issue state when the PR merges. After a successful linear-tracker merge, update the linked issue explicitly (
```
orca linear status set <key> --to "Done" --workspace <id>
```
and
```
orca linear comment add <key> --body "Merged in <pr/branch>"
```
) so the tracker reflects the run.

opencode的
```
-a <agent>
```
在TUI模式下存在问题（打印帮助信息后退出）→ 通过
```
OPENCODE_CONFIG_CONTENT='{"default_agent":"worker"}'
```
传递Agent，并添加
```
--auto
```
作为安全网：
bash
```
OPENCODE_CONFIG_CONTENT='{"default_agent":"worker"}' opencode --auto -m <model>
```
```
worker-start --agent <tui>
```
会启动指定的TUI应用；它不会选择宽松的
```
worker
```
配置文件。对于opencode，请通过
```
OPENCODE_CONFIG_CONTENT
```
选择配置文件并通过
```
--terminal
```
绑定（参见DAG循环）。

worker-start --terminal <handle>

要求

--worktree

与终端的工作树匹配，否则会因

terminal_worktree_mismatch

失败。

opencode默认会对
```
external_directory
```
和
```
doom_loop
```
进行提示（
```
ask
```
）；
```
worker
```
Agent会自动允许这些操作，因此无人值守的运行绝不会因权限提示而停滞。
```
worker_done
```
必须来自工作者自身终端，并注入
```
--task-id
```
/
```
--dispatch-id
```
；它会自动标记任务和分发完成——请勿在其后执行手动
```
task-update
```
（恢复场景除外）。
```
worker-start
```
的
```
--worktree new-child
```
/
```
new-top-level
```
会创建新的工作树+分支，且不会重新运行设置。请勿将主工作树用于任务。
通过
```
terminal create
```
启动的工作者（自定义argv /
```
OPENCODE_CONFIG_CONTENT
```
）属于
```
external_terminal
```
：在
```
worker-release
```
返回
```
retained / external_terminal
```
后，请自行关闭工作者终端（
```
orca terminal close --terminal <handle>
```
）——Orca不会关闭未通过
```
worker-start
```
创建的终端。
合并后的追踪器更新不会自动完成：
```
gh pr merge
```
会自行关闭GitHub问题，但Linear在PR合并时不会更改问题状态。成功合并线性追踪器的任务后，请显式更新关联问题（
```
orca linear status set <key> --to "Done" --workspace <id>
```
和
```
orca linear comment add <key> --body "已合并至<pr/branch>"
```
），以便追踪器反映运行状态。