Skip to content

fix(monitor): wake the session once when its watched PR merges or closes - #37776

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/monitor-final-wake
Nov 16, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/monitor-final-wake

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a session that watches a pull request with monitor_start is woken when that pull request merges or closes, and monitor_update never acknowledges a change to a loop that has already ended.

Two defects, both measured on a dashboard host over 2026-11-14/15 (seven misses on five worker sessions):

Why it matters

Every long task that hands a worker a PR to drive to merge relies on this wake. Without it the worker idles until a person or the conductor notices, and the conductor's acceptance waits on a done report that never comes.

Not a goal

  • The structured monitor_watch controller path (monitoring/decision.py), which already has the opt-in wake_on_terminal; unchanged.
  • PR Readiness holding on "re-checking " after CI ends: that is the repo's sweep cadence (pr-readiness-sweep.yml), not this code.
  • Letting monitor_update revive an ended loop for a new target.

What changed (motivation → approach → change)

  • RC1 src/kiro_crew/autonudge_service/gate.py: the terminal branch no longer splits on is_channel_key. Every gated loop records the owed turn in monitor.terminal_pending (plus a one-line monitor.terminal_note built from the typed reading), fires, and settles through the existing delivered-terminal path (firing.py → _settle_delivered_terminal) once the turn lands. A busy session leaves the debt for the next tick, as it already did for a busy channel thread. The bell notice is unchanged; it is sent at settlement.
  • src/kiro_crew/monitoring/models.py: new MonitorState.terminal_note: str = "" (older records read ""; the fire then falls back to target + outcome).
  • src/kiro_crew/autonudge_service/model.py: terminal_wake_line(loop) → [monitor finished] PR owner/repo#N merged at <ts>, head <sha12>. This is the last wake; the loop stops after this turn. (closed without merging for a close).
  • src/kiro_crew/slack/gateway_runtime/nudge_dashboard_fire.py: an owed final turn puts that line first in both the prompt and the transcript row, and reports delivered only once the turn STARTS (it waits on the same admission future a structured wake uses), so an unattended turn that times out behind the background cap keeps the debt instead of settling the watch unsent.
  • src/kiro_crew/slack/gateway_runtime/nudge_channel_fire.py: the Slack thread and DM (Discord/Webex) fires put the same line first, so the final turn reads the same on every surface. terminal_wake_line is re-exported through kiro_crew.autonudge and reached through the gateway facade.
  • src/kiro_crew/session_summary.py: [monitor finished] joins _INJECTED_PREFIXES, so the final wake is read as automation, not a human turn, in session summaries.
  • RC2 src/kiro_crew/mcp_tools/control_parts/monitor.py: for monitor_update, an inactive loop that ended on its subject (a gated loop stopped monitor_terminal, or a structured monitor with an outcome) is refused in the same call: monitor_update: NOT applied — this session's loop already ended: ... To watch a new subject, call monitor_start in this turn. No directive is emitted. monitor_start is unchanged: it already replaces such a loop, and that is the remedy the refusal names.
  • monitor_start tool description: "A merge or a close ends the watch rather than waking you" → "A merge or a close wakes you ONE last time, the turn opening with the result (...), then ends the watch; report from that turn."
  • RFC amended in this PR: docs/request-for-change/rfc-gated-pr-poll-loops.md (status implemented) recorded "On a dashboard loop, a merge or close settles the loop with the bell notice and no turn" in § 3.4, the § 3.2 table and § 7 Risks. Those three places now state the new behaviour, and § 3.4 carries an "Amended:" paragraph with the reason. The matching lines in the babysit skill, kirocrew-prepare-pr/references/rationale.md and learn-cron-dashboard.md are updated, and four code comments that said "channel loop" for the owed-turn rule now say "gated loop".

Backwards compatibility

