tumwater 0.1.2 → 0.2.0

package/dist/src/operator/retire.js

@@ -1,14 +1,32 @@
+// vocabulary: plain
 import fs from "node:fs";
 import { loadConfigSafe } from "../config/config.js";
+import { CUSTOM_NAME_RE } from "../config/config-schema.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { loopEnabled } from "../roles/loop-ids.js";
-import { branchExists, currentBranch, deleteRef, isDirty, isMergedInto, refSha, targetBranch, } from "../git/git.js";
+import { branchExists, countCommitsInRange, currentBranch, deleteRef, isDirty, isMergedInto, refSha, targetBranch, } from "../git/git.js";
 import { errorMessage } from "../text/text.js";
 import { loadLoopState } from "../loop/loop-state.js";
-import { branchName, landingRefName, worktreePath } from "../paths.js";
+import { branchName, mergeRefName, legacyLandingRefName, worktreePath } from "../paths.js";
 import { isUsableWorktree, removeWorktree } from "../git/worktree.js";
 import { roleWorktreeDir, slotForDir, updateSlotsState } from "../git/slots-state.js";
-import { resumeRole } from "../fleet/fleet-state.js";
+import { pausedRoles, resumeRole } from "../team/team-state.js";
 import { git } from "../git/git-run.js";
+/** `tumwater retire --role <id>`: remove a disabled loop's persistent worktree and branch, plus the
+ * per-role merge ref and paused-state marker that outlive it. The safety rails and the `--force`
+ * override live here, so the CLI layer (operator/operator-commands.ts) stays a thin renderer. */
+/** The role's merge pin, falling back to the legacy-named one a not-yet-migrated repo holds. */
+async function mergeRefSha(root, role) {
+    return (await refSha(root, mergeRefName(role))) ?? (await refSha(root, legacyLandingRefName(role)));
+}
+/** The id gate for ids no config names (a lowered `instances`, a removed custom role): the id is
+ * well-formed (CUSTOM_NAME_RE keeps `..` and `/` out of the paths retire builds), is not the
+ * director, and still has its branch or merge ref. Read-only. */
+export async function hasRetirableLeftovers(root, role) {
+    if (!CUSTOM_NAME_RE.test(role) || role === DIRECTOR_ROLE)
+        return false;
+    return (await branchExists(root, branchName(role))) || (await mergeRefSha(root, role)) !== null;
+}
 /** Collect what exists today for `role`, with every probe tolerant of partial state — a retired
  * role's leftovers are exactly the messy half-state this command exists to clean up. */
 export async function collectRetire(root, role) {
@@ -25,51 +43,51 @@ export async function collectRetire(root, role) {
         throw new Error(`cannot read tumwater.json: ${errorMessage(config.error)}`);
     }
     const mainBranch = targetBranch(config.config.baseBranch, await currentBranch(root));
-    // Count unlanded work from the branch ref at root, not from the worktree's HEAD: the worktree
-    // may be gone or unusable (the messy half-state this command exists to clean up) while the
-    // branch still holds commits — reading HEAD through the worktree would report 0 and let
-    // retireRole's `branch -D` delete unlanded work without objection. When the branch is
-    // absent, or a usable worktree sits on it, the rev-list range is empty or matches HEAD.
+    // Count unmerged work from the branch ref at root, not from the worktree's HEAD: the worktree may
+    // be gone or unusable (the messy half-state this command exists to clean up) while the branch
+    // still holds commits — reading HEAD through the worktree would report 0 and let retireRole's
+    // `branch -D` delete unmerged work without objection. When the branch is absent, or a usable
+    // worktree sits on it, the rev-list range is empty or matches HEAD.
     const branch = branchName(role);
     const branchThere = await branchExists(root, branch);
     const ahead = branchThere
-        ? Number.parseInt(await git(root, "rev-list", "--count", `${mainBranch}..${branch}`), 10)
+        ? await countCommitsInRange(root, `${mainBranch}..${branch}`)
         : 0;
     const dirty = usable && wt !== null ? await isDirty(wt) : false;
-    const landing = await refSha(root, landingRefName(role));
-    // A landing ref pins a committed-but-unlanded sha (plans/merge-queue.md invariant 4): count
-    // it as unlanded work too — the branch can sit at main while the pin holds the crash survivor.
-    const pinnedUnlanded = landing !== null && !(await isMergedInto(root, landing, mainBranch)) ? 1 : 0;
+    const mergeRef = await mergeRefSha(root, role);
+    // A merge ref pins a committed-but-unmerged sha (plans/merge-queue.md invariant 4): count it as
+    // unmerged work too — the branch can sit at main while the pin holds the crash survivor.
+    const pinnedUnmerged = mergeRef !== null && !(await isMergedInto(root, mergeRef, mainBranch)) ? 1 : 0;
     return {
         role,
         worktreePresent: present,
         worktreeUsable: usable,
         branchPresent: branchThere,
-        landingRefPresent: landing !== null,
-        aheadOfMain: ahead + pinnedUnlanded,
+        mergeRefPresent: mergeRef !== null,
+        aheadOfMain: ahead + pinnedUnmerged,
         dirty,
         enabledInConfig: loopEnabled(config.config, role),
-        midTick: loadLoopState(root, role).running === true,
+        midRun: loadLoopState(root, role).running === true,
     };
 }
 /** The artifacts retire manages, in removal order. */
