Repository navigation
feat: wake a conductor from its work ledger instead of a timer - #12781
Conversation
|
Intent: make a conductor watch its own work ledger, so a cycle where no worker needs it costs no model turn, and a worker that does need it is answered on the next tick instead of at the next scheduled read. |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
5541950 to
6db2248
Compare
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The PR adds its own two store-seam allowlist entries, which the authorizing RFC records as "a human's edit" that must not arrive with a passing suite. Watch
[DESIGN-REVIEWED] 68c57f6 Description read[DESCRIPTION-READ] ba1bd1696e699c4d8a4c39307dd8c90c88671ad3d068a9e488098121c387d3f8 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 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The push half's only decision record is a draft RFC shipped inside this PR, and the store-importer allowlist entries the base RFC reserved for a maintainer arrive self-added. Not justified as shipped
What this change shipsInventory (10 items) — 5 justifiedIntent: a conductor learns of a worker's report, question or death the moment it happens, and a quiet tick costs no model turn — an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 68c57f6 Description read[DESCRIPTION-READ] b81d4e8f9fe33eb8b71ea634f573891417ff0a6f4b530342f41ef0dc57ccc592 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5 Review — ✅ no blocking findingsReviewed Review details2 advisory findings; nothing blocks the merge. FINDING — src/kiro_crew/crew_log/eager.py:526 — FINDING — src/kiro_crew/probes/work_ledger.py:263 — [OPUS-REVIEWED] 68c57f6 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
6db2248 to
8790b5f
Compare
|
self-added: yes
|
|
self-added: yes
|
|
mechanism: the per-tick config read is gone, not moved
|
|
mechanism: LedgerWakeConfig, its loader field and its reader are deleted
|
|
mechanism: the rate file remembers several recently charged tokens, not one
|
|
mechanism: the watch FieldSpec is removed from MONITOR_UPDATE_SCHEMA
|
|
mechanism: LedgerWakeConfig, the loader field, the reader and the probe parameter are deleted
|
|
|
8790b5f to
2c9610f
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Windows junction note at head a73ef9f852:
ledger_wake.note_wake checks parent.is_symlink(). On Windows that does not detect an NTFS directory junction, which can be created without symlink privilege. A junction at the rate-file parent can therefore redirect the persistence path once a work-ledger watch is reachable.
Please use platform_compat.is_link_or_junction(parent) so Windows junctions are refused with symlinks.
|
@iamwhatever — re: "Require some more discussions on this method" (reviewed at What the method does. It turns a babysit/conductor loop from a blind fixed-interval timer into a monitor that observes the conductor's own work-ledger and only spends a turn when that typed evidence warrants it — a quiet ledger costs no wake, and a finished ledger retires the watch. The watched subject is never guessed from prose: for the Why the gate is sound. The probe is strictly read-only over the store; every wake is charged through the existing per-item rate limit ( What changed since
Current state: PR Readiness = success on |
UX Review (Fable 5) — ⏭️ skippedRevision |
A conductor's babysit loop can watch its own work ledger: a tick with nothing actionable costs no model turn, a worker's report/question/death pulls the next tick forward within seconds, and a finished ledger retires the watch. Folds in the stacked crew-log push (#15691) so a worker's write wakes its conductor through the crew log rather than only on the scheduled cadence. Includes the review-fix round on the folded surface: - gate._terminal_still_holds classifies the observation-less work-ledger terminal from the recheck verdict's outcome/keys (not from a PR observation), so a settled channel work-ledger loop settles instead of redelivering forever. - conductor_wake._admit sweeps aged-out items from both pull-forward tables so they cannot grow for the life of the loop. - the crew-log push carries the entry's board and fires only when it matches the bound conductor, so a nested conductor's own write does not spend its parent item's pull-forward budget. - subject.infer_subject resolves a work-ledger watch's own session before a judge brief is consulted, so a brief naming a PR cannot retarget the watch. - ledger_wake.note_wake's redirect guard screens junctions as well as symlinks.
Problem / Motivation
Goal: a conductor learns of a worker's report, question or death the moment it
happens, and a tick where nothing changed costs no model turn.
A conductor watches its workers by waking up on a timer. Every tick it spends a model
turn to read its work ledger, and almost every one of those reads finds nothing new.
Meanwhile a worker that reported
question29 minutes ago is still waiting, and a workerwhose session died without reporting is not noticed until someone looks. The cost falls
in the wrong place twice: the conductor pays for silence, and the worker pays for the
conductor's sleep.
This PR ships both halves of the fix. The first half is the gate: the conductor's
loop reads the ledger in Python before it spends a turn. The second half is the
push: a worker's write pulls the conductor's next tick forward, so the gate runs
within seconds of the event instead of at the next cadence. The push landed on this
branch as #15691, so the two
commits here are one feature each.
What authorizes this change, on main.
docs/request-for-change/rfc-conductor-work-ledger.md,"Phase 3 -- the wake gate", states the scope as "a
work-ledgerprobe, its registrationin
build, thewatchfield onmonitor_start's schema, and the target-inferencebranch. No kernel change", and lists the liveness conjunction as an exit criterion: "An
item past the staleness window whose session is running does not wake; the same item
with its session stopped does." The gate commit is that scope, including the
watchfield.
docs/request-for-change/rfc-wake-judge.mdsection 6 names this probe as thetyped half of a pair: "probe first, judge on what" the probe cannot type.
What this PR decides, and where that decision lives. The push half has no
decision record on main. Its RFC,
docs/request-for-change/rfc-crew-log-wake.md, shipsINSIDE this PR (status
draft), because this repository does not take standalone RFCpull requests (#15671 was closed on
that rule). The First Principles lane reads RFC status from the base commit by design, so
it will read this RFC as draft until the PR merges; clearing that is a maintainer's
/ai-review override first-principles <sha>, recorded once the head is settled.The RFC's terminology note matters for reading the diff: the event source is the crew
log (one append-only file per unit). The session ledger and the work ledger are both
folds of it. The push hooks the log's append path, never a fold.
Why it matters
A fleet of five workers costs its conductor ten turns an hour to learn nothing. Raise
the cadence to answer workers faster and the bill rises; lower it to save turns and a
blocked worker waits longer. No setting is right, because the schedule guesses at
something the ledger already knows.
Measured on a pod running this head (
docs: see Manual verification):question-> conductor turn startsprogressreportsquestionreports in one minuteNot a goal
A second wake channel. Both halves reuse the watch kernel (
irq.py) that alreadyruns pull-request watches inside the nudge loop. The push moves that loop's deadline; it
does not deliver anything of its own.
Reading a worker's prose. The probe answers only what is typed: an event kind, a
status, whether a session is running or gone. Whether a worker's words deserve a turn
is the wake judge's question.
A worker addressing its conductor. The push carries no value and no frame. A worker
writes its own report; the gateway's eager drain sees the committed entry, resolves the
binding, and pulls the conductor's tick forward. The worker holds no handle on the
conductor and the
session_sendrefusal upward is unchanged.Durable delivery. A dropped push is not retried. The scheduled tick reads the same
ledger a cadence later, so a lost push costs at most one cadence of delay and no new
store. (Pure-push with a mailbox was weighed in the RFC's alternatives and not taken.)
A fold subscription. The push listens on the crew-log drain by entry type, not on a
FoldAdvancedevent. Re-hosting it as a subscriber of the bus that#15781 adds is a named follow-up
once that bus is on main; it removes the binding lookup, since the
workfold is keyed bythe conductor's own slot.
What changed (motivation -> approach -> change)
Gate (commit 1)
probes/work_ledger.pyledger_wake.pyworker_closedprobes/targets.py,probes/__init__.pywork_ledger_target(); the new kind is servedautonudge.py,autonudge_service/*validation.py,mcp_tools/control.py,autonudge_authz.pymonitor_start/monitor_updateacceptwatch: "work-ledger"-- the one-call armslack/gateway.pyworker_running/worker_closedresolvers from the slot tableA worker report carrying
done,blockedorquestionwakes the conductor. Aprogressreport moves the token and does not wake. Every other event kind in the storeis written by the conductor itself, so waking on one would wake a conductor with its own
hand. Silence gets its own wake through
work_ledger.is_stale: quiet past the window,worker not running, last word still leaving the move with it. A worker whose slot is GONE
skips the window.
One item's news is capped at
MAX_WAKES_PER_ITEM_PER_HOUR = 12. A tick can charge anitem several times (
_EVENT_TAIL = 8events per item per tick, plus a stale token), sothe cadence bounds ticks and the budget bounds wakes; they coincide only for an item
producing exactly one wake per tick.
Push (commit 2, #15691)
conductor_wake.pyfire_now; a per-item cap on pushes, separate from the cap on wakescrew_log/eager.pywork/recordedwhose writer is a bound worker, deduped per worker per batch; on the worker thread, never on the append pathdashboard/state.pyledger_wake.worker_closedcounts a slot under construction, unrestored or restoring as opendashboard/chat_handlers.py,slack/gateway.pyautonudge_service/timers.py,firing.py_arm_timer, so the mark survives; a loop restored after a gateway restart fires one immediate gated tickprobes/work_ledger.pydashboard/handlers/work_ledger.py,work_ledger_board.pyworker_closedthrough the same resolver as the gate, so the badge and the wake agreedocs/system-specs/modules/monitor-architecture.mdmonitor_start'swatch; the objective row is still borrowed fromreview_ready(own row is a follow-up)docs/request-for-change/rfc-crew-log-wake.md, READMEBackwards compatibility
Compatible. The pull-request watch infers its subject exactly as before;
watchisoptional and only one value is accepted. Terminal success is now declared per OUTCOME in
probes.terminal_succeeded(all-acceptedis a success,all-closedis not) ratherthan by
"merged" in verdict.keys; the pull-request answer is unchanged. The eagerdrain's "does not push" statement in
crew_log/eager.pyis rewritten: it pushes onething, a deadline, and the module docstring says so.
Tests
test/test_probe_work_ledger.py-- one case per exit criterion of the gate: each wakingstatus,
progressnever wakes, a conductor's ownverdictnever wakes, token holds onre-read, silence wakes only with the worker not running,
worker_closedskips the window,all-closed is terminal, unreadable is not-read, budget counts distinct wakes, no config
switch, per-outcome terminal keys, explicit ledger watch ignores a PR in the same text.
test/test_conductor_wake.py-- the push: binding resolution, a conductor's ownwork/recordedpushes nothing, dedupe per batch,fire_nowrefused while a fire is inflight is not lost, the push cap, slot-close and turn-end triggers, a slot under
construction or unrestored is not closed, the restart replay fires exactly one gated tick,
the pushed-tick mark survives
_arm_timer.test/test_autonudge.py,test_work_ledger.py,test_work_ledger_board.py,test_work_ledger_tools.py,test_members_dm_thread.pyextended for the shared paths.Mutation checks: each of the round-6 fixes was run with the fix reverted (red) and applied
(green).
Manual verification
End to end on a pod built from this head, DEBUG log on, harness driving real
work_reportcalls from bound worker sessions against a conductor with an armedwatch: "work-ledger"loop. Eight scenarios, three runs each: S1 latency, S2 progressonly, S3 worker closed, S4 close after done (no second wake), S5 storm, S6 budget, S7 push
disabled (skipped: no switch exists), S8 restart (skipped on this host: the pod wipes its
data dir; covered by the unit test). 18 pass, 0 fail, 6 skipped. The S1 fire chain
(
work/recorded-> eager drain ->fire_for_worker_slot->fire_now-> probeIMMEDIATE) is visible in the pod log.The seams a human had to accept
_PERMITTED_STORE_IMPORTERSintest/test_work_ledger.pygains three entries:ledger_wake.py,probes/work_ledger.py,conductor_wake.py. The first two read theconductor's items for the loop the scheduler is already ticking (
loop.slot_key); thethird reads ONLY
read_binding, to map a worker slot the gateway itself observed to itsconductor. None resolves identity from a request body and none is model-reachable. The
third entry goes away when the push becomes a bus subscriber (see Not a goal).
Related Issues
No linked issue: Phase 3 of
docs/request-for-change/rfc-conductor-work-ledger.md(status
partial, revision v4, on main) plus the push decision recorded indocs/request-for-change/rfc-crew-log-wake.md(in this PR). A feature gets no trackingissue in this repo.
Checklist