> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件、状态与转换

状态属于具体对象。Session 仍 open 时 Run 可以 completed；Run 等待审批时 Sandbox 可以 running；Runtime unreachable 不证明计算资源不存在。客户端连接状态另行维护。

## Session

| 状态 | 解释 |
| - | - |
| `open` | 允许工作，不代表已有 Sandbox 或当前正在执行。 |
| `pausing / paused / resuming` | 暂停与恢复过程，结合 pause\_scope 判断；Session 级与 Sandbox 级暂停不同。 |
| `closing / closed` | 关闭进行中／已关闭；closing 时保留清理跟踪，不能提前删除私有资源记录。 |

来源：[modules/sandboxes/lifecycle.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts)。

## Run

| 状态 | 解释 |
| - | - |
| `queued` | 已持久接受，尚未执行，不代表创建资源成功。 |
| `provisioning` | 准备计算、镜像或 Runtime，构建等待不是另一条 Run。 |
| `running` | 执行中，结合事件观察活动。 |
| `waiting_authorization` | 账户授权需要处理；查询绑定连接及 Tool call。 |
| `waiting_approval` | 审批或 Tool 结果未知需要处理；先查询审批和 Tool call，再选择操作。 |
| `cancelling` | 取消正在收敛，已发出的外部操作可能仍返回。 |
| `completed / failed / cancelled` | Run 终态；completed 也不等于 Session 已关闭。 |

来源：[modules/execution/runs.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/runs.ts)。

## Runtime binding

| 状态 | 解释 |
| - | - |
| `reserved / preparing / starting` | 控制平面的 Runtime 绑定准备与启动阶段。 |
| `ready` | 绑定就绪，不代表永远在线或每个任务成功。 |
| `restoring / restoring_preparing / restoring_starting` | 文件系统恢复后的 Runtime 准备过程。 |
| `unreachable` | 无法确认可达，保留恢复，不直接判定资源丢失。 |
| `interrupted` | 执行中断，需调查 workspace 与副作用，不盲目重启。 |

来源：[modules/execution/worker.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/worker.ts)。

## Sandbox 资源

| 状态 | 解释 |
| - | - |
| `provider-derived state` | 连接器返回的字符串，不是跨 Provider 封闭枚举；running、paused 等需结合连接器语义。 |
| `confirmed absence / unknown` | inspect 的 null 是确认不存在；认证、网络失败不能转换为 null。 |

来源：[modules/sandboxes/connector.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/connector.ts)。

## 资源操作

| 状态 | 解释 |
| - | - |
| `pending` | 持久操作意图，不证明远程接受。 |
| `completed` | 该操作完成；create 完成不代表任务或删除完成。 |
| `unknown` | 远程结果未确定，需按原操作与回执对账。 |
| `rejected` | 明确拒绝分配或镜像构建失败；不能普遍推断远程资源不存在。 |
| `deleted` | 镜像准备或 checkpoint 资源已记录清理；需结合操作 kind 理解。删除操作本身完成时使用 `completed`。 |
| `review_state: automatic / needs_review / acknowledged` | 独立审查轴；acknowledged 不会把 unknown 变成 completed。 |

来源：[modules/sandboxes/operations.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/operations.ts)。

## 转换与观察

正常 Run 由 queued → provisioning → running → completed。失败、授权、审批、取消与 worker 恢复会产生其他分支；这不是只能顺序前进的 UI 进度条。`run.claimed` 描述 worker 领取及 generation，不是一个名为 claimed 的 Run 状态。`run.recovery_needed` 可以在保留当前状态时写入恢复错误，不是新终态。

