fix(native-chat): a message sent while Stopping waits at the end of the queue, and a person's Stop never holds another agent's mail

[brennanb2025]

	Files	Added	Deleted	Net
Test	19	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​875	$\color{#cf222e}{\Huge{\mathbf{−}}}$​114	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​761
Prod	25	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​285	$\color{#cf222e}{\Huge{\mathbf{−}}}$​159	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​126

Lands with the queued-messages capability rollout (#21062). Based on main (with #24586). Nothing here takes effect on a host that does not advertise the queued-messages capability, which no shipped host does yet; the capability bump that turns it on is a separate, later PR.

ELI5

Press Stop, then type another message while the chat still reads "Stopping…". With queueing on, that message now waits in the queue, at the end, paused by your Stop like everything else you queued, until you press Resume or start a new turn. A message another agent sends this chat (orchestration mail) is never held by your Stop: it runs when the stop lands, and the queue labels it as waiting, not paused.

What Changed

The problem. With queueing advertised, a message sent while "Stopping…":

1. Had no card, then became a bubble. A person's Stop holds the session's lane until the agent answers its interrupt, which can take seconds (longer over SSH). The send was admitted only behind it. By then the turn read ended, so the host sent it plain: nothing on screen during "Stopping…", then a bubble and a new turn, ignoring the Stop's pause.
2. Was promised the wrong thing. The composer said "Queue a message to run after the stop", but your Stop pauses the queue, so a queued message waits for Resume.
3. Labelled another agent's mail as paused. Under a person's Stop every card read "paused", including orchestration mail, which runs when the stop lands anyway: a label that flashes and is then contradicted.

Before / after (only where the host advertises queueing):

Where	Before	After
A message you send while "Stopping…", queueing on (desktop) or on the phone	No card until the stop lands, then sent plain	A card at the end of the queue at once, held by your Stop's pause, even when it is the only card; no "Send message?" dialog while the chat is working
The same, queueing off (desktop)	Sent plain after the stop	Unchanged: sent plain, runs when the stop lands
Cards waiting when you Stop, or added while it is in force	Cards queued before the Stop held	Every one of your cards held, in order, until Resume or a turn you start
Orchestration mail, queued before your Stop or during it	Held with your cards	Runs when the stop lands, ahead of your held cards; its turn lifts the pause, so your cards then follow in order
A mail card's label under your Stop	"Paused"	Waiting, like any card the queue will send
The composer placeholder while "Stopping…", queueing on	"Queue a message to run after the stop"	The normal prompt (the card waits for Resume); "Send a message to run after the stop" stays where queueing is off

Mechanism.

• The card is written without waiting behind the Stop. While the host reads that a person's Stop is ending the work, a text send asking to be queued gets the usual ledger and lease admission, then a plan that only writes the card through the journal's ordered writer: always a card, never the lane. A close or reopen during admission writes nothing and leaves the operation pending, so a resend runs it afresh. A replay answers the same card.
• One pause rule, read by the drain, its consume and admission alike (queued-message-pause.ts): a person's stopped pause holds every waiting card except orchestration mail; a /clear's pause holds only the cards it carried; a restart's holds all.
• Mail is a message whose body names its sender (from, from feat(native-chat): show which agent a chat message is from, and open it #25888). A client's own send cannot set from, so its presence is the whole test, on the host and on both clients (queuePauseHoldsCard in src/shared). Clients check presence rather than parsing the sender, so a newer build's sender shape still reads as mail exactly as the host reads it; parsing would bring the "paused" flash back for those.
• Clients pass the pause itself (its reason) instead of a yes/no, so only cards that pause holds read paused.
• No wire change. Every fact used here is already published: the pause and its reason beside the list, and from on each card's body.

Why

• A message typed after pressing Stop is a new instruction, but your Stop says "don't run anything until I say so"; holding it at the end with the rest, in order, keeps both. Starting a turn or Resume releases everything in order.
• Orchestration mail acts like a normal message from another agent: it is delivered once the agent is idle, as terminal orchestration delivers it, and is not the person's to pause.
• Writing the card off the lane is safe because a card has no order to keep with the Stop. Only its later dispatch is ordered, and that already waits for the stopped turn to end.
• Alternatives considered:
  • Let a message typed during Stopping skip the paused cards (an earlier version of this PR, with a heldByPause card field). It reorders the queue against the person's own order and needed a new wire field.
  • Parse from on the client to decide "mail". It disagrees with the host for any sender shape the client cannot parse.

Differences from the common pattern

Difference	Label
A message sent during "Stopping…" waits even when it is the only card.	Intended. It is the queue's one pause rule applied to it, so the person's Stop means the same thing for every card.
Orchestration mail is never held by a person's Stop.	Intended. Mail is another agent's message, not the person's queued work; holding it would stall the sender with no way for it to know why.
Asymmetry in the fallback. A send admitted off the lane falls back to the lane if Stopping cleared by the time it runs; there, a preparation refusal is recorded after the operation's ledger row, so a retry replays the refusal, while an on-lane refusal places no row.	Temporary. It needs Stopping to clear inside the admission window and a preparation refusal together. Follow-up: run the preparation before placing the row on this path.

Mixed versions.

• No new field. An older client labels every card under a pause as paused, mail included, as today (pinned in tests/e2e/cross-version-wire/queued-card-sender-downgrade.unit.test.ts against a build without this change).
• A card from a host without from (before feat(native-chat): show which agent a chat message is from, and open it #25888) reads as the person's; such a host also predates this rule and holds mail, so the label matches.
• Only delivery: 'queue-if-active' text sends go off the lane. An older host never advertises queueing, so a newer client never asks it to queue.

Linked Issue

None: maintainer change, the queue half of #24369 split out to land with #21062.

Visual Proof

N/A until #21062: with queueing off, which is every shipped host today, nothing here is visible. Live QA of the queue-on build is still to run (see Testing).

Testing

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

• End to end through the shipped host, journal and Codex adapter (structured-agent-session-codex-interrupt-order.test.ts): while the Stop waits on Codex's answer, a send asking to be queued returns a card at once; a retry answers the same card; after the stop it waits with the held cards, and Resume sends them in order.

• Host: the pause rule (queued-message-pause.test.ts); a send while Stopping (structured-agent-session-queued-send-while-stopping.test.ts: always a card at the end; mail runs first, then the person's cards; only the mail card's body names a sender); the stop-row, pause-lift and Stop-event tests; a restart still holding mail queued after a Stop.

• Clients: desktop and phone card labels (a person's Stop marks only their cards paused, any other pause marks all); the desktop send while Stopping follows the queueing setting with no dialog while working; the placeholder.

• Cross-version: queued-card-sender-downgrade (above), plus the kept-card and Stop-event downgrade files.

• Each rule was checked by breaking it and watching its tests fail (removing the mail check turns 7 tests in 3 files red).

• At 2d950cad6c9: 20 desktop test files (243 tests) and 4 phone files (82 tests) pass; tc:node, tc:web, phone tsc and its tests-typecheck ratchet pass; oxlint and oxfmt are clean.

• Still to do before ready: port the client tests to the new desktop send layer (fix(native-chat): no saved outbox on the desktop; one send at a time, and the host owns what it accepted #25959) once it lands; live QA with queueing on.

AI Disclosure

Review

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Ensure no issues in: Security, Cross-platoform support (Linux, Windows, Mac), Remote SSH, Mobile, general backwards compatibility, performance

• SSH: everything runs on the execution host; clients present what it publishes.
• Performance: the queue's published list is keyed on its pauses too, so a Stop or a person's turn republishes it once.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[brennanb2025]

Closing this stale queue implementation after a replacement issue is created. Preserve immediate cards for messages sent during Stop and the rule that another agent’s mail is not held by a person’s pause.

The remaining problem is tracked in #27657.