tumwater 0.2.0 → 0.3.0

package/dist/src/orchestrator/retention.js

@@ -1,16 +1,19 @@
-// vocabulary: plain
 /** Session retention (the `sessionRetentionDays` setting): the once-per-day gate and the prune
  * itself, split out of orchestrator.ts — the poll-loop runtime carried both a startup prune and
  * a near-identical in-poll prune plus the last-applied-window bookkeeping, and scheduling.ts
- * held the due-gate despite being about tick policy, not file retention. Dependency direction:
+ * held the due-gate despite being about run policy, not file retention. Dependency direction:
  * orchestrator → retention; this module owns the whole "which files age out, and when" concern
  * and the orchestrator only hands it the (possibly live-reloaded) window. */
 import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
-import { pruneOldFiles } from "../files/files.js";
-import { pruneSessionLedgers, pruneOpencodeSessions } from "../agent/session-ledger.js";
+import { DAY_MS } from "../text/datetime.js";
+import { ensureParentDir, pruneOldFiles } from "../files/files.js";
+import { pruneSessionLedgers, pruneOpencodeSessions, pruneCodexSessions } from "../agent/session-ledger.js";
 import { loadConfigSafe } from "../config/config.js";
+import { resolvedBackendConfig } from "../config/config-views.js";
 import { opencodeBackend, opencodeSpillDir } from "../agent/opencode/opencode-backend.js";
