# agent-runtime

统一维护项目的 Agent profile、Orca 执行环境、worktree 和跨 session terminal。它让
`builder.android`、`builder.ios` 等 binding 成为可配置路由，而不是写死在 skill 代码里的
枚举。

## 什么时候使用

- 给不同 builder/tester/ACK 绑定不同机器、项目目录、Agent CLI 或模型。
- 创建远程 Mac/本地 worktree，并需要后续 session 继续查看构建。
- 检查 `.pouch/agent.yaml` 是否能被所有 adapter 安全读取。

## 使用前准备

- 项目根已有 `.pouch/agent.yaml`。
- 远程 environment 已通过 Orca 配对，且 project/worktree 已存在或被明确创建。
- 机器路径、project id/name 和模型信息由使用者确认；配置不包含凭据。

## 使用示例

```text
把 builder.android 绑定到本地 app，把 builder.ios 绑定到 macmini，创建 iOS worktree，
然后让 builder 继续使用同一个 session 构建。
```

## Agent 会做什么

1. 校验并解析通用配置。
2. 按 environment、host、project、绝对 path 精确定位 Orca worktree。
3. 按需要创建持久 terminal，并记录可显式恢复的 run receipt。

不会自动复用旧 terminal、执行配置中的自由 shell、读取 secrets 或上传产物。

## 如何判断完成

- `agent.py validate` 通过。
- 每个 binding 能唯一解析到目标 worktree，或明确报告需创建/登记的环境。
- session 可用 run id 查询、attach 和 stop。