Spec: Human Inbox unread, personal attention and actions #126

Parent and design authority

• Feature Project: https://github.com/orgs/BotHarness/projects/9. Historical parent [Retired] Post-M4: Messaging / Bot Inbox / Orchestrator / Assignments #30 is retired. This issue is the current specification/index; implementation is tracked by native children Tracer: Human Inbox Group unread summary and deliberate read #546–Tracer: Human Inbox handled history and action triage order #553.
• ADR-0071 and ADR-0098 define the Human Inbox boundary. Tracer: Activity Center Overview shows Bot status and active Sessions #541 owns Activity Center Overview; Tracer: Human @所有 Bot mentions current Group members #542 owns the Human-only @所有 Bot composer shortcut.
• The next executable slice is local-Human Group unread summary, exact source navigation, and deliberate read advancement. Later stories below are delivered as narrow follow-on slices after that path is validated.

Problem Statement

When several PersonaBots work across several Channels, the Human must inspect each conversation separately to learn what is unread, where they were mentioned, and which live requests need an answer. The current Human Inbox already lists several action and informational projections, while Bot attention and Wake Policy now deliver Bot work independently. It does not yet give the Human a reliable cross-Channel IM-style unread view or let the Human answer every live request in one place. This makes a busy Group hard to triage and can make Bot requests wait behind ordinary traffic.

Solution

The personal Human Inbox inside Activity Center brings together unresolved explicit Human actions, mentions and replies, other unread Channel activity, informational updates, and handled history. It projects the owning Channel, Source Event, request, Assignment, and Human read-position facts. A busy Group contributes one expandable Channel summary, with exact source navigation and a count of distinct unread messages; concrete message viewing or an explicit mark-read action advances the canonical Human read position. Live action cards can later be answered in the Inbox with the same authorized operation used at their source, or opened there. The entry shows unread message count and a separate unresolved-action indicator. Existing Bot Inbox Admission, attention, and Wake Policy behavior remains the PersonaBot path.

User Stories

