Document Codex heartbeat-vs-A2A wake validation

Context

Operator-observed Codex wake behavior on 2026-06-15 sharpened #13287 into a differential validation problem: pure heartbeat wakes appear to submit/start a Codex turn, while actionable A2A message wakes may land in the Codex prompt surface without submitting when the operator is AFK.

#13291 is the close-target leaf for PR #13290's generic L2 submit-boundary pinning. This ticket is narrower: document the controlled validation protocol that #13287 needs before a future runtime fix can claim live L4 Codex delivery.

The Problem

The current wake prompt landing matrix states that adapter success is not enough and that Codex payloads must land in the prompt surface. That is necessary but not precise enough for the regression observed in #13287: the failure may only appear when comparing pure heartbeat, direct A2A message, and mixed message+heartbeat digests on the same active Codex route.

Without an explicit differential protocol, a later PR can pass backend tests, cite a green adapter log, and still overclaim the unresolved live boundary: prompt insertion is not proof that Codex submitted the text and started a turn.

The Architectural Reality

V-B-A anchors checked before filing:

• ai/docs/wake-prompt-landing-matrix.md is the existing authority for wake prompt landing proof and already warns that adapter success is not sufficient.
• ai/daemons/wake/daemon.mjs#buildWakeDigest() builds different observable digest shapes for messages and heartbeats; pure heartbeat carries the lifecycle directive while message-bearing digests do not.
• ai/daemons/wake/daemon.mjs#deliverDigest() selects the adapter from subscription metadata, not from event type, so the current evidence points to payload/focus/submit behavior rather than two explicit adapters.
• Live @neo-gpt route evidence from #13287 shows active bridge-daemon Codex metadata with no explicit adapter field, so the immediate validation must include the default macOS bridge path.

Duplicate sweep:

• Live latest-open sweep checked the latest 20 open issues at 2026-06-15T02:54:52Z. Adjacent issues found: #13291 (generic submit boundary close-target for PR #13290), #13287 (live L4 behavior), #13283 (add_memory WAL/graph), but no equivalent differential-protocol leaf.
• Live GitHub search for Codex heartbeat A2A submission differential wake matrix returned no equivalent open issue.
• A2A all-status sweep checked the recent wake/submit/matrix/#13287 message set immediately before creation; it found Ada's #13287 evidence notes and ack, but no competing [lane-claim] or [lane-intent] for this docs leaf.
• Local exact sweep across resources/content/** and ai/docs/** found #13137 as the heartbeat-only directive precedent and #13287/#13291 as adjacent scope, not this protocol leaf.
• KB semantic sweep was attempted twice during intake but the OpenAI-compatible synthesis/query path timed out after 15s while KB health itself reported healthy; this ticket therefore relies on live GitHub/local-source evidence and stays docs-only.

The Fix

Update ai/docs/wake-prompt-landing-matrix.md with a Codex-specific heartbeat-vs-A2A submission differential section that requires controlled validation of:

1. pure heartbeat digest;
2. direct A2A message digest;
3. mixed message + heartbeat digest.

Each scenario must record backend adapter intent separately from live Codex prompt landing and submit/start-turn evidence.

Contract Ledger

Decision Record impact

None. This is a documentation/protocol leaf under the existing Agent Harness wake substrate; it does not amend an ADR.

Acceptance Criteria

• ai/docs/wake-prompt-landing-matrix.md contains a Codex heartbeat-vs-A2A differential section covering pure heartbeat, direct A2A message, and mixed message+heartbeat scenarios.
• The section distinguishes backend adapter assertions from live Codex assertions.
• The section requires the live evidence artifact to record subscription id, adapter metadata, payload scenario, prompt landing, submit/start-turn result, and whether human Enter was required.
• The PR body closes this leaf only and keeps #13287 open for the live L4 behavior.

Out of Scope

• Changing wake daemon runtime behavior.
• Claiming Codex live submit/start-turn behavior is fixed.
• Replacing #13291's generic submit-boundary tests/matrix slice.

Avoided Traps

• Do not close #13287 from this docs-only PR. #13287 remains the live L4 behavior ticket.
• Do not duplicate #13291. #13291 is already tied to PR #13290's generic boundary pin; this leaf is the differential validation protocol for the remaining live regression.
• Do not infer a different adapter. Current V-B-A shows the active route selects by subscription metadata, not event type.

Related

Related: #13287 Related: #13291 Parent epic: #13012

Origin Session ID: 019ec8a7-1f8e-75a3-b223-fe59cc444776

Retrieval Hint: "Codex heartbeat direct A2A mixed wake validation matrix prompt submit start turn #13287"