tumwater 0.2.0 → 0.3.0

package/dist/src/operator/revert.js

@@ -1,11 +1,11 @@
-// vocabulary: plain
 import { loadConfigSafe } from "../config/config.js";
-import { withStateLockAsync } from "../concurrency/lock.js";
+import { withPrimaryWorktreeLockAsync } from "../concurrency/lock.js";
 import { currentBranch, headOf, isMergedInto, targetBranch } from "../git/git.js";
-import { COMMIT_IDENT, gitTry } from "../git/git-run.js";
-import { stampedSubject } from "../git/commit-message.js";
-import { primaryWorktreeLockPath } from "../paths.js";
+import { GitError, commitAuthorArgs, committerIdentArgs, gitTry, runGit } from "../git/git-run.js";
+import { stampedRole, stampedSubject } from "../git/commit-message.js";
 import { shortSha } from "../text/format.js";
+import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { runMergedSha } from "../run/run-detail-data.js";
 /** `tumwater revert <sha>`: undo one merged change on main, committing the inverse as
  * `tumwater(operator): Revert <short sha>` on the primary checkout. Mirrors
  * `commitOperatorBacklogEdit`'s lock-and-branch discipline (src/backlog/backlog-commit.ts): the
@@ -13,6 +13,118 @@ import { shortSha } from "../text/format.js";
  * fast-forward, and it refuses — writing nothing — when the primary is not on the base branch.
  * Fail-closed: an unknown ref, a ref not on the base branch, or a revert that conflicts writes
  * no commit and leaves the checkout as it was. */