1. As the local Human, I want one Activity Center entry across my PersonaBots and Channels, so that I can triage work without visiting each Bot DM or Group first.
2. As the local Human, I want the entry badge to count my distinct unread Channel messages, so that it reflects the volume of content I have not seen.
3. As the local Human, I want a separate pending-action indicator, so that a request remains visible even after I read its message.
4. As the local Human, I want ordinary unread, mentions/replies, and explicit actions shown separately, so that I can choose between catching up and unblocking work.
5. As the local Human, I want a busy Group's unread messages folded into one Channel summary, so that forty messages do not create forty Inbox rows.
6. As the local Human, I want that summary to show the Channel, unread count, and latest activity, so that I can decide where to read first.
7. As the local Human, I want opening the summary to preserve unread state, so that scanning several summaries does not falsely imply that I read their messages.
8. As the local Human, I want opening a specific message to land at that exact Channel position, so that I can see its real surrounding conversation.
9. As the local Human, I want only concrete messages that I actually view to advance my read position, so that later unseen messages remain unread.
10. As the local Human, I want an explicit mark-read control to advance only through the chosen message or captured summary endpoint, so that concurrently arriving messages remain unread.
11. As the local Human, I want my own sends excluded from unread, so that composing a message does not increase my badge.
12. As the local Human, I want one Source Event counted once even if it mentions several Bots or is also a report or action card, so that counts and lists are trustworthy.
13. As the local Human, I want distinct questions from separate Bots to remain distinct action cards, so that each Bot can receive its own answer.
14. As the local Human, I want my Channel membership and visibility boundary honored, so that I do not see unread content outside my authorized conversation history.
15. As the local Human, I want unread state restored after Host restart, so that reopening the app does not make old messages appear new or read.
16. As the local Human, I want changes from another open window to refresh the same Inbox and badge, so that the views do not disagree about my read state.
17. As the local Human, I want Human/Bot messages that explicitly mention me or directly reply to me in a separate list, so that personal attention is easy to find.
18. As the local Human, I want a mention or reply to link to its exact Source Event, so that I can answer with full Channel context.
19. As the local Human, I want a message that is both a mention and unread to appear once in Human Channel attention, so that categories do not duplicate its content.
20. As the local Human, I want actions sorted by longest waiting first, so that old unanswered requests do not sink below new traffic.
21. As the local Human, I want mentions and unread summaries sorted by recent activity, so that I can catch up with active Channels quickly.
22. As the local Human, I want Bot and Channel filters and stable pagination, so that large multi-Bot lists remain navigable while new messages arrive.
23. As the local Human, I want a live question card to show its exact question, choices or input, and short expandable context, so that I can respond without losing the source meaning.
24. As the local Human, I want to answer a live question or decide an approval in the Inbox, so that many concurrent Bot requests can be handled from one place.
25. As the local Human, I want the card's Open source action as well, so that I can read the complete conversation before deciding.
26. As the local Human, I want a stale or already answered card rejected and refreshed, so that two windows or responders cannot submit conflicting decisions.
27. As the local Human, I want a resolved card removed from active actions and retained in searchable handled history with links to the original request and answer, so that I can audit my decisions.
28. As the local Human, I want a Bot DM completion report that is unread to appear once with a report label, so that information is not duplicated across lists.
29. As the local Human, I want an informational report with no Channel placement to remain an update, so that it does not inflate unread-message totals.
30. As the local Human, I want Bot Inbox events without a Human decision or unread Channel message to stay in the Bot Inbox, so that the Human Inbox remains a personal triage view.
31. As a future additional Human, I want my read position and eligible action projection keyed by my identity, so that another Human's reading or answering does not silently mark my messages read.
32. As an eligible Human for a Group-answerable request, I want the first valid answer to resolve the shared request across personal views, so that another person cannot answer a request that has already been settled.
33. As the local Human, I want existing Group join and Workspace Grant cards to keep their authorized decisions and exact source links, so that the broader Inbox does not weaken current action handling.
34. As the local Human, I want waiting or blocked Assignment cards to remain linked to their owning Bot and Session, so that I can inspect the actual work before replying.
35. As the local Human, I want a needs-repair card to retain its Bot Inbox fallback when its Channel source is gone, so that I still have a path to diagnose the failure.
36. As the local Human, I want an informational completion report to remain dismissible without being treated as an unresolved blocker, so that finished work does not inflate my action count.
37. As the local Human, I want repeated notifications about one still-live causal request coalesced into one updated card, so that retries do not multiply my workload.
38. As the local Human, I want a request that escalates in severity to update its existing card rather than vanish behind an older summary, so that the most urgent current state remains visible.
39. As the local Human, I want source and tool details shown only through their existing authorization checks, so that Inbox convenience does not expose information I could not open at the source.

Implementation Decisions

