Step 2.5: Inbox substrate + v0 prioritizer

[heavygee]

Goal

Land the inbox_items substrate, an event→inbox promotion job, a hand-tuned v0 priority scorer, dedupe/merge, and explain_priority provenance — the layer the read-only Overseer will consume.

Spec

• docs/plans/2026-06-03-overseer-build-sequence.md Step 2.5 (primary)
• docs/plans/2026-06-03-overseer-contracts.md §3 (inbox item model), §1 (attention_candidate promotion gate), §11 (provenance for Overseer speech)
• docs/plans/2026-06-03-overseer-prioritization.md §5 (scoring loop, v0 simplifications), "Foundational formulas (sketch)"
• Upstream alignment: in discussion Voice roadmap: picker -> provider abstraction -> local stack -> fleet command centre tiann/hapi#691 tiann named the control-plane attention events as "permission requests, blocked sessions, completions"; the public reply committed to "building the priority model (permission > blocked > completion) first." The v0 scorer defaults must encode exactly that ordering.

Acceptance

• Migration adds inbox_items table (per contracts §3) + a join/index path from events.id to inbox_items.source_event_ids.
• Event → inbox-candidate promotion job: walks new events, promotes those with attention_candidate = 1 per the taxonomy.
• v0 priority scorer: hand-tuned base_priority per event_type + linear aging. No salience learning; no per-operator weights (schema designed for them, not active).
• Base-priority ordering encodes permission_request/approval_requested > blocked > needs_decision > completed(with operator_action_required) > everything else — matching the maintainer's stated control-plane priority model (discussion Voice roadmap: picker -> provider abstraction -> local stack -> fleet command centre tiann/hapi#691). The ordering is config-driven so it can be tuned, but ships with this default.
• Merge / dedupe: same dedupe_key collapses repeated emissions into one inbox item, aggregating source_event_ids; event_links graph walked for root-cause merging (5 workers blocked_by the same upstream → one fleet-level inbox item).
• explain_priority(item_id) computes and stores the reason-for-priority string (event IDs, aging contribution, time-criticality bumps) at scoring time, so the Overseer recites the reasoning rather than reverse-engineering it.
• UI debug pane extended to show inbox state alongside the events viewer.

Out of scope

• Salience learning / per-operator weights (post-MVP; schema designed for it).
• Overseer entity, voice attachment, dispatch (Step 3: Read-only Overseer wired to voice #25, Step 4: Disagreement-capable Overseer + voice dispatch with confirm #26).
• Bounded-deferral mode auto-detection (modes are operator-set).

Dependencies

• Blocks: Step 2.75: Replay harness v0 + CI gate #24 (replay harness asserts against promotion + scoring), Step 3: Read-only Overseer wired to voice #25 (read-only Overseer queries the inbox)
• Blocked by: Step 2: Events table + worker emission #22 (events substrate)
• Part of: Fleet Overseer architecture — umbrella #19

Suggested PR breakdown

1-2 PRs: inbox schema migration; promotion job + v0 scorer; explain_priority.

Risks

• Filter quality has no obvious bootstrap: the salience model starts with zero feedback signal and the first weeks it will get prioritization wrong. Mitigations: conservative defaults (under-surface rather than over-surface), explicit operator feedback commands (prioritization §5), short-term human-curated category weights.