tumwater 0.2.0 → 0.3.0

package/dist/src/orchestrator/orchestrator-scheduling.js

@@ -1,383 +1,48 @@
-// vocabulary: plain
 /** The poll loop's per-runner scheduling pass (src/orchestrator/orchestrator.ts): decide, for each
- * runner, whether this poll admits a tick and why — the pause/quiet/cost-cap/failure-hold
+ * runner, whether this poll admits a run and why — the pause/quiet/cost-cap/failure-hold
  * gates, the merge-queue interlock, need-based deferral, and once-mode settlement —
- * producing the reasons map orchestrator-launch.ts's launchDueTicks starts ticks from.
+ * producing the reasons map orchestrator-launch.ts's launchDueRuns starts runs from.
  * Split out of runOrchestrator's poll body so the WHY-due policy reads on its own screen;
- * the poll body keeps the poll's other passes (config reload, markers, gates, redeploy,
+ * orchestrator-poll.ts keeps the poll's other passes (config reload, markers, gates, redeploy,
  * merge drain) and the launch call itself. */
 import { increment } from "../collections.js";
-import { reviewRunConfig, seamHoldKey } from "../config/config-views.js";
-import { deferTickReason, isEligible } from "../scheduling/scheduling.js";
-import { BUGFIX_ROLE, DIRECTOR_ROLE, commitTier } from "../roles/roles.js";
-import { baseRoleOf, instanceIndex, loopEnabled, loopPaused } from "../roles/loop-ids.js";
-import { hasOutstandingWork, saveLoopState } from "../loop/loop-state.js";
-import { inboxSize } from "../inbox/inbox.js";
-import { briefStatusIncomplete } from "../brief/brief.js";
-import { queuedMergeRoles } from "../merge/merge-queue.js";
-import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { reviewRunConfig, roleSeamTier, seamHoldKey } from "../config/config-views.js";
+import { openBugs } from "../backlog/backlog.js";
+import { fallbackProbeDuePair } from "../budget/fallback-breaker.js";
+import { modelPairName } from "../budget/budget.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 import { eligibleEntries } from "../backlog/backlog-eligibility.js";
-import { CLAIM_IDLE_MAX_MS, assignNext, claimReleaseReason, heldKeys, listedKeys, } from "../scheduling/claims.js";
-/** Record why the poll skipped a due loop on its state (LoopState.skipReason), saving only when
- * the value changes: a skipped loop gets no tick to save its own state, and a loop that stays
- * skipped must not rewrite its file every poll. */
-function noteSkip(root, runner, reason) {
-    if (runner.state.skipReason === reason)
-        return;
-    runner.state.skipReason = reason;
-    saveLoopState(root, runner.state);
-}
+import { planBacklogFull } from "../scheduling/claims.js";
+import { admitRunner } from "./scheduling-admit.js";
+import { skipRunner } from "./scheduling-skip.js";
+import { buildSchedulingScope, noteSkip, } from "./scheduling-scope.js";
 /** Decide which runners are due this poll. Mutates `deferredDue` (and once-mode settlement)
- * as its only side effects; returns the reason per admitted runner. */
+ * as its only side effects; returns the reason per admitted runner. The once-per-poll
+ * precompute lives on the scope scheduling-scope.ts's buildSchedulingScope builds (the
+ * merge-queue snapshot, director pin, per-base claim groups, gate predicates and admission
+ * state); this per-runner loop reads them all through it. */
 export async function pollRunnerReasons(ctx) {
-    const { root, runners, once, now, mainHead, userPaused, quietNow, pausedRoles: pausedRolesSet, capPaused, maintenanceQuota, bootstrapHeld, bootstrapActive, budgetPausedRoles, probeRoles, reviewStrongPaused, roleQuietHeld, heldProviders, windowHeldProviders, reviewHeld, roleProviders, openBugsNow, workBacklogOpen, planBacklogFull, holdForRestart, diskHeld, deferredDue, workMergedSince, } = ctx;
-    const reasons = new Map();
-    // Computed ONCE per poll (the plan tight-loop rule, src/brief/brief.ts): the flag means the
-    // brief's status section is still the placeholder, read once from the resolved brief so the
-    // whole pass agrees on it — the pass already holds root for its other per-poll reads.
-    const descriptionIncomplete = briefStatusIncomplete(root);
-    // Merge-queue interlock data, listed ONCE per poll (was once per runner per poll — each
-    // queuedMergeFiles() re-lists the merge-queue directory and re-stats every queued entry): the
-    // check below only asks whether the runner's role has a queued entry. The queue changes
-    // only when a merge completes or a tick enqueues — both asynchronous events this pass
-    // observes on its next poll — so one snapshot is as fresh as per-runner reads, and a
-    // merge that completes mid-pass just keeps its role blocked one extra poll (conservative).
-    const queuedRoles = queuedMergeRoles(root);
-    // Parallel work instances (plans/parallel-work-instances.md "Claims", part 4/7): a base role
-    // with more than one runner assigns each due instance a distinct eligible entry, and releases
-    // the claims whose entry left, turned ineligible, was disabled or went stale. Computed once
-    // per poll and only for a multi-runner base, so a single-runner team is unchanged. The
-    // release runs before assignment so a freed key counts as free below.
-    const claimGroups = new Map();
-    const baseCounts = new Map();
-    for (const runner of runners) {
-        const base = baseRoleOf(runner.role);
-        increment(baseCounts, base);
-    }
-    for (const [base, count] of baseCounts) {
-        if (count <= 1)
-            continue;
-        const groupRunners = runners.filter((r) => baseRoleOf(r.role) === base);
-        const eligible = eligibleEntries(root, base);
-        const eligibleKeys = new Set(eligible.map((e) => e.key));
-        const listed = listedKeys(root, base);
-        // A group whose runner is mid-entry with no recorded claim (it took the entry while it was
-        // the only runner, before a live reload raised `instances`) cannot be told WHICH entry that
-        // is from state alone. Assigning a free entry to a sibling could then hand it the same
-        // work: hold the whole group's assignment until that runner settles (merges, drops or goes
-        // idle), at which point its own staging may have recorded a claim. A busy runner that DOES
-        // hold a claim is fine — `held` excludes its key and siblings take other entries.
-        let hold = false;
-        for (const r of groupRunners) {
-            const busy = r.state.running ||
-                queuedRoles.has(r.role) ||
-                hasOutstandingWork(r.state);
-            if (r.state.claim === undefined && busy)
-                hold = true;
-            const released = claimReleaseReason(r, {
-                listedKeys: listed,
-                eligibleKeys,
-                now,
-                hasQueuedMerge: queuedRoles.has(r.role),
-                // Per instance, not per base role: a lowered `instances` leaves the surplus runner in
-                // place with `loopEnabled` false, and its idle claim must be released so a sibling can
-                // take the entry instead of the key staying held until the 24h stale sweep.
-                enabled: loopEnabled(r.config, r.role),
-                // Only this instance paused (not its whole role; instance 1 under `<role>-1`): a sibling
-                // can take the entry. With the base role paused no sibling runs, so the claim stays.
-                paused: loopPaused(pausedRolesSet, r.role) && !pausedRolesSet.has(base),
-            });
-            if (released === null)
-                continue;
-            const title = r.state.claim?.title ?? "";
-            r.state.claim = undefined;
-            // Persist the release: an idle extra instance gets no tick to save its state, so the dead
-            // claim would stay on disk for status/doctor to show and for a restart to release again.
-            saveLoopState(root, r.state);
-            const reason = released;
-            logEventBestEffort(root, { source: r.role, type: "claim", action: "released", title, reason });
-            if (reason === "stale") {
-                warnEventBestEffort(root, r.role, `released "${title}", which a stopped instance was working on (idle ${Math.round(CLAIM_IDLE_MAX_MS / 3_600_000)}h)`);
-            }
-        }
-        claimGroups.set(base, {
-            eligible,
-            eligibleKeys,
-            held: heldKeys(groupRunners, eligibleKeys, listed),
-            hold,
-        });
-    }
-    // The team gates' block predicate (the director exempt — an explicit human prompt
-    // outranks any autonomous gate, quiet hours included): the once-mode settle below and
-    // the start gate must agree on exactly when a team gate holds, so the compound lives
-    // here once. Quiet hours fold in beside the operator pause and the budget gate — the
-    // schedule is not probe-worthy the way a paused budget is, so no probeDue exception.
-    // The per-role windows (quietHoursPerRole) fold in beside the team one as a fourth
-    // disjunct — a role held by either window (or both, held once) starts no new ticks;
-    // the director stays exempt by the same role check that covers the other disjuncts.
-    // The budget hold, per role (part 5c/8): a tier that resolved to pause holds its own roles,
-    // and — with review on — an unresolvable strong tier holds every role (nothing could merge).
-    // The probe of a demoted pair pierces the hold for EXACTLY the probed pair's tier's roles:
-    // the earlier draft's pair-blind pierce lifted the pause team-wide on any due probe.
-    // Quiet hours fold in beside the operator pause — the schedule is not probe-worthy the way a
-    // paused budget is.
-    const budgetHolds = (role) => (reviewStrongPaused || budgetPausedRoles.has(role)) && !probeRoles.has(role);
-    const operatorPauseBlocks = (role) => (userPaused || quietNow || roleQuietHeld.has(role) || budgetHolds(role)) &&
-        role !== DIRECTOR_ROLE;
-    // Fresh operator demand: a queued prompt or a wake newer than the loop's last tick end. The
-    // same override the need-based deferral honors (an explicit "try again now" is not idle
-    // maintenance); shared by the bootstrap and maintenance-allowance holds so the two cannot
-    // drift on what counts as demand.
-    const hasDemand = (runner) => inboxSize(root, runner.role) > 0 ||
-        (runner.state.wokenAt !== undefined && runner.state.wokenAt > (runner.state.lastRunEndedAt ?? 0));
-    // The new-project bootstrap hold (part 2/2): held unless the loop has a fresh operator wake
-    // or a queued prompt.
-    const bootstrapHeldNow = (runner) => bootstrapHeld.has(runner.role) && !hasDemand(runner);
-    // The maintenance allowance's team-level hold (part 1b/4): `used` has reached `allowance`,
-    // so no maintenance loop starts unless it carries demand (`tumwater wake <maintenance-role>`
-    // runs exactly one tick). The per-poll admission headroom is spent separately, after each
-    // loop's due check, where the pass knows what actually ticks; the verdict alone cannot.
-    const maintenanceQuotaOverLine = (runner) => commitTier(baseRoleOf(runner.role)) === "maintenance" &&
-        maintenanceQuota.used >= maintenanceQuota.allowance &&
-        !hasDemand(runner);
-    // The one-poll admission budget: each due maintenance loop this pass admits spends one of
-    // the remaining `allowance - used` slots, reset every pass, so two due maintenance loops
-    // cannot start in the same poll and overshoot the allowance.
-    let maintenanceQuotaAdmitted = 0;
-    // The stand-down's eligible lists per base role, read at most once per poll (see the check
-    // below).
-    const eligibleMemo = new Map();
-    for (const runner of runners) {
-        // Once mode: a paused role runs no tick this round and must be reported as skipped,
-        // so it settles here — before the gates that would otherwise skip it silently (a
-        // once round has to end even when a pause marker is left over; a later resume within
-        // the same round cannot un-settle it, which is the at-most-one-tick contract).
-        if (once.active &&
-            !once.isSettled(runner) &&
-            !runner.state.running &&
-            (loopPaused(pausedRolesSet, runner.role) ||
-                capPaused.has(runner.role) ||
-                maintenanceQuotaOverLine(runner) ||
-                bootstrapHeldNow(runner) ||
-                operatorPauseBlocks(runner.role))) {
-            once.settle(runner.role, "paused");
-        }
-        // Once mode's at-most-one-tick contract (src/scheduling/once-round.ts): a role that already ran
-        // its tick — or was settled with a skip reason — runs nothing further this round, even
-        // when its backoff has expired or the clock override would admit it again. Without this
-        // gate the one-tick guarantee held only for deferrable built-ins (their deferral
-        // settles them); a custom loop or work role with a short backoff re-qualified every
-        // poll and the round never ended.
-        if (once.active && !runner.state.running && once.isSettled(runner))
-            continue;
-        if (holdForRestart || diskHeld)
-            continue; // a restart or a low disk is pending: nothing new starts, on any loop
-        // The per-role pause gates BEFORE the team check and exempts nothing — the director
-        // included (the operator named that one loop deliberately).
-        if (loopPaused(pausedRolesSet, runner.role))
+    const scope = await buildSchedulingScope(ctx);
+    const { root, writing, reasons } = scope;
+    for (const runner of scope.ordered) {
+        // The WHY-due policy: every gate that decides this runner is due or skipped, and the
+        // once/deferral bookkeeping that travels with them, lives in scheduling-skip.ts's
+        // skipRunner. What follows is only the claim-admission tail (part 3/3, scheduling-admit.ts).
+        const verdict = await skipRunner(scope, runner);
+        if (verdict.skip)
             continue;
-        // The role's own daily cost cap (src/gates/role-cap-gates.ts): no start-gate change — a
-        // parked waiter finishes (in-flight ticks finish, NEW ticks are gated at scheduling,
-        // exactly like every per-role pause), and there is no fallback-probe exception: the
-        // stop is about spend, and probing it adds noise, not signal. The lift is a live
-        // config edit or local midnight — no marker exists for `resume --role` to touch.
-        if (capPaused.has(runner.role))
-            continue;
-        // The maintenance allowance (plans/work-ratio.md, part 1b/4): no new maintenance tick while
-        // the rolling 24 h window is over its line. A fresh operator wake or a queued prompt admits
-        // one anyway (maintenanceQuotaOverLine), the same demand override the bootstrap hold honors.
-        if (maintenanceQuotaOverLine(runner))
-            continue;
-        // The new-project bootstrap (part 2/2): no new maintenance ticks until the plan target is
-        // met; a fresh wake or queued prompt admits one anyway (bootstrapHeldNow).
-        if (bootstrapHeldNow(runner))
-            continue;
-        if (operatorPauseBlocks(runner.role))
-            continue; // no new role ticks while either gate holds
-        // The director honors only the subscription-window hold: the per-run 429 retry that backs
-        // its other exemptions does not answer a window rejection, so its prompt would fail and
-        // re-queue every poll until the repeated-failure pause stops it.
-        if (runner.role === DIRECTOR_ROLE && windowHeldProviders.has(roleProviders.get(runner.role)))
-            continue;
-        if (runner.role !== DIRECTOR_ROLE &&
-            (reviewHeld || heldProviders.has(roleProviders.get(runner.role))))
-            continue; // nor while ITS provider's failure storm holds — or the reviewer's (nothing could merge)
-        // The loop's OWN queue decides inbox due-ness: the director counts its historical
-        // inbox, every other loop its per-role queue (tumwater prompt --role <id>) — so a
-        // queued prompt makes its loop due by itself, no wake marker needed (isEligible).
-        const { run, reason } = isEligible(runner, now, mainHead, inboxSize(root, runner.role), {
-            once: once.active,
-            bootstrapActive,
-            descriptionIncomplete,
-        });
-        if (!run) {
-            // Not due this poll: any deferral episode has ended (or never started). No event —
-            // the tick's own events cover it.
-            if (deferredDue.get(runner.role))
-                deferredDue.set(runner.role, false);
-            // Once mode: idle and not due — settleSkipped records the skip reason (the caller's
-            // summary reports it).
-            if (once.active && !runner.state.running)
-                once.settleSkipped(runner);
+        const reason = verdict.reason;
+        // Post-gate admission (part 3/3, scheduling-admit.ts): the stand-down turn-down and the
+        // parallel-work-instance claim assignment, after every skip gate has admitted this runner.
+        // Returns "skipped" having recorded its skip reason and settled its once answer; "admitted"
+        // runs the binder: the final noteSkip, the reasons entry and the writing increment.
+        if (admitRunner(scope, runner, reason) === "admitted") {
             noteSkip(root, runner, undefined);
-            continue;
+            reasons.set(runner, reason);
+            if (scope.claimGroups.has(baseRoleOf(runner.role)) && !runner.state.running)
+                increment(writing, baseRoleOf(runner.role));
         }
-        // Merge queue 3/5 interlock (invariant 3): a role with a QUEUED or IN-FLIGHT merge never
-        // starts a tick — the entry stays in the queue until its merge completes, so one check
-        // covers both. Uniform over every role, director included: its prompt is not finished until it
-        // merges. Placed before the need-based deferral block on purpose — no episode bookkeeping is
-        // needed (the tick that queued the merge ran, which closed any deferral episode; its `queued`
-        // can leave a prior no_change in lastResult — loop-state.ts records only completed results
-        // — but the merge's outcome replaces it before the interlock lets the role back into this
-        // pass), and skipping here saves that branch's workMergedSince git-range query for the skipped
-        // role.
-        if (queuedRoles.has(runner.role)) {
-            noteSkip(root, runner, undefined);
-            continue;
-        }
-        // Need-based deferral: a due maintenance tick (scheduled or main-moved wake) whose last
-        // tick did nothing stays deferred while the feature/bugfix backlog is open or no new
-        // work has merged to react to — nextRunAt is left untouched, so it re-checks every poll
-        // until the backlog drains and qualifying work merges. Resume wakes precede this check in
-        // isEligible, the director's "inbox" reason skips it, work roles are not in
-        // DEFERRABLE_ROLES (bugfix is the exception while its backlog is empty — deferTick), and
-        // a fresh operator wake overrides it (deferTick's woken check — an explicit "try again
-        // now" is a demand, not idle maintenance). Sitting before reasons.set also keeps a
-        // deferred role out of the wake-event pass below.
-        if (reason === "scheduled" || reason === "main moved") {
-            const s = runner.state;
-            // The git range is only consulted when the other conditions already hold — a
-            // never-ticked role or a tick with pending business runs without paying for it, and an
-            // open backlog defers regardless of what merged. bugfix in search mode is the
-            // exception: its deferral keys on the work-merged verdict alone, so the backlog-open
-            // shortcut must not stand in for the query.
-            const searchBugfix = baseRoleOf(runner.role) === BUGFIX_ROLE && !openBugsNow;
-            const merged = (!workBacklogOpen || searchBugfix) && s.lastMainHead !== ""
-                ? await workMergedSince.since(s.lastMainHead, mainHead)
-                : true;
-            const deferral = deferTickReason(s, runner.role, merged, workBacklogOpen, openBugsNow, now, planBacklogFull);
-            const deferredNow = deferral !== null;
-            if (deferredNow !== (deferredDue.get(runner.role) ?? false)) {
-                if (deferral)
-                    logEventBestEffort(root, { source: runner.role, type: "run_deferred", reason: deferral });
-                deferredDue.set(runner.role, deferredNow);
-            }
-            if (deferredNow) {
-                // Once mode: a deferred maintenance tick decided not to run — its once-round
-                // answer, so it settles instead of holding the round open for DEFER_MAX_MS.
-                if (once.active)
-                    once.settle(runner.role, "deferred");
-                noteSkip(root, runner, deferral === "backlog"
-                    ? "deferred-backlog"
-                    : deferral === "plans-full"
-                        ? "deferred-plans-full"
-                        : "deferred-no-work");
-                continue;
-            }
-        }
-        else if (deferredDue.get(runner.role)) {
-            deferredDue.set(runner.role, false); // an inbox/resume run ends the episode
-        }
-        // The allowance's in-flight admission (plans/work-ratio.md, part 1b/4): `used` counts the
-        // maintenance loops already in flight, so a due maintenance tick admitted here spends one
-        // of the remaining `allowance - used` slots. This must sit after the due check — the pure
-        // verdict cannot know which loops will be eligible this poll, so the reservation lives in
-        // the pass that does; without it two due maintenance loops start in the same poll. Demand
-        // spends no slot: it is an explicit operator request, not idle maintenance.
-        if (commitTier(baseRoleOf(runner.role)) === "maintenance" && !hasDemand(runner)) {
-            if (maintenanceQuotaAdmitted >= maintenanceQuota.allowance - maintenanceQuota.used) {
-                noteSkip(root, runner, undefined);
-                continue;
-            }
-            maintenanceQuotaAdmitted++;
-        }
-        // Parallel work instances (part 4/7): a multi-runner base role's claim assignment, after
-        // every gate has admitted this runner. A runner that already holds a claim proceeds — its
-        // revision, resume or retry is the same entry. An unclaimed runner with outstanding work
-        // (a revision) is the mid-entry runner the group hold waits on: it proceeds unassigned —
-        // holding it too would deadlock the whole group, since only its tick can settle the hold.
-        // Otherwise, when the tick is not an inbox/resume run, it takes the first free entry; an
-        // extra instance with none free is skipped without touching its backoff, and the primary
-        // runs unassigned only while some eligible entry exists (all of them held by siblings).
-        // Stand-down: the feature charter says "If PLANS.md is empty or everything is done, there is
-        // nothing to do" and the bugfix charter says "when every open entry carries [a Refused note],
-        // there is nothing to do", so a feature runner (primary included) with no eligible plan at all,
-        // or a bugfix runner whose open bugs are all held (no open bugs at all is search mode, which
-        // still runs), skips its scheduled and main-moved ticks instead of paying a model run that
-        // can only end in
-        // nothing-to-do. Startup, inbox and resume ticks, a fresh operator wake, and a runner with a
-        // claim or outstanding work still run. nextRunAt and backoff stay put, so the first poll
-        // after a plan turns eligible ticks it.
-        const standDownBase = baseRoleOf(runner.role);
-        if ((standDownBase === "feature" || (standDownBase === BUGFIX_ROLE && openBugsNow)) &&
-            (reason === "scheduled" || reason === "main moved") &&
-            !(runner.state.wokenAt !== undefined && runner.state.wokenAt > (runner.state.lastRunEndedAt ?? 0)) &&
-            runner.state.claim === undefined &&
-            !hasOutstandingWork(runner.state)) {
-            let eligible = eligibleMemo.get(standDownBase);
-            if (eligible === undefined) {
-                eligible = claimGroups.get(standDownBase)?.eligible ?? eligibleEntries(root, standDownBase);
-                eligibleMemo.set(standDownBase, eligible);
-            }
-            if (eligible.length === 0) {
-                noteSkip(root, runner, "no-free-entry");
-                runner.state.heldElsewhere = undefined;
-                if (once.active)
-                    once.settle(runner.role, "no free entry");
-                continue;
-            }
-        }
-        const claimGroup = claimGroups.get(baseRoleOf(runner.role));
-        if (claimGroup) {
-            if (runner.state.claim) {
-                // keeps its claim
-            }
-            else if (hasOutstandingWork(runner.state)) {
-                // finishes its own unrecorded entry
-            }
-            else if (reason !== "inbox" && reason !== "resume") {
-                // The group holds an unclaimed mid-entry sibling: assign nothing this poll, or a
-                // sibling could be handed that same entry (the reported `feature-2`/`bugfix-2`
-                // duplication). It resolves the moment the sibling settles.
-                if (claimGroup.hold) {
-                    noteSkip(root, runner, "claim-hold");
-                    continue;
-                }
-                const free = claimGroup.eligible.filter((e) => !claimGroup.held.has(e.key));
-                const pick = assignNext(free);
-                // An unassigned runner is told which entries its siblings hold (cleared when none).
-                const heldTitles = claimGroup.eligible.filter((e) => claimGroup.held.has(e.key)).map((e) => e.title);
-                runner.state.heldElsewhere = !pick && heldTitles.length > 0 ? heldTitles : undefined;
-                if (pick) {
-                    runner.state.claim = {
-                        file: baseRoleOf(runner.role) === BUGFIX_ROLE ? "BUGS.md" : "PLANS.md",
-                        key: pick.key,
-                        title: pick.title,
-                        at: now,
-                        source: "assigned",
-                    };
-                    claimGroup.held.add(pick.key);
-                    logEventBestEffort(root, {
-                        source: runner.role,
-                        type: "claim",
-                        action: "assigned",
-                        key: pick.key,
-                        title: pick.title,
-                    });
-                }
-                else if (instanceIndex(runner.role) >= 2) {
-                    noteSkip(root, runner, "no-free-entry");
-                    if (once.active)
-                        once.settle(runner.role, "no free entry");
-                    continue; // an idle extra instance: no tick, no backoff climb
-                }
-            }
-        }
-        else {
-            runner.state.heldElsewhere = undefined; // no claim group (e.g. instances lowered to 1)
-        }
-        noteSkip(root, runner, undefined);
-        reasons.set(runner, reason);
     }
     return reasons;
 }
@@ -387,3 +52,37 @@ export async function pollRunnerReasons(ctx) {
 export function reviewHoldKey(roleConfig) {
     return seamHoldKey(reviewRunConfig(roleConfig));
 }
+/** Backlog-aware deferral: while PLANS.md `## Planned` or BUGS.md `## Open` on main
+ * holds an entry feature or bugfix may take (eligibleEntries), idle maintenance runs
+ * stay deferred — queued feature/bugfix work outranks them regardless of what merged.
+ * Stat-cached reads (backlog.ts): one stat per file per poll while the files are unchanged.
+ * bugfix is not a maintenance role, but while BUGS.md `## Open` is empty it defers like
+ * one (deferRun) — openBugsNow is that emptiness, read once here and reused for both
+ * predicates. Also the demoted fallback's half-open window (part 5c/8): the pair whose probe
+ * is due, and the roles whose model tier WOULD run on that pair absent the demotion (the
+ * price-based resolution — the serving resolution has already dropped the pair, which is
+ * exactly why it is being probed). Only those roles pierce the budget hold, and the launch
+ * pass admits exactly one of them as the probe — a probe blind to the pair's tier would lift
+ * the pause for every role, and a probe with no eligible runner must not hijack the poll's
+ * other launches. The review-on strong pause (budgetGate): with the review gate on, an
+ * unresolvable strong tier means nothing could merge, so EVERY role is held — the per-tier
+ * pause set alone would let small/default roles author changes no reviewer could judge. The
+ * probe of the strong pair pierces this hold for exactly the probed tier's roles too. */
+export function pollDeferralInputs(root, runners, liveConfig, gateStates, gates, breakerNowMs) {
+    const openBugsNow = openBugs(root).length > 0;
+    const workBacklogOpen = eligibleEntries(root, "feature").length > 0 || eligibleEntries(root, "bugfix").length > 0;
+    const plansFull = planBacklogFull(root, liveConfig);
+    const probePair = fallbackProbeDuePair(gateStates.budget.breakers, breakerNowMs);
+    const probeRoles = new Set();
+    if (probePair !== null) {
+        for (const r of runners) {
+            if (r.role === DIRECTOR_ROLE)
+                continue;
+            const p = gates.priceResolved[roleSeamTier(liveConfig, r.role)].pair;
+            if (p !== null && modelPairName(p) === probePair)
+                probeRoles.add(r.role);
+        }
+    }
+    const reviewStrongPaused = gates.budgetActive && liveConfig.review.enabled && gates.servingResolved.strong.pair === null;
+    return { openBugsNow, workBacklogOpen, plansFull, probePair, probeRoles, reviewStrongPaused };
+}