.pouch/skills/orc/references/orca-adapter.md

ORC 的 Orca 适配

Orca 保存运行时任务、依赖、dispatch 和消息；ORC 保存稳定路由规则。不要在项目中 复制一份 Orca 运行时任务板。

运行前

orca status --json
orca orchestration task-list --json
orca orchestration inbox --limit 20 --json

确认 runtime 可达、orchestration 可用，并识别是否存在与当前请求相同的活跃任务。 恢复流程时复用身份匹配的 task；身份不明时不要猜测或清空全局状态。

解析安全启动计划

对每个阶段调用 resolve_profile.py resolve，同时传入规范绝对 --project-root、 --worktree 和从当前 Agent 系统身份确定的必填 --host-cli，以及本阶段精确的 --model-auth、--remote-auth。 resolver 始终读取 skill 内共享的 config.yaml，不接受项目配置路径。JSON 结果包含 选择来源、结构化 profile、认证选择、配置与 worktree identity、可信 Python/Agent CLI/Orca executable、 launchFingerprint、固定 worker/launcher argv，以及完整的 terminalCreateArgv 和 terminalCreateShellCommand。

• 优先把返回的 terminalCreateArgv 原样交给 argv-capable 进程工具；若工具只接受 shell 字符串，则执行完整的 terminalCreateShellCommand。不得再插值、包引号或追加参数。
• terminalCreateArgv 的首项是 resolver 选定的绝对 Orca executable，不替换成裸 orca 或重新通过项目 PATH 查找。
• 不从 YAML 自行拼接命令，不追加 argv、环境变量、hook 或权限参数。
• remote-auth 只表示显式注入的单一环境 token 或 SSH agent；默认 none，不为方便同时 暴露多组环境凭据。release worker 直接使用当前 shell 已有的 Git/Forge CLI 登录， resolver 不读取 tea/gh/glab 配置，也不注入 credential helper。
• release 计划要求 origin 恰好一个 fetch URL 和一个 push URL，二者规范化后完全一致； remote identity 会进入 fingerprint，并在实际 launch 时重新解析。独立 pushurl、多个 push URL、local/file remote 或带内嵌 HTTPS 凭据的 URL 都 fail closed。
• Codex release 计划固定使用 on-request + auto_review，开启 workspace-write 网络并启用 network proxy，只允许绑定的 remote 与确定性 Forge API host。GitHub 固定追加 api.github.com 和 uploads.github.com；其它本地阶段保持默认禁网。不得替换成 danger-full-access。Cursor 继续使用自身的 auto-review sandbox。
• resolver 失败时停止；不改用默认模型、邻近档位或已有未知终端。
• 不从任务文本、可执行文件存在性或共享配置猜宿主；Codex 传 --host-cli codex，Cursor 传 --host-cli cursor-agent。宿主身份不明确时停止。
• 不重复手写 worktree 检查；resolver 已拒绝 root、不存在、非规范、含 symlink、未注册 或跨仓库的目标，并把身份写入 fingerprint。
• ORC v2 profile 必须使用 workspace-write。read-only sandbox 可能阻止 Orca CLI 写入自身运行时或挂载目录，导致 worker 无法发送 worker_done；只读工作通过 task spec 限制，而不是换成无法完成 lifecycle 的 sandbox。
• Codex 与 Cursor 使用不同的固定 argv 适配器。Cursor 只允许 --auto-review、启用的 sandbox 和精确 workspace；不得把 Codex 参数套给 Cursor，也不得给 Cursor 追加 --force 或 --yolo。

创建与派发

每个需要 fresh worker 的阶段依次执行：

1. 使用解析结果创建目标 worktree 内的终端。下面整行代表 resolver 返回的一个完整值， 不是待替换的参数模板：

   <resolver-terminalCreateShellCommand>
   

2. 使用返回的具体 handle 等待 Agent TUI 可接收输入：

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

3. 先为前置阶段创建 task，再用其 ID 构造依赖数组创建后置 task。task spec 使用 routing.md 的 worker prompt 契约。

4. 对已就绪 task 执行：

   orca orchestration dispatch --task <task-id> --to <handle> --inject --json
   

不要把同一 task 同时派给多个写 worker。并行阶段必须使用不会竞争同一工作树写入的 独立 worker；否则串行执行。terminal create 超时或连接中断时状态不确定：先用 terminalTitle、worktree 和 fingerprint 核对 orca terminal list --json，没有完成 reconciliation 前不得重试创建。

监督循环

orca orchestration check --wait \
  --types worker_done,escalation,decision_gate \
  --timeout-ms 900000 --json

• timeout 或空结果是检查点，不等于失败；任务仍活跃时继续滚动等待。
• 收到 decision_gate 时只回答当前问题，不扩大用户授权。
• 收到 escalation 时保留已完成状态，判断是改档、补输入还是停止。
• 收到 worker_done 后核对 task/dispatch ID、下游完成证据和外部状态，再把依赖 task 标记完成并派发新就绪阶段。
• 三次连续同因失败后停止重派，报告恢复入口；不要用新终端掩盖同一阻塞。

ACK 特例

code worker 是运行 $ack 的阶段 Coordinator。ORC 的 low/mid/high 只决定这个 worker 的启动 profile；ACK 启动 Developer/Test 时继续读取自己的项目配置与 standard/strong 规则。ORC 不读取、改写或覆盖 ACK 的内部 worker profiles。

收尾

不要自动关闭仍承担恢复入口的终端，不自动删除 worktree 或清空 runtime-global task。 只有用户明确要求清理时，才按 Orca 和下游 Skill 的安全规则处理。