tumwater 0.4.1 → 0.4.2

package/dist/src/config/config-live.js

@@ -47,163 +47,195 @@ export function newLiveConfigReload(deps) {
     // the config application that follows the emission. bestEffortEventLogger (events.ts) holds
     // the shared "logging must not throw" policy.
     const { emit, warn } = bestEffortEventLogger(deps.root);
+    // Warn once per vanish and once per reappearance of tumwater.json.
+    function noteConfigPresence(reloaded) {
+        // A missing file keeps the last-known-good config too, and never reloads as defaults: the
+        // team was started on a real file (startup refuses to run without one), so its vanishing
+        // mid-run is an incident — a merge's fast-forward deleted it on 2026-09-22 and the team
+        // silently ran 8.6 h on defaults (BUGS.md 2026-09-23). One warning per vanish, not per
+        // poll; its return logs one line, then the normal reload below diffs it against the
+        // retained config — so config_changed names only what the returned file really changed.
+        if (reloaded.missing) {
+            if (!configMissing) {
+                warn(`tumwater.json missing — keeping current config until it returns (${configPath(deps.root)})`);
+                configMissing = true;
+                lastConfigError = null; // Whatever state it returns in is stated afresh.
+            }
+        }
+        else if (configMissing) {
+            warn("tumwater.json reappeared — reloading it");
+            configMissing = false;
+        }
+    }
+    // Refuse a live edit that routes a seam to an API-key-logged-in codex, keeping prevLive.
+    function refuseApiKeyCodex(nextConfig, prevBackends) {
+        // A live edit that routes a seam to a codex logged in with an API key is refused before
+        // the reload is applied: startup refuses the same codex seam (decision 5), and here a
+        // warn-only would let the running team spend per-token Codex the budget cap cannot see
+        // (review objection 1). Refusing keeps the last-known-good config, like a missing or
+        // broken file. The seed runs once per root (`codex login status` is a real probe); the
+        // persisted account file is the voice of the refusal on later polls, re-probing a stale
+        // api answer (codex-account.ts) so the operator's `codex login --device-auth` remedy
+        // clears it at the next seed. A subscription codex passes through to the backend loop.
+        const newlyRoutedCodex = !prevBackends.has("codex") && backendsInUse(nextConfig).includes("codex");
+        if (newlyRoutedCodex && !liveCodexSeedAttempted.has(deps.root)) {
+            liveCodexSeedAttempted.add(deps.root);
+            seedCodexAccount(deps.root, nextConfig);
+        }
+        if (newlyRoutedCodex && readCodexAccount(deps.root)?.billing === "api") {
+            if (codexLiveRefused)
+                return true;
+            codexLiveRefused = true;
+            warn("refusing live edit: Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run `CODEX_HOME=<home> codex login --device-auth`");
+            return true;
+        }
+        // A poll that did not refuse clears the warn-once marker so a later re-entry into the
+        // refusal (the operator reverts, then re-adds the API-billed codex seam) warns again.
+        codexLiveRefused = false;
+        return false;
+    }
+    // Emit config_changed and model_changed for what this reload actually changed.
+    function emitConfigChangeEvents(nextConfig) {
+        // A live edit that changes behavior elsewhere logs one event naming the settings that
+        // changed (maxConcurrent and sessionRetentionDays have their own events elsewhere).
+        const changedKeys = changedConfigKeys(prevLive, nextConfig);
+        if (changedKeys.length > 0) {
+            emit({ source: TUMWATER_SOURCE, type: "config_changed", keys: changedKeys });
+            // A real model-wiring change gets its own event naming the new selector(s), which the
+            // key list cannot show; a non-model edit (instructions, an interval) emits nothing.
+            const fromModel = teamModelLabel(prevLive);
+            const toModel = teamModelLabel(nextConfig);
+            const roleDiffs = changedKeys
+                .filter((key) => key.startsWith("roles."))
+                .map((key) => {
+                const role = key.slice("roles.".length);
+                const from = modelSelectorField(configForRole(prevLive, role)).model ?? null;
+                const to = modelSelectorField(configForRole(nextConfig, role)).model ?? null;
+                return { role, from, to };
+            })
+                .filter((d) => d.from !== d.to);
+            if (fromModel !== toModel || roleDiffs.length > 0)
+                emit({
+                    source: TUMWATER_SOURCE,
+                    type: "model_changed",
+                    from: fromModel,
+                    to: toModel,
+                    ...(roleDiffs.length > 0 ? { roles: roleDiffs } : {}),
+                });
+        }
+    }
+    // Verify and seed each backend a live edit newly routes to.
+    function seedNewlyRoutedBackends(nextConfig, prevBackends) {
+        // A live edit that routes a seam to a backend the previous config did not use: the
+        // team keeps running, but that backend must be verified and its account (claude) or
+        // models catalog (opencode) seeded, exactly as startup would — so a claude reviewer
+        // added to a pi team does not start uncheckable. A missing binary is a warning event,
+        // never a crash; a present one logs its verdict as a backend_binary event. The seed is
+        // attempted once per root. (The codex seed moved to the refusal check at the top of
+        // this block, which also refuses an API-key-logged-in codex seam.)
+        for (const backend of backendsInUse(nextConfig)) {
+            if (prevBackends.has(backend))
+                continue;
+            const resolved = resolveBackendBin(nextConfig, backend);
+            if (findBackendBinary(resolved)) {
+                emit({ source: TUMWATER_SOURCE, type: "backend_binary", agent: backend, found: true });
+            }
+            else {
+                warn(`newly routed ${backend} backend: ${backendMissingMessage(resolved, backend)}`);
+            }
+            if (backend === "claude" && !liveClaudeSeedAttempted.has(deps.root)) {
+                liveClaudeSeedAttempted.add(deps.root);
+                seedClaudeAccount(deps.root, nextConfig);
+            }
+            if (backend === "opencode" && !liveOpencodeSeedAttempted.has(deps.root)) {
+                liveOpencodeSeedAttempted.add(deps.root);
+                // Not awaited: poll() is synchronous and a models.dev fetch must not stall the loop.
+                void seedOpencodeCatalog(deps.root, nextConfig, { ...deps.opencodeSeed, warn }).catch((err) => warn(`open code model catalog seed failed: ${errorMessage(err)}`));
+            }
+        }
+    }
+    // Live-resize the concurrency cap and the per-provider key caps.
+    function resizeConcurrency(nextConfig) {
+        // Live-resize the concurrency cap: a mid-run edit changes how many pi runs execute
+        // concurrently within this poll — no restart. Growing admits already-queued runs;
+        // shrinking never preempts in-flight work, it only caps future grants.
+        const newMaxConcurrent = Math.max(1, nextConfig.maxConcurrent);
+        if (newMaxConcurrent !== lastMaxConcurrent) {
+            deps.semaphore.setCapacity(newMaxConcurrent);
+            emit({ source: TUMWATER_SOURCE, type: "max_concurrent_changed", from: lastMaxConcurrent, to: newMaxConcurrent });
+            lastMaxConcurrent = newMaxConcurrent;
+        }
+        // Live-resize the per-provider caps (plans/provider-concurrency.md §7): an edit
+        // re-applies the whole map to the pool, and each changed provider fires its own
+        // `provider_concurrency_changed` event. setKeyCaps never preempts — shrinking only
+        // withholds future grants on that key until releases drain it under the new cap.
+        const nextKeyCaps = nextConfig.maxConcurrentPerProvider ?? {};
+        deps.semaphore.setKeyCaps(nextKeyCaps);
+        for (const provider of new Set([...Object.keys(lastKeyCaps), ...Object.keys(nextKeyCaps)])) {
+            const from = lastKeyCaps[provider];
+            const to = nextKeyCaps[provider];
+            if (from !== to) {
+                emit({
+                    source: TUMWATER_SOURCE,
+                    type: "provider_concurrency_changed",
+                    provider,
+                    from: from ?? 0,
+                    to: to ?? 0,
+                });
+            }
+        }
+        lastKeyCaps = nextKeyCaps;
+    }
+    // Sync the runner list to newly enabled roles and warn on enable/disable.
+    function syncRunners(nextConfig) {
+        const nowEnabled = runnerIds(nextConfig);
+        // Enabling a role — or raising `roles.<id>.instances` — mid-run starts it: create the
+        // runner for each newly present role id (its persisted state survives). A lowered
+        // instance count keeps its runner; `runnerEnabled` skips its future runs. A scoped round
+        // skips every other id: the enabling is logged (the warn loop below), but its runner
+        // waits for the next unscoped round.
+        for (const role of nowEnabled) {
+            if (deps.roleFilter !== undefined && !deps.roleFilter.includes(role))
+                continue;
+            if (!deps.runners.some((r) => r.role === role))
+                deps.runners.push(new RoleRunner(deps.root, role, nextConfig, deps.mainBranch, deps.runnerSignal));
+        }
+        for (const role of prevEnabled)
+            if (!nowEnabled.includes(role))
+                warn(`role ${role} disabled — no new runs`);
+        for (const role of nowEnabled)
+            if (!prevEnabled.has(role))
+                warn(`role ${role} enabled — starting runs`);
+        prevEnabled = new Set(nowEnabled);
+    }
+    // Warn once per distinct broken-file error text.
+    function noteInvalidConfig(reloaded) {
+        if (reloaded.error && reloaded.error !== lastConfigError) {
+            warn(`tumwater.json invalid — keeping current config: ${reloaded.error}`);
+            lastConfigError = reloaded.error;
+        }
+    }
     return {
         poll() {
             const reloaded = loadConfigCached(deps.root);
-            // A missing file keeps the last-known-good config too, and never reloads as defaults: the
-            // team was started on a real file (startup refuses to run without one), so its vanishing
-            // mid-run is an incident — a merge's fast-forward deleted it on 2026-09-22 and the team
-            // silently ran 8.6 h on defaults (BUGS.md 2026-09-23). One warning per vanish, not per
-            // poll; its return logs one line, then the normal reload below diffs it against the
-            // retained config — so config_changed names only what the returned file really changed.
-            if (reloaded.missing) {
-                if (!configMissing) {
-                    warn(`tumwater.json missing — keeping current config until it returns (${configPath(deps.root)})`);
-                    configMissing = true;
-                    lastConfigError = null; // Whatever state it returns in is stated afresh.
-                }
-            }
-            else if (configMissing) {
-                warn("tumwater.json reappeared — reloading it");
-                configMissing = false;
-            }
+            noteConfigPresence(reloaded);
             if (reloaded.config) {
                 const nextConfig = reloaded.config;
-                // A live edit that routes a seam to a codex logged in with an API key is refused before
-                // the reload is applied: startup refuses the same codex seam (decision 5), and here a
-                // warn-only would let the running team spend per-token Codex the budget cap cannot see
-                // (review objection 1). Refusing keeps the last-known-good config, like a missing or
-                // broken file. The seed runs once per root (`codex login status` is a real probe); the
-                // persisted account file is the voice of the refusal on later polls, re-probing a stale
-                // api answer (codex-account.ts) so the operator's `codex login --device-auth` remedy
-                // clears it at the next seed. A subscription codex passes through to the backend loop.
                 const prevBackends = new Set(backendsInUse(prevLive));
-                const newlyRoutedCodex = !prevBackends.has("codex") && backendsInUse(nextConfig).includes("codex");
-                if (newlyRoutedCodex && !liveCodexSeedAttempted.has(deps.root)) {
-                    liveCodexSeedAttempted.add(deps.root);
-                    seedCodexAccount(deps.root, nextConfig);
-                }
-                if (newlyRoutedCodex && readCodexAccount(deps.root)?.billing === "api") {
-                    if (codexLiveRefused)
-                        return prevLive;
-                    codexLiveRefused = true;
-                    warn("refusing live edit: Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run `CODEX_HOME=<home> codex login --device-auth`");
+                if (refuseApiKeyCodex(nextConfig, prevBackends))
                     return prevLive;
-                }
-                // A poll that did not refuse clears the warn-once marker so a later re-entry into the
-                // refusal (the operator reverts, then re-adds the API-billed codex seam) warns again.
-                codexLiveRefused = false;
-                live = reloaded.config;
-                // A live edit that changes behavior elsewhere logs one event naming the settings that
-                // changed (maxConcurrent and sessionRetentionDays have their own events elsewhere).
-                const changedKeys = changedConfigKeys(prevLive, reloaded.config);
-                if (changedKeys.length > 0) {
-                    emit({ source: TUMWATER_SOURCE, type: "config_changed", keys: changedKeys });
-                    // A real model-wiring change gets its own event naming the new selector(s), which the
-                    // key list cannot show; a non-model edit (instructions, an interval) emits nothing.
-                    const fromModel = teamModelLabel(prevLive);
-                    const toModel = teamModelLabel(reloaded.config);
-                    const roleDiffs = changedKeys
-                        .filter((key) => key.startsWith("roles."))
-                        .map((key) => {
-                        const role = key.slice("roles.".length);
-                        const from = modelSelectorField(configForRole(prevLive, role)).model ?? null;
-                        const to = modelSelectorField(configForRole(nextConfig, role)).model ?? null;
-                        return { role, from, to };
-                    })
-                        .filter((d) => d.from !== d.to);
-                    if (fromModel !== toModel || roleDiffs.length > 0)
-                        emit({
-                            source: TUMWATER_SOURCE,
-                            type: "model_changed",
-                            from: fromModel,
-                            to: toModel,
-                            ...(roleDiffs.length > 0 ? { roles: roleDiffs } : {}),
-                        });
-                }
-                // A live edit that routes a seam to a backend the previous config did not use: the
-                // team keeps running, but that backend must be verified and its account (claude) or
-                // models catalog (opencode) seeded, exactly as startup would — so a claude reviewer
-                // added to a pi team does not start uncheckable. A missing binary is a warning event,
-                // never a crash; a present one logs its verdict as a backend_binary event. The seed is
-                // attempted once per root. (The codex seed moved to the refusal check at the top of
-                // this block, which also refuses an API-key-logged-in codex seam.)
-                for (const backend of backendsInUse(reloaded.config)) {
-                    if (prevBackends.has(backend))
-                        continue;
-                    const resolved = resolveBackendBin(reloaded.config, backend);
-                    if (findBackendBinary(resolved)) {
-                        emit({ source: TUMWATER_SOURCE, type: "backend_binary", agent: backend, found: true });
-                    }
-                    else {
-                        warn(`newly routed ${backend} backend: ${backendMissingMessage(resolved, backend)}`);
-                    }
-                    if (backend === "claude" && !liveClaudeSeedAttempted.has(deps.root)) {
-                        liveClaudeSeedAttempted.add(deps.root);
-                        seedClaudeAccount(deps.root, reloaded.config);
-                    }
-                    if (backend === "opencode" && !liveOpencodeSeedAttempted.has(deps.root)) {
-                        liveOpencodeSeedAttempted.add(deps.root);
-                        // Not awaited: poll() is synchronous and a models.dev fetch must not stall the loop.
-                        void seedOpencodeCatalog(deps.root, reloaded.config, { ...deps.opencodeSeed, warn }).catch((err) => warn(`open code model catalog seed failed: ${errorMessage(err)}`));
-                    }
-                }
-                prevLive = reloaded.config;
+                live = nextConfig;
+                emitConfigChangeEvents(nextConfig);
+                seedNewlyRoutedBackends(nextConfig, prevBackends);
+                prevLive = nextConfig;
                 for (const r of deps.runners)
-                    r.config = reloaded.config;
-                // Live-resize the concurrency cap: a mid-run edit changes how many pi runs execute
-                // concurrently within this poll — no restart. Growing admits already-queued runs;
-                // shrinking never preempts in-flight work, it only caps future grants.
-                const newMaxConcurrent = Math.max(1, reloaded.config.maxConcurrent);
-                if (newMaxConcurrent !== lastMaxConcurrent) {
-                    deps.semaphore.setCapacity(newMaxConcurrent);
-                    emit({ source: TUMWATER_SOURCE, type: "max_concurrent_changed", from: lastMaxConcurrent, to: newMaxConcurrent });
-                    lastMaxConcurrent = newMaxConcurrent;
-                }
-                // Live-resize the per-provider caps (plans/provider-concurrency.md §7): an edit
-                // re-applies the whole map to the pool, and each changed provider fires its own
-                // `provider_concurrency_changed` event. setKeyCaps never preempts — shrinking only
-                // withholds future grants on that key until releases drain it under the new cap.
-                const nextKeyCaps = reloaded.config.maxConcurrentPerProvider ?? {};
-                deps.semaphore.setKeyCaps(nextKeyCaps);
-                for (const provider of new Set([...Object.keys(lastKeyCaps), ...Object.keys(nextKeyCaps)])) {
-                    const from = lastKeyCaps[provider];
-                    const to = nextKeyCaps[provider];
-                    if (from !== to) {
-                        emit({
-                            source: TUMWATER_SOURCE,
-                            type: "provider_concurrency_changed",
-                            provider,
-                            from: from ?? 0,
-                            to: to ?? 0,
-                        });
-                    }
-                }
-                lastKeyCaps = nextKeyCaps;
-                const nowEnabled = runnerIds(reloaded.config);
-                // Enabling a role — or raising `roles.<id>.instances` — mid-run starts it: create the
-                // runner for each newly present role id (its persisted state survives). A lowered
-                // instance count keeps its runner; `runnerEnabled` skips its future runs. A scoped round
-                // skips every other id: the enabling is logged (the warn loop below), but its runner
-                // waits for the next unscoped round.
-                for (const role of nowEnabled) {
-                    if (deps.roleFilter !== undefined && !deps.roleFilter.includes(role))
-                        continue;
-                    if (!deps.runners.some((r) => r.role === role))
-                        deps.runners.push(new RoleRunner(deps.root, role, reloaded.config, deps.mainBranch, deps.runnerSignal));
-                }
-                for (const role of prevEnabled)
-                    if (!nowEnabled.includes(role))
-                        warn(`role ${role} disabled — no new runs`);
-                for (const role of nowEnabled)
-                    if (!prevEnabled.has(role))
-                        warn(`role ${role} enabled — starting runs`);
-                prevEnabled = new Set(nowEnabled);
+                    r.config = nextConfig;
+                resizeConcurrency(nextConfig);
+                syncRunners(nextConfig);
                 lastConfigError = null;
             }
-            else if (reloaded.error && reloaded.error !== lastConfigError) {
-                warn(`tumwater.json invalid — keeping current config: ${reloaded.error}`);
-                lastConfigError = reloaded.error;
+            else {
+                noteInvalidConfig(reloaded);
             }
             return live;
         },

package/dist/src/config/config-views.js

@@ -109,12 +109,7 @@ export function tierModel(config, tier) {
  * key it overrides would.
  *
  * `tier` is the seam's effective tier, already resolved by the caller from any tier-name
- * override — so `o.model` here is always a selector string, never a tier reference.
- *
- * Exported so imageRerouteTarget (src/agent/image-input.ts) can probe a peer tier's
- * top-level model (`withModelOverrides(config, tier, {})`, the same shape resolverConfig
- * builds strong with) and reshape a tier's fallback pair into a runnable config — the
- * tier-config builder the plan names. */
+ * override — so `o.model` here is always a selector string, never a tier reference. */
 export function withModelOverrides(config, tier, o) {
     // The top-level model resolves at the seam's tier: a string form is the default tier's
     // selector; a map form takes the tier's entry, else `default`'s.
@@ -204,7 +199,7 @@ export function configForRole(config, role) {
 }
 /** The config a role's runs SCHEDULE from: configForRole, except that while PLANS.md still
  * has planning room (planBacklogOpen — below the plan role's eligible-plan target, or holding
- * a plan that needs review/needs replan) the plan role schedules with a ZERO min gap, so a
+ * a plan that needs review) the plan role schedules with a ZERO min gap, so a
  * productive plan run reruns on the next poll and an unproductive one drops to the idle
  * backoff. The plan role's own machine signal is `planBacklogFull` (src/scheduling/claims.ts):
  * a fresh project's empty backlog is not full, so this subsumes the old placeholder-status

package/dist/src/config/config-write.js

@@ -13,12 +13,28 @@
 import { isDeepStrictEqual } from "node:util";
 import { modelTierMap } from "./config-schema.js";
 import { isJsonObject, objectOrEmpty } from "../files/json-object.js";
+import { isExponentSpelling } from "../text/text.js";
 import { show } from "./config-field-checks.js";
 import { canonicalConfigKey } from "./config-aliases.js";
 import { unknownRoleMessage } from "../roles/roles.js";
 import { loadConfig, collapseBackendAliases, knownRoleIdsCached, } from "./config.js";
 import { checkDailyBudgetUsd, checkProviderConcurrencyCap, checkQuietHours, parseConfigKey, PER_KEY_VALIDATORS, unknownConfigKeyError, unknownRoleFieldError, } from "./config-keys.js";
 import { writeConfigMutation, fail, rawConfigObject, without, preservingFileRoles, preserveFileRoles, withSectionOrDropped, } from "./config-write-core.js";
+/** Drop `field` from the `backends.<backend>` entry of the config `next`, dropping the whole
+ * backend entry when it empties. The one home of the "remove a nested backend field, drop the
+ * backend when empty" step the legacy `agentBin`/`piArgs` collapse and the `claudeWindowReserve`
+ * collapse share, so the empty-entry rule cannot drift between the two. */
+function dropNestedBackendField(next, backend, field) {
+    const record = next;
+    const backends = { ...(record.backends ?? {}) };
+    const entry = { ...(backends[backend] ?? {}) };
+    delete entry[field];
+    if (Object.keys(entry).length === 0)
+        delete backends[backend];
+    else
+        backends[backend] = entry;
+    return { ...next, backends: backends };
+}
 /** Set the daily cost budget cap in tumwater.json through the shared writer idiom (see
  * writeConfigMutation), after checkDailyBudgetUsd has screened the value with its own
  * actionable message — the one both dashboards flash. A cap the config already resolves to
@@ -80,10 +96,7 @@ export function setConfigKey(root, key, rawValue) {
             (parsed.kind === "map" && parsed.map === "maxConcurrentPerProvider") ||
             (parsed.kind === "role" && parsed.field === "instances") ||
             (parsed.kind === "section" && parsed.section === "bootstrap" && parsed.field === "untilPlansDone");
-        if (isPlainIntegerKey &&
-            trimmed !== "" &&
-            !/^\d*\.?\d+$/.test(trimmed) &&
-            /^\d+(\.\d+)?[eE][+-]?\d+$/.test(trimmed))
+        if (isPlainIntegerKey && trimmed !== "" && isExponentSpelling(trimmed))
             return `${key} must be a plain integer — no exponent notation`;
         return null;
     };
@@ -267,31 +280,11 @@ export function setConfigKey(root, key, rawValue) {
         let unchanged;
         // Writers keep one spelling: a legacy top-level set drops the matching backends.pi field, so
         // the file can never hold both (validateConfig's raw pass rejects a file that does).
-        const dropLegacyPiAlias = (next, key) => {
-            const record = next;
-            const backends = { ...(record.backends ?? {}) };
-            const entry = { ...(backends.pi ?? {}) };
-            delete entry[key === "agentBin" ? "bin" : "args"];
-            if (Object.keys(entry).length === 0)
-                delete backends.pi;
-            else
-                backends.pi = entry;
-            return { ...next, backends: backends };
-        };
+        const dropLegacyPiAlias = (next, key) => dropNestedBackendField(next, "pi", key === "agentBin" ? "bin" : "args");
         // Writers keep one spelling: setting the top-level `claudeWindowReserve` drops the nested
         // `backends.claude.windowReserve`, so a supported `config set` never writes the rejected pair
         // (validateConfig still refuses a hand-edited file holding both).
-        const dropNestedReserve = (next) => {
-            const record = next;
-            const backends = { ...(record.backends ?? {}) };
-            const entry = { ...(backends.claude ?? {}) };
-            delete entry.windowReserve;
-            if (Object.keys(entry).length === 0)
-                delete backends.claude;
-            else
-                backends.claude = entry;
-            return { ...next, backends: backends };
-        };
+        const dropNestedReserve = (next) => dropNestedBackendField(next, "claude", "windowReserve");
         const result = writeConfigMutation(root, (cfg) => {
             oldValue = cfg[key];
             if (isDeepStrictEqual(oldValue, value)) {

package/dist/src/doctor/doctor-backlog-bugs.js

@@ -1,20 +1,18 @@
-import { andMore, quoteHeading, readBacklogChecked, FIX_CLAIMS_CHECKED, REFUSAL_NOTE_MAX, STALE_QUESTION_DAYS, STALE_BUG_DAYS, STALE_WAIT_DAYS } from "./doctor-backlog.js";
+import { andMore, quoteHeading, readBacklogChecked, FIX_CLAIMS_CHECKED, REFUSAL_NOTE_MAX, STALE_QUESTION_DAYS, STALE_BUG_DAYS } from "./doctor-backlog.js";
 import { truncate } from "../text/text.js";
+import { plural, agree } from "../text/phrases.js";
 import { ageInDays, filingDate, fixedBugEntries, openBugEntries, openQuestionEntries, plannedPlanEntries } from "../backlog/backlog.js";
-import { stripEntryStamp } from "../backlog/backlog-structure.js";
 import { questionFilingDate } from "../backlog/question-answer.js";
-import { refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
+import { needsReviewNote, refusalNote } from "../backlog/backlog-eligibility.js";
 import { plannedPartKeys, plansWaitingOn, prerequisitesMerged } from "../backlog/backlog-parts.js";
 import { lastDate } from "../backlog/backlog-md.js";
 import { formatTimestamp } from "../text/datetime.js";
 import { stringList } from "../files/json-object.js";
-import { byDaysThenIndex } from "../collections.js";
 import { readEventsSince } from "../events/event-window.js";
 import { okOutcome, warnOutcome } from "./outcome.js";
 /** The doctor's open-bug and question checks, split out of doctor-backlog.ts: questions that
  * have waited too long for an answer (checkStaleQuestions), bugs left unfixed (checkStaleBugs),
- * bugs held for their next failure (checkWaitingBugs, with its quotedTestName / waitingNoteDate /
- * failureMentions helpers), fixed records whose quoted test regressed (checkRegressedFixes), and
+ * fixed records whose quoted test regressed (checkRegressedFixes), and
  * entries parked by a Refused note (checkRefusedEntries). They import the shared helpers
  * (readBacklogChecked, andMore) from doctor-backlog.ts, plus the age/trim bounds, and
  * all warn instead of failing: a stale or
@@ -48,17 +46,18 @@ export function checkStaleQuestions(root) {
     return warnOutcome(`QUESTIONS.md question ${quoteHeading(first.title)} has waited ${first.days} d for an answer${more} — ` +
         `a question that waits too long for a human answer is worth your attention`);
 }
-/** Stale bugs — unrefused open BUGS.md bugs whose `(found by … YYYY-MM-DD)` or `(reported …)`
- * stamp is at least 3 days old. The bugfix role fixes a bug within hours, so one that sits means
- * no role is fixing it. Positions are the 1-based `bug --list` numbers; a refused bug is skipped
- * (checkRefusedEntries names it), a waiting bug is skipped (checkWaitingBugs names it) and so is
- * an undated heading. A warn, never a fail. */
+/** Stale bugs — unrefused, unheld open BUGS.md bugs whose `(found by … YYYY-MM-DD)` or
+ * `(reported …)` stamp is at least 3 days old. The bugfix role fixes a bug within hours, so one
+ * that sits means no role is fixing it. Positions are the 1-based `bug --list` numbers; a refused
+ * bug is skipped (checkRefusedEntries names it), a bug parked by a Needs-review note is skipped
+ * (the note names what would make it fail, so it is not unfixed), and so is an undated heading.
+ * A warn, never a fail. */
 export function checkStaleBugs(root) {
     const doc = readBacklogChecked(root, "BUGS.md");
     if (typeof doc !== "string")
         return doc;
     const stale = openBugEntries(root).flatMap((entry, index) => {
-        if (refusalNote(entry.body) !== null || waitingNote(entry.body) !== null)
+        if (refusalNote(entry.body) !== null || needsReviewNote(entry.body) !== null)
             return [];
         const stamp = filingDate(entry.title);
         if (stamp === null)
@@ -85,10 +84,6 @@ export function quotedTestName(title) {
 function dayAfterMs(date) {
     return new Date(Number(date.slice(0, 4)), Number(date.slice(5, 7)) - 1, Number(date.slice(8, 10)) + 1).getTime();
 }
-/** The first `YYYY-MM-DD` in a Waiting for the next failure note's text, or null. */
-export function waitingNoteDate(note) {
-    return /\d{4}-\d{2}-\d{2}/.exec(note)?.[0] ?? null;
-}
 /** True when `text` is a check-failure report that names `name` as a test that failed — the
  * doctors' recurrence/regression evidence. The recurrence scans must not count any line that
  * merely *contains* the quoted test name as the flake's return, or a warning that only quotes
@@ -127,8 +122,8 @@ export function failureMentions(events, name, sinceMs) {
 }
 /** The newest failure report at or after `since` naming `name` — `failureMentions`'s last
  * mention — or undefined when none. The single home of the "did this flake come back after
- * its boundary?" step, shared by the waiting-bug recurrence scan (checkWaitingBugs) and the
- * regressed-fix match (matchedRegressedFixes), so both keep the same last-mention rule. */
+ * its boundary?" step, shared by the regressed-fix match (matchedRegressedFixes), so both
+ * keep the same last-mention rule. */
 function lastFailureMention(events, name, sinceMs) {
     const mentions = failureMentions(events, name, sinceMs);
     return mentions[mentions.length - 1];
@@ -136,104 +131,11 @@ function lastFailureMention(events, name, sinceMs) {
 /** The read-events window (ms) that reaches the oldest of `sinces` — `Date.now()` minus the
  * oldest timestamp, floored at 0 — so a recurrence check reads events past every candidate's
  * `since`. The single home of the "oldest of a set of since-times" step, shared by
- * checkWaitingBugs and checkRegressedFixes, so those sites cannot drift on the clamp or the
+ * checkRegressedFixes, so those sites cannot drift on the clamp or the
  * time base. */
 function sinceWindowMs(sinces) {
     return Math.max(0, Date.now() - Math.min(...sinces));
 }
-/** Open BUGS.md bugs held by a **Waiting for the next failure …** note, in file order: the
- * doctor's `checkWaitingBugs` selection and anchor, factored out so the always-on stale-wait
- * feed (staleWaitingBugRows) reads the same held set and cannot drift from the doctor's rule.
- * A bug that is also Refused is left to checkRefusedEntries. `since` is the day-after the
- * note's date — the recurrence scan's boundary; `date` the note's own `YYYY-MM-DD` or null. */
-function heldWaitingBugs(root) {
-    return openBugEntries(root).flatMap((entry, index) => {
-        const note = waitingNote(entry.body);
-        if (note === null || refusalNote(entry.body) !== null)
-            return [];
-        const name = quotedTestName(entry.title);
-        const date = waitingNoteDate(note);
-        const since = name !== null && date !== null ? dayAfterMs(date) : null;
-        return [{ index, position: index + 1, title: entry.title, note, name, since, date }];
-    });
-}
-/** Waiting bugs — open BUGS.md bugs held by a **Waiting for the next failure …** note, which
- * parks a bug until it fails again. Positions are the 1-based `bug --list` numbers; a bug that
- * is also Refused is left to checkRefusedEntries. Ok when the hold is undisturbed — doctor
- * then only names the bugs and how to release one — and a warn when a held bug's quoted test
- * has failed in a gate or merge check since the day after its note (the note carries only a
- * date, so a same-day failure cannot be told from the one it was written about). A warn is
- * never a fail, and doctor writes nothing to BUGS.md. */
-export function checkWaitingBugs(root) {
-    const doc = readBacklogChecked(root, "BUGS.md");
-    if (typeof doc !== "string")
-        return doc;
-    const held = heldWaitingBugs(root);
-    const [first, ...rest] = held;
-    if (!first)
-        return okOutcome("no open bug is waiting for its next failure");
-    const sinces = held.flatMap((b) => (b.since !== null && !Number.isNaN(b.since) ? [b.since] : []));
-    if (sinces.length > 0) {
-        const { events } = readEventsSince(root, sinceWindowMs(sinces));
-        const recurred = held.flatMap((b) => {
-            if (b.name === null || b.since === null)
-                return [];
-            const newest = lastFailureMention(events, b.name, b.since);
-            return newest ? [{ ...b, newest }] : [];
-        });
-        const [again, ...others] = recurred;
-        if (again) {
-            const more = andMore(others, (b) => `#${b.position} ${quoteHeading(b.title)}`);
-            return warnOutcome(`BUGS.md bug #${again.position} ${quoteHeading(again.title)} failed again since its Waiting for the next failure note ` +
-                `(${formatTimestamp(again.newest.ts)}: ${truncate(again.newest.text, REFUSAL_NOTE_MAX)})${more} — ` +
-                `record the occurrence under the entry and release it with \`tumwater bug --release ${again.position}\``);
-        }
-    }
-    /* A Waiting hold has no expiry of its own, so a bug whose flake never comes back parks
-     * indefinitely; a hold that has outlived STALE_WAIT_DAYS without a recurrence is escalated
-     * from the ok below to a warn so the operator is nudged to release or re-hold it. */
-    const lapsed = held.flatMap((b) => {
-        /* An undated note (no YYYY-MM-DD in its text) has no hold-start marker, and checkStaleBugs
-         * skips any bug carrying a waiting note, so without a fallback it would park indefinitely
-         * too; the filing stamp anchors it — the hold cannot be younger than the bug it dates from. */
-        const anchor = b.date ?? filingDate(b.title);
-        if (anchor === null)
-            return [];
-        const days = ageInDays(anchor);
-        return days >= STALE_WAIT_DAYS ? [{ ...b, days }] : [];
-    });
-    const [firstLapsed, ...restLapsed] = lapsed;
-    if (firstLapsed) {
-        const more = andMore(restLapsed, (b) => `#${b.position} ${quoteHeading(b.title)}`);
-        return warnOutcome(`BUGS.md bug #${firstLapsed.position} ${quoteHeading(firstLapsed.title)} has waited ${firstLapsed.days} d for its next failure without one ` +
-            `— its flake likely never comes back, so it parks indefinitely; release it with \`tumwater bug --release ${firstLapsed.position}\`${more}`);
-    }
-    const more = andMore(rest, (b) => `#${b.position} ${quoteHeading(b.title)}`);
-    return okOutcome(`BUGS.md bug #${first.position} ${quoteHeading(first.title)} is held until it fails again ` +
-        `(${truncate(first.note, REFUSAL_NOTE_MAX)})${more} — selfcheck lifts the note when it records a new occurrence; ` +
-        `release it now with \`tumwater bug --release ${first.position}\``);
-}
-/** The always-on rows behind the dashboard/TUI/`tumwater status` waiting-bug alert: open BUGS.md
- * bugs held by a **Waiting for the next failure …** note whose anchor (the note's `YYYY-MM-DD`,
- * else the heading's filing stamp) is at least STALE_WAIT_DAYS old. Shares the doctor's
- * STALE_WAIT_DAYS threshold and the heldWaitingBugs selection/anchor, so the alert and the
- * doctor's `waiting bugs` row cannot drift on the rule; an undated note-and-heading is skipped.
- * The returned objects carry the 0-based index (drawer address `bugs:<index>`), the 1-based
- * position (`bug --release <position>`), the stamp-stripped title, and the whole-day age.
- * Returned most-days-waited-first, ties in file order, like staleOpenBugs. This deliberately
- * omits `checkWaitingBugs`'s recurrence scan, because that scan reads events back to the oldest
- * hold and is too costly on the status poll path; the doctor still reports a recurrence first. */
-export function staleWaitingBugRows(root, now = Date.now()) {
-    return heldWaitingBugs(root)
-        .flatMap((b) => {
-        const anchor = b.date ?? filingDate(b.title);
-        if (anchor === null)
-            return [];
-        const days = ageInDays(anchor, now);
-        return days >= STALE_WAIT_DAYS ? [{ index: b.index, position: b.position, title: stripEntryStamp(b.title), days }] : [];
-    })
-        .sort(byDaysThenIndex);
-}
 /** The regression candidates for the `regressed fixes` feed: a newest-FIX_CLAIMS_CHECKED BUGS.md
  * Fixed record whose heading quotes a test name and carries a `YYYY-MM-DD` date, unless an Open
  * bug already quotes the same test (which means the regression is filed). Shared by the doctor's
@@ -316,12 +218,12 @@ export function checkRefusedEntries(root) {
         return okOutcome("no planned plan or open bug is held by a Refused note");
     const more = andMore(rest, (e) => `${e.file} ${e.command} #${e.position} ${quoteHeading(e.title)}` +
         (e.mergeDone.length > 0 ? " [prerequisites no longer planned]" : "") +
-        (e.waiting > 0 ? ` [${e.waiting} part(s) wait on it]` : ""));
+        (e.waiting > 0 ? ` [${plural(e.waiting, "part waits on it", "parts wait on it")}]` : ""));
     const stale = first.mergeDone.length > 0
-        ? `; its prerequisite(s) ${first.mergeDone.map((r) => `${r.series} ${r.part}/${r.of}`).join(", ")} are no longer planned, so the refusal may be stale`
+        ? `; its ${agree(first.mergeDone.length, "prerequisite", "prerequisites")} ${first.mergeDone.map((r) => `${r.series} ${r.part}/${r.of}`).join(", ")} ${agree(first.mergeDone.length, "is", "are")} no longer planned, so the refusal may be stale`
         : "";
     const waiting = first.waiting > 0
-        ? `; ${first.waiting} planned part(s) wait on it, directly or through an earlier part`
+        ? `; ${plural(first.waiting, "planned part waits on it", "planned parts wait on it")}, directly or through an earlier part`
         : "";
     return warnOutcome(`${first.file} ${first.command} #${first.position} "${first.title}" is held by a Refused note ` +
         `(${truncate(first.note, REFUSAL_NOTE_MAX)})${stale}${waiting}${more} — no role takes a refused entry until it is edited: ` +