# Inbox `update` Test Plan

## Scope

This document covers progress and blocked transitions via `inbox update`.

Shared conventions live in [../_shared/README.md](../_shared/README.md).

## case: update-moves-thread-to-in-progress

### 用例意义

验证租约拥有者可以把线程推进到 `in_progress`，并生成进度消息。

### 前置条件

- `worker-a` 已成功 `claim` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status in_progress --summary "Implementation started" --body "Scanning current HTTP client usage."
```

### 预期输出

- 命令退出码为 `0`
- `thread.status == "in_progress"`
- `message.kind == "progress"`
- `message.to_agent` 指向线程创建者

### 断言结论

- `update` 会把状态推进和消息追加合并为同一次事务

## case: update-moves-thread-to-blocked-with-payload

### 用例意义

验证 `update --status blocked` 会写入阻塞问题消息，并保留结构化 payload。

### 前置条件

- `worker-a` 已成功 `claim` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status blocked --summary "Need timeout decision" --payload-json '{"question":"Should retries apply to read timeouts?"}'
```

### 预期输出

- 命令退出码为 `0`
- `thread.status == "blocked"`
- `message.kind == "question"`
- `message.payload_json.question` 保存提问内容

### 断言结论

- `blocked` 更新会生成面向创建者的问题消息

## case: update-accepts-body-file-and-artifact

### 用例意义

验证 `update` 支持通过 `body-file` 与 artifact 发送结构化进度材料。

### 前置条件

- `worker-a` 已成功 `claim` 线程 `THREAD_ID`
- `TMPDIR/progress.md` 已存在

### 输入

```bash
inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status in_progress --summary "Implementation started" --body-file TMPDIR/progress.md --artifact TMPDIR/progress.md --artifact-kind note
inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
```

### 预期输出

- `update` 成功
- 对应消息 `body` 等于文件内容
- 对应消息包含 1 个 artifact，kind 为 `note`

### 断言结论

- `update` 的正文与 artifact 支持与 `send/reply/done/fail` 保持一致

## case: update-rejects-invalid-payload-json

### 用例意义

验证 `update` 对非法 `--payload-json` 输入返回稳定错误契约。

### 前置条件

- `worker-a` 已成功 `claim` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status blocked --summary "Need timeout decision" --payload-json not-json
```

### 预期输出

- 退出码为 `30`
- JSON 错误码为 `invalid_input`

### 断言结论

- 阻塞问题的 payload 需要满足合法 JSON 约束

## case: update-rejects-non-owner

### 用例意义

验证非租约拥有者不能更新线程状态。

### 前置条件

- `worker-a` 已成功 `claim` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json update --agent worker-b --thread THREAD_ID --status in_progress --summary "Implementation started"
```

### 预期输出

- 退出码为 `20`
- JSON 错误码为 `lease_conflict`

### 断言结论

- `update` 明确依赖活跃 lease 所属者