Skip to content

fix(session-control): tell the sender when a queued delivery is discarded - #18913

Merged
cruisercohen merged 2 commits into
mainfrom
fix/issue-13354
Oct 11, 2026
Merged

cruisercohen merged 2 commits into
mainfrom
fix/issue-13354

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A session whose queued message to another session is cancelled from that session's queue, or discarded by a hard stop, is told in its own transcript that the message will not run.

session_send into a busy target answers started: false: the message is on the target's queue and will run later. Two deliberate actions take it off that queue unrun, and neither tells the sender:

  • api_chat_slot_queue_cancel (dashboard/chat_handlers.py) takes only the text out through slot.queue_remove_by_id(queue_id), so the entry's sender stamp is discarded unread.
  • The hard-kill branch of stop_slot_turn calls slot._queue.clear() after _settle_discarded_stage_deliveries, which settles sub-agent delivery debt but never reads the sender stamp.

Only the drain's re-check (_drop_stale_admissions) reads the stamp and writes a sender notice today.

Why it matters

A session coordinating others is told its message is queued. If the target's queue card is cancelled or the target is hard-stopped, that receipt is the last thing the sender hears, and it is false: the message will never run, and the sender keeps waiting for a reply that cannot come. Every sign of the discard is on the target's transcript, which the sender does not read.

