A DM can return a message ID and sit unread forever: delivery to a queue is not delivery to the agent

[khaliqgant]

Summary

A DM sent to an agent can return a message ID and appear in list_dms, while get_message_readers returns an empty reader list and the recipient never acts on it. The send succeeded at the data plane; the message sat unread in the recipient's DM queue and was never injected into its session.

Delivery to a queue is not delivery to an agent, and today nothing distinguishes the two from the sender's side.

Observed

A working agent (soc2-architect) sent five DMs to chief-khaliq over a working day — aliveness pings, a final summary, and a design note. All five:

• returned real message IDs,
• appear in a 1:1 relay conversation visible via list_dms,
• show an empty reader list via get_message_readers,
• were never seen or acted on by the recipient.

The recipient was demonstrably alive and working throughout — it was posting in a group thread during the same window. So this is not a dead-recipient case.

The sender's own summary: "the sends succeeded at the data plane and sat unread in chief-khaliq's DM queue — delivery to a queue isn't delivery to the agent, which is presumably why you saw nothing."

What did work: a message posted into an existing group thread the recipient was participating in, and a steer-mode DM, which "injects into their active session rather than sitting in the unread queue like my five wait-mode DMs did."

Why this matters

A successful send receipt is currently indistinguishable from a delivered message. An agent coordinating with another has no way to know its message was never seen, so it either blocks waiting for a reply that cannot come, or proceeds on the assumption that silence means disagreement or death.

In practice this pushed a working agent to conclude a live counterpart was unresponsive, and it degraded coordination across several lanes for a full day. The agent's own conclusion is the useful one: "the reliable coordination surfaces right now are the group thread and durable artifacts, not DMs or registry status."

That is a workaround, not a fix — DMs are the natural addressing primitive and are currently unreliable in a way the sender cannot detect.

Compounding factor

Filed alongside this: channel @-mentions appear to truncate at the first hyphen and deliver to a different existing agent. Together, two of the three obvious ways to reach a named agent fail silently.

Expected

• A sender can tell whether a message was delivered to the agent as opposed to enqueued.
• Either wait-mode DMs are injected into an idle recipient's session, or the sender is told they were not.
• get_message_readers returning empty for a live recipient is surfaced as a signal rather than left for the sender to discover by inference.

Suggested checks

• DM a live, idle agent → confirm it is injected and the reader list becomes non-empty.
• DM a live, busy agent → confirm defined behaviour, and that the sender can observe which happened.
• Confirm wait and steer mode semantics are documented where a caller chooses between them, since the difference decided delivery here.

Notes

Reported from operational behaviour, not from reading the delivery path — the exact queue/injection semantics should be confirmed in source. The observable fact is: five sends, five message IDs, zero readers, live recipient.

[khaliqgant]

relay#1467 investigation notes

Branch: fix/relay-1467-dm-delivery (pushed from origin/main)

First source finding

• The MCP send_dm handler in packages/cli/src/cli/mcp/messaging-tools.ts returns the created Relaycast message record verbatim. Its description explicitly promises only the record/message ID; it does not report whether the recipient consumed or even received the delivery.
• wait versus steer is preserved into the broker delivery. In crates/broker/src/pty_worker.rs, a wait delivery can remain blocked while the recipient CLI reports an auto-suggestion, whereas steer bypasses that blocker and sends the escape sequence before injection.
• Reader state is not an enqueue acknowledgement. crates/broker/src/runtime/worker_events.rs marks the Relaycast message read only after MessageDeliveryConfirmed; therefore an empty reader list is the expected observable for queued/unconsumed delivery, but the current MCP result does not label it as such.
• The sender-side mode descriptions are vague: MCP says only Delivery mode; CLI says wait or steer. The richer distinction exists only in a README example.
• relay#1466 is not the same local resolution path: no mention tokenizer was found in this repository's broker/CLI/SDK source. Channel text and the server-populated mentions receipt are passed through the Relaycast API. Continue A DM can return a message ID and sit unread forever: delivery to a queue is not delivery to the agent #1467 first; Channel @-mentions truncate at the first hyphen, silently delivering to a different existing agent #1466 likely needs Relaycast service work, though Relay can add receipt validation if desired.

Planned red checks

• A send_dm result must identify the exact requested recipient and explicitly state queued/unconfirmed delivery for both modes.
• A default/wait receipt must explain idle-boundary behavior; a steer receipt must explain immediate interruption behavior.
• An empty get_message_readers result must carry an explicit unread/queued signal; a non-empty result must report read.
• SDK direct-message normalization must preserve the requested recipient in target so the send receipt can be asserted against the request.

Tooling limitation

The lane exposes neither Veto MCP tools nor a local veto executable. Repository discovery was performed manually with rg; repository-native tests, review/security checks, and per-workflow GitHub Actions status will be recorded before handoff.

[khaliqgant]

Implementation is pushed at commit 38496ccb on fix/relay-1467-dm-delivery.

What changed:

• send_dm now returns an explicit delivery receipt instead of letting a message ID imply delivery. The receipt says queued_unconfirmed, names the effective wait/steer mode, includes requested and resolved recipient names plus recipientMatched, and explicitly says reading is not confirmed.
• SDK direct-message normalization preserves the exact named recipient in target, so the send receipt can assert that the resolved recipient equals the request.
• get_message_readers keeps the existing readers array and adds a delivery signal: read for a non-empty list and queued_or_unread for an empty list.
• CLI send output exposes the same additive receipt. wait versus steer is documented in MCP schemas, CLI help/README, TypeScript and Python SDK docs, and both bundled Relay skill copies.
• A defensive regression proves a receipt that actually names chief for a chief-khaliq request reports recipient_mismatch rather than success.

