tumwater 0.1.2 → 0.2.0

package/dist/src/status/status-polls.js

@@ -1,5 +1,7 @@
+// vocabulary: plain
 import { asTestCounts } from "../build/build-check-counts.js";
-import { isLandingChange } from "../landing/landing-slot.js";
+import { isFullCheckScope } from "../build/build-check-events.js";
+import { isMergeChange, readMergeMarker } from "../merge/merge-slot.js";
 import { defaultConfig, loadConfigCached } from "../config/config.js";
 import { DEFAULT_EVENT_TAIL, readEvents } from "../events/event-read.js";
 import { currentBranchFromHeadFile, readBranchHead, targetBranch } from "../git/git.js";
@@ -8,9 +10,18 @@ import { eventsLogPath, statePath } from "../paths.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { countMaintenanceWindow, maintenanceQuota, newMaintenanceWindowCounter, } from "../gates/maintenance-quota.js";
 import { commitTier } from "../roles/roles.js";
+/** Is a value one of MainCheckStatus's three statuses? The one home of the membership test:
+ * the event log is loose-typed by design, and a check whose status is not one of the three
+ * (a hand-edited or future-format block) is malformed — dropped like any other malformed
+ * check (see MainCheckScan.check's note) rather than narrowed with a cast into a status it
+ * cannot prove, which would otherwise leak a mystery word to the header badge and the GUI
+ * payload (mainCheckVerdict renders any unmatched status verbatim). */
+function isMainCheckStatus(status) {
+    return status === "passed" || status === "failed" || status === "skipped";
+}
 /** How far mainCheckForPoll may grow its event tail. The per-poll default
- * (event-read.ts's DEFAULT_EVENT_TAIL) covers a healthy fleet — a merge-scope check rides
- * every landing and every redeploy — but a burst of quiet or failing ticks logs hundreds
+ * (event-read.ts's DEFAULT_EVENT_TAIL) covers a healthy team — a merge-scope check rides
+ * every merge and every redeploy — but a burst of quiet or failing ticks logs hundreds
  * of events without moving main, and a tail
  * that ends before the last check makes the header badge vanish and reappear as ticks tick
  * by. Growing until the check is found keeps "absent" meaning what the field's contract says
@@ -21,9 +32,9 @@ import { commitTier } from "../roles/roles.js";
  * Past the cap the badge drops, the same graceful loss log rotation already imposes. */
 const MAIN_CHECK_SCAN_MAX_EVENTS = 5_000;
 /** Per-root note that the previous scan had to grow past the default event tail
- * (DEFAULT_EVENT_TAIL) without finding a merge-scope check. A check rides every landing, so a poll
+ * (DEFAULT_EVENT_TAIL) without finding a merge-scope check. A check rides every merge, so a poll
  * that grew all the way to the cap is a burst of quiet or failing ticks — hundreds of events
- * between landings — and the next poll's growth starts straight at the cap instead of re-scanning
+ * between merges — and the next poll's growth starts straight at the cap instead of re-scanning
  * the ×4 ladder's intermediate windows (200→800→3200→5000 ≈ 9.2k re-parsed events per
  * fresh tail, vs 5.2k for 200→cap; measured on a 6k-event check-free log, ~2.3 ms → ~1.2 ms per
  * append+poll). A poll that finds a check clears the note, so the ordinary find-in-200 /
@@ -32,21 +43,21 @@ const MAIN_CHECK_SCAN_MAX_EVENTS = 5_000;
 const mainCheckGrewFull = new Set();
 const MAIN_CHECK_FULL_SET_MAX = 64;
 /** Per-root scan cache (stat-cache.cachedByStat): both dashboards poll snapshot every second,
- * but events.jsonl is written only at tick boundaries and landings, so an unchanged log serves
+ * but events.jsonl is written only at tick boundaries and merges, so an unchanged log serves
  * the whole scan from one stat instead of re-listing the ladder, re-parsing its windows, and
- * re-collecting the landed events. Rotation swaps the inode and every append changes the size,
+ * re-collecting the merged events. Rotation swaps the inode and every append changes the size,
  * so both invalidate through the same freshness check; keyed by root so distinct repos never
  * collide. Bounded inside cachedByStat. */
 const mainCheckScanCache = new Map();
 /** Scan the log for MainCheckScan, growing the tail until a merge-scope check is inside it (see
  * MAIN_CHECK_SCAN_MAX_EVENTS): a check older than the default tail must still badge the header,
- * and every event after the check — the landed pairing the sha needs — is newer, so one window
+ * and every event after the check — the merged pairing the sha needs — is newer, so one window
  * holds the whole derivation. */
 function scanMainCheck(root) {
     let check;
-    // The final window's landed events, in scan order — collected in the same pass that
+    // The final window's merged events, in scan order — collected in the same pass that
     // finds the check instead of a second full scan of the window below.
-    let landed = [];
+    let mergeDone = [];
     const grewFull = mainCheckGrewFull.has(root);
     // A set note means the previous scan reached the cap without finding a check, so start
     // there: starting at DEFAULT_EVENT_TAIL would only re-read (and re-parse on a cache miss)
@@ -55,16 +66,16 @@ function scanMainCheck(root) {
     for (let window = grewFull ? MAIN_CHECK_SCAN_MAX_EVENTS : DEFAULT_EVENT_TAIL;; window = grewFull ? MAIN_CHECK_SCAN_MAX_EVENTS : Math.min(window * 4, MAIN_CHECK_SCAN_MAX_EVENTS)) {
         const events = readEvents(root, window);
         check = undefined;
-        landed = [];
+        mergeDone = [];
         // One pass collects both facts the derivation needs: the newest merge-scope check and
-        // every landed event. The landings are re-read against the check's ts below — a pass
-        // over the landings alone, not a second pass over every event in the window.
+        // every merged event. The merges are re-read against the check's ts below — a pass
+        // over the merges alone, not a second pass over every event in the window.
         for (const e of events) {
-            if (e.type === "build_check" && (e.scope === "landing" || e.scope === "batch" || e.scope === "baseline")) {
+            if (e.type === "build_check" && isFullCheckScope(e.scope)) {
                 check = e;
             }
-            else if (e.type === "landed" && typeof e.ts === "number") {
-                landed.push(e);
+            else if (e.type === "merge_done" && typeof e.ts === "number") {
+                mergeDone.push(e);
             }
         }
         // Found, the log is shorter than the window (nothing older exists to find), or the cap
@@ -80,21 +91,21 @@ function scanMainCheck(root) {
         mainCheckGrewFull.delete(root);
     else
         mainCheckGrewFull.add(root);
-    if (!check || typeof check.ts !== "number" || typeof check.status !== "string") {
+    if (!check || typeof check.ts !== "number" || !isMainCheckStatus(check.status)) {
         return { check: undefined };
     }
-    let landedAfter;
-    let landedBefore;
-    for (const e of landed) {
+    let mergeDoneAfter;
+    let mergeDoneBefore;
+    for (const e of mergeDone) {
         if (e.ts > check.ts)
-            landedAfter = e;
+            mergeDoneAfter = e;
         else
-            landedBefore = e;
+            mergeDoneBefore = e;
     }
     return {
         check,
-        ...(typeof landedAfter?.commit === "string" ? { landedAfterCommit: landedAfter.commit } : {}),
-        ...(typeof landedBefore?.commit === "string" ? { landedBeforeCommit: landedBefore.commit } : {}),
+        ...(typeof mergeDoneAfter?.commit === "string" ? { mergeDoneAfterCommit: mergeDoneAfter.commit } : {}),
+        ...(typeof mergeDoneBefore?.commit === "string" ? { mergeDoneBeforeCommit: mergeDoneBefore.commit } : {}),
     };
 }
 /** The cached scan for `root`, computing it through scanMainCheck on a cache miss. The clone
@@ -103,6 +114,21 @@ function scanMainCheck(root) {
 function mainCheckScanFor(root) {
     return (cachedByStat(mainCheckScanCache, root, eventsLogPath(root), () => scanMainCheck(root), (v) => ({ ...v, ...(v.check ? { check: { ...v.check } } : {}) })) ?? { check: undefined });
 }
+/** Has main's newest merge-scope check retired a loop's stale `main_red` verdict? Only a
+ * PASSED check stamped strictly after the loop's red tick ended counts — the team-level
+ * green is newer evidence than the loop's own red (BUGS.md 2026-09-30). A failed or skipped
+ * newest check, a check from before the red tick, or a loop with no known tick end all leave
+ * the verdict standing. Single-homed here beside heldByMainRed. */
+function mainCheckRecovered(mainCheck, s) {
+    return mainCheck?.status === "passed"
+        && s.lastRunEndedAt !== undefined
+        && mainCheck.at > s.lastRunEndedAt;
+}
+/** Is a loop's tick verdict still the red-main hold? The one predicate behind the status
+ * phase's `main red` label and doctor's `main red` check, so the two cannot disagree. */
+export function heldByMainRed(s, mainCheck) {
+    return s.lastResult === "main_red" && s.queuedSummary === undefined && !mainCheckRecovered(mainCheck, s);
+}
 /** The newest merge-scope build_check in the event tail, with the main sha it verified
  * (mainCheck's derivation — see the field's comment). A gate-scope check is excluded: it
  * verified a role worktree, not main. The log-derived scan is stat-cached per events.jsonl
@@ -111,10 +137,10 @@ function mainCheckScanFor(root) {
 export function mainCheckForPoll(root, cfg) {
     const scan = mainCheckScanFor(root);
     const check = scan.check;
-    if (!check || typeof check.ts !== "number" || typeof check.status !== "string")
+    if (!check || typeof check.ts !== "number" || !isMainCheckStatus(check.status))
         return undefined;
     const branch = targetBranch(cfg.baseBranch, currentBranchFromHeadFile(root));
-    const sha = scan.landedAfterCommit ?? readBranchHead(root, branch) ?? scan.landedBeforeCommit;
+    const sha = scan.mergeDoneAfterCommit ?? readBranchHead(root, branch) ?? scan.mergeDoneBeforeCommit;
     const counts = asTestCounts(check.counts);
     return {
         ...(sha ? { sha } : {}),
@@ -128,18 +154,27 @@ export function mainCheckForPoll(root, cfg) {
  * marker displays only while its sha is still queued; a marker with per-change records keeps
  * just its records whose sha is still queued — a change whose entry was dropped is finished,
  * whatever its record last said — and displays only while one of those is not `done`. */
-export function liveLandingMarker(marker, queued) {
+export function liveMergeMarker(marker, queued) {
     if (!Array.isArray(marker.changes))
         return queued.has(marker.sha) ? marker : undefined;
     // Drop foreign entries before reading their sha/status: a `null`/scalar record in a
     // hand-edited marker would otherwise throw out of the every-second status poll.
-    const changes = marker.changes.filter(isLandingChange).filter((c) => queued.has(c.sha));
+    const changes = marker.changes.filter(isMergeChange).filter((c) => queued.has(c.sha));
     return changes.some((c) => c.status !== "done") ? { ...marker, changes } : undefined;
 }
+/** The marker observers display for a queue read: undefined unless the orchestrator is running
+ * (`running`) and the marker has a live record for a queued entry (liveMergeMarker). The one
+ * home of this cross-check for the status snapshot, `tumwater queue`, and the TUI Pending pane. */
+export function queueInFlight(root, entries, running) {
+    if (!running)
+        return undefined;
+    const marker = readMergeMarker(root);
+    return marker ? liveMergeMarker(marker, new Set(entries.map((e) => e.sha))) : undefined;
+}
 // The last config each root loaded successfully. snapshot is polled every second by the
 // TUI and GUI, where a throw would kill (or blind) the observer — but tumwater.json can be
 // transiently broken while a user edits it live-reload style. On failure we keep showing
-// the fleet with the last known-good role set; the orchestrator does the same in its own
+// the team with the last known-good role set; the orchestrator does the same in its own
 // reload poll and surfaces the error as a warning event visible in `tumwater logs`.
 const lastGoodConfig = new Map();
 /** The config to display loop state against: fresh when valid, otherwise the last
@@ -178,10 +213,10 @@ const maintenanceCounters = new Map();
 /** The maintenance allowance verdict as an observer sees it for this poll (status-data's
  * `maintenanceQuota` field): the rolling-window counts over the same event log the gate reads,
  * plus the enabled maintenance loops currently in flight (running a tick or holding a queued
- * landing, so the `used` figure matches the gate's). `held` names the enabled maintenance loop
+ * merge, so the `used` figure matches the gate's). `held` names the enabled maintenance loop
  * ids the scheduler holds while `used >= allowance`. Pure read — unlike the gate it logs nothing
  * and keeps no hold edge, so it can run in the TUI/GUI process every second. */
-export function maintenanceQuotaForPoll(root, perWorkLanding, loops, queuedLandingRoles, now) {
+export function maintenanceQuotaForPoll(root, perWorkMerge, loops, queuedMergeRoles, now) {
     let counter = maintenanceCounters.get(root);
     if (!counter) {
         counter = newMaintenanceWindowCounter();
@@ -194,9 +229,9 @@ export function maintenanceQuotaForPoll(root, perWorkLanding, loops, queuedLandi
         if (commitTier(loop.role) !== "maintenance")
             continue;
         maintenanceRoles.push(loop.role);
-        if (loop.running || queuedLandingRoles.has(loop.role))
+        if (loop.running || queuedMergeRoles.has(loop.role))
             inFlight++;
     }
-    const verdict = maintenanceQuota({ work, maint, inFlight, perWorkLanding });
+    const verdict = maintenanceQuota({ work, maint, inFlight, perWorkMerge });
     return { allowance: verdict.allowance, used: verdict.used, held: verdict.held ? maintenanceRoles : [] };
 }

package/dist/src/status/status-roles.js

@@ -0,0 +1,105 @@
+// vocabulary: plain
+import path from "node:path";
+import { configForRole, modelSelectorField, roleSeamTier, } from "../config/config-views.js";
+import { modelFallbackView } from "../config/config-fallbacks.js";
+import { isCustomRole } from "../config/config.js";
+import { baseRoleOf, loopIds } from "../roles/loop-ids.js";
+import { formatModelSelector } from "../config/model-selector.js";
+import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
+import { isJsonObject } from "../files/json-object.js";
+import { loopStateForPoll } from "./status-polls.js";
+import { roleImageInfo, seamImageLabel } from "../agent/image-input.js";
+import { imageProbeEntryFresh, readImageProbeCache } from "../doctor/image-probe.js";
+/** One row per enabled loop id (part 5b/7). `configForRole`, `modelFallbackView`, the leased /
+ * pinned slot and the pi-default seam all resolve against the values `snapshot()` already
+ * read once for the poll — the info and slots pins (threaded as `slots`) keep rows, `running`
+ * and `disk` on the same shared reads, and `now` is the snapshot's pinned clock so every row
+ * agrees on what "active" means. One read of pi's own saved default per poll (docs/backends.md)
+ * serves the rows whose seam runs pi and resolves no model — its settings.json sits beside the
+ * models catalog this snapshot reads (piSettingsPath), so one seam serves both. */
+export function collectRoleRows(root, cfg, now, slots, modelsPath) {
+    const roles = loopIds(cfg);
+    const piDefault = readPiDefaultModel(piSettingsPath(modelsPath), root);
+    // One probe-cache read per poll serves every row's image-input surface (same no-data policy
+    // as every other degraded read: a missing cache is an empty one).
+    const probes = readImageProbeCache(root);
+    return roles.map((r) => {
+        const base = { ...loopStateForPoll(root, r), custom: isCustomRole(cfg, r) };
+        const leased = slots.find((slot) => slot.lease?.role === r);
+        const pinned = slots.find((slot) => slot.pinnedFor === r);
+        const slot = leased ?? pinned;
+        // Every row carries the selector its config resolves to, so the dashboards show which
+        // model a role rides even with a single string `model`. A tier-name `roles.<id>.model`
+        // and a role selector override both resolve through configForRole — the same view the
+        // seam consumes. Part 7a (model-tiers.md "Observability"): the seam tier tag is added
+        // only with a tier map declared, where it names the tier a role rides.
+        const eff = configForRole(cfg, r);
+        // The image-input surface (plans/image-input.md "Surfaces", part 5/5): the loop's own
+        // capability and its reroute target, one shared resolver so the status rows, the role
+        // page, and the submit gate cannot disagree about who reads images or where a blind
+        // prompt would run.
+        const image = roleImageInfo(cfg, r, modelsPath, probes);
+        // Model failure fallback, part 2/2: while the role's episode is active its ticks run on
+        // the tier-resolved fallback pair, so the row names that pair, the episode's start, and
+        // the failure that tripped it. `now` is the poll's own clock (the snapshot seam), so
+        // every row agrees on what "active" means.
+        const episode = modelFallbackView(base.modelFallback, cfg, r, now);
+        // A seam that runs pi and resolves neither a provider nor a model starts on pi's own
+        // saved default — name it in the row (modelFromPi) so the operator sees which model the
+        // loop runs. The config's `thinking` wins over the default's because tumwater passes it
+        // to pi as `--thinking` (src/pi/pi-args.ts). Any other row is unchanged and carries no
+        // `modelFromPi`.
+        const runsPiWithoutAModel = (eff.agent === undefined || eff.agent === "pi") &&
+            eff.provider === undefined &&
+            eff.model === undefined;
+        const modelFromPi = runsPiWithoutAModel && piDefault !== null;
+        return {
+            ...base,
+            ...modelSelectorField(eff),
+            imageInput: image.imageInput,
+            imageRerouteLabel: image.imageReroute,
+            ...(modelFromPi
+                ? {
+                    model: formatModelSelector({
+                        ...piDefault,
+                        thinking: eff.thinking ?? piDefault.thinking,
+                    }),
+                    modelFromPi: true,
+                }
+                : {}),
+            ...(isJsonObject(cfg.model) ? { modelTier: roleSeamTier(cfg, r) } : {}),
+            ...(episode !== null ? { fallback: episode } : {}),
+            ...(slot ? { slot: path.basename(slot.dir), slotPinned: pinned !== undefined } : {}),
+            ...(baseRoleOf(r) === r ? {} : { instanceOf: baseRoleOf(r) }),
+        };
+    });
+}
+/** The doctor's live-probe failures (plans/image-input.md "Surfaces", part 5/5): every cached
+ * probe verdict of `fail` that is still fresh (the claim is unchanged and within the 7-day
+ * TTL), labelled as `<provider>/<model>`. A claimed model that failed the probe reads `false`
+ * everywhere (seamImageInput honors a fresh failure), but the observability value is naming
+ * it — a claim the doctor contradicted is exactly what the amber probe alert and the role/status
+ * rows should surface, not just "this loop is text-only". A torn or missing cache answers
+ * empty (the same no-data policy as the per-loop read). */
+export function collectImageProbeFailures(root, now = Date.now()) {
+    const probes = readImageProbeCache(root);
+    const out = [];
+    for (const [key, entry] of Object.entries(probes)) {
+        if (entry.verdict !== "fail" || !imageProbeEntryFresh(entry, now))
+            continue;
+        // The cache key is agent/provider/model, and a pi model id is itself fully qualified (the
+        // key's third segment can carry embedded '/' — parseModelSelector keeps the id whole), so
+        // split only the first two separators and keep the rest as the model. A naive split("/")
+        // destructured to three parts would truncate a qualified id to its org, mislabelling the
+        // model the doctor flagged.
+        const first = key.indexOf("/");
+        const second = key.indexOf("/", first + 1);
+        if (first === -1 || second === -1)
+            continue;
+        const agent = key.slice(0, first) || undefined;
+        const provider = key.slice(first + 1, second) || undefined;
+        const model = key.slice(second + 1) || undefined;
+        out.push(seamImageLabel(agent, provider, model));
+    }
+    return out.sort();
+}

package/dist/src/{fleet → team}/error-storm.js

@@ -1,11 +1,11 @@
-/** The fleet-wide error-storm warning (BUGS.md 2026-09-29): when three or more roles' ticks
+/** The team-wide error-storm warning (BUGS.md 2026-09-29): when three or more roles' ticks
  * are failing consecutively on one shared cause, only each role's own "consecutive tick
- * failures" warning fires — nothing fleet-wide names the shared cause. The 2026-09-22
+ * failures" warning fires — nothing team-wide names the shared cause. The 2026-09-22
  * meltdown (all 14 roles timing out at the 1800 s default for 8 hours) surfaced as 14
- * independent streak warnings; an operator scanning the feed saw a quiet fleet. POLICY, on
- * the shape of the fleet-wide hold (src/fleet/fleet-hold.ts): a pure reducer over the
+ * independent streak warnings; an operator scanning the feed saw a quiet team. POLICY, on
+ * the shape of the team-wide hold (src/team/team-hold.ts): a pure reducer over the
  * observations the orchestrator collects each poll and the previous storm, so the rule is
- * unit-testable without a fleet and the orchestrator owns only the wiring (the warning
+ * unit-testable without a team and the orchestrator owns only the wiring (the warning
  * event). Like the hold it has memory — which storm is active is a fact about the past
  * no single poll's inputs carry — so it is a reducer rather than a stateless predicate. */
 import { getOrCreate, rankByCount } from "../collections.js";
@@ -18,19 +18,19 @@ import { ERROR_STREAK_WARN } from "../tick/tick-apply.js";
  * standard the 2026-09-22 storm's diagnosis needed. Two would cry wolf on a pair of roles that
  * happen to hit the same broken merge target; the per-role warnings already cover that pair. */
 export const ERROR_STORM_ROLES = 3;
-/** The fleet's starting state: no storm. */
+/** The team's starting state: no storm. */
 export const ERROR_STORM_QUIET = { key: null, roles: [] };
 /** The config knob a shared cause points at, when one is known. Only the timeout cause is
  * mapped: `timed out after <dur>` is the reducer's pooled rendering of the tick-timeout errors
- * (src/agent/run-agent.ts's two `timed out after ${tickTimeoutSeconds}s` shapes, pooled into one
+ * (src/agent/run-agent.ts's two `timed out after ${runTimeoutSeconds}s` shapes, pooled into one
  * key by poolTimeoutKey — src/failure/failure-cluster.ts owns the two shapes and their
- * pooling), and a fleet-wide
+ * pooling), and a team-wide
  * run of it means the tick budget does not fit the serving model — the one cause with a knob
  * to name. Every other cause is left unmapped: the storm warning still names it, but inventing
  * a knob for a cause no setting controls would send an operator turning the wrong dial.
  * Exported for its unit tests. */
 export function errorStormKnob(key) {
-    return key === TICK_TIMEOUT_KEY ? "tickTimeoutSeconds" : undefined;
+    return key === TICK_TIMEOUT_KEY ? "runTimeoutSeconds" : undefined;
 }
 /** Step the storm by one orchestrator poll: from `prev` and every role's current streak,
  * decide what is storming now. A role counts toward a cause once its streak has reached the
@@ -41,7 +41,7 @@ export function errorStormKnob(key) {
  * (the wiring logs exactly one event), a poll that still sees the same storm returns `prev`
  * itself so the caller can tell nothing changed, and a storm whose members drop below the
  * bar goes quiet and re-arms — a recurrence warns again. A storm on a different cause is a
- * new episode: the old cause no longer explains the fleet, so the new one names itself. */
+ * new episode: the old cause no longer explains the team, so the new one names itself. */
 export function errorStorm(prev, observations) {
     const rolesByKey = new Map();
     for (const { role, consecutiveErrors, lastError } of observations) {

package/dist/src/{fleet → team}/failure-spread.js

@@ -1,15 +1,15 @@
-/** The fleet-wide wide-shallow storm alarm (BUGS.md 2026-09-30, part (2) of the
+/** The team-wide wide-shallow storm alarm (BUGS.md 2026-09-30, part (2) of the
  * 2026-09-29 connection-storm entry): when many roles each fail a few times on one provider
  * failure kind, no existing bar trips — the per-role streak alarm needs one role DEEP
  * (ERROR_STREAK_WARN consecutive, src/tick/tick-apply.ts), the error-storm warning needs several
- * roles deep at once (src/fleet/error-storm.ts), and the fleet hold needs failures COALESCED within
- * a two-minute window (src/fleet/fleet-hold.ts). A degraded backend that fails the fleet widely and
+ * roles deep at once (src/team/error-storm.ts), and the team hold needs failures COALESCED within
+ * a two-minute window (src/team/team-hold.ts). A degraded backend that fails the team widely and
  * shallowly — six ticks across as many roles, each failure minutes apart — rides all three
  * gaps in silence. This alarm counts raw failures of one kind across roles in a rolling
  * window, independent of any role's streak depth: the fourth bar, shaped for the spread the
- * other three cannot see. POLICY, on the shape of its siblings (src/fleet/error-storm.ts,
- * src/fleet/fleet-hold.ts): a pure reducer over the observations the orchestrator collects each
- * poll and the previous state, so the rule is unit-testable without a fleet and the
+ * other three cannot see. POLICY, on the shape of its siblings (src/team/error-storm.ts,
+ * src/team/team-hold.ts): a pure reducer over the observations the orchestrator collects each
+ * poll and the previous state, so the rule is unit-testable without a team and the
  * orchestrator owns only the wiring (the warning event). Like both siblings it has memory —
  * which failures still sit inside the window is a fact about the past no single poll's inputs
  * carry — so it is a reducer rather than a stateless predicate. */
@@ -24,10 +24,10 @@ import { increment, rankCountEntries } from "../collections.js";
 export const FAILURE_SPREAD_COUNT = 6;
 /** How recent a failure must be to count toward the alarm. Thirty minutes: wide enough that
  * failures spaced minutes apart — the shape a degraded backend produces against a staggered
- * fleet — read as one episode; narrow enough that a bad half-hour this morning does not alarm
+ * team — read as one episode; narrow enough that a bad half-hour this morning does not alarm
  * all afternoon. */
 export const FAILURE_SPREAD_WINDOW_MS = 30 * 60_000;
-/** The fleet's starting state: quiet, with no history. */
+/** The team's starting state: quiet, with no history. */
 export const FAILURE_SPREAD_QUIET = { recent: [], active: false, kind: null };
 /** Step the alarm by one orchestrator poll: fold each observation into the window (skipping
  * ones older than the window and ones already folded — the same runner observation re-read

package/dist/src/{fleet → team}/orchestrator-info.js

@@ -2,7 +2,7 @@ import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { finiteNumber, isJsonObject } from "../files/json-object.js";
 import { pidAlive } from "../process/process.js";
 import { orchestratorStatePath } from "../paths.js";
-import { warnEventBestEffort } from "../events/events.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 /** Assign one field of the orchestrator info file in place, but only when the value differs
  * from what it already carries, and report whether it changed. This is the shared rule for the
@@ -11,12 +11,30 @@ import { errorMessage } from "../text/text.js";
  * once after several fields. The comparison uses JSON serialization, matching
  * writeOrchestratorInfo's
  * own output, so a value equal to the stored one is never treated as a change. */
-export function assignInfoFieldIfChanged(info, field, value) {
+function assignInfoFieldIfChanged(info, field, value) {
     if (JSON.stringify(value) === JSON.stringify(info[field]))
         return false;
     info[field] = value;
     return true;
 }
+/** Assign several non-recomputable info fields in place (each via assignInfoFieldIfChanged) and
+ * publish the file best-effort once when any of them changed — the publish idiom the
+ * orchestrator's poll (permits, build) and gate-polls (the budget trio, disk) apply to every
+ * field observers cannot recompute. Every field is staged regardless of the others (this is
+ * not a short-circuiting find), so a batch like the budget trio lands as exactly one write no
+ * matter how many of its fields changed, while an unchanged batch leaves the file untouched.
+ * Returns whether the file was written. The staging primitive and the best-effort writer are
+ * private to this module now that publishInfoFields is the only publish path. */
+export function publishInfoFields(root, info, fields) {
+    let changed = false;
+    for (const [field, value] of fields) {
+        if (assignInfoFieldIfChanged(info, field, value))
+            changed = true;
+    }
+    if (changed)
+        writeOrchestratorInfoBestEffort(root, info);
+    return changed;
+}
 /** Read the running orchestrator's info file; null when it is missing or unreadable.
  * Never throws — a torn write (e.g. a crash mid-write) must not take down observers
  * that poll this every second (TUI, GUI, status). The nested fields cross the same
@@ -67,6 +85,36 @@ function parseBuild(v) {
         build.restartBlocked = v.restartBlocked;
     return build;
 }
+/** The published permit snapshot, or undefined for any foreign shape. Each `byKey` entry must
+ * carry its two numbers; `limit` is kept only when it is a number, so a malformed provider
+ * map is dropped to `undefined` rather than reaching a render that reads it as a valid cap. */
+/** One entry of the published provider-holds list, or undefined for any foreign shape: a
+ * well-formed entry is an object with a finite `until` and a string `kind`; a `provider` that
+ * is present but not a string drops the entry, so a guarded list keeps its well-formed
+ * siblings rather than dropping wholesale. */
+function parseProviderHold(v) {
+    if (!isJsonObject(v) || !isFiniteNumber(v.until) || typeof v.kind !== "string")
+        return undefined;
+    if (v.provider !== undefined && typeof v.provider !== "string")
+        return undefined;
+    return { ...(v.provider !== undefined ? { provider: v.provider } : {}), until: v.until, kind: v.kind };
+}
+function parsePermits(v) {
+    if (!isJsonObject(v) || !isFiniteNumber(v.inUse) || !isFiniteNumber(v.limit) || !isFiniteNumber(v.reserve))
+        return undefined;
+    if (!isJsonObject(v.byKey))
+        return undefined;
+    const byKey = {};
+    for (const [key, value] of Object.entries(v.byKey)) {
+        if (!isJsonObject(value) || !isFiniteNumber(value.inUse) || !isFiniteNumber(value.waiting))
+            continue;
+        const entry = { inUse: value.inUse, waiting: value.waiting };
+        if (isFiniteNumber(value.limit))
+            entry.limit = value.limit;
+        byKey[key] = entry;
+    }
+    return { inUse: v.inUse, limit: v.limit, reserve: v.reserve, byKey };
+}
 function isLastReclaim(v) {
     if (!isJsonObject(v))
         return false;
@@ -75,19 +123,23 @@ function isLastReclaim(v) {
         isFiniteNumber(v.freedGB) &&
         (mode === "pressure" || mode === "idle" || mode === "manual"));
 }
+/** Parse one nested field through a field parser and either assign its parsed shape or, when
+ * the parser rejects the value as foreign, delete the field so a degraded value never reaches
+ * a render that reads it as valid. The only fields with a dedicated parser (build,
+ * fallbackDemoted, permits) keep their values unchanged when well-formed. */
+function parseOrDelete(rec, key, parse) {
+    const parsed = parse(rec[key]);
+    if (parsed === undefined)
+        delete rec[key];
+    else
+        rec[key] = parsed;
+}
 /** Degrade each known nested field to a usable shape or drop it, mutating the freshly parsed
  * object in place so a well-formed file keeps its values unchanged. */
 function normalizeInfoFields(rec) {
-    const build = parseBuild(rec.build);
-    if (build === undefined)
-        delete rec.build;
-    else
-        rec.build = build;
-    const demoted = parseDemotion(rec.fallbackDemoted);
-    if (demoted === undefined)
-        delete rec.fallbackDemoted;
-    else
-        rec.fallbackDemoted = demoted;
+    parseOrDelete(rec, "build", parseBuild);
+    parseOrDelete(rec, "fallbackDemoted", parseDemotion);
+    parseOrDelete(rec, "permits", parsePermits);
     const demotions = rec.fallbackDemotions;
     if (!isJsonObject(demotions))
         delete rec.fallbackDemotions;
@@ -103,6 +155,22 @@ function normalizeInfoFields(rec) {
     const budget = rec.budget;
     if (!isJsonObject(budget) || !isFiniteNumber(budget.spentUsd))
         delete rec.budget;
+    if (rec.chain !== undefined && !isJsonObject(rec.chain))
+        delete rec.chain;
+    if (rec.stopsAt !== undefined && !isFiniteNumber(rec.stopsAt))
+        delete rec.stopsAt;
+    const providerHolds = rec.providerHolds;
+    if (!Array.isArray(providerHolds))
+        delete rec.providerHolds;
+    else {
+        const kept = [];
+        for (const value of providerHolds) {
+            const parsed = parseProviderHold(value);
+            if (parsed !== undefined)
+                kept.push(parsed);
+        }
+        rec.providerHolds = kept;
+    }
     const disk = rec.disk;
     if (!isJsonObject(disk) ||
         !isFiniteNumber(disk.freeGB) ||
@@ -118,25 +186,25 @@ function normalizeInfoFields(rec) {
 /** Publish the running orchestrator's info file atomically (writeJsonAtomic's tmp + rename).
  * The only writer of that path, so a process killed mid-write — the orchestrator's own poll
  * publishes budget/disk/build changes while `tumwater run` in another terminal reads it to
- * refuse a second fleet — leaves either the previous complete file or the new one, never a
+ * refuse a second team — leaves either the previous complete file or the new one, never a
  * torn body that readOrchestratorInfo reports as no running orchestrator. */
 export function writeOrchestratorInfo(root, info) {
     writeJsonAtomic(orchestratorStatePath(root), info);
 }
 /** Publish the info file for a caller on a path that must not throw — the orchestrator's
  * catch-less poll loop, whose build/budget/disk updates run every couple of seconds. The info
- * file is an observation surface, not fleet state: an unwritable state dir (ENOSPC, EACCES, the
- * path replaced by a directory) must degrade the published snapshot, not end the fleet. The
+ * file is an observation surface, not team state: an unwritable state dir (ENOSPC, EACCES, the
+ * path replaced by a directory) must degrade the published snapshot, not end the team. The
  * failure is reported as a best-effort warning; the caller keeps polling and the field is
  * retried the next time its value changes. Startup's first write stays strict
- * (writeOrchestratorInfo): it is what refuses a second fleet, so a repo that cannot publish it
+ * (writeOrchestratorInfo): it is what refuses a second team, so a repo that cannot publish it
  * must fail fast rather than boot. */
-export function writeOrchestratorInfoBestEffort(root, info) {
+function writeOrchestratorInfoBestEffort(root, info) {
     try {
         writeOrchestratorInfo(root, info);
     }
     catch (err) {
-        warnEventBestEffort(root, "harness", `could not publish orchestrator info: ${errorMessage(err)}`);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `could not publish orchestrator info: ${errorMessage(err)}`);
     }
 }
 /** True when the recorded orchestrator's pid is still alive (see pidAlive). Callers that have

package/dist/src/{fleet → team}/reclaim.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 /** Pressure reclaim of build outputs (plans/disk-floor.md, "Reclaiming build outputs", part
  * 2/4): when the worktrees volume drops below `diskReclaimGB`, delete the files git ignores
  * (`git clean -fdX`) in idle harness worktrees, least recently used first, before part 1/4's
@@ -10,7 +11,7 @@
 import path from "node:path";
 import { worktreesDir } from "../paths.js";
 import { git, gitTry } from "../git/git-run.js";
-import { logEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { loadLoopState } from "../loop/loop-state.js";
 import { BYTES_PER_GB, sampleFreeBytes } from "../gates/disk-gate.js";
 import { subdirectoryNames } from "../files/files.js";
@@ -29,7 +30,7 @@ const HOUR_MS = 60 * 60 * 1000;
  * the listing instead of being stamped used and delaying a later reclaim. */
 export function reclaimCandidates(root, now = Date.now(), opts = {}) {
     const dir = worktreesDir(root);
-    // A missing worktrees dir (a fleet that has not started) yields no candidates.
+    // A missing worktrees dir (a team that has not started) yields no candidates.
     const names = subdirectoryNames(dir, (name) => !RESERVED_WORKTREES.has(name));
     // Seed never-seen worktrees as used-now under the cross-process lock, and remember which of
     // this pass's names that covered so they stay out of it. A later pass (or a restart) then sees
@@ -89,7 +90,7 @@ function isIdleExpired(candidate, idleHours, now) {
 /** True when `dir` is a linked worktree and not the primary checkout: `git rev-parse --git-dir`
  * and `--git-common-dir` differ for a linked worktree and are equal for the primary checkout.
  * Reading the primary checkout's `.gitignore` with `clean -X` would delete `.tumwater/`, the
- * fleet's entire state, so both this and the path check below are load-bearing. */
+ * team's entire state, so both this and the path check below are load-bearing. */
 export async function isLinkedWorktree(dir) {
     const gitDir = await gitTry(dir, "rev-parse", "--git-dir");
     const commonDir = await gitTry(dir, "rev-parse", "--git-common-dir");
@@ -167,7 +168,7 @@ export async function reclaimPass(root, mode, opts) {
         durationMs: Date.now() - startedAt,
     };
     logEventBestEffort(root, {
-        loop: "harness",
+        source: TUMWATER_SOURCE,
         type: "disk_reclaim",
         mode,
         worktrees: cleaned,