Not a goal

  • The channel-conversation counterpart (a message a channel queued into a resumed dashboard session, CHANNEL_RECIPIENT_META_KEY). Its notice is a network write with its own recipient ladder; the issue scopes to the session-to-session sender stamp.
  • The messaging-side /stop under a unified dm_scope (messaging: /stop under a unified dm_scope discards other senders queued messages #12660), which clears a different queue.
  • Other queue discards not named in the issue: a rewind discarding queued entries, and closing the target session.
  • Keeping a send that lands while a hard stop settles (open fix(chat): keep a send that lands while a hard Stop settles #18822). This change reports that entry's discard to its sender; it does not keep the entry.
  • Pending steers dropped by the hard kill: their sender is already told synchronously, because the steer's delivery id is dropped with it.

What changed (motivation → approach → change)

Symptom: a cross-session delivery cancelled from the queue or cleared by a hard stop leaves its sender with a "queued" receipt and no further word (see Tests).

Root cause: the sender stamp (send_origin_meta) is read at only one of the three places a stamped entry leaves the queue unrun.

Change:

  • session_control.notify_send_origin_discarded(state, *, entry_meta, target_slot, text, cause) reads the stamp off the entry's meta and appends to the sender: ⚠️ Message you sent to <target> was discarded before it ran: <reason>. It was not delivered and will not run. Text: "<excerpt>". cause is SEND_DISCARD_QUEUE_CANCEL ("it was cancelled from that session's queue") or SEND_DISCARD_HARD_STOP ("a hard stop of that session discarded its queue").
  • The recipient check is factored out of notify_send_origin_dropped into _send_origin_recipient, used by both notifiers, so the four no-write cases (no stamp, self-send, closed sender, reused key held by a different tab) hold identically on all three discard paths. notify_send_origin_dropped keeps its signature, wording and behaviour.
  • api_chat_slot_queue_cancel keeps the entry it already looks up for the user-origin check and notifies after a successful removal.
  • The hard-kill branch of stop_slot_turn already takes the queue and empties it in one step before the sub-agent settle (merged fix(chat): keep a send that lands while a hard Stop settles #18822). This change notifies the sender of each taken entry right after that clear, synchronously, before the settle can suspend, so a cancelled stop cannot leave a discarded entry unreported. _queue.clear() stays the module's single clear, as test_session_control_doc.py pins.
  • Rebased onto fix(chat): keep a send that lands while a hard Stop settles #18822, which is now merged: a send that lands while the hard stop settles is no longer discarded but stays queued for the next turn, so this change does not report it (its message will still run). The "Not a goal" bullet about fix(chat): keep a send that lands while a hard Stop settles #18822 was written while it was open; its second sentence describes the pre-merge behaviour.
  • docs/system-specs/modules/session-control.md and the module docstring describe the discard notice.

Rejected alternatives:

  • Passing constraints=[] or a synthetic constraint to notify_send_origin_dropped: its wording explains a changed authorization, which a deliberate discard is not, and an empty list renders an explanation of nothing.
  • A reason keyword on notify_send_origin_dropped that switches its wording: one function with two mutually exclusive argument sets. A second notifier sharing the recipient resolver keeps each signature honest and the identity check in one place.
  • Suggesting a re-send in the notice: the discard was a deliberate act, and inviting the sender to re-send would work against it.

Backwards compatibility

Compatible: both discards still remove exactly what they removed before; the only addition is a notice row on a live sending session.
Removes nothing: no function, field, key or outcome is removed, and notify_send_origin_dropped keeps its signature and wording.

Tests

New test/test_queue_discard_sender_notice.py (12 tests), driving the real queue-cancel route handler and the real stop_slot_turn with real session_send deliveries:

  • test_cancelling_a_queued_delivery_tells_its_sender: names the target, says it will not run, quotes the text, and does not use the drain's authorization wording.
  • test_cancelling_one_entry_tells_only_its_own_sender, test_cancelling_a_human_typed_entry_tells_nobody, test_a_cancel_of_an_unknown_id_tells_nobody.
  • test_a_hard_stop_tells_every_sender_its_message_was_discarded: each sender learns about its own message only.
  • test_a_soft_stop_keeps_the_queue_and_tells_nobody (control).
  • test_a_hard_stop_reports_only_the_entries_it_took: the entry the kill took is reported; a send made inside the settle await stays queued and its sender is told nothing.
  • test_a_hard_stop_of_a_human_typed_queue_tells_nobody, test_a_hard_stop_tells_a_closed_sender_nothing, test_a_hard_stop_does_not_reach_the_next_tenant_of_a_reused_key.
  • test_discard_notifier_writes_nothing_without_a_live_matching_sender, test_an_unknown_discard_cause_writes_nothing_and_does_not_raise.

Red with chat_handlers.py reset to origin/main bf1723d (4 failed, 8 passed; the controls pass):

FAILED test_cancelling_a_queued_delivery_tells_its_sender - AssertionError: the sending session was told nothing
FAILED test_cancelling_one_entry_tells_only_its_own_sender - IndexError: list index out of range
FAILED test_a_hard_stop_tells_every_sender_its_message_was_discarded - assert (0 == 1)
FAILED test_a_hard_stop_reports_only_the_entries_it_took - IndexError: list index out of range

Green on this branch:

  • pytest -n 0 test/test_queue_discard_sender_notice.py: 12 passed.
  • pytest -n 8 over the new file plus test_queue_drop_sender_notice.py, test_queue_cancel.py, test_session_control.py, test_session_control_doc.py, test_stop_handler_idempotent.py, test_compaction_stop_declined.py, test_chat_handlers_composition_contract.py, test_slot_running_readers.py, test_stop_wedged_dispatched_turn.py, test_session_broadcast.py, test_queued_prompt_durability.py, test_discord_resumed_busy.py, test_work_ledger_board.py: 867 passed.
  • flake8, isort, black, mypy on the touched files; scripts/check_comment_history.py, scripts/check_black_formatting.py, scripts/check_sync_io_in_async.py, scripts/check_subprocess_encoding.py, scripts/check_feature_map.py, ./scripts/docs-lint.sh: all pass.

Manual verification

N/A — unit coverage sufficient: the tests drive both real handlers in-process, and the notice is a transcript row with no rendering change.

Related Issues

Fixes #13354

Related: merged #13303 (the drain-side sender notice). Merged #18822 (keeps a send that lands while a hard stop settles; this branch is rebased onto it). Open #10098 touches the same hard-kill clear; whichever lands second rebases.

Pattern harvest

Rule candidate: review-prompt
Pattern: a per-entry stamp read at one removal site of a collection while sibling removal sites discard the entry unread.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 10, 2026
…rded

A queue-card cancel and a hard stop both discard a queued cross-session delivery without reading its sender stamp, so the sender's last word stays the started:false receipt. Both sites now call notify_send_origin_discarded, which shares the drop notice's recipient check and words the notice for the discard.

Fixes #13354
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f617397

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check before merge: a rewind (chat_rewind.py:647) and closing the target still discard stamped entries without telling the sender. Both are deferred under Not a goal.

What this change ships

Inventory (6 items) — 6 justified

Intent: a session that queued a message to another session learns when that message is discarded and will never run. FIX (#13354; tests fail on base).

  1. Cancelling a queued cross-session card now writes a "discarded, will not run" notice into the sender's transcript — justified
  2. A hard stop now notifies the sender of each cross-session entry it clears — justified
  3. The recipient check (no stamp, self-send, closed sender, reused key) moves into _send_origin_recipient, which the drop and discard notifiers share — justified
  4. New public notify_send_origin_discarded plus the SEND_DISCARD_QUEUE_CANCEL and SEND_DISCARD_HARD_STOP causes, each with one call site — justified
  5. An unknown cause logs and writes nothing instead of raising — justified
  6. The session-control spec and the module docstring describe the discard notice — justified

[FIRST-PRINCIPLES-REVIEWED] f617397

Description read

[DESCRIPTION-READ] d06a293e5d4e9cc054f5ed0cf2a40921aebe364334c2c65d0386b08b24834d1e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] f617397

Description read

[DESCRIPTION-READ] 3cff6a9675f174bc00dd338858facdbd5821f5021b343b6afe5e55bb757fe322

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f617397

Verdict parsed from the review's SHA-scoped output markers for commit f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable f617397e3b94a4a0a53cf4fe57ecbbdc975aab1c: <one-sentence reason>

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 10, 2026
@cruisercohen
cruisercohen marked this pull request as ready for review October 10, 2026 20:02
@cruisercohen
cruisercohen requested review from a team and KiroCrewCaptain as code owners October 10, 2026 20:02
@cruisercohen
cruisercohen enabled auto-merge (squash) October 10, 2026 20:03
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 10, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at head f617397: PR Readiness is green, no open change requests, and the review lanes passed. (AI-assisted review at bolichen97's request.)

@cruisercohen
cruisercohen merged commit dd8fc8a into main Oct 11, 2026
105 of 113 checks passed
@cruisercohen
cruisercohen deleted the fix/issue-13354 branch October 11, 2026 01:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

dashboard: a queue-cancel or hard-kill discard strands the sender of a queued cross-session delivery

2 participants