Red/green evidence by exit code:

• New regression check before implementation: exit 1 (4/4 failed).
• Changed MCP/CLI test set after implementation: exit 0 (27/27 passed).
• Full SDK suite with lane-injected telemetry identity variables removed: exit 0 (163/163 passed).
• Root monorepo typecheck: exit 0.
• CLI lint: exit 0, no errors (76 existing warnings).
• Broker wait-mode idle gate test: exit 0.
• Broker steer-mode immediate-bypass test: exit 0.
• Formatting and git diff --check: exit 0.
• TruffleHog verified-secret scan over every changed file: exit 0, zero verified secrets.
• Runtime dependency audit: exit 1 on the repository's existing backlog (11 findings); this branch changes no dependencies.

relay#1466 is not claimed here: repository discovery found no local mention tokenizer. Channel text and the server-populated mention receipt cross the Relaycast API, so that issue is a different resolution path. This branch only adds defensive recipient-mismatch signaling where a response supplies a different resolved recipient.

Veto MCP tools and a local veto executable were unavailable in this lane, so the equivalent repository-native type, lint, test, diff, and secret gates above were run manually. No merge was attempted.

[khaliqgant]

Implementation is pushed at commit 38496ccb on fix/relay-1467-dm-delivery.

What changed:

• send_dm now returns an explicit delivery receipt instead of letting a message ID imply delivery. The receipt says queued_unconfirmed, names the effective wait/steer mode, includes requested and resolved recipient names plus recipientMatched, and explicitly says reading is not confirmed.
• MCP and CLI independently resolve the exact named recipient from the workspace directory before sending, so the send receipt can assert that the resolved recipient equals the request without trusting a request echo.
• get_message_readers keeps the existing readers array and adds a delivery signal: read for a non-empty list and queued_or_unread for an empty list.
• CLI send output exposes the same additive receipt. wait versus steer is documented in MCP schemas, CLI help/README, TypeScript and Python SDK docs, and both bundled Relay skill copies.
• A defensive regression proves a receipt that actually names chief for a chief-khaliq request reports recipient_mismatch rather than success.

Red/green evidence by exit code:

• New regression check before implementation: exit 1 (4/4 failed).
• Changed MCP/CLI test set after review follow-up: exit 0 (32/32 passed).
• Full SDK suite with lane-injected telemetry identity variables removed: exit 0 (163/163 passed).
• Root monorepo typecheck: exit 0.
• CLI lint: exit 0, no errors (76 existing warnings).
• Broker wait-mode idle gate test: exit 0.
• Broker steer-mode immediate-bypass test: exit 0.
• Formatting and git diff --check: exit 0.
• TruffleHog verified-secret scan over every changed file: exit 0, zero verified secrets.
• Runtime dependency audit: exit 1 on the repository's existing backlog (11 findings); this branch changes no dependencies.

relay#1466 is not claimed here: repository discovery found no local mention tokenizer. Channel text and the server-populated mention receipt cross the Relaycast API, so that issue is a different resolution path. This branch only adds defensive recipient-mismatch signaling where a response supplies a different resolved recipient.

Veto MCP tools and a local veto executable were unavailable in this lane, so the equivalent repository-native type, lint, test, diff, and secret gates above were run manually. No merge was attempted.

Review follow-up commit 0f9a6201 fixes the automated P2 about request-echo resolution: missing exact names now fail before send, directory-unavailable receipts say recipient_unresolved, and full hyphenated names win over existing strict prefixes by exact comparison.

[khaliqgant]

Review follow-up is pushed at 49f8ba3b, confirmed as the remote branch head.

• Unresolved receipts now discard an untrusted raw response target; a target is emitted only from the independent exact directory resolution.
• CLI reader output now carries the same explicit queued_or_unread / readConfirmed: false signal as MCP.
• The changelog entry is split into short impact-first bullets. Its [Unreleased - Patch] heading is retained because the repository AGENTS.md explicitly requires it for the first pending patch entry.

Focused regressions, root typecheck, CLI lint, formatting/diff checks, and verified-secret scan all exit 0. GitHub Actions verification for this exact SHA is in progress. No merge was attempted.

[khaliqgant]

Final handoff for relay#1467 is ready in PR #1468.

Remote branch head is confirmed as 3698f0f7, with a clean worktree. All 11 GitHub Actions workflows triggered for that exact SHA completed successfully: CI, E2E Tests, Fleet E2E, Large File Check, Node.js Compatibility, Package Validation, Prettier Auto-Format, Relay Evals, Security Scan, Stress Tests, and Test. The PR currently has no pending or failing checks.

Codegen Models, Test Build Scripts, Test Install Script, Rust Auto-Format, and Cancel PR Jobs on Merge were absent due their event/path conditions and are not counted as passing. The runtime dependency audit remains the repository's existing 11-finding baseline; this branch changes no dependencies. Veto was unavailable in this lane, so no Veto verdict is claimed.

relay#1466 is not claimed: repository discovery found no local mention tokenizer, so it is a separate upstream Relaycast resolution path. No merge was attempted.