Skip to content

fix(work-ledger): wake a conductor once per item per reason, not once per repeat - #37883

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/ledger-wake-once-per-reason
Nov 16, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/ledger-wake-once-per-reason

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a conductor's work-ledger patrol wakes it at most once per item per reason; a repeat of the same cause, with nothing new on that item, does not wake it again.

An owner review of 75 delivered work-ledger wakes on one conductor session found repeats that carried no news:

  • reason=stall three times in about 40 minutes for one item (2026-11-15 19:51, 20:13, 20:30Z). The worker reported progress at 19:32, 19:58 and 20:15, each time after the conductor nudged it, and stopped again. Each stall came 15 minutes after the previous progress.
  • reason=stall three times (20:45, 21:19, 21:46Z) for an item the conductor had parked with a decide ("hold, report progress and wait"). The worker answered each park with a progress report and waited.
  • status=blocked twice within a minute for one item (2026-11-16 02:28:57 and 02:29:47Z): blocked (reason needs_human), the conductor's decide, then the same blocked / needs_human again with a re-worded summary.

Why it matters

Each repeat costs the conductor a model turn that reads a board it already read, and it lands mid-turn on other work. The owner reads these wakes as noise.

Not a goal

What changed (motivation → approach → change)

Why the existing filter (#33602) let these through:

  • Stall: the probe's stall token was stall:<last_report_at>. Every progress report moves that stamp, so each "still waiting" report minted a new token, and the seen set treated it as a new stall once the 15-minute window ran out again.
  • Blocked: ledger_wake.repeats_status compares a report only with the event right before it. The conductor's own decision sat between the two blocked reports, so the second one counted as news.

The change stays inside that filter:

  • src/kiro_crew/ledger_wake.py: stall_episode builds the stall token from what the silence is about: the item's status, the newest worker report of another status (read from the tail the probe already loads), a decide the worker has not answered yet, its wake_at, and whether its session is gone. A progress that keeps the status changes none of these. A status change, a new unanswered decide, a new wake_at or a closed session do.
  • src/kiro_crew/ledger_wake.py: previous_report / repeats_wait. A blocked or question that repeats the worker's previous report, skipping the conductor's own writes, is a repeat. A question also needs the same summary. Events carry no reason, so the probe keeps the last delivered wait's cause (cause_token, cause:<status>:<reason>) in the seen set it already has (note_wake(cause=...)). The newest report is a repeat only when its cause matches. A new reason wakes.
  • src/kiro_crew/probes/work_ledger.py: uses both. done keeps the back-to-back rule from fix: wake a conductor only on a changed worker status; longer floor for a PR waiting on review #33602. reply and any new status still wake.
  • src/kiro_crew/probes/work_ledger.py: the stall observation key carries the episode, so the kernel's realert_secs mask cannot hide a re-armed stall (a closed session, a new unanswered decide).
  • src/kiro_crew/probes/work_ledger.py: an item with an open ask record (the conductor waits on a person for it; decide / close clear it) raises no stall wake while its worker session is open. This is the owner's rule for this PR ("an item that waits on a person is not stale"). It lives in the probe only: work_ledger.is_stale and the board's stale flag are unchanged.
  • The item's stale flag is unchanged on reads, and the patrol's floor turn still shows it. So a worker that really died is still found.
  • Docs changed in this PR: docs/system-specs/modules/monitor-architecture.md (repeat rule, stall token and key, ask) and docs/request-for-change/rfc-permanent-patrol.md §4 (the repeat rule it states).

Bot conductors and conductor mode arm the same watch="work-ledger" probe, so both get this.

Backwards compatibility

Compatible: no field, validator or key is removed or renamed. The rate file gains cause: tokens in an existing list. An old stall token stall:<stamp> is replaced by the first episode token, which costs at most one extra stall per open item after upgrade.

Removes nothing: the change only suppresses wakes that repeat a delivered cause. Every value it reads stays on the board.

Tests

test/test_probe_work_ledger.py:

  • test_the_same_wait_after_the_conductors_decision_does_not_wake: blocked / decide / the same blocked → no second wake (the it_bc232b0e case).
  • test_the_same_status_with_a_new_reason_wakes: a new reason wakes, across a decide and back to back.
  • test_an_identical_question_across_a_decide_does_not_wake_but_a_new_one_does.
  • test_progress_reports_that_keep_the_status_raise_one_stall: replaces test_many_stalls_cannot_evict_a_report_still_in_the_tail, which pinned one stall per progress report. Now it is one stall per status run, and the blocked report still wakes once.
  • test_a_parked_worker_answering_each_decide_with_progress_stalls_once (the it_d2445efa case).
  • test_an_unanswered_decide_re_arms_the_stall, test_a_closed_session_re_arms_the_stall.
  • test_an_item_waiting_on_a_person_raises_no_stall: an ask record holds the stall wake but not the board flag; a closed session still raises, and the next decide re-arms it.
  • test_a_re_armed_stall_is_delivered_through_the_kernel_mask: a re-armed stall gets past the kernel's mask via irq.run.
  • test_a_bot_conductor_gets_the_same_once_per_reason_filter[conductor-mode|bot].
  • Replaced test_the_same_status_after_the_conductors_decision_wakes: it pinned the opposite of the new rule.

Proof: PROVEN test/test_probe_work_ledger.py::test_the_same_wait_after_the_conductors_decision_does_not_wake, test/test_probe_work_ledger.py::test_the_same_status_with_a_new_reason_wakes, test/test_probe_work_ledger.py::test_an_identical_question_across_a_decide_does_not_wake_but_a_new_one_does, test/test_probe_work_ledger.py::test_progress_reports_that_keep_the_status_raise_one_stall, test/test_probe_work_ledger.py::test_a_parked_worker_answering_each_decide_with_progress_stalls_once (head 13863b2)

With the source hunks stashed, all 11 new tests fail. Run locally under the shared test lock with -n 2: test_probe_work_ledger.py 126 passed. test_conductor_wake, test_autonudge_ledger_extension, test_autonudge_person_wait_hold, test_autonudge_ledger_quiet_floor, test_conductor_base_work_ledger, test_work_ledger*, test_remote_dispatch_hub_ingest/puller and test_mate_worker_parity: 665 passed.

Manual verification

N/A: unit coverage. The three cases above are replayed as tests from the transcript and worker logs.

Related Issues

N/A

Sibling sweep

Swept: git grep -nE "repeats_status|_STALL_KEY|last_report_at or 'none'" -- src/
Sibling: src/kiro_crew/conductor_wake.py -- not affected -- it only pulls the tick forward; the probe decides whether a turn is spent

Pattern harvest

Not generalizable: the defect is a dedupe key that tracked a timestamp instead of the cause, specific to this probe's token.

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

Contributed under Apache-2.0.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 13863b27b7dff947bcc2f982975d5978534f563a 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 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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 13863b27b7dff947bcc2f982975d5978534f563a — 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 does not.

First-Principles-Verdict: PASS

The fix is aimed at the cause: dedupe keys now follow what the wake is about, not the report timestamp. The ask-record stall hold rides along with no reported case behind it.

Notes

  • Item 5 — oversized: the Goal is "a repeat of the same cause … does not wake it again", but waits_on_person = bool(item.ask) and not closed holds back the first stall too. None of the three reported cases involves an ask record, and the only support given is "the owner's rule for this PR". It also defines "waits on a person" a second time, beside work_vocab.waits_on_person, whose docstring says it is "The one rule behind every 'needs you' count". Subtraction: delete the waits_on_person hold in probes/work_ledger.py and test_an_item_waiting_on_a_person_raises_no_stall. Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 2 — inherited: the deleted RFC line says "so does every question … since each is a new ask". The evidence covers only blocked. No reported case shows a repeated question waking. Subtraction: drop "question" from _WAIT_STATUSES and its test.

What this change ships

Inventory (6 items) — 4 justified

Intent: stop a conductor being woken again and again about a work item when nothing new happened on it. FIX.

  1. A repeated blocked with the same reason, across a conductor decide, no longer wakes — justified
  2. A repeated identical question across a decide no longer wakes — rides along; no reported case
  3. The same status with a new reason still wakes — justified
  4. A stall wakes once per episode, not once per progress report — justified
  5. An item with an open ask record raises no stall while its worker session is open — rides along, oversized
  6. The stall observation key carries the episode, so a re-armed stall gets past the kernel mask — justified

[FIRST-PRINCIPLES-REVIEWED] 13863b2

Description read

[DESCRIPTION-READ] 91889a2641430aa8872bbe96f5752c55abe1316b57bda767cf788504190ab625

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

The design fixes the dedupe key itself, not the symptom, and keeps the board's stale flag and the floor turn as the backstop.

Notes

  • The replaced pin covered decide "retry once" → blocked "retried, still stuck". After this change a failed retry that comes back with the same reason (or with no reason, since cause:blocked: matches) no longer wakes the conductor. It only finds out on the next floor turn. The new RFC §4 and spec wording should say outright that the old "after a decision, it wakes" rule is being reversed on purpose, with the owner's review as the reason. It should not read as a gap that was closed.
  • While an ask is open and the worker session is still open, the probe raises no stall for that item. A worker that hangs during that time is caught only by the floor turn. This is acceptable for now, but the spec should name the floor turn as the only thing that catches it.

[DESIGN-REVIEWED] 13863b2

Description read

[DESCRIPTION-READ] 0f34a822bf7852ae7938eda18f5f8a97a4685193ef49995b691db511326a26ba

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

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 13863b2

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

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

@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 13863b27b7dff947bcc2f982975d5978534f563a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 13863b2

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

… per repeat

A stall wake is keyed on its episode (status, the newest report of another
status, an unanswered decide, wake_at, session gone) instead of the last
report's stamp, so a worker that reports progress and stops again is one
stall; the observation key carries the episode so the kernel mask does not
hide a re-armed stall. A blocked or question report that repeats the
worker's previous report wakes nothing even across the conductor's own
decide, unless its reason differs from the cause last delivered or a
question's summary changed. An item with an open ask record raises no
stall wake while its worker session is open.
@iamwhatever
iamwhatever force-pushed the fix/ledger-wake-once-per-reason branch from b8ac24b to 13863b2 Compare November 16, 2026 08:15
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Head 13863b2 answers both blocking findings on b8ac24b:

  • GPT 6.1 F1 (re-armed stall reuses a masked key) fixed. The stall observation key is now stall:<item_id>:<episode>, the same identity as the seen-set token, so a closed session or a new unanswered decide gets past the kernel's realert_secs mask. New test: test_a_re_armed_stall_is_delivered_through_the_kernel_mask, which drives irq.run and fails without the change.
  • First Principles (ask exemption in is_stale) taken. The item.ask branch is gone from work_ledger.is_stale; work_ledger_rules.py matches main again, so the board's stale flag and the dashboard readers are unchanged. The rule itself comes from the owner for this PR ("an item that waits on a person is not stale"), so it now sits in the probe only: an item with an open ask record raises no stall wake while its worker session is open, a closed session still raises one, and the next decide (which clears the record) re-arms it. Test: test_an_item_waiting_on_a_person_raises_no_stall, which also asserts the board flag still reads stale. The description and monitor-architecture.md say this now.
  • Design note (only the newest report's reason is known): kept as is, since the board shows the latest state. Adding a per-event reason would change the event schema, which is out of scope here.

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

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider raised 2 possible problems and estimates a 55% chance that this change introduces a defect; a person should check them.

The core dedupe fixes are sound and tested: a stall token built from what the silence is about, and blocked/question repeats that skip the conductor's own writes while a new reason (via the cause token) still wakes. The PR also adds a stall hold keyed on bool(item.ask). That record is cleared only by decide/close, not by a person's steer or by later worker reports. So a worker that resumes after the person answered and then stalls never raises a stall wake (only the floor turn catches it), contrary to the canonical work_vocab.waits_on_person rule. The hold also suppresses first wakes, which is outside the frozen goal. Request changes: remove the hold or narrow it to the shared rule, and add a test for the steer-then-stall path.

Things to check (possible problems the decider raised; at this confidence many turn out to be fine):

  • Failing path: the conductor records an ask, then the person answers by steering the worker directly. A steer is not a worker report, so the conductor is never woken and never writes a decide. The worker resumes, reports progress, then goes quiet with its session open. is_stale is true, but the h (src/⁠kiro_crew/probes/work_ledger.py, medium)
  • The open-ask stall hold is new scope beyond the frozen goal (it suppresses first wakes, not repeats). It should be removed, or narrowed to the canonical rule and justified separately. (src/⁠kiro_crew/probes/work_ledger.py, low)

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 13863b27b7 · 398 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 10: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.

Tier 1 auto-approve: fix (5 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: work-ledger probe wakes a conductor once per item per reason instead of once per repeated report; plus tests. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/request-for-change/rfc-permanent-patrol.md, docs/system-specs/modules/monitor-architecture.md.

@KiroCrewCaptain
KiroCrewCaptain merged commit 4175fc5 into main Nov 16, 2026
99 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/ledger-wake-once-per-reason branch November 16, 2026 10:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This merged while my review of 13863b2 was still running, so here is its one finding as a follow-up item.

src/kiro_crew/probes/work_ledger.py:429: the open-ask stall hold (waits_on_person = bool(item.ask) and not closed) can hide a real stall. Trigger: the conductor records an ask, the person answers by steering the worker directly (no decide), the worker resumes, reports progress, then goes quiet with its session still open. Only decide and close clear item.ask (work_ledger_writes.py:711, :738), so is_stale is true but the probe raises no stall wake for the rest of the item's life; on the base this stall woke the conductor. The board (_ANSWER_KINDS = {"decision", "steer"}) and work_vocab.waits_on_person already treat a steer as answering an ask, and the hold also suppresses the first stall of any item with an ask record, not only a repeat.

Smallest follow-up: drop the hold (the line, its guard, the matching monitor-architecture.md sentence and test_an_item_waiting_on_a_person_raises_no_stall), since stall_episode already wakes once per episode; or reuse the shared answered rule (work_vocab.waits_on_person). A test for ask, then steer, then progress, then a stall raising one stall wake would pin it.

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.

2 participants