tumwater 0.1.2 → 0.2.0

package/dist/src/orchestrator/orchestrator.js

@@ -1,42 +1,49 @@
-import { assignInfoFieldIfChanged, writeOrchestratorInfo, writeOrchestratorInfoBestEffort } from "../fleet/orchestrator-info.js";
+import { publishInfoFields, writeOrchestratorInfo } from "../team/orchestrator-info.js";
 import { loopEnabled, loopIds } from "../roles/loop-ids.js";
 import { newLiveConfigReload } from "../config/config-live.js";
 import { FALLBACK_BREAKER_POLICY, fallbackProbeDuePair, } from "../budget/fallback-breaker.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { modelPairName } from "../budget/budget.js";
-import { roleSeamTier, reviewRunConfig, seamHoldKey } from "../config/config-views.js";
+import { roleSeamTier, seamConcurrencyKey } from "../config/config-views.js";
 import { launchDueTicks } from "./orchestrator-launch.js";
-import { pollRunnerReasons } from "./orchestrator-scheduling.js";
-import { openBugs, plannedPlans } from "../backlog/backlog.js";
+import { pollRunnerReasons, reviewHoldKey } from "./orchestrator-scheduling.js";
+import { openBugs } from "../backlog/backlog.js";
+import { eligibleEntries } from "../backlog/backlog-eligibility.js";
 import { LoopRunner } from "../loop/loop.js";
 import { branchHead, currentBranch } from "../git/git.js";
 import { removeLegacyLandWorktrees } from "../git/worktree.js";
 import { retireLegacyRoleWorktrees } from "../git/worktree-pool.js";
