Fleet Overseer architecture — umbrella

[heavygee]

Goal

Track the build of HAPI's fleet attention-arbitration layer (the "Overseer"): a single fleet-level conversational agent that reads a cross-session event stream, maintains a prioritized inbox of items needing operator judgement, surfaces them through a persistent voice conversation, and dispatches operator-confirmed edicts back into the worker fleet.

Spec

• docs/plans/2026-06-03-overseer-framing.md (concept, model, decision channel)
• docs/plans/2026-06-03-overseer-contracts.md (schemas + contracts §1-§4, §7, §8, §10-§15)
• docs/plans/2026-06-03-overseer-prioritization.md (§5 scoring loop, §6 replay harness, §9 attention budget, prior art)
• docs/plans/2026-06-03-overseer-build-sequence.md (Steps 1-6, MVP acceptance bar, risks by phase, PR slicing)
• docs/adr/0001-worker-facing-attribution-one-boss.md (one-boss principle ADR)

Child issues (build sequence)

Pre-flight:

• Pre-flight: emission-contract empirical sniff #20 — Emission-contract empirical sniff (blocks Step 2)

MVP steps (acceptance bar met when Step 4 lands):

• Step 1: Voice persistence + receiving-session indicator #21 — Step 1: Voice persistence + receiving-session indicator (parallel; not blocked by substrate)
• Step 2: Events table + worker emission #22 — Step 2: Events table + worker emission
• Step 2.5: Inbox substrate + v0 prioritizer #23 — Step 2.5: Inbox substrate + v0 prioritizer
• Step 2.75: Replay harness v0 + CI gate #24 — Step 2.75: Replay harness v0 + CI gate
• Step 3: Read-only Overseer wired to voice #25 — Step 3: Read-only Overseer wired to voice
• Step 4: Disagreement-capable Overseer + voice dispatch with confirm #26 — Step 4: Disagreement-capable Overseer + voice dispatch with confirm

Post-MVP:

• Step 5: Chrome-button move + per-session button retirement #27 — Step 5: Chrome-button move + per-session button retirement

Cross-cutting:

• Operator intent capture at fleet level (contracts §15) #28 — Operator intent capture at fleet level (contracts §15; absorbs UI: per-session scratchlist (held queue of unsent messages) #11 at fleet level)

Dependency graph

                      [umbrella: #19]
                            |
        +-------------------+-------------------+
        |                                       |
   [#20 emission sniff]                      (informs)
        |
        v
   [#22 events + emission]
        |
        v
   [#23 inbox + v0 prioritizer]
        |
        v
   [#24 replay harness + CI]
        |
        v
   +----+----+
   |         |
 [#21 voice  [#25 read-only
  persist]    Overseer + voice]
 (parallel        |
  to 22-24)        v
              [#26 dispatch + contradiction]
                   |
                   v
              [#27 chrome-button + retire per-session]

Step 1 (#21) is intentionally parallel to Steps 2-2.75: voice persistence is frontend/transport work that does not depend on the substrate.

Absorbed / reconciled existing issues

• App: project-level page with PR / issues panels + agent dispatcher (controlplane) #14 (project-page / controlplane) — adjacent controlplane UI; the Overseer IS the controlplane with voice as its native UI. Cross-referenced; its dashboard work lands around Steps 3-4.
• Controlplane: cross-session chat search + memory layer (Claude's pattern) #18 (cross-session memory) — becomes the Overseer's saved-filter views over the events table (substrate in Step 2: Events table + worker emission #22, query tools in Step 3: Read-only Overseer wired to voice #25).
• UI: per-session scratchlist (held queue of unsent messages) #11 (per-session scratchlist) — absorbed at fleet level by Operator intent capture at fleet level (contracts §15) #28 (contracts §15) after the v1 per-session model ships. Not superseded.
• Hub/MCP: channels support - inbound push from MCP servers into sessions #17 (channels) — external sources emit into events as source_kind=channel (contracts §10). Explicitly post-MVP.

Notes

This is the largest single architectural commitment in HAPI to date: weeks of work, not days. The build is sequenced dependency-first so each phase ships as a small, standalone-useful PR before the user-facing chrome shifts to depend on the substrate.