heartbeat session_mode:auto does not execute handoff-save path in real runs

[elliot245]

Problem

heartbeat with session_mode: auto is intended to persist a concise handoff before session rollover when context gets low. In real runs, that handoff-save path did not execute at all for the main agent.

This is separate from #111.

• Heartbeat auto mode can starve checks for hours due to repeated busy_skip preflight #111 focuses on repeated busy_skip starving heartbeat coverage.
• This issue focuses on the missing handoff-save / memory-persistence behavior in auto mode.

Evidence From Production History

Observed in main heartbeat audit from 2026-02-26 to 2026-03-16:

• session_mode=auto entries: 909
• send_status=ok: 492
• send_status=skip: 417
• entries with numeric context_left: 95
• entries with context_left < 25: 0

Additional evidence:

• there are no persisted handoff files for main under .claude/state/agent-manager/heartbeat-handoffs/main/
• so there is no production evidence that auto ever entered the handoff-save + rollover path

Why This Is A Bug

From the operator perspective, auto did not deliver its core promise: before rolling over, prompt the agent to save a concise memory/handoff.

In practice, the save-memory prompt never ran in real heartbeat history for the main agent.

That makes auto misleading operationally:

• config says auto
• operators expect low-context sessions to save a handoff before rollover
• real runs show no such handoff path was exercised

Likely Causes

There appear to be two separate problems:

1. The real heartbeat path rarely or never reaches the rollover condition.

   Current evidence suggests auto is dominated by:

   • preflight skips (busy_skip / pending_skip / active_skip), and/or
   • context detection that never reports <25%

2. Even when rollover does trigger, the implementation does not strictly wait for the explicit HEARTBEAT_HANDOFF_SAVED [HB_ID:...] acknowledgment.

   The current flow asks the agent to reply with that exact ack, but the gate is effectively:

   • wait until runtime becomes idle
   • inspect the handoff file content

   So it waits for file content, not for the explicit ack requested in the prompt.

Expected Behavior

For session_mode:auto:

• when context is low, the system should actually send the handoff-save prompt in real runs
• rollover should not proceed until the handoff is verifiably saved
• the verification should include the explicit HEARTBEAT_HANDOFF_SAVED [HB_ID:...] acknowledgment, not only a heuristic file-content check
• audit/trace should make this observable

Suggested Fix

1. Add observability for rollover path entry:

   • explicit audit event for handoff_prompt_sent
   • explicit audit event for handoff_saved
   • explicit audit event for rollover_started

2. Tighten handoff completion criteria:

   • require both handoff file saved and matching HEARTBEAT_HANDOFF_SAVED [HB_ID:...] ack before rollover

3. Revisit why auto never reached context<25% in real runs:

   • verify provider-specific context parsing for Codex
   • verify whether preflight skip starves rollover opportunity before handoff logic is reached

Acceptance Criteria

• production heartbeat history can show real auto runs entering the handoff-save path
• rollover no longer proceeds on file-content heuristic alone
• operators can tell from audit logs whether handoff prompt was sent, acknowledged, and saved
• documentation reflects the real semantics of auto