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

Inbox fail Test Plan

Scope

This document covers failure terminal completion via inbox fail.

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

case: fail-marks-thread-failed

用例意义

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

前置条件

• worker-b 已成功 claim 线程 THREAD_ID

输入

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

输入

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

输入

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

输入

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

预期输出

• 退出码为 30
• JSON 错误码为 invalid_state

断言结论

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