+/** The shared git steps of a revert: `git revert --no-commit <sha>` in `wt`, then commit just the
+ * inverse as `message`. `wt` must have a clean tracked tree (so `--abort` after a conflict has
+ * nothing to discard). Never throws; a conflict or a failed commit aborts the revert and comes
+ * back as `{ ok: false, error }` with `wt` as it was. */
+export async function revertCommitIn(wt, sha, message) {
+    if ((await gitTry(wt, "revert", "--no-commit", sha)) === null) {
+        // The tree was clean when the revert started, so --abort restores exactly that state.
+        await gitTry(wt, "revert", "--abort");
+        return { ok: false, error: `reverting ${shortSha(sha)} conflicted; nothing was committed and the checkout is unchanged` };
+    }
+    // `--only` with the revert's own staged paths commits just the inverse, so it cannot pick up any
+    // unrelated change of another path staged after the clean check. `--no-renames` keeps a rename's
+    // two halves as separate path lines: the default name-only collapses a detected rename to its
+    // destination, which would commit only half and leave the other half staged with a dirty tree.
+    const pathsSpec = ((await gitTry(wt, "diff", "--cached", "--name-only", "--no-renames")) ?? "")
+        .split("\n")
+        .filter((p) => p.length > 0);
+    if ((await gitTry(wt, ...(await committerIdentArgs(wt)), "commit", ...commitAuthorArgs(), "--only", "-m", message, "--", ...pathsSpec)) === null) {
+        await gitTry(wt, "revert", "--abort");
+        return { ok: false, error: `the revert of ${shortSha(sha)} did not commit; nothing was committed` };
+    }
+    return { ok: true, sha: await headOf(wt, "HEAD") };
+}
+/** The read-only refusals shared by a revert and its preview: the primary checkout must be on the
+ * base branch, `ref` must resolve to a commit, and that commit must be merged into the branch.
+ * The dashboard's `handleRun` also calls it, to decide whether a run's commit is on the base
+ * branch. */
+export async function resolveRevertTarget(root, ref) {
+    const primary = await currentBranch(root);
+    const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
+    if (primary === null || base !== primary)
+        return { ok: false, error: `the primary checkout is not on ${base} — run from a checkout of it` };
+    const full = await gitTry(root, "rev-parse", "--verify", ref + "^{commit}");
+    if (full === null)
+        return { ok: false, error: `no such commit: ${ref}` };
+    if (!(await isMergedInto(root, full, primary)))
+        return { ok: false, error: `${shortSha(full)} is not on ${primary}` };
+    return { ok: true, full, primary };
+}
+/** The refusal for a commit without exactly one parent (a root or a merge), or null. Shared by
+ * the revert and its preview: `git revert` of a root deletes the whole tree, of a merge needs
+ * `-m`. */
+async function parentRefusal(root, full) {
+    const parents = (await runGit(root, ["rev-list", "--parents", "-n", "1", full])).split(" ").length - 1;
+    if (parents === 1)
+        return null;
+    return `${shortSha(full)} has ${parents} parents; tumwater revert undoes a single-parent commit only, so nothing was written`;
+}
+/** The commit a run's merge put on main, or the CLI's refusal: the run did not merge, or merged
+ * but the event log no longer names its commit. Shared by `tumwater revert <role> <n>` and the
+ * TUI History trail's Ctrl+V so the two cannot drift. */
+export function runRevertSha(role, run, detail) {
+    if (detail.result !== "merged")
+        return { ok: false, error: `${role} run #${run} did not merge (result: ${detail.result ?? "unknown"}); there is nothing to revert` };
+    const sha = runMergedSha(detail);
+    if (sha === null)
+        return { ok: false, error: `${role} run #${run} merged but the event log no longer names its commit; pass the sha from git log instead` };
+    return { ok: true, sha };
+}
+/** `tumwater revert <sha> --dry-run`: what a revert of `ref` would undo and whether it applies
+ * cleanly, from git's object store alone — a `git merge-tree` three-way merge (base = the commit,
+ * ours = HEAD, theirs = its parent, the merge `git revert` performs). Takes no lock and never
+ * touches the index, the worktree or a ref. Never throws. */
+export async function previewRevert(root, ref) {
+    try {
+        const target = await resolveRevertTarget(root, ref);
+        if (!target.ok)
+            return target;
+        const { full, primary } = target;
+        const refusal = await parentRefusal(root, full);
+        if (refusal !== null)
+            return { ok: false, error: refusal };
+        const subject = await runGit(root, ["log", "-1", "--format=%s", full]);
+        const paths = (await runGit(root, ["diff", "--name-only", "--no-renames", full + "^", full]))
+            .split("\n")
+            .filter((p) => p.length > 0);
+        const head = await headOf(root, "HEAD");
+        let applies = true;
+        try {
+            await runGit(root, ["merge-tree", "--write-tree", "--merge-base=" + full, "HEAD", full + "^"]);
+        }
+        catch (err) {
+            if (!(err instanceof GitError))
+                throw err;
+            if (err.code !== 1)
+                return { ok: false, error: `could not preview the revert: ${err.message}` };
+            applies = false;
+        }
+        const dirty = (await runGit(root, ["status", "--porcelain", "--untracked-files=no"])) !== "";
+        return { ok: true, sha: full, subject, paths, head, primary, applies, dirty };
+    }
+    catch {
+        return { ok: false, error: "the revert preview did not complete (git failed); nothing was written" };
+    }
+}
+/** The role a revert of a commit with this subject undoes: the stamped role when it is a working
+ * role, else null — an unstamped (hand-made) commit, the operator's or the harness's own. */
+function revertedRole(subject) {
+    const role = stampedRole(subject);
+    if (role === undefined || role === "operator" || role === "tumwater")
+        return null; // vocabulary-ok: commit stamp strings
+    return role;
+}
+/** What to tell the operator after reverting a commit with this subject: the role that made it may
+ * redo the work. Null when no role made it — an unstamped (hand-made) commit, the operator's or
+ * the harness's own. */
+export function revertFollowUp(subject) {
+    const role = revertedRole(subject);
+    if (role === null)
+        return null;
+    return `the ${role} role may redo the work, so cancel or edit its PLANS.md/BUGS.md entry if it should not`;
+}
 /** Revert one already-merged commit (`ref` resolved to a commit) and commit the inverse on the
  * primary checkout under the primary-worktree lock. Never throws; every refusal and every git
  * failure comes back as `{ ok: false, error }` after restoring the checkout. `head` is captured
@@ -24,18 +136,17 @@ export async function revertMergedCommit(root, ref) {
         // call, and that write takes the same lock synchronously — a lock already held across our
         // awaits would block its event loop until the lock times out.
         await new Promise((resolve) => setImmediate(resolve));
-        return await withStateLockAsync(primaryWorktreeLockPath(root), async () => {
-            const primary = await currentBranch(root);
-            const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
-            if (primary === null || base !== primary)
-                return { ok: false, error: `the primary checkout is not on ${base} — run from a checkout of it` };
-            const full = await gitTry(root, "rev-parse", "--verify", ref + "^{commit}");
-            if (full === null)
-                return { ok: false, error: `no such commit: ${ref}` };
+        return await withPrimaryWorktreeLockAsync(root, async () => {
+            const target = await resolveRevertTarget(root, ref);
+            if (!target.ok)
+                return target;
+            const { full } = target;
+            const refusal = await parentRefusal(root, full);
+            if (refusal !== null)
+                return { ok: false, error: refusal };
             // `head` is captured before the revert so a future caller can compare before/after.
             const head = await headOf(root, "HEAD");
-            if (!(await isMergedInto(root, full, primary)))
-                return { ok: false, error: `${shortSha(full)} is not on ${primary}` };
+            const subject = await runGit(root, ["log", "-1", "--format=%s", full]);
             // Fail-closed on any staged or unstaged change to a tracked path: we refuse to revert a
             // checkout that has one (untracked files are tolerated — the lock dir we just created is
             // one). This keeps the inverse commit free of unrelated content and, just as important,
@@ -44,25 +155,22 @@ export async function revertMergedCommit(root, ref) {
             // pre-existing work can never be lost.
             if ((await gitTry(root, "status", "--porcelain", "--untracked-files=no")) !== "")
                 return { ok: false, error: "the worktree has staged or unstaged changes; commit or stash them first, nothing was committed" };
-            if ((await gitTry(root, "revert", "--no-commit", full)) === null) {
-                // The tree was clean when the revert started, so --abort restores exactly that state.
-                await gitTry(root, "revert", "--abort");
-                return { ok: false, error: `reverting ${shortSha(full)} conflicted; nothing was committed and the checkout is unchanged` };
-            }
-            const commitMsg = stampedSubject("operator", "Revert " + shortSha(full)); // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
-            // Mirror commitOperatorBacklogEdit: `--only` with the revert's own staged paths commits
-            // just the inverse, so it cannot pick up any unrelated change of another path staged
-            // after the clean check above. `--no-renames` keeps a rename's two halves as separate
-            // path lines: the default name-only collapses a detected rename to its destination, which
-            // would commit only half and leave the other half staged with a dirty tree.
-            const pathsSpec = ((await gitTry(root, "diff", "--cached", "--name-only", "--no-renames")) ?? "")
-                .split("\n")
-                .filter((p) => p.length > 0);
-            if ((await gitTry(root, ...COMMIT_IDENT, "commit", "--only", "-m", commitMsg, "--", ...pathsSpec)) === null) {
-                await gitTry(root, "revert", "--abort");
-                return { ok: false, error: `the revert of ${shortSha(full)} did not commit; nothing was committed` };
-            }
-            return { ok: true, headSha: await headOf(root, "HEAD"), beforeSha: head };
+            const reverted = await revertCommitIn(root, full, stampedSubject("operator", "Revert " + shortSha(full))); // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
+            if (!reverted.ok)
+                return reverted;
+            // Log the operator's deliberate revert while the primary lock is held, so the inverse
+            // commit and its trail land together. Best-effort: a failed event write must never turn a
+            // successful revert into a refusal.
+            const role = revertedRole(subject);
+            logEventBestEffort(root, {
+                source: TUMWATER_SOURCE,
+                type: "operator_revert",
+                commit: full,
+                revert: reverted.sha,
+                subject,
+                ...(role === null ? {} : { runner: role }),
+            });
+            return { ok: true, headSha: await headOf(root, "HEAD"), beforeSha: head, subject };
         });
     }
     catch {

package/dist/src/orchestrator/orchestrator-launch.js

@@ -1,18 +1,17 @@
-// vocabulary: plain
 /** The orchestrator's launch pass: the half of the per-poll runner sweep that admits due
- * roles to their ticks. The decision half (isEligible, the pause/backoff/deferral gates,
+ * roles to their runs. The decision half (isEligible, the pause/backoff/deferral gates,
  * once-mode settling) stays in runOrchestrator (src/orchestrator/orchestrator.ts) — it reads
  * the poll's gate verdicts and the backlog state; this module takes its output, the
  * `reasons` map of due runners, and turns each into a reserved, semaphore-gated, in-flight
- * tick: the probe admission for the fallback breaker, the wake event, the
- * reservation/parking bookkeeping, runTimedRoleTick's wiring (slot acquisition, the start
+ * run: the probe admission for the fallback breaker, the wake event, the
+ * reservation/parking bookkeeping, runTimedRoleRun's wiring (slot acquisition, the start
  * gate, breaker evidence), and the in-flight-bucket bookkeeping the drain and the p75
  * duration sample read. Split out of orchestrator.ts — whose poll loop otherwise reads as
  * one decision after another — so the launch mechanics read as one step of that loop. The
  * shared in-flight state (buckets, permit holders, duration samples, gateStates) is passed
  * in and mutated in place, exactly as the inline version did: the drain's `finally` and the
  * redeployer read it between polls. */
