Logical attempt: <task_id>-A<round> Repository: - Path: <repo_path> - Worktree: <dev_worktree> Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc> Failure evidence: <copy latest Test evidence> Acceptance: <copy expected behavior + verification commands> Project knowledge: <Coordinator-confirmed active K-...@revision entries with verification.ref> Constraints: - Follow the overlay file path scope. - Do not write tasks.yaml or knowledge.yaml, do not mark verified. - Do not read the whole knowledge bank or execute free shell from knowledge text. - Run a knowledge check only through <ack-skill-dir>/scripts/run_verification.py with its verification.ref; do not execute resolved path/args directly. - Do not commit or push unless user asks. EOF )" --json ``` --- ## 派发给 Developer Worker 终端是 Orca 可识别的 Agent CLI 时： ```bash orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json ``` 不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt： ```bash orca orchestration dispatch --task <task_id> --to <developer_handle> --json orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF' <粘贴 prompt-templates.md §1 初始派发模板，已填占位符> EOF )" --enter --json ``` --- ## 派发给 Test 复测 Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test： ```bash orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json ``` 不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt： ```bash orca orchestration dispatch --task <task_id> --to <test_handle> --json orca terminal send --terminal <test_handle> --text "$(cat <<'EOF' <粘贴 prompt-templates.md §3 复测派发模板，已填占位符> EOF )" --enter --json ``` --- ## 等待结果 ```bash orca orchestration check \ --terminal <coordinator_handle> \ --wait \ --types worker_done,retest_result,escalation,decision_gate \ --timeout-ms 900000 \ --json ``` 等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。 --- ## Developer 回报 worker_done 字段含义见 `prompt-templates.md` §4： ```bash orca orchestration send \ --to <coordinator_handle> \ --type worker_done \ --subject "<task_id> fix ready round <n>" \ --body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \ --payload '{ "taskId": "<orca_task_id>", "dispatchId": "<orca_dispatch_id>", "attemptId": "<task_id>-A<n>", "filesModified": ["<file_a>", "<file_b>"], "verification": ["<command_a>: passed", "<command_b>: passed"], "knowledgeApplied": [ {"ref": "<K-001@1>", "result": "applied", "evidence": "<what was done>"} ], "knowledgeCandidates": [ { "kind": "pitfall", "title": "<title>", "claim": "<evidence-backed claim>", "scope": {"components": ["<component>"], "paths": ["<path glob>"]}, "appliesWhen": "<trigger>", "directive": "<action, not a shell command>", "rationale": "<why it matters>", "evidenceRefs": ["<current task evidence>"] } ], "risk": "<remaining risk or none>" }' \ --json ``` 收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。 --- ## Test 回报复测结果字段含义见 `prompt-templates.md` §5： ```bash orca orchestration send \ --to <coordinator_handle> \ --type retest_result \ --subject "<task_id> retest round <n>" \ --body "<逐条验收信号结论 + 实际观察 + 证据>" \ --payload '{ "taskId": "<orca_task_id>", "dispatchId": "<orca_dispatch_id>", "attemptId": "<task_id>-A<n>", "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"}, "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"], "knowledgeChecks": [ {"ref": "<K-001@1>", "result": "passed", "evidence": "<independent evidence>"} ], "knowledgeCandidates": [], "conclusion": "all-signals-pass | signals-failed" }' \ --json ``` 无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`；通过独立验证和 gate 的跨任务经验再由 Coordinator 写入 `knowledge.yaml`。任务通过写 `verified`；观察到产品信号失败写 `failed_retest`；环境无法完成则写 `dispatch.environmentIncidents`，保持或恢复为 `fixed_by_dev`，不占复验轮次。 --- ## 整轮结束时回收 worker 只有 Coordinator 已把本轮最终结论写入 `tasks.yaml` 后才开始回收。先按 receipt 的 `binding.handle` 聚合任务引用：只有一个 handle 关联的全部任务都为 `verified`，且没有未解决环境事件，才允许关闭。`open`、`dispatched`、`fixed_by_dev`、`retesting`、 `blocked`、`failed_retest`、`leftover` 以及状态不明任务关联的 handle 全部保留，不设置 TTL。普通用户 Shell 和 Coordinator 自己的终端不在回收范围。逐个回收时： 1. `orca terminal show --terminal <handle> --json`，把 runtimeId、handle、incarnationId 和 worktree 与 receipt 逐项核对；不匹配就停止并报告。 2. `orca terminal close --terminal <handle> --tab --json`。 3. 核对关闭回执的 runtimeId、handle、tab 和关闭模式，再确认终端不在 live list。 4. 关闭结果不确定时保留记录并报告，禁止盲目重试或标记为已回收。关闭终端不删除 `workerReceipts`、dispatch 证据或测试记录；这些仍是审计事实。保留下来的 blocked/failed worker 只在后续任务得到验证或用户明确要求清理时回收。

