# Inbox `fail` Test Plan

## Scope

This document covers failure terminal completion via `inbox fail`.

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

## case: fail-marks-thread-failed

### 用例意义

验证租约拥有者可以把线程推进到 `failed` 终态，并生成失败结果消息。

### 前置条件

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

### 输入

```bash
inbox --db TMPDIR/coord.db --json fail --agent worker-b --thread THREAD_ID --summary "Migration failed" --body "The migration cannot proceed because the prior schema is inconsistent."
```

### 预期输出

- 命令退出码为 `0`
- `thread.status == "failed"`
- `message.kind == "result"`

### 断言结论

- `fail` 与 `done` 共享结果消息模型，但进入的是失败终态

## case: fail-persists-failure-body-and-artifact

### 用例意义

验证 `fail` 能持久化失败说明与附件。

### 前置条件

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

### 输入

```bash
inbox --db TMPDIR/coord.db --json fail --agent worker-b --thread THREAD_ID --summary "Migration failed" --body-file TMPDIR/failure.md --artifact TMPDIR/failure.md --artifact-kind report
inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
```

### 预期输出

- `fail` 成功
- 最终结果消息 `body` 等于文件内容
- 结果消息包含 1 个 `report` artifact

### 断言结论

- 失败终态同样要能完整交付排障材料

## case: fail-rejects-non-owner

### 用例意义

验证非租约拥有者不能把线程标记为失败。

### 前置条件

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

### 输入

```bash
inbox --db TMPDIR/coord.db --json fail --agent worker-x --thread THREAD_ID --summary "Migration failed"
```

### 预期输出

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

### 断言结论

- `fail` 与 `done` 一样受 lease owner 约束

## case: fail-rejects-on-terminal-thread

### 用例意义

验证已进入终态的线程不能再次执行 `fail`。

### 前置条件

- 线程 `THREAD_ID` 已经是 `done`、`failed` 或 `cancelled`

### 输入

```bash
inbox --db TMPDIR/coord.db --json fail --agent worker-b --thread THREAD_ID --summary "Migration failed"
```

### 预期输出

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

### 断言结论

- `fail` 对终态线程不会重复成功