tumwater 0.1.2 → 0.2.0

package/dist/src/loop/leftover.js

@@ -1,57 +1,58 @@
+// vocabulary: plain
 import { aheadOfMain, commitMessage, deleteRef, headOf, isMergedInto, refSha, setRef } from "../git/git.js";
 import { parseCommitMetadata } from "../git/commit-message.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { enqueueLanding, queuedLandings } from "../landing/landing-queue.js";
-import { landingRefName } from "../paths.js";
+import { enqueueMerge, queuedMerges } from "../merge/merge-queue.js";
+import { mergeRefName } from "../paths.js";
 import { shortSha } from "../text/format.js";
-/** Salvaging a commit a previous tick left unlanded (plans/merge-queue.md). Since merge queue
+/** Salvaging a commit a previous tick left unmerged (plans/merge-queue.md). Since merge queue
  * 2/5 the role's branch is reset to main the moment its commit is pinned, so the leftover
  * normally lives in `refs/tumwater/landing/<role>`: recovery puts that sha back on the durable
- * land queue, so it lands through the SAME slot, gate, and strike cap a fresh tick's change
+ * merge queue, so it merges through the SAME slot, gate, and strike cap a fresh tick's change
  * does — no crash or abort path smuggles unreviewed work into main (invariant 1), and main keeps
- * exactly one writer, the orchestrator's landing slot (an in-tick recovery landing used to race
+ * exactly one writer, the orchestrator's merge slot (an in-tick recovery merge used to race
  * the slot's batches into `merge_blocked`). A commit with NO pin — a crash in the window between
  * the tick's commit and its pin write, or a failed pin write itself — still sits on the branch
  * ahead of main; recovery adopts that tip into the pin scheme and queues it, so invariant 1
  * holds whether or not the pin survived. Split out of loop.ts — which keeps the tick lifecycle
  * around it — because this is a self-contained concern with its own entry condition and git
  * surface; the only things it borrows from the loop are identity, the tick number, the
- * worktree (for the no-pin fallback), and three pieces of the role's landing state: its
+ * worktree (for the no-pin fallback), and three pieces of the role's merge state: its
  * conflict streak, outstanding hand-back, and permanent-reviewer hold. */
-/** Consecutive landings of one pinned sha that may end `merge_conflict` before recovery stops
+/** Consecutive merges of one pinned sha that may end `merge_conflict` before recovery stops
  * re-queuing it (LoopState.mergeConflicts). Each attempt costs a conflict-resolution run, and
  * a role holding a pin never authors: without a cap an unmergeable change would re-queue
  * forever, burning one resolution run per drain. At the cap the pin is handed back to its
  * author with the markers in place rather than discarded (PLANS.md "Robust conflict landing,
  * part 2/2"); a lineage already handed back once is discarded instead. */
 export const MERGE_CONFLICT_LIMIT = 2;