-import { opencodeDbPath, sessionsRootDir, toolOutputDir } from "../paths.js";
+import { codexBackend } from "../agent/codex/codex-backend.js";
+import { codexHome } from "../agent/codex/codex-catalog.js";
+import { opencodeDbPath, salvageDir, sessionsRootDir, toolOutputDir } from "../paths.js";
 /** Is a once-per-day session prune due? Due when retention is enabled (> 0) and a full day
  * has passed since the last prune (or no prune has run yet). */
 export function dueForPrune(lastPruneAt, now, retentionDays) {
@@ -18,7 +21,7 @@ export function dueForPrune(lastPruneAt, now, retentionDays) {
         return false; // 0 disables pruning — never due.
     if (lastPruneAt === null)
         return true; // Never pruned yet — due immediately.
-    return now - lastPruneAt >= 24 * 3600 * 1000;
+    return now - lastPruneAt >= DAY_MS;
 }
 /** The retention state machine across one orchestrator's lifetime: which window was last
  * applied and when we last pruned. Constructed once at startup — construction runs the startup
@@ -71,14 +74,39 @@ export class RetentionPruner {
         // hands every expired OpenCode session id to `opencode session delete`. Each half warns its
         // own unit.
         const { config } = loadConfigSafe(root);
-        const bin = config !== undefined ? opencodeBackend.resolveBin(config).bin : undefined;
+        let bin = config !== undefined ? opencodeBackend.resolveBin(config).bin : undefined;
+        const dbPath = opencodeDbPath(root);
+        try {
+            ensureParentDir(dbPath);
+        }
+        catch {
+            // The directory cannot be created, so no OpenCode DB is there to delete from; this pass
+            // runs in the poll loop, where a throw ends the team. Skip only the session deletes.
+            bin = undefined;
+        }
         const deleted = pruneOpencodeSessions(sessions, days, {
             bin,
-            env: { ...process.env, OPENCODE_DB: opencodeDbPath(root) },
+            env: { ...process.env, OPENCODE_DB: dbPath },
             spillDir: opencodeSpillDir(root),
         });
         if (deleted > 0)
             warnEventBestEffort(root, TUMWATER_SOURCE, `deleted ${deleted} expired opencode session(s)`);
+        // Codex's sessions also live outside .tumwater — under the team's CODEX_HOME (part 8/9).
+        // Resolve its binary and home exactly as a run's invocation would and purge its expired
+        // sessions from the ledger BEFORE the file pass below ages it out. Like the OpenCode twin,
+        // an unavailable config skips the deletes rather than guessing at a binary and home: a
+        // bare `codex` under the operator's inherited CODEX_HOME could act on the wrong home
+        // (review objection 2). CODEX_HOME is always set explicitly — to the resolved team home,
+        // or to undefined when the config is absent — so the inherited CODEX_HOME never reaches
+        // the purge (its rollout fallback would otherwise unlink the operator's own home).
+        const codexBin = config !== undefined ? codexBackend.resolveBin(config).bin : undefined;
+        const codexHomeDir = config !== undefined ? codexHome(resolvedBackendConfig(config, "codex")) : undefined;
+        const deletedCodex = pruneCodexSessions(sessions, days, {
+            bin: codexBin,
+            env: { ...process.env, CODEX_HOME: codexHomeDir },
+        });
+        if (deletedCodex > 0)
+            warnEventBestEffort(root, TUMWATER_SOURCE, `deleted ${deletedCodex} expired codex session(s)`);
         // Age out session/tool-output files now: an entirely stale dir is gone before the line
         // pass reads it. A running role's ledger mtime stays young, so pruneOldFiles never ages
         // that file out; each warning must name the unit it pruned.
@@ -88,5 +116,11 @@ export class RetentionPruner {
         const prunedLines = pruneSessionLedgers(sessions, days);
         if (prunedLines > 0)
             warnEventBestEffort(root, TUMWATER_SOURCE, `pruned ${prunedLines} stale session ledger line(s)`);
+        // Salvaged slot leftovers (src/git/slot-salvage.ts) age out on the same window as the
+        // sessions that made them: a patch still waiting by then belongs to a role that has not run
+        // since, and the operator had the window's length to take a kept one.
+        const prunedPatches = pruneOldFiles(salvageDir(root), days);
+        if (prunedPatches > 0)
+            warnEventBestEffort(root, TUMWATER_SOURCE, `pruned ${prunedPatches} old salvaged workspace patch(es)`);
     }
 }

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

@@ -0,0 +1,116 @@
+/** The poll loop's per-runner admission tail (part 3/3, split out of pollRunnerReasons): the
+ * stand-down turn-down and the parallel-work-instance claim assignment, run after every skip
+ * gate has admitted a runner. Returns "admitted" when the runner may start a run, or "skipped"
+ * (having recorded its skip reason and settled its once-round answer) when it stands down or
+ * yields its place. Split out of orchestrator-scheduling.ts so the post-gate admission policy
+ * reads on its own screen; orchestrator-scheduling.ts's loop owns the binder: the final
+ * `noteSkip(root, runner, undefined)`, the `reasons` entry and the `writing` increment when an
+ * admitted runner actually starts. */
+import { assignNext } from "../scheduling/claims.js";
+import { eligibleEntries } from "../backlog/backlog-eligibility.js";
+import { logEventBestEffort } from "../events/events.js";
+import { freshlyWoken, hasOutstandingWork } from "../runner/runner-state.js";
+import { BUGFIX_ROLE } from "../roles/roles.js";
+import { baseRoleOf, instanceIndex } from "../roles/runner-ids.js";
+import { noteSkip } from "./scheduling-scope.js";
+/** Decide a runner's post-gate admission. `reason` is the runner's due reason — the
+ * `skipRunner` verdict's reason, itself `isEligible`'s — which the stand-down block keyed on
+ * scheduled/main-moved and the claim-group block keyed on inbox/resume read. Mutates the
+ * runner's claim/heldElsewhere state, the claim group's held set, and once-mode settlement on
+ * the skip paths. */
+export function admitRunner(scope, runner, reason) {
+    // 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 run can settle the hold.
+    // Otherwise, when the run 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
+    // stands down too while siblings hold every eligible entry, unless an operator wake is fresh
+    // (then it runs unassigned).
+    // 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 runs instead of paying a model run that
+    // can only end in
+    // nothing-to-do. Startup, inbox and resume runs, 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 starts a run for it.
+    const standDownBase = baseRoleOf(runner.role);
+    if ((standDownBase === "feature" || (standDownBase === BUGFIX_ROLE && scope.openBugsNow)) &&
+        (reason === "scheduled" || reason === "main moved") &&
+        !freshlyWoken(runner.state) &&
+        runner.state.claim === undefined &&
+        !hasOutstandingWork(runner.state)) {
+        let eligible = scope.eligibleMemo.get(standDownBase);
+        if (eligible === undefined) {
+            eligible =
+                scope.claimGroups.get(standDownBase)?.eligible ??
+                    eligibleEntries(scope.root, standDownBase);
+            scope.eligibleMemo.set(standDownBase, eligible);
+        }
+        if (eligible.length === 0) {
+            noteSkip(scope.root, runner, "no-free-entry");
+            runner.state.heldElsewhere = undefined;
+            if (scope.once.active)
+                scope.once.settle(runner.role, "no free entry");
+            return "skipped";
+        }
+    }
+    const claimGroup = scope.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(scope.root, runner, "claim-hold");
+                return "skipped";
+            }
+            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: scope.now,
+                    source: "assigned",
+                };
+                claimGroup.held.add(pick.key);
+                logEventBestEffort(scope.root, {
+                    source: runner.role,
+                    type: "claim",
+                    action: "assigned",
+                    key: pick.key,
+                    title: pick.title,
+                });
+            }
+            else if (instanceIndex(runner.role) >= 2 ||
+                (heldTitles.length > 0 && !freshlyWoken(runner.state))) {
+                // An idle extra instance, or a primary whose eligible entries siblings all hold
+                // (unless an operator wake is fresh): no run, no backoff climb.
+                noteSkip(scope.root, runner, "no-free-entry");
+                if (scope.once.active)
+                    scope.once.settle(runner.role, "no free entry");
+                return "skipped";
+            }
+        }
+    }
+    else {
+        runner.state.heldElsewhere = undefined; // no claim group (e.g. instances lowered to 1)
+    }
+    return "admitted";
+}

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