-const ARTIFACTS = ["worktree", "branch", "landingRef", "pausedMarker"];
+const ARTIFACTS = ["worktree", "branch", "mergeRef", "pausedMarker"];
 /** The safety rails: each returns a one-line objection, or null when the state is clean. */
 function objections(status) {
     const reasons = [];
     if (status.enabledInConfig)
         reasons.push(`role ${status.role} is still enabled in tumwater.json — disable it first`);
     if (status.aheadOfMain > 0)
-        reasons.push(`branch ${branchName(status.role)} holds ${status.aheadOfMain} unlanded commit(s) — land or discard them first`);
+        reasons.push(`branch ${branchName(status.role)} holds ${status.aheadOfMain} unmerged commit(s) — merge or discard them first`);
     if (status.worktreePresent && !status.worktreeUsable)
         reasons.push("the worktree is unusable and cannot be checked for uncommitted changes — remove it manually or use --force");
     if (status.dirty)
         reasons.push("the worktree has uncommitted changes");
-    if (status.midTick)
-        reasons.push("a tick is in flight for this loop");
+    if (status.midRun)
+        reasons.push("a run is in progress for this role");
     return reasons;
 }
-/** Remove the role's worktree, branch, landing ref, and paused-state marker. Refuses — removing
+/** Remove the role's worktree, branch, merge ref, and paused-state marker. Refuses — removing
  * nothing — when any safety rail objects, unless `force` overrides every objection. */
 export async function retireRole(root, role, { force }) {
     const status = await collectRetire(root, role);
@@ -117,15 +135,32 @@ export async function retireRole(root, role, { force }) {
     }
     else
         mark("branch", false);
-    if (status.landingRefPresent) {
-        await deleteRef(root, landingRefName(status.role));
-        mark("landingRef", true);
+    if (status.mergeRefPresent) {
+        await deleteRef(root, mergeRefName(status.role));
+        await deleteRef(root, legacyLandingRefName(status.role)); // a team stopped before its first start here
+        mark("mergeRef", true);
     }
     else
-        mark("landingRef", false);
+        mark("mergeRef", false);
     mark("pausedMarker", resumeRole(root, status.role));
     return { status, removed, skipped };
 }
+/** Preview `retireRole` without touching the worktree, refs, slot state, or paused marker. */
+export async function previewRetire(root, role) {
+    const status = await collectRetire(root, role);
+    const there = {
+        worktree: status.worktreePresent,
+        branch: status.branchPresent,
+        mergeRef: status.mergeRefPresent,
+        pausedMarker: pausedRoles(root).includes(role),
+    };
+    return {
+        status,
+        wouldRemove: ARTIFACTS.filter((a) => there[a]),
+        skipped: ARTIFACTS.filter((a) => !there[a]),
+        objections: objections(status),
+    };
+}
 /** The one-line human description of an artifact name, for the CLI renderer. */
 export function artifactPhrase(name, role) {
     switch (name) {
@@ -135,8 +170,8 @@ export function artifactPhrase(name, role) {
             return `the worktree`;
         case "branch":
             return `the branch (${branchName(role)})`;
-        case "landingRef":
-            return `the landing ref (${landingRefName(role)})`;
+        case "mergeRef":
+            return `the merge ref (${mergeRefName(role)})`;
         case "pausedMarker":
             return `the paused-state marker`;
         default:

package/dist/src/operator/revert.js

@@ -0,0 +1,71 @@
+// vocabulary: plain
+import { loadConfigSafe } from "../config/config.js";
+import { withStateLockAsync } 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 { shortSha } from "../text/format.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
+ * inverse commit lands under the primary-worktree lock so it cannot interleave with a
+ * 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. */
+/** 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
+ * before the revert so a future caller can compare; the resolved full sha is what the commit
+ * message shortens. */
+export async function revertMergedCommit(root, ref) {
+    try {
+        // Yield first: a synchronous caller (the TUI key handler) may write again right after this
+        // 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}` };
+            // `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}` };
+            // 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,
+            // makes `git revert --abort` below safe to run after a conflict — with nothing dirty in
+            // the index or tree there is nothing for its hard reset to discard, so the operand's
+            // 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 };
+        });
+    }
+    catch {
+        return { ok: false, error: "the revert did not complete (git failed); nothing was committed" };
+    }
+}

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

@@ -1,3 +1,4 @@
+// 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,
  * once-mode settling) stays in runOrchestrator (src/orchestrator/orchestrator.ts) — it reads
@@ -12,21 +13,28 @@
  * 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 { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { seamHoldKey } from "../config/config-views.js";
+import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { fairOrder } from "../scheduling/scheduling.js";
 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_LANDING_WINDOW_MS input): the drain window tracks recent tick pace, not all-time
+ * HANDOFF_MERGE_WINDOW_MS input): the drain window tracks recent tick 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:
+ * 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
  * 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, rolePermitHolders, roleInFlight, directorInFlight, roleTickDurationsMs, startHeld, } = ctx;
