tumwater 0.4.2 → 0.4.4

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

@@ -1,8 +1,7 @@
-import { publishInfoFields } from "../team/orchestrator-info.js";
-import { baseRoleOf, runnerEnabled } from "../roles/runner-ids.js";
+import { publishInfoFields } from "../team/team-orchestrator-info.js";
+import { runnerEnabled } from "../roles/runner-ids.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { reviewHoldKey, pollDeferralInputs, pollRunnerReasons } from "./orchestrator-scheduling.js";
-import { seamConcurrencyKey } from "../config/config-views.js";
 import { launchDueRuns } from "./orchestrator-launch.js";
 import { branchHead, currentBranch } from "../git/git.js";
 import { queuedMergeFiles, queuedMergeRoles } from "../merge/merge-queue.js";
@@ -15,11 +14,21 @@ import { checkPermitSnapshot } from "../concurrency/check-permit.js";
 import { slotPoolSnapshot } from "../git/worktree-pool.js";
 import { redeployTarget, watchVerifiesMain } from "../baseline/main-baseline.js";
 import { p75RunDurationMs } from "../run/run-timing.js";
+import { reapAttributableOrphans } from "../doctor/doctor-orphans.js";
 import { pollTeamGates } from "../gates/gate-polls.js";
 import { heldProviders, windowHeldProviders } from "../team/team-hold.js";
 import { workReserveCount } from "../scheduling/claims.js";
 export function newPollState() {
-    return { restart: false, holdForRestart: false, diskHeld: false, warnedBranchDivergence: false, lastReserve: 0 };
+    return { restart: false, holdForRestart: false, diskHeld: false, warnedBranchDivergence: false, lastReserve: 0, lastOrphanReapAt: 0 };
+}
+/** How often the orchestrator's poll loop stands down the orphan reap — a once-per-interval
+ * throttle so a slow process-table scan never runs on the busy per-poll hot path. */
+export const ORPHAN_REAP_INTERVAL_MS = 15 * 60_000;
+/** Whether the orphan reap is due now, given the last poll it ran: true at and after
+ * `now >= last + intervalMs`. Purely a clock comparison so tests pin it from literal
+ * numbers. A fresh state's `last` of 0 is always due against a real `now`. */
+export function dueForOrphanReap(last, now, intervalMs = ORPHAN_REAP_INTERVAL_MS) {
+    return now - last >= intervalMs;
 }
 /** The start gate every reserved run passes the moment its permit is granted
  * (runTimedRoleRun's `held`): closed while a restart is pending, and after one is decided so
@@ -29,20 +38,13 @@ function runStartHeld(state) {
     return state.holdForRestart || state.restart || state.diskHeld;
 }
 /** The one start-gate rule for merges: a restart/disk hold's `held` counts against every role,
- * while a hold on the reviewer's provider (`reviewHeld`) parks only the entries a pre-merge
- * review gates — a role on `review.afterMerge` keeps draining (it merges without a reviewer),
- * and no role at all (the conservative team-wide verdict a caller that cannot name a role
- * reads) still holds. Shared by pollMergeDrain's startHeld and the merge tests, so the
- * production wiring and its coverage cannot drift. */
-export function mergeStartHeld(held, reviewHeld, afterMergeRoles, role) {
-    return held || (reviewHeld && (role === undefined || !afterMergeRoles.has(baseRoleOf(role))));
-}
-/** The base roles whose review runs after merging — the config's `review.afterMerge` list, mapped
- * through `baseRoleOf` so a listed base id stands for all its parallel instances. The one build of
- * the set pollMergeDrain's start gate and pollSchedule's launch gate both exempt from a
- * reviewer-hold, so the two passes cannot read the standing differently. */
-function afterMergeRoleIds(config) {
-    return new Set((config.review.afterMerge ?? []).map(baseRoleOf));
+ * while a hold on the reviewer's provider (`reviewHeld`) parks only the entries a caller that
+ * names no role admits — the post-merge review drain. A role named (every merge entry) is never
+ * held by the reviewer: no role start or landing waits on the reviewer. Shared by
+ * pollMergeDrain's startHeld and the merge tests, so the production wiring and its coverage
+ * cannot drift. */
+export function mergeStartHeld(held, reviewHeld, role) {
+    return held || (reviewHeld && role === undefined);
 }
 /** Live-reload, notify/retention/launchservices, CLI request markers, abort settling and the
  * branch-divergence watch. Writes state.warnedBranchDivergence. */
@@ -52,7 +54,7 @@ export async function pollRequestsAndWatch(ctx, state) {
     // src/config/config-live.ts owns the last-known-good retention and the edge-triggered
     // warnings/events around it.
     const liveConfig = ctx.liveReload.poll();
-    // The notify command rides the same last-known-good reload (src/events/notify.ts): a live
+    // The notify command rides the same last-known-good reload (src/events/event-notify.ts): a live
     // `config set notify` edit takes effect on the next poll, no restart.
     ctx.notifier.update(liveConfig);
     // Live session retention (the last restart-only setting): the edge-triggered
@@ -60,6 +62,15 @@ export async function pollRequestsAndWatch(ctx, state) {
     // src/orchestrator/retention.ts. The live config (last-known-good while the file is broken or
     // missing) drives the check, like the budget gate.
     ctx.retentionPruner.poll(root, liveConfig.sessionRetentionDays);
+    // The orphan reap (src/doctor/doctor-orphans.ts): at most once per interval, kill the
+    // orphans the doctor row already reports that are old enough to be certain a live run no
+    // longer owns them — the automatic counterpart to the human click `doctor
+    // --kill-orphans`/dashboard/TUI makes. The time is stamped before the await, so a slow
+    // scan cannot overlap the next poll's reap (and this await anyway holds the poll step).
+    if (dueForOrphanReap(state.lastOrphanReapAt, Date.now())) {
+        state.lastOrphanReapAt = Date.now();
+        await reapAttributableOrphans(root);
+    }
     // A missing or stale opencode catalog is refetched at most once an hour while opencode is routed.
     ctx.opencodeCatalogRefresh.poll(liveConfig);
     // launchservicesd's Mach-port budget (src/process/launch-services.ts owns it):
@@ -119,9 +130,8 @@ export function pollGatesAndHolds(ctx, state, { liveConfig, now }) {
     state.diskHeld = gates.diskHeld;
     // Publish the permit pool's live state (plans/provider-concurrency.md §8): observers
     // (status, TUI, GUI) read one file instead of coupling to this Semaphore, and the team
-    // line shows per-provider counts only while a cap map is configured. Written only when
-    // it changes, like budget and disk; a map-less team publishes `byKey` empty, which
-    // renders exactly as before. The check-permit pool rides along, so status can show checks
+    // line shows the team total. Written only when it changes, like budget and disk. The
+    // check-permit pool rides along, so status can show checks
     // running and waiting while merges stall. The workspace pool's live state rides along too:
     // one small slots.json read per poll, and publishInfoFields rewrites the info file only
     // when a value changed.
@@ -131,17 +141,15 @@ export function pollGatesAndHolds(ctx, state, { liveConfig, now }) {
         ["slotPool", slotPoolSnapshot(root)],
     ]);
     // The failure hold, keyed per provider (PLANS.md 2026-10-05): a role is held when ITS
-    // run model's provider stands under a hold, and the roles a pre-merge review gates are held
-    // when the reviewer's provider is (with the review gate on their approved change could not
-    // merge without a reviewer — while a role on `review.afterMerge` merges without one, so it is
-    // exempt, and the merge queue reads the same scoped reviewHeld verdict). Key presence in the
+    // run model's provider stands under a hold. A hold on the reviewer's provider parks only
+    // the post-merge review drain, never a role start, verify or landing. Key presence in the
     // map is relapse memory, not a hold: heldProviders() reads only standing holds (`until`
     // non-null), so a lifted hold never keeps blocking.
     const teamHeldProviders = heldProviders(gateStates.teamHold);
     const teamHeldNow = () => heldProviders(gateStates.teamHold);
     // The reviewer's seam is read from the config merges actually review under — the poll's
     // roleConfig, which a used-up claude window or the cap has already moved to a fallback —
-    // so a reviewer that left claude no longer holds the roles a pre-merge review gates on the
+    // so a reviewer that left claude no longer parks the post-merge review drain on the
     // claude hold.
     const reviewSeamKey = reviewHoldKey(gates.roleConfig);
     return {
@@ -149,8 +157,7 @@ export function pollGatesAndHolds(ctx, state, { liveConfig, now }) {
         teamHeldProviders,
         teamHeldNow,
         reviewHeldNow: () => liveConfig.review.enabled && teamHeldNow().has(reviewSeamKey),
-        reviewHeld: liveConfig.review.enabled && teamHeldProviders.has(reviewSeamKey),
-        roleProviders: new Map(runners.map((r) => [r.role, r.runProvider(now)])),
+        roleProviders: new Map(runners.map((r) => [r.role, r.runProvider()])),
     };
 }
 /** Self-redeploy (src/redeploy/redeployer.ts): with main's head in hand, let the state
@@ -180,6 +187,8 @@ export async function pollRedeploy(ctx, state, { liveConfig, mainHead, now }) {
         directorInFlight: ctx.directorInFlight.size,
         roleRunP75Ms: p75RunDurationMs(ctx.roleRunDurationsMs),
     }, liveConfig.autoRestart, now);
+    // The tip beside the target: a tip no passing check covers yet is published as waitingForCheck.
+    await redeploy.noteTip(mainHead);
     publishInfoFields(ctx.root, ctx.info, [["build", redeploy.status(now)]]);
     if (action === "restart") {
         state.restart = true;
@@ -201,16 +210,12 @@ export async function pollRedeploy(ctx, state, { liveConfig, mainHead, now }) {
  * merge slot, and the dedupe against main). A restart or disk hold stops the whole drain, as it
  * starts no run; what is already in flight carries on, and a verify parked for its permit
  * meets the same start gate as a parked run when the permit comes. A hold on the reviewer's
- * provider parks only the entries a pre-merge review gates, per the role-scoped mergeStartHeld:
- * a `review.afterMerge` role's approved/queued changes keep draining. */
+ * provider parks nothing in the drain — no merge entry is held by the reviewer (its hold parks
+ * only the post-merge review drain, whose no-role start gate reads it). */
 export async function pollMergeDrain(ctx, state, { liveConfig, mainHead }, gates) {
     if (state.holdForRestart || state.diskHeld)
         return;
     const { root, mainBranch } = ctx;
-    // The roles whose review runs after merging (plans post-merge-review role): while the
-    // reviewer is held, their approved/queued changes keep draining, so the per-entry start gate
-    // exempts them from the reviewer-hold leg below.
-    const afterMergeRoles = afterMergeRoleIds(liveConfig);
     // A `main_red` pin the pipeline kept goes back on the queue once main's head has moved.
     for (const r of ctx.runners)
         await requeueMainRedPin(root, mainBranch, r.state, mainHead);
@@ -222,9 +227,8 @@ export async function pollMergeDrain(ctx, state, { liveConfig, mainHead }, gates
         runners: ctx.runners,
         liveConfig,
         roleConfig: gates.roleConfig,
-        directorConfig: gates.directorConfig,
-        piDefault: ctx.piDefault,
-        startHeld: (role) => mergeStartHeld(runStartHeld(state), gates.reviewHeldNow(), afterMergeRoles, role),
+        directorConfig: liveConfig,
+        startHeld: (role) => mergeStartHeld(runStartHeld(state), gates.reviewHeldNow(), role),
     }, ctx.merges);
 }
 /** The scheduling pass: the deferral inputs feed pollRunnerReasons, whose reasons map
@@ -232,10 +236,6 @@ export async function pollMergeDrain(ctx, state, { liveConfig, mainHead }, gates
 export async function pollSchedule(ctx, state, { liveConfig, mainHead, now }, gates) {
     const { root, runners, gateStates } = ctx;
     const inputs = pollDeferralInputs(root, runners, liveConfig, gateStates, gates, ctx.breakerNow());
-    // The roles whose review runs after merging: while the reviewer is held their runs stay
-    // launchable (the pre-merge gate skips their review), so the permit-time start gate exempts
-    // them from the reviewer-hold leg below, exactly as the scheduling pass and merge drain do.
-    const afterMergeRoles = afterMergeRoleIds(liveConfig);
     const reasons = await pollRunnerReasons({
         root,
         runners,
@@ -252,14 +252,11 @@ export async function pollSchedule(ctx, state, { liveConfig, mainHead, now }, ga
         bootstrapHeld: gates.bootstrapHeld,
         budgetPausedRoles: gates.budgetPausedRoles,
         probeRoles: inputs.probeRoles,
-        reviewStrongPaused: inputs.reviewStrongPaused,
         roleQuietHeld: gates.roleQuietHeld,
         holdForRestart: state.holdForRestart,
         diskHeld: state.diskHeld,
         heldProviders: gates.teamHeldProviders,
         windowHeldProviders: windowHeldProviders(gateStates.teamHold),
-        reviewHeld: gates.reviewHeld,
-        afterMergeRoles,
         roleProviders: gates.roleProviders,
         openBugsNow: inputs.openBugsNow,
         workBacklogOpen: inputs.workBacklogOpen,
@@ -280,52 +277,30 @@ export async function pollSchedule(ctx, state, { liveConfig, mainHead, now }, ga
         probePair: inputs.probePair,
         probeRoles: inputs.probeRoles,
         budgetActive: gates.budgetActive,
-        windowMovedRoles: gates.windowMovedRoles,
         semaphore: ctx.semaphore,
-        piDefault: ctx.piDefault,
         rolePermitHolders: ctx.rolePermitHolders,
         roleInFlight: ctx.roleInFlight,
         directorInFlight: ctx.directorInFlight,
         roleRunDurationsMs: ctx.roleRunDurationsMs,
         startHeld: (role) => runStartHeld(state) ||
             (role !== DIRECTOR_ROLE
-                ? (!afterMergeRoles.has(baseRoleOf(role)) && gates.reviewHeldNow()) ||
-                    gates.teamHeldNow().has(gates.roleProviders.get(role))
+                ? gates.teamHeldNow().has(gates.roleProviders.get(role))
                 : windowHeldProviders(gateStates.teamHold).has(gates.roleProviders.get(role))),
     });
 }
 /** Priority headroom, then once mode's exit; returns whether the loop should stop. Writes
  * state.lastReserve and, in once mode, fires internalStop. */
-export function pollReserveAndExit(ctx, state, { liveConfig, now }) {
+export function pollReserveAndExit(ctx, state, { liveConfig }) {
     const { root, runners, semaphore } = ctx;
     // Priority headroom (plans/parallel-work-instances.md part 7/7): withhold a few permits
     // from maintenance while a work role has work to take, so a due work run never waits out
     // a whole maintenance run. Sized after the launch pass, so a runner launched this poll
     // already reads as running and reserves nothing for itself.
-    const poolSnapshot = semaphore.snapshot();
-    // The provider-headroom predicate receives the structural ClaimRunner; the config that
-    // names the provider lives on the real RoleRunners, so look the runner up by role.
-    const runnerByRole = new Map(runners.map((r) => [r.role, r]));
     const reserve = workReserveCount(root, runners, {
         maxConcurrent: liveConfig.maxConcurrent,
         enabled: new Set(runners.filter((r) => runnerEnabled(r.config, r.role)).map((r) => r.role)),
         queuedMergeRoles: queuedMergeRoles(root),
         instancesOf: (base) => liveConfig.roles[base]?.instances ?? 1,
-        // Per-provider headroom (plans/provider-concurrency.md §6): an idle work role reserves a
-        // permit only when its own provider could use it — capped and full, it would only idle
-        // the slot another provider's maintenance run could take. Read from the pool's live
-        // snapshot; an uncapped key (or the team-total-only case) always has headroom.
-        providerHasHeadroom: (r) => {
-            const runner = runnerByRole.get(r.role);
-            const cfg = runner && runner.role !== DIRECTOR_ROLE ? runner.runConfig(now) : null;
-            const key = cfg ? seamConcurrencyKey(cfg, ctx.piDefault) : undefined;
-            if (key === undefined)
-                return true;
-            const k = poolSnapshot.byKey[key];
-            if (k?.limit === undefined)
-                return true;
-            return k.inUse < k.limit;
-        },
     });
     semaphore.setReserve(reserve);
     if ((state.lastReserve === 0) !== (reserve === 0)) {

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

@@ -48,8 +48,8 @@ export async function pollRunnerReasons(ctx) {
 }
 /** The team-hold key of the reviewer's seam, read from the config merges actually review under
  * (the poll's roleConfig, which a used-up claude window or the cap has moved to a fallback), so
- * a reviewer that left claude no longer holds the roles a pre-merge review gates on the claude
- * hold. */
+ * a reviewer that left claude no longer parks the no-role post-merge review drain on the claude
+ * hold — no named entry (start, verify or landing) waits on the reviewer. */
 export function reviewHoldKey(roleConfig) {
     return seamHoldKey(reviewRunConfig(roleConfig));
 }
@@ -65,11 +65,8 @@ export function reviewHoldKey(roleConfig) {
  * 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 a pre-merge review gates is
- * held (a `review.afterMerge` role is exempt — its review runs after merging) — 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. */
+ * other launches. The probe of a demoted pair pierces the 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;
@@ -85,6 +82,5 @@ export function pollDeferralInputs(root, runners, liveConfig, gateStates, gates,
                 probeRoles.add(r.role);
         }
     }
-    const reviewStrongPaused = gates.budgetActive && liveConfig.review.enabled && gates.servingResolved.strong.pair === null;
-    return { openBugsNow, workBacklogOpen, plansFull, probePair, probeRoles, reviewStrongPaused };
+    return { openBugsNow, workBacklogOpen, plansFull, probePair, probeRoles };
 }

package/dist/src/orchestrator/orchestrator.js

@@ -1,4 +1,4 @@
-import { readOrchestratorInfo, writeOrchestratorInfo } from "../team/orchestrator-info.js";
+import { readOrchestratorInfo, writeOrchestratorInfo } from "../team/team-orchestrator-info.js";
 import { runnerIds } from "../roles/runner-ids.js";
 import { newLiveConfigReload } from "../config/config-live.js";
 import { FALLBACK_BREAKER_POLICY, } from "../budget/fallback-breaker.js";
@@ -10,20 +10,18 @@ import { mergeTasks, newMergePipeline } from "../merge/merge-pipeline.js";
 import { bestEffortEventLogger, logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { removeQuiet } from "../files/files.js";
 import { OnceRound } from "../scheduling/once-round.js";
-import { newNotifier } from "../events/notify.js";
+import { newNotifier } from "../events/event-notify.js";
 import { piModelsPath } from "../pi/pi-models.js";
-import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
 import { Semaphore } from "../concurrency/semaphore.js";
 import { orchestratorStatePath } from "../paths.js";
 import { createMainWatch } from "../baseline/main-watch.js";
 import { queueCulpritHeal } from "../baseline/main-red.js";
 import { RetentionPruner } from "./retention.js";
-import { newOpencodeCatalogRefresh } from "../gates/startup-gate.js";
+import { newOpencodeCatalogRefresh } from "../gates/startup-gates.js";
 import { WorkMergedCache } from "../scheduling/work-merged-cache.js";
 import { drainInFlightWork, HANDOFF_MERGE_WINDOW_MS, sleepInterruptible, } from "../run/run-timing.js";
 import { newTeamGateStates } from "../gates/gate-polls.js";
-import { loggedWindowKeys } from "../team/team-polls.js";
-import { ReclaimController } from "../team/reclaim.js";
+import { ReclaimController } from "../team/team-reclaim.js";
 import { reapPreviousTeamOrphans } from "../doctor/doctor-orphans.js";
 import { runStartupMigrations } from "./startup-migration-steps.js";
 import { archiveAtTeamStart } from "../backlog/backlog-archive.js";
@@ -34,9 +32,6 @@ export async function runOrchestrator(opts) {
     const { root, config, mainBranch, signal: externalSignal } = opts;
     const pollMs = opts.pollMs ?? POLL_MS;
     const modelsPath = opts.modelsPath ?? piModelsPath();
-    // pi's saved default model — the same stat-cached read status-roles.ts makes — used as the
-    // fallback provider key for a pi seam that names no model (plans/provider-concurrency.md §2).
-    const piDefault = readPiDefaultModel(piSettingsPath(modelsPath), root);
     const breakerPolicy = opts.fallbackBreakerPolicy ?? FALLBACK_BREAKER_POLICY;
     const breakerNow = opts.breakerNow ?? Date.now;
     // Parallel work instances (part 5b/7): the runner list is every runner id the config enables
@@ -77,10 +72,6 @@ export async function runOrchestrator(opts) {
     // resolver — merge-drain.ts) all hold a permit; see its MergePipelineContext for why a
     // merge is not exempt.
     const semaphore = new Semaphore(Math.max(1, config.maxConcurrent));
-    // Seed the pool's per-provider caps from the startup config (plans/provider-concurrency.md
-    // §7): a role run's lease is bounded by its provider key from the first launch onward, not
-    // just after a live edit. A config without the key passes an empty map, the no-change case.
-    semaphore.setKeyCaps(config.maxConcurrentPerProvider ?? {});
     const infoFile = orchestratorStatePath(root);
     const info = { pid: process.pid, startedAt: Date.now(), roles: enabled };
     if (redeploy)
@@ -174,9 +165,6 @@ export async function runOrchestrator(opts) {
     // the start gate reads gateStates.teamHold at permit time, so its closures always see
     // the latest poll's hold verdict rather than the poll that created them.
     const gateStates = newTeamGateStates(config);
-    // A restart must not re-announce a window that is still open.
-    gateStates.claudeWindowWarned = loggedWindowKeys(root, "subscription_window_warning", Date.now());
-    gateStates.claudeWindowReserved = loggedWindowKeys(root, "subscription_window_reserved", Date.now());
     // The live config the last successful reload produced (last-known-good while the file is
     // broken or missing). The reload bookkeeping itself lives in src/config/config-live.ts.
     const liveReload = newLiveConfigReload({ root, config, mainBranch, runnerSignal: roleSignal, runners, semaphore, roleFilter: opts.roleFilter });
@@ -194,10 +182,10 @@ export async function runOrchestrator(opts) {
     // logs exactly once — on the transition in, never while merely not-due and never on exit.
     // In-memory only: a restart mid-episode can re-log at most one event.
     const deferredDue = new Map();
-    // The operator notify hook (src/events/notify.ts owns the whole concern): one configured shell
-    // command run on notable events (budget_paused, role_streak_paused, merge_failed,
-    // restart_blocked). Subscribed here so it sees every event this process logs from start;
-    // disposed beside the orchestrator_stop event below.
+    // The operator notify hook (src/events/event-notify.ts owns the whole concern): one
+    // configured shell command run on notable events (budget_paused, role_streak_paused,
+    // merge_failed, restart_blocked). Subscribed here so it sees every event this
+    // process logs from start; disposed beside the orchestrator_stop event below.
     const notifier = newNotifier(root);
     // Best-effort event logging in the poll loop (bestEffortEventLogger, events.ts): this loop
     // and its finally run with no catch, so an unwritable feed (ENOSPC, EACCES, the path replaced
@@ -221,7 +209,6 @@ export async function runOrchestrator(opts) {
         once,
         info,
         modelsPath,
-        piDefault,
         redeploy,
         launchServicesWatch,
         reclaim,

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

@@ -19,52 +19,73 @@ import { noteSkip } from "./scheduling-scope.js";
  * 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)) &&
+    if (standDownForNoWork(scope, runner, reason))
+        return "skipped";
+    return claimGroupAdmission(scope, runner, reason);
+}
+/** The candidate half of the stand-down test: true when a feature runner, or a bugfix runner
+ * whose open bugs are non-empty (no open bugs at all is search mode, which still runs), is due
+ * a scheduled or main-moved run, is not freshly woken, and holds no claim or outstanding work —
+ * so startup, inbox and resume runs, a fresh operator wake, and a claimed or mid-entry runner
+ * all pass through. The caller stands the runner down only when this holds and no entry is
+ * eligible. */
+function noWorkScheduledRun(scope, runner, reason) {
+    const base = baseRoleOf(runner.role);
+    return ((base === "feature" || (base === 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";
-        }
+        !hasOutstandingWork(runner.state));
+}
+/** The eligible-entries list for a base role, computed once per poll and memoized on the
+ * scope so the stand-down and claim-group paths share it. */
+function eligibleForBase(scope, base) {
+    let eligible = scope.eligibleMemo.get(base);
+    if (eligible === undefined) {
+        eligible =
+            scope.claimGroups.get(base)?.eligible ?? eligibleEntries(scope.root, base);
+        scope.eligibleMemo.set(base, eligible);
     }
+    return eligible;
+}
+/** Stand down a runner with no eligible entry at all on its scheduled and main-moved runs: 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. nextRunAt and backoff stay put, so the first poll after a plan turns eligible
+ * starts a run for it. */
+function standDownForNoWork(scope, runner, reason) {
+    if (!noWorkScheduledRun(scope, runner, reason))
+        return false;
+    if (eligibleForBase(scope, baseRoleOf(runner.role)).length > 0)
+        return false;
+    noteSkip(scope.root, runner, "no-free-entry");
+    runner.state.heldElsewhere = undefined;
+    if (scope.once.active)
+        scope.once.settle(runner.role, "no free entry");
+    return true;
+}
+/** 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). */
+function claimGroupAdmission(scope, runner, reason) {
     const claimGroup = scope.claimGroups.get(baseRoleOf(runner.role));
     if (claimGroup) {
         if (runner.state.claim) {
             // keeps its claim
+            return "admitted";
         }
         else if (hasOutstandingWork(runner.state)) {
             // finishes its own unrecorded entry
+            return "admitted";
         }
         else if (reason !== "inbox" && reason !== "resume") {
             // The group holds an unclaimed mid-entry sibling: assign nothing this poll, or a
@@ -74,39 +95,7 @@ export function admitRunner(scope, runner, reason) {
                 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";
-            }
+            return assignClaim(scope, runner, claimGroup.eligible, claimGroup.held);
         }
     }
     else {
@@ -114,3 +103,47 @@ export function admitRunner(scope, runner, reason) {
     }
     return "admitted";
 }
+/** Assign the first free eligible entry to an unclaimed admitted runner: record the claim on
+ * the runner, add it to the group's held set, and log the assignment. With no free entry, an
+ * idle extra instance, or a primary whose eligible entries siblings all hold (unless an
+ * operator wake is fresh), stands down rather than run unassigned. */
+function assignClaim(scope, runner, eligible, held) {
+    const free = eligible.filter((e) => !held.has(e.key));
+    const pick = assignNext(free);
+    // An unassigned runner is told which entries its siblings hold (cleared when none).
+    const heldTitles = eligible.filter((e) => held.has(e.key)).map((e) => e.title);
+    runner.state.heldElsewhere = !pick && heldTitles.length > 0 ? heldTitles : undefined;
+    if (pick) {
+        recordAssignedClaim(scope, runner, pick, held);
+        return "admitted";
+    }
+    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";
+    }
+    return "admitted";
+}
+/** Build the runner's claim record, add the picked entry to the group's held set, and log the
+ * assignment to the events feed. */
+function recordAssignedClaim(scope, runner, pick, held) {
+    runner.state.claim = {
+        file: baseRoleOf(runner.role) === BUGFIX_ROLE ? "BUGS.md" : "PLANS.md",
+        key: pick.key,
+        title: pick.title,
+        at: scope.now,
+        source: "assigned",
+    };
+    held.add(pick.key);
+    logEventBestEffort(scope.root, {
+        source: runner.role,
+        type: "claim",
+        action: "assigned",
+        key: pick.key,
+        title: pick.title,
+    });
+}