tumwater 0.1.2 → 0.2.0

package/dist/src/roles/role-view.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 /** One loop's read-only inspection payload — the collector behind `tumwater role <id>`:
  * what the loop IS (catalog entry or custom, enabled, paused, tier), what it RUNS ON
  * (resolved provider/model, the budget fallback pair), what it CARRIES (the instructions
@@ -7,29 +8,59 @@
  * without the CLI and one renderer consumes exactly this shape. Every read degrades like
  * backlogPayload does — a missing tumwater.json is the defaults, a missing state file a
  * fresh state, a missing queue directory an empty inbox — so the command works with the
- * fleet stopped and never throws on a torn repo. */
-import { defaultConfig, enabledRoleIds, isCustomRole, knownRoleIds, loadConfigSafe } from "../config/config.js";
+ * team stopped and never throws on a torn repo. */
+import { defaultConfig, enabledRoleIds, isCustomRole, knownRoleIds, loadConfigSafe, parseJsonConfig } from "../config/config.js";
 import { DIRECTOR_ROLE, customRole, roleById, roleTier, unknownRoleMessage } from "./roles.js";
 import { queuedRolePromptCount } from "../inbox/inbox.js";
-import { pausedRoles } from "../fleet/fleet-state.js";
+import { pausedRoles } from "../team/team-state.js";
 import { loadLoopState } from "../loop/loop-state.js";
+import { baseRoleOf, loopIds, loopPaused } from "./loop-ids.js";
+import { roleCapVerdicts } from "../gates/role-cap-gates.js";
+import { yieldMultiplierFor } from "../scheduling/backoff.js";
+import { quietHoursStatus } from "../scheduling/quiet-hours.js";
 import { assembleTickPrompt } from "../tick/tick-prompt.js";
-import { configForRole, fallbackPair, modelFallbackView, resolvedModelFields, roleSeamTier, } from "../config/config-views.js";
-import { fallbackModelPair, piModelsPath } from "../pi/pi-models.js";
+import { configForRole, resolvedModelFields, reviewRunConfig, roleSeamTier, seamConcurrencyKey } from "../config/config-views.js";
+import { fallbackPair, modelFallbackView } from "../config/config-fallbacks.js";
+import { fallbackModelPair, piModelsPath, seamContextWindow } from "../pi/pi-models.js";
+import { readOpencodeCache } from "../agent/opencode/opencode-catalog.js";
+import { formatModelSelector } from "../config/model-selector.js";
+import { roleImageInfo } from "../agent/image-input.js";
+import { readImageProbeCache } from "../doctor/image-probe.js";
+import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
 import { claudeWindowEntries, readClaudeAccount } from "../agent/claude/claude-account.js";
-import { roleNotesPath } from "../paths.js";
+import { CONFIG_BASENAME, configPath, roleNotesPath } from "../paths.js";
 import { readTextOrNull } from "../files/files.js";
+import { eventRole, eventUsage, readEvents } from "../events/event-read.js";
+import { finiteNumber, objectOrEmpty } from "../files/json-object.js";
+import { canonicalRoleId } from "./legacy-role-ids.js";
+import { orchestratorAlive, readOrchestratorInfo } from "../team/orchestrator-info.js";
+/** The roles.<base>.<field> value the FILE actually holds, or undefined when the file never
+ * set that field. Needed only for the seeded per-role fields: overlayDefaults fills every
+ * built-in role's minRunIntervalSeconds from config.ts's catalog, so the merged config cannot
+ * tell an operator-set override from a seeded default. This reads the same raw file view
+ * unsetConfigKey judges presence against (configPath + CONFIG_BASENAME + objectOrEmpty), so
+ * the override tag and the drawer's clear path agree with what unsetting can actually remove. */
+export function rawRoleField(root, roleId, field) {
+    const { raw } = parseJsonConfig(configPath(root), CONFIG_BASENAME);
+    const rawRoles = objectOrEmpty(raw).roles;
+    const entry = rawRoles && typeof rawRoles === "object" ? rawRoles[roleId] : undefined;
+    const obj = entry && typeof entry === "object" ? entry : undefined;
+    if (!obj)
+        return undefined;
+    return obj[field];
+}
 /** Collect one loop's inspection payload. `modelsPath` overrides pi's model definitions location
  * — a test seam, like status/status-data.ts's snapshot — consulted only when a fallback pair is
  * configured (the freeness verdict needs the definitions; nothing else does). */
