tumwater 0.3.0 → 0.4.0

package/dist/src/budget/budget-fallback-view.js

@@ -0,0 +1,288 @@
+/** The fallback config view the budget gate derives each poll, split out of pollBudgetGate's
+ * event-and-verdict half (src/gates/budget-gates.ts) so the two halves each have a plain
+ * function boundary and their own tests (the same split stage-path-checks.ts made of
+ * stage-check.ts). This module owns everything pollBudgetGate does from its `onFallback` seam
+ * through the end of the function: the seam/backends walk and used-up window moves
+ * (`windowOut`, `movedBackends`, `windowMove`, `windowTiers`, `windowResumedBackends`,
+ * `windowResumed`), the motion keys (`resolvedKey`, `movedKey`, `fromKey`), the two view
+ * derivations (`fallbackConfig`/`directorConfig`), the `movedTiers`/`applyFallbackModel`
+ * application, `chainInfo`, and the `pairs` handback list. Its one entry reads the inputs
+ * pollBudgetGate's first half already resolved and returns the view fields `BudgetGatePoll`
+ * carries, so pollBudgetGate keeps its call signature and src/gates/gate-polls.ts's
+ * destructure of it is unchanged. The plan references the moved comments carry (part 5b/8,
+ * part 5c/8, 6a/7) hold here. */
+import { MODEL_TIERS, } from "../config/config-schema.js";
+import { modelPairName, pairDailyCost } from "../budget/budget.js";
+import { fallbackServingPair, } from "../budget/fallback-breaker.js";
+import { applyFallbackModel, seamsInUse, tierChainSteps, tierFallbackLabels, } from "../config/config-fallbacks.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { enabledRoleIds } from "../config/config.js";
+import { formatModelSelector, seamAgent } from "../config/model-selector.js";
+import { configForRole, isTierName, reviewConfig, roleSeamTier, withModelOverrides, } from "../config/config-views.js";
+import { piPairFree, seamFree } from "../pi/pi-models.js";
+import { dayAt } from "../text/datetime.js";
+/** Can the account not take extra usage: some window is rejected, or the newest non-reset
+ * window's `overageStatus` is `rejected`. Shared with budget-gates.ts's verdict half (its
+ * per-pair `pairFreeAt` reads the same overage refusal). */
+export function claudeOverageRefused(account) {
+    const live = Object.values(account.windows).filter((w) => w.status !== "reset");
+    if (live.some((w) => w.status === "rejected"))
+        return true;
+    const newest = live.reduce((a, w) => (a === null || w.observedAt > a.observedAt ? w : a), null);
+    return newest?.overageStatus === "rejected";
+}
+/** The subscription backend a fallback pair or model seam routes to, when that backend's
+ * account reads subscription billing: a resolved seam's own routed agent, else a fallback
+ * pair's `backend` (`x.backend`), whose account is `billing === "subscription"`, else null.
+ * One backend can be a subscription while another bills by API, so a used-up window is judged
+ * per backend. Exported for the gate-polls window loop (part 2e/9), which reads it per
+ * backend in use. */
+export function subscriptionBackendOf(x, accounts) {
+    const seam = x;
+    // A resolved seam carries its routed backend in `agent` (fallback pairs never do); a raw
+    // fallback pair carries the backend in its own `backend` field.
+    const id = seam.agent !== undefined ? seamAgent({ agent: seam.agent }) : seam.backend;
+    if (id === undefined)
+        return null;
+    const account = accounts(id);
+    return account?.billing === "subscription" ? id : null;
+}
+/** Derive the fallback view for one poll from the verdict half's already-resolved inputs
+ * (`priceResolved`, `servingResolved`, `chainPairs`, `pairNames`) and the `reached` flag
+ * and the shared reads (`state`, `config`, `accounts`, `windowOutFor`/`directorWindowOutFor`,
+ * `providers`, `catalog`), writing the cross-poll view state (`from`/`fromKey`/`fallbackConfig`,
+ * `directorFrom`/`directorKey`/`directorView`, `prevWindowMoved`) and returning the view fields
+ * pollBudgetGate hands back. */
+export function budgetFallbackView(a) {
+    const { state, config: liveConfig, now, states, providers, catalog, accounts, windowOutFor, directorWindowOutFor, priceResolved, servingResolved, chainPairs, pairNames, reached, } = a;
+    // While the fallback holds, roles run under the derived view — the free pair installed
+    // top-level and every per-role/reviewer model override dropped, so no seam can reach a priced
+    // model. A breaker-demoted fallback keeps the view too: its gate is `paused`, but a run parked
+    // in the semaphore when it tripped, the half-open probe, and the merges must still run on the
+    // free pair — a demotion must never promote them to the priced model the cap already spent.
+    const onFallback = reached && pairNames.length > 0;
+    // A used-up window moves the subscription jobs of the backend whose window stands to their
+    // tier's fallback below the cap too; with no fallback to move to, nothing changes and that
+    // backend's hold applies. Every backend with a subscription seam in the config counts
+    // (seamsInUse enumerates them: every enabled role, the reviewer, the resolver, the director,
+    // and every tier fallback step), so a used-up window with no seam on that backend (or no
+    // fallback) moves nothing.
+    const seamBackends = new Set();
+    for (const seam of seamsInUse(liveConfig)) {
+        if (seam.agent === undefined)
+            continue;
+        const acc = accounts(seam.agent);
+        if (acc?.billing === "subscription")
+            seamBackends.add(seam.agent);
+    }
+    // The used-up windows behind this poll's move, keyed by backend: a backend counts only when
+    // a subscription seam of it is in the config, its own window is used up, and there is a
+    // fallback pair to move to. `windowOut` names only those backends; a healthy or absent
+    // backend's window is untouched.
+    const windowOut = {};
+    const movedBackends = new Set();
+    for (const backend of seamBackends) {
+        const win = windowOutFor(backend);
+        if (win !== null && pairNames.length > 0) {
+            windowOut[backend] = win;
+            movedBackends.add(backend);
+        }
+    }
+    const windowMove = movedBackends.size > 0;
+    // The resolved pairs are part of the key: a priced step crossing its own daily cap changes
+    // the resolution without a config or window change, and the view must follow it.
+    const resolvedKey = MODEL_TIERS.map((t) => {
+        const rp = priceResolved[t].pair;
+        return rp ? modelPairName(rp) : "-";
+    }).join(",");
+    // The set of window-moved backends is part of the key too (not just the `w` flag): a second
+    // backend's window can come or go while the move still stands, and the view must re-derive
+    // for the roles it newly blocks or frees.
+    const movedKey = [...movedBackends].sort().join("+");
+    const fromKey = `${windowMove ? "w" : ""}${reached ? "c" : ""}|${movedKey}|${resolvedKey}`;
+    if ((onFallback || windowMove) && (state.from !== liveConfig || state.fromKey !== fromKey)) {
+        state.from = liveConfig;
+        state.fromKey = fromKey;
+        // A job keeps its own model while that model is available: below the cap every seam but a
+        // subscription one whose own backend's window is used up; at the cap it must also be free.
+        const seamBlocked = (seam) => {
+            const b = subscriptionBackendOf(seam, accounts);
+            return b !== null && windowOut[b] !== undefined;
+        };
+        const available = (seam) => !seamBlocked(seam) && (!reached || seamFree(providers, seam, accounts, catalog));
+        const view = applyFallbackModel(liveConfig, priceResolved, available);
+        // A role pinned to a subscription backend under a tier of another backend has no tier pair
+        // to fall onto — dropping its override would put it on the tier's priced primary — so it
+        // keeps its pin and that backend's hold stops it, as before the window move.
+        if (movedBackends.size > 0) {
+            for (const role of enabledRoleIds(liveConfig)) {
+                const tier = roleSeamTier(liveConfig, role);
+                const pin = liveConfig.roles[role];
+                const roleBackend = subscriptionBackendOf(configForRole(liveConfig, role), accounts);
+                const tierBackend = subscriptionBackendOf(withModelOverrides(liveConfig, tier, {}), accounts);
+                if (pin && roleBackend !== null && roleBackend !== tierBackend)
+                    view.roles[role] = pin;
+            }
+            // A reviewer pinned to a subscription backend under such a tier would likewise end up on
+            // the tier's priced primary; it goes to the tier's fallback pair instead (a held reviewer
+            // would park the roles a pre-merge review gates).
+            const rm = liveConfig.review.model;
+            const reviewTier = isTierName(rm) ? rm : "strong";
+            const reviewPair = priceResolved[reviewTier].pair;
+            const reviewBackend = subscriptionBackendOf(reviewConfig(liveConfig), accounts);
+            const reviewTierBackend = subscriptionBackendOf(withModelOverrides(liveConfig, reviewTier, {}), accounts);
+            // Only the reviewer's own backend's window counts: a reviewer on a healthy backend must
+            // stay put even while another backend's window moves its tier.
+            if (reviewPair &&
+                reviewBackend !== null &&
+                windowOut[reviewBackend] !== undefined &&
+                reviewBackend !== reviewTierBackend)
+                view.review = {
+                    ...view.review,
+                    backend: reviewPair.backend ?? "pi",
+                    provider: undefined,
+                    model: formatModelSelector({
+                        provider: reviewPair.backend === undefined ? reviewPair.provider : undefined,
+                        model: reviewPair.model ?? "",
+                        thinking: reviewPair.thinking,
+                    }),
+                    thinking: undefined,
+                };
+        }
+        state.fallbackConfig = view;
+    }
+    // The tiers the window move put on a fallback pair: those whose own seam is a subscription
+    // backend whose window stands.
+    const windowTiers = {};
+    if (windowMove) {
+        const moved = new Set();
+        for (const tier of MODEL_TIERS) {
+            const b = subscriptionBackendOf(withModelOverrides(liveConfig, tier, {}), accounts);
+            if (b !== null && windowOut[b] !== undefined)
+                moved.add(tier);
+        }
+        const labels = tierFallbackLabels(priceResolved);
+        for (const tier of MODEL_TIERS)
+            if (moved.has(tier) && labels[tier] !== undefined)
+                windowTiers[tier] = labels[tier];
+    }
+    // The director follows availability, not the cap: while the window move stands and its own
+    // model job is a subscription backend, its tier's resolved pair replaces the live config (only
+    // subscription jobs of a used-up window are unavailable, so a priced director primary keeps
+    // its model over the cap). With no fallback (windowMove false) it stays on the live config and
+    // the scheduler holds it on that backend's hold.
+    const directorBackend = subscriptionBackendOf(configForRole(liveConfig, DIRECTOR_ROLE), accounts);
+    const directorMoved = directorBackend !== null && pairNames.length > 0 && directorWindowOutFor(directorBackend) !== null;
+    if (!directorMoved)
+        state.directorFrom = null;
+    else if (state.directorFrom !== liveConfig || state.directorKey !== resolvedKey) {
+        state.directorFrom = liveConfig;
+        state.directorKey = resolvedKey;
+        state.directorView = applyFallbackModel(liveConfig, priceResolved, (seam) => {
+            const b = subscriptionBackendOf(seam, accounts);
+            return b === null || windowOut[b] === undefined;
+        });
+    }
+    const windowResumedBackends = [...state.prevWindowMoved].filter((b) => !movedBackends.has(b));
+    const windowResumed = windowResumedBackends.length > 0;
+    state.prevWindowMoved = movedBackends;
+    const movedTiers = new Set();
+    // The tiers `applyFallbackModel` moved: those whose own seam fails the `available` test above.
+    for (const tier of MODEL_TIERS) {
+        const seam = withModelOverrides(liveConfig, tier, {});
+        const b = subscriptionBackendOf(seam, accounts);
+        const out = (windowMove && b !== null && windowOut[b] !== undefined) || (reached && !seamFree(providers, seam, accounts, catalog));
+        if (out)
+            movedTiers.add(tier);
+    }
+    const chain = chainInfo({
+        config: liveConfig,
+        resolved: servingResolved,
+        moved: movedTiers,
+        breakers: state.breakers,
+        states,
+        now,
+        windowOutFor,
+        accounts,
+        isPriced: (p) => !piPairFree(providers, p, accounts, catalog),
+    });
+    return {
+        onFallback,
+        chain,
+        roleConfig: onFallback || windowMove ? state.fallbackConfig : liveConfig,
+        pairs: distinctPairs(priceResolved, chainPairs),
+        windowOut,
+        windowTiers,
+        windowResumed,
+        windowResumedBackends,
+        directorConfig: directorMoved ? state.directorView : liveConfig,
+    };
+}
+/** The `chain` block: for each tier this poll moved off its primary, the step it runs on and
+ * why the position before it cannot run (plans/fallback-chain.md "Events and surfaces").
+ * `moved` names the tiers the poll moved; a tier the gate pauses (`pair: null`) gets no entry.
+ * The reason is read from the position just before the active step — the previous chain step,
+ * or the tier's primary at step 0 — in the order demoted, step-cap, window/reserve, overage,
+ * cap. */
+export function chainInfo(a) {
+    const out = {};
+    const steps = tierChainSteps(a.config);
+    const midnight = dayAt(-1, new Date(a.now)).getTime();
+    for (const tier of MODEL_TIERS) {
+        const r = a.resolved[tier];
+        if (!a.moved.has(tier) || r.pair === null)
+            continue;
+        const own = steps.filter((s) => s.tier === (r.from ?? tier)).map((s) => s.pair);
+        const idx = r.step ?? 0;
+        const prior = idx > 0 ? own[idx - 1] : null;
+        // The backend whose used-up window this tier's chain reads for the window/reserve reason:
+        // the prior step's own backend when a prior step is subscription, else the primary's.
+        const priorSub = prior ? subscriptionBackendOf(prior, a.accounts) : null;
+        const primarySub = subscriptionBackendOf(withModelOverrides(a.config, tier, {}), a.accounts);
+        const windowBackend = (prior !== null ? priorSub : null) ?? primarySub;
+        const info = { pair: modelPairName(r.pair), step: idx + 1, of: own.length, reason: "cap" };
+        const priorName = prior ? modelPairName(prior) : "";
+        if (prior && a.breakers[priorName] !== undefined && !fallbackServingPair(a.breakers, priorName)) {
+            info.reason = "demoted";
+        }
+        else if (prior?.maxDailyCostUsd !== undefined &&
+            pairDailyCost(a.states, priorName, a.now) >= prior.maxDailyCostUsd) {
+            info.reason = "step-cap";
+            info.returnsAt = midnight;
+        }
+        else if (windowBackend !== null && a.windowOutFor(windowBackend) !== null) {
+            const win = a.windowOutFor(windowBackend);
+            info.reason = win.reserve ? "reserve" : "window";
+            info.returnsAt = win.resetsAt;
+        }
+        else if (prior &&
+            subscriptionBackendOf(prior, a.accounts) !== null &&
+            prior.extraUsage &&
+            a.accounts("claude") &&
+            claudeOverageRefused(a.accounts("claude"))) {
+            info.reason = "overage";
+        }
+        else {
+            info.returnsAt = midnight;
+        }
+        if (r.pair.maxDailyCostUsd !== undefined && a.isPriced(r.pair)) {
+            info.spentUsd = pairDailyCost(a.states, modelPairName(r.pair), a.now);
+            info.capUsd = r.pair.maxDailyCostUsd;
+        }
+        out[tier] = info;
+    }
+    return out;
+}
+/** The distinct non-null fallback pairs a resolution hands out (tier order, first occurrence
+ * first) — the handback match list: a reopen hands back every in-flight run on any of
+ * them (part 5c/8's per-tier handback). */
+function distinctPairs(resolved, chainPairs) {
+    const out = [];
+    // The resolved pairs first, then every other price-free chain step: a run can be on any step.
+    const candidates = [...MODEL_TIERS.map((t) => resolved[t].pair), ...chainPairs];
+    for (const p of candidates) {
+        if (p !== null && !out.some((q) => modelPairName(q) === modelPairName(p)))
+            out.push(p);
+    }
+    return out;
+}

