tumwater 0.2.0 → 0.3.0

package/dist/src/brief/brief.js

@@ -1,19 +1,18 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { briefCandidates } from "../paths.js";
 import { errorMessage, truncateWithNote } from "../text/text.js";
 /** The managed sections of the project brief (TUMWATER.md, with README.md as the
  * compatibility path — plans/portability.md §7a/7): marker constants, the templates a fresh
- * repo gets, and reading the project's initial prompt back out. */
+ * repo gets, and reading the project's brief text back out. */
 export const PROMPT_START = "<!-- tumwater:prompt:start -->";
 export const PROMPT_END = "<!-- tumwater:prompt:end -->";
-/** Cap on the initial prompt (see readInitialPrompt). The prompt is the project's reason to
- * exist and rides into EVERY tick and director prompt, so unbounded text would be a standing
- * per-tick prefill cost — the same budget customRoles.task and roles.<id>.instructions are
+/** Cap on the brief text (see readBriefText). The prompt is the project's reason to
+ * exist and rides into EVERY run and director prompt, so unbounded text would be a standing
+ * per-run prefill cost — the same budget customRoles.task and roles.<id>.instructions are
  * held to. `tumwater init` rejects an over-long prompt before it is committed (init.ts); this
  * constant is the shared bound so the read path and the init check cannot drift. */
-export const INITIAL_PROMPT_MAX_CHARS = 4096;
+export const BRIEF_TEXT_MAX_CHARS = 4096;
 // The status markers stay exported too: the readme role targets the resolved brief file, not
 // a hardcoded README.md, and doctor's brief check reports which file holds the sections. The
 // prompt markers above stay exported because init.ts names them in its error message.
@@ -21,21 +20,21 @@ export const STATUS_START = "<!-- tumwater:status:start -->";
 export const STATUS_END = "<!-- tumwater:status:end -->";
 /** The placeholder every fresh template seeds between the status markers. A brief still
  * carrying exactly this body (or an empty one) is "description incomplete"; once the readme
- * role replaces it with a real status the tight-loop rule turns itself off. Hoisted so the
- * template and briefStatusIncomplete cannot drift on the wording. */
-export const EMPTY_STATUS = "_No status yet. The readme role keeps this section up to date._";
-/** The two managed sections a fresh brief carries — the initial prompt in its prompt
+ * role replaces it with a real status the project's description is complete. Hoisted so the
+ * template and the readme role's real-status replacement cannot drift on the wording. */
+const EMPTY_STATUS = "_No status yet. The readme role keeps this section up to date._";
+/** The two managed sections a fresh brief carries — the brief text in its prompt
  * markers, an empty status in its status markers — under the given H1. Both homes render
  * the identical body (README.md for a fresh repo, TUMWATER.md for an adopted one), so the
  * body lives here once and the two templates cannot drift on section wording or marker
  * placement; the H1 is the only difference between them. */
