feat(agent-runtime): unify agent bindings and sessions

skills/agent-runtime/README.md

@@ -0,0 +1,38 @@
+# 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。