package/dist/src/budget/budget-wiring.js

@@ -0,0 +1,158 @@
+import { MODEL_TIERS } from "../config/config-schema.js";
+import { publishInfoFields } from "../team/orchestrator-info.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { fallbackDemotion } from "./fallback-breaker.js";
+import { gateRoleConfig, runOnPair, subscriptionBackendOf, } from "../gates/budget-gates.js";
+import { configForRole, roleSeamTier, withModelOverrides } from "../config/config-views.js";
+/** Perform the budget gate's wiring for one poll, exactly as `pollTeamGates` did inline:
+ * publish the demotions and the switch/serve info fields, log the one `fallback_switched`
+ * transition event per tier change, assign every runner's config and cap flag, and hand
+ * in-flight fallback runs back on a cap reopen or window reset. */
+export function applyBudgetGateWiring(input) {
+    const { root, runners, liveConfig, info, accounts, budget, view } = input;
+    // Publish what observers cannot derive themselves: every pair's demotion — a per-tier
+    // fallback can demote a pair the legacy single `fallback` never names, and a dashboard that
+    // only sees the engaged pair's verdict would show a tier's roles running while the
+    // scheduler holds them (part 5c/8) — plus the engaged pair's own (the legacy
+    // `fallbackDemoted` field, what `tumwater doctor` and the failure digest read) and the
+    // gate's own spend/cap pair — summed over the runners' live states, which every
+    // persisted-file reader lags by the in-flight runs' charges. Both rewritten only when they
+    // change, like the build status; the exit removes the whole file, so no stale pair survives
+    // a stop.
+    const demotions = {};
+    for (const [name, b] of Object.entries(budget.breakers)) {
+        const d = fallbackDemotion(b);
+        if (d)
+            demotions[name] = d;
+    }
+    const engagedDemotion = budget.engaged !== null ? demotions[budget.engaged] : undefined;
+    const spend = { spentUsd: view.spentUsd, capUsd: view.capUsd };
+    publishInfoFields(root, info, [
+        ["fallbackDemotions", demotions],
+        ["fallbackDemoted", engagedDemotion],
+        ["budget", spend],
+        ["chain", Object.keys(view.chain).length > 0 ? view.chain : undefined],
+    ]);
+    // One fallback_switched per poll in which a tier's pair or step changed (a return to the
+    // primary reads `to: null`, reason "available").
+    const switched = {};
+    const prevChain = budget.prevChain;
+    for (const tier of MODEL_TIERS) {
+        const was = prevChain[tier];
+        const cur = view.chain[tier];
+        if (was?.pair === cur?.pair && was?.step === cur?.step)
+            continue;
+        switched[tier] = {
+            from: was?.pair ?? null,
+            to: cur?.pair ?? null,
+            reason: cur?.reason ?? "available",
+        };
+    }
+    if (Object.keys(switched).length > 0)
+        logEventBestEffort(root, {
+            source: TUMWATER_SOURCE,
+            type: "fallback_switched",
+            tiers: switched,
+        });
+    budget.prevChain = view.chain;
+    // The director keeps the live config — an explicit human prompt outranks the
+    // autonomous-spend cap (gateRoleConfig). Assigned every poll (not only on transitions)
+    // so a runner created mid-gate, or one left behind by a broken-file poll that skipped
+    // the reload, can never run on the wrong model.
+    for (const r of runners) {
+        r.config = gateRoleConfig(r.role, liveConfig, view.roleConfig, view.directorConfig);
+        // An image reroute must never spend past the daily cap: while the gate has the team on
+        // its free fallback pairs, a reroute looks only among those pairs (plans/image-input.md
+        // "Reroute target" "Regime"). Set beside the config assignment so the scheduler's regime
+        // and the roles' never disagree.
+        r.budgetFallbackActive = view.onFallback;
+    }
+    // The budget reopened: a run that started on a fallback pair keeps it until it ends, so hand
+    // those runs back — abort them resumably (session and worktree edits kept) and let their next
+    // run continue the same session on the primary, whose config the assignment above already
+    // installed (PLANS.md 2026-09-30). Per-tier fallbacks put different roles on different pairs
+    // (part 5c/8), so the match runs over EVERY pair the price-based resolution hands out, not only
+    // one. A run started on the primary keeps running, the director is exempt, and the merges (the
+    // slot's own runs) are untouched. One event per pair names who was handed back, so the resulting
+    // aborted runs read as the budget reopening, not as unexplained failures. The subscription
+    // window reset (below the cap): the same hand-back for the pairs the window move used. A window
+    // that resets while the cap still holds hands back nothing.
+    const handBack = view.resumed || (view.windowResumedBackends.length > 0 && !view.budgetActive);
+    // The window handback names the backend whose window resumed (the entry's goal) — not the
+    // handed-back pair's own backend: for claude-only the fallback pair carries no backend (it would
+    // read undefined), and with two subscription backends it would name the opposite one. A pair
+    // belongs to those resumed backends whose tiers' price-resolved pair it is.
+    const resumedBackendSet = new Set(view.windowResumedBackends);
+    const resumedBackendForPair = (leftPair) => {
+        for (const tier of MODEL_TIERS) {
+            const p = view.priceResolved[tier]?.pair;
+            if (p && p.provider === leftPair.provider && p.model === leftPair.model) {
+                const b = subscriptionBackendOf(withModelOverrides(liveConfig, tier, {}), accounts);
+                if (b !== null && resumedBackendSet.has(b))
+                    return b;
+            }
+        }
+        return undefined;
+    };
+    if (handBack && view.pairs.length > 0) {
+        // A cap reopen while the window is still used up leaves the window's tiers on their
+        // fallback pairs: handing those runs back would abort them to restart on the same pair.
+        const stillMoved = Object.keys(view.windowTiers).flatMap((t) => {
+            const p = view.priceResolved[t].pair;
+            return p ? [p] : [];
+        });
+        for (const leftPair of view.pairs) {
+            if (stillMoved.some((p) => p.provider === leftPair.provider && p.model === leftPair.model))
+                continue;
+            const matching = runners.filter((r) => r.role !== DIRECTOR_ROLE && runOnPair(r.runModelPair(), leftPair));
+            if (matching.length > 0) {
+                logEventBestEffort(root, {
+                    source: TUMWATER_SOURCE,
+                    type: "budget_handback",
+                    roles: matching.map((r) => r.role),
+                    provider: leftPair.provider,
+                    model: leftPair.model,
+                    ...(view.resumed
+                        ? {}
+                        : { reason: "window", backend: resumedBackendForPair(leftPair) }),
+                });
+                for (const r of matching)
+                    r.handBackRun();
+            }
+        }
+    }
+}
+/** The per-tier budget pause subject sets (part 5c/8), computed exactly as `pollTeamGates` did
+ * inline: `budgetPausedRoles` holds every role whose model tier resolved to no usable free pair
+ * while the cap is reached, and `windowMovedRoles` the role whose own subscription backend owns
+ * a used-up window's moved tier. The director is exempt (as under every autonomous gate), a role
+ * below the cap is held only when it was window-moved, and the demoted pair's probe pierces the
+ * set for its own tier's roles only — probeRoles in the orchestrator's scheduling pass. */
+export function budgetPausedSubjects(input) {
+    const { runners, liveConfig, accounts, budgetActive, servingResolved, windowTiers } = input;
+    const budgetPausedRoles = new Set();
+    const windowMovedRoles = new Set();
+    const movedTiers = Object.keys(windowTiers);
+    // The backend whose used-up window moved a given tier: the tier's own seam's backend — the same
+    // read budget-gates made to put it in `windowTiers`. A role on a moved tier whose own backend is
+    // DIFFERENT (a healthy backend riding the same tier) keeps its pair: only the role whose own
+    // backend owns the out window is moved.
+    const tierMovedBackend = (tier) => subscriptionBackendOf(withModelOverrides(liveConfig, tier, {}), accounts);
+    for (const r of runners) {
+        if (r.role === DIRECTOR_ROLE)
+            continue;
+        const tier = roleSeamTier(liveConfig, r.role);
+        // A role pinned to the moved tier's own subscription backend keeps it through the window move
+        // (it is not on a pair); a role on the same tier pinning a healthy backend does not.
+        if (movedTiers.includes(tier) &&
+            subscriptionBackendOf(configForRole(liveConfig, r.role), accounts) === tierMovedBackend(tier))
+            windowMovedRoles.add(r.role);
+        // Below the cap only a window-moved role can sit on a demoted fallback.
+        if (!budgetActive && !windowMovedRoles.has(r.role))
+            continue;
+        if (servingResolved[tier].pair === null)
+            budgetPausedRoles.add(r.role);
+    }
+    return { budgetPausedRoles, windowMovedRoles };
+}