Changes behaviour for every dashboard gated PR loop: one more delivered turn per watch, at its merge or close. Channel loops are unchanged. A stored loop whose subject already ended is not revisited. A record from an older build has no terminal_note; it reads "" and the line falls back to target + outcome.

Takes away: the turn-free dashboard settlement, and the "requested" ack from monitor_update on an ended loop.

Reader: src/kiro_crew/autonudge_service/firing.py:_fire_cycle -- gateway -- moves terminal_pending to terminal_delivered on delivery and settles; already ran for channel loops, now for all; test_a_merge_wakes_the_dashboard_session_once_then_ends_the_watch
Reader: src/kiro_crew/slack/gateway_runtime/nudge_wiring.py:_notify_nudge_expired -- bell -- reads terminal_pending as terminal news; unchanged contract
Reader: src/kiro_crew/dashboard/session_directive_apply_monitor.py -- turn boundary -- still refuses the same update; the preflight now says so first; test_monitor_update_on_an_ended_loop_is_refused_at_call_time

Tests

New test/test_monitor_terminal_final_wake.py, shaped on the observed misses:

  • test_a_merge_wakes_the_dashboard_session_once_then_ends_the_watch[worker|conductor|bot]: worker slot, conductor slot, and a Bot's dashboard thread (member_slot_key) — exactly one fire, it carries PR acme/widgets#37164 merged at <ts>, head <sha12>., then the loop is inactive with outcome SUCCESS.

  • test_a_busy_session_keeps_the_final_turn_owed, test_a_close_without_merge_says_so_and_settles_blocked, test_no_line_when_nothing_is_owed.

  • test_the_final_dashboard_turn_opens_with_the_result[worker|conductor|bot]: through _fire_dashboard_nudge, the nudge row starts with [monitor finished] PR ....

  • test_a_final_turn_that_never_starts_is_not_reported_delivered: the background queue closes the turn unstarted, and the fire answers not-delivered.

  • test_slack_gateway_coverage.py::TestFireDiscordNudge::test_an_owed_final_turn_opens_with_the_result: a Bot DM's final turn opens with the result.

  • test_monitor_update_on_an_ended_loop_is_refused_at_call_time, test_monitor_update_on_an_ended_structured_monitor_is_refused: no directive, names monitor_start. Controls: test_monitor_start_still_replaces_the_ended_loop, test_monitor_update_on_a_live_loop_still_emits.

  • test_session_summary_extract.py::test_a_monitors_final_wake_is_automation.

Changed: test_prepare_pr_gated_poll_loop.py (test_a_merge_or_close_ends_the_loop_after_one_turn), test_monitor_start_ack.py (new description sentence), test_autonudge_settlement.py (test_every_loop_gets_a_final_turn_before_it_settles replaces the dashboard-quiet case; test_a_terminal_subject_stops_the_loop_after_one_turn), test_review_repair_routing_skill.py (new babysit sentence).

  • Local, under the shared test lock (-n 2): the 15 autonudge / monitor / wake / gateway-nudge test files touching these modules, 631 passed; RC2 tool files again after the last edit, 122 passed. After the review fixes: 19 gateway-fire / autonudge / monitor files 1033 passed, facade contract files 697 passed (mirror guard re-run green after the manifest line). Last push: every test file naming the touched paths (140 files) plus the summary tests, 6549 passed. Mutation: putting back the channel-only condition fails all 4 RC1 tests in the new file, and disabling the new refusal fails both RC2 refusal tests.

Manual verification

N/A — unit coverage of the gate, fire and tool paths; no running gateway was touched.

Related Issues

Fixes #37774

Sibling sweep

Swept: git grep -n "is_channel_key(loop.slot_key)" -- src/kiro_crew/autonudge_service/
Sibling: src/kiro_crew/autonudge_service/firing.py:813 -- not affected -- channel self-re-arm; a dashboard loop re-arms from the turn-complete hook
Sibling: src/kiro_crew/autonudge_service/subject_reads.py:_settle_terminal -- not affected -- a held loop delivers no turn, so it still settles at once on every surface