-export function rolePayload(root, role, modelsPath = piModelsPath()) {
+export function rolePayload(root, typedRole, modelsPath = piModelsPath(), now = new Date()) {
+    const role = canonicalRoleId(typedRole);
     // loadConfigSafe (not loadConfigCached's hold-last-good machinery — this is a one-shot
     // command, not a poller): a broken or missing file degrades to the defaults, so the
     // command still answers for built-in roles on a torn repo.
     const { config } = loadConfigSafe(root);
     const cfg = config ?? defaultConfig();
     const catalog = roleById(role);
-    const customEntry = cfg.customLoops.find((c) => c.name === role);
+    const customEntry = cfg.customRoles.find((c) => c.name === role);
     // The director is inspectable like any loop but has no catalog entry: a pseudo-Role whose
     // find text is empty (rolePayload nulls it below — the director's queued prompts ARE its
     // work), so the unknown-role throw only fires for ids nothing can answer.
@@ -44,20 +75,132 @@ export function rolePayload(root, role, modelsPath = piModelsPath()) {
         throw new Error(unknownRoleMessage(role, knownRoleIds(cfg)));
     }
     const effective = configForRole(cfg, role);
-    // The claude billing answer, read only for a claude seam (the account file is claude's):
-    // its subscription window's primary type rides along for the renderer's label.
-    const account = effective.agent === "claude" ? readClaudeAccount(root) : null;
+    // The claude billing answer, read when a claude seam is in play — the role's OWN seam, or
+    // the review gate's when the reviewer runs claude (PLANS.md "Mixed claude + pi fleets, part
+    // 3/4" gap 7): a pi author on a claude reviewer still shows where its changes' spend lands.
+    // Its subscription window's primary type rides along for the renderer's label. The account
+    // file is team-global, so either seam reads the same answer.
+    const claudeInPlay = effective.agent === "claude" || (cfg.review.enabled && reviewRunConfig(cfg).agent === "claude");
+    const account = claudeInPlay ? readClaudeAccount(root) : null;
+    const info = readOrchestratorInfo(root);
+    const chainStep = (orchestratorAlive(root, info) && info?.chain?.[roleSeamTier(cfg, role)]) || null;
     const billingWindow = account?.billing === "subscription" ? claudeWindowEntries(account)[0]?.type : undefined;
+    // pi's own saved default for a pi seam that resolves no model, read once beside the models
+    // catalog this collector already takes as a seam (piSettingsPath). The config's `thinking`
+    // wins over the default's because tumwater passes it to pi as `--thinking`, mirroring the
+    // snapshot's modelFromPi rule. Any other seam stays unchanged and carries no `piDefault`.
+    const runsPiWithoutAModel = (effective.agent === undefined || effective.agent === "pi") &&
+        effective.provider === undefined &&
+        effective.model === undefined;
+    const piDefault = runsPiWithoutAModel ? readPiDefaultModel(piSettingsPath(modelsPath), root) : null;
+    // The role's provider key and its cap (plans/provider-concurrency.md §8): the same pure
+    // key the orchestrator's admission resolves for this role, answered from the same
+    // piDefault seam the orchestrator carries, so `tumwater role <id>` names the exact key
+    // whose cap bounds the role. The cap is the map's entry for that key, absent when no
+    // `maxConcurrentPerProvider` map is set or the key has no entry (then the role is bounded
+    // only by the team total, and the cap is omitted).
+    const providerKey = seamConcurrencyKey(effective, piDefault);
+    const providerCap = providerKey !== undefined ? cfg.maxConcurrentPerProvider?.[providerKey] : undefined;
     // The fallback story the operator sees: the declared pair, but the price-resolved pair when
     // one exists (a map with no `default` entry borrows another tier's free pair) and the
     // freeness verdict from the same read. `fallbackFree` false keeps the declared pair visible
     // so a refused fallback is still named.
     const declaredFallback = fallbackPair(cfg);
-    const freeFallback = declaredFallback ? fallbackModelPair(cfg, modelsPath, readClaudeAccount(root)) : null;
+    // The opencode catalog answer (part 6b/7), read the way the budget gate reads it — always,
+    // from the same team-global cache the startup gate seeds — so the fallback free-ness verdict
+    // prices opencode pairs against the same snapshot as the gate. A conditional read cannot
+    // decide up front which pair the verdict will price: `fallbackModelPair` may resolve to a
+    // free pair BORROWED from another tier (a map whose `default` entry is priced borrows a
+    // free pair elsewhere), which routes to opencode even when the role's own seam, the declared
+    // default pair, and the review gate are not opencode. A null catalog would read that borrowed
+    // opencode pair NOT free, so this view and the gate would disagree; reading always (as the
+    // gate does) keeps them on one answer. OpenCode's `catalog` is threaded the way claude's
+    // `account` is: absent, an opencode pair reads NOT free.
+    const opencodeCatalog = readOpencodeCache(root);
+    const freeFallback = declaredFallback ? fallbackModelPair(cfg, modelsPath, readClaudeAccount(root), opencodeCatalog) : null;
     const fallback = freeFallback ?? declaredFallback;
     // One state read serves both the model-fallback episode and the next-tick preview below.
     const state = loadLoopState(root, role);
     const episode = state.modelFallback;
+    // The loop's recent tick outcomes, read from the event log (readEvents) so the command
+    // answers with the team stopped and never touches live state. readEvents returns the log's
+    // newest events in file (chronological) order, so filtering to this role's run_end events
+    // and taking the last 8 yields the newest 8, reversed to newest-first. Durations and
+    // summaries ride along only when the event carried them (a torn or empty line drops them),
+    // and an empty result is omitted so a never-ticked loop carries no `recentOutcomes` at all.
+    // One event-log read serves both per-loop facts — the recent outcomes and the spend sum — so
+    // the two cannot drift on what they cover: filtered to this role's run_end events once, then
+    // the outcome projection keeps the newest valid 8 while the usage fold sums the whole window.
+    const events = readEvents(root);
+    const tickEnds = events.filter((ev) => ev.type === "run_end" && eventRole(ev) === role);
+    // The event log is read without a shape filter, so a torn or hand-edited run_end line can
+    // carry a non-numeric ts/durationMs or an empty result — the same foreign shape every other
+    // consumer guards with finiteNumber. A line with no usable ts or result is as unusable as
+    // an absent one (the same "a torn line carries no usable timestamp" rule eventTick/tickStartMap
+    // apply), so it contributes no outcome; a non-numeric durationMs is dropped like a missing one.
+    const recentOutcomes = tickEnds
+        .filter((ev) => {
+        return finiteNumber(ev.ts, null) !== null && typeof ev.result === "string" && ev.result !== "";
+    })
+        .slice(-8)
+        .map((ev) => ({
+        ts: ev.ts,
+        result: ev.result,
+        ...(finiteNumber(ev.durationMs, null) !== null ? { durationMs: ev.durationMs } : {}),
+        ...(typeof ev.summary === "string" && ev.summary !== "" ? { summary: ev.summary } : {}),
+    }))
+        .reverse();
+    // The loop's own spend over the same retained window, summed per-run_end through the shared
+    // eventUsage guard (a torn or hand-edited run_end line contributes nothing: a non-numeric
+    // field reads as 0, and a line without a usable ts is as unusable as an absent one, matching
+    // recentOutcomes's drop rule so a torn tick never silently spends). Omitted when all three
+    // sums are 0, keeping a never-costly loop's JSON unchanged (the report's zero-means-absent
+    // convention).
+    const usage = tickEnds.reduce((acc, ev) => {
+        if (finiteNumber(ev.ts, null) === null)
+            return acc;
+        const u = eventUsage(ev);
+        acc.tokens += u.tokens;
+        acc.costUsd += u.costUsd;
+        acc.notionalCostUsd += u.notionalCostUsd;
+        return acc;
+    }, { tokens: 0, costUsd: 0, notionalCostUsd: 0 });
+    // The per-role daily cap, answered by the verdict the scheduler's gate shares (roleCapVerdicts)
+    // over the base role's instances, so the page cannot disagree with the hold. A cap of 0
+    // disables (roleCapPaused's rule) and the director is exempt, so neither carries the field.
+    const base = baseRoleOf(role);
+    // The roles.<base>.minRunIntervalSeconds override, resolved through the base role like the
+    // cap, quiet hours and instructions — an instance id shows (and can edit) the override its
+    // runs carry. Presence is judged against the FILE (rawRoleField), not the merged cfg:
+    // overlayDefaults seeds every built-in role's minRunIntervalSeconds from config.ts's catalog,
+    // so the merged value would make steward/qa/... always look overridden and the drawer's
+    // clear a no-op. undefined when unset, so the spread below drops it (the payload stays
+    // byte-identical when there is no override).
+    const rawInterval = rawRoleField(root, base, "minRunIntervalSeconds");
+    const minRunIntervalOverride = typeof rawInterval === "number" ? rawInterval : undefined;
+    // The raw provider/model/thinking the FILE holds (roles.<base>), distinct from the resolved
+    // provider/model/thinking fields configForRole merges with the top level — the drawer's
+    // Model overrides editor prefills from these, empty when unset. Presence is judged against
+    // the FILE (rawRoleField) like minRunIntervalOverride, so a config that relies on the top
+    // level or a tier name carries no override. Each is spread only when a string, so a file
+    // with no overrides yields a payload byte-identical to today's.
+    const providerOverrideRaw = rawRoleField(root, base, "provider");
+    const modelOverrideRaw = rawRoleField(root, base, "model");
+    const thinkingOverrideRaw = rawRoleField(root, base, "thinking");
+    const providerOverride = typeof providerOverrideRaw === "string" ? providerOverrideRaw : undefined;
+    const modelOverride = typeof modelOverrideRaw === "string" ? modelOverrideRaw : undefined;
+    const thinkingOverride = typeof thinkingOverrideRaw === "string" ? thinkingOverrideRaw : undefined;
+    const capUsd = cfg.maxDailyCostUsdPerRole?.[base];
+    let dailyCap;
+    if (role !== DIRECTOR_ROLE && typeof capUsd === "number" && Number.isFinite(capUsd) && capUsd > 0) {
+        const ids = loopIds(cfg).filter((id) => baseRoleOf(id) === base);
+        if (!ids.includes(role))
+            ids.push(role);
+        const runners = ids.map((id) => ({ role: id, state: id === role ? state : loadLoopState(root, id) }));
+        const verdict = roleCapVerdicts(runners, cfg.maxDailyCostUsdPerRole, now.getTime()).get(base);
+        if (verdict)
+            dailyCap = { capUsd, spentUsd: verdict.spentUsd, over: verdict.over, roleIds: verdict.roleIds };
+    }
     // The role's notebook, read for display. The same degradation as every other read here: a
     // missing, empty, or unreadable file is simply "no note yet". The director has none.
     let note = null;
@@ -65,26 +208,68 @@ export function rolePayload(root, role, modelsPath = piModelsPath()) {
         const text = readTextOrNull(roleNotesPath(root, role));
         note = text !== null && text.trim() !== "" ? text : null;
     }
+    // The windows the scheduler applies (gates/gate-polls.ts), through the same parser and
+    // predicate; the director is exempt from both gates.
+    const quietHours = [];
+    if (role !== DIRECTOR_ROLE) {
+        const own = quietHoursStatus(cfg.quietHoursPerRole?.[baseRoleOf(role)], now);
+        if (own.window !== null)
+            quietHours.push({ scope: "role", window: own.window, inWindow: own.inWindow });
+        const team = quietHoursStatus(cfg.quietHours, now);
+        if (team.window !== null)
+            quietHours.push({ scope: "fleet", window: team.window, inWindow: team.inWindow }); // vocabulary-ok: persisted --json scope value
+    }
+    // The resolved primary seam's declared context window. A run currently on the model
+    // fallback may use a different window, which is the fallback's own documented state.
+    const contextWindow = seamContextWindow(configForRole(cfg, role), root, modelsPath);
     return {
         id: role,
         title: resolved.title,
         custom: isCustomRole(cfg, role),
         enabled: enabledRoleIds(cfg).includes(role),
-        paused: pausedRoles(root).includes(role),
+        paused: loopPaused(new Set(pausedRoles(root)), role),
         tier: roleTier(role),
         modelTier: roleSeamTier(cfg, role),
         ...resolvedModelFields(effective.provider, effective.model, effective.thinking),
-        agent: effective.agent ?? "pi",
+        ...(piDefault
+            ? {
+                piDefault: formatModelSelector({
+                    ...piDefault,
+                    thinking: effective.thinking ?? piDefault.thinking,
+                }),
+            }
+            : {}),
+        backend: effective.agent ?? "pi",
+        ...(providerKey !== undefined ? { providerKey } : {}),
+        ...(providerCap !== undefined ? { providerCap } : {}),
         fallback,
         fallbackFree: freeFallback !== null,
         modelFallback: modelFallbackView(episode, cfg, role),
         ...(account !== null ? { billing: account.billing } : {}),
         ...(billingWindow !== undefined ? { billingWindow } : {}),
-        minTickIntervalSeconds: effective.minTickIntervalSeconds,
-        instructions: cfg.roles[role]?.instructions ?? null,
+        chainStep,
+        ...roleImageInfo(cfg, role, modelsPath, readImageProbeCache(root)),
+        minRunIntervalSeconds: effective.minRunIntervalSeconds,
+        ...(minRunIntervalOverride !== undefined ? { minRunIntervalOverride } : {}),
+        ...(providerOverride !== undefined ? { providerOverride } : {}),
+        ...(modelOverride !== undefined ? { modelOverride } : {}),
+        ...(thinkingOverride !== undefined ? { thinkingOverride } : {}),
+        // The configured parallel-runner count (roles.<base>.instances), present only when the
+        // config sets it — unlike minRunIntervalSeconds no catalog seed fills built-ins' counts,
+        // so the merged cfg tells presence exactly. Resolved through the base role like the
+        // instructions and min-run-interval override.
+        ...(cfg.roles[base]?.instances !== undefined ? { instances: cfg.roles[base].instances } : {}),
+        // The roles.<base>.instructions override verbatim — resolved through the base role like
+        // the cap and quiet hours, so an instance id shows (and can edit) the override its runs
+        // carry (tick-prompt reads config.roles[base]); null when unset.
+        instructions: cfg.roles[baseRoleOf(role)]?.instructions ?? null,
         find: role === DIRECTOR_ROLE ? null : resolved.find,
-        note,
+        notes: note,
         inboxCount: queuedRolePromptCount(root, role),
+        // The resolved primary seam's declared context window in tokens, or null when it cannot
+        // be known (a non-pi seam, an unresolvable provider/model pair, or a model with no
+        // declared window) — the same seam `- Next run:` previews. Independent of the fallback.
+        contextWindow,
         // The preview seam: the queued prompt (if any) is read, not consumed, so an inspection
         // never costs the loop its queued work — the property the tick-prompt test pins.
         nextPrompt: assembleTickPrompt({
@@ -93,6 +278,20 @@ export function rolePayload(root, role, modelsPath = piModelsPath()) {
             role,
             state,
             preview: true,
+            // The compact prompt every run gets (loop-tick.ts), so the preview is the real prompt.
+            compact: true,
         })?.prompt ?? null,
+        // The loop's schedule — surfaced read-only from the same persisted state rolePayload
+        // already loaded for the model-fallback episode and the next-tick preview, so no new
+        // read path exists and the collector stays one loadLoopState per role. `lastRunEndedAt`
+        // is omitted (JSON unchanged) until the loop has actually ticked.
+        nextRunAt: state.nextRunAt,
+        backoffSeconds: state.backoffSeconds,
+        yieldMultiplier: yieldMultiplierFor(state),
+        ...(state.lastRunEndedAt !== undefined ? { lastRunEndedAt: state.lastRunEndedAt } : {}),
+        ...(quietHours.length > 0 ? { quietHours } : {}),
+        ...(recentOutcomes.length > 0 ? { recentOutcomes } : {}),
+        ...(usage.tokens !== 0 || usage.costUsd !== 0 || usage.notionalCostUsd !== 0 ? { usage } : {}),
+        ...(dailyCap ? { dailyCap } : {}),
     };
 }

package/dist/src/roles/roles.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 /** The role registries and classification helpers over the built-in role catalog. The catalog
  * itself — each loop's identity and its "find something to do" prompt text — lives in
  * role-catalog.ts (split out 2026-10-01, organize); this module re-exports ROLES and Role so
@@ -10,24 +11,25 @@ import { typoSuffix } from "../text/suggest.js";
 export { ROLES };
 /** The director loop's id — a target that is not in ROLES (allRoleIds appends it) and is
  * driven by operator prompts, not a find prompt: an un-targeted `tumwater prompt` queues
- * there. It keeps running through a fleet-wide `pause` (which stops only the role loops);
+ * there. It keeps running through a team-wide `pause` (which stops only the role loops);
  * an un-targeted `stop` signals the whole orchestrator, director included. */
 export const DIRECTOR_ROLE = "director";
 /** The bugfix loop's id. It is the one work role that also defers like a maintenance role while its
- * backlog (BUGS.md `## Open`) is empty — see deferTick in src/scheduling/scheduling.ts. */
+ * backlog (BUGS.md `## Open`) is empty — see deferTick in src/scheduling/scheduling.ts. With open
+ * bugs it never defers, but pollRunnerReasons stands it down while all of them are held. */
 export const BUGFIX_ROLE = "bugfix";
 /** Work-tier roles (need-based prioritization): they
- * ship work — feature and bugfix land code on main, plan feeds them — so their due ticks are
+ * ship work — feature and bugfix merge code on main, plan feeds them — so their due ticks are
  * never deferred and slot allocation always orders them ahead of maintenance. */
 const WORK_ROLES = new Set(["feature", "bugfix", "plan"]);
 /** Observer roles (plans/observer-roles.md 1/2): a role whose product is an observation, not a
  * commit, and for which `no_change` means "checked, all well" rather than "found nothing to do".
  * The idle ladder's premise — a loop that keeps finding nothing stops burning model time — does
- * not hold for these, so their no_change tick schedules at `minTickIntervalSeconds` and leaves
+ * not hold for these, so their no_change tick schedules at `minRunIntervalSeconds` and leaves
  * `backoffSeconds` at 0 (src/scheduling/backoff.ts). The error ladder still applies in full, and
  * they are removed from DEFERRABLE_ROLES because their input (the running product for `qa`, the
- * event log for `telemetry`) is not a function of whether main moved. */
-export const OBSERVER_ROLES = new Set(["qa", "telemetry"]);
+ * event log for `selfcheck`) is not a function of whether main moved. */
+export const OBSERVER_ROLES = new Set(["qa", "selfcheck"]);
 /** The built-in maintenance roles that author code on their own cadence — the eight members
  * DEFERRABLE_ROLES and BASELINE_BLOCKED_ROLES share. Both sets list them because both charter
  * the same roles (defer-until-needed scheduling, red-main blocking), so the list lives once
@@ -36,15 +38,16 @@ const CODE_MAINTENANCE_ROLES = [
     "organize",
     "coverage",
     "clean",
-    "dry",
+    "dedupe",
     "perf",
     "security",
     "robustness",
     "improve",
 ];
 /** Maintenance-tier roles (need-based prioritization): exactly the ten built-ins whose due
- * ticks are deferrable while no feature/bugfix/director/human commit has landed on main since
- * their last tick and that tick did nothing. Unknown/custom roles are deliberately NOT in this
+ * ticks are deferrable while no feature, bugfix, director, operator or human commit has merged
+ * into main since their last tick and that tick did nothing. Unknown/custom roles are
+ * deliberately NOT in this
  * set — the harness cannot judge what an arbitrary custom role needs, so they never defer (they
  * still sort into tier 1 for fairOrder via roleTier). Observers are excluded: an unmoved tree
  * says nothing about whether the product or the event log has something new to report. */
@@ -78,8 +81,8 @@ export function roleTier(role) {
  * by the gate's pre-check, so spending an authoring run on it is pure waste. Exempt: director
  * (human prompts outrank autonomous gates, like the budget gate), bugfix (the designated healer
  * — its tick runs the suite per "leave the project working" and can fix a red main through the
- * existing pre-merge gate; blocking it would leave only humans able to unblock the fleet), and
- * plan/readme/steward/qa/telemetry (markdown-only charter — their diffs are exempt from the build
+ * existing pre-merge gate; blocking it would leave only humans able to unblock the team), and
+ * plan/readme/steward/qa/selfcheck (markdown-only charter — their diffs are exempt from the build
  * pre-check via review.exemptPaths, so a red main does not block them). */
 export const BASELINE_BLOCKED_ROLES = new Set([
     "feature",
@@ -90,8 +93,8 @@ export const BASELINE_BLOCKED_ROLES = new Set([
 export function baselineBlocked(role) {
     return BASELINE_BLOCKED_ROLES.has(baseRoleOf(role));
 }
-/** Work ratio 4/4: which commit tier a loop's base role lands into, for the work vs maintenance
- * split the report and the "Landed today" tile show and the maintenance allowance (Work ratio
+/** Work ratio 4/4: which commit tier a loop's base role merges into, for the work vs maintenance
+ * split the report and the "Merged today" tile show and the maintenance allowance (Work ratio
  * 1a/4, src/gates/maintenance-quota.ts) counts. The one home of the split. `work` is the
  * shipping tier (feature, bugfix, director); `maintenance` is code upkeep plus readme. Every
  * other role (plan, steward, observers, custom) is neither and counts only toward the total
@@ -129,7 +132,7 @@ export function unknownRoleMessage(role, validIds) {
  * role-specific find-something-to-do text, and the title is what identifies the loop inside
  * its own prompt (`You are the "<name>" loop (user-defined loop)`) and commit context.
  * Custom loops run the `default` tier — the harness cannot judge what an arbitrary loop's
- * work needs, so it gets the fleet's ordinary model. */
+ * work needs, so it gets the team's ordinary model. */
 export function customRole(name, task) {
-    return { id: name, title: "user-defined loop", find: task, tier: "default" };
+    return { id: name, title: "custom role", find: task, tier: "default" };
 }

package/dist/src/scheduling/backoff.js

@@ -11,12 +11,12 @@ import { yieldScaledRole } from "../roles/roles.js";
  * unit-tested without touching a disk. */
 /** Clear a loop's backoff so its next orchestrator poll finds it immediately due: zero
  * backoffSeconds (so the next no_change/error tick restarts the backoff ladder from the
- * bottom instead of climbing from wherever the fleet parked) and pull nextRunAt forward to
+ * bottom instead of climbing from wherever the team parked) and pull nextRunAt forward to
  * now. Pure: returns a new state and preserves everything else — counters (an
  * observation-window reset is zeroCounters' job), wake tracking (lastMainHead), and the
  * last-result fields. Scheduling operation, not observation-window reset: it exists so an
  * operator who fixed what the loops were failing on can say "try again" (BUGS.md
- * 2026-09-15: the fleet had no wake lever). Also stamps wokenAt, which is what lets
+ * 2026-09-15: the team had no wake lever). Also stamps wokenAt, which is what lets
  * isEligible honor the demand over the role's min-tick interval (LoopState.wokenAt). */
 export function clearBackoff(s, now) {
     // wokenAt marks the wake as newer than the current gap window's opening tick, which is
@@ -27,7 +27,7 @@ export function clearBackoff(s, now) {
 }
 /** Re-apply a wake that was consumed while the just-ended tick was still in flight. The tick
  * holds the same state object wake() mutated in place, but applyTickOutcome's own schedule
- * overwrites the wake: lastTickEndedAt is re-stamped past wokenAt (so the min-gap exemption
+ * overwrites the wake: lastRunEndedAt is re-stamped past wokenAt (so the min-gap exemption
  * reads stale) and nextRunAt is scheduled a fresh gap or backoff out — the operator's "try
  * again now" silently waits out the whole interval. Called by the tick's end-save after
  * applyTickOutcome (src/tick/tick-apply.ts), it re-applies the demand exactly like a wake
@@ -40,22 +40,22 @@ export function clearBackoff(s, now) {
 export function restoreMidTickWake(s) {
     if (s.resumePending)
         return false;
-    if (s.wokenAt === undefined || s.wokenAt <= (s.lastTickStartedAt ?? 0))
+    if (s.wokenAt === undefined || s.wokenAt <= (s.lastRunStartedAt ?? 0))
         return false;
     // clearBackoff stamps wokenAt = now, which must read NEWER than the end-save's
-    // lastTickEndedAt for isEligible's exemption to fire — both are Date.now() reads, so a
+    // lastRunEndedAt for isEligible's exemption to fire — both are Date.now() reads, so a
     // same-millisecond tie would swallow the demand; floor it just past the end stamp.
-    Object.assign(s, clearBackoff(s, Math.max(Date.now(), (s.lastTickEndedAt ?? 0) + 1)));
+    Object.assign(s, clearBackoff(s, Math.max(Date.now(), (s.lastRunEndedAt ?? 0) + 1)));
     return true;
 }
 /** Yield-scaled clocks: how long a role's own recent
  * results stretch its min-tick gap. The ring (LoopState.recentOutcomes) holds one char per
- * COUNTED tick — a landing (`changed`/`queued`) is `L`, every other counted result is `n`;
+ * COUNTED tick — a merge (`changed`/`queued`) is `L`, every other counted result is `n`;
  * the error class (`error`/`aborted`/`quiet_killed`) is no yield evidence either way and is
  * not recorded at all, so a run of backend failures neither stretches a role's clock nor
  * resets it. */
 export const YIELD_RING = 20;
-const YIELD_LAND = "L";
+const YIELD_MERGE = "L";
 /** Results that never enter the ring. */
 const UNCOUNTED_RESULTS = new Set(["error", "aborted", "quiet_killed"]);
 /** Record one finished tick's result on the state's yield ring, oldest entries falling off
@@ -64,21 +64,21 @@ const UNCOUNTED_RESULTS = new Set(["error", "aborted", "quiet_killed"]);
 export function pushYieldOutcome(s, result) {
     if (UNCOUNTED_RESULTS.has(result))
         return;
-    const ch = result === "changed" || result === "queued" ? YIELD_LAND : "n";
+    const ch = result === "changed" || result === "queued" ? YIELD_MERGE : "n";
     s.recentOutcomes = ((s.recentOutcomes ?? "") + ch).slice(-YIELD_RING);
 }
 const YIELD_MAX = 8;
-/** The multiplier on a scalable role's minTickIntervalSeconds gap its recent yield earns:
- * 1 while any of the last 10 counted ticks landed, otherwise doubling per 5 further empty
+/** The multiplier on a scalable role's minRunIntervalSeconds gap its recent yield earns:
+ * 1 while any of the last 10 counted ticks merged, otherwise doubling per 5 further empty
  * ticks — 10 empties ×2, 15 ×4, 20 ×8 — capped at 8. `recent` is the ring's chars, oldest
  * first, as pushYieldOutcome recorded them. Pure; unit-tested beside the other ladder math.
- * A landing inside the last 10 resets the multiplier to 1 even when older empties remain in
- * the ring: one landing is the evidence the role's clock should trust, and the ring's older
- * half only matters once the landing has aged out of the recent window. */
+ * A merge inside the last 10 resets the multiplier to 1 even when older empties remain in
+ * the ring: one merge is the evidence the role's clock should trust, and the ring's older
+ * half only matters once the merge has aged out of the recent window. */
 export function yieldMultiplier(recent) {
-    if (recent.slice(-10).includes(YIELD_LAND))
+    if (recent.slice(-10).includes(YIELD_MERGE))
         return 1;
-    const empty = recent.filter((c) => c !== YIELD_LAND).length;
+    const empty = recent.filter((c) => c !== YIELD_MERGE).length;
     if (empty < 10)
         return 1;
     return Math.min(YIELD_MAX, 2 ** (Math.floor((empty - 10) / 5) + 1));
@@ -92,6 +92,16 @@ export function yieldMultiplier(recent) {
 export function yieldMultiplierFor(s) {
     return yieldScaledRole(s.role) ? yieldMultiplier((s.recentOutcomes ?? "").split("")) : 1;
 }
+/** The `×N` yield-multiplier suffix a next-run display rides: `×4` when the multiplier is
+ * above 1, else `""` — the quiet scalable loop's stretched effective gap made visible (the
+ * multiplier gates the scheduled gap in isEligible, so a `now`-due cell at ×4 is a role
+ * waiting out its gap, not a broken clock). Shared by the status table's `next run` cell
+ * (status-render.ts's nextRunCell) and the role view's Schedule line (role-render.ts) so the
+ * two node surfaces cannot drift on how an above-1 multiplier is worded; the GUI renders the
+ * same rule from its own separate-runtime copy (gui-client.ts's fmtNextRun). */
+export function yieldMultiplierSuffix(mult) {
+    return mult > 1 ? ` ×${mult}` : "";
+}
 /** Next step of a backoff ladder: initial (capped) on the first step, then multiplied, capped. */
 export function nextBackoffSeconds(current, ladder) {
     const { initialSeconds, factor, maxSeconds } = ladder;
@@ -108,16 +118,16 @@ export function scheduleBackoff(s, ladder) {
     s.nextRunAt = Date.now() + s.backoffSeconds * 1000;
 }
 /** Schedule the loop's next tick at its minimum interval — the role-resolved config's
- * minTickIntervalSeconds (a per-role slow clock), converted seconds→ms here so every outcome
+ * minRunIntervalSeconds (a per-role slow clock), converted seconds→ms here so every outcome
  * arm that shares this cadence cannot drift apart. The productive-side counterpart of
  * scheduleBackoff: together the two own the whole "when does this loop run again" decision. */
 export function scheduleAtMinInterval(s, cfg) {
-    s.nextRunAt = Date.now() + cfg.minTickIntervalSeconds * 1000;
+    s.nextRunAt = Date.now() + cfg.minRunIntervalSeconds * 1000;
 }
 /** Backoff ladder for failed ticks (`error` results). The idle ladder prices hour-long model
  * runs — its cap exists so a loop that keeps finding nothing stops burning model time. A tick
  * that fails (a broken toolchain, a dead pi subprocess) often never reaches the model, so it
- * climbs this short ladder, capped in minutes: one broken `git` must not park a fleet for the
+ * climbs this short ladder, capped in minutes: one broken `git` must not park a team for the
  * idle ladder's 10-hour sleep (BUGS.md, the 2026-09-15 outage). One ladder, one sensible
  * default, no knob: the cap is the point. */
 export const ERROR_BACKOFF = { initialSeconds: 30, factor: 2, maxSeconds: 600 };

package/dist/src/scheduling/claims.js

@@ -1,13 +1,14 @@
+// vocabulary: plain
 /** Work-instance claims (plans/parallel-work-instances.md "Claims", part 4/7): which backlog
  * entry each runner of a multi-instance base role may take, whether it must drop the entry, and
  * which entry a staged diff moved. The pure policies live here — assignment is the first free
  * entry in file order, release is `left` / `ineligible` / `disabled` / `stale` — so
  * orchestrator-scheduling.ts and tick-stage.ts share one definition and the rules are unit
- * tested without a fleet. The claim itself is persisted on LoopState, so it survives a crash,
+ * tested without a team. The claim itself is persisted on LoopState, so it survives a crash,
  * resume, revision and leftover recovery. */
 import path from "node:path";
 import { hasOutstandingWork } from "../loop/loop-state.js";
-import { eligibleEntries, entryKey } from "../backlog/backlog-eligibility.js";
+import { backlogHolds, eligibleEntries, entryKey } from "../backlog/backlog-eligibility.js";
 import { actionableEntryRanges, actionableEntryRangesFor } from "../backlog/backlog-structure.js";
 import { readTextOrNull } from "../files/files.js";
 import { changeBaseRev, fileContentAt } from "../git/git.js";
@@ -24,6 +25,15 @@ export const CLAIM_IDLE_MAX_MS = 24 * 60 * 60 * 1000;
 export function planBacklogTarget(config) {
     return configuredInstances(config, "feature") + 1;
 }
+/** Does PLANS.md already hold the plan loop's target (planBacklogTarget eligible plans), with no
+ * plan marked needs-review or needs-replan? The charter makes splitting or replanning a marked
+ * plan outrank the stop, so a marked entry keeps the plan loop running; otherwise a plan tick can
+ * only end in TUMWATER_NOTHING_TO_DO and the scheduler defers it (deferTickReason). */
+export function planBacklogFull(root, config) {
+    if (eligibleEntries(root, "feature").length < planBacklogTarget(config))
+        return false;
+    return !backlogHolds(root).plans.some((h) => h === "needs-review" || h === "needs-replan");
+}
 /** The backlog file and section a role's entries live under: PLANS.md's `## Planned` for
  * feature, BUGS.md's `## Open` for bugfix. An instance id resolves through its base role. */
 function roleSection(role) {
@@ -59,15 +69,15 @@ export function assignNext(free) {
     return free[0] ?? null;
 }
 /** Why a runner must drop its claim, or null when it keeps it. A runner is idle when it is not
- * running, has no queued landing, no outstanding revision and no pending resume; `disabled`
- * and `stale` only release an idle runner, while a claim whose entry left or turned ineligible
- * is released outright (there is nothing left to do). */
+ * running, has no queued merge, no outstanding revision and no pending resume; `disabled`,
+ * `paused` and `stale` only release an idle runner, while a claim whose entry left or turned
+ * ineligible is released outright (there is nothing left to do). */
 export function claimReleaseReason(runner, ctx) {
     const claim = runner.state.claim;
     if (!claim)
         return null;
     const idle = !runner.state.running &&
-        !ctx.hasQueuedLanding &&
+        !ctx.hasQueuedMerge &&
         !hasOutstandingWork(runner.state);
     if (!ctx.listedKeys.has(claim.key))
         return "left";
@@ -75,12 +85,14 @@ export function claimReleaseReason(runner, ctx) {
         return "ineligible";
     if (!ctx.enabled && idle)
         return "disabled";
+    if (ctx.paused && idle)
+        return "paused";
     if (idle && ctx.now - claim.at > CLAIM_IDLE_MAX_MS)
         return "stale";
     return null;
 }
 /** The entries `headMd` moved out of `section` that `baseMd` still listed, in base file order.
- * A moved entry's key matches whether it landed into `## Done`/`## Fixed` or was renamed; a key
+ * A moved entry's key matches whether it merged into `## Done`/`## Fixed` or was renamed; a key
  * absent from the head section means it is no longer actionable there. */
 export function movedOutEntries(baseMd, headMd, section) {
     const headKeys = new Set(actionableEntryRanges(headMd, section).map((e) => entryKey(e.title)));
@@ -102,7 +114,7 @@ export async function stagedMovedEntries(wt, mainBranch, role) {
 /** How many permits to withhold from tier ≥ 1 acquirers this poll so a work loop that has work
  * to take can claim one without waiting out a maintenance tick (plans/parallel-work-instances.md
  * "Priority headroom", part 7/7). Only the claim-taking roles (feature, bugfix) count: an idle
- * one — not running, with no queued landing — counts when it either holds an eligible claim or
+ * one — not running, with no queued merge — counts when it either holds an eligible claim or
  * its base role still has an unclaimed eligible entry. Returns min(floor(maxConcurrent / 3),
  * the count), so an entirely busy work tier reserves nothing. */
 export function workReserveCount(root, runners, opts) {
@@ -137,7 +149,11 @@ export function workReserveCount(root, runners, opts) {
             continue;
         if (!opts.enabled.has(r.role))
             continue;
-        if (r.state.running || opts.queuedLandingRoles.has(r.role))
+        if (r.state.running || opts.queuedMergeRoles.has(r.role))
+            continue;
+        // A work loop whose provider is full (capped and at its cap) cannot use a reserved permit
+        // anyway, so it must not withhold one from another provider's maintenance tick (§6).
+        if (opts.providerHasHeadroom !== undefined && !opts.providerHasHeadroom(r))
             continue;
         const eligible = eligibleFor(base);
         const holdsClaim = r.state.claim !== undefined && eligible.has(r.state.claim.key);