-/** Queue a commit a previous tick left unlanded. Entry condition: the landing ref exists and
+/** Queue a commit a previous tick left unmerged. Entry condition: the merge ref exists and
  * its sha is not yet contained in main — or, with no pin at all, the role's branch is ahead of
  * main (crash between the commit and the pin). A present-but-contained ref is stale — a crash
  * between the ff-merge and the ref deletion — and is deleted without queuing anything. Returns
  * null when there was nothing to salvage. The queued entry carries the pin's sha plus the
  * summary, body, and high-friction flag read back from its commit message, because the
- * authoring run that set them is gone; from there the landing slot keeps or deletes the ref per
- * the lander's usual policy. An unreadable ref or worktree reads as no leftover — only git-level
+ * authoring run that set them is gone; from there the merge slot keeps or deletes the ref per
+ * the merger's usual policy. An unreadable ref or worktree reads as no leftover — only git-level
  * errors in the stale-pin cleanup propagate. */
 export async function recoverLeftover(ctx) {
-    // One landing ref per role, so at most one outstanding landing per role: a second entry beside
+    // One merge ref per role, so at most one outstanding merge per role: a second entry beside
     // one the slot has yet to finish would share — and fight over — the same ref.
-    const queued = queuedLandings(ctx.root).find((e) => e.role === ctx.role);
+    const queued = queuedMerges(ctx.root).find((e) => e.role === ctx.role);
     if (queued)
         return { kind: "already_queued", entry: queued };
-    const ref = landingRefName(ctx.role);
+    const ref = mergeRefName(ctx.role);
     let sha = await refSha(ctx.root, ref).catch(() => null);
     if (sha) {
         if (await isMergedInto(ctx.root, sha, ctx.mainBranch)) {
-            // Stale pin: the work already landed and a crash skipped its un-pinning. Clean it up so
-            // the next tick does not re-land what main already holds.
+            // Stale pin: the work already merged and a crash skipped its un-pinning. Clean it up so
+            // the next tick does not re-merge what main already holds.
             await deleteRef(ctx.root, ref);
             return null;
         }
     }
     else {
-        // No pin: either nothing was left behind, or a crash landed in the commit→pin window (or
+        // No pin: either nothing was left behind, or a crash hit the commit→pin window (or
         // the pin write failed) and the commit still sits on the branch ahead of main. Recover that
         // tip too — invariant 1 must hold whether or not the pin survived. An unreadable worktree
         // reads as "no leftover", exactly like a failed ref read: never propagate into the tick.
@@ -62,11 +63,11 @@ export async function recoverLeftover(ctx) {
         if (!sha)
             return null;
         // Adopt the unpinned commit into the pin scheme so every downstream outcome — kept on an
-        // under-cap review failure (the strike cap's retry), deleted on reject/land/discard,
+        // under-cap review failure (the strike cap's retry), deleted on reject/merge/discard,
         // discarded on a user abort — behaves exactly as for a normally pinned one. A failed
         // adoption is logged and leaves the commit on the branch (see `unpinned`).
         if (!(await setRef(ctx.root, ref, sha))) {
-            warnEventBestEffort(ctx.root, ctx.role, `failed to adopt unpinned leftover ${shortSha(sha)} into its landing ref`);
+            warnEventBestEffort(ctx.root, ctx.role, `failed to adopt unpinned leftover ${shortSha(sha)} into its merge ref`);
             return { kind: "unpinned", sha };
         }
     }
@@ -75,7 +76,7 @@ export async function recoverLeftover(ctx) {
     // full gate check for a request that can never succeed until the model config changes. The
     // caller clears the hold (and re-queues) once the resolved reviewer selector differs, so a
     // fixed config recovers automatically (BUGS.md 2026-10-06).
-    const held = ctx.landingReviewError;
+    const held = ctx.mergeReviewError;
     if (held?.sha === sha)
         return { kind: "held", sha, message: held.message };
     const attempts = ctx.mergeConflicts?.sha === sha ? ctx.mergeConflicts.count : 0;
@@ -85,7 +86,7 @@ export async function recoverLeftover(ctx) {
             // This lineage already used its one hand-back and still conflicts at the cap: drop the
             // pin (the warning names its sha and both attempts) and let the author start over.
             await deleteRef(ctx.root, ref);
-            warnEventBestEffort(ctx.root, ctx.role, `discarding leftover ${shortSha(sha)} after ${attempts} landings ended in unresolved merge conflicts with main, even after a hand-back`);
+            warnEventBestEffort(ctx.root, ctx.role, `discarding leftover ${shortSha(sha)} after ${attempts} merges ended in unresolved conflicts with main, even after sending it back to the role to resolve`);
             return { kind: "discarded", sha, summary, attempts };
         }
         // Main has moved too far under this change for the resolver to reconcile it: keep the pin
@@ -97,9 +98,9 @@ export async function recoverLeftover(ctx) {
     const entry = {
         role: ctx.role,
         sha,
-        tick: ctx.tick,
-        // Name what lands, not merely that a recovery happened: the recovered commit's own subject
-        // rides the landing, so the failure digest's "Landed in the window" can correlate a
+        run: ctx.tick,
+        // Name what merges, not merely that a recovery happened: the recovered commit's own subject
+        // rides the merge, so the failure digest's "Merged in the window" can correlate a
         // recovered merge with the work it names (BUGS.md 2026-09-21). Unreadable messages fall
         // back to the bare provenance label.
         summary: meta.subject
@@ -108,18 +109,18 @@ export async function recoverLeftover(ctx) {
         body: meta.body,
         highFriction: meta.highFriction || undefined,
         // A retriable revision keeps its round from the commit's Revision trailer, so its next
-        // rejection records the following round (not round 1 again) and a recovered landing still
+        // rejection records the following round (not round 1 again) and a recovered merge still
         // deletes the rejected ref (plans/revise-rejected.md). Absent on a fresh change.
         ...(meta.revisionRound !== undefined ? { revisionRound: meta.revisionRound } : {}),
         enqueuedAt: Date.now(),
     };
-    enqueueLanding(ctx.root, entry);
-    logEventBestEffort(ctx.root, { loop: ctx.role, type: "land_queued", commit: sha, summary: entry.summary });
+    enqueueMerge(ctx.root, entry);
+    logEventBestEffort(ctx.root, { source: ctx.role, type: "merge_queued", commit: sha, summary: entry.summary });
     return { kind: "enqueued", entry };
 }
 /** The review-gate metadata a pinned leftover commit carries in its own message: its
  * subject, high-friction flag, and author's body, or an empty object when the commit
- * predates the contract or the message cannot be read. Recovery lands through the same gate
+ * predates the contract or the message cannot be read. Recovery merges through the same gate
  * as a fresh tick, so it must present those fields the same way — otherwise a flagged change
  * is silently reviewed as routine (BUGS.md 2026-09-19), and the merged event names the
  * recovery but not the work (BUGS.md 2026-09-21). */

package/dist/src/loop/loop-fallback.js

@@ -35,7 +35,7 @@ export function foldModelFallbackPhase(ctx, fallbackCtx, pi) {
     const willBeIn = next !== undefined && next.since > 0;
     if (!wasIn && willBeIn) {
         logEventBestEffort(ctx.root, {
-            loop: ctx.role,
+            source: ctx.role,
             type: "model_fallback_started",
             provider: fallbackCtx.fallback.provider,
             model: fallbackCtx.fallback.model,
@@ -57,7 +57,7 @@ function emitFallbackEnded(ctx, prior, primary, now, wasIn) {
     if (!wasIn)
         return;
     logEventBestEffort(ctx.root, {
-        loop: ctx.role,
+        source: ctx.role,
         type: "model_fallback_ended",
         provider: primary.provider,
         model: primary.model,

package/dist/src/loop/loop-pi.js

@@ -1,15 +1,19 @@
 import { runPi } from "../pi/pi.js";
 import { agentSessionResumable } from "../agent/agent-backend.js";
-import { HOLD_BASE_MS } from "../fleet/fleet-hold.js";
+import { HOLD_BASE_MS } from "../team/team-hold.js";
 import { backendKindPhrase } from "../text/phrases.js";
-import { configForRole } from "../config/config-views.js";
+import { configForRole, resolvedAgentConfig, seamHoldKey, seamPairName } from "../config/config-views.js";
+import { ensureProviderLease } from "../concurrency/provider-lease.js";
 import { buildSummaryRequestPrompt } from "../prompt/prompt-followup.js";
 import { readClaudeAccount, subscriptionWindowRejected } from "../agent/claude/claude-account.js";
-import { dailyCost, fleetDailyCost } from "../budget/budget.js";
+import { observeOpencodeRun, opencodeModelKey } from "../agent/opencode/opencode-catalog.js";
+import { dailyCost, teamDailyCost, pairDailyCost } from "../budget/budget.js";
 import { loadLoopState } from "./loop-state.js";
 import { baseRoleOf, loopIds } from "../roles/loop-ids.js";
 import { buildStageFixPrompt } from "../prompt/gate-prompts.js";
+import { logEventBestEffort } from "../events/events.js";
 import { nativeLogPath, piLogPath, roleNotesPath, sessionDir } from "../paths.js";
+import { piModelsPath } from "../pi/pi-models.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { cappedRequestTimeouts } from "../request-timeouts.js";
 /** Upper bound on how long the transient retry waits out a provider's Retry-After hint
@@ -19,7 +23,7 @@ import { cappedRequestTimeouts } from "../request-timeouts.js";
  * working). */
 const RATE_LIMIT_RETRY_AFTER_CAP_S = 120;
 /** What a hint-less 429 waits before its one retry. With no Retry-After from the provider, the
- * fleet's own constants state the refill physics: fleet/fleet-hold.ts's base hold is one minute,
+ * team's own constants state the refill physics: team/team-hold.ts's base hold is one minute,
  * "the shortest pause that lets the bucket refill". Retrying sooner re-enters the same exhausted
  * per-minute bucket the first request just emptied and burns the tick's only retry on a
  * near-certain second 429. A present hint always wins instead; the cap above still bounds
@@ -30,24 +34,25 @@ function sleepFor(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 /** The `--max-budget-usd` cap for one API-billed claude authoring run (plans/agent-backends.md
- * §7): the remaining fleet budget (`maxDailyCostUsd` − today's fleet spend), lowered to the
+ * §7): the remaining team budget (`maxDailyCostUsd` − today's team spend), lowered to the
  * base role's own remaining cap when `maxDailyCostUsdPerRole` names it. The cap map and its
  * spend are keyed by BASE role, exactly as the scheduler's role-cap gate reads them
  * (src/gates/role-cap-gates.ts: `baseRoleOf` groups `feature`/`feature-2` and sums the
  * group's spend), so instance loop ids share their base's cap instead of silently falling
- * through to the fleet budget. Returns undefined — no cap — for the director, a non-claude
+ * through to the team budget. Returns undefined — no cap — for the director, a non-claude
  * seam, an account that is not API-billed, a disabled cap (0), or no remaining budget at all
  * (a non-positive cap is dropped by the argv builder). Spend is read from the persisted loop
  * states: each role's daily window is what the budget gate and the dashboards sum, and this
- * runs before the authoring run records its own cost. */
-function authoringBudgetCap(root, role, cfg, agent) {
+ * runs before the authoring run records its own cost. A pair with a step cap of its own (a
+ * priced fallback step, `fallbackStepCaps`) is also held to that step's remaining budget. */
+function authoringBudgetCap(root, role, cfg, agent, pair) {
     if (role === DIRECTOR_ROLE || agent !== "claude")
         return undefined;
     if (readClaudeAccount(root)?.billing !== "api")
         return undefined;
     const now = Date.now();
     const states = loopIds(cfg).map((r) => loadLoopState(root, r));
-    let cap = cfg.maxDailyCostUsd - fleetDailyCost(states, now);
+    let cap = cfg.maxDailyCostUsd - teamDailyCost(states, now);
     const base = baseRoleOf(role);
     const perRole = cfg.maxDailyCostUsdPerRole?.[base];
     if (perRole !== undefined && perRole > 0) {
@@ -57,17 +62,22 @@ function authoringBudgetCap(root, role, cfg, agent) {
             : dailyCost(loadLoopState(root, role), now);
         cap = Math.min(cap, perRole - spent);
     }
+    // A fallback step with its own cap (applyFallbackModel's fallbackStepCaps, set only on the
+    // derived view) lowers the run to what is left of the step's budget for the day.
+    const stepCap = cfg.fallbackStepCaps?.[pair];
+    if (stepCap !== undefined)
+        cap = Math.min(cap, stepCap - pairDailyCost(states, pair, now));
     // Round the subtraction's floating-point residue off so the argv carries a clean number.
     cap = Math.round(cap * 1e6) / 1e6;
     return cap > 0 ? cap : undefined;
 }
 /** The pi-invocation plumbing of one role loop, extracted from LoopRunner (src/loop/loop.ts):
  * the shared per-loop wiring for every run (role config, session dir, raw log, abort
- * signal), the one bounded transient-failure retry all runs share, the landing slot's
+ * signal), the one bounded transient-failure retry all runs share, the merge slot's
  * run (which watches only the shutdown signal), and the tick's SUMMARY follow-up turn.
  * It owns HOW a loop talks to pi; the LoopRunner tick state machine owns WHAT runs happen
  * and folds every run's spend back through the host's foldUsage (authoring) or
- * foldLandingUsage (landing/review). */
+ * foldMergeUsage (merge/review). */
 export class LoopPi {
     host;
     constructor(host) {
@@ -77,15 +87,15 @@ export class LoopPi {
      * role-resolved config, this loop's session dir and raw log, and the per-tick abort signal.
      * One place for those derivations — a new PiRunOptions field touches only here instead of
      * drifting between the author run and the SUMMARY follow-up. Callers override what differs
-     * (the follow-up's capped timeouts, the landing's shutdown-only signal). */
+     * (the follow-up's capped timeouts, the merge's shutdown-only signal). */
     loopPiOpts(wt, prompt, sessionName, kind, resume = false, config, notesPath) {
-        // A caller-supplied config (the landing conflict resolver's strong-tier one,
+        // A caller-supplied config (the merge conflict resolver's strong-tier one,
         // plans/model-tiers.md part 4/8) replaces the role's own for that one run; the role's
         // config is the default for every other caller. Resolved once here so the native-log path
         // names the same agent the run actually uses.
         const resolved = config ?? configForRole(this.host.config(), this.host.role);
         const maxBudgetUsd = kind === "author"
-            ? authoringBudgetCap(this.host.root, this.host.role, this.host.config(), resolved.agent ?? "pi")
+            ? authoringBudgetCap(this.host.root, this.host.role, this.host.config(), resolved.agent ?? "pi", seamPairName(resolved))
             : undefined;
         return {
             cwd: wt,
@@ -101,7 +111,7 @@ export class LoopPi {
             rawLogFile: piLogPath(this.host.root, this.host.role),
             nativeLogFile: nativeLogPath(this.host.root, this.host.role, resolved.agent ?? "pi"),
             signal: this.host.runSignal(),
-            // Only runAuthoringPi and its SUMMARY/stage-fix follow-ups pass this; a landing,
+            // Only runAuthoringPi and its SUMMARY/stage-fix follow-ups pass this; a merge,
             // review, or conflict-resolution run has no notebook, and neither does the director.
             notesPath,
             // A tool call silent for the configured stall threshold names itself in the event feed
@@ -112,30 +122,42 @@ export class LoopPi {
             // The translator's unmapped-native-type and cost_unknown warnings reach the event feed
             // as their own warning events, once per run.
             onAgentWarning: (warning) => this.host.warn(`agent_unknown_event: ${warning}`),
+            // A run that read an image its model cannot see (plans/image-input.md "Detecting a
+            // blind read"): the runner killed the authoring run (action "fail") or a gate run
+            // merely recorded it ("logged") — each logged here with this loop's identity so the
+            // feed names who, on which tick, read which file on which blind model.
+            onBlindRead: (path, action) => logEventBestEffort(this.host.root, {
+                source: this.host.role,
+                type: "image_blind",
+                run: this.host.tickNumber(),
+                path,
+                model: resolved.model,
+                action,
+            }),
         };
     }
-    /** Run the orchestrator's landing slot's pi (merge queue 3/5): the shared per-loop wiring
+    /** Run the orchestrator's merge slot's pi (merge queue 3/5): the shared per-loop wiring
      * of runRolePi — role config, session dir, raw log, transient-failure retry — with usage
      * folded into the authoring loop's counters, but watching ONLY the harness shutdown signal
-     * (which may be undefined — PiRunOptions.signal is optional): a landing is outside any
+     * (which may be undefined — PiRunOptions.signal is optional): a merge is outside any
      * tick, so `tumwater abort --role` (which targets a tick's per-tick abort controller) must
      * never reach it, and the stale per-tick controller of a finished tick must not abort it
      * either. Session naming is the caller's (the reviewer composes its own from
-     * ReviewContext.tick; landing-merge.ts keeps its conflict-resolver naming through
-     * LanderContext.runPi).
+     * ReviewContext.tick; merge-to-main.ts keeps its conflict-resolver naming through
+     * MergerContext.runPi).
      */
-    async runLandingPi(wt, prompt, sessionName, config) {
+    async runMergePi(wt, prompt, sessionName, config) {
         return this.runWithTransientRetry({
             ...this.loopPiOpts(wt, prompt, sessionName, "gate", false, config),
             signal: this.host.signal,
         }, { authoring: false });
     }
-    /** The landing gate's reviewer runs (review.ts's review run and verdict follow-up): the
+    /** The merge gate's reviewer runs (review.ts's review run and verdict follow-up): the
      * same shared transient-retry wiring — a 429 in the gate waits its hint out and retries
      * once, exactly like an authoring run (BUGS.md 2026-10-01) — with one folding difference:
-     * the FINAL run's usage is folded by the gate's caller (landing-core's foldUsage of
+     * the FINAL run's usage is folded by the gate's caller (merge-core's foldUsage of
      * gate.run / gate.followUpRun), so only a RETRIED first attempt is folded here. That fold
-     * is not optional: it stamps the fleet-wide rate-limit hold's input before the wait, and
+     * is not optional: it stamps the team-wide rate-limit hold's input before the wait, and
      * it is the only record the failed attempt's spend would ever get.
      * Takes full PiRunOptions because the gate's two runs differ in everything but the loop
      * they charge (config, session dir and name, label, tool-call callbacks, signal).
@@ -144,7 +166,7 @@ export class LoopPi {
         return this.runWithTransientRetry(opts, { foldFinal: false, authoring: false });
     }
     /** The one bounded transient-failure retry shared by EVERY pi run this loop makes
-     * (runRolePi, runLandingPi, and runGatePi): two transient failures of the world (not of
+     * (runRolePi, runMergePi, and runGatePi): two transient failures of the world (not of
      * the session) earn exactly one retry that continues the same session — the model server
      * timing out an idle predict stream, the provider severing that stream outright (undici's
      * bare "terminated", the stream-severed backend kind), the provider accepting a request
@@ -162,18 +184,49 @@ export class LoopPi {
      * Extracted verbatim from runRolePi so the rule lives in one place
      * (574a14c's loopPiOpts move was the wiring half of the same single-source-of-truth).
      */
+    /** Part 6c/7: demote a catalog-free opencode model the first time a run bills it. Observed
+     * here — the fold chokepoint every run of the loop passes through — because it is the one
+     * place that has the run's resolved model (opts.config) and its cost (the run) together, and
+     * it holds the loop's root and role for the cache and the event feed. pi and claude runs
+     * have no opencode catalog entry and no-op. Best-effort like observeClaudeAccount: an
+     * unwritable cache or event feed must not fail the run that observed it. */
+    observeFreeModelCost(run, config) {
+        if (config.agent !== "opencode")
+            return;
+        try {
+            observeOpencodeRun(this.host.root, { model: opencodeModelKey(config.model ?? ""), costUsd: run.costUsd }, { source: this.host.role });
+        }
+        catch {
+            // The next priced run demotes it; nothing this run depends on is lost.
+        }
+    }
     async runWithTransientRetry(opts, 
     /** runGatePi only: skip folding the FINAL returned run (the caller folds it), while a
      * retried first attempt still folds — its spend and its rate-limit hold stamp must not
      * vanish just because the gate routes its own folding. Default folds everything, the
-     * authoring and landing behavior. */
+     * authoring and merge behavior. */
     { foldFinal = true, authoring = true } = {}) {
         // The fold every attempt takes: an authoring run charges the loop's tick counters
-        // (foldUsage); a landing, reviewer, or conflict-resolution run charges the same cost and
-        // prompt-token totals but never the tick's pre-edit prefix (foldLandingUsage).
-        const fold = (run) => authoring ? this.host.foldUsage(run) : this.host.foldLandingUsage(run);
+        // (foldUsage); a merge, reviewer, or conflict-resolution run charges the same cost and
+        // prompt-token totals but never the tick's pre-edit prefix (foldMergeUsage).
+        // The seam this run actually ran on, as the team hold keys it (seamHoldKey): the fold
+        // stamps the rate-limit and backend-failure observations with it, so a storm on a claude
+        // reviewer holds `claude` and a pi author on a different provider stays open. opts.config
+        // is always the run's own resolved seam (reviewRunConfig for the reviewer, the role's
+        // config or fallback pair for the author), so this names the backend that failed.
+        const provider = seamHoldKey(opts.config);
+        // The run's model pair name, the key of the per-step daily spend (LoopState.dayCostByPair).
+        const pair = seamPairName(opts.config);
+        const fold = (run) => authoring ? this.host.foldUsage(run, provider, pair) : this.host.foldMergeUsage(run, provider, pair);
+        // The run re-keys the calling tick's provider lease to the provider THIS run uses, if it is
+        // not already there (plans/provider-concurrency.md §5): a budget handback or a model-failure
+        // switch that moved this run onto another seam moves the tick's lease with it, so a
+        // claude-authored tick whose gate run lands on omlx is counted there. No-op when the tick
+        // carries no lease (a bare LoopPi unit test, `tumwater tick`).
+        await ensureProviderLease(opts.config);
         const pi = await runPi(opts);
         this.warnFallbackClone(pi);
+        this.observeFreeModelCost(pi, opts.config);
         if (!pi.aborted &&
             !pi.timedOut &&
             !pi.quietKilled &&
@@ -185,19 +238,19 @@ export class LoopPi {
             // A subscription claude usage-window rejection is not the 429 the retry's minute-scale
             // wait beats: the window resets hours out, so a within-run retry is guaranteed to fail
             // after burning up to RATE_LIMIT_RETRY_AFTER_CAP_S. The tick ends and the kept session
-            // resumes once the fleet hold lifts (plans/agent-backends.md §8, part 6e).
+            // resumes once the team hold lifts (plans/agent-backends.md §8, part 6e).
             !subscriptionWindowRejected(pi)) {
             this.host.warn(pi.transientPiCrash
                 ? `pi crashed on malformed JSON (${pi.errorMessage ?? "no detail"}) — resuming the session once`
                 : pi.transientRateLimit
-                    ? `provider rate-limited the request (429${pi.retryAfterSeconds ? `, retry after ${pi.retryAfterSeconds}s` : `, no hint — waiting ${RATE_LIMIT_NO_HINT_RETRY_S}s`}) — retrying the pi run once`
+                    ? `provider rate-limited the request (429${pi.retryAfterSeconds ? `, retry after ${pi.retryAfterSeconds}s` : `, no hint — waiting ${RATE_LIMIT_NO_HINT_RETRY_S}s`}) — retrying the agent run once`
                     : pi.backendKind === "stream-severed"
-                        ? "provider severed the in-flight stream (terminated) — retrying the pi run once"
+                        ? "provider severed the in-flight stream (terminated) — retrying the agent run once"
                         : pi.backendKind === "timeout"
-                            ? "provider request timed out after accepting the connection — retrying the pi run once"
-                            : "model server timed out an idle predict stream (e.g. machine sleep) — retrying the pi run once");
+                            ? "provider request timed out after accepting the connection — retrying the agent run once"
+                            : "model server timed out an idle predict stream (e.g. machine sleep) — retrying the agent run once");
             // The failed attempt folds NOW, before the wait and the retry: a 429 it ended on is the
-            // fleet-wide rate-limit hold's input (LoopRunner.lastRateLimit, stamped at fold time), and
+            // team-wide rate-limit hold's input (LoopRunner.lastRateLimit, stamped at fold time), and
             // folding after a retry that ran on for an hour would report the storm an hour late.
             fold(pi);
             // The pause is the rate-limit branch's, plus the timeout kind's: a server timeout or
@@ -224,6 +277,7 @@ export class LoopPi {
             // partial progress is not re-done. The next tick still starts fresh.
             const retry = await runPi({ ...opts, continueSession: true });
             this.warnFallbackClone(retry);
+            this.observeFreeModelCost(retry, opts.config);
             if (foldFinal)
                 fold(retry);
             this.warnBackendKindFloor(retry);
@@ -237,8 +291,8 @@ export class LoopPi {
     /** The backend-kind floor (BUGS.md 2026-09-29): a failed run that ended on a
      * provider-backend failure (connection down, 5xx, model load) still warns — parity with
      * the 429 branch above, so any episode is visible from the feed alone instead of living
-     * only in per-tick error events an operator must aggregate by hand. The fleet-wide hold
-     * (src/fleet/fleet-hold.ts) and the storm alarms judge the spread; this line is the per-run
+     * only in per-tick error events an operator must aggregate by hand. The team-wide hold
+     * (src/team/team-hold.ts) and the storm alarms judge the spread; this line is the per-run
      * floor under them, not a retry: a dead backend is not something an immediate re-run beats.
      * Applied to whichever run is returned (BUGS.md 2026-10-09): the retry's returned run is a
      * second, independent run the retry predicate was never applied to, so a retry that dies
@@ -253,7 +307,7 @@ export class LoopPi {
             !run.quietKilled &&
             run.transientBackend &&
             !this.retryCoversBackendKind(run)) {
-            this.host.warn(`provider backend failure (${backendKindPhrase(run.backendKind)}) — the transient retry does not cover this kind; the fleet-wide hold watches for a storm`);
+            this.host.warn(`provider backend failure (${backendKindPhrase(run.backendKind)}) — the transient retry does not cover this kind; the team-wide wait watches for a storm`);
         }
     }
     /** Whether the one bounded transient retry admits `run` on its backend-kind alone: the
@@ -271,13 +325,13 @@ export class LoopPi {
     warnFallbackClone(run) {
         if (!run.fallbackClone)
             return;
-        this.host.warn(`pi could not resolve the model id exactly (${run.fallbackClone}) — the run uses the provider default's price and context window; add an exact entry to ~/.pi/agent/models.json`);
+        this.host.warn(`pi could not resolve the model id exactly (${run.fallbackClone}) — the run uses the provider default's price and context window; add an exact entry to ${piModelsPath()}`);
     }
     /** Run pi for this loop's authoring run in worktree `wt`: the shared per-loop wiring and
      * the transient-failure retry, with usage folded into the tick's counters. It is the ONE
      * entry point that carries the role notebook (PLANS.md "Role notebook": TUMWATER_NOTES_PATH,
-     * read by the bundled role-notes extension): every other run (runRolePi's landing/conflict path,
-     * runLandingPi, runGatePi) leaves it unset, and the director is excluded because its work is
+     * read by the `tumwater-notes` command): every other run (runRolePi's merge/conflict path,
+     * runMergePi, runGatePi) leaves it unset, and the director is excluded because its work is
      * the operator's prompt, not a recurring search.
      *
      * Every run starts a FRESH pi session: context never accumulates across ticks, so ticks start
@@ -290,22 +344,21 @@ export class LoopPi {
     }
     /** The notebook path an authoring run carries: the role's note file, or undefined for the
      * director, which has no notebook. The SUMMARY/stage-fix follow-ups share the authoring
-     * tick's session and must carry the same notes wiring — claude re-passes `--mcp-config` on
-     * every invocation because it keeps no flags across `--continue`, and pi reads
-     * TUMWATER_NOTES_PATH from the environment. */
+     * tick's session and must carry the same notes wiring — every invocation reads the path
+     * from TUMWATER_NOTES_PATH in the environment, so the follow-up re-passes the same path. */
     authorNotesPath() {
         return this.host.role === DIRECTOR_ROLE
             ? undefined
             : roleNotesPath(this.host.root, this.host.role);
     }
-    /** The shared authoring/conflict run wiring WITHOUT the role notebook. The landing merge's
+    /** The shared authoring/conflict run wiring WITHOUT the role notebook. The merge pipeline's
      * conflict resolver reaches pi through this (plans/merge-queue.md), and a conflict resolution
      * is not the role's recurring search: it must not carry the notes tool or rewrite the note.
      * Authoring ticks run through runAuthoringPi above, which is the only notebook-carrying path. */
     async runRolePi(wt, prompt, sessionName, resume = false, config) {
-        // The refusal-note landing (loop.ts's merge) reaches pi here, in the ROLE's own worktree,
+        // The refusal-note merge (loop.ts's merge) reaches pi here, in the ROLE's own worktree,
         // so its runs demux as author — exactly the verdict the pre-part-1/5 cwd test gave them.
-        // The shared-worktree conflict resolver goes through runLandingPi and demuxes as gate.
+        // The shared-worktree conflict resolver goes through runMergePi and demuxes as gate.
         return this.runWithTransientRetry(this.loopPiOpts(wt, prompt, sessionName, "author", resume, config));
     }
     /** Hard caps on the SUMMARY follow-up turn: it should take one short reply on a warm session,
@@ -331,7 +384,7 @@ export class LoopPi {
      * authoring run's budget: one short reply on a warm session. The run takes the loop's SHARED
      * transient-failure retry (BUGS.md 2026-10-01): a 429 on the follow-up turn waits its
      * Retry-After hint out and retries once on the same session, exactly like the authoring run,
-     * the landing slot's run, and the gate's reviewer runs it mirrors. The caps bound BOTH
+     * the merge slot's run, and the gate's reviewer runs it mirrors. The caps bound BOTH
      * attempts (the retry inherits this capped config), so a flaky provider cannot stretch the
      * follow-up past its budget by more than one capped turn. The wiring folds every attempt
      * (the failed 429 before the wait), and the returned final run is folded here by the wiring
@@ -341,12 +394,13 @@ export class LoopPi {
         const dir = sessionDir(this.host.root, this.host.role);
         // The follow-up continues THIS tick's author session. The backend's own resumable rule
         // keeps it honest: pi would reach the newest file, claude its recorded id, so a conflict
-        // resolver's gate run in the same dir cannot be mistaken for this tick's session.
-        if (!agentSessionResumable(dir, { kind: "author", agent: cfg.agent ?? "pi" })) {
+        // resolver's gate run in the same dir cannot be mistaken for this tick's session. The
+        // claude config dir rides along so a claude team's resume looks under its own dir.
+        if (!agentSessionResumable(dir, { kind: "author", agent: cfg.agent ?? "pi" }, resolvedAgentConfig(cfg, "claude").configDir)) {
             return null;
         }
         return this.runWithTransientRetry({
-            ...this.loopPiOpts(wt, prompt, `tumwater-${this.host.role}-${this.host.tickNumber()}-${suffix}`, "author", true, undefined, this.authorNotesPath()),
+            ...this.loopPiOpts(wt, prompt, `tumwater-${this.host.role}-${this.host.tickNumber()}-${suffix}`, "author", true, cfg, this.authorNotesPath()),
             config: {
                 ...cfg,
                 ...cappedRequestTimeouts(cfg, timeoutS, LoopPi.SUMMARY_REQUEST_QUIET_S),
@@ -357,8 +411,8 @@ export class LoopPi {
      * bounded turn, folded into the tick's usage like every other run. Null when there is no
      * session to continue (pi never wrote one) — the caller then derives a subject itself. The
      * run is returned even when it failed so the caller can honor a shutdown abort. */
-    async requestSummary(wt, config) {
-        return this.requestFollowUp(wt, buildSummaryRequestPrompt(), "summary", LoopPi.SUMMARY_REQUEST_TIMEOUT_S, config);
+    async requestSummary(wt, config, overLength) {
+        return this.requestFollowUp(wt, buildSummaryRequestPrompt(overLength), "summary", LoopPi.SUMMARY_REQUEST_TIMEOUT_S, config);
     }
     /** Ask the tick's own pi session (--continue) to fix the pre-queue self-check's findings:
      * one bounded turn, folded into the tick's usage like every other run. Null when there is no

package/dist/src/loop/loop-recovery.js

@@ -1,6 +1,6 @@
 import { setRef } from "../git/git.js";
 import { resetWorktreeToMain } from "../git/worktree.js";
-import { landingRefName } from "../paths.js";
+import { mergeRefName } from "../paths.js";
 import { shortSha } from "../text/format.js";
 /** Finish a tick whose pi run was killed mid-flight — shared by the author-run and review-
  * gate abort branches, which have identical semantics; only what the kill left behind
@@ -33,38 +33,38 @@ export async function finishAbortedTickPhase(ctx, userPrompt, wt, userAborted, h
     // prompt says the run was moved back to the primary model, not that the harness restarted.
     return handedBack ? { result: "aborted", resumeCause: "budget-resumed" } : { result: "aborted" };
 }
-/** Pin `sha` by this role's landing ref and free the worktree (plans/merge-queue.md invariant
+/** Pin `sha` by this role's merge ref and free the worktree (plans/merge-queue.md invariant
  * 4): the pin must exist BEFORE resetWorktreeToMain moves the branch, or the commit is
  * orphaned. Returns false when the pin write failed — the caller then leaves the commit on its
  * branch (no reset) and defers to next-tick recovery, which adopts it into the pin scheme.
- * After a successful pin the review gate and the rebase run in the vet's leased pool slot —
- * never in this worktree (merge queue 2/5). */
+ * After a successful pin the review gate and the rebase run in the verification's leased pool
+ * slot, never in this worktree (merge queue 2/5). */
 export async function pinAndResetPhase(ctx, wt, sha) {
-    const pinned = await setRef(ctx.root, landingRefName(ctx.role), sha);
+    const pinned = await setRef(ctx.root, mergeRefName(ctx.role), sha);
     if (!pinned) {
-        ctx.warn(`failed to pin ${shortSha(sha)} by its landing ref — leaving the commit on the branch for next-tick recovery`);
+        ctx.warn(`failed to pin ${shortSha(sha)} by its merge ref — leaving the commit on the branch for the next run's recovery`);
         return false;
     }
     await resetWorktreeToMain(wt, ctx.mainBranch);
     return true;
 }
 /** End a tick whose leftover recovery found work to salvage (src/loop/leftover.ts) without an
- * authoring run — the leftover owns the role's one landing ref until its landing resolves. A
+ * authoring run — the leftover owns the role's one merge ref until its merge resolves. A
  * tick's dequeued user prompt goes back to its queue, since nothing ran it. A pin put on
- * the land queue ends the tick `queued` exactly like a fresh changed tick (the land-queue
- * interlock then holds the role until the slot lands it) and frees the worktree, the pin now
- * holding the commit. When the pin is left over from a landing that failed non-terminally
- * (`priorLandingFailure`), re-queuing it is a retry of a PERSISTENT failure the `queued` result
+ * the merge queue ends the tick `queued` exactly like a fresh changed tick (the merge-queue
+ * interlock then holds the role until the slot merges it) and frees the worktree, the pin now
+ * holding the commit. When the pin is left over from a merge that failed non-terminally
+ * (`priorMergeFailure`), re-queuing it is a retry of a PERSISTENT failure the `queued` result
  * cannot express, so it rides the outcome's recoveryFailure into the error streak and the
- * warning that names the stuck gate (BUGS.md 2026-09-21). A role whose landing is still queued
+ * warning that names the stuck gate (BUGS.md 2026-09-21). A role whose merge is still queued
  * ends `queued` on that entry — nothing enqueued twice, nothing reset. A leftover that could
  * not be pinned stays on the branch and the tick fails like a fresh tick's failed pin. Every
  * arm is `recoveredLeftover`: no model ran, so the tick is no evidence about the backend. */
-export async function finishRecoveryTickPhase(ctx, recovered, userPrompt, wt, priorLandingFailure) {
+export async function finishRecoveryTickPhase(ctx, recovered, userPrompt, wt, priorMergeFailure) {
     ctx.pending.clear();
     ctx.pending.requeueUnfulfilled(userPrompt);
     if (recovered.kind === "unpinned") {
-        ctx.state.lastError = `failed to pin leftover ${shortSha(recovered.sha)} by its landing ref; left for next-tick recovery`;
+        ctx.state.lastError = `failed to pin leftover ${shortSha(recovered.sha)} by its merge ref; left for the next run's recovery`;
         return { result: "error", summary: ctx.state.lastError, recoveredLeftover: true };
     }
     if (recovered.kind === "held") {
@@ -77,7 +77,7 @@ export async function finishRecoveryTickPhase(ctx, recovered, userPrompt, wt, pr
     }
     const { entry } = recovered;
     if (recovered.kind === "enqueued") {
-        ctx.setRecoveryFailure(priorLandingFailure);
+        ctx.setRecoveryFailure(priorMergeFailure);
         await resetWorktreeToMain(wt, ctx.mainBranch);
     }
     return {