@@ -0,0 +1,201 @@
+/** One poll's scheduling-scope precompute, built by orchestrator-scheduling.ts's
+ * pollRunnerReasons: the shared pass context and the values computed once per poll before the
+ * per-runner loop — the merge-queue snapshot, the director pin, per-base claim groups, the
+ * gate predicates, and the mutable admission state (quota counter, ordered runners, eligible
+ * memo, reasons map). Parts 2/3 and 3/3 lift the loop's skip and admit halves against this
+ * scope. */
+import { increment } from "../collections.js";
+import { DIRECTOR_ROLE, commitTier } from "../roles/roles.js";
+import { baseRoleOf, runnerEnabled, runnerPaused } from "../roles/runner-ids.js";
+import { hasOutstandingWork, saveRunnerStateBestEffort } from "../runner/runner-state.js";
+import { queuedMergeRoles } from "../merge/merge-queue.js";
+import { hasUnmergedPin } from "../runner/leftover.js";
+import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { eligibleEntries } from "../backlog/backlog-eligibility.js";
+import { CLAIM_IDLE_MAX_MS, claimReleaseReason, heldKeys, listedKeys, } from "../scheduling/claims.js";
+/** Record why the poll skipped a due role on its state (RunnerState.skipReason), saving only when
+ * the value changes: a skipped role gets no run to save its own state, and a role that stays
+ * skipped must not rewrite its file every poll. */
+export function noteSkip(root, runner, reason) {
+    if (runner.state.skipReason === reason)
+        return;
+    runner.state.skipReason = reason;
+    saveRunnerStateBestEffort(root, runner.state);
+}
+/** Compute the once-per-poll precompute the scheduling pass's per-runner loop reads. Has the
+ * same side effects the poll body's own precompute had: the merge-queue snapshot, the
+ * hasUnmergedPin director pin, the per-base claim-group build (with its claim-release loop,
+ * which mutates runner state, persists and logs), and the writing count. */
+export async function buildSchedulingScope(ctx) {
+    const { root, runners, once, now, mainHead, userPaused, quietNow, pausedRoles, capPaused, maintenanceQuota, bootstrapHeld, budgetPausedRoles, probeRoles, reviewStrongPaused, roleQuietHeld, heldProviders, windowHeldProviders, reviewHeld, roleProviders, openBugsNow, workBacklogOpen, planBacklogFull, holdForRestart, diskHeld, deferredDue, workMergedSince, } = ctx;
+    // 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 run 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);
+    // The director's kept merge pin (a non-terminal merge failure kept it): due on its own min-run
+    // clock, since its only other run is an operator prompt. A queued or in-flight pin is the
+    // merge-queue interlock's to hold, so the leftover reason is not offered then.
+    const pinnedDirector = !queuedRoles.has(DIRECTOR_ROLE) && (await hasUnmergedPin(root, DIRECTOR_ROLE));
+    // 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 `runnerEnabled` 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: runnerEnabled(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: runnerPaused(pausedRoles, r.role) && !pausedRoles.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 run to save its state, so the dead
+            // claim would stay on disk for status/doctor to show and for a restart to release again.
+            saveRunnerStateBestEffort(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 runs;
+    // 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 role's last run 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. Computed ONCE per runner per poll (the scheduling loop's
+    // per-runner `demand`), so a role's queue is listed a single time a poll instead of once per
+    // hold check; every consumer takes the boolean rather than re-calling inboxSize.
+    // The new-project bootstrap hold (part 2/2): held unless the role has a fresh operator wake
+    // or a queued prompt.
+    const bootstrapHeldNow = (runner, demand) => bootstrapHeld.has(runner.role) && !demand;
+    // The maintenance allowance's team-level hold (part 1b/4): `used` has reached `allowance`,
+    // so no maintenance role starts unless it carries demand (`tumwater wake <maintenance-role>`
+    // gets exactly one run). The per-poll admission headroom is spent separately, after each
+    // role's due check, where the pass knows what actually runs; the verdict alone cannot.
+    const maintenanceQuotaOverLine = (runner, demand) => commitTier(baseRoleOf(runner.role)) === "maintenance" &&
+        maintenanceQuota.used >= maintenanceQuota.allowance &&
+        !demand;
+    // Runs writing code per multi-runner base role (plans/fast-merge.md "Lever 1"): a runner in
+    // flight, not one whose change waits in the merge queue. `instances` limits this count, so the
+    // role's extra runner ids start work only while fewer than `instances` are running; admissions
+    // this poll count at once, so one pass cannot overshoot.
+    const writing = new Map();
+    for (const r of runners) {
+        if (claimGroups.has(baseRoleOf(r.role)) && r.state.running && !queuedRoles.has(r.role)) {
+            increment(writing, baseRoleOf(r.role));
+        }
+    }
+    // Admission order: a runner of a multi-runner base with a pending revision or conflict
+    // hand-back comes first (its change came back; it holds no new claim), then the rest in runner
+    // order, so the lowest-index free runner takes new work. Other roles keep their place.
+    const ownsOutstanding = (r) => claimGroups.has(baseRoleOf(r.role)) && hasOutstandingWork(r.state);
+    const ordered = [
+        ...runners.filter((r) => ownsOutstanding(r)),
+        ...runners.filter((r) => !ownsOutstanding(r)),
+    ];
+    // The stand-down's eligible lists per base role, read at most once per poll (see the check
+    // below).
+    const eligibleMemo = new Map();
+    return {
+        root,
+        runners,
+        once,
+        now,
+        mainHead,
+        userPaused,
+        quietNow,
+        pausedRoles,
+        capPaused,
+        maintenanceQuota,
+        bootstrapHeld,
+        budgetPausedRoles,
+        probeRoles,
+        reviewStrongPaused,
+        roleQuietHeld,
+        heldProviders,
+        windowHeldProviders,
+        reviewHeld,
+        roleProviders,
+        openBugsNow,
+        workBacklogOpen,
+        planBacklogFull,
+        holdForRestart,
+        diskHeld,
+        deferredDue,
+        workMergedSince,
+        queuedRoles,
+        pinnedDirector,
+        claimGroups,
+        writing,
+        ownsOutstanding,
+        ordered,
+        eligibleMemo,
+        reasons: new Map(),
+        quotaAdmitted: 0,
+        budgetHolds,
+        operatorPauseBlocks,
+        bootstrapHeldNow,
+        maintenanceQuotaOverLine,
+    };
+}

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

@@ -0,0 +1,185 @@
+import { logEventBestEffort } from "../events/events.js";
+import { baseRoleOf, configuredInstances, runnerPaused } from "../roles/runner-ids.js";
+import { BUGFIX_ROLE, DIRECTOR_ROLE, commitTier } from "../roles/roles.js";
+import { deferRunReason, isEligible } from "../scheduling/scheduling.js";
+import { inboxSize } from "../inbox/inbox.js";
+import { freshlyWoken } from "../runner/runner-state.js";
+import { MERGE_CONFLICT_LIMIT } from "../runner/leftover.js";
+import { noteSkip } from "./scheduling-scope.js";
+/** Decide whether this runner is due this poll, running every skip gate and the once/deferral
+ * bookkeeping against scheduling-scope.ts's scope. Returns skip:true when a gate declined the
+ * run, and skip:false with the due reason otherwise (the admit tail in scheduling-admit.ts
+ * consumes the reason). Mutates the shared scope —
+ * deferredDue, quotaAdmitted, once-mode settlement — and writes skip reasons as its only
+ * side effects. */
+export async function skipRunner(scope, runner) {
+    const { root, once, now, mainHead, pausedRoles, capPaused, holdForRestart, diskHeld, windowHeldProviders, roleProviders, reviewHeld, heldProviders, openBugsNow, workBacklogOpen, planBacklogFull, deferredDue, workMergedSince, queuedRoles, pinnedDirector, claimGroups, writing, maintenanceQuota, maintenanceQuotaOverLine, bootstrapHeldNow, operatorPauseBlocks, } = scope;
+    // The role's inbox size and operator demand, computed once per runner per poll: every
+    // consumer below (the holds, isEligible's inbox count, the maintenance admission) shares
+    // this one directory listing + per-file stat read instead of each re-scanning the queue.
+    // The queue is append-only while this pass runs (nothing dequeues until launch, after the
+    // pass), so one read per runner is stable, and `now` here matches the poll's own clock.
+    const inboxCount = inboxSize(root, runner.role);
+    const demand = inboxCount > 0 || freshlyWoken(runner.state);
+    // Once mode: a paused role gets no run 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-run contract).
+    if (once.active &&
+        !once.isSettled(runner) &&
+        !runner.state.running &&
+        (runnerPaused(pausedRoles, runner.role) ||
+            capPaused.has(runner.role) ||
+            maintenanceQuotaOverLine(runner, demand) ||
+            bootstrapHeldNow(runner, demand) ||
+            operatorPauseBlocks(runner.role))) {
+        once.settle(runner.role, "paused");
+    }
+    // Once mode's at-most-one-run contract (src/scheduling/once-round.ts): a role that already had
+    // its run — 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-run guarantee held only for deferrable built-ins (their deferral
+    // settles them); a custom role 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))
+        return { skip: true };
+    if (holdForRestart || diskHeld)
+        return { skip: true }; // a restart or a low disk is pending: nothing new starts, on any role
+    // The per-role pause gates BEFORE the team check and exempts nothing — the director
+    // included (the operator named that one role deliberately).
+    if (runnerPaused(pausedRoles, runner.role))
+        return { skip: true };
+    // The role's own daily cost cap (src/gates/role-cap-gates.ts): no start-gate change — a
+    // parked waiter finishes (in-flight runs finish, NEW runs 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))
+        return { skip: true };
+    // The maintenance allowance (plans/work-ratio.md, part 1b/4): no new maintenance run 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, demand))
+        return { skip: true };
+    // The new-project bootstrap (part 2/2): no new maintenance runs until the plan target is
+    // met; a fresh wake or queued prompt admits one anyway (bootstrapHeldNow).
+    if (bootstrapHeldNow(runner, demand))
+        return { skip: true };
+    if (operatorPauseBlocks(runner.role))
+        return { skip: true }; // no new role runs 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)))
+        return { skip: true };
+    if (runner.role !== DIRECTOR_ROLE &&
+        (reviewHeld || heldProviders.has(roleProviders.get(runner.role))))
+        return { skip: true }; // nor while ITS provider's failure storm holds — or the reviewer's (nothing could merge)
+    // The role's OWN queue decides inbox due-ness: the director counts its historical
+    // inbox, every other role its per-role queue (tumwater prompt --role <id>) — so a
+    // queued prompt makes its role due by itself, no wake marker needed (isEligible).
+    const { run, reason, skip } = isEligible(runner, now, mainHead, inboxCount, {
+        once: once.active,
+        planBacklogOpen: !planBacklogFull,
+        // A pin at the conflict cap whose lineage is not yet handed back is owed an authoring run
+        // (the promptless path would skip it unchanged every poll), so only a prompt makes it due.
+        leftoverPending: pinnedDirector &&
+            !((runner.state.mergeConflicts?.count ?? 0) >= MERGE_CONFLICT_LIMIT &&
+                runner.state.conflictHandback === undefined),
+    });
+    if (!run) {
+        // Not due this poll: any deferral episode has ended (or never started). No event —
+        // the run'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);
+        // Thread a gate-specific skip through (e.g. the yield-stretched gap) so a runner the
+        // poll declined and will keep declining does not read as "due — starts on the next
+        // poll"; stays undefined for every ordinary not-due path.
+        noteSkip(root, runner, skip);
+        return { skip: true };
+    }
+    // Merge queue 3/5 interlock (invariant 3): a role with a QUEUED or IN-FLIGHT merge never
+    // starts a run — 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 run that queued the merge finished, which closed any deferral episode; its
+    // `queued` can leave a prior no_change in lastResult — runner-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);
+        return { skip: true };
+    }
+    // The role's `instances` limit on concurrent runs: a multi-runner base admits a runner only
+    // while fewer than `instances` of its runners are running. A parked runner (queued change)
+    // was skipped by the interlock above and holds no place.
+    const writingBase = baseRoleOf(runner.role);
+    if (claimGroups.has(writingBase) && !runner.state.running) {
+        if ((writing.get(writingBase) ?? 0) >= configuredInstances(runner.config, runner.role)) {
+            noteSkip(root, runner, "instances-full");
+            return { skip: true };
+        }
+    }
+    // Need-based deferral: a due maintenance run (scheduled or main-moved wake) whose last
+    // run 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 — deferRun), and
+    // a fresh operator wake overrides it (deferRun'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-run role, or one 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 = deferRunReason(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 maintenance run that deferred itself — 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");
+            return { skip: true };
+        }
+    }
+    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 roles already in flight, so a due maintenance run admitted here spends one
+    // of the remaining `allowance - used` slots. This must sit after the due check — the pure
+    // verdict cannot know which roles will be eligible this poll, so the reservation lives in
+    // the pass that does; without it two due maintenance roles start in the same poll. Demand
+    // spends no slot: it is an explicit operator request, not idle maintenance.
+    if (commitTier(baseRoleOf(runner.role)) === "maintenance" && !demand) {
+        if (scope.quotaAdmitted >= maintenanceQuota.allowance - maintenanceQuota.used) {
+            noteSkip(root, runner, "maintenance-due-cap");
+            return { skip: true };
+        }
+        scope.quotaAdmitted++;
+    }
+    return { skip: false, reason: reason };
+}

