Skip to content

docs(rfc): crew log wake -- a worker's write pulls the conductor's tick forward - #15671

Closed
chenmingwei23 wants to merge 1 commit into
mainfrom
docs/rfc-crew-log-wake
Closed

chenmingwei23 wants to merge 1 commit into
mainfrom
docs/rfc-crew-log-wake

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: record the decision that a worker's report, or its session's close, pulls its conductor's armed wake gate forward at once, so the conductor acts within seconds of the event instead of up to one patrol cadence later.

Today a conductor learns about its workers by ticking. The Phase 3 wake gate (rfc-conductor-work-ledger, in flight on #12781) makes a tick that finds nothing cost no model turn, which fixes the price of patrolling. It does not fix the delay: the gate runs on the loop's cadence (300 s by default), so a question written one second after a tick waits 299 s, and a worker session closed with its item still open is noticed only after a staleness window has also elapsed on a later tick.

The crew log's eager fold already sits on the append path and says in its own header that it does not push because "there is no consumer yet to need it". The conductor's armed gate is that consumer. The team discussion of 2026-09-30 reached the same gap from the product side (a conductor does not know when a session it opened ended) and weighed direct worker-to-conductor messaging against the crew log route; this document records the crew log route and names the one seam it needs.

An earlier draft of this design (2026-09-22, never in this tree) said "the ledger is the channel" and hooked session_ledger_record. The word has since moved: the per-unit append-only file is the crew log, and the session ledger and work ledger are two folds of it. This document hooks the log, not a fold, and says so.

Why it matters

A conductor fleet is only as responsive as its slowest wait. A worker parked on a question for a full cadence is a worker doing nothing, and a worker that died without reporting is invisible until two timers have elapsed. Closing that gap is what lets the patrol cadence move from minutes to hours, which is where the real token saving is.

Not a goal

  • Lifting the upward session_send refusal; the worker gains no handle on its conductor.
  • A general event bus, a UI push, or a per-(slot, fold) revision contract.
  • Replacing the periodic tick; it stays as the liveness fallback.
  • Any code. This PR is the design record; the implementation follows feat: wake a conductor from its work ledger instead of a timer #12781.

What changed (motivation -> approach -> change)

Goal -> approach: the cheapest push is one that moves a deadline the conductor already armed, because every cap, stop sentinel and the probe gate then apply unchanged. AutoNudgeService.fire_now is exactly that seam and its docstring states the contract. So the design adds two triggers (a work/* crew-log append from a bound worker; close_slot on a bound worker) that each resolve the binding and call fire_now on the conductor's work-ledger loop, plus one probe input (worker_closed) so a close is stale at once rather than after the window. The 2026-09-22 draft's [ledger wake] envelope, delivered map, replay sweep and one-shot scheduler deadline are dropped: with the tick kept as fallback, a lost push is caught a cadence later and none of that machinery is needed.

Change: docs/request-for-change/rfc-crew-log-wake.md (status draft) and its row in the directory README with the audit note.

Backwards compatibility

Compatible: documentation only.

Tests

N/A -- documentation only. scripts/docs-lint.sh passes on the branch with the new file indexed.

Manual verification

Every symbol the document cites was read at 321fd996a2: fire_now and its three refusals in autonudge_service/firing.py, crew_log/eager.py and its "does not push" header, work_ledger.apply_worker_report, work_ledger.read_binding, chat_handlers.close_slot, and the Phase 3 block of rfc-conductor-work-ledger.md.

Related Issues

Builds on #12781 (Phase 3 wake gate, draft) and the Phase 3 block of rfc-conductor-work-ledger.md.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 1, 2026 01:59
@chenmingwei23
chenmingwei23 force-pushed the docs/rfc-crew-log-wake branch from c9120f2 to 3f87f5c Compare October 1, 2026 02:00
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 3f87f5c6c8001c2255e4be5a2f1995f977b2b16d and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- docs/request-for-change/rfc-crew-log-wake.md:163 -- mid-fire fire_now returns 409 without latching _rearm_pending, so the report waits the hours-long cadence -> Fix: require a latched zero-delay re-arm after _firing clears.
[GPT-REVIEWED] 3f87f5c

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

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

Lossy push undercuts its own payoff: once the patrol cadence stretches to hours, every drop case parks an actionable report for hours, not minutes.

Watch

Goal 4 ("a dropped push is caught by the next scheduled tick") is priced at today's 300 s cadence, but §3.3's conclusion is "the goal-conductor skill can lengthen the patrol cadence … silence is measured in hours." §3.3 names three drop cases (eager queue drops under pressure, restart between append and drain, fire_now refused mid-fire); after the cadence moves, each one turns a worker's question into an hours-long park — the exact harm §1 set out to fix. Open question 2 waves this off, but only for progress, where loss really is free; for the actionable set it is not addressed. The cheapest fix stays inside the design's own minimalism: one re-arm-at-zero bit when fire_now is refused mid-fire, and a stated cadence floor (or max-loss bound) for the skill in step 3 of the rollout.
Clears when: the RFC bounds the worst-case delay for a lost actionable push at the lengthened cadence, or adds the end-of-cycle re-fire for refused actionable pushes.

Suggestions

  • §3.2 should state whether worker_closed is derived at probe time (slot absent) or stamped by the close_slot hook: the parent RFC explicitly chose derived-not-stamped for orphaned ("a missed hook would leave the flag wrong forever"), and a stamped flag misses workers reaped or crashed outside close_slot — derived gets trigger-two's instant wake and self-heals, so record that choice now before the implementation PR guesses.

[DESIGN-REVIEWED] 3f87f5c

Description read

[DESCRIPTION-READ] e43716cf6b17be251fdf2eee0f02108cd2080e5d3af6b6b7cc05ae82444ebfc2

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.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Closing: standalone RFC PRs are not wanted in this repository. The decision belongs in the implementing PR body.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 3f87f5c6c8001c2255e4be5a2f1995f977b2b16d — this comment is updated in place on each push.

Review details

Advisory only — nothing blocks; the RFC's prescribed seam cannot run as written and three of its code citations are wrong.

FINDING — docs/request-for-change/rfc-crew-log-wake.md:183 — "The hook runs on the eager drain thread" calling fire_now: the drain is a plain threading.Thread with no event loop (crew_log/eager.py:299, target=_run), while fire_now is a coroutine whose _arm_timer does asyncio.create_task (autonudge_service/timers.py:360), so the consumer §3.1 prescribes arms nothing from that thread and needs a loop-thread hop — a second seam §3.1's "fire_now is the right seam and the only one touched" denies → Fix: name the run_coroutine_threadsafe/call_soon_threadsafe hop in §3.1 and §5, and say which side of it resolves the binding.

FINDING — docs/request-for-change/rfc-crew-log-wake.md:125 — "chat_handlers.close_slot is the one path a dashboard session is closed through" is false: api_chat_slots_cleanup (chat_handlers.py:7923) and _remove_slot_for_history_key (handlers/sessions.py:2958) each state._slots.pop(...) plus a tombstone without calling it, so goal 2 ("wakes its conductor without waiting for a staleness window") does not hold for a live worker slot whose history row is deleted → Fix: hook the converging session/closed crew-log entry (already in eager._WAKE_TYPES) instead of close_slot, or name every close path in §3.2 and §8.

FINDING — docs/request-for-change/rfc-crew-log-wake.md:162 — "the re-arm at the end of that cycle covers the report that caused it": a dashboard-slot loop gets no end-of-cycle re-arm (firing.py:636 re-arms only is_channel_key), the mid-fire 409 records nothing in _rearm_pending, and the post-turn _arm_from_deadline reads the cleared next_due_ts = 0.0 (firing.py:594) as a fresh full countdown — so a question written while the conductor is mid-turn waits a whole cadence (hours, after §3.3) rather than §4's "seconds" → Fix: have the refused push leave a pending pull-forward (or set the deadline to now) and correct §3.4 and §7 Q2 to name the re-arm that actually runs for a dashboard slot.

FINDING — docs/request-for-change/rfc-crew-log-wake.md:100 — "apply_worker_report already appends a WORK_ENTRY_TYPE entry to the worker's crew log through the emitter" is wrong: it ends at _commit_item_locked, which writes only the item and event files, and the append is crew_log_emit.on_work_recorded at dashboard/handlers/work_ledger.py:630 — so the trigger also carries unstated preconditions (crew log enabled, append accepted) → Fix: redraw §3's diagram and §3.1 to name the handler as the append site and state those preconditions.

FINDING — docs/request-for-change/rfc-crew-log-wake.md:30 — "rebuilt by rebuild_from_crew_log" cites a function that does not exist in the tree (sole hit is a stale docstring mention at work_ledger.py:3503); the real path is work_ledger.rebuild_from_projection (work_ledger.py:2817) → Fix: cite rebuild_from_projection.

[OPUS-REVIEWED] 3f87f5c

Verdict parsed from the review's SHA-scoped output markers for commit 3f87f5c6c8001c2255e4be5a2f1995f977b2b16d.

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

@bolichen97
bolichen97 deleted the docs/rfc-crew-log-wake branch November 6, 2026 07:22
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.

1 participant