Pattern harvest

Not generalizable: the turn-free settlement was one recorded choice in one branch (rfc-gated-pr-poll-loops § 3.4), amended here; the in-band preflight already exists for the other certain refusals and only missed this one case.

Known limits

  • The final turn counts as a delivered cycle; a loop at its last capped cycle when the merge lands stops on the cap instead (the bell still says it merged, as today).

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 16, 2026 03:09
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 15456d997d03133664422d4e05d8fa6b477a0e42 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 15456d997d03133664422d4e05d8fa6b477a0e42 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The pin removed for "a dashboard loop does not pay for one" is reversed openly: the RFC is amended with its reason and the observed misses, and docs/decisions/ has no entry for it.

Notes

  • Each dashboard PR watch now costs one more delivered turn, at its merge or close. Bots and conductors that watch many PRs will pay this per watch, and reverting this change takes the cost away.

[DESIGN-REVIEWED] 15456d9

Description read

[DESCRIPTION-READ] 9e94d7809218509c0d3f37612fd0229ffb2b671c1f5837cb65ade0d043a78bea

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 Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ human override accepted

@iamwhatever overrode this lane for 15456d997d03133664422d4e05d8fa6b477a0e42 via /ai-review override (this commit only).

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 15456d9

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 15456d997d03133664422d4e05d8fa6b477a0e42 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 15456d9

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 15456d997d03133664422d4e05d8fa6b477a0e42 false-positive: <reason, 20 to 500 characters>

