# Agent Runtime 配置

## 文件与合并

提交 `.pouch/agent.yaml`。若存在 `.pouch/agent.local.yaml`，按 mapping 深度合并；local
文件只能覆盖同名字段，不能增加未声明的顶层结构。合并后的配置必须再次完整校验。

```yaml
schemaVersion: 1
locations:
  local-app:
    environment: local
    host: local
    project: git:git.yumee.top/bloggarden/app
    path: /home/ace/code/draft2/blogger/app
  remote-ios:
    environment: macmini
    host: runtime:14b6d8ce-4528-49f4-8d46-56b266a5ad69
    project: git:git.yumee.top/bloggarden/app
    path: /Users/laily/workrepo/bloggarden-app
profiles:
  android-builder:
    role: build
    cli: codex
    tier: standard
    model: gpt-5
    reasoningEffort: medium
    permissionMode: workspace-write
  ios-builder:
    role: build
    cli: codex
    tier: strong
    model: gpt-5
    reasoningEffort: high
    permissionMode: workspace-write
bindings:
  builder.android:
    adapter: builder
    location: local-app
    profile: android-builder
    makefile: makefile.builder
    target: android
    session:
      lifecycle: persistent
  builder.ios:
    adapter: builder
    location: remote-ios
    profile: ios-builder
    makefile: makefile.builder
    target: ios
    session:
      lifecycle: persistent
```

## 字段原则

- binding、location、profile ID 只允许小写字母、数字和 `-`，binding 用一个或多个点
  分隔；ID 是路由名，不是任意 shell 文本。
- `environment: local` 使用当前 Orca runtime；远程环境使用已保存的名称。`host` 必须
  是 `local` 或 `runtime:<environment-id>`，由 Orca 查询结果证明，不能凭主机名猜测。
- `project` 必须是 Orca project id 或精确 display name；`path` 必须是目标机器上的绝对
  路径。解析 worktree 时四者必须同时匹配，标题、分支和 basename 不能消歧。
- `profile` 的 CLI 只能来自 ACK/tester 共同 allowlist：`codex`、`cursor-agent`、`grok`、
  `omp`、`pi`。`model` 为安全模型 ID 或 null；`reasoningEffort` 为 `low|medium|high|xhigh`
  或 null；权限只允许 `read-only|workspace-write`。
- builder 的 `target` 只能是 make target 名；`makefile` 只能是项目内相对文件名。脚本、
  远端命令、环境变量和凭据由 builder/Orca adapter 提供，不能写入此配置。
- `session.lifecycle` 为 `persistent` 或 `ephemeral`。persistent 只表示允许显式跨
  session attach/resume，不表示自动复用旧 terminal。

旧版 `.pouch/tester/local.yaml` 和 `.pouch/ack/agents.yaml` 继续兼容。迁移时应让它们
由 adapter 从 common profile/location 生成或覆盖，不能删除旧 receipt、fingerprint 或
tester 的每轮 terminal 清理语义。