ai-workflow-skill/docs/tests/inbox/claim/README.md

Inbox claim Test Plan

Scope

This document covers lease acquisition via inbox claim.

Shared conventions live in ../_shared/README.md.

case: claim-acquires-thread-lease

用例意义

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

前置条件

• 已存在一个 pending 线程 THREAD_ID

输入

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

输入

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

输入

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

输入

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 存在

断言结论

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