Skip to content

feat: wake a conductor from its work ledger instead of a timer - #12781

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/work-ledger-wake-gate
Oct 1, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/work-ledger-wake-gate

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

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 question 29 minutes ago is still waiting, and a worker
whose 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-ledger probe, its registration
in build, the watch field on monitor_start's schema, and the target-inference
branch. 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 watch
field. docs/request-for-change/rfc-wake-judge.md section 6 names this probe as the
typed 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, ships
INSIDE this PR (status draft), because this repository does not take standalone RFC
pull 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):

scenario result
worker reports question -> conductor turn starts 0.26 s
five progress reports 5 pushes, 0 turns
ten workers, 20 reports in 2 s 1 turn
30 question reports in one minute 6 turns, loop still armed

Not a goal

A second wake channel. Both halves reuse the watch kernel (irq.py) that already
runs 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_send refusal 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
FoldAdvanced event. 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 work fold is keyed by
the conductor's own slot.

What changed (motivation -> approach -> change)

Gate (commit 1)

Part What it does
probes/work_ledger.py reads one conductor's items and classifies them
ledger_wake.py the rules as pure functions: which statuses wake, the per-item budget, worker_closed
probes/targets.py, probes/__init__.py work_ledger_target(); the new kind is served
autonudge.py, autonudge_service/* drives the probe each tick; a pushed tick must pass the gate (the free-pass after a wake is for the scheduled tick only)
validation.py, mcp_tools/control.py, autonudge_authz.py monitor_start / monitor_update accept watch: "work-ledger" -- the one-call arm
slack/gateway.py supplies the worker_running / worker_closed resolvers from the slot table

A worker report carrying done, blocked or question wakes the conductor. A
progress report moves the token and does not wake. Every other event kind in the store
is 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 an
item several times (_EVENT_TAIL = 8 events per item per tick, plus a stale token), so
the cadence bounds ticks and the budget bounds wakes; they coincide only for an item
producing exactly one wake per tick.

Push (commit 2, #15691)

Part What it does
conductor_wake.py resolves a worker slot to its conductor's armed loop and calls fire_now; a per-item cap on pushes, separate from the cap on wakes
crew_log/eager.py the drain thread calls the push for each committed work/recorded whose writer is a bound worker, deduped per worker per batch; on the worker thread, never on the append path
dashboard/state.py a worker slot closing pushes once; ledger_wake.worker_closed counts a slot under construction, unrestored or restoring as open
dashboard/chat_handlers.py, slack/gateway.py a worker's turn ending pushes once, so a turn that died without a report is noticed
autonudge_service/timers.py, firing.py a pushed tick is marked after _arm_timer, so the mark survives; a loop restored after a gateway restart fires one immediate gated tick
probes/work_ledger.py a pushed tick's coalescing window is 0, so several workers' reports in one tick are delivered together
dashboard/handlers/work_ledger.py, work_ledger_board.py the Crew board's stale badge reads worker_closed through the same resolver as the gate, so the badge and the wake agree
docs/system-specs/modules/monitor-architecture.md the kind is reachable via monitor_start's watch; the objective row is still borrowed from review_ready (own row is a follow-up)
docs/request-for-change/rfc-crew-log-wake.md, README the decision record, with alternatives

Backwards compatibility

Compatible. The pull-request watch infers its subject exactly as before; watch is
optional and only one value is accepted. Terminal success is now declared per OUTCOME in
probes.terminal_succeeded (all-accepted is a success, all-closed is not) rather
than by "merged" in verdict.keys; the pull-request answer is unchanged. The eager
drain's "does not push" statement in crew_log/eager.py is rewritten: it pushes one
thing, a deadline, and the module docstring says so.

Tests

test/test_probe_work_ledger.py -- one case per exit criterion of the gate: each waking
status, progress never wakes, a conductor's own verdict never wakes, token holds on
re-read, silence wakes only with the worker not running, worker_closed skips 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 own
work/recorded pushes nothing, dedupe per batch, fire_now refused while a fire is in
flight 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.py extended 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_report calls from bound worker sessions against a conductor with an armed
watch: "work-ledger" loop. Eight scenarios, three runs each: S1 latency, S2 progress
only, 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 -> probe
IMMEDIATE) is visible in the pod log.

The seams a human had to accept

_PERMITTED_STORE_IMPORTERS in test/test_work_ledger.py gains three entries:
ledger_wake.py, probes/work_ledger.py, conductor_wake.py. The first two read the
conductor's items for the loop the scheduler is already ticking (loop.slot_key); the
third reads ONLY read_binding, to map a worker slot the gateway itself observed to its
conductor. 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 in
docs/request-for-change/rfc-crew-log-wake.md (in this PR). A feature gets no tracking
issue in this repo.

Checklist

  • At most two commits (one per half), each 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: monitor-architecture spec, RFC + README
  • No secrets, credentials, or internal references in the diff

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

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.
Not a goal: changing the Crew page, the conductor skills or brief templates, the session ledger, or what any already-armed loop watches.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 68c57f67467c33549114575071ba1da27abc73e5 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 68c57f6

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

@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 Sep 22, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/work-ledger-wake-gate branch from 5541950 to 6db2248 Compare September 22, 2026 11:06
@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 Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

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

  • rfc-conductor-work-ledger.md (unchanged by this diff) states "the two _PERMITTED_STORE_IMPORTERS entries are a human's edit, by design… the entries belong to whoever accepts the seam, not to the change that needs them", and that test_only_the_phase_2_seams_import_the_module is expected red on this branch. The diff instead edits the allowlist in test/test_work_ledger.py to admit probes/work_ledger.py and conductor_wake.py (and rewrites the header from "argue for itself in review" to "argue for itself HERE, in its own comment"), so the guard's review-forcing red never fires and the seams are accepted by the change that needs them. The paragraph is also now stale twice over: ledger_wake.py no longer imports the store, and the branch is green.
    Clears when: a maintainer explicitly accepts the two seams (comment or commit), and the rfc-conductor-work-ledger allowlist paragraph is updated in the same PR to record that acceptance.
  • Authorization audit records for work-ledger watches name the borrowed pull-request review_ready objective (per the monitor-architecture hunk: "the authorization audit record names that borrowed objective"). Audit rows are durable, so every row minted before the registry-row follow-up permanently mislabels the kind's objective in a governance-adjacent record.
    Clears when: the named follow-up (registry row + per-kind objective stamp) lands, or the PR states that interim audit rows carrying review_ready are acceptable.

[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 .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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 68c57f67467c33549114575071ba1da27abc73e5 — 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: 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

  • Item 3 (with items 5–7) — no recorded decision: the description concedes it — "The push half has no decision record on main"; rfc-crew-log-wake.md ships inside the PR, which is a proposal, not a record (whether these timing changes to an opt-in watch are product shape took argument, so this stays advisory rather than a block).
    Clears when: a maintainer records /ai-review override first-principles 68c57f67467c33549114575071ba1da27abc73e5: <decision>, or rfc-crew-log-wake.md merges non-draft on the base branch and the author pushes or rebases.
  • Item 9 — rewritten pin: the base RFC and the test's own comment record "the entries belong to whoever accepts the seam, not to the change that needs them" and "must argue for itself in review rather than arrive with a passing suite"; this diff adds probes/work_ledger.py and conductor_wake.py to _PERMITTED_STORE_IMPORTERS itself and softens the comment to "argue for itself HERE, in its own comment", shipping green the red the pin called "the guard working as specified".
    Clears when: a maintainer explicitly accepts the two store seams on this head (their own edit or a recorded approval), or the PR cites evidence the pin's rule was wrong.

What this change ships

Inventory (10 items) — 5 justified

Intent: 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.

  1. watch: "work-ledger" on monitor_start/monitor_update arms a ledger-gated loop in one call — justified
  2. A conductor tick where no worker said anything actionable spends no model turn — justified
  3. A worker's report, session close, or turn end pulls the conductor's next tick forward within seconds — no recorded decision (draft RFC inside this PR)
  4. A finished ledger ends its watch recorded as success instead of blocked — justified
  5. Crew board stale badge flags a reported-then-closed worker at once, skipping the window — no recorded decision (same draft RFC, §3.2)
  6. A restored work-ledger loop fires one immediate gated tick at gateway boot instead of waiting its deadline — no recorded decision (same draft RFC, §3.2c)
  7. A pushed tick never spends the post-wake free follow-up, and a quiet push keeps the earlier deadline — no recorded decision (same draft RFC, §3.4)
  8. Per-item budgets: 12 wakes/hour (persisted) and 12 pull-forwards/hour (in-memory) — justified
  9. _PERMITTED_STORE_IMPORTERS gains two entries added by the change that needs them — rewritten pin
  10. New RFC rfc-crew-log-wake.md, its README row, and the monitor-architecture spec update — justified

[FIRST-PRINCIPLES-REVIEWED] 68c57f6

Description read

[DESCRIPTION-READ] b81d4e8f9fe33eb8b71ea634f573891417ff0a6f4b530342f41ef0dc57ccc592

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 Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

2 advisory findings; nothing blocks the merge.

FINDING — src/kiro_crew/crew_log/eager.py:526 — seen: set[str] dedupes by worker slot while the batch it walks is keyed (unit_id, board), so a nested conductor's own-board work/recorded entry drained first consumes the slot and the sibling entry carrying the parent's board is skipped, leaving fire_for_worker_slot_from_thread refused on expected_board != binding[0] and the parent never pulled forward for a report that did land → Fix: key the dedupe as (slot, wake.board), or only seen.add(slot) when the push returns True.

FINDING — src/kiro_crew/probes/work_ledger.py:263 — _item_observations' docstring asserts "Every observation here is IMMEDIATE, not WAKE" while the body emits irq.Severity.WAKE twice and the sibling tuning() docstring argues the opposite ("WAKE rather than IMMEDIATE") → Fix: restate the docstring as WAKE delivered at once because this probe's tuning() sets coalesce_secs to 0, keeping the latency argument.

[OPUS-REVIEWED] 68c57f6

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

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

@chenmingwei23
chenmingwei23 force-pushed the feat/work-ledger-wake-gate branch from 6db2248 to 8790b5f Compare September 22, 2026 11:53
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_instances.py (import) since this head went green (80bd0a8 -> ff30e06); CI re-running.

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

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: slot-table liveness resolver injected at the gateway construction site

  • Production AutoNudgeService passes no worker_running (span=f357cc5b557e)

fixed. The finding is correct and the defect was mine: the resolver was designed as an injected value and never wired, so every worker read as idle and the description's claim about a worker in a long build was false as shipped.
slack/gateway.py now defines a slot-table resolver beside the existing _monitor_owner_session_id closure and passes it as worker_running. It tries both slot spellings and reads running, not merely open, which is the same lookup the work ledger's own HTTP reader performs.
Verified by the probe test that records which liveness answer the store's is_stale was asked with.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: slot-table liveness resolver injected at the gateway construction site

  • Item 5, zero consumers for worker_running (span=775ec85e735e)

fixed. Same defect as the design lane's, and the same remedy: the sole production construction site now injects the resolver, so the seam has a consumer rather than a named follow-up.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

mechanism: the per-tick config read is gone, not moved

  • synchronous config loading blocks monitor ticks (span=1c5c73f18adb)

fixed, and by removal. The finding is correct: KiroCrewConfig.load caches the merged dict but still makes a stat pass per call, so the read was filesystem work on the event loop every tick.
I had justified it from the method's own docstring, which claims it adds no filesystem I/O on the loop. The docstring overstates: the cache lookup and the freshness check share one stat.
The switch it read is deleted outright (see span=15137de977ab), so no config is read on the tick path at all. Nothing was moved to a thread, because there is nothing left to move.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

mechanism: LedgerWakeConfig, its loader field and its reader are deleted

  • ledger_wake is never hydrated by _load_resolved (span=15137de977ab)

fixed by taking the recommended subtraction. The finding is exactly right: sections are hydrated by an explicit _coerced_section line and I never wrote one, so a persisted enabled=false was ignored and the switch only ever returned its default.
My test passed because it built the dataclass directly instead of loading config, which is why a decorative switch read as working.
Removed rather than hydrated: the RFC's Phase 3 scope does not include a switch, arming is already opt-in, and a loop is already stoppable. config-baseline.json is regenerated accordingly.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

mechanism: the rate file remembers several recently charged tokens, not one

  • two stable tokens per tick defeat the single last_token exemption (span=9d8679067077)

fixed. The finding is correct and precise: an item whose worker reported blocked or question and then stalled produces both the report event id and the silence token in the same tick, and with one remembered token each evicted the other and re-charged it, emptying a twelve-per-hour budget in six ticks.
recent_tokens now holds up to four, newest first, and the reader tolerates the older single last_token spelling on disk so an upgrade does not re-charge live wakes.
Covered by a test that spends the budget with distinct tokens and then re-asks with an already-charged one.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

mechanism: the watch FieldSpec is removed from MONITOR_UPDATE_SCHEMA

  • Item 3, zero consumers on the update path (span=f195a267c45b)

fixed by taking the subtraction. The finding is correct: no update path reads watch, so the field validated an argument that changed nothing, and the RFC's Phase 3 scope names monitor_start alone.
The field now exists on the arm schema only, and a test asserts the update schema carries none, so the absence is pinned rather than incidental.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

mechanism: LedgerWakeConfig, the loader field, the reader and the probe parameter are deleted

  • Item 8, ledger_wake.enabled is outside the recorded Phase 3 scope (span=18b39edc5d35)

fixed by taking the subtraction, and the GPT lane independently found the switch was never hydrated, so it could not have honoured a persisted value anyway.
Your named-harm test is the right bar and it is not met: arming requires a conductor to name the subject, and the loop is already stoppable, so the third off-position had one consumer and no harm it uniquely covered.
The section's own text still described the withdrawn session-ledger design, which is a second reason it should not ship.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • Incomplete by construction, the pending maintainer edits are the feature (span=541bf8eaaaa2)

needs-a-decision, and the finding is accepted as stated. This branch cannot contain either half: both files are write-protected for the author, and one of them is the store-import allowlist, which is the boundary itself, so an agent adding its own entry would be stepping over the rule the list draws.
Put to the maintainer directly, no issue filed: apply the add_kwargs forward in autonudge_authz.py and the two _PERMITTED_STORE_IMPORTERS entries, or rule that the gate must reach the store through an already-listed seam instead. The argument for the seam is in the description.
The PR stays a draft until then. It is not asking to merge incomplete.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • Item 2, the arm chain has four seams and this branch carries one (span=e0cb412ced1f)

needs-a-decision, and the finding corrected a false claim in the description, which now names all four seams: the schema here, the monitor_start directive payload, the applier that drops unlisted fields, and the write-protected forward.
The author is scoped out of the two middle files by the dispatching conductor, so this cannot be closed by writing them here.
Put to the maintainer directly: widen this PR's scope to the payload and applier, or keep them named as pending. Until one or the other, the field validates and nothing arms.

@chenmingwei23
chenmingwei23 force-pushed the feat/work-ledger-wake-gate branch from 8790b5f to 2c9610f Compare September 22, 2026 12:13
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 22, 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.

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.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

@iamwhatever — re: "Require some more discussions on this method" (reviewed at a375411812). Here is the method as it stands on the current head 4c2a51facec643e8ea9f1295d216bbb58104bf9c, and what changed since you reviewed.

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 work-ledger kind it is the arming session itself, resolved from the loop's slot_key rather than from the instruction text, so rewording an instruction cannot silently disarm the watch.

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 (within_rate_limit), and the rate-file write in note_wake refuses rather than proceeds when its parent directory is a link/junction. An unknown worker-liveness reads as "not running" — the fail-open direction that can only add a wake, never suppress one. Ending a watch is the one action a conductor cannot recover by waiting, so terminal is decided only by a kernel-attributed Severity.TERMINAL key (all-accepted = success), never by parsing prose.

What changed since a375411812:

  1. Rebased onto current main, which had extracted AutoNudgeService into the autonudge_service package (subject/mutations/gate/timers/…). All of the method's semantic deltas were relocated onto the new submodule homes (subject-inference threading → subject.py; the arm-chain watch kwarg, (gate or watch) monitor construction and the update rebind → mutations.py; the terminal-gate disjunct and probe-build wiring → gate.py), and the signature-hash refactor-contract manifest was re-pinned for the five changed/added members.
  2. Hardened the rate-file redirect guard (bolichen97's finding). note_wake's guard was parent.is_symlink(), which returns False for a Windows directory junction and left the same redirect open on Windows. It is now platform_compat.is_link_or_junction(parent) — it screens the parent and refuses (returns False) on any link/junction, never traversing one; it is recorded as a refuse-site in the link-screen baseline (not a vets-then-continue HELD_SITE). A junction-parity test exercises it on the platform the gap was reachable on.
  3. Added test coverage for the new branches: a service-level watch="work-ledger" arming test (covering the mutations.py threading and the subject.loop_subject re-derivation) and the junction-parity redirect test.

Current state: PR Readiness = success on 4c2a51face; black/isort/flake8/mypy clean; the touched-file suites pass. Re-requesting your review.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ⏭️ skipped

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

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.
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.

3 participants