Overseer: opt-in better LLM fallback for missing AGENT_NOTIFY_SUMMARY

[heavygee]

Summary

v1 hub fallback (Piece 2 / PR #87) synthesizes a Session Log-only progress event from the first non-empty assistant line when extractNotifySummary returns null. That is good as a blind-turn backstop but not as useful as a real AGENT_NOTIFY_SUMMARY self-report.

This issue tracks the opt-in better fallback (prefer Option A: raw OpenAI-compatible completions / responses call). Design lives in docs/plans/2026-07-24-overseer-summary-emission.md section "Better fallback".

Design constraints (operator-resolved — do not re-litigate)

1. Default OFF. Explicit settings/env toggle. Never surprise usage.
2. Rarity gate before recommending enable: measure emit vs hub-synthesized miss rate after Pieces 1–3 are live. Target well under ~5% of turns needing fallback (5% is already generous). Rarity is the cost control.
3. When it runs, full turn content. No input-char truncation that would make the summary worse than a primary agent emit. Accuracy must match primary usefulness.
4. Transparency: provenance must clearly mark hub-LLM (or oneshot-agent) synthesis — never pretend the primary agent said it. Session Log / inbox labels must be obvious ("fallback LLM summary" class copy).
5. Option A first (OpenAI-compatible /v1/chat/completions and/or /v1/responses behind one adapter). Option B (out-of-band oneshot agent) is a later alternative if A is insufficient.
6. Fork-only. Never upstream. No user-turn prepend (fix(cli): skill_lookup $name instruction prepended to Cursor user turns triggers prompt-injection false positive tiann/hapi#1095/fix(cli): stop skill_lookup $name user-turn prepend (prompt-injection FP) tiann/hapi#1096).

Acceptance

• Config surface (env and/or hub settings): base URL, API key, model, enable flag (default false)
• Adapter supports Chat Completions + Responses (or documented subset with local-gateway note)
• Wired into overseerEventRecorder path only when extractNotifySummary is null and better-fallback is enabled
• Full last-turn assistant plain text is the prompt input (no quality-degrading char cap)
• Empty turns still skip; failures fall through to existing heuristic fallback
• Provenance + payload fields distinguish primary / heuristic / llm-fallback
• Tests for adapter + recorder branch; typecheck green
• Docs: how to enable, cost warning, rarity gate reminder
• Soup layer stacked after flavors (feat(overseer): non-Cursor session-summary contract + debug relative dates #88) when ready

Related

• Design: docs/plans/2026-07-24-overseer-summary-emission.md
• PR feat(overseer): emit AGENT_NOTIFY_SUMMARY from Cursor (Half B, piece 1) #86 Cursor overlay, feat(overseer): deterministic per-turn fallback when no summary line (Half B, piece 2) #87 heuristic fallback, feat(overseer): non-Cursor session-summary contract + debug relative dates #88 non-Cursor systemPrompt
• Remaining flavor coverage: Overseer: wire AGENT_NOTIFY_SUMMARY emission for kimi / pi / remaining ACP #89 (kimi/pi/ACP)
• Voice subscriber only speaks real AGENT_NOTIFY_SUMMARY — LLM fallback events stay Session Log unless/until we deliberately promote (default: attn=0 like heuristic)

Non-goals (this issue)

• Enabling by default
• Speaking LLM fallbacks via hapi-voice-subscriber
• Option B oneshot agent spawn

[heavygee]

Peer spawned to implement this: HAPI session 82af1ef4-2ffd-44a1-94ee-8951e64a5c08 (Peer: overseer LLM fallback (#90)), worktree ~/coding/hapi/worktrees/overseer-llm-fallback @ feat/overseer-llm-fallback (stacked on flavors #88). Design: docs/plans/2026-07-24-overseer-summary-emission.md.

[heavygee]

Implemented in #91 (stacked on #88). Default OFF.

[heavygee]

Orchestrator ack: PR #91 looks stacked correctly on flavors (#88). Soup placement requested from meta (after emit → heuristic fallback → flavors → this LLM fallback layer). Reminder: leave HAPI_OVERSEER_LLM_FALLBACK off until miss-rate gate after Pieces 1–3 are live.