-import { abandonFallbackProbeAt, recordFallbackTickAt, startFallbackProbeAt, } from "../budget/fallback-breaker.js";
+import { abandonFallbackProbeAt, recordFallbackRunAt, startFallbackProbeAt, } from "../budget/fallback-breaker.js";
 import { seamHoldKey } from "../config/config-views.js";
 import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
@@ -21,20 +20,20 @@ import { modelPairName } from "../budget/budget.js";
 import { withProviderLease } from "../concurrency/provider-lease.js";
 import { seamConcurrencyKey } from "../config/config-views.js";
 import { DIRECTOR_ROLE, roleTier } from "../roles/roles.js";
-import { runTimedRoleTick } from "../tick/tick-timing.js";
-/** How many recent work-bearing tick durations the p75 sample keeps (drainInFlightWork's
- * HANDOFF_MERGE_WINDOW_MS input): the drain window tracks recent tick pace, not all-time
+import { runTimedRoleRun } from "../run/run-timing.js";
+/** How many recent work-bearing run durations the p75 sample keeps (drainInFlightWork's
+ * HANDOFF_MERGE_WINDOW_MS input): the drain window tracks recent run pace, not all-time
  * pace, so the sample is a ring buffer. */
-export const ROLE_TICK_DURATION_SAMPLES = 50;
-/** The admission wait threshold below which a role tick's semaphore wait logs no event — a
- * tick that starts at once stays silent. Mirrors SLOT_WAIT_EVENT_MS in src/git/worktree-pool.ts:
+export const ROLE_RUN_DURATION_SAMPLES = 50;
+/** The admission wait threshold below which a role run's semaphore wait logs no event — a
+ * run that starts at once stays silent. Mirrors SLOT_WAIT_EVENT_MS in src/git/worktree-pool.ts:
  * the wait that signals maxConcurrentPerProvider (or maxConcurrent) caps the team. */
 export const PROVIDER_WAIT_EVENT_MS = 30_000;
