Dead-letters section and Requeue button (vikunja#557)

[TadMSTR]

Build agent-workflow-interop-2026-08 Phase 1. Pairs with task-queue-mcp#18 (v0.10.0), which owns the queue-side half and the operator-only POST /tasks/{id}/requeue route this calls.

Why

~/.claude/task-queue/dead-letters/ is written by task-dispatcher when a task exhausts its routing retries. Nothing could show it: the MCP's get_task answered not found, and this plugin globbed the queue root only.

Seventeen tasks sat there between 2026-05-29 and 2026-07-25 — every one a security audit request, all seventeen carrying the identical failed_reason — with no interface anywhere in the fleet able to display the number.

This does not fix the bug that produced them (vikunja#63/#169).

What

• GET /dead-letters — read-only, reading dead-letters/*.yml directly like every other read here. No new manifest permission, no new env var.
• panels/dead-letters.ts — the section.
• dead-letters.ts — record shaping and reason-grouping as pure, unit-tested functions.
• Requeue button → new requeue control action → the MCP's operator-only route.

Three decisions

• Collapsed, and a section rather than a tab. The healthy count is zero, so a tab would be permanently empty furniture and an always-open block a permanent scroll cost. What it must never be is absent: the heading renders whatever the count is, including none, and turns red the moment it is not.
• Grouped by failed_reason. Seventeen records with one identical reason are one bug that fired seventeen times. Seventeen sibling rows read as seventeen unrelated problems — roughly how they were treated for three months.
• The count loads on every refresh, not on expand. A number that only appears once the operator opens the section is a number nobody sees, which is the exact failure this surface exists to end.

Requeue is confirmed before firing, and the confirmation says the part that matters: it does not fix why the task was dropped, so if the cause is live it comes back.

A drift gate the invariant was missing

AGENTS.md says the ControlAction union, server.ts's route regex, and the MCP's custom routes are "three copies of one contract" — and nothing checked it. Adding an action to the union alone compiles; the failure mode is a button that 404s against the plugin's own backend. The two copies in this repo are now pinned to each other by a source-level test. Verified to fail in both directions (drop requeue from the regex → red; drop it from the union → red).

Handled edge cases

Case	Behaviour	Why
record has no id	skipped, not rendered	a row that cannot be addressed is a row whose Requeue button could not work
unparseable failure timestamp	renders —	ago() maps an invalid date to "just now", which would claim a three-month-old drop happened seconds ago
created is a Date	serialised, not string-coerced	js-yaml parses every real record's unquoted timestamp into a Date
task lands in dead-letters/	no WS event	fs.watch is not recursive on Linux; deliberate, and documented — the dispatcher's unlink from the queue root does fire

Verification

npm run build (tsc gate) clean; 85 tests pass. Ran dist/server.js against the live queue:

GET /dead-letters → 17 records
reasons: {"Invalid or missing build_name in payload: 'unknown'": 17}
agents:  {"security": 17}

Not yet deployed — needs ./deploy.sh && pm2 restart cloudcli after merge, and the paired task-queue-mcp container rebuild for the Requeue button's route to exist.

🤖 Generated with Claude Code