[Jacksondr5]

Problem

When an agent sends with j5_send_message to an agent whose delivery won't run soon, the sender is told nothing. Three cases: the receiver's queue is held, its worktree setup failed, or it stopped on a usage limit. The message waits, but the sender can't tell it isn't lost, so it may send it again or wait for nothing. Closes #272.

What changed

The send result's deliveryNotice now covers these cases, with the approved wording. The templates sit beside receiverBacklogNotice in envelopes.v1.json:

• Usage limit, continues automatically: "<receiver> hit its provider's usage limit and continues automatically at <resetAt>. Your message is saved and will run then, in the order it was sent. Don't send it again."
• Usage limit, waits for a person: "… is paused until a person continues it. Your message is saved and will run then, …"
• Queue on hold (a busy receiver with a held queue, or a failed worktree setup): "<receiver>'s queue is on hold, so your message waits until a person resumes it. …"

How each case is detected:

• readReceiverBacklog returns a discriminated result: behind_turn, usage_limit or queue_held. withDeliveryNotice renders whichever one applies.
• The rules for an idle receiver are taken out of DeliveryTransport into idleQueueHold, so the notice and the delivery decide "held" the same way. The delivery's behaviour is unchanged.
  • Usage limit: upstream refuses to resume such a thread.
  • Failed worktree setup: resuming would run the message in the project checkout.
• "Continues automatically" is decided the way upstream's usage-limit banner decides it: the thread's limitRecovery is armed with autoResume for this run and this resetAt.
• Usage-limit notice: given only when the delivery actually waits: the receiver has a held queue, or the message is already queued.
• An idle receiver with a held queue and neither of those problems still gets no notice: the delivery resumes the queue and the message runs (An agent's message to a stopped agent runs ahead of the messages held in its queue #580).
• The notice is still advice: a failed read is logged and the send succeeds. Reads stay field-scoped (getThreadRecords). Error turn items are read only for the latest run, and only when that run failed.
• Messages accepted before a queue becomes held stay silent, as intended. The "Held A2A deliveries and limited receivers: tell the sender what is happening #272" comment is gone.

Docs: the j5_send_message Result paragraph in docs/j5/product/a2a/agent-tools.md is rewritten, with a History line. The tool description's sentence ("deliveryNotice says when your message will wait behind the receiver's current turn") is still accurate, so it is unchanged and the pinned string stays byte-identical.

#705 (upstream advance to v0.1.3): that branch rewrites the steer/queue section of deliverAgent just below the hold block. It doesn't touch receiverBacklog.ts, envelopes.v1.json, EnvelopeFormatter.ts or the hold conditions. This PR only edits the hold block above its hunk, so the two should merge cleanly.

Live testing

Not run live. The change is server-only. The tests in DeliveryTransport.integration.test.ts run the real orchestrator, event sink and A2A send service on SQLite and pin each notice's exact text:

• a busy receiver with a held queue
• a failed worktree setup
• a usage limit with no automatic continue
• a usage limit armed to continue automatically (through the same thread.metadata.update the banner's "Resume at reset" sends)
• no notice for an idle receiver whose held queue the delivery resumes
• existing backlog tests updated for the new result shape

A real usage limit can't be triggered on demand, so the usage-limit cases are tested only here, not live. The held-queue case can be reached live: stop a busy agent, start it on a new message from the composer, then message it from another agent.

Checklist

• One concern: the description has no "also"
• Tests cover the changed behavior (backend changes ship with focused tests)
• UI changes: not applicable, no UI change
• Live testing: the section above says what ran live and what did not
• Upstream-owned files: none edited (J5-owned paths only)
• Upstream product: unchanged; this follows D4's existing rules
• Surfaces: MCP j5_send_message is the only entry point for the notice. It is not shown in any client. It is computed for local agents only, as the backlog notice is. Provider-independent.
• Docs: docs/j5/product/a2a/agent-tools.md rewritten where this changes it

Verified: vp test run for DeliveryTransport.integration.test.ts, EnvelopeFormatter.test.ts, PeerRoundTrip.test.ts and src/j5/a2a/mcp (all pass). A mutation check confirmed each new test fails when its branch is removed. Server typecheck exit 0; lint and format clean on src/j5/a2a.

Built by Claude Opus 5.5 in Claude Code (J5 Code).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
j5-code	Ready	Preview	Oct 25, 2026 3:24am UTC

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{This review includes 7 billable files and costs up to $1.75.}

• Ask an admin to make reviews automatic

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Or wait 17 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 5 included reviews currently available. Your 12 included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: Jacksondr5/j5code
• Branch: j5code/held-delivery-notice-272
• File: .coderabbit.config.ts
• Commit: 588e4f4
• Layers: Repository TS config
• Review profile: CHILL
• Plan: Essentials
• Run ID: 92975628-a3cb-4f25-8b16-0d7163188f95

Commits

Reviewing files that changed from the base of the PR and between 75e8264 and 588e4f4.

Files selected for processing: 7

• apps/server/src/j5/a2a/DeliveryTransport.integration.test.ts
• apps/server/src/j5/a2a/DeliveryTransport.ts
• apps/server/src/j5/a2a/EnvelopeFormatter.ts
• apps/server/src/j5/a2a/contracts.ts
• apps/server/src/j5/a2a/envelopes.v1.json
• apps/server/src/j5/a2a/receiverBacklog.ts
• docs/j5/product/a2a/agent-tools.md

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}