# Inbox `claim` Test Plan

## Scope

This document covers lease acquisition via `inbox claim`.

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

## case: claim-acquires-thread-lease

### 用例意义

验证 `claim` 可以把 `pending` 线程切换到 `claimed`，并生成租约事件消息。

### 前置条件

- 已存在一个 `pending` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID --lease-seconds 300
```

### 预期输出

- 命令退出码为 `0`
- `thread.status == "claimed"`
- `thread.assigned_to == "worker-a"`
- `message.kind == "event"`
- `message.summary == "thread claimed"`

### 断言结论

- `claim` 同时更新线程状态与活跃租约
- 成功领取会附带一条事件消息，而不是静默改状态

## case: claim-rejects-when-thread-missing

### 用例意义

验证 `claim` 对不存在的线程返回稳定的 not-found 错误契约。

### 前置条件

- 空数据库已完成 `init`

### 输入

```bash
inbox --db TMPDIR/coord.db --json claim --agent worker-z --thread thr_missing
```

### 预期输出

- 退出码为 `40`
- JSON 错误码为 `not_found`

### 断言结论

- 缺失线程会被明确区分为引用错误，而不是 lease 冲突

## case: claim-rejects-when-thread-already-claimed

### 用例意义

验证同一线程在已有活跃租约时，其他执行者无法重复领取。

### 前置条件

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

### 输入

```bash
inbox --db TMPDIR/coord.db --json claim --agent worker-y --thread THREAD_ID
```

### 预期输出

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

### 断言结论

- 活跃 lease 是 `claim` 的排他条件

## case: claim-records-requested-lease-duration

### 用例意义

验证 `claim --lease-seconds` 的请求值会进入事件消息 payload，便于后续审计。

### 前置条件

- 已存在一个 `pending` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID --lease-seconds 300
```

### 预期输出

- 命令退出码为 `0`
- `message.payload_json.lease_seconds == 300`
- `message.payload_json.lease_token` 存在

### 断言结论

- 请求的租约时长不是仅用于内部计算，也会被持久化到事件消息中