Runtime 进程调用还有自己的 starting、running、cancelling、exited、cancelled、failed、interrupted 状态，见 [Runtime](https://github.com/NexusFox88/docs/blob/main/resources/runtime/server.py)。exited 只表示进程退出，worker 仍需解析结果并导出产物，不能直接映射为 Run completed。数据库 Runtime binding 与该调用状态也不是同一个字段。

## 转换条件与分对象状态示例

以下示例分别摘取不同对象的字段，不是一个组合 API 响应，也不是真实执行记录。判断下一步动作时应读取当前记录。

| 对象 / 示例 | 触发条件 | 后续状态或动作 |
| - | - | - |
| Session `{"state":"open","pause_scope":null}` | 暂停要求没有活动 Run，也没有 pending/unknown 的创建操作；Sandbox 范围还要求能力支持 | `pausing` → `paused`；先查看 `pause_scope`，再判断计算资源是否暂停 |
| Session `{"state":"paused","pause_scope":"sandbox"}` | 恢复遵循已保存的 scope；原生暂停／恢复需要先确认结果 | `resuming` → `open`；恢复后的 Runtime binding 仍需准备才能执行 |
| Session `{"state":"closing"}` | 显式关闭拒绝活动 Run；未确认的创建、checkpoint 或清理可能延迟关闭 | 生命周期清理完成前保持 `closing`，之后为 `closed`；保留操作回执 |
| Run `{"state":"queued"}` | 执行前取消 | 直接进入 `cancelled`，不要求经过 `cancelling` |
| Run `{"state":"running"}` | 取消活动的非终态 Run | `cancelling` → `cancelled` 或 `failed`；已经派发的副作用仍需调查 |
| Run `{"state":"waiting_approval"}` | 匹配的审批或未知 Tool 结果必须通过对应处理器解决 | 可以回到 `running`；审批决定与结果对账是不同操作 |
| Runtime binding `{"state":"restoring"}` | worker 准备并启动恢复后的 binding | `restoring_preparing` → `restoring_starting` → `ready`；失败不证明 Sandbox 不存在 |
| Runtime binding `{"state":"unreachable"}` | 恢复流程检查原 Runtime | 确认重连可恢复 `ready`；不要仅因连接失败就分配替代资源 |
| 资源操作 `{"kind":"image_prepare","state":"rejected"}` | 镜像检查返回构建失败 | 保留构建／模板句柄；后续镜像清理可以将状态设为 `deleted` |
| 资源操作 `{"state":"unknown","review_state":"acknowledged"}` | 操作者已确认知悉不确定结果 | 结果仍是 `unknown`；确认知悉不是远程结果确认 |

普通 Run 路径为 `queued → provisioning → running → completed`。worker 的转换方法还允许 queued、provisioning、running、两种等待状态及 cancelling 进入 failed。授权、审批和 Tool 处理器另有等待／恢复转换，不能把 worker 的转换表当作完整状态机。取消已终态或已在 cancelling 的 Run 时保留原状态。

暂停／恢复已经处于匹配的目标状态时直接返回，不启动另一次转换；暂停 scope 不同则冲突。同 scope 的未完成转换进入对账路径。原生暂停／恢复结果不确定时，控制平面检查原资源，不盲目重复远程操作。Provider 管理的自动待机与显式暂停计算资源也需要分别判断。

到期清理与显式关闭不同：它可以先隔离活动 Run 的执行权、使待定审批过期，并记录带有 `reason: sandbox_expired` 的 `run.cancelling`，再完成资源清理。因此，关闭按钮与到期 worker 的前置条件并不相同。

`session.pausing`、`session.paused`、`session.resuming`、`session.resumed` 持久化在独立的内部 `session_lifecycle_events` 表中。它们不是下文 Run 事件 API 承诺提供的事件。观察生命周期操作时，应刷新 Session 记录。

来源：[Session 生命周期](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts)、[Run 转换与取消](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/runs.ts)、[Runtime worker](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/worker.ts)、[镜像准备与清理](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/image-preparation.ts)、[Tool broker](https://github.com/NexusFox88/docs/blob/main/resources/modules/tools/broker.ts)。

## 事件 envelope 与游标

```json theme={null}
{"id":"42","type":"run.queued","data":{"session_id":"00000000-0000-0000-0000-000000000001"},"created_at":"2026-11-19T00:00:00Z"}
```

这是脱敏格式示例，不是实测日志。JSON events 查询返回 `{events:[...]}`，每条包含 id、type、data、created\_at；SSE 在 id/event/data 字段传递事件，SDK 解析结果不附加数据库 created\_at 字段。SSE 片段：

```text theme={null}
id: 42
event: run.queued
data: {"session_id":"00000000-0000-0000-0000-000000000001"}

```

游标是数据库 sequence 的数字字符串，按 Run 查询递增但不保证连续，也不是 Runtime cursor。事件持久化后才推送。JSON 查询每页最多 500 条；SSE `after` 优先于 Last-Event-ID，默认 0。应用按 Run/id 去重，在同一事务保存事件和游标。只在收到数据后更新游标不足以保证应用持久化。

每约 15 秒可能收到无数据的 keepalive 注释。终态且事件排空后发送 `stream.end`，payload 为 `{state: ...}`，没有 id，不是持久事件。客户端断开只停止观察，不取消 Run。空页不证明终态，流结束后查询 Run。实现见 [HTTP SSE](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts)与 [Runs](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/runs.ts)。

## 主要事件及 payload

| 事件 | payload 字段或含义 |
| - | - |
| `run.queued` | `session_id` |
| `run.claimed` | `generation, recovery` |
| `run.provisioning / run.running` | `transition data (often {})` |
| `run.completed` | `final assistant output` |
| `run.failed` | `failure details including code` |
| `run.cancelling / run.cancelled` | `{} or lifecycle reason; expiry cleanup can include resource_cleanup` |
| `run.recovery_needed` | `generation and diagnostic fields` |
| `runtime.reconnected` | `{}` |
| `sandbox.image_building` | `{}` |
| `workspace.inputs_verified` | `session_id, files (path, sha256, size)` |
| `authorization.required` | `connection_id`；需要账户授权，不是操作审批 |
| `tool.outcome_unknown` | `call_id`；核实原外部请求的结果 |
| `agent.initialized` | `schema_version, digest, harness, context_delivery, files, session_id, agent_id, agent_revision`；context\_delivery 为 `none`、`initial_input` 或 `native_history` |
| `approval.required` | `id, action` |
| `approval.decided` | `id, approved` |
| `artifact.created` | `id, name, sha256, size` |
| `authorization.denied` | `call_id, source: caller, outcome: authorization_denied` |
| `tool.outcome_resolved` | `call_id, outcome, evidence, source: caller_verified` |
| `tool.completed` | `call_id; additional fields depend on direct/caller-verified/denied path` |
| `tool.result_after_cancellation` | `call_id, outcome` |

字段由生成路径决定，不把示意列当作严格 JSON schema。Tool 事件来源：[broker](https://github.com/NexusFox88/docs/blob/main/resources/modules/tools/broker.ts)、[reconciliation](https://github.com/NexusFox88/docs/blob/main/resources/modules/tools/reconciliation.ts)；产物见 [artifacts](https://github.com/NexusFox88/docs/blob/main/resources/modules/artifacts/artifacts.ts)。`tool.outcome_unknown` 表示需要调查的外部结果，不等于新的审批请求；查询原 tool call 的 hash、策略和状态再操作。

## 模型与受保护 API 的传输事件

`model.response` 和 `protected_api.response` 记录与 Run 关联的授权访问所产生的认证传输事实。data 包含 `connection_id`、可为空的 HTTP `status`、`transport`（已知状态时为 `received`，否则为 `failed`），以及提供时的 `connection_version`。生成器不写入请求头、prompt 或响应正文。未绑定 Run ID 的公共访问授权不会产生此 Run 事件。

`status: 200` 只证明收到 HTTP 响应，不证明模型完成任务或 Tool 写入成功。`status: null` 则保留远程结果的不确定性。这些事件不同于 ToolBroker 的 `tool.completed`，也不同于最终 `run.completed`。依据：[ConnectionAccess.recordModelOutcome](https://github.com/NexusFox88/docs/blob/main/resources/modules/access/access.ts)。

## Runtime 与派生活动事件

Runtime ingest 用来源键去重保存事件，再可能从 `harness.stdout` 派生一条规范化活动事件。新增事件有独立的持久事件 ID，不代表第二个 Runtime cursor。这些是可观察的进程与输出记录，不是模型私有推理。

| 事件 | payload／解释 |
| - | - |
| `runtime.interrupted` | 启动时发现被中断调用：`{"reason":"supervisor_restarted"}` |
| `harness.starting` | `{}`；进程启动意图 |
| `harness.failed` | 启动失败：`{"code":"harness_start_failed"}` |
| `harness.running` | `{"pid":123}`；进程 ID 示例，不是 Run ID |
| `harness.stdout`／`harness.stderr` | `{"text":"..."}`；脱敏输出片段，可能包含特定 Harness 的 JSON |
| `harness.exited` | `exit_code, state`；Runtime 终止，不证明 Run 结果解析与导出成功 |
| `agent.activity.started`／`agent.activity.completed` | `kind`，以及可选的 `name`、`id`、`is_error`；规范化 kind 包括 `tool`、`command_execution`、`mcp_tool_call`、`file_change` |
| `agent.message`／`agent.message.delta` | `text`；可见消息或文本增量，不是权威的 Run 最终输出 |

[活动投影函数](https://github.com/NexusFox88/docs/blob/main/resources/modules/harnesses/activity.ts)只接受完整、以换行结尾且不超过 65536 个 JavaScript code units 的 JSON 字符串。它识别选定的 OpenClaw、item 类和 tool/text 事件结构，不会规范化任意输出或全部 Harness。名称截断为 256、ID 为 512、消息文本为 32768 个单位。没有规范化活动不等于没有执行工作。不要无条件拼接 `agent.message` 和 `agent.message.delta`，也不要用它们覆盖 Run 的权威输出。

来源 envelope 由 [Runtime](https://github.com/NexusFox88/docs/blob/main/resources/runtime/server.py)生成；`text` 内的原生 JSON 仍与 Harness 版本有关。安全保留未知记录，解释时查询对应 Harness 契约。本节示例用于说明源码定义的 payload，不是实际任务日志。

## 根据关联记录选择操作

| 观察到的情况 | 接着查询 | 应用动作 |
| - | - | - |
| `waiting_authorization` 与 `authorization.required` | Connection 和原 Tool call | 完成或明确拒绝账户授权 |
| `waiting_approval` 且存在 pending 审批 | 审批 `id`、action 和调用参数 | 对这一次具体操作征求决定 |
| `waiting_approval` 与 `tool.outcome_unknown` | Tool call 的 `unknown` 状态、请求哈希、原执行策略和外部证据 | 核实原结果并进行结果对账；不创建替代审批，不盲目重新派发 |
| `approval.decided` 或 `tool.completed` | 当前 Run 和关联调用 | 刷新状态；这些路径可能恢复 `running`，却不产生 `run.running` 事件 |
| `harness.exited` | 当前 Run 和产物列表 | 继续观察直到控制平面确定 Run 结果 |
| `run.completed` 但 Session 仍 open | 结果、产物和 Session 生命周期 | 允许下一轮或关闭；任务成功不证明资源已删除 |

例如，`{"type":"tool.outcome_unknown","data":{"call_id":"example-call"}}` 应引导界面进入调查，它没有审批 ID。而 `{"type":"approval.required","data":{"id":"example-approval","action":{"summary":"illustrative operation"}}}` 指向一个决策记录，`action` 的结构取决于生成路径。这些是 payload 示意，不是 UUID 合法、可直接重放的请求。

事件描述已经发生的事；判断当前可执行动作需要查询对象现状。broker 和决策处理器在部分路径直接更新 Run 状态，因此不能只去掉事件名称的 `run.` 前缀来推算当前状态。

## 消费端要求

对未知事件类型保留或忽略展示，不崩溃，不凭它制造状态转换；按实际 payload 判别，不无条件读取字段。Tool completed 可能携带错误结果或代表拒绝后的交付，不能直接当成副作用成功。caller\_verified 是人工核实结论，不是服务端再次访问 Provider 的证明。

重连原 Run，别重新提交；结果未知先对账。分别展示 Run 终态、Session 状态、连接可达性与清理状态，避免一个绿色成功标签掩盖未知资源。

恢复模型见[持久事件](https://docs.hexagon.autos/zh-CN/concepts/events-and-recovery.md)，运维检查见[可观测性](https://docs.hexagon.autos/zh-CN/operate/observability.md)。SDK 事件解析实现分别位于 [Python](https://github.com/NexusFox88/docs/blob/main/resources/sdk/python/hexagon/__init__.py) 与 [TypeScript](https://github.com/NexusFox88/docs/blob/main/resources/sdk/typescript/index.ts)。

## 按事件列出的 payload 示例

以下示例按源码结构覆盖前文当前固定事件类别，包括无编号的传输结束标记。每行只展示 `data`，不是完整 envelope。ID、摘要、时间和内容都是示意；全零哈希是占位符，不是字节完整性回执。这些行不构成一次按时间排序的执行记录。转换 data 为空是合法情况；恢复诊断、审批 action 和原生输出可能包含路径特定的其他字段。仍需安全处理未来或 Provider 特定的未知事件。

| 事件 | 示意 `data` |
| - | - |
| `run.queued` | `{"session_id":"00000000-0000-4000-8000-000000000001"}` |
| `run.claimed` | `{"generation":2,"recovery":true}` |
| `run.provisioning` | `{}` |
| `run.running` | `{}` |
| `run.completed` | `{"role":"assistant","text":"Example result","artifacts":[]}` |
| `run.failed` | `{"code":"runtime_interrupted","runtime_state":"interrupted"}` |
| `run.cancelling` | `{}` |
| `run.cancelled` | `{"reason":"sandbox_expired","resource_cleanup":"confirmed"}` |
| `run.recovery_needed` | `{"generation":2}` |
| `runtime.reconnected` | `{}` |
| `runtime.interrupted` | `{"reason":"supervisor_restarted"}` |
| `sandbox.image_building` | `{}` |
| `workspace.inputs_verified` | `{"session_id":"00000000-0000-4000-8000-000000000001","files":[{"path":"notes.txt","sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":5}]}` |
| `agent.initialized` | `{"schema_version":1,"digest":"0000000000000000000000000000000000000000000000000000000000000000","harness":{"id":"pi","version":"1.5.2"},"context_delivery":"none","files":[],"session_id":"00000000-0000-4000-8000-000000000001","agent_id":null,"agent_revision":null}` |
| `approval.required` | `{"id":"00000000-0000-4000-8000-000000000001","action":{"summary":"Illustrative action"}}` |
| `approval.decided` | `{"id":"00000000-0000-4000-8000-000000000001","approved":false}` |
| `authorization.required` | `{"connection_id":"00000000-0000-4000-8000-000000000001"}` |
| `authorization.denied` | `{"call_id":"00000000-0000-4000-8000-000000000001","source":"caller","outcome":"authorization_denied"}` |
| `tool.outcome_unknown` | `{"call_id":"00000000-0000-4000-8000-000000000001"}` |
| `tool.outcome_resolved` | `{"call_id":"00000000-0000-4000-8000-000000000001","outcome":"failed","evidence":"Checked original external record","source":"caller_verified"}` |
| `tool.completed` | `{"call_id":"00000000-0000-4000-8000-000000000001"}` |
| `tool.result_after_cancellation` | `{"call_id":"00000000-0000-4000-8000-000000000001","outcome":"unknown"}` |
| `artifact.created` | `{"id":"00000000-0000-4000-8000-000000000001","name":"report.txt","sha256":"0000000000000000000000000000000000000000000000000000000000000000","size":5}` |
| `model.response` | `{"connection_id":"00000000-0000-4000-8000-000000000001","status":200,"transport":"received","connection_version":1}` |
| `protected_api.response` | `{"connection_id":"00000000-0000-4000-8000-000000000001","status":null,"transport":"failed","connection_version":1}` |
| `harness.starting` | `{}` |
| `harness.failed` | `{"code":"harness_start_failed"}` |
| `harness.running` | `{"pid":123}` |
| `harness.stdout` | `{"text":"Example visible output\n"}` |
| `harness.stderr` | `{"text":"Example diagnostic\n"}` |
| `harness.exited` | `{"exit_code":0,"state":"exited"}` |
| `agent.activity.started` | `{"kind":"command_execution","id":"example-command"}` |
| `agent.activity.completed` | `{"kind":"tool","name":"example","is_error":true}` |
| `agent.message` | `{"text":"Example visible message"}` |
| `agent.message.delta` | `{"text":"Example fragment"}` |
| `stream.end` | `{"state":"completed"}` |

## 事件发出边界与开放的事件类型

上方固定 payload 示例覆盖 35 个持久事件名称，以及单独的 `stream.end` 传输标记。这是当前源码清单，不是封闭的事件类型枚举：`Runs.ingest` 按 Runtime 提供的 `type` 保存记录，共享 Runtime 契约也可能演进。未知事件类型必须能安全保存或忽略，不能由新名称推导一个新的 Run 状态。

| 发出边界 | 名称与 payload 的来源 |
| - | - |
| Run 领域 | `Runs.submit`、`claim`、`advance`、`cancel`、审批与恢复方法；`advance` 仅在允许的转换中展开 `run.${state}` |
| 准备与到期 | 输入校验、镜像构建等待、初始化；生命周期到期发出包含清理信息的 cancelling / cancelled |
| Tool broker 与对账 | 授权、审批、未知 / 已核对结果与完成；取消期间可能把等待事件替换为 `tool.result_after_cancellation` |
| 受保护访问 | `ConnectionAccess.recordModelOutcome` 选择 `model.response` 或 `protected_api.response`，不发出提示词或响应体 |
| 产物捕获 | `Artifacts.capture` 仅在插入产物记录时发出事件 |
| Runtime supervisor | 启动、stdout / stderr、退出与重启中断；输出事件名称由对应流名展开 |
| 活动投影 | `harnessActivity` 从指定 stdout JSON 形状派生有界的可见活动 / 消息事件 |
| SSE 传输 | Run 为终态且持久事件已读尽时生成 `stream.end`，不插入事件表 |

Session 生命周期事件另存在一张表中，不因此成为 Run 流的一部分。事件发出位置必须与直接状态更新一起审阅：审批、拒绝授权或完成 Tool 调用都可能改变 Run 状态，而没有对应的 `run.running` 事件。

## 每个状态值的最小样例

每个单元格中都是相互独立的示意投影，不是某个同时包含多个候选状态的响应；省略了必要标识和其他字段。结合上文转换条件阅读，不能把样例当成强制设置状态的命令。

| 对象 / 字段 | 示意投影 | 来源 |
| - | - | - |
| Session / `state` | `{"state":"open"}`\<br/>`{"state":"pausing"}`\<br/>`{"state":"paused"}`\<br/>`{"state":"resuming"}`\<br/>`{"state":"closing"}`\<br/>`{"state":"closed"}` | [modules/sandboxes/lifecycle.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts) |
| Run / `state` | `{"state":"queued"}`\<br/>`{"state":"provisioning"}`\<br/>`{"state":"running"}`\<br/>`{"state":"waiting_authorization"}`\<br/>`{"state":"waiting_approval"}`\<br/>`{"state":"cancelling"}`\<br/>`{"state":"completed"}`\<br/>`{"state":"failed"}`\<br/>`{"state":"cancelled"}` | [modules/execution/runs.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/runs.ts) |
| Runtime binding / `state` | `{"state":"reserved"}`\<br/>`{"state":"preparing"}`\<br/>`{"state":"starting"}`\<br/>`{"state":"ready"}`\<br/>`{"state":"restoring"}`\<br/>`{"state":"restoring_preparing"}`\<br/>`{"state":"restoring_starting"}`\<br/>`{"state":"unreachable"}`\<br/>`{"state":"interrupted"}` | [modules/execution/worker.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/worker.ts) |
| Resource operation / `state` | `{"state":"pending"}`\<br/>`{"state":"completed"}`\<br/>`{"state":"unknown"}`\<br/>`{"state":"rejected"}`\<br/>`{"state":"deleted"}` | [modules/sandboxes/image-preparation.ts](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/image-preparation.ts) |
| Resource operation review / `review_state` | `{"review_state":"automatic"}`\<br/>`{"review_state":"needs_review"}`\<br/>`{"review_state":"acknowledged"}` | [modules/storage/013-resource-review.sql](https://github.com/NexusFox88/docs/blob/main/resources/modules/storage/013-resource-review.sql) |
| Runtime invocation / `state` | `{"state":"starting"}`\<br/>`{"state":"running"}`\<br/>`{"state":"cancelling"}`\<br/>`{"state":"exited"}`\<br/>`{"state":"cancelled"}`\<br/>`{"state":"failed"}`\<br/>`{"state":"interrupted"}` | [runtime/server.py](https://github.com/NexusFox88/docs/blob/main/resources/runtime/server.py) |

Sandbox 状态仍是开放的 Provider 字符串。还需区分控制平面的一个投影：Session 成功关闭时，若此前有 Sandbox 对象，保存的对象会写入 `{"state":"destroyed"}`。这是保留的生命周期投影，不是新获取的 Provider inspect 响应，也不是所有供应商的统一枚举。连接器的 `inspect(id) === null` 另表示缺失结果，不是一个 `state` 等于 null 的资源。参见[关闭逻辑](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts)。

## 生命周期动作是有条件的转换

同一种 Session 状态可能对应不同计算策略。需结合 `pause_scope`、声明能力和持久操作回执判断。以下说明动作前提与观察规则，不是可代替服务端校验的客户端状态机。

| 动作与来源 | 远程操作之前 | 确认结果或保留的不确定性 |
| - | - | - |
| `scope: session` 暂停 | 拒绝 closing / closed，要求没有活动 Run 与 pending / unknown 创建操作；先保存 `pausing` 和 scope | 记录 `paused`，但不宣称计算已暂停，也不能当作停止计费。 |
| 原生 Sandbox 暂停 | 要求 `pause_resume` 与对应连接器方法；首次远程调用前保存意图 | 查询原资源是否为 `paused`；资源缺失是 `sandbox_lost`，其他状态保留 `session_transition_pending`。 |
| 原生 Sandbox 恢复 | 从 `paused` 开始或继续 `resuming`，沿用已保存 scope | 首次调用 resume，恢复路径可使用 `reconcileResume`，然后查询同一资源是否为 `running`；不通过分配替代资源来消除不确定性。 |
| Provider 自动待机 | 声明的 `automatic_standby` 选择独立策略 | Session 可以进入 `paused`，但 Hexagon 没有因此执行原生暂停，也不证明 Provider 已停止计算。分别看 `provider_managed_standby` 与 `compute_paused`。 |
| 快照暂停 / 恢复 | 先保存 checkpoint / restore 操作及原句柄 | 使用已保存 checkpoint；恢复响应丢失时，只采用原操作的唯一匹配。零匹配或多个匹配保留 `unknown`，不新发恢复请求。 |
| 重复请求目标状态 | 暂停时已为 `paused`，恢复时已为 `open` | 返回当前目标状态，不重复远程动作；请求不同 pause scope 会冲突。相反方向的进行中转换返回 `session_transition_pending`。 |
| Sandbox 恢复收尾 | 原生或 Provider 自动待机恢复达到生命周期目标 | Session 变为 `open`；非 interrupted 的 Runtime binding 变为 `restoring`，下一次 invocation 前仍需准备 Runtime。interrupted binding 不会被静默修复。 |

依据：[changePause](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts)、[checkpointTransition](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/checkpoints.ts)、[worker 准备流程](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/worker.ts)。

## 审阅状态不等于操作结果已确认

只有当前为 `unknown` 的操作接受以下审阅动作。审阅历史与调度修改先持久化，再按需执行对账。HTTP 成功响应仍可能包含 `reconciliation_error`；读取返回的操作结果，不能把状态码当作清理回执。

| 审阅动作 | review\_state 变化 | 触发的工作 |
| - | - | - |
| `acknowledge` | `acknowledged`，清空下一次检查时间 | 记录人工关注并暂停自动审阅，不确认远程成功或资源缺失 |
| `reopen` | `automatic`，安排立即检查 | 返回自动处理；这个动作本身不直接调用生命周期对账分支 |
| `reconcile` | `automatic`，安排立即检查 | 按当前 Session / 操作立即分发：closing 或 delete → close；checkpoint → Sandbox pause；restore → resume；其他类型 → provision |

即使 Session 仍处于 closing，`completed`、`rejected` 或 `deleted` 的操作也不会因此变得可审阅。找到实际未决操作，并保留其私有标识。依据：[ResourceOperations.review](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/operations.ts)；操作流程见[资源对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)。

## 默认值与参数化状态写入

新记录的初始值分别为 Session `open`、Run `queued`、Runtime binding `reserved`、资源操作 `pending`；操作审阅初始值为 `automatic`。依据是[初始 schema](https://github.com/NexusFox88/docs/blob/main/resources/modules/storage/001-initial.sql)、[Runtime binding schema](https://github.com/NexusFox88/docs/blob/main/resources/modules/storage/004-runtime-bindings.sql)与[审阅 schema](https://github.com/NexusFox88/docs/blob/main/resources/modules/storage/013-resource-review.sql)。大部分生命周期状态列是 text，不是数据库强制约束的枚举；本页描述当前实现会写入的值。客户端需能容纳未来值，但不能自行推导转换。

| 参数化写入 | 值与控制条件 |
| - | - |
| `Runs.advance` | `provisioning`、`running`、`completed`、`failed`、`cancelled`，受显式转换表与有效 lease 限制 |
| `Runs.cancel` | queued 时写 `cancelled`，其他活动状态写 `cancelling`；终态或已 cancelling 返回不变 |
| `ToolBroker.wait` | 当前调用位置只传入 `waiting_authorization` 或 `waiting_approval`，不覆盖 cancelling |
| `changePause` 中间 / 目标状态 | `pausing` / `paused` 或 `resuming` / `open`，由动作与校验过的 scope 决定 |
| worker 准备 | 根据原 binding 状态选择 `preparing` 或 `restoring_preparing`，然后选择 `starting` 或 `restoring_starting` |
| 镜像检查 | `ready` 映射为操作 `completed`，`failed` 映射为 `rejected`，构建中保持 `pending` |
| 审阅调度 | `acknowledged` 保持已确认关注，多次未知尝试可转为 `needs_review`，否则 automatic；显式审阅动作见上表 |

关闭对账与采用资源继续执行的条件不同。provision / restore 需要唯一匹配；close 可以将原操作的多个精确匹配保存在 `reconciled_ids`，并尝试清理这些归属明确的资源，零匹配仍保留创建未确认。在这一清理对账过程中将原 create 操作标记 `completed`，不证明 Agent invocation 成功，也不代表独立的 delete 操作已经完成。依据：[closeSession](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts)。

[状态写入源码清单](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-state-write-sites.json)记录了当前非测试 TypeScript 应用 / 模块 / 集成中，这四张表的 45 处插入或状态更新查询；动态查询表达式另列供审阅。这证明源码覆盖范围，不代表所有转换都已在数据库或 Provider 上实际执行。

下一步：[事件流指南](https://docs.hexagon.autos/zh-CN/build/stream-events.md)、[恢复](https://docs.hexagon.autos/zh-CN/build/recovery.md)、[对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.