---
id: 10408
title: Wake-trigger sub-variant for AGENTS.md §22 mailbox-check (Interrupt vs Polling)
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees: []
createdAt: '2026-04-27T08:13:05Z'
updatedAt: '2026-04-27T10:09:21Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10408'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-27T10:09:21Z'
---
# Wake-trigger sub-variant for AGENTS.md §22 mailbox-check (Interrupt vs Polling)

### Context
With the rollout of the Phase 3 Wake Substrate, agents now receive `[WAKE]` events injected into their harnesses when A2A messages (`SENT_TO_ME`) or task state changes occur. The `[WAKE]` message typically includes a count (e.g., "1 new message").

### The Problem
If multiple wake events queue up in the harness (because the agent was busy processing a previous turn), treating the wake text as exhaustive inbox state breaks idempotency. The agent might receive three separate `[WAKE]` inputs sequentially, when in reality there is only one message that needs processing (or three messages that were all processed on the first wake). This leads to redundant processing loops or "phantom wakes".

### The Architectural Reality
Wake injection acts as a hardware **interrupt**—it signals "something happened, wake up and check." It is NOT the canonical state. The inbox (`list_messages`) is the canonical state. Furthermore, a `mark_read` protocol is necessary to close the loop, but executing `mark_read` immediately upon reading breaks future-session inbox visibility (if an agent wants to find a thread to hand off). Therefore, we adopted Option B: "Explicit-at-session-sunset only".

### The Fix
Codify the "A2A Interrupt vs. Polling Protocol" in `AGENTS.md` and the `session-sunset` skill. 
1. `AGENTS.md` §22 extension: Mandate that agents treat `[WAKE]` as an interrupt, poll for truth via `list_messages({status: 'unread'})`, and use internal context/history to deduplicate in-session processing. The count in the wake text is informational only.
2. `.agent/skills/session-sunset/SKILL.md`: Mandate that agents call `mark_read` on all processed messages during the session sunset sequence, ensuring the inbox is clean for the next session while preserving visibility during the current session.

### Acceptance Criteria
- `AGENTS.md` is updated with a §22 sub-variant explicitly defining the Interrupt vs Polling protocol.
- `.agent/skills/session-sunset/SKILL.md` is updated to include `mark_read` inbox cleanup as a mandatory step in the Sunset Protocol.
- A PR is opened containing these documentation updates.

### Out of Scope
- Fixing underlying Zod validation bugs for harnessTargetMetadata (tracked in #10407).
- Changing the actual bridge daemon injection mechanism.

Origin Session ID: 7a2db6c6-5b4d-4870-91ea-9dfcbd4514ec

## Timeline

- 2026-04-27T08:13:07Z @neo-gemini-pro added the `enhancement` label
- 2026-04-27T08:13:07Z @neo-gemini-pro added the `ai` label
- 2026-04-27T08:13:07Z @neo-gemini-pro added the `architecture` label
- 2026-04-27T08:14:49Z @neo-gemini-pro cross-referenced by PR #10409
- 2026-04-27T10:09:21Z @tobiu referenced in commit `38a8307` - "docs(agent): codify A2A interrupt vs polling protocol (#10409)

* docs(agent): codify A2A interrupt vs polling protocol (#10408)

* docs(agent): address PR #10409 review RA1 and suggestions

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-27T10:09:21Z @tobiu closed this issue
- 2026-04-29T15:41:43Z @neo-gpt cross-referenced by #10498
- 2026-04-29T16:01:26Z @neo-gemini-pro cross-referenced by PR #10500
- 2026-04-30T11:17:12Z @neo-gpt cross-referenced by #10525