• Extend the existing Human attention query/projection at the Host seam. Keep Channel Source Events and placements, Channel membership/read positions, live request facts, and Assignment facts in their owning modules; do not create a second Inbox content store or a new Bot attention authority.
• The first tracer projects one unread summary per Group Channel for the current local Human. Derive unread from committed, Human-visible Channel placements beyond that Human's canonical read position, excluding the Human's own sends. Count distinct Source Events once, including those that also carry report, mention, or action roles.
• Read advancement uses the existing Channel mark-read operation. Opening or expanding an Inbox summary is read-only. Exact source navigation uses the existing Channel timeline-around path; the existing concrete-message visibility behavior may advance read position. An explicit mark-read command targets a specific committed message, not an unbounded “latest” value after concurrent arrivals.
• Extend the existing Host↔Client Bridge/RPC contract at the Human Inbox query surface for summaries, counts, and source anchors. Reuse existing read-position and mark-read RPC operations. Client state drops stale filtered/page responses when scope changes, as it does today.
• The entry badge is a count of distinct unread Human Channel Source Events across accessible Group and Bot DM Channels. Show an independent indicator when unresolved explicit Human actions exist. Overview's action count has the same explicit-action definition but is owned by Tracer: Activity Center Overview shows Bot status and active Sessions #541.
• After the first tracer, represent mentions/replies with trusted Human target identity and exact Source Event links. Current ChannelMention only targets PersonaBots, so an untrusted text @name is insufficient. Native Channels have no stable sub-Thread conversation identity, so Group unread groups by Channel only.
• After the first tracer, route inline answer/decision/reply through the same authorized owning commands as the source card. Revalidate live request state on submit. Handled history references canonical request/answer facts rather than copying their content.
• Keep action-required strictly for unresolved typed Human work: live question, approval, Group join or Workspace Grant decision, waiting/blocked Assignment, and repair or future typed causes that genuinely need Human action. Mentions and ordinary unread alone do not become actions.
• Preserve existing causal coalescing, severity escalation, Group/Grant decisions, Assignment Session navigation, repair fallbacks, report dismissal, and source-detail authorization while adding new lists. Stable action identity follows the owning request or work item, not the number of notices it emitted.
• The current product still has one local Human. Identity-keyed read facts preserve the model for multiple Humans later, but this spec does not add accounts or shared group-response UI now.
• Deliver in order: Group unread summary/navigation/read → Human mention/reply targeting → inline live actions and handled history. Validate the first complete Host-to-Client path with the Human before expanding sibling behavior.

Testing Decisions

• Test externally observable facts and interactions, not SQL statement shape or component internals. The highest existing seam is the Human Inbox Host query with the real Channel authority; the Client seam is the existing Bridge actions and rendered Inbox/navigation flow.
• At the Host query seam, verify count and grouping from real committed placements, source dedup across several Bot Admissions and report/action roles, own-send exclusion, membership visibility, monotonic identity-keyed read positions, restart, and a message arriving between summary capture and explicit mark-read.
• At the Bridge seam, verify an authorized Human obtains the summary and exact source anchor, marks a concrete message read, and sees the count change. Invalid or foreign Channel/message targets fail without changing read state.
• At the Client seam, verify a Group summary stays unread when expanded; exact navigation shows the intended message, visible content advances read state, filters and pagination do not apply stale responses, and unread badge/action indicator remain independent.
• For later slices, verify mention/reply target authenticity and one human-facing item per Source Event; verify native inline actions share source authorization, reject stale requests, and retain handled navigation.
• Regress the existing Group join, Grant, Assignment waiting/blocked, needs-repair, and informational report paths, especially causal updates and fallback navigation; new unread behavior must not reclassify them as ordinary unread-only items.
• Use existing Channel read-position/receipt tests, Human Inbox query and refresh tests, and Client source-navigation tests as prior art. Finish the first slice with a runnable DSH path: accumulate Group messages from several Bots, open Activity Center, inspect the summary, navigate to a concrete message, mark read, restart, and confirm counts.

Out of Scope

• Activity Center Overview charts, live Session cards, token usage, and Memory trends (Tracer: Activity Center Overview shows Bot status and active Sessions #541).
• Human @所有 Bot input and its per-Bot Admissions (Tracer: Human @所有 Bot mentions current Group members #542).
• Bot Inbox event timeline, PersonaBot attention preferences, and Wake Policy changes.
• Native Channel sub-Threads; Thread grouping begins only after a stable Thread identity and navigation exist.
• Multiple Human account management or Bot-authored all-member mentions.
• A new Channel-level token allocation, copied Source Event bodies, or a second durable Inbox store.

Further Notes

• The confirmed high-traffic example has forty Group unread messages including two mentions, plus four distinct live action cards from Bot DMs. Activity Center shows the deduplicated unread badge and separate action signal; Inbox shows one Group summary, precise mention links, and four oldest-first action cards. Viewing only the summary leaves all forty unread. Overview and the all-Bot composer shortcut are separate tickets.
• Existing wake/attention delivery is a Bot concern. Human unread reflects what the Human actually saw, regardless of whether any Bot was awakened by the same Source Event.