-import { queuedLandingFiles, queuedLandingRoles } from "../landing/landing-queue.js";
-import { drainLandings, settleAbortedVetted } from "../landing/landing-drain.js";
-import { abortableLandings, landingTasks, newLandingPipeline } from "../landing/landing-pipeline.js";
-import { bestEffortEventLogger, logEventBestEffort } from "../events/events.js";
+import { queuedMergeFiles, queuedMergeRoles } from "../merge/merge-queue.js";
+import { drainMergeQueue, settleAbortedApproved } from "../merge/merge-drain.js";
+import { abortableMerges, mergeTasks, newMergePipeline } from "../merge/merge-pipeline.js";
+import { bestEffortEventLogger, logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { removeQuiet } from "../files/files.js";
 import { OnceRound } from "../scheduling/once-round.js";
 import { newNotifier } from "../events/notify.js";
 import { consumeAbortRequests, consumeReclaimRequest, consumeRestartRequest, consumeResetRequest, consumeWakeRequest, } from "../operator/operator-requests.js";
 import { piModelsPath } from "../pi/pi-models.js";
+import { piSettingsPath, readPiDefaultModel } from "../pi/pi-settings.js";
 import { Semaphore } from "../concurrency/semaphore.js";
 import { orchestratorStatePath } from "../paths.js";
 import { RetentionPruner } from "./retention.js";
-import { WorkLandedCache } from "../scheduling/work-landed-cache.js";
-import { drainInFlightWork, HANDOFF_LANDING_WINDOW_MS, p75TickDurationMs, sleepInterruptible, } from "../tick/tick-timing.js";
-import { newFleetGateStates, pollFleetGates } from "../gates/gate-polls.js";
-import { ReclaimController } from "../fleet/reclaim.js";
-import { heldProviders } from "../fleet/fleet-hold.js";
-import { workReserveCount } from "../scheduling/claims.js";
+import { WorkMergedCache } from "../scheduling/work-merged-cache.js";
+import { drainInFlightWork, HANDOFF_MERGE_WINDOW_MS, p75TickDurationMs, sleepInterruptible, } from "../tick/tick-timing.js";
+import { newTeamGateStates, pollTeamGates } from "../gates/gate-polls.js";
+import { ReclaimController } from "../team/reclaim.js";
+import { heldProviders, windowHeldProviders } from "../team/team-hold.js";
+import { planBacklogFull, workReserveCount } from "../scheduling/claims.js";
+import { runStartupMigrations } from "./startup-migration-steps.js";
+import { archiveAtTeamStart } from "../backlog/backlog-archive.js";
 const POLL_MS = 2000;
 /** Run all enabled loops until the signal aborts — or until a pending self-redeploy has drained
- * the fleet and swapped the new build into dist/ (then `restart` is true). */
+ * the team and swapped the new build into dist/ (then `restart` is true). */
 export async function runOrchestrator(opts) {
     const { root, config, mainBranch, signal: externalSignal } = opts;
     const pollMs = opts.pollMs ?? POLL_MS;
     const modelsPath = opts.modelsPath ?? piModelsPath();
+    // pi's saved default model — the same stat-cached read status-roles.ts makes — used as the
+    // fallback provider key for a pi seam that names no model (plans/provider-concurrency.md §2).
+    const piDefault = readPiDefaultModel(piSettingsPath(modelsPath), root);
     const breakerPolicy = opts.fallbackBreakerPolicy ?? FALLBACK_BREAKER_POLICY;
     const breakerNow = opts.breakerNow ?? Date.now;
     // Parallel work instances (part 5b/7): the runner list is every loop id the config enables
@@ -51,15 +58,15 @@ export async function runOrchestrator(opts) {
         throw new Error('no roles enabled in tumwater.json — enable at least one role in its "roles" section (e.g. `"feature": { "enabled": true }`), or remove that section to restore every role\'s default');
     // Two internal stop controllers ride beside the caller's (Ctrl+C/SIGTERM): internalStop, the
     // graceful shutdown the once-mode exit and the hand-off's deadline abort fire — it cuts role
-    // ticks and landings alike — and internalRoleStop, which ONLY the restart drain fires when it
+    // ticks and merges alike — and internalRoleStop, which ONLY the restart drain fires when it
     // gives up on its permit-holding ROLE ticks (they then end as `aborted`, resumable on the new
     // build, exactly like a shutdown). The split is the point: the drain's abort must not cut off
-    // an in-flight landing, which then never reaches the hand-off window the wait announces
-    // (BUGS.md 2026-09-30: the landing died 13 ms after the warning). So the runners and the timed
-    // tick wrapper watch roleSignal — the full signal PLUS the role-only stop — while the landing
+    // an in-flight merge, which then never reaches the hand-off window the wait announces
+    // (BUGS.md 2026-09-30: the merge died 13 ms after the warning). So the runners and the timed
+    // tick wrapper watch roleSignal — the full signal PLUS the role-only stop — while the merge
     // tasks keep wiring the full signal alone. A director tick is never aborted by either
-    // controller: poll holds for it without a cap, so by the time `restart` lands only role ticks
-    // and the landing can remain.
+    // controller: poll holds for it without a cap, so by the time `restart` takes effect only
+    // role ticks and the merge can remain.
     const internalStop = new AbortController();
     const internalRoleStop = new AbortController();
     const signal = AbortSignal.any([externalSignal, internalStop.signal]);
@@ -71,34 +78,49 @@ export async function runOrchestrator(opts) {
     const launchServicesWatch = opts.once ? null : (opts.launchServicesWatch ?? null);
     // Pressure reclaim (plans/disk-floor.md, part 2/4): one background pass at a time, driven by
     // the disk gate's poll below. In-process state (the use registry) is enough, because this
-    // process is the one that runs ticks and landings.
+    // process is the one that runs ticks and merges.
     const reclaim = new ReclaimController(root);
     let restart = false;
-    const runners = enabled.map((role) => new LoopRunner(root, role, config, mainBranch, roleSignal));
-    // The shared concurrency cap: role ticks and the landings (each vet, and the merge's conflict
-    // resolver — landing-drain.ts) all hold a permit; see its LandingPipelineContext for why a
-    // landing is not exempt.
+    // The shared concurrency cap: role ticks and the merges (each verify, and the merge's conflict
+    // resolver — merge-drain.ts) all hold a permit; see its MergePipelineContext for why a
+    // merge is not exempt.
     const semaphore = new Semaphore(Math.max(1, config.maxConcurrent));
+    // Seed the pool's per-provider caps from the startup config (plans/provider-concurrency.md
+    // §7): a role tick's lease is bounded by its provider key from the first launch onward, not
+    // just after a live edit. A config without the key passes an empty map, the no-change case.
+    semaphore.setKeyCaps(config.maxConcurrentPerProvider ?? {});
     const infoFile = orchestratorStatePath(root);
     const info = { pid: process.pid, startedAt: Date.now(), roles: enabled };
     if (redeploy)
         info.build = redeploy.status();
+    if (opts.stopsAt !== undefined)
+        info.stopsAt = opts.stopsAt;
     writeOrchestratorInfo(root, info);
     // Best-effort, like every other event write in this function (see `emit` below): this runs
     // BEFORE the try/finally and its cleanup, so a raw logEvent throw here would not just stop
-    // the fleet from starting over an informational event — it would also skip the finally that
+    // the team from starting over an informational event — it would also skip the finally that
     // disposes the notifier and removes the info file just written. An unwritable feed
-    // (ENOSPC, EACCES, the path replaced by a directory) must not turn a fleet that can run
+    // (ENOSPC, EACCES, the path replaced by a directory) must not turn a team that can run
     // into one that refuses to start; logEventBestEffort reports the write failure on stderr so
     // it stays visible, and startup proceeds to the poll loop, which is already best-effort.
     logEventBestEffort(root, {
-        loop: "harness",
+        source: TUMWATER_SOURCE,
         type: "orchestrator_start",
         pid: process.pid,
         roles: enabled,
         ...(redeploy ? { build: redeploy.build.sha } : {}),
     });
-    // Legacy lander checkouts (`_land-<role>`) from a pre-pool build hold nothing now that vets
+    // The first per-runner state read is each LoopRunner constructor's loadLoopState, so the
+    // persisted-name migrations run before it. (After the info write and start event above, which
+    // an in-process test or a second `tumwater run` probe reads synchronously.)
+    await runStartupMigrations(root);
+    // Finished backlog entries still in the live files move to the archives now
+    // (plans/backlog-archive.md), while no merge is in progress and no run is in flight: a
+    // repository migrates on its first start with this build, and an entry a hand commit moved is
+    // swept. One commit on main, or a warning; the team starts either way.
+    await archiveAtTeamStart(root);
+    const runners = enabled.map((role) => new LoopRunner(root, role, config, mainBranch, roleSignal));
+    // Legacy merger checkouts (`_land-<role>`) from a pre-pool build hold nothing now that verifies
     // and merges lease pooled slots: remove them once, before any tick, so the retired layout
     // never lingers on disk. (After the info write and start event above, so startup's published
     // state is on disk synchronously for an in-process test or a second `tumwater run` probe.)
@@ -107,64 +129,64 @@ export async function runOrchestrator(opts) {
     // window, right after the LoopRunners above: a role with a pending resume keeps its dir as a
     // pinned slot, every other legacy dir goes. Pass every configured loop id, not `enabled` (a
     // `--once --role` filter): a scoped run must not retire or unpin the other roles, whose
-    // pending resumes the next full-fleet start still owns. See retireLegacyRoleWorktrees.
+    // pending resumes the next full-team start still owns. See retireLegacyRoleWorktrees.
     await retireLegacyRoleWorktrees(root, loopIds(config));
     // Session retention (src/orchestrator/retention.ts owns the whole concern): construction runs the
-    // startup prune, seeding the once-per-day gate so an unchanged fleet prunes at most once
+    // startup prune, seeding the once-per-day gate so an unchanged team prunes at most once
     // per day — and 0 disables pruning, the same convention as quietTimeoutSeconds.
     const retentionPruner = new RetentionPruner(root, config.sessionRetentionDays);
     // In-flight tasks, split by who requested them: the redeploy drain caps role ticks at its
     // window but waits for a director tick without one — an explicit human prompt outranks the
-    // self-redeploy (BUGS.md 2026-09-08). The landing tasks are deliberately OUTSIDE this split:
-    // in-process tasks (the vets and the one merge, since 2026-09-18 under the same maxConcurrent
+    // self-redeploy (BUGS.md 2026-09-08). The merge tasks are deliberately OUTSIDE this split:
+    // in-process tasks (the verifies and the one merge, since 2026-09-18 under the same maxConcurrent
     // permits as role ticks) that shutdown still awaits — to the end on an operator stop, and for a
-    // bounded hand-off on a restart (drainInFlightWork) — an aborted landing keeps its ref and
+    // bounded hand-off on a restart (drainInFlightWork) — an aborted merge keeps its ref and
     // drops its entry, recovering on next start. roleInFlight holds every RESERVED role tick
     // (permit holders and waiters parked in the semaphore queue alike), since shutdown awaits
     // both; what the restart drain waits on, aborts, and reports as abortedTicks is only
     // rolePermitHolders, the role ticks actually holding a permit. A parked waiter has nothing to
     // drain — the start gate (tickStartHeld below) keeps it from starting while a restart is
     // pending — and counting it held drains open for ticks that had not begun and inflated
-    // abortedTicks (12 reported against 3 aborted tick_ends on 2026-09-21; BUGS.md 2026-09-23).
+    // abortedTicks (12 reported against 3 aborted run_ends on 2026-09-21; BUGS.md 2026-09-23).
     const roleInFlight = new Set();
     const rolePermitHolders = new Set();
     const directorInFlight = new Set();
-    // The restart drain's window tracks the fleet's real tick duration (BUGS.md 2026-09-18): the
+    // The restart drain's window tracks the team's real tick duration (BUGS.md 2026-09-18): the
     // durations of recent COMPLETED role ticks feed a p75 that poll uses in place of the
     // cold-start constant. Bounded (orchestrator-launch.ts's ROLE_TICK_DURATION_SAMPLES) so a
-    // long-running fleet's memory stays flat; aborted ticks are
+    // long-running team's memory stays flat; aborted ticks are
     // excluded — their short cut-off durations would drag the window down and cause more aborts.
     const roleTickDurationsMs = [];
-    // Every landing task (landing-drain.ts's LandingPipeline): the vetting stage's tasks, the
-    // changes they vetted, and the merge slot.
-    const landings = newLandingPipeline();
+    // Every merge task (merge-drain.ts's MergePipeline): the verification stage's tasks, the
+    // changes they approved, and the merge slot.
+    const merges = newMergePipeline();
     // Once-mode bookkeeping (`tumwater run --once`) — the tick-count snapshot, the per-role
     // settle reasons, and the quiet-poll exit rule — lives in src/scheduling/once-round.ts.
     const once = new OnceRound(runners, opts.once === true);
-    // The fleet-wide gates' and alarms' cross-poll memory (src/gates/gate-polls.ts owns the family's
+    // The team-wide gates' and alarms' cross-poll memory (src/gates/gate-polls.ts owns the family's
     // wiring — budget, pause, quiet hours, failure hold, and the two storm alarms): the gates'
     // previous values for the edge-triggered events, the fallback breaker, and the hold's own
     // memory (deadline, kind, relapse count). In memory only — a restart re-trusts the
     // fallback, starts with the hold open, and can re-log at most one event per gate. The
     // budget gate's breaker is also the fallback ticks' evidence sink: the start pass below
     // records every tick's outcome into it and runs its probe (src/budget/fallback-breaker.ts), and
-    // the start gate reads gateStates.fleetHold at permit time, so its closures always see
+    // the start gate reads gateStates.teamHold at permit time, so its closures always see
     // the latest poll's hold verdict rather than the poll that created them.
-    const gateStates = newFleetGateStates(config);
+    const gateStates = newTeamGateStates(config);
     // The live config the last successful reload produced (last-known-good while the file is
     // broken or missing). The reload bookkeeping itself lives in src/config/config-live.ts.
     const liveReload = newLiveConfigReload({ root, config, mainBranch, runnerSignal: roleSignal, runners, semaphore, roleFilter: opts.roleFilter });
     // The pause gates (src/gates/pause-gates.ts owns the concern): the operator pause's and the
     // per-role pause's cross-poll bookkeeping, so each pause/resume crossing logs exactly one
     // event instead of once per ~2s poll.
-    // The primary checkout's branch, for the edge-triggered divergence warning: the fleet
+    // The primary checkout's branch, for the edge-triggered divergence warning: the team
     // resolved its target branch at startup, and a human checking out something else mid-run
-    // must not silently change what the fleet merges into — every role worktree is based on
+    // must not silently change what the team merges into — every role worktree is based on
     // the resolved branch. One warning per episode, re-armed when the checkout returns.
     let warnedBranchDivergence = false;
-    // Need-based deferral: whether qualifying work has landed
-    // since a role's last-seen main head, cached per head (see scheduling/work-landed-cache.ts).
-    const workLandedSince = new WorkLandedCache(root, mainBranch);
+    // Need-based deferral: whether qualifying work has merged
+    // since a role's last-seen main head, cached per head (see scheduling/work-merged-cache.ts).
+    const workMergedSince = new WorkMergedCache(root, mainBranch);
     // Per-role deferred-due state for one-shot tick_deferred events: the previous poll's
     // deferral per role (like prevBudgetPaused/prevUserPaused, but per role), so each episode
     // logs exactly once — on the transition in, never while merely not-due and never on exit.
@@ -176,21 +198,21 @@ export async function runOrchestrator(opts) {
     let holdForRestart = false;
     // Whether the last poll's disk gate held new work (plans/disk-floor.md, part 1/4). Hoisted
     // beside holdForRestart because tickStartHeld reads it at permit time, between polls — the
-    // disk hold closes the same gate point every fleet-wide hold uses.
+    // disk hold closes the same gate point every team-wide hold uses.
     let diskHeld = false;
     // The start gate every reserved tick passes the moment its permit is granted
     // (runTimedRoleTick's `held`): closed while a restart is pending, and after one is decided so
     // no waiter the shutdown hands a permit to starts on the build being replaced. One predicate,
-    // so another fleet-wide hold on new ticks can close the same gate point.
+    // so another team-wide hold on new ticks can close the same gate point.
     const tickStartHeld = () => holdForRestart || restart || diskHeld;
     // The operator notify hook (src/events/notify.ts owns the whole concern): one configured shell
-    // command run on notable events (budget_paused, role_streak_paused, land_failed,
+    // command run on notable events (budget_paused, role_streak_paused, merge_failed,
     // restart_blocked). Subscribed here so it sees every event this process logs from start;
     // disposed beside the orchestrator_stop event below.
     const notifier = newNotifier(root);
     // Best-effort event logging in the poll loop (bestEffortEventLogger, events.ts): this loop
     // and its finally run with no catch, so an unwritable feed (ENOSPC, EACCES, the path replaced
-    // by a directory) must not end the fleet — and, in the finally, must not skip the
+    // by a directory) must not end the team — and, in the finally, must not skip the
     // notifier/quiet-file cleanup or mask an in-flight error. The feed is the failure; the poll
     // and the shutdown still run.
     const { emit, warn } = bestEffortEventLogger(root);
@@ -222,37 +244,37 @@ export async function runOrchestrator(opts) {
             consumeWakeRequest(root, runners);
             consumeRestartRequest(root, redeploy);
             consumeReclaimRequest(root, reclaim);
-            consumeAbortRequests(root, runners, abortableLandings(landings));
-            await settleAbortedVetted(root, landings);
+            consumeAbortRequests(root, runners, abortableMerges(merges));
+            await settleAbortedApproved(root, merges);
             // branchHead reads the ref files first (microsecond-scale; this runs every poll) and
             // spawns `git rev-parse` only when they cannot resolve it. "" means main does not exist
             // yet — isEligible treats an empty head as "no wake".
             const mainHead = (await branchHead(root, mainBranch)) ?? "";
             // Branch-divergence watch, once per poll (see warnedBranchDivergence above): the
-            // fleet keeps fast-forwarding the branch it resolved at startup — the safe behavior,
+            // team keeps fast-forwarding the branch it resolved at startup — the safe behavior,
             // since role worktrees are based on it — and one warning names the divergence
             // instead of leaving it mysterious. Back on the target branch re-arms the check.
             const liveBranch = await currentBranch(root);
             if (liveBranch !== null && liveBranch !== mainBranch) {
                 if (!warnedBranchDivergence) {
                     warnedBranchDivergence = true;
-                    warn(`primary checkout moved to ${liveBranch} — the fleet keeps merging into ${mainBranch}`);
+                    warn(`your checkout moved to ${liveBranch} — the team keeps merging into ${mainBranch}`);
                 }
             }
             else {
                 warnedBranchDivergence = false;
             }
             const now = Date.now();
-            // The fleet's gates and alarms, one poll of the family (src/gates/gate-polls.ts): the daily
+            // The team's gates and alarms, one poll of the family (src/gates/gate-polls.ts): the daily
             // budget gate — with its derived-state publish and the fallback handback to the
-            // primary — the operator and per-role pause gates, quiet hours, the fleet-wide failure
+            // primary — the operator and per-role pause gates, quiet hours, the team-wide failure
             // hold, and the two observational storm alarms. The family's cross-poll memory lives
             // in gateStates, advanced in place; this returns this poll's verdicts for the
             // scheduling and start passes. The failure hold is deliberately not among them — the
-            // start gate and the landings' startHeld read the LATEST poll's verdict at permit
-            // time from gateStates.fleetHold, so a waiter granted its permit after later polls
+            // start gate and the merges' startHeld read the LATEST poll's verdict at permit
+            // time from gateStates.teamHold, so a waiter granted its permit after later polls
             // ran meets the hold as it stands then, not as this poll left it.
-            const { roleConfig, userPaused, pausedRoles: pausedRolesSet, capPaused, maintenanceQuota, bootstrapHeld, bootstrapActive, budgetPausedRoles, servingResolved, priceResolved, budgetActive, roleQuietHeld, quietNow, diskHeld: polledDiskHeld, } = pollFleetGates(gateStates, {
+            const { roleConfig, directorConfig, userPaused, pausedRoles: pausedRolesSet, capPaused, maintenanceQuota, bootstrapHeld, bootstrapActive, budgetPausedRoles, servingResolved, priceResolved, budgetActive, roleQuietHeld, quietNow, diskHeld: polledDiskHeld, } = pollTeamGates(gateStates, {
                 root,
                 runners,
                 liveConfig,
@@ -264,23 +286,33 @@ export async function runOrchestrator(opts) {
             // The latest poll's disk verdict, hoisted for tickStartHeld's permit-time reads
             // (plans/disk-floor.md, part 1/4).
             diskHeld = polledDiskHeld;
+            // Publish the permit pool's live state (plans/provider-concurrency.md §8): observers
+            // (status, TUI, GUI) read one file instead of coupling to this Semaphore, and the team
+            // line shows per-provider counts only while a cap map is configured. Written only when
+            // it changes, like budget and disk; a map-less team publishes `byKey` empty, which
+            // renders exactly as before.
+            publishInfoFields(root, info, [["permits", semaphore.snapshot()]]);
             // The failure hold, keyed per provider (PLANS.md 2026-10-05): a role is held when ITS
             // tick model's provider stands under a hold, and every role is held when the
-            // reviewer's provider is (with the review gate on, nothing could land — and the land
+            // reviewer's provider is (with the review gate on, nothing could merge — and the merge
             // queue below reads the same reviewHeld verdict). Key presence in the map is relapse
             // memory, not a hold: heldProviders() reads only standing holds (`until` non-null),
-            // so a lifted hold never keeps blocking. Read fresh from gateStates.fleetHold — the
+            // so a lifted hold never keeps blocking. Read fresh from gateStates.teamHold — the
             // permit-time closures below see the latest poll's verdicts, not this poll's snapshot.
-            const fleetHeldProviders = heldProviders(gateStates.fleetHold);
+            const teamHeldProviders = heldProviders(gateStates.teamHold);
             // Fresh reads for the permit-time closures: they run after later polls have advanced
-            // gateStates.fleetHold, so they re-derive from the LATEST poll's map, not this snapshot.
-            const fleetHeldNow = () => heldProviders(gateStates.fleetHold);
-            const reviewHeldNow = () => liveConfig.review.enabled && fleetHeldNow().has(seamHoldKey(reviewRunConfig(liveConfig)));
-            const reviewHeld = liveConfig.review.enabled && fleetHeldProviders.has(seamHoldKey(reviewRunConfig(liveConfig)));
+            // gateStates.teamHold, so they re-derive from the LATEST poll's map, not this snapshot.
+            const teamHeldNow = () => heldProviders(gateStates.teamHold);
+            // The reviewer's seam is read from the config merges actually review under — the poll's
+            // roleConfig, which a used-up claude window or the cap has already moved to a fallback —
+            // so a reviewer that left claude no longer holds the whole team on the claude hold.
+            const reviewSeamKey = reviewHoldKey(roleConfig);
+            const reviewHeldNow = () => liveConfig.review.enabled && teamHeldNow().has(reviewSeamKey);
+            const reviewHeld = liveConfig.review.enabled && teamHeldProviders.has(reviewSeamKey);
             const roleProviders = new Map(runners.map((r) => [r.role, r.runProvider(now)]));
             // Self-redeploy (src/redeploy/redeployer.ts): with main's head in hand, let the state
             // machine observe it. `hold` starts no new ticks at all — director included; a restart
-            // lands within the drain's window plus a bounded landing hand-off, and its prompt waits
+            // takes effect within the drain's window plus a bounded merge hand-off, and its prompt waits
             // in the inbox for the new build — while the green check/compile/drain run in the
             // background. That covers ticks
             // reserved before the hold too: a waiter parked in the semaphore queue that is granted a
@@ -299,15 +331,14 @@ export async function runOrchestrator(opts) {
                     roleTickP75Ms: p75TickDurationMs(roleTickDurationsMs),
                 }, liveConfig.autoRestart, now);
                 const build = redeploy.status(now);
-                if (assignInfoFieldIfChanged(info, "build", build))
-                    writeOrchestratorInfoBestEffort(root, info);
+                publishInfoFields(root, info, [["build", build]]);
                 if (action === "restart") {
                     restart = true;
                     // Only permit holders have a pi run to cut off (the director is guaranteed finished by
                     // then): a parked waiter meets the closed start gate whenever the shutdown hands it a
                     // permit, so it needs no abort — and aborting for it alone would also cut off an
-                    // in-flight landing that no permit-holding tick put at stake. The role-only controller
-                    // keeps that promise: the landing, wired to the full signal, runs on into the hand-off
+                    // in-flight merge that no permit-holding tick put at stake. The role-only controller
+                    // keeps that promise: the merge, wired to the full signal, runs on into the hand-off
                     // window the wait announces (BUGS.md 2026-09-30).
                     if (rolePermitHolders.size > 0)
                         internalRoleStop.abort();
@@ -315,13 +346,13 @@ export async function runOrchestrator(opts) {
                 }
                 holdForRestart = action === "hold";
             }
-            // Merge queue 3/5 — drain the durable land queue while neither a restart nor a failure
-            // hold is pending (the scheduler's WHEN; landing-drain.ts owns the HOW — the vetting
-            // stage, its merge slot, and the dedupe against main). A held poll starts no vet and no
-            // merge, exactly as it starts no tick; what is already in flight runs on, and a vet
+            // Merge queue 3/5 — drain the durable merge queue while neither a restart nor a failure
+            // hold is pending (the scheduler's WHEN; merge-drain.ts owns the HOW — the verification
+            // stage, its merge slot, and the dedupe against main). A held poll starts no verify and no
+            // merge, exactly as it starts no tick; what is already in flight runs on, and a verify
             // parked for its permit meets the same start gate as a parked tick when the permit comes.
             if (!holdForRestart && !reviewHeld && !diskHeld) {
-                await drainLandings({
+                await drainMergeQueue({
                     root,
                     mainBranch,
                     signal,
@@ -329,17 +360,21 @@ export async function runOrchestrator(opts) {
                     runners,
                     liveConfig,
                     roleConfig,
+                    directorConfig,
+                    piDefault,
                     startHeld: () => tickStartHeld() || reviewHeldNow(),
-                }, landings);
+                }, merges);
             }
-            // Backlog-aware deferral: while PLANS.md `## Planned` or BUGS.md `## Open` on main is
-            // non-empty, idle maintenance ticks stay deferred — queued feature/bugfix work outranks
-            // them regardless of what landed. Stat-cached reads (backlog.ts): one stat per file per
+            // Backlog-aware deferral: while PLANS.md `## Planned` or BUGS.md `## Open` on main
+            // holds an entry feature or bugfix may take (eligibleEntries), idle maintenance ticks
+            // stay deferred — queued feature/bugfix work outranks
+            // them regardless of what merged. Stat-cached reads (backlog.ts): one stat per file per
             // poll while the files are unchanged. bugfix is not a maintenance role, but while BUGS.md
             // `## Open` is empty it defers like one (deferTick) — openBugsNow is that emptiness, read
             // once here and reused for both predicates.
             const openBugsNow = openBugs(root).length > 0;
-            const workBacklogOpen = plannedPlans(root).length > 0 || openBugsNow;
+            const workBacklogOpen = eligibleEntries(root, "feature").length > 0 || eligibleEntries(root, "bugfix").length > 0;
+            const plansFull = planBacklogFull(root, liveConfig);
             // A demoted fallback's half-open window (part 5c/8): the pair whose probe is due, and
             // the roles whose model tier WOULD run on that pair absent the demotion (the price-based
             // resolution — the serving resolution has already dropped the pair, which is exactly
@@ -347,7 +382,7 @@ export async function runOrchestrator(opts) {
             // admits exactly one of them as the probe — a probe blind to the pair's tier would lift
             // the pause for every role (objection to an earlier draft), and a probe with no
             // eligible runner must not hijack the poll's other launches (the launch pass continues
-            // only the eligible runners it cannot admit, never the rest of the fleet).
+            // only the eligible runners it cannot admit, never the rest of the team).
             const probePair = fallbackProbeDuePair(gateStates.budget.breakers, breakerNow());
             const probeRoles = new Set();
             if (probePair !== null) {
@@ -360,7 +395,7 @@ export async function runOrchestrator(opts) {
                 }
             }
             // The review-on strong pause (budgetGate): with the review gate on, an unresolvable
-            // strong tier means nothing could land, so EVERY role is held — the per-tier pause set
+            // strong tier means nothing could merge, so EVERY role is held — the per-tier pause set
             // alone would let small/default roles author changes no reviewer could judge. The probe
             // of the strong pair pierces this hold for exactly the probed tier's roles too.
             const reviewStrongPaused = budgetActive && liveConfig.review.enabled && servingResolved.strong.pair === null;
@@ -383,13 +418,15 @@ export async function runOrchestrator(opts) {
                 roleQuietHeld,
                 holdForRestart,
                 diskHeld,
-                heldProviders: fleetHeldProviders,
+                heldProviders: teamHeldProviders,
+                windowHeldProviders: windowHeldProviders(gateStates.teamHold),
                 reviewHeld,
                 roleProviders,
                 openBugsNow,
                 workBacklogOpen,
+                planBacklogFull: plansFull,
                 deferredDue,
-                workLandedSince,
+                workMergedSince,
             });
             launchDueTicks({
                 root,
@@ -405,40 +442,61 @@ export async function runOrchestrator(opts) {
                 probeRoles,
                 budgetActive,
                 semaphore,
+                piDefault,
                 rolePermitHolders,
                 roleInFlight,
                 directorInFlight,
                 roleTickDurationsMs,
                 startHeld: (role) => tickStartHeld() ||
-                    (role !== DIRECTOR_ROLE &&
-                        (reviewHeldNow() || fleetHeldNow().has(roleProviders.get(role)))),
+                    (role !== DIRECTOR_ROLE
+                        ? reviewHeldNow() || teamHeldNow().has(roleProviders.get(role))
+                        : windowHeldProviders(gateStates.teamHold).has(roleProviders.get(role))),
             });
             // Priority headroom (plans/parallel-work-instances.md part 7/7): withhold a few permits
             // from maintenance while a work loop has work to take, so a due work tick never waits out
             // a whole maintenance tick. Sized after the launch pass, so a runner launched this poll
             // already reads as running and reserves nothing for itself.
+            const poolSnapshot = semaphore.snapshot();
+            // The provider-headroom predicate receives the structural ClaimRunner; the config that
+            // names the provider lives on the real LoopRunners, so look the runner up by role.
+            const runnerByRole = new Map(runners.map((r) => [r.role, r]));
             const reserve = workReserveCount(root, runners, {
                 maxConcurrent: liveConfig.maxConcurrent,
                 enabled: new Set(runners.filter((r) => loopEnabled(r.config, r.role)).map((r) => r.role)),
-                queuedLandingRoles: queuedLandingRoles(root),
+                queuedMergeRoles: queuedMergeRoles(root),
+                // Per-provider headroom (plans/provider-concurrency.md §6): an idle work loop reserves a
+                // permit only when its own provider could use it — capped and full, it would only idle
+                // the slot another provider's maintenance tick could take. Read from the pool's live
+                // snapshot; an uncapped key (or the team-total-only case) always has headroom.
+                providerHasHeadroom: (r) => {
+                    const runner = runnerByRole.get(r.role);
+                    const cfg = runner && runner.role !== DIRECTOR_ROLE ? runner.runConfig(now) : null;
+                    const key = cfg ? seamConcurrencyKey(cfg, piDefault) : undefined;
+                    if (key === undefined)
+                        return true;
+                    const k = poolSnapshot.byKey[key];
+                    if (k?.limit === undefined)
+                        return true;
+                    return k.inUse < k.limit;
+                },
             });
             semaphore.setReserve(reserve);
             if ((lastReserve === 0) !== (reserve === 0)) {
-                emit({ loop: "harness", type: "permit_reserve", reserve });
+                emit({ source: TUMWATER_SOURCE, type: "permit_reserve", reserve });
             }
             lastReserve = reserve;
-            // Once mode's exit: every enabled role settled, no tick in flight, and the land queue
-            // empty with no landing in flight for one full poll cycle — then fire the internal
+            // Once mode's exit: every enabled role settled, no tick in flight, and the merge queue
+            // empty with no merge in flight for one full poll cycle — then fire the internal
             // stop, the same graceful shutdown the restart drain uses (the `finally` awaits
-            // in-flight landing tasks to the end). The one-poll-cycle requirement is the guard
-            // against dropping a queued-but-not-yet-started landing: a stop that lands during the
+            // in-flight merge tasks to the end). The one-poll-cycle requirement is the guard
+            // against dropping a queued-but-not-yet-started merge: a stop that arrives during the
             // shutdown drain drops the queue entry, so the slot gets its poll to pick the entry up
             // before the stop is trusted.
             if (once.exitReady({
                 roleTicks: roleInFlight.size,
                 directorTicks: directorInFlight.size,
-                landings: landingTasks(landings).length,
-                queuedLandings: queuedLandingFiles(root).length,
+                merges: mergeTasks(merges).length,
+                queuedMerges: queuedMergeFiles(root).length,
             })) {
                 internalStop.abort();
                 break;
@@ -447,8 +505,8 @@ export async function runOrchestrator(opts) {
         }
     }
     finally {
-        await drainInFlightWork(root, roleInFlight, directorInFlight, landingTasks(landings), restart, opts.handoffLandingWindowMs ?? HANDOFF_LANDING_WINDOW_MS, () => internalStop.abort());
-        emit({ loop: "harness", type: "orchestrator_stop" });
+        await drainInFlightWork(root, roleInFlight, directorInFlight, mergeTasks(merges), restart, opts.handoffMergeWindowMs ?? HANDOFF_MERGE_WINDOW_MS, () => internalStop.abort());
+        emit({ source: TUMWATER_SOURCE, type: "orchestrator_stop" });
         notifier.dispose();
         removeQuiet(infoFile);
     }

package/dist/src/orchestrator/retention.js

@@ -1,13 +1,16 @@
+// vocabulary: plain
 /** Session retention (the `sessionRetentionDays` setting): the once-per-day gate and the prune
  * itself, split out of orchestrator.ts — the poll-loop runtime carried both a startup prune and
  * a near-identical in-poll prune plus the last-applied-window bookkeeping, and scheduling.ts
  * held the due-gate despite being about tick policy, not file retention. Dependency direction:
  * orchestrator → retention; this module owns the whole "which files age out, and when" concern
  * and the orchestrator only hands it the (possibly live-reloaded) window. */
-import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { pruneOldFiles } from "../files/files.js";
-import { pruneSessionLedgers } from "../agent/session-ledger.js";
-import { sessionsRootDir, toolOutputDir } from "../paths.js";
+import { pruneSessionLedgers, pruneOpencodeSessions } from "../agent/session-ledger.js";
+import { loadConfigSafe } from "../config/config.js";
+import { opencodeBackend, opencodeSpillDir } from "../agent/opencode/opencode-backend.js";
+import { opencodeDbPath, sessionsRootDir, toolOutputDir } from "../paths.js";
 /** Is a once-per-day session prune due? Due when retention is enabled (> 0) and a full day
  * has passed since the last prune (or no prune has run yet). */
 export function dueForPrune(lastPruneAt, now, retentionDays) {
@@ -34,8 +37,8 @@ export class RetentionPruner {
             this.prune(root, retentionDays);
     }
     /** Apply a (possibly live-reloaded) retention window: a mid-run edit re-prunes immediately;
-     * independently of edits, an unchanged fleet prunes at most once per day so a never-restarted
-     * fleet still honors its window. Both paths log the startup warning shape only when files
+     * independently of edits, an unchanged team prunes at most once per day so a never-restarted
+     * team still honors its window. Both paths log the startup warning shape only when files
      * were actually deleted — quiet polls stay silent. */
     poll(root, retentionDays) {
         if (retentionDays !== this.lastRetention || dueForPrune(this.lastPruneAt, Date.now(), retentionDays)) {
@@ -46,7 +49,7 @@ export class RetentionPruner {
             // only for a positive window.
             if (retentionDays !== this.lastRetention) {
                 logEventBestEffort(root, {
-                    loop: "harness",
+                    source: TUMWATER_SOURCE,
                     type: "retention_changed",
                     from: this.lastRetention,
                     to: retentionDays,
@@ -61,15 +64,29 @@ export class RetentionPruner {
     }
     prune(root, days) {
         const sessions = sessionsRootDir(root);
-        // Age out session/tool-output files first: an entirely stale dir is gone before the line
-        // pass reads it. Ledger lines are counted separately — a ledger's mtime stays young while
-        // its role runs, so pruneOldFiles never ages the file out; trimming its lines is what
-        // bounds it, and each warning must name the unit it pruned.
+        // OpenCode's sessions live outside .tumwater (design §4, finding 17): resolve its binary
+        // and OPENCODE_DB exactly as a run's invocation would, and purge its expired sessions and
+        // spill files from the ledger BEFORE the file pass below ages it out — an idle role's
+        // whole ledger file is deleted once its mtime passes the window, so only reading it first
+        // hands every expired OpenCode session id to `opencode session delete`. Each half warns its
+        // own unit.
+        const { config } = loadConfigSafe(root);
+        const bin = config !== undefined ? opencodeBackend.resolveBin(config).bin : undefined;
+        const deleted = pruneOpencodeSessions(sessions, days, {
+            bin,
+            env: { ...process.env, OPENCODE_DB: opencodeDbPath(root) },
+            spillDir: opencodeSpillDir(root),
+        });
+        if (deleted > 0)
+            warnEventBestEffort(root, TUMWATER_SOURCE, `deleted ${deleted} expired opencode session(s)`);
+        // Age out session/tool-output files now: an entirely stale dir is gone before the line
+        // pass reads it. A running role's ledger mtime stays young, so pruneOldFiles never ages
+        // that file out; each warning must name the unit it pruned.
         const pruned = pruneOldFiles(sessions, days) + pruneOldFiles(toolOutputDir(root), days);
         if (pruned > 0)
-            warnEventBestEffort(root, "harness", `pruned ${pruned} old pi session/tool-output file(s)`);
+            warnEventBestEffort(root, TUMWATER_SOURCE, `pruned ${pruned} old agent session/tool-output file(s)`);
         const prunedLines = pruneSessionLedgers(sessions, days);
         if (prunedLines > 0)
-            warnEventBestEffort(root, "harness", `pruned ${prunedLines} stale session ledger line(s)`);
+            warnEventBestEffort(root, TUMWATER_SOURCE, `pruned ${prunedLines} stale session ledger line(s)`);
     }
 }