feat(bus): mail-model inbox — unread/read, keep-unread wait, reply-to, 500-char cap

[rr0hit]

What

Mail-model enhancements to the flow message bus. All changes are additive and non-breaking — flow inbox pop and every existing verb/flag keep their exact current behavior. Bundles the pop-only API groundwork with the new inbox surface.

Message bus (code)

• flow inbox --all — list everything still retained (read + unread), each with id + status, not just unread.
• flow inbox read <id> — show/ack a specific message out of pop's oldest-first order (works for already-consumed messages too — displays without re-mutating).
• flow inbox pop --wait --keep-unread — reader/relay wake primitive: returns the message but does not ack it (claims the row delivered so a loop won't re-return it, but leaves a human-directed message unanswered/immortal so a forwarder can pass it along). Plain pop --wait is unchanged.
• flow message <addr> "..." --reply-to <id> — stamp a parent id so a routed reply carries lineage; the receiver sees ↳ in reply to [id]: <snippet>. Validated at send time.
• Mail nomenclature (unread / read) in human output and --json (mail field). New reply_to column migrated idempotently on open; sweep retention widened so an unacked human message is immortal like pending.
• Body cap raised 200 → 500 (non-breaking — a larger limit; short messages unaffected).

Skill

• references/messaging.md + SKILL.md §4.18 rewritten: mail nomenclature, two Monitor recipes (consumer pop --wait vs reader/relay pop --wait --keep-unread), two-purpose framing (reach-out-to-user / peer-collab), niche/escalate content trimmed.
• Auto-mode guidance: headless flow do --auto agents should post regular progress via flow message user/flow broadcast, not only when blocked.

Vanishing-message bug — investigated, RESOLVED (not a durability bug)

Both reported ids survived in the DB as acked. Root cause: the sending session's own UserPromptSubmit hook auto-acks its outbound human-directed messages and raced the out-of-band Telegram relay. The --keep-unread reader primitive is the fix — the relay claims the row delivered (which the pending-only prompt-hook ack can no longer touch) and acks it by id only after the human answers.

Verification

make test green. All six enhancements exercised end-to-end in an isolated sandbox (22/22 assertions pass): inbox --all, read <id> (out-of-order ack + already-read), pop --keep-unread (wakes without acking, loop-safe, contrasted against acking pop), --reply-to (lineage shown + invalid-id rejected), 500-char cap (500 accepted / 501 rejected / 300 accepted), and mail nomenclature.

🤖 Generated with Claude Code

[anshulsao]

LGTM. Build/vet/tests pass locally; the retention-predicate refactor (shared busRollable) and the widened atomic ack guard are clean.

Three low-severity non-blockers noted (fix at leisure):

1. busSnippet slices the body by byte offset — can split a multi-byte rune now that the cap is 500 chars; use runes.
2. PreToolUse matcher is an allowlist (Bash|Edit|Write|...), but the docstrings say "every tool" — MCP/TodoWrite calls won't surface a mid-turn stop; align docs or widen matcher.
3. Dropping migrateBusKindBroadcast leaves legacy kind='post' rows stranded (immortal under the new retention predicate) on very old DBs.