EN Messaging and ACK - jaeseongs95/agent-governance-suite GitHub Wiki

한국어 | English

Messaging and ACK

The most important rule in AGS session communication is simple:

Sending, delivery, acknowledgement, and completion are different states.

Message Lifecycle

Conceptually, a message can pass through states such as:

prepared
   ↓
sent / queued
   ↓
delivered / claimed
   ↓
ACK
   ↓
actual task result

Exact implementation state names can evolve between releases, but the semantic distinction should remain.

System-Issued Message IDs

Messages are tracked with system-issued IDs.

If a send result is ambiguous, repeatedly creating new IDs for the same payload can produce duplicate work.

Check the existing message status before retrying with a new message.

What ACK Means

ACK means that message processing has been acknowledged.

It does not mean:

  • the requested task is complete,
  • the review passed,
  • execution was approved,
  • the change is safe,
  • or a result has already been returned.

The actual work result must be evaluated separately.

Wake Is Not the Message Body

AGS separates the durable message payload from the host-specific wake signal.

The local messaging layer tracks the content and delivery state. Host-specific mechanisms such as Codex queue wake or Claude-side delivery mechanisms act as edge transports that can notify a session that work is available.

A successful wake does not prove that the message body was fully processed.

The Session Board Is Not Messaging

The session board is a pull-based discovery mechanism.

Seeing another session on the board does not mean that any message has been delivered to it.

The normal flow is:

Discover owner on Session Board
              ↓
Send PEER message
              ↓
Track messageId
              ↓
Receive ACK
              ↓
Receive actual result

Automatic Wake

Wake behavior depends on factors such as:

  • receiving host,
  • current session state,
  • hook support,
  • wake configuration,
  • relay / presence state,
  • generation,
  • and host-specific transport.

A terminated session should not be treated as equivalent to an idle session.

Peer Wait

The existence of a message or ACK is not enough to infer peer completion.

AGS peer-wait policy uses separate observable conditions for resumability and does not promote weak signals into strong completion evidence.

Retry Discipline

When delivery is uncertain:

  1. Check the existing message ID first.
  2. Distinguish body delivery from ACK.
  3. Determine whether an actual task result is still pending.
  4. Avoid generating duplicate IDs before checking the original delivery state.
  5. After upgrades or broker restarts, verify that old and new runtime processes are not mixed.

Technical Documentation