Skip to content

fix(subagent): clear an owed expiry report only on a delivery ack - #20508

Merged
bolichen97 merged 1 commit into
mainfrom
fix/owed-report-delivery-ack-16861
Oct 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/owed-report-delivery-ack-16861

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A memory-wait expiry's owed report is cleared only when the gateway says it delivered the report, so no current or future gateway path can drop it across a restart.

Today taskq_clear_owed_report_if_delivered clears the store's owed mark when the report task returned True and none of _digest_held, _delivery_queued, _report_undelivered is set. That is a guess from missing flags. A gateway route that parks or swallows the report without setting one of them would clear the mark while the parent was never told, and a restart then drops the expiry for good. Deferred from #16347 (Design Review).

Why it matters

The expiry report is the parent's only word that a spawn will never run: it has no run folder for orphan recovery to find. Any new delivery route in the gateway (channel, cron, digest, announce) that forgets to set a "parked" flag silently loses it. A positive ack makes the safe outcome the default.

Not a goal

  • Removing report_owed from SubagentDelivery on the digest and queued-announce paths. Those reports are delivered later, by a settle that only holds ids, so they still need the debt carried with them; their settles are unchanged.
  • Changing when a run's delivered tombstone is written. _report_undelivered keeps that job.

What changed (motivation → approach → change)

Symptom: the owed mark is cleared on the absence of flags. Cause: there is no positive signal from where the report lands. Change: a new SubagentInfo._report_delivered flag in subagent.py. In slack/gateway.py it is set where a report reaches the parent: after the parent's injected turn returns, when the blocking tool already collected it inline, and when a route has no conversation so the notice is the whole delivery. In subagent_manager/terminal.py the reporter sets it when nothing consumes reports, and when the parent was retired. The direct clear (subagent_manager/admission/taskq_bridge.py) and the digest settle (subagent_manager/waves.py) now clear only on that flag. The flag is classified as not delivery state in the routing table, and docs/system-specs/modules/subagent.md is updated.

Backwards compatibility

Compatible: every route that delivered before now sets the ack, and every parked or failed route still leaves the mark owed; the only new outcome is "owed" for a route that sets nothing.

Removes nothing: _report_undelivered stays and still gates the delivered tombstone; no key, record or reader is dropped.

Tests

  • test_a_report_parked_without_an_acknowledgement_stays_owed (new): an _on_done that returns normally and sets no flag leaves the expiry owed. Red on main (the old three-flag check clears it), green here.
  • The harness on_done now acknowledges, like a real delivering route.
  • Existing given-up, digest, queued and replay owed-report tests pass unchanged.
  • Determinism: test/test_subagent_queue_max_wait.py run 3 times with -n 4 and once in shuffled order, 48 passed each time.

Manual verification

N/A: the change is internal store bookkeeping, covered end to end by the gateway-through tests in test_subagent_queue_max_wait.py.

Related Issues

Closes #16861

Pattern harvest

Rule candidate: review-prompt
Pattern: "done" inferred from the absence of every known failure flag instead of a positive ack set where the work lands.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 14, 2026 21:43
@bolichen97
bolichen97 requested a review from mbriones98 October 14, 2026 21:43
@bolichen97
bolichen97 enabled auto-merge (squash) October 14, 2026 21:43
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@bolichen97
bolichen97 force-pushed the fix/owed-report-delivery-ack-16861 branch from 95fa989 to 410fe47 Compare October 14, 2026 22:08
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 410fe470f942f63aea373b20d6acb015e7b72c29 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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 410fe470f942f63aea373b20d6acb015e7b72c29 — 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 that every gateway route that really delivers sets _report_delivered. If one misses it, the report is no longer lost, but after a restart it gets replayed as a duplicate.

What this change ships

Inventory (6 items) — 6 justified

Intent: after a restart, the parent still hears that a memory-wait spawn expired and will never run. This is a FIX (#16861).

  1. A directly delivered expiry report's owed mark is cleared only when the route confirms delivery, not when no failure flag is set. — justified
  2. The digest settle clears the held expiries only when the flusher confirms delivery. — justified
  3. Gateway routes confirm delivery when the parent's injected turn returns, and at the three places where the blocking tool already collected the report inline. — justified
  4. Notification-only routes (no conversation to inject into) confirm delivery once the notice is sent. — justified
  5. The reporter confirms delivery itself when no consumer is wired and when the parent was retired. — justified
  6. _report_undelivered is narrowed to gating the delivered tombstone only. — justified

[FIRST-PRINCIPLES-REVIEWED] 410fe47

Description read

[DESCRIPTION-READ] d392cc6d4c99d6dfa10a055977299de1438edf2dd7ef6fc43f8e441fdf854fd2

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.

@bolichen97

bolichen97 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor Author
  • Every delivering route sets _report_delivered -- rebutted

Audited every _subagent_done exit on 410fe47: _inject_with_retry acks once the parent turn returns (channel, Slack, session-only, cron); the three inline-collected skips, the slot-gone notification and the notification-only tail ack; _report_terminal acks its no-consumer and retired-parent skips.
Every route that leaves it unset parks or fails: digest hold and queued / idle-slot announces carry report_owed to the settle that clears on consumption; _inject_with_retry failure arms return None before the ack; flush-only records owe nothing.
A future route that forgets the ack now replays a visible duplicate instead of losing the expiry, the trade #16861 asked for.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that every delivering route sets _report_delivered. The new test only covers the case where no ack is set, so a missed ack site would go unnoticed and the expiry would be reported a second time after a restart.

[DESIGN-REVIEWED] 410fe47

Description read

[DESCRIPTION-READ] dd52a32778f38627e73f445f508c34efb5b9cace282d8fbc347101d411f6ffa3

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 410fe47

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 410fe47

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

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

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A missed ack site would go unnoticed by the new test -- rebutted

The positive cases are already pinned through the real gateway on this head: test_an_injection_that_lands_clears_it (cron + Slack inject ack), test_a_digest_that_lands_clears_it (digest flusher ack, last-member and forced), test_a_solo_expiry_into_an_idle_slot_is_cleared_once_consumed and test_the_digest_that_delivers_the_expiry_clears_it (consumption settle) all assert owed_reports == [], so dropping any of those ack sites turns them red.
The new test pins the other half: a route that sets nothing stays owed.
Remaining ack sites (inline-collected skips, notification-only tails) are one-line sets beside their return; a miss there costs a visible duplicate after restart, not a lost report.

@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 15, 2026
@bolichen97
bolichen97 merged commit 839b5e6 into main Oct 15, 2026
102 checks passed
@bolichen97
bolichen97 deleted the fix/owed-report-delivery-ack-16861 branch October 15, 2026 00:59
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 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.

Owed expiry reports: clear on positive delivery ack (follow-up to #16347)

2 participants