# Inbox `watch` Test Plan

## Scope

This document covers blocking thread-activity wait behavior via `inbox watch`.

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

## case: watch-wakes-on-matching-thread

### 用例意义

验证 `watch` 在新匹配线程到达时会被唤醒，并返回线程、消息与事件信息。

### 前置条件

- `worker-d` 当前没有匹配 `pending` 线程
- `watch` 先于 `send` 启动

### 输入

```bash
inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 2
inbox --db TMPDIR/coord.db --json send --from leader --to worker-d --subject "Build admin editor" --summary "Create the first editor screen"
```

### 预期输出

- `watch` 退出码为 `0`
- `watch.data.woke == true`
- 返回 `thread`、`message`、`event`

### 断言结论

- `watch` 唤醒结果不仅说明“醒了”，还提供触发该唤醒的具体事件上下文

## case: watch-respects-status-filter

### 用例意义

验证 `watch --status` 只会对匹配状态的后续事件唤醒。

### 前置条件

- 存在一个会被推进到 `blocked` 的线程 `THREAD_ID`
- `watch` 以 `--status blocked` 先启动

### 输入

```bash
inbox --db TMPDIR/coord.db --json watch --agent worker-c --status blocked --timeout-seconds 2
inbox --db TMPDIR/coord.db --json update --agent worker-c --thread THREAD_ID --status blocked --summary "Need policy decision"
```

### 预期输出

- `watch` 只在线程进入 `blocked` 后返回
- 返回的 `thread.status == "blocked"`

### 断言结论

- `watch` 的状态过滤作用在“事件发生后的线程状态”上

## case: watch-times-out-with-no-activity

### 用例意义

验证在超时时间内没有匹配活动时，`watch` 返回稳定超时契约。

### 前置条件

- 没有新匹配事件会发生

### 输入

```bash
inbox --db TMPDIR/coord.db --json watch --agent worker-d --status pending --timeout-seconds 1
```

### 预期输出

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

### 断言结论

- `watch` 超时被归类为“无匹配工作”，而不是内部错误

## Notes

- 未传 `--after-event` 时，`watch` 默认从“当前时刻之后”开始等待，不会回放既有事件