.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，以及本阶段精确的 --model-auth、--remote-auth。JSON 结果包含选择来源、 结构化 profile、认证选择、配置与 worktree identity、可信 Python/Codex/Orca executable、 launchFingerprint、固定 worker/launcher argv，以及完整的 terminalCreateArgv 和 terminalCreateShellCommand。

• 优先把返回的 terminalCreateArgv 原样交给 argv-capable 进程工具；若工具只接受 shell 字符串，则执行完整的 terminalCreateShellCommand。不得再插值、包引号或追加参数。
• terminalCreateArgv 的首项是 resolver 选定的绝对 Orca executable，不替换成裸 orca 或重新通过项目 PATH 查找。
• 不从 YAML 自行拼接命令，不追加 argv、环境变量、hook 或权限参数。
• remote-auth 必须与本阶段唯一目标 provider/transport 一致；默认 none，不为方便 同时暴露多个 token 或 SSH agent。需要代理、额外凭据或 Docker registry env secret 时 fail closed，由用户确认新的最小权限适配，不继承 ambient proxy/credential 变量。
• resolver 失败时停止；不改用默认模型、邻近档位或已有未知终端。
• 不重复手写 worktree 检查；resolver 已拒绝 root、不存在、非规范、含 symlink、未注册、 跨仓库或不在 allowlist 的目标，并把身份写入 fingerprint。
• ORC v1 profile 必须使用 workspace-write。read-only sandbox 可能阻止 Orca CLI 写入自身运行时或挂载目录，导致 worker 无法发送 worker_done；只读工作通过 task spec 限制，而不是换成无法完成 lifecycle 的 sandbox。

创建与派发

每个需要 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 的安全规则处理。