Step 2: Events table + worker emission

[heavygee]

Goal

Land the cross-session events substrate — events + event_links + FTS5 tables — and populate it via the prompted event-emission contract plus a hub-observed synthesis fallback. No Overseer yet; just the substrate.

Spec

• docs/plans/2026-06-03-overseer-build-sequence.md Step 2 (primary)
• docs/plans/2026-06-03-overseer-contracts.md §1 (worker event taxonomy, wire format, hub-observed fallback), the events / event_links / artifact_refs schemas, §2 (worker state model, for stale synthesis)
• Code refs: hub/src/store/messages.ts, hub/src/store/sessions.ts (store layer to model on); shared/src/modes.ts AGENT_FLAVORS

Acceptance

• Migration adds events table (incl. artifact_refs, operator_action_required, risk_detected, attention_candidate, dedupe_key, severity, confidence, provenance, idempotency_key) per the contracts schema.
• Migration adds event_links table (typed edges: spawned | blocks | blocked_by | supersedes | resolves | caused_by | duplicates) — from day one.
• FTS5 virtual table over summary + tags + payload_json.
• Worker event taxonomy implemented via the prompted event-emission contract (sentinel-delimited JSON blocks <!--HAPI_EVENTS_BEGIN--> / <!--HAPI_EVENTS_END-->, schema_version, required event_type + summary, defensive coercion/validation; malformed input writes a validation_error event with source_kind = system).
• completed enrichment honored: resolving flags (operator_action_required, artifact_refs, risk_detected, confidence) rather than completion subtypes.
• Hub-observed event synthesis layer: when prompt compliance fails (no completed despite finishing, no stale despite long silence, no tool_result despite an obvious tool call), the hub synthesizes the event from observable signals with source_kind = system and provenance noting the inferred signal.
• Read-only events viewer in the UI debug pane to confirm shape and density.
• attention_candidate defaults to 0 (safe default: unknown event types do not push the operator).

Out of scope

• Inbox promotion / prioritization (Step 2.5: Inbox substrate + v0 prioritizer #23).
• Any Overseer entity, voice routing, or dispatch (Step 3: Read-only Overseer wired to voice #25, Step 4: Disagreement-capable Overseer + voice dispatch with confirm #26).
• Channel sources (source_kind=channel) — post-MVP (Hub/MCP: channels support - inbound push from MCP servers into sessions #17).

Dependencies

• Blocks: Step 2.5: Inbox substrate + v0 prioritizer #23 (inbox substrate consumes the events table)
• Blocked by: Pre-flight: emission-contract empirical sniff #20 (emission-contract sniff calibrates emission vs. hub-observed scope)
• Part of: Fleet Overseer architecture — umbrella #19

Suggested PR breakdown

1-2 PRs: events schema migration; worker prompted-emission contract + wire format; hub-observed fallback (could split if migration and fallback land separately).

Risks

• The events table is the new load-bearing wall: schema wrong, retrofit painful; schema right, every future feature plugs in for free. The migration deserves specific review attention. Add event_links from day one — retrofitting typed dependency edges into a populated events table is much more painful than getting them in early.
• Prompted event-emission is best-effort; workers will sometimes fail to emit. The hub-observed fallback is essential and must be built alongside the taxonomy, not later — otherwise the substrate has silent holes the Overseer cannot reason about.

[heavygee]

Taxonomy alignment with maintainer's control-plane priority model (discussion tiann#691)

The maintainer named "permission requests" as a first-class control-plane attention event (priority model: permission > blocked > completion). HAPI has a native permission-prompt flow (an agent requesting operator approval to run a tool/command). This step should:

• Map HAPI's native permission-prompt to a taxonomy event — either a dedicated permission_request event_type or an explicit binding onto approval_requested — with attention_candidate = 1 and high default severity.
• Ensure the hub-observed fallback can synthesize the permission event from the permission-prompt mechanism even if the worker doesn't emit it via the prompted contract (permission prompts are hub-observable by nature).

The base-priority ordering itself is encoded downstream in #23's v0 scorer.