-function managedSections(heading, initialPrompt) {
+function managedSections(heading, briefText) {
     return `# ${heading}
 
 ## Brief
 
 ${PROMPT_START}
-${initialPrompt.trim()}
+${briefText.trim()}
 ${PROMPT_END}
 
 ## Status
@@ -45,19 +44,19 @@ ${EMPTY_STATUS}
 ${STATUS_END}
 `;
 }
-/** The README.md a fresh repo starts with: the initial prompt and an empty status,
+/** The README.md a fresh repo starts with: the brief text and an empty status,
  * each in its managed section. */
-export function readmeTemplate(projectName, initialPrompt) {
-    return managedSections(projectName, initialPrompt);
+export function readmeTemplate(projectName, briefText) {
+    return managedSections(projectName, briefText);
 }
 /** The TUMWATER.md an adopted repo gets (plans/portability.md §7a/7, written by 7b's adopt
  * path): the same two managed sections as the README template, under a brief heading —
  * so the resolution logic in this module is the only difference between the two homes. */
-export function briefTemplate(projectName, initialPrompt) {
-    return managedSections(`${projectName} — project brief`, initialPrompt);
+export function briefTemplate(projectName, briefText) {
+    return managedSections(`${projectName} — project brief`, briefText);
 }
 /** True when `text` carries a well-formed managed prompt block: opening marker, then a
- * closing one strictly after it (readInitialPrompt's ordering guard). */
+ * closing one strictly after it (readBriefText's ordering guard). */
 function ownsBrief(text) {
     const start = text.indexOf(PROMPT_START);
     if (start < 0)
@@ -72,8 +71,8 @@ function ownsBrief(text) {
  *
  * A candidate that exists but cannot be read (README.md created as a directory, a
  * permission-lost file) is an operator-visible break, not a silent skip: the brief is
- * every loop's reason to exist, read each tick, so falling through to the next candidate
- * could run the team on the wrong brief and throwing raw would crash every tick with an
+ * every role's reason to exist, read each run, so falling through to the next candidate
+ * could run the team on the wrong brief and throwing raw would crash every run with an
  * errno that names neither the file nor the fix — the message below names both. */
 function firstBriefText(root, accepts) {
     for (const candidate of briefCandidates(root)) {
@@ -93,37 +92,18 @@ function firstBriefText(root, accepts) {
 }
 /** Which file owns the project's managed sections — the basename of the first candidate
  * that carries a well-formed prompt block, or null when none does. Callers that only need
- * the prompt use readInitialPrompt; this exists for the prompt builders (which name the
+ * the prompt use readBriefText; this exists for the prompt builders (which name the
  * actual file) and doctor's brief check. */
 export function briefFile(root) {
     return readBrief(root)?.file ?? null;
 }
-/** False when there is no resolved brief, or the resolved brief carries no well-formed
- * STATUS_START/STATUS_END pair (a malformed brief is doctor's warning, not a tight loop);
- * otherwise true when the status body between the markers is empty or still the EMPTY_STATUS
- * placeholder. The one machine-detectable "description not yet complete" signal: the initial
- * prompt half of the description is always present (init rejects an empty one). One small
- * single-file read, like readInitialPrompt. */
-export function briefStatusIncomplete(root) {
-    const found = firstBriefText(root, ownsBrief);
-    if (!found)
-        return false;
-    const bodyStart = found.text.indexOf(STATUS_START);
-    if (bodyStart < 0)
-        return false;
-    const bodyEnd = found.text.indexOf(STATUS_END, bodyStart + STATUS_START.length);
-    if (bodyEnd < 0)
-        return false;
-    const body = found.text.slice(bodyStart + STATUS_START.length, bodyEnd).trim();
-    return body === "" || body === EMPTY_STATUS;
-}
-/** The project's initial prompt, extracted from the resolved brief file's managed section —
+/** The project's brief text, extracted from the resolved brief file's managed section —
  * TUMWATER.md when it exists with markers, else README.md (plans/portability.md §7a/7). The
  * closing marker is searched for only AFTER the opening one: an end marker mentioned in prose
  * before the real block (e.g. README docs explaining how to edit the prompt) must not make a
- * valid later block unreadable — every loop would then run without its project prompt, and
+ * valid later block unreadable — every role would then run without its project prompt, and
  * init's guard would reject re-init as if the section were missing. */
-export function readInitialPrompt(root) {
+export function readBriefText(root) {
     return readBrief(root)?.prompt ?? "";
 }
 /** The full path of the file that owns the prompt block (the same candidate readBrief
@@ -135,7 +115,7 @@ export function briefPath(root) {
 /** `text` with the prompt block's content replaced by `prompt` (trimmed), every byte outside
  * the two markers kept; null when the text has no well-formed block. Finds the block by
  * extractPrompt's rule (first start marker, then the first end marker after it). */
-export function replaceInitialPrompt(text, prompt) {
+export function replaceBriefText(text, prompt) {
     const start = text.indexOf(PROMPT_START);
     if (start < 0)
         return null;
@@ -161,22 +141,22 @@ function extractPrompt(text) {
     if (prompt === null)
         return null;
     // A hand-edited brief can carry an over-long prompt past init's length check. Truncate it
-    // for every tick instead of injecting the whole thing (the same defensive cap readPrinciples
+    // for every run instead of injecting the whole thing (the same defensive cap readPrinciples
     // applies, through text.ts's truncateWithNote), with a visible note so the loss is not
     // silent. init rejects the normal path before it is committed, so this is the backstop.
-    return truncateWithNote(prompt, INITIAL_PROMPT_MAX_CHARS, "brief");
+    return truncateWithNote(prompt, BRIEF_TEXT_MAX_CHARS, "brief");
 }
 /** The resolved brief as one value: the owning file's basename (briefFile) and its extracted
- * initial prompt (readInitialPrompt) from a SINGLE firstBriefText scan. Tick prompt assembly
- * asks for both on every tick, and briefFile + readInitialPrompt each re-ran the candidate
- * scan and re-read the file — two whole-file reads per tick for one file's worth of content.
- * readInitialPrompt and briefFile now derive from this, so there is one read path; null when
+ * brief text (readBriefText) from a SINGLE firstBriefText scan. Run prompt assembly
+ * asks for both on every run, and briefFile + readBriefText each re-ran the candidate
+ * scan and re-read the file — two whole-file reads per run for one file's worth of content.
+ * readBriefText and briefFile now derive from this, so there is one read path; null when
  * no candidate carries a well-formed prompt block (both derived values are then empty/null). */
 export function readBrief(root) {
     const found = firstBriefText(root, ownsBrief);
     return found ? { file: found.file, prompt: extractPrompt(found.text) ?? "" } : null;
 }
-/** The brief's plain-text form: its file name, then the initial prompt — what `tumwater brief`
+/** The brief's plain-text form: its file name, then the brief text — what `tumwater brief`
  * prints and the TUI's Brief tab shows, so the two cannot drift. */
 export function renderBrief(brief) {
     return `${brief.file}\n${brief.prompt}`;

package/dist/src/budget/budget.js

@@ -1,17 +1,17 @@
-/** The daily-cost budget: a loop's and the team's local-day spend and the gate those figures
+/** The daily-cost budget: a role's and the team's local-day spend and the gate those figures
  * drive (plans/daily-cost-budget.md, plans/fallback-model.md). The circuit breaker that judges
  * whether the gate's fallback can actually serve lives beside it in fallback-breaker.ts. Split
- * out of loop-state.ts, which owns
- * LoopState persistence and scheduling bookkeeping: the budget is POLICY both the scheduler and
+ * out of runner-state.ts, which owns
+ * RunnerState persistence and scheduling bookkeeping: the budget is POLICY both the scheduler and
  * every observer evaluate from the same definitions. Kept free of the scheduler and of pi's
  * model catalog (fallback readiness arrives as plain booleans), so observers can depend on it
  * without importing either — the one-way rule that previously kept these functions in
- * loop-state.ts. */
+ * runner-state.ts. */
 import { MODEL_TIERS } from "../config/config-schema.js";
-import { nonNegativeNumber } from "../files/json-object.js";
+import { nonNegativeNumber, setOwn } from "../files/json-object.js";
 import { dayAt, dayKey } from "../text/datetime.js";
 /** The local calendar day as YYYY-MM-DD — the same local-time convention as every other
- * wall-clock display in the harness (lastTickCell). */
+ * wall-clock display in the harness (lastRunCell). */
 export function todayStamp(now = Date.now()) {
     return dayKey(now);
 }
@@ -22,10 +22,10 @@ export function todayStamp(now = Date.now()) {
 function spendNumber(value) {
     return nonNegativeNumber(value, 0);
 }
-/** This loop's spend for the local day (the daily cost budget window): $0 when its stamp is
- * stale or missing — a loop that hasn't ticked since yesterday reads as $0 today with no save
+/** This role's spend for the local day (the daily cost budget window): $0 when its stamp is
+ * stale or missing — a role that hasn't ran since yesterday reads as $0 today with no save
  * required, and spend recorded before this field existed is unknown. A non-number,
- * non-finite, or negative value reads as $0 too: `loadLoopState` heals the field on read, but
+ * non-finite, or negative value reads as $0 too: `loadRunnerState` heals the field on read, but
  * this is the budget gate's own guard, and a hand-edited or torn `dayCostUsd` (or an in-memory
  * state) would otherwise concatenate into
  * teamDailyCost's sum (or make every `>= cap` comparison false) and silently defeat the cap,
@@ -33,11 +33,11 @@ function spendNumber(value) {
 export function dailyCost(s, now = Date.now()) {
     return s.dayStamp === todayStamp(now) ? spendNumber(s.dayCostUsd) : 0;
 }
-/** Record a pi run's cost into the loop's daily window, rolling over at local midnight:
- * when `now` is on a different day than the recorded stamp the window resets first, so a tick
+/** Record a pi run's cost into the role's daily window, rolling over at local midnight:
+ * when `now` is on a different day than the recorded stamp the window resets first, so a run
  * that crosses midnight attributes its spend to the correct day. Mutates `s` in place — like
- * applyTickOutcome and foldUsage's other counter updates, the caller's state object is
- * authoritative across an in-flight tick; the value persists at tick end with the rest of the
+ * applyRunOutcome and foldUsage's other counter updates, the caller's state object is
+ * authoritative across an in-flight run; the value persists at run end with the rest of the
  * state. Both operands are guarded through spendNumber so a corrupt stored value or a
  * non-finite/negative run cost cannot poison the window with a string/NaN/negative sum. */
 export function recordDailyCost(s, usd, now = Date.now(), pair) {
@@ -53,10 +53,10 @@ export function recordDailyCost(s, usd, now = Date.now(), pair) {
     if (pair !== undefined) {
         const by = (s.dayCostByPair ??= {});
         const sum = spendNumber(Object.hasOwn(by, pair) ? by[pair] : 0) + spendNumber(usd);
-        Object.defineProperty(by, pair, { value: sum, enumerable: true, writable: true, configurable: true });
+        setOwn(by, pair, sum);
     }
 }
-/** One model pair's spend for the local day, summed over every loop's per-pair window
+/** One model pair's spend for the local day, summed over every role's per-pair window
  * (`dayCostByPair`): $0 for a stale day stamp or a pair no run has charged. */
 export function pairDailyCost(states, pair, now = Date.now()) {
     const today = todayStamp(now);
@@ -65,14 +65,24 @@ export function pairDailyCost(states, pair, now = Date.now()) {
         return sum + (by !== undefined && Object.hasOwn(by, pair) ? spendNumber(by[pair]) : 0);
     }, 0);
 }
-/** The team's spend for the local day: every loop's daily window summed. */
+/** The team's spend for the local day: every role's daily window summed. */
 export function teamDailyCost(states, now = Date.now()) {
     return states.reduce((sum, s) => sum + dailyCost(s, now), 0);
 }
+/** The roles that spent most today, highest first (ties by role name), at most `limit`; roles
+ * with no spend today (zero or a stale day window) are left out. Each state is its own role, so
+ * `feature` and `feature-2` are listed apart. */
+export function topDailySpenders(states, now = Date.now(), limit = 3) {
+    return states
+        .map((s) => ({ role: s.role, spentUsd: dailyCost(s, now) }))
+        .filter((r) => r.spentUsd > 0)
+        .sort((a, b) => b.spentUsd - a.spentUsd || (a.role < b.role ? -1 : a.role > b.role ? 1 : 0))
+        .slice(0, limit);
+}
 /** True when today's spend has reached the daily cost budget — the view is non-null, its cap is
  * enabled (capUsd > 0; a cap of 0 disables the gate regardless of spend), and spend sits at or
  * above it. The single definition of "the budget gate is on": the orchestrator evaluates it from
- * live loop states via budgetPaused, and both dashboards evaluate it from the snapshot's
+ * live runner states via budgetPaused, and both dashboards evaluate it from the snapshot's
  * materialized budget field (status/status-data.ts) — which carries the object even while
  * disabled, so the capUsd > 0 term is what keeps a disabled team out of "budget paused". The
  * comparison cannot drift between what the scheduler enforces and what users see. */
@@ -84,7 +94,7 @@ export function budgetReached(budget) {
 export const BUDGET_WARNING_FRACTION = 0.8;
 /** True when today's spend has crossed `BUDGET_WARNING_FRACTION` of the daily cap while the
  * budget gate is still open — the early heads-up beside budgetReached, which fires only once
- * the cap itself is reached and the team has already stopped (or demoted) its ticks. Same
+ * the cap itself is reached and the team has already stopped (or demoted) its runs. Same
  * guard terms as budgetReached (non-null view, a cap of 0 disables the budget), scaled by the
  * warning fraction, so the two views can never disagree about whether the budget is on. */
 export function budgetWarning(budget) {
@@ -98,7 +108,7 @@ export function budgetWarning(budget) {
 export function budgetPaused(states, config, now = Date.now()) {
     return budgetReached(budgetSpend(states, config, now));
 }
-/** The team's daily-budget figures from live loop states — the exact pair the gate evaluates:
+/** The team's daily-budget figures from live runner states — the exact pair the gate evaluates:
  * today's summed spend and the configured cap (0 when disabled). budgetReached's own capUsd > 0
  * term makes a disabled cap read unreached, so the pair needs no null ceremony. Returning the
  * figures (not just the verdict) lets the scheduler publish WHAT it tripped on, not only THAT it
@@ -141,7 +151,7 @@ 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 tick is wasted work);
+ * review is on and `strong` does (nothing could merge, so every authoring run is wasted work);
  * `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/budget/fallback-breaker.js

@@ -1,16 +1,15 @@
-// vocabulary: plain
 /** The fallback's circuit breaker (BUGS.md 2026-09-20): whether the engaged free fallback can
  * actually SERVE. Split out of budget.ts, which keeps the daily-cost figures and the gate they
  * drive; the breaker is a self-contained pure state machine — no scheduler, no pi model
- * catalog, no persistence — that depends on nothing but the TickResult vocabulary, so the
- * orchestrator can hold it in memory and fold tick outcomes into it without importing the
+ * catalog, no persistence — that depends on nothing but the RunResult vocabulary, so the
+ * orchestrator can hold it in memory and fold run outcomes into it without importing the
  * budget. The gate reads its verdict through fallbackServing (budget.ts's budgetGate). */
-/** failureLimit 3 is a single loop's failing-streak threshold (tick-apply.ts ERROR_STREAK_WARN)
- * applied team-wide: consecutive across every role, so any tick that served in between resets
- * it — a healthy backend with one flaky tick never trips it, while a dead one trips on its
- * first three ticks (on 2026-09-19 the third failure landed 24 minutes into the hour; the 30
- * ticks after it were the waste). A 5-minute first cool-down because a failed probe costs one
- * tick — about half of that hour's failures came back in under 10 s, the rest ran minutes
+/** failureLimit 3 is a single role's failing-streak threshold (run-apply.ts ERROR_STREAK_WARN)
+ * applied team-wide: consecutive across every role, so any run that served in between resets
+ * it — a healthy backend with one flaky run never trips it, while a dead one trips on its
+ * first three runs (on 2026-09-19 the third failure landed 24 minutes into the hour; the 30
+ * runs after it were the waste). A 5-minute first cool-down because a failed probe costs one
+ * run — about half of that hour's failures came back in under 10 s, the rest ran minutes
  * before the 400 — which is cheap next to idling until midnight; doubling to at most 30 minutes
  * bounds how long an operator who fixed the backend waits for the team to notice (editing the
  * cap or the pair re-trusts it at once — see rekeyFallbackBreaker). */
@@ -44,34 +43,34 @@ export function fallbackServing(b) {
     return b.probeAt === null;
 }
 /** Half-open: the demoted fallback's cool-down has elapsed and no probe is in flight, so one role
- * tick may start on it despite the `paused` gate. */
+ * run may start on it despite the `paused` gate. */
 export function fallbackProbeDue(b, now) {
     return b.pair !== null && b.probeAt !== null && !b.probing && now >= b.probeAt;
 }
-/** The breaker once the probe tick has been admitted: probing until recordFallbackTick hears
- * back, so every other due role waits for its verdict — one tick's evidence per cool-down, not
+/** The breaker once the probe run has been admitted: probing until recordFallbackRun hears
+ * back, so every other due role waits for its verdict — one run's evidence per cool-down, not
  * a whole maxConcurrent wave of failures. */
 export function startFallbackProbe(b) {
     return { ...b, probing: true };
 }
 /** The breaker when an admitted probe never ran — turned away at its permit by the restart
  * hold's start gate: no evidence either way, so the claim is handed back and the probe is due
- * again at the next poll. Without this the breaker would wait on a verdict no tick will ever
+ * again at the next poll. Without this the breaker would wait on a verdict no run will ever
  * deliver, and the demoted pause could only clear on a rekey. */
 export function abandonFallbackProbe(b) {
     return { ...b, probing: false };
 }
-/** What one role tick that ran on the fallback says about its backend. `failed` is `error`
+/** What one role run that ran on the fallback says about its backend. `failed` is `error`
  * alone: every way a backend cannot serve — an HTTP 4xx/5xx like oMLX's prefill guard, a
- * refused connection, a request that never returns (the tick timeout) — ends a tick as `error`,
+ * refused connection, a request that never returns (the run timeout) — ends a run as `error`,
  * and 33 of 33 did on 2026-09-19. (An `error` can also be local, e.g. a worktree that will not
  * reset; failureLimit of those in a row team-wide is still a team that cannot work, and the
  * probe wins the pause back.) `served` is a result only a model reply produces: a change bound
  * for merge (`queued`, `changed`), an explicit decision (`no_change`, `refused`), or a
  * reviewer's rejection. Everything else is no evidence: harness and operator kills (`aborted`,
- * `user_aborted`), ticks that never reached the model (`skipped`, `main_red`), a quiet kill
+ * `user_aborted`), runs that never reached the model (`skipped`, `main_red`), a quiet kill
  * (the model had answered before the stall — a tool call or the stream stopped), and the
- * merge results (`merge_conflict`, `merge_blocked`, `review_error`) — a tick no longer
+ * merge results (`merge_conflict`, `merge_blocked`, `review_error`) — a run no longer
  * returns them since leftover recovery queues its pin instead of merging it, and they would
  * not say whether the backend was involved. */
 export function fallbackEvidence(result) {
@@ -88,15 +87,15 @@ export function fallbackEvidence(result) {
             return "none";
     }
 }
-/** Fold one finished role tick that ran on the fallback into the breaker. `ranOn` is the breaker as
- * the tick started under it — evidence about a subject that is no longer engaged is dropped —
- * and `probe` says whether the orchestrator admitted it as the half-open probe. A served tick
+/** Fold one finished role run that ran on the fallback into the breaker. `ranOn` is the breaker as
+ * the run started under it — evidence about a subject that is no longer engaged is dropped —
+ * and `probe` says whether the orchestrator admitted it as the half-open probe. A served run
  * closes the breaker from any state (the backend demonstrably works). A failed probe re-opens it
- * with the cool-down doubled up to maxCooldownMs; a failed tick while closed counts toward
+ * with the cool-down doubled up to maxCooldownMs; a failed run while closed counts toward
  * failureLimit and trips the breaker at it; a failed straggler that started before the trip leaves
  * the running cool-down alone. A probe with no evidence frees the probe slot, so the next due role
  * probes instead. */
-export function recordFallbackTick(b, ranOn, result, probe, now, policy = FALLBACK_BREAKER_POLICY) {
+export function recordFallbackRun(b, ranOn, result, probe, now, policy = FALLBACK_BREAKER_POLICY) {
     if (ranOn.pair === null || ranOn.pair !== b.pair || ranOn.capUsd !== b.capUsd)
         return b;
     const isProbe = probe && b.probing;
@@ -143,7 +142,7 @@ export function fallbackServingPair(map, pair) {
 }
 /** The pair whose half-open window is due, or null when none is. Several pairs can carry a
  * demotion at once (one per resolved tier), so the walk returns the first due entry in map
- * order and the caller probes that single pair this tick. */
+ * order and the caller probes that single pair this run. */
 export function fallbackProbeDuePair(map, now) {
     for (const [pair, b] of Object.entries(map)) {
         if (fallbackProbeDue(b, now))
@@ -153,7 +152,7 @@ export function fallbackProbeDuePair(map, now) {
 }
 /** Apply `f` to the pair's entry when the map holds one, else return the map unchanged — the
  * shape shared by the map-scoped breaker transitions below (claim/hand back a probe, fold a
- * tick): a pair the resolution dropped has no judgment to touch. */
+ * run): a pair the resolution dropped has no judgment to touch. */
 function withPair(map, pair, f) {
     const b = map[pair];
     return b === undefined ? map : { ...map, [pair]: f(b) };
@@ -168,9 +167,9 @@ export function startFallbackProbeAt(map, pair) {
 export function abandonFallbackProbeAt(map, pair) {
     return withPair(map, pair, abandonFallbackProbe);
 }
-/** Fold one finished role tick into the pair named `pair`'s entry (recordFallbackTick's
+/** Fold one finished role run into the pair named `pair`'s entry (recordFallbackRun's
  * semantics, scoped to the map): an absent entry has no judgment to fold into and is left
  * alone. */
-export function recordFallbackTickAt(map, pair, ranOn, result, probe, now, policy = FALLBACK_BREAKER_POLICY) {
-    return withPair(map, pair, (b) => recordFallbackTick(b, ranOn, result, probe, now, policy));
+export function recordFallbackRunAt(map, pair, ranOn, result, probe, now, policy = FALLBACK_BREAKER_POLICY) {
+    return withPair(map, pair, (b) => recordFallbackRun(b, ranOn, result, probe, now, policy));
 }

package/dist/src/build/build-check-detect.js

@@ -1,11 +1,10 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { isJsonObject } from "../files/json-object.js";
 import { readJsonFile } from "../files/json-files.js";
-import { walkUp } from "../files/files.js";
+import { isDirectory, statOrNull, walkUp } from "../files/files.js";
 import { isNonBlankString } from "../text/text.js";
-/** Hard cap on one build check run — a hung script (watch mode) must not wedge the tick, and
+/** Hard cap on one build check run — a hung script (watch mode) must not wedge the run, and
  * a timeout is environmental, never fail-closed. The default `check.timeoutSeconds` resolves
  * to this (via ms in detectBuildCheck); runBuildCheck uses it as its default timeout
  * parameter so tests can shorten it. */
@@ -18,13 +17,7 @@ const WALK_UP_LEVELS = 5;
 /** True when `dir` holds both a package.json and a node_modules/ directory — the structural
  * signature of an installed JS project root. */
 function hasInstall(dir) {
-    try {
-        fs.statSync(path.join(dir, "package.json"));
-        return fs.statSync(path.join(dir, "node_modules")).isDirectory();
-    }
-    catch {
-        return false;
-    }
+    return statOrNull(path.join(dir, "package.json")) !== null && isDirectory(path.join(dir, "node_modules"));
 }
 /** Read the check script from `dir`'s package.json: prefer test — npm convention makes
  * `npm test` the canonical verify command — then typecheck, then build; null when none is
@@ -95,15 +88,30 @@ export function detectBuildCheck(startDir, config, maxLevels = WALK_UP_LEVELS) {
     return found !== null && found.kind === "npm" && configuredMs !== undefined ? { ...found, timeoutMs: configuredMs } : found;
 }
 /** The configured per-change gate command (`check.gateCommand`, PLANS.md Land-queue speed 3e) when
- * it is a non-blank string, else undefined — off. Opt-in: a repo that sets it trades a cheaper
- * review-gate pre-check for a full check.command run that happens once per stack at the batch/merge
- * scope instead. One reading shared by runScopedBuildCheck (which runs it at scope "gate") and
- * merge-to-main.ts's verifyMerge (which must then never treat the gate's green as the full
- * check's), so the two cannot disagree about whether it is on. */
+ * it is a non-blank string, else undefined — off. Opt-in: when no `mergeCommand` is declared, a
+ * project that sets one merges on it, not the full check (mergeCommandOf's fallback, PLANS.md
+ * "Fast merge" "Defaults"). One reading shared by runScopedBuildCheck (which runs it at scope
+ * "gate") and merge-to-main.ts's verifyMerge (which must then never treat the gate's green as the
+ * full check's), so the two cannot disagree about whether it is on. */
 export function gateCommandOf(config) {
     const g = config?.check?.gateCommand;
     return isNonBlankString(g) ? g : undefined;
 }
+/** The configured in-lock merge command (`check.mergeCommand`, PLANS.md "Fast merge" part 6/14)
+ * when it is a non-blank string, else undefined — off. An absent `mergeCommand` falls back to
+ * the gate command (`gateCommandOf`, PLANS.md "Fast merge" "Defaults"): a project that declared
+ * a `check.gateCommand` merges on it. With it set, the merge and batch scopes run it instead of
+ * the full check, and main's full-check verdict comes from the main watch. A blank string
+ * (`""`) is the explicit opt-out that keeps the full check in the merge lock even when a gate
+ * command is set. One reading shared by runScopedBuildCheck, the merge paths and the main-red
+ * verdict reads, so they cannot disagree about whether it is on. */
+export function mergeCommandOf(config) {
+    const c = config?.check;
+    const m = c?.mergeCommand;
+    if (m === undefined)
+        return gateCommandOf(config);
+    return isNonBlankString(m) ? m : undefined;
+}
 /** Resolve `node_modules/<rel>` by walking UP from `startDir` — the same climb detectBuildCheck
  * makes, and the same one npm's run-script PATH walk makes: a tumwater worktree has no install
  * of its own (node_modules is gitignored, so it exists only where someone ran npm install), and

package/dist/src/build/build-check-events.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** The presentation half of the build check: the scope vocabulary, the environmental-skip
  * warning's wording, and the build_check event's shape. Split out of build-check.ts — which
  * keeps the deterministic execution and classification (detect → spawn → classify) — because
@@ -8,21 +7,27 @@
  * running a check. This module imports only types from build-check.js, so no runtime cycle.
  * runScopedBuildCheck (build-check-scoped.ts) is the only caller that both runs a check and
  * uses this wording; the baseline surfaces use the event/warning helpers alone. */
+import { logEventBestEffort } from "../events/events.js";
 /** Does this build_check scope stand for a full-suite verdict — merge, batch, or the red-main
  * baseline? A gate check can run a subset of the tree, so a scope outside this set is never a
  * full-suite check. The one vocabulary the three predicates that recognize a full-suite check
  * select on — isPassingFullCheck, isRedFullCheck, and the status polls' newest-merge-check
  * scan (status-polls.ts) — so they cannot drift on which scopes count. The deadline-killed
  * failure costing in time-spend.ts is a narrower pair (merge/batch only, with a status and a
- * timeout required), so it keeps its own check. */
-export function isFullCheckScope(scope) {
+ * timeout required), so it keeps its own check. `full` is the event's `full` field: false
+ * (a check.mergeCommand run) is never a full-suite check. */
+export function isFullCheckScope(scope, full) {
+    // A merge or batch run of check.mergeCommand carries `full: false` (buildCheckEvent): it ran
+    // the cheaper command, so it is no full-suite verdict whatever its scope.
+    if (full === false)
+        return false;
     return scope === "merge" || scope === "batch" || scope === "baseline";
 }
 /** Is this a passing build_check over the full suite? The scopes doctor's check row counts —
  * merge, batch and the red-main baseline — are isFullCheckScope's set; a gate check can run a
  * subset, so it is left out. */
 export function isPassingFullCheck(ev) {
-    return ev.type === "build_check" && ev.status === "passed" && isFullCheckScope(ev.scope);
+    return ev.type === "build_check" && ev.status === "passed" && isFullCheckScope(ev.scope, ev.full);
 }
 /** The red sibling of isPassingFullCheck: a failed build_check over the same three scopes
  * (isFullCheckScope's set). A `skipped` check made no verdict about the tree, and a merge-scope
@@ -30,7 +35,7 @@ export function isPassingFullCheck(ev) {
  * alone is the rule. The two predicates are mutually exclusive on `status`, so a fold branch on
  * them never sees the other's events. */
 export function isRedFullCheck(ev) {
-    return ev.type === "build_check" && ev.status === "failed" && isFullCheckScope(ev.scope);
+    return ev.type === "build_check" && ev.status === "failed" && isFullCheckScope(ev.scope, ev.full);
 }
 /** How late a check's deadline timer may fire before the timeout's wording stops naming the
  * configured bound alone. Normal timer lag is milliseconds; past this the warning and the
@@ -236,11 +241,14 @@ function buildCheckRunFields(outcome) {
  * runScopedBuildCheck's two priced events in build-check-scoped.ts (the killed retry and the
  * final verdict) and the red-main baseline loggers (main-red.ts's baselineCheckLogger,
  * redeploy.ts's redeploy mirror), which all paid the run whose timings the event carries. */
-export function buildCheckEvent(source, scope, outcome, durationMs) {
+export function buildCheckEvent(source, scope, outcome, durationMs, 
+/** True for a merge/batch run of check.mergeCommand: the event then carries `full: false`. */
+cheaper = false) {
     return {
         source,
         type: "build_check",
         scope,
+        ...(cheaper ? { full: false } : {}),
         status: outcome.status,
         script: outcome.script,
         durationMs,
@@ -259,6 +267,17 @@ export function buildCheckEvent(source, scope, outcome, durationMs) {
             : {}),
     };
 }
+/** A scoped check that waited at least this long for a process-wide check permit is worth an
+ * event: it is the operator's signal that `maxConcurrentChecks` is too small for the team. */
+export const CHECK_WAIT_EVENT_MS = 30_000;
+/** Log one `check_wait` when a scoped check waited at least CHECK_WAIT_EVENT_MS for a check
+ * permit; a shorter wait is ordinary queueing and stays silent. The one home of the event's
+ * shape, beside buildCheckEvent. Best-effort: an unwritable feed must not fail the check. */
+export function logCheckWaitEvent(root, role, scope, waitedMs, parked) {
+    if (waitedMs < CHECK_WAIT_EVENT_MS)
+        return;
+    logEventBestEffort(root, { source: role, type: "check_wait", role, scope, waitedMs, ...parked });
+}
 /** The onRun hook that logs one baseline check's build_check event through `log` under `source`:
  * main-red.ts's gate logger (logEventBestEffort) and redeploy.ts's green-check and witness hooks
  * all turn the same run shape into the same baseline event, so that mapping lives here once