# Runner连接与观测生命周期

注册成功、Edge连接、执行准入和计算依赖安装分别有独立状态，文档需为每一步说明判断依据。

## 注册、恢复与刷新

创建Runner先保存待完成记录及加密连接命令交付，再登记所有权，最后推进内部生命周期为active；失败可能留下可恢复意图。普通读取只展示active记录，不能据失败后列表为空断言所有写入均已回滚。

相同工作区、请求ID、Principal和Effective Role的重放可回读交付命令，交付窗口为30分钟。当前重放不以name建立新的请求payload一致性校验；同请求ID改名仍返回原Runner，不能把它作为更新名称的方法。显式刷新使原交付失效；窗口届满、记录删除中或身份不匹配可返回409等错误。

刷新使用agent_runner.manage，保持Runner/Edge ID，返回新连接命令。它会与Edge主动续期竞争当前JTI，内部有限重读重试不等于客户端可无限重复刷新。响应丢失先保留Runner ID并核对，不能使用普通GET取回连接命令。

注销先提交deleting屏障，再处理关联插件原生会话、凭据吊销、所有权及记录清理。失败可由既有恢复机制继续；不承诺停止主机上的astra-edge进程、卸载软件、删除用户文件或立即取消全部任务。

## 连接状态和权限

health从可读Runner及启用Sandbox形成可见集合，再读取调用者映射下的Edge状态，连接缓存5秒。无可见对象时不调用Astra；有对象但Astra失败时返回对象列表及astra_reachable=false，不能把它当确定离线。

当前connected/ready均由连接命中派生；phase来自持久记录。运行前仍重验agent_runner.use或agent_sandbox.use及真实Agent的agent.use，健康结果不是授权凭据。

## 计算依赖观测

限制读取提供当前部署参数，服务缺失返回503，加载失败返回500，不伪造默认配置。安装观测来自已保存cloud实例，仅保留当前SHA和非终态记录；空列表可表示未设置依赖、无匹配观测或服务未装配。

实例READY与py_requirements_status=FAILED可同时出现，二者描述不同层次。聚合状态按失败优先、其次安装中、再就绪处理；资源详情的聚合加载失败可省略py_deps，不应把缺失对象自动解释为安装成功。

<span id="errors"></span>

## 错误与恢复

| 入口 | 主要错误合同 |
| --- | --- |
| Runner列表/详情/创建/刷新/删除 | 字符串code/msg；400 INVALID_PARAMS，404 RUNNER_NOT_FOUND，403 RUNNER_FORBIDDEN，503 RUNNER_IAM_UNAVAILABLE；名称、请求身份、进行中或交付不可用对应不同409代码。 |
| Edge续期 | 数值code为HTTP状态：401表示旧注册凭据或当前绑定无效，503表示吊销/绑定依赖不可用，其余内部故障500。不套Runner字符串错误。 |
| 执行器健康 | 正常包为字符串OK/msg；缺工作区的接口错误使用数值2，service错误沿公共映射。Astra状态读取失败可仍HTTP200。 |
| 依赖限制 | 503 LIMITS_UNAVAILABLE，500 LIMITS_READ_FAILED；缺工作区400 INVALID_PARAMS。 |
| Worker观测 | 资源预检查的任意错误折叠404 NOT_FOUND；观测读取其他错误500 INTERNAL_ERROR。没有读取服务时提前返回空数组。 |

不能由404推断对象全局不存在，或由空数组推断权限/对象检查成功。