+    const { root, reasons, signal, gateStates, breakerPolicy, breakerNow, probePair, probeRoles, budgetActive, semaphore, piDefault, rolePermitHolders, roleInFlight, directorInFlight, roleTickDurationsMs, startHeld, } = ctx;
     let admittedProbe = false;
     for (const runner of fairOrder([...reasons.keys()])) {
         if (signal.aborted)
@@ -47,7 +55,7 @@ export function launchDueTicks(ctx) {
         }
         const reason = reasons.get(runner);
         if (reason && reason !== "scheduled" && reason !== "startup") {
-            logEventBestEffort(root, { loop: runner.role, type: "wake", reason });
+            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,
@@ -58,8 +66,13 @@ export function launchDueTicks(ctx) {
         // 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
         // maxConcurrent (BUGS.md 2026-09-24). Cleared the moment the permit is granted. The
-        // director never queues, so it is never a parked waiter.
+        // director never queues, so it is never a parked waiter. Its provider key rides beside
+        // `parkedSince` (provider-concurrency part 5/5): the key the admission lease will
+        // acquire, computed from the same runConfig admission uses, so a waiter named by a
+        // full key renders `awaiting <key> slot` on the dashboards.
+        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).
@@ -67,22 +80,61 @@ export function launchDueTicks(ctx) {
         // Whether runner.tick() was ever called — false when the start gate (or a shutdown)
         // turned the tick away at its permit.
         let started = false;
+        // The tick'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
+        // 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
+        // runs — so a full provider admits no further grants until the director releases.
+        let directorLease = null;
         const task = (async () => {
             durationMs = await runTimedRoleTick(signal, usesSlot
                 ? async () => {
-                    await semaphore.acquire(roleTier(runner.role));
+                    // 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();
+                    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
+                    // stays silent.
+                    if (Date.now() - admittedAt >= (ctx.providerWaitMs ?? PROVIDER_WAIT_EVENT_MS)) {
+                        logEventBestEffort(ctx.root, {
+                            source: TUMWATER_SOURCE,
+                            type: "provider_wait",
+                            role: runner.role,
+                            waitedMs: Date.now() - admittedAt,
+                            ...(key !== undefined ? { key } : {}),
+                        });
+                    }
                     // 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
                     // microtask chain, so no poll ever counts it as a permit holder.
                     runner.state.parkedSince = undefined;
+                    runner.state.parkedOn = undefined;
                     rolePermitHolders.add(runner);
                 }
-                : async () => { }, usesSlot
+                : 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,
+                    // 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());
+                    directorLease = semaphore.forceLease(cfg ? seamConcurrencyKey(cfg, piDefault) : undefined);
+                }, usesSlot
                 ? () => {
                     rolePermitHolders.delete(runner);
-                    semaphore.release();
+                    lease.release();
                 }
-                : () => { }, async () => {
+                : () => {
+                    directorLease.release();
+                }, async () => {
                 started = true;
                 // A role tick that starts while the budget holds runs on the fallback pair its tier
                 // resolved to (the gate's per-tier view was installed in its config), or — when a
@@ -94,11 +146,19 @@ export function launchDueTicks(ctx) {
                 // 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 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
-                    ? modelPairName({ provider: cfg.provider, model: cfg.model })
+                    ? modelPairName({ provider: seamHoldKey(cfg), model: cfg.model })
                     : null;
                 const ranOn = ranPair !== null ? gateStates.budget.breakers[ranPair] : undefined;
-                const outcome = await runner.tick();
+                // 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
+                // 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 });
                 if (ranPair !== null && ranOn !== undefined) {
                     const at = breakerNow();
                     const evidence = outcome.recoveredLeftover ? "skipped" : outcome.result;
@@ -123,7 +183,7 @@ export function launchDueTicks(ctx) {
             // A reservation whose tick 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 tick_start/tick_end — the persisted state still reads exactly as the last real
+            // 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.
             if (!started)
                 runner.state.running = false;
@@ -138,14 +198,14 @@ export function launchDueTicks(ctx) {
         // 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
-        // unhandled and take the whole fleet down. Surface it as a warning (warnEventBestEffort,
+        // unhandled and take the whole team down. Surface it as a warning (warnEventBestEffort,
         // which keeps a failed warning write from becoming that unhandled rejection) and hand the
         // reservation back so the role can schedule again, exactly as the unstarted path above
         // does; the drain's allSettled is otherwise silent about the failure.
         void task
             .catch((err) => {
             runner.state.running = false;
-            warnEventBestEffort(root, runner.role, `tick task rejected: ${errorMessage(err)}`);
+            warnEventBestEffort(root, runner.role, `run task rejected: ${errorMessage(err)}`);
         })
             .finally(() => {
             bucket.delete(task);