package/dist/src/budget/budget.js

@@ -151,7 +151,8 @@ export function modelPairName(p) {
  * `strong` tiers resolved to a usable free pair (resolveTierFallbacks over the full usable
  * predicate — price AND breaker serving) — plus whether the review gate is on. The gate is
  * `paused` when `default` resolves to pause (nothing for the team's bulk to run on), or when
- * review is on and `strong` does (nothing could merge, so every authoring run is wasted work);
+ * review is on and `strong` does (nothing could merge for the roles a pre-merge review gates, so
+ * their authoring runs are wasted work — a `review.afterMerge` role's is not);
  * `fallback` otherwise, with the tiers that did resolve running their pairs and the rest held
  * per role. The single definition of the gate: the orchestrator enforces it and both dashboards
  * display it, so what an operator sees is what the scheduler is doing. */

package/dist/src/build/dep-install.js

@@ -3,8 +3,11 @@ import { resolveFromNodeModules } from "./build-check-detect.js";
 import { readJsonFile } from "../files/json-files.js";
 import { EXEC_MAX_BUFFER } from "../process/process.js";
 import { KILL_GRACE_MS, runScriptGroup } from "../process/process-group.js";
-import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { withLock } from "../concurrency/lock.js";
+import { mergeLockDir } from "../paths.js";
 import { errorMessage } from "../text/text.js";
+import { shortSpanPhrase } from "../text/phrases.js";
 /** Keeping a tree's install in step with its lockfile (BUGS.md 2026-10-01). node_modules is
  * gitignored, so a tumwater worktree has none of its own: its toolchain and every import resolve by
  * walking UP to the root checkout's install (detectBuildCheck, resolveFromNodeModules). That
@@ -116,3 +119,63 @@ export async function syncRootInstall(root, role, install = npmInstall) {
     if (!r.ok)
         warnEventBestEffort(root, role, `the root install did not pick up main's dependencies (${r.packages.join(", ")})${r.detail ? `: ${r.detail}` : ""}; checks install into their own trees until a later merge re-syncs it`);
 }
+/** Re-sync the root checkout's install on demand — the `tumwater doctor --resync-install` verb
+ * (and, in part 2/2, the Health surfaces' button), the always-on `install` alert's advice made a
+ * harness verb. Runs the same `syncInstall` the merge path runs, under the merge lock (the lock
+ * tryMerge holds around its own syncRootInstall, merge-to-main.ts), so a merge and the operator
+ * never run two root installs at once. No drift spawns nothing and logs nothing; a re-sync logs
+ * the same dep_install event syncRootInstall does, under TUMWATER_SOURCE, warning on failure.
+ * Never throws. */
+export async function resyncRootInstall(root, install = npmInstall) {
+    // Nothing is pinned when no readable package-lock.json names a top-level project — that is not
+    // "the tree matches the lockfile" (there is none), so `pinned` tells the two no-drift cases
+    // apart for the renderer.
+    const readPinned = () => !!readJsonFile(path.join(root, "package-lock.json"))
+        ?.packages?.[""];
+    try {
+        return await withLock(mergeLockDir(root), async () => {
+            // Read inside the lock: a concurrent merge can swap package-lock.json between a read before
+            // the lock and syncInstall, and an `attempted`-false run must match the lockfile the sync
+            // would have aligned the tree against.
+            const pinned = readPinned();
+            const r = await syncInstall(root, install);
+            if (!r)
+                return { attempted: false, ok: true, packages: [], durationMs: 0, pinned };
+            logEventBestEffort(root, {
+                source: TUMWATER_SOURCE,
+                type: "dep_install",
+                packages: r.packages,
+                status: r.ok ? "passed" : "failed",
+                durationMs: r.durationMs,
+                ...(r.detail ? { error: r.detail } : {}),
+            });
+            if (!r.ok)
+                warnEventBestEffort(root, TUMWATER_SOURCE, `the manual root install re-sync did not pick up the root lockfile's dependencies (${r.packages.join(", ")})${r.detail ? `: ${r.detail}` : ""}; checks install into their own trees until a later merge re-syncs it`);
+            return {
+                attempted: true,
+                ok: r.ok,
+                packages: r.packages,
+                durationMs: r.durationMs,
+                pinned,
+                ...(r.detail ? { detail: r.detail } : {}),
+            };
+        });
+    }
+    catch (err) {
+        // A withLock timeout/throw must not throw to the CLI: report it as a failed re-sync so the
+        // doctor run still renders its verdict rather than crashing.
+        return { attempted: true, ok: false, packages: [], durationMs: 0, pinned: readPinned(), detail: errorMessage(err) };
+    }
+}
+/** The one renderer the CLI and part 2/2's Health surfaces share for a RootInstallResync — a
+ * no-drift run (attempted false) says nothing to do, a success names the re-synced packages, and
+ * a failure names its detail. */
+export function rootInstallResyncLines(r) {
+    if (!r.attempted)
+        return r.pinned
+            ? ["node_modules already matches package-lock.json — nothing to re-sync"]
+            : ["no package-lock.json to match — nothing to re-sync"];
+    if (r.ok)
+        return [`re-synced the root install (${r.packages.join(", ")}) in ${shortSpanPhrase(r.durationMs)}`];
+    return [`the root install re-sync failed: ${r.detail ?? "unknown error"}`];
+}

package/dist/src/cli/cli-args.js

@@ -125,6 +125,14 @@ export function parseResultFlag(args, missingValueError) {
     const { rest, value } = takeValuedFlag(args, "--result", missingValueError, true);
     return { rest, raw: value };
 }
+/** Parse an optional `--status <state>[,...]` flag for the post-merge review view: the raw value
+ * (null when absent) alongside `rest`, the args with the value token removed so a state name
+ * cannot be read as a positional. Validation of the states belongs to the caller
+ * (cmdReviews); a valueless or empty value fails with `missingValueError`. */
+export function parseStatusFlag(args, missingValueError) {
+    const { rest, value } = takeValuedFlag(args, "--status", missingValueError, true);
+    return { rest, raw: value };
+}
 /** Parse an optional `--model <selector>[,...]` flag for the history trail form: the raw value
  * (null when absent) alongside `rest`, the args with the value token removed so a selector
  * cannot be read as a positional. Validation belongs to the caller (parseHistoryModelList); a
@@ -165,6 +173,44 @@ export function parsePositionFlag(flag, raw, example) {
         fail(`${flag} needs a positive integer${gotSuffix(raw)}`);
     return n;
 }
+/** Scan a queue-style command's edge-triggered flags in one pass: the one valued position
+ * flag `--<flag> <n>` (at most once, parsed through parsePositionFlag with the caller's
+ * `example` spelling), the `--json` boolean (at most once), any extra boolean edge flags in
+ * `extraBooleans` (each at most once), `--help`/`-h` tolerated (dropped), and every other
+ * token collected into `rest` for the caller's rejectUnknownArgs. Returns the parsed position,
+ * the --json flag, the extra booleans' presence (for the --done/--ready variants), and rest.
+ * One home for the scan loop the position-flag command shells used to repeat by hand
+ * (`--cancel`, `--top`, `--release`, `--accept`, `--show`), so the at-most-once wording, the
+ * plain-decimal rule, and the help-tolerance rule cannot drift among them. */
+export function scanPositionArgs(args, flag, example, extraBooleans = []) {
+    let json = false;
+    let position = null;
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--json") {
+            rejectRepeatFlag(json, "--json");
+            json = true;
+            continue;
+        }
+        if (extraBooleans.includes(arg)) {
+            rejectRepeatFlag(flags[arg] === true, arg);
+            flags[arg] = true;
+            continue;
+        }
+        if (arg === flag) {
+            rejectRepeatFlag(position !== null, flag);
+            position = parsePositionFlag(flag, args[i + 1], example);
+            i++;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h")
+            continue;
+        rest.push(arg);
+    }
+    return { json, flags, position, rest };
+}
 /** Resolve a read-only command's `--role <id>` scope: the role id, or null when the flag is
  * absent. The id is validated against built-ins PLUS user-defined roles, read through
  * loadConfigCached (which never throws) so a transiently broken tumwater.json cannot take a
@@ -316,6 +362,23 @@ export function failOverDurationCap(flag, ms, maxMs, hint) {
 export function failRivalShapes(subject, rival, why) {
     fail(`${subject} cannot be combined with ${rival} (${why})`);
 }
+/** Guard a trailing-window command's `--until <window>` against its `--since <window>` pair —
+ * the shared fail sentences the three windowed views (logs, history, report) print, so the
+ * wording cannot drift per command. When `--until` is present but `--since` is not, it fails
+ * `` `${label} --until requires --since` ``; when both are present and the until window reaches
+ * or exceeds the since window, it fails `` `${label} --until (<until>) must be shorter than
+ * --since (<since>)` `` — each named through the same durationLabel the parser reads, so an
+ * operator could retype the window. `sinceMs` is the command's parsed `--since` window (null
+ * when it read the day-shape instead), the single value the until window must stay below.
+ * Returns silently when both checks pass, like failOverDurationCap above. */
+export function failUntilShorterThanSince(label, untilMs, sinceMs) {
+    if (untilMs === null)
+        return;
+    if (sinceMs === null)
+        fail(`${label} --until requires --since`);
+    if (sinceMs !== null && untilMs >= sinceMs)
+        fail(`${label} --until (${durationLabel(untilMs)}) must be shorter than --since (${durationLabel(sinceMs)})`);
+}
 /** Read an optional `--since <duration>` window from a command's args and cap it: the one
  * home of the flagValue → parseDurationFlag → failOverDurationCap idiom the three windowed
  * read-only views (logs, history, report) share. Returns the parsed milliseconds, or null