-/** Launch one due runner's tick: reserve it, park it in the semaphore, and start it under
- * runTimedRoleTick with the breaker-evidence wiring. Returns the task promise already added
+/** Launch one due runner's run: reserve it, park it in the semaphore, and start it under
+ * runTimedRoleRun with the breaker-evidence wiring. Returns the task promise already added
  * to its in-flight bucket (its `finally` self-removes and folds the duration sample). */
-export function launchDueTicks(ctx) {
-    const { root, reasons, signal, gateStates, breakerPolicy, breakerNow, probePair, probeRoles, budgetActive, semaphore, piDefault, rolePermitHolders, roleInFlight, directorInFlight, roleTickDurationsMs, startHeld, } = ctx;
+export function launchDueRuns(ctx) {
+    const { root, reasons, signal, gateStates, breakerPolicy, breakerNow, probePair, probeRoles, budgetActive, windowMovedRoles, semaphore, piDefault, rolePermitHolders, roleInFlight, directorInFlight, roleRunDurationsMs, startHeld, } = ctx;
     let admittedProbe = false;
     for (const runner of fairOrder([...reasons.keys()])) {
         if (signal.aborted)
@@ -58,10 +57,10 @@ export function launchDueTicks(ctx) {
             logEventBestEffort(root, { source: runner.role, type: "wake", reason });
         }
         runner.state.running = true; // Reserve before the semaphore wait so we don't double-schedule.
-        // The director never queues behind role loops: a user prompt starts immediately,
+        // The director never queues behind roles: a user prompt starts immediately,
         // even when maxConcurrent slots are busy. Parked waiters keep fairOrder's tier order
-        // across polls too: a work-role arrival jumps ahead of maintenance ticks that queued
-        // in an earlier poll (in-flight ticks always run to completion).
+        // across polls too: a work-role arrival jumps ahead of maintenance runs that queued
+        // in an earlier poll (in-flight runs always finish).
         const usesSlot = runner.role !== DIRECTOR_ROLE;
         // Mark the parked waiter while it waits: it holds no permit yet, so the dashboards
         // render `awaiting slot` (an inactive state) and the active rows keep tracking
@@ -73,36 +72,44 @@ export function launchDueTicks(ctx) {
         const parkKey = runner.role === DIRECTOR_ROLE ? null : runner.runConfig(Date.now());
         runner.state.parkedSince = usesSlot ? Date.now() : undefined;
         runner.state.parkedOn = usesSlot && parkKey ? seamConcurrencyKey(parkKey, piDefault) : undefined;
-        // The tick's own run time (null when it never ran, was cut off, or ended without
-        // work): the drain-window sample is taken only for a work-bearing tick that finished
-        // on its own (runTimedRoleTick; BUGS.md 2026-09-30).
+        // The run's own duration (null when it never started, was cut off, or ended without
+        // work): the drain-window sample is taken only for a work-bearing run that finished
+        // on its own (runTimedRoleRun; BUGS.md 2026-09-30).
         let durationMs = null;
-        // Whether runner.tick() was ever called — false when the start gate (or a shutdown)
-        // turned the tick away at its permit.
+        // Whether runner.run() was ever called — false when the start gate (or a shutdown)
+        // turned the run away at its permit.
         let started = false;
-        // The tick's keyed semaphore lease (plans/provider-concurrency.md §4): acquired on the
+        // The run's keyed semaphore lease (plans/provider-concurrency.md §4): acquired on the
         // authoring seam's provider key and released in place of the bare team release, so the
-        // cap is real for role ticks from part 2/5 on. The director never queues, so its lease is
+        // cap is real for role runs from part 2/5 on. The director never queues, so its lease is
         // never created here.
         let lease = null;
         // The director's forced provider lease (plans/provider-concurrency.md §4): never queues and
-        // never counts toward maxConcurrent, but DOES count toward its provider key while its tick
+        // never counts toward maxConcurrent, but DOES count toward its provider key while its run
         // runs — so a full provider admits no further grants until the director releases.
         let directorLease = null;
         const task = (async () => {
-            durationMs = await runTimedRoleTick(signal, usesSlot
+            durationMs = await runTimedRoleRun(signal, usesSlot
                 ? async () => {
                     // The key is the authoring seam's concurrency key, computed here at admission
                     // (runConfig applies any budget or model-failure fallback already in force).
                     const cfg = runner.role === DIRECTOR_ROLE ? null : runner.runConfig(Date.now());
                     const key = cfg ? seamConcurrencyKey(cfg, piDefault) : undefined;
                     const admittedAt = Date.now();
+                    // Which cap would hold the run, read once at park time (not revised if the caps
+                    // change mid-wait): the run's own provider cap when full, else the team total.
+                    const pool = semaphore.snapshot();
+                    const keyed = key !== undefined ? pool.byKey[key] : undefined;
+                    const providerFull = keyed?.limit !== undefined && keyed.inUse >= keyed.limit;
+                    const heldBy = providerFull
+                        ? { cap: "provider", limit: keyed.limit }
+                        : { cap: "team", limit: pool.limit };
                     lease = await semaphore.acquireLease(roleTier(runner.role), key);
                     // A wait of PROVIDER_WAIT_EVENT_MS or more for the provider/team slot is
                     // provider contention worth surfacing: name it so `tumwater doctor`'s provider
                     // contention row can sum it and the operator can size maxConcurrentPerProvider
                     // (or maxConcurrent) from real waits. Best-effort like the launch pass's other
-                    // events, so an unwritable log never blocks a start; a tick admitted at once
+                    // events, so an unwritable log never blocks a start; a run admitted at once
                     // stays silent.
                     if (Date.now() - admittedAt >= (ctx.providerWaitMs ?? PROVIDER_WAIT_EVENT_MS)) {
                         logEventBestEffort(ctx.root, {
@@ -111,18 +118,19 @@ export function launchDueTicks(ctx) {
                             role: runner.role,
                             waitedMs: Date.now() - admittedAt,
                             ...(key !== undefined ? { key } : {}),
+                            ...heldBy,
                         });
                     }
-                    // Permit granted: the tick is now an active, permit-holding state until the
-                    // release below. A tick the start gate turns away releases within the same
+                    // Permit granted: the run is now an active, permit-holding state until the
+                    // release below. A run the start gate turns away releases within the same
                     // microtask chain, so no poll ever counts it as a permit holder.
                     runner.state.parkedSince = undefined;
                     runner.state.parkedOn = undefined;
                     rolePermitHolders.add(runner);
                 }
                 : async () => {
-                    // The director wraps its tick in a forced lease on its run's provider key, never
-                    // queuing behind role loops: a user prompt starts at once even on a full provider,
+                    // The director wraps its run in a forced lease on its provider key, never
+                    // queuing behind roles: a user prompt starts at once even on a full provider,
                     // and the key's in-use rises by one — overshooting by one — so no further grant on
                     // that key happens until its release drains it back under the cap.
                     const cfg = runner.runConfig(Date.now());
@@ -136,55 +144,55 @@ export function launchDueTicks(ctx) {
                     directorLease.release();
                 }, async () => {
                 started = true;
-                // A role tick that starts while the budget holds runs on the fallback pair its tier
+                // A role run that starts while the budget holds uses the fallback pair its tier
                 // resolved to (the gate's per-tier view was installed in its config), or — when a
                 // model-fallback episode is active — on the tier's model-fallback pair, which can
                 // differ from the budget pair. Its outcome is the evidence for the pair it ACTUALLY
                 // ran on, so read it from runConfig (config + episode), never from configForRole
-                // alone: a per-pair breaker fed a fallback tick under the primary's name would
+                // alone: a per-pair breaker fed a fallback run under the primary's name would
                 // misprice a healthy pair and miss a dead one (PLANS.md "Model failure fallback,
                 // part 1/2").
                 const now = Date.now();
                 const cfg = runner.role === DIRECTOR_ROLE ? null : runner.runConfig(now);
-                // The breaker is keyed by the seam that ran (seamHoldKey), like the tick pair and
+                // The breaker is keyed by the seam that ran (seamHoldKey), like the run pair and
                 // the team-hold stamps (PLANS.md "Mixed claude + pi fleets, part 2/4"): a claude
-                // fallback tick demotes the `claude/<model>` breaker entry, never `?/…`.
-                const ranPair = budgetActive && cfg?.model !== undefined
+                // fallback run demotes the `claude/<model>` breaker entry, never `?/…`.
+                const ranPair = (budgetActive || windowMovedRoles.has(runner.role)) && cfg?.model !== undefined
                     ? modelPairName({ provider: seamHoldKey(cfg), model: cfg.model })
                     : null;
                 const ranOn = ranPair !== null ? gateStates.budget.breakers[ranPair] : undefined;
-                // The tick's lease rides in the provider-lease store for the length of the tick, so
-                // every run it makes re-keys it to the provider that run actually uses
-                // (plans/provider-concurrency.md §5) — a budget or model-failure switch that moves a
-                // mid-tick run to another provider moves the lease with it. The director's forced
+                // The run's lease rides in the provider-lease store for the length of the run, so
+                // every agent run it makes re-keys it to the provider that agent run actually uses
+                // (plans/provider-concurrency.md §5) — a budget or model-failure switch that moves an
+                // agent run to another provider mid-run moves the lease with it. The director's forced
                 // lease re-keys the same way, and its rekey never waits.
-                const outcome = await withProviderLease(runner.role === DIRECTOR_ROLE ? directorLease : lease, semaphore, () => runner.tick(), { piDefault });
+                const outcome = await withProviderLease(runner.role === DIRECTOR_ROLE ? directorLease : lease, semaphore, () => runner.run(), { piDefault });
                 if (ranPair !== null && ranOn !== undefined) {
                     const at = breakerNow();
                     const evidence = outcome.recoveredLeftover ? "skipped" : outcome.result;
-                    gateStates.budget.breakers = recordFallbackTickAt(gateStates.budget.breakers, ranPair, ranOn, evidence, probe, at, breakerPolicy);
+                    gateStates.budget.breakers = recordFallbackRunAt(gateStates.budget.breakers, ranPair, ranOn, evidence, probe, at, breakerPolicy);
                 }
                 else if (probe && probePair !== null) {
-                    // A probe whose tick started on no engaged pair — the budget gate reopened
+                    // A probe whose run started on no engaged pair — the budget gate reopened
                     // between admission and start (the cap raised, or midnight reset spend) — folds
                     // no evidence, so its claim would hang on the pair's entry forever: probing
                     // blocks both fallbackProbeDuePair and startFallbackProbeAt, and nothing but a
                     // rekey clears it, so the demoted fallback could never earn another probe. Hand
-                    // the claim back exactly as the !started path below does for a tick turned away
+                    // the claim back exactly as the !started path below does for a run turned away
                     // at its permit.
                     gateStates.budget.breakers = abandonFallbackProbeAt(gateStates.budget.breakers, probePair);
                 }
                 return outcome;
             }, Date.now, 
-            // The restart start gate, plus the failure hold for role ticks (the director is
+            // The restart start gate, plus the failure hold for role runs (the director is
             // exempt, as at scheduling): a waiter granted its permit mid-storm must not start
             // into it.
             () => startHeld(runner.role));
-            // A reservation whose tick never started hands itself back, so the role re-schedules
+            // A reservation whose run never started hands itself back, so the role re-schedules
             // once the hold lifts (or on the new build) instead of sitting `running` forever with
             // nothing in flight. Memory only, on purpose: nothing started, so no state write and
             // no run_start/run_end — the persisted state still reads exactly as the last real
-            // tick left it, and the next generation schedules the role from that.
+            // run left it, and the next generation schedules the role from that.
             if (!started)
                 runner.state.running = false;
             // A probe turned away the same way answered nothing: hand its claim back (see
@@ -194,7 +202,7 @@ export function launchDueTicks(ctx) {
         })();
         const bucket = runner.role === DIRECTOR_ROLE ? directorInFlight : roleInFlight;
         bucket.add(task);
-        // A LoopRunner.tick folds every failure it handles into an `error` outcome, so this task
+        // A RoleRunner.run folds every failure it handles into an `error` outcome, so this task
         // should resolve. A throw outside that fold (a finalize-time file write, a runner bug)
         // rejects it instead; the drain awaits the bucket with allSettled, but chaining cleanup
         // off a bare `void task.finally(...)` would leave the derived promise's rejection
@@ -210,9 +218,9 @@ export function launchDueTicks(ctx) {
             .finally(() => {
             bucket.delete(task);
             if (bucket === roleInFlight && durationMs !== null) {
-                roleTickDurationsMs.push(durationMs);
-                if (roleTickDurationsMs.length > ROLE_TICK_DURATION_SAMPLES)
-                    roleTickDurationsMs.shift();
+                roleRunDurationsMs.push(durationMs);
+                if (roleRunDurationsMs.length > ROLE_RUN_DURATION_SAMPLES)
+                    roleRunDurationsMs.shift();
             }
         });
     }