package/dist/src/orchestrator/startup-migration-steps.js

@@ -1,3 +1,4 @@
+import { errCode } from "../errno.js";
 import { legacyMigrateLandQueueDir } from "../merge/merge-queue.js";
 import fs from "node:fs";
 import { deleteRefIfAt, refSha, refsUnder, setRef } from "../git/git.js";
@@ -13,11 +14,11 @@ registerStartupMigration({
     run: async (root) => {
         try {
             fs.unlinkSync(legacyLandingStatePath(root));
-            return ["removed the old landing.json marker"]; // vocabulary-ok: names the legacy file
+            return { moved: ["removed the old landing.json marker"], kept: [], failed: [] }; // vocabulary-ok: names the legacy file
         }
         catch (err) {
-            if (err.code === "ENOENT")
-                return [];
+            if (errCode(err) === "ENOENT")
+                return { moved: [], kept: [], failed: [] };
             throw err;
         }
     },
@@ -26,7 +27,7 @@ registerStartupMigration({
     name: "mergeRefs",
     run: async (root) => {
         const legacyPrefix = "refs/tumwater/landing/"; // vocabulary-ok: legacy name read from old refs or commits
-        const notes = [];
+        const notes = { moved: [], kept: [], failed: [] };
         for (const { ref, sha } of await refsUnder(root, legacyPrefix)) {
             const role = ref.slice(legacyPrefix.length);
             const target = mergeRefName(role);
@@ -35,14 +36,14 @@ registerStartupMigration({
                 if (!(await setRef(root, target, sha)))
                     continue; // keep the legacy pin; the next start retries
                 await deleteRefIfAt(root, ref, sha);
-                notes.push(`moved ${ref} to ${target}`);
+                notes.moved.push(`moved ${ref} to ${target}`);
             }
             else if (existing === sha) {
                 await deleteRefIfAt(root, ref, sha);
-                notes.push(`removed ${ref}: ${target} already names the same commit`);
+                notes.moved.push(`removed ${ref}: ${target} already names the same commit`);
             }
             else
-                notes.push(`kept ${ref} and ${target}: they name different commits`);
+                notes.kept.push(`kept ${ref} and ${target}: they name different commits`);
         }
         return notes;
     },