# Inbox `fetch` Test Plan

## Scope

This document covers agent-scoped candidate thread retrieval via `inbox fetch`.

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

## case: fetch-returns-pending-thread-for-target-agent

### 用例意义

验证 `fetch` 能按目标执行者拉取待处理线程。

### 前置条件

- `leader` 已向 `worker-a` 发送至少一个 `pending` 线程

### 输入

```bash
inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending
```

### 预期输出

- 命令退出码为 `0`
- 返回 `data.threads`
- 至少包含一个 `assigned_to == "worker-a"` 且 `status == "pending"` 的线程

### 断言结论

- `fetch` 默认是执行者视角的候选工作列表，不是全局线程扫描

## case: fetch-respects-status-and-limit-filters

### 用例意义

验证 `fetch` 同时遵守状态过滤与返回上限。

### 前置条件

- `worker-a` 拥有多个不同状态的线程
- 其中至少两个线程满足目标状态过滤条件

### 输入

```bash
inbox --db TMPDIR/coord.db --json fetch --agent worker-a --status pending,blocked --limit 1
```

### 预期输出

- 命令退出码为 `0`
- 返回线程数不超过 `1`
- 返回的每条线程都满足 `status in ["pending","blocked"]`

### 断言结论

- `fetch` 的 `status` 与 `limit` 会同时生效
- 返回顺序按 `updated_at` 倒序，优先暴露最新线程

## case: fetch-unread-uses-read-cursor

### 用例意义

验证 `fetch --unread` 基于 agent 的 read cursor 计算未读，而不是仅按线程是否存在新消息。

### 前置条件

- `leader` 已向 `worker-e` 发送一个 `pending` 线程 `THREAD_ID`

### 输入

```bash
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
inbox --db TMPDIR/coord.db --agent worker-e --json show --thread THREAD_ID --mark-read
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
inbox --db TMPDIR/coord.db --json send --from leader --to worker-e --thread THREAD_ID --summary "Use sentence case" --body "Keep the nav labels in sentence case."
inbox --db TMPDIR/coord.db --json fetch --agent worker-e --status pending --unread
```

### 预期输出

- 第一次 `fetch --unread` 返回该线程
- `show --mark-read` 后，第二次 `fetch --unread` 无匹配结果
- 新消息追加后，第三次 `fetch --unread` 再次返回该线程

### 断言结论

- 未读判断依赖 `thread_reads.last_read_message_id`
- 新消息到达会让同线程重新进入未读结果集

## case: fetch-returns-no-matching-work-when-empty

### 用例意义

验证 `fetch` 在没有匹配线程时返回稳定的“无工作”错误契约。

### 前置条件

- 空数据库已完成 `init`

### 输入

```bash
inbox --db TMPDIR/coord.db --json fetch --agent worker-z --status pending
```

### 预期输出

- 退出码为 `10`
- JSON 错误码为 `no_matching_work`

### 断言结论

- 空结果不是成功空数组，而是显式的“无匹配工作”信号