Polite-msg: load-bearing report-backs can still silently dead-letter (box_not_empty), + no way to clear the graveyard

[dotdevdotdev]

Context — what surfaced

agentwire doctor now reports dead-lettered report-backs sitting in session inboxes (~/.agentwire/inbox/<session>/dead/). At time of writing: 48 corpses across 6 recipients (agentwire 27, fragmentz 15, orchestrator 2, agentwire-dev 2, playchek 1, documentscribe 1), 47 of them kind: done report-backs + 1 note, spanning 06-20 → 06-28.

Root-cause finding (investigated)

The acute bug is already fixed by #524, and these corpses are a pre-fix graveyard that #524's own new doctor-surfacing exposed for the first time:

• The target_busy exemption in inbox._bump_attempts (a busy/generating orchestrator whose input box can't be parsed → message stays pending forever, never dead-letters, surfaced via doctor/watch) was added in fix(sessions): never-clobber report-back delivery + doctor/watch surfacing (#523) #524 (cc26288).
• All 48 corpses predate fix(sessions): never-clobber report-back delivery + doctor/watch surfacing (#523) #524's merge (merged 2026-06-28 09:38 UTC; newest corpse died 08:02 UTC). Zero have appeared since the fix.
• Reason distribution: 47 box_not_empty, 1 pre-schema (no reason). Zero target_busy (as expected — that path no longer dead-letters).
• Confirmed the running install carries the fix.

So: not a live regression. But the investigation exposes two real residuals.

Residual A — box_not_empty still silently dead-letters load-bearing kinds

inbox._bump_attempts: when the box is parseable but non-empty (box_not_empty), attempts increment and the message dead-letters after MAX_ATTEMPTS = 40 (~40 min at the ~60s drain tick). For a note that's fine. For a done/escalation report-back it's a silent loss — surfaced only by doctor / msg dead (pull), never pushed. 47/48 corpses were done, so the reliability impact was real pre-fix and the path still exists.

box_not_empty fires when the recipient's input box holds text for 40 consecutive minutes — a genuine human draft (correct to defer, don't clobber) or a Claude Code queued-input placeholder (see Residual B).

Options:

1. On dead-letter of a load-bearing kind (done/request/escalation), escalate to the human out-of-band (email/quo/desktop toast) instead of silently dropping to dead/. The drop becomes non-silent at the human level.
2. Deliver at the turn boundary: the idle/Notification hook already fires when a session goes idle (empty box) — drain the inbox on that event so report-backs land at the next safe moment rather than racing a 60s poll against a busy box.
3. Keep box_not_empty pending-forever like target_busy only when it's not a genuine human draft (see B), so a load-bearing message is never aged out by transient box occupancy.

(The #524 review already called escalation-into-the-pane an "accepted tradeoff" — this is the inverse: escalate out of the pane to the human, no clobber.)

Residual B — queued-input placeholder may be misread as a human draft

prompt_router.prompt_is_empty is conservative: any non-empty box content → defer. Its docstring explicitly calls out the Claude Code "Press up to edit queued messages" placeholder as a non-empty case. That placeholder is not a human draft — clobber risk is nil — yet it's classified box_not_empty and burns attempts toward dead-letter. If a recipient sits with queued input for 40 min, a report-back dies for no good reason. Consider detecting that placeholder and treating it like target_busy (keep pending, don't penalize) rather than like a human draft.

Residual C — no way to clear the graveyard

doctor surfaces dead-letters but there's no command to purge them, so stale pre-fix corpses accumulate visibly forever. Add agentwire msg dead --purge [-s <session>] [--older-than <dur>] (MCP msg_dead purge flag), and/or auto-age-out corpses older than N days. (The current 48 are all pre-#524 and obsolete — a one-time clear is needed regardless.)

Pointers

• agentwire/inbox.py — _bump_attempts (the target_busy vs box_not_empty split), MAX_ATTEMPTS, flush_session
• agentwire/prompt_router.py — prompt_is_empty, input_box_content, safe_deliver
• agentwire/msg_cli.py — dead subcommand (list only, no purge)
• History: Worktree report-back dead-letters against a busy orchestrator — finished workers never trigger review #523 (silent dead-letter), fix(sessions): never-clobber report-back delivery + doctor/watch surfacing (#523) #524 (cc26288 — the fix that exempted target_busy + added doctor/watch surfacing)

Built by dotdev.dev

[dotdevdotdev]

A + B implemented → PR #547 (C — msg dead --purge — shipped in #545, so #547 closes this).

Residual A (escalate on dead-letter): chose option 1 — out-of-band email to the owner. On dead-letter of a load-bearing kind (done/request/escalation), inbox._escalate_dead_letter sends a branded Resend email (shared owner-escalation wiring, same as usage-limit parking) with sender→recipient, last defer reason, and the message text. note/ingest are not escalated. Best-effort — a send failure logs dead_letter_escalate_failed and never breaks the drain; the corpse still lands in dead/.

Residual B (queued placeholder): chose option 3 — treat the placeholder like target_busy (keep pending, don't penalize). Key design call: the fix lives at the penalty layer, not the collision detector. New prompt_router.is_queued_placeholder (loose match) routes a "…queued messages" box to a new no-penalty reason queued_placeholder in _bump_attempts. input_box_content/prompt_is_empty are unchanged, so a non-empty box is still never pasted into — no-clobber guarantee intact, existing test_queued_placeholder_treated_as_content stays green. If Claude Code rewords the placeholder, a non-match degrades to today's safe behavior (penalize), never to delivery.

Schemas/contracts locked in:

• inbox._NO_PENALTY_REASONS = {"target_busy", "queued_placeholder"} — the defer reasons that don't bump attempts.
• inbox.ESCALATE_KINDS = ("done", "request", "escalation") — load-bearing kinds emailed on dead-letter.
• New events: dead_letter_escalated (ok=bool), dead_letter_escalate_failed (error). Deferred-with-placeholder logs reason queued_placeholder.

Verified: tests/unit 2058 + tests/integration 84 pass, ruff clean. Live smoke after rebuild: installed package carries the symbols, doctor green (Resend key set), limits tick drains clean (exit 0), portal restarted healthy (HTTP 200). The 48 pre-#524 corpses were already purged last session, so the graveyard is empty.