@iamwhatever
iamwhatever force-pushed the fix/monitor-final-wake branch from 2772e94 to 1ce62bd Compare November 16, 2026 03:51
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 16, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Fixes on head 1ce62bd (one amended commit) for the reds on 2772e94:

  • Source Gates (comment-history): the test docstring "used to settle" is now present tense.
  • PR Hygiene: added the ## Pattern harvest and ## Sibling sweep sections (body only).
  • Opus 5.5 (channel fires carry no result): nudge_channel_fire.py now puts terminal_wake_line(loop) first on both the Slack thread and DM compose sites. Test: TestFireDiscordNudge::test_an_owed_final_turn_opens_with_the_result.
  • GPT 6.1 F1 (upheld; an unattended final turn can be reported dispatched before admission): an owed final turn on a dashboard slot now waits on the existing admission future and reports DISPATCHED only when the turn starts; a queue timeout reports not-delivered, so the debt stays and the next tick re-fires. Test: test_a_final_turn_that_never_starts_is_not_reported_delivered.
  • GPT 6.1 F2 (downgraded by adjudication; stale "closed" note if a busy session's PR is reopened and merged before the next poll): not changed. The settlement re-probe already rejects the stale classification (_terminal_still_holds), clears the marker and keeps the watch, and the next tick owes a fresh "merged" turn. Fixing it needs another reclassify-and-persist branch with its own rollback on this path, for a three-condition race that self-corrects in one tick.
  • First Principles (product-shape change without accepted RFC): this PR amends rfc-gated-pr-poll-loops.md § 3.4 in place, as the PR body says; the decision is the maintainer's. The suggested subtraction (gate=false on worker/conductor arms) would turn every quiet interval back into a paid turn, which is what that RFC removed.

@iamwhatever
iamwhatever force-pushed the fix/monitor-final-wake branch from 1ce62bd to df9a206 Compare November 16, 2026 04:46
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Head df9a206 (same single commit, amended) for the reds on 1ce62bd:

  • Backend Tests (Linux + Windows shards 6/8, 2/8): two tests still pinned the old turn-free ending. test_prepare_pr_gated_poll_loop.py now asserts one delivered final turn then settlement (test_a_merge_or_close_ends_the_loop_after_one_turn); test_monitor_start_ack.py asserts the new description sentence.
  • GPT 6.1 F2 (upheld; [monitor finished] read as a human turn by the summary classifier): added to session_summary._INJECTED_PREFIXES, with test_a_monitors_final_wake_is_automation.
  • GPT 6.1 F1 (downgraded; delivery acknowledged before a cold ACP session starts): not changed. The admission wait already covers the queue-timeout case; a session-start failure after admission surfaces as the error card in that same chat and the user already has the merge bell. Closing it fully needs a new runner-to-fire acceptance seam for plain nudges, used only by this path.
  • First Principles: unchanged, maintainer decision on the RFC amendment.

@iamwhatever
iamwhatever force-pushed the fix/monitor-final-wake branch from df9a206 to b01ab2b Compare November 16, 2026 05:25
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Head b01ab2b (single commit, amended) for the reds on df9a206:

  • Backend Lint (black baseline): test/test_session_summary_extract.py is now black-clean, so it is pruned from .github/black-baseline.txt (check_black_formatting.py --update-baseline, one line).
  • GPT 6.1 (upheld; a debt owed for a CLOSED reading survived a later MERGED reading): the gate now replaces the owed ending when the classification changes (terminal_pending != classification), restoring the previous debt if the write fails. Test: test_a_close_then_merge_while_busy_reports_the_merge (fails with the old condition).
  • First Principles: unchanged, maintainer decision on the RFC amendment.

@iamwhatever
iamwhatever force-pushed the fix/monitor-final-wake branch from b01ab2b to c94c8ba Compare November 16, 2026 06:21
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Head c94c8ba (single commit, amended) for the GPT 6.1 finding on b01ab2b (final wake marked delivered before provider admission):

  • The owed final turn on a dashboard slot now rides a MonitorCompletionHook whose acceptance_callback settles the fire as DISPATCHED. The runner calls it at turn_dispatch_gates.py mark_accepted(), after every refusing gate and right before provider entry, the same boundary structured wakes use. A turn refused while being prepared (closing session, restart) or never admitted (queue timeout) reads as not delivered, so the debt stays and the next tick re-fires. The hook's completion record is a no-op (no controller owns this turn); _prompt_depth is not changed.
  • Tests: test_a_final_turn_refused_while_being_prepared_is_not_delivered (fails with the earlier pre-_run_chat settle), test_a_final_turn_that_never_starts_is_not_reported_delivered, and the result-line test now runs through an accepting runner.
  • The previous round's reds were only First Principles and this GPT finding; everything else on b01ab2b was green or still running (Windows shard 5).

A dashboard PR loop settled on the merge with only the user's bell, so the agent waiting on it was never woken; every gated loop with a pull-request reading now gets one final turn opening with the result. monitor_update on such an ended loop is refused in the same call instead of acknowledged.
@iamwhatever
iamwhatever force-pushed the fix/monitor-final-wake branch from c94c8ba to 15456d9 Compare November 16, 2026 07:07
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Head 15456d9 (single commit, amended) for the GPT 6.1 finding on c94c8ba (final-wake row written before admission):

  • An owed final turn now writes its nudge row inside the acceptance callback, then settles DISPATCHED, the same order _accept_dashboard_turn uses for a structured wake. A turn that is never admitted or is refused while being prepared writes no row, so a retry cannot duplicate one.
  • Structure: the final wake now follows the structured wake's accept path end to end (wait for admission, row on acceptance, delivered on acceptance), rather than patching the plain-nudge path point by point.
  • Tests: test_a_final_turn_that_never_starts_is_not_reported_delivered and test_a_final_turn_refused_while_being_prepared_is_not_delivered now also assert no row; both fail with the eager append restored.
  • On c94c8ba every other check finished green (82 pass), including all Linux and Windows backend shards.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 15456d9 product-shape: A watched PR's merge or close wakes its session once on every surface; rfc-gated-pr-poll-loops §3.4 is amended in this PR by owner decision.

@github-actions

Copy link
Copy Markdown
Contributor

AI-review override not recorded: product-shape is not a release class. Use /ai-review override <fable|gpt|design|ux|first-principles|scope|all> <current-sha> <class>[ #N]: <reason, 20 to 500 characters>, where <class> is one of false-positive, not-applicable, pre-existing, evidence-supplied, infra-failure, reissue, deferred, owner-decision. What each class needs: docs/ci/ci-and-reviews.md#risk-release-records.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 15456d9 owner-decision: owner decision #37776 (comment) : a watched PR's merge or close wakes its session once on every surface; rfc-gated-pr-poll-loops section 3.4 is amended in this PR.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@iamwhatever recorded a owner-decision release (class owner-decision) for the first-principles AI finding on 15456d997d03133664422d4e05d8fa6b477a0e42.

owner decision #37776 (comment) : a watched PR's merge or close wakes its session once on every surface; rfc-gated-pr-poll-loops section 3.4 is amended in this PR.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 14% chance that this change introduces a defect, above the 12% limit for approving on its own.

Both defects are fixed. RC1: the gate's terminal branch now marks a final turn as owed for every gated PR loop (it was channel-only); a dashboard loop with no PR reading still settles immediately with the bell. The existing surface-agnostic delivered-terminal settlement in firing.py then settles the loop and emits the bell. The dashboard fire counts the final turn as delivered only once the runner accepts it (admission future plus a synthetic completion hook with no side effects), and a turn that never starts falls back to BUSY so the debt stays owed. notify_turn_complete returns early for inactive loops, so settled loops are never re-armed. RC2: the in-band preflight refuses monitor_update only where the turn boundary is already certain to refuse it: a gated loop stopped with monitor_terminal is always denied in _monitor_update, and a structured monitor with an outcome makes _update_monitor_admitted return None. Retained user stops keep the existing refusal, and monitor_start is unchanged. The RFC is amended openly with an owner-decision override, no docs/decisions entry covers the old behaviour, and the new tests cover the gate, the fire, a busy session, close-then-merge, unstart

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 15456d997d · 741 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 16, 2026 09:04

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving. On this head the review checked these points. The gate records the owed final turn durably and rolls it back if the write fails. A dashboard final turn counts as delivered only once the runner accepts it. The monitor_update refusal fires only where the turn boundary always refuses. The review also reverted the gate condition and the in-band refusal, and the new tests went red each time. No security, sandbox or approval boundary changes.
Done well: an owed final turn that times out or is refused while it is being prepared keeps its debt, so the watch never settles on a turn nobody received.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:

  • The [monitor finished] opener is not yet in the goal-conductor SKILL.md automation-opener lists (around lines 244 and 710) or in docs/system-specs/common/injected-messages.md. A conductor may read its final wake as a turn a person typed.
  • terminal_wake_line (autonudge_service/model.py:880) falls back to "merged" or "closed without merging" for any kind of watch. A channel work-ledger watch with no reading would report that its own session key "closed without merging". Neutral wording for watches that are not PRs, plus a test for the empty-note case, would close this.
  • The Backwards compatibility section says channel loops are unchanged. Their final turn now opens with the new line, and a later, different ending replaces the owed debt.

@KiroCrewCaptain
KiroCrewCaptain merged commit 944c87d into main Nov 16, 2026
99 of 100 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/monitor-final-wake branch November 16, 2026 09:04
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
buluoray pushed a commit that referenced this pull request Nov 19, 2026
…ses (#37776)

A dashboard PR loop settled on the merge with only the user's bell, so the agent waiting on it was never woken; every gated loop with a pull-request reading now gets one final turn opening with the result. monitor_update on such an ended loop is refused in the same call instead of acknowledged.

Co-authored-by: Joe Guo <zejiangg@amazon.com>
(cherry picked from commit 944c87d)
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.

bug(monitor): a dashboard PR monitor stops silently on merge, and monitor_update on that ended loop acks a change it cannot apply

2 participants