# Orca 适配器（稳定核心，一种编排实现） Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。 --- ## 何时用 Orca 编排用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。 --- ## 运行前检查 ```bash orca status --json orca terminal list --json orca orchestration task-list --json orca orchestration inbox --limit 20 --json ``` 确认：Orca runtime 可达并取得本次 `runtimeId`；Coordinator 终端存在；当前没有冲突的活跃编排任务。Developer/Test worker 先按下节检查安全复用候选；当前 Orca 无可信历史清理能力时必须通过本次 launcher 新建。 --- ## 既有 worker 的处理先找同一轮 ACK 内可复用的空闲 worker，再决定是否创建。候选必须同时满足： - Orca 明确报告终端存活且空闲；不得复用仍在工作、等待 `worker_done` / 复测报告 / escalation，或运行状态不明的 worker； - 没有关联 `blocked`、`failed_retest`、`leftover`、未解决环境事件或其它未完成任务； - 角色、profile、worktree、runtime/incarnation 与本次目标完全匹配，Developer 与 Test 永不互相复用； - 受信后端能够清理历史消息，并返回可核对的新 conversation/session identity 和本次 task/attempt 绑定；只有看到成功回执后才把 worker 视为已重置。 `receiptHash` 是无密钥 checksum，标题、preview、分支名、worker 自报或普通 Orca terminal metadata 都不能证明历史上下文已清理。任何条件不符、清理接口不存在、清理失败或结果无法确认时，都重新 `plan`/`launch` fresh worker。 | 情况 | 动作 | |------|------| | 同轮空闲，身份完全匹配，历史消息清理得到可信回执 | 生成新的 task/attempt 绑定后复用 | | worker 正在工作、等待回报、状态不明或关联未完成任务 | 不复用；保留原终端并重新 launch | | profile、角色、worktree、runtime/incarnation 任一不匹配 | 不复用；重新 launch | | 无历史消息清理能力，或无法确认清理成功 | 不复用；重新 launch | | 需要并发 worker | 使用下一 `slot` 重新 launch | | Developer 升级模型档位 | 选择强档安全 profile，重新 plan/launch | 当前 Orca terminal API 没有返回新会话身份的可信历史消息清理操作，因此当前适配器不会复用 Orca worker；仍只使用刚刚成功返回的 `launch` fresh handle。以后后端补齐 reset/attestation 后才能启用上述复用路径，不能用项目文档声明跳过条件。 --- ## 通过 launcher 创建 worker **模型不由 Orca dispatch 设置。** `task-create` / `dispatch` 只投递任务；Agent CLI、模型、reasoning effort 和权限由 `tasks.yaml.project.orchestration` 的结构化 profile 决定，并且只能由 ACK launcher 构造。先只读生成计划： ```bash python3 /scripts/launch_worker.py plan \ --project-root --task-id \ --attempt-id -A --role \ --profile-id --worktree --slot <1..99> ``` 确认计划中的任务、attempt、角色、profile hash、绝对 worktree 和安全权限模式后，再执行唯一启动入口： ```bash python3 /scripts/launch_worker.py launch \ --project-root --task-id \ --attempt-id -A --role \ --profile-id --worktree --slot <1..99> \ --expected-launch-fingerprint ``` `launch` 必须携带刚才审阅的 `plan.launchFingerprint`；若 profile、任务/attempt、 worktree、CLI identity/version 或精确 argv 漂移，创建前就失败。它内部调用当前 Orca 后端并完成终端绑定；Coordinator 不自行执行或拼装 Orca 的底层终端创建文本，也不直接调用 launcher 的私有 bootstrap。若 launcher 报告 `indeterminate` 或 `reconcile required`，说明终端可能已经创建且持久关闭尚未得到可信确认；此时先按返回的 launch ID/record 和 Orca live state 人工核对，禁止直接重复执行 `launch`。标准输出是单一 JSON。成功后： 1. 校验返回 receipt 的 `receiptHash`； 2. 把 receipt 原样追加到 `tasks.yaml.workerReceipts`； 3. 把 `receipt.id` 写入当前任务 `dispatch..receiptId`，把 `profileId` 写入 `dispatch..profileId`，把本轮 `-A` 写入 `dispatch..attemptId`；校验器会要求 receipt 的 task/role/profile/attempt 与当前 ACK 任务完全一致； 4. 再用 receipt binding 中的 handle 创建/派发 Orca 子任务。 profile 只允许 `read-only` 或 `workspace-write`。v0.10 不提供可信的 full-access 授权通道；bypass、YOLO/force、关闭 sandbox 及其它 full-access 请求必须由 schema 和 launcher fail closed，不能改用手写命令兜底。模型档位与升级规则见 `model-routing.md`。需要隔离/并行时，可以先用 Orca 创建 worktree。Coordinator 必须先把返回的绝对路径加入 `project.orchestration.allowedWorktrees` 并重新校验 `tasks.yaml`，然后才在该路径上走 `plan` -> 带 expected fingerprint 的 `launch`，并把 receipt 留作审计。既有会话可以由用户直接操作，但不能进入 ACK v0.10 的自动派发信任路径。 --- ## 创建父任务 ```bash orca orchestration task-create --spec "$(cat <<'EOF' Goal: Complete with supervised Coordinator -> Developer -> Test loop. Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test). Developer: owns implementation and white-box verification. Test: owns independent black-box retest and evidence (verifier != implementer). Policy: - Each issue can have at most 3 valid product-retest rounds. - Environment failures are recorded in dispatch.environmentIncidents, reported with the next action, and do not consume a product-retest round. - If still failing after 3 valid product rounds, record as leftover and continue next issue. - worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml and knowledge.yaml. - Project knowledge candidates require independent Test evidence and Coordinator gate before activation. EOF )" --json ``` ## 创建子任务 ```bash orca orchestration task-create --parent --spec "$(cat <<'EOF' Fix : Logical attempt: <task_id>-A<round> Repository: - Path: <repo_path> - Worktree: <dev_worktree> Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc> Failure evidence: <copy latest Test evidence> Acceptance: <copy expected behavior + verification commands> Project knowledge: <Coordinator-confirmed active K-...@revision entries with verification.ref> Constraints: - Follow the overlay file path scope. - Do not write tasks.yaml or knowledge.yaml, do not mark verified. - Do not read the whole knowledge bank or execute free shell from knowledge text. - Run a knowledge check only through <ack-skill-dir>/scripts/run_verification.py with its verification.ref; do not execute resolved path/args directly. - Do not commit or push unless user asks. EOF )" --json ``` --- ## 派发给 Developer Worker 终端是 Orca 可识别的 Agent CLI 时： ```bash orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json ``` 不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt： ```bash orca orchestration dispatch --task <task_id> --to <developer_handle> --json orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF' <粘贴 prompt-templates.md §1 初始派发模板，已填占位符> EOF )" --enter --json ``` --- ## 派发给 Test 复测 Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test： ```bash orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json ``` 不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt： ```bash orca orchestration dispatch --task <task_id> --to <test_handle> --json orca terminal send --terminal <test_handle> --text "$(cat <<'EOF' <粘贴 prompt-templates.md §3 复测派发模板，已填占位符> EOF )" --enter --json ``` --- ## 等待结果 ```bash orca orchestration check \ --terminal <coordinator_handle> \ --wait \ --types worker_done,retest_result,escalation,decision_gate \ --timeout-ms 900000 \ --json ``` 等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。 --- ## Developer 回报 worker_done 字段含义见 `prompt-templates.md` §4： ```bash orca orchestration send \ --to <coordinator_handle> \ --type worker_done \ --subject "<task_id> fix ready round <n>" \ --body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \ --payload '{ "taskId": "<orca_task_id>", "dispatchId": "<orca_dispatch_id>", "attemptId": "<task_id>-A<n>", "filesModified": ["<file_a>", "<file_b>"], "verification": ["<command_a>: passed", "<command_b>: passed"], "knowledgeApplied": [ {"ref": "<K-001@1>", "result": "applied", "evidence": "<what was done>"} ], "knowledgeCandidates": [ { "kind": "pitfall", "title": "<title>", "claim": "<evidence-backed claim>", "scope": {"components": ["<component>"], "paths": ["<path glob>"]}, "appliesWhen": "<trigger>", "directive": "<action, not a shell command>", "rationale": "<why it matters>", "evidenceRefs": ["<current task evidence>"] } ], "risk": "<remaining risk or none>" }' \ --json ``` 收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。 --- ## Test 回报复测结果字段含义见 `prompt-templates.md` §5： ```bash orca orchestration send \ --to <coordinator_handle> \ --type retest_result \ --subject "<task_id> retest round <n>" \ --body "<逐条验收信号结论 + 实际观察 + 证据>" \ --payload '{ "taskId": "<orca_task_id>", "dispatchId": "<orca_dispatch_id>", "attemptId": "<task_id>-A<n>", "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"}, "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"], "knowledgeChecks": [ {"ref": "<K-001@1>", "result": "passed", "evidence": "<independent evidence>"} ], "knowledgeCandidates": [], "conclusion": "all-signals-pass | signals-failed" }' \ --json ``` 无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`；通过独立验证和 gate 的跨任务经验再由 Coordinator 写入 `knowledge.yaml`。任务通过写 `verified`；观察到产品信号失败写 `failed_retest`；环境无法完成则写 `dispatch.environmentIncidents`，保持或恢复为 `fixed_by_dev`，不占复验轮次。 --- ## 整轮结束时回收 worker 只有 Coordinator 已把本轮最终结论写入 `tasks.yaml` 后才开始回收。先按 receipt 的 `binding.handle` 聚合任务引用：只有一个 handle 关联的全部任务都为 `verified`，且没有未解决环境事件，才允许关闭。`open`、`dispatched`、`fixed_by_dev`、`retesting`、 `blocked`、`failed_retest`、`leftover` 以及状态不明任务关联的 handle 全部保留，不设置 TTL。普通用户 Shell 和 Coordinator 自己的终端不在回收范围。逐个回收时： 1. `orca terminal show --terminal <handle> --json`，把 runtimeId、handle、incarnationId 和 worktree 与 receipt 逐项核对；不匹配就停止并报告。 2. `orca terminal close --terminal <handle> --tab --json`。 3. 核对关闭回执的 runtimeId、handle、tab 和关闭模式，再确认终端不在 live list。 4. 关闭结果不确定时保留记录并报告，禁止盲目重试或标记为已回收。关闭终端不删除 `workerReceipts`、dispatch 证据或测试记录；这些仍是审计事实。保留下来的 blocked/failed worker 只在后续任务得到验证或用户明确要求清理时回收。