tumwater 0.1.2 → 0.2.0

package/dist/src/loop/loop.js

@@ -1,10 +1,12 @@
 import { loadLoopState, saveLoopState, zeroCounters } from "./loop-state.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { baseRoleOf } from "../roles/loop-ids.js";
-import { warnEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { promptPreview } from "../inbox/inbox.js";
 import { assembleTickPrompt } from "../tick/tick-prompt.js";
 import { LoopPi } from "./loop-pi.js";
-import { configForRole, fallbackRoleConfig, seamHoldKey, } from "../config/config-views.js";
+import { configForRole, seamHoldKey, withModelOverrides, } from "../config/config-views.js";
+import { fallbackRoleConfig } from "../config/config-fallbacks.js";
 import { PendingPrompt } from "../inbox/pending-prompt.js";
 import { modelFallbackActive } from "./model-fallback.js";
 import { clearBackoff } from "../scheduling/backoff.js";
@@ -26,20 +28,20 @@ export class LoopRunner {
      * tick intervals, backoff, and role enablement for subsequent ticks. */
     config;
     /** The 429 observation from this loop's usage accounting (TickUsage.lastRateLimit,
-     * src/tick/tick-usage.ts): the orchestrator's fleet-wide hold wiring reads it through the
-     * runner (src/fleet/fleet-polls.ts), so the field keeps its place on the runner's surface. */
+     * src/tick/tick-usage.ts): the orchestrator's team-wide hold wiring reads it through the
+     * runner (src/team/team-polls.ts), so the field keeps its place on the runner's surface. */
     get lastRateLimit() {
         return this.usage.lastRateLimit;
     }
     /** The backend-failure observation (TickUsage.lastBackendFailure, src/tick/tick-usage.ts): the
      * non-429 sibling of lastRateLimit above — the connection, timeout, server, and model-load
-     * kinds the fleet-wide hold groups storms by (src/fleet/fleet-hold.ts). Same runner surface,
+     * kinds the team-wide hold groups storms by (src/team/team-hold.ts). Same runner surface,
      * same consumer. */
     get lastBackendFailure() {
         return this.usage.lastBackendFailure;
     }
     /** Per-tick and lifetime usage accounting (src/tick/tick-usage.ts): the turns/cost windows the
-     * commit trailer and tick_end event read, the lifetime totals folded into state, and the
+     * commit trailer and run_end event read, the lifetime totals folded into state, and the
      * observations above. Grown through foldUsage — the once-per-run choke point. */
     usage = new TickUsage();
     /** The dequeued user prompt a tick is executing and its requeue policy
@@ -49,7 +51,7 @@ export class LoopRunner {
     pending;
     /** Per-tick abort controller, recreated at every tick start: `abortTick()` kills the
      * in-flight pi run without touching the harness shutdown signal (`this.signal`), which
-     * would stop the whole fleet. */
+     * would stop the whole team. */
     tickAbort = new AbortController();
     /** Set by abortTick() when a user-initiated abort lands mid-tick: runTick's two abort
      * branches (author run, review gate) then diverge from shutdown semantics — worktree reset
@@ -70,7 +72,14 @@ export class LoopRunner {
      * resolve to, since different roles may run on different pairs.
      * Transient — never persisted — and captured fresh at every tick start. */
     tickPair;
-    /** The landing failure this tick's leftover recovery is retrying, if any (a retriable lander
+    /** Whether the budget gate currently has the team on its free fallback pairs (src/gates/
+     * budget-gates.ts onFallback, set alongside `config` by the orchestrator's poll): an
+     * image reroute may then look only among the free fallback pairs, never a priced primary
+     * (plans/image-input.md "Reroute target" "Regime"). Pure scheduler input, never whether
+     * the LOOP itself is mid-fallback; defaults false, so standalone-loop tests stay on the
+     * primary regime unless they set it. */
+    budgetFallbackActive = false;
+    /** The merge failure this tick's leftover recovery is retrying, if any (a retriable merger
      * outcome that kept the pin, which recovery re-queued): set in finishRecoveryTick and
      * attached to the returned TickOutcome so applyTickOutcome can feed it into the error streak
      * even though the tick itself ends `queued` (BUGS.md 2026-09-21). Reset at every tick start. */
@@ -102,9 +111,9 @@ export class LoopRunner {
             signal: this.signal,
             runSignal: () => this.runSignal(),
             warn: (message) => this.warn(message),
-            foldUsage: (run) => this.foldUsage(run),
-            foldLandingUsage: (run) => this.foldLandingUsage(run),
-            tickNumber: () => this.state.ticks,
+            foldUsage: (run, provider, pair) => this.foldUsage(run, provider, pair),
+            foldMergeUsage: (run, provider, pair) => this.foldMergeUsage(run, provider, pair),
+            tickNumber: () => this.state.runs,
             sleep: this.sleep,
         });
         // A persisted running flag means the previous process died mid-tick WITHOUT the
@@ -114,6 +123,7 @@ export class LoopRunner {
             this.state.resumePending = true;
         this.state.running = false;
         this.state.parkedSince = undefined;
+        this.state.parkedOn = undefined;
     }
     save() {
         saveLoopState(this.root, this.state);
@@ -143,7 +153,7 @@ export class LoopRunner {
      * when no tick is running — the orchestrator checks `state.running` before calling, and a
      * direct call must not arm a stale flag. Otherwise set the userAborted flag and abort the
      * per-tick controller: runPi terminates the in-flight pi child (SIGTERM → SIGKILL
-     * escalation) exactly like a harness shutdown, but only this loop's run dies — the fleet
+     * escalation) exactly like a harness shutdown, but only this loop's run dies — the team
      * keeps running. */
     abortTick() {
         if (!this.state.running)
@@ -173,7 +183,29 @@ export class LoopRunner {
      * active (a due probe runs the primary), else the role's own resolved config. The hold and
      * start passes read this so a role mid-episode is keyed by the provider it will actually use.
      * Pure read of config + state + the caller's clock. */
+    /** Which pair set an image reroute may look among (plans/image-input.md "Reroute target"
+     * "Regime"): the free fallback pairs while the budget gate is on fallback OR the role is
+     * in a model-fallback episode; otherwise the primary tiers. One home for the rule, shared
+     * by the target-resolution sites (the verdict's reroute arm, the attachment preflight). */
+    rerouteRegime(now) {
+        if (this.budgetFallbackActive)
+            return "fallback";
+        if (modelFallbackActive(this.state.modelFallback, now))
+            return "fallback";
+        return "primary";
+    }
     runConfig(now) {
+        // A pending image-input reroute (plans/image-input.md part 4/5) outranks the role's own
+        // tier and its model fallback: the next tick starts on the image-capable target the
+        // blind-read tick recorded, rebuilt from the stored seam over the live config.
+        if (this.state.imageReroute) {
+            const r = this.state.imageReroute;
+            return withModelOverrides(this.config, r.tier, {
+                provider: r.provider,
+                model: r.model,
+                thinking: r.thinking,
+            });
+        }
         const fallback = fallbackRoleConfig(this.config, this.role);
         if (fallback !== null && modelFallbackActive(this.state.modelFallback, now))
             return fallback;
@@ -196,10 +228,13 @@ export class LoopRunner {
      * runner records it as pending — re-queued if the tick ends without fulfilling it. Null when
      * the loop has nothing to run (an empty director inbox); a role loop's assembly never
      * returns null. */
-    tickPrompt(agent) {
-        const assembled = assembleTickPrompt({ root: this.root, config: this.config, role: this.role, state: this.state, agent });
+    tickPrompt(agent, compact) {
+        const assembled = assembleTickPrompt({ root: this.root, config: this.config, role: this.role, state: this.state, agent, compact });
         if (assembled === null)
             return null;
+        if (assembled.userPrompt !== null) {
+            logEventBestEffort(this.root, { source: this.role, type: "prompt_taken", run: this.state.runs, preview: promptPreview(assembled.userPrompt) });
+        }
         this.pending.record(assembled.userPrompt, assembled.userPromptFile);
         return assembled.prompt;
     }
@@ -212,45 +247,45 @@ export class LoopRunner {
         return pinAndResetPhase(this.tickContext(), wt, sha);
     }
     /** Thin delegate to finishRecoveryTickPhase (src/loop/loop-recovery.ts). */
-    async finishRecoveryTick(recovered, userPrompt, wt, priorLandingFailure) {
-        return finishRecoveryTickPhase(this.tickContext(), recovered, userPrompt, wt, priorLandingFailure);
+    async finishRecoveryTick(recovered, userPrompt, wt, priorMergeFailure) {
+        return finishRecoveryTickPhase(this.tickContext(), recovered, userPrompt, wt, priorMergeFailure);
     }
     /** Fold one pi run's usage into the tick's counters and the lifetime totals — the
      * accounting itself lives in TickUsage.fold (src/tick/tick-usage.ts); this keeps the once-per-run
-     * choke point and the foldLandingUsage face on the runner, where LoopPi and the landing
-     * wiring (src/landing/landing-slot.ts) reach them. */
-    foldUsage(run) {
-        this.usage.fold(this.state, run);
+     * choke point and the foldMergeUsage face on the runner, where LoopPi and the merge
+     * wiring (src/merge/merge-slot.ts) reach them. */
+    foldUsage(run, provider, pair) {
+        this.usage.fold(this.state, run, true, provider, pair);
     }
-    /** Run pi for the orchestrator's landing slot (merge queue 3/5): runRolePi's shared wiring
+    /** Run pi for the orchestrator's merge slot (merge queue 3/5): runRolePi's shared wiring
      * with usage folded into this loop's counters, watching ONLY the harness shutdown signal
-     * (`this.signal`) — a landing is outside any tick, so `tumwater abort --role` must never
-     * reach it. The plumbing lives in src/loop/loop-pi.ts; this is the landing slot's public
+     * (`this.signal`) — a merge is outside any tick, so `tumwater abort --role` must never
+     * reach it. The plumbing lives in src/loop/loop-pi.ts; this is the merge slot's public
      * face. */
-    async runLandingPi(wt, prompt, sessionName, config) {
-        return this.pi.runLandingPi(wt, prompt, sessionName, config);
+    async runMergePi(wt, prompt, sessionName, config) {
+        return this.pi.runMergePi(wt, prompt, sessionName, config);
     }
-    /** Run pi for the landing gate's reviewer (the review run and its verdict follow-up)
+    /** Run pi for the merge gate's reviewer (the review run and its verdict follow-up)
      * through the loop's shared transient-retry wiring — the same retry an authoring run gets,
      * so a 429 in the gate is waited out and retried once instead of failing the review on
      * first contact (BUGS.md 2026-10-01). A retried first attempt is folded here at retry time
-     * (the fleet-wide rate-limit hold's input); the FINAL run's usage is folded by the gate's
+     * (the team-wide rate-limit hold's input); the FINAL run's usage is folded by the gate's
      * caller, exactly as before — the plumbing lives in src/loop/loop-pi.ts; this is the
-     * landing wiring's public face. */
+     * merge wiring's public face. */
     async runGatePi(opts) {
         return this.pi.runGatePi(opts);
     }
-    /** Public face of foldUsage for the orchestrator's landing wiring: folds a landing pi run
-     * (reviewer, conflict resolution) into the AUTHORING role's counters, so the fleet's daily
+    /** Public face of foldUsage for the orchestrator's merge wiring: folds a merge pi run
+     * (reviewer, conflict resolution) into the AUTHORING role's counters, so the team's daily
      * cost and the per-role usage windows attribute that spend to the role that authored the
      * work — no new counter semantics, just the same fold loop.ts applies to its tick runs. */
-    foldLandingUsage(run) {
-        // authoring=false: a landing/review run's usage counts toward cost and prompt tokens, but
+    foldMergeUsage(run, provider, pair) {
+        // authoring=false: a merge/review run's usage counts toward cost and prompt tokens, but
         // never toward the tick's pre-edit counter (src/tick/tick-usage.ts fold).
-        this.usage.fold(this.state, run, false);
+        this.usage.fold(this.state, run, false, provider, pair);
     }
     /** Run one full tick of this role loop (the pipeline lives in src/loop/loop-tick.ts):
-     * `tickPhase` resolves the config and fallback episode, logs tick_start, runs the pipeline,
+     * `tickPhase` resolves the config and fallback episode, logs run_start, runs the pipeline,
      * and finalizes. Never throws: a failed tick is an "error" result, saved and logged. */
     async tick() {
         return tickPhase(this.tickContext());
@@ -284,7 +319,8 @@ export class LoopRunner {
             save: () => this.save(),
             warn: (message) => this.warn(message),
             runSignal: () => this.runSignal(),
-            tickPrompt: (agent) => this.tickPrompt(agent),
+            tickPrompt: (agent, compact) => this.tickPrompt(agent, compact),
+            rerouteRegime: (now) => this.rerouteRegime(now),
             get recoveryFailure() {
                 return self.recoveryFailure;
             },
@@ -305,7 +341,7 @@ export class LoopRunner {
             finishAbortedTick: (userPrompt, wt) => this.finishAbortedTick(userPrompt, wt),
             pinAndReset: (wt, sha) => this.pinAndReset(wt, sha),
             foldModelFallback: (fallbackCtx, pi) => this.foldModelFallback(fallbackCtx, pi),
-            finishRecoveryTick: (recovered, userPrompt, wt, priorLandingFailure) => this.finishRecoveryTick(recovered, userPrompt, wt, priorLandingFailure),
+            finishRecoveryTick: (recovered, userPrompt, wt, priorMergeFailure) => this.finishRecoveryTick(recovered, userPrompt, wt, priorMergeFailure),
         };
     }
 }

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

@@ -15,11 +15,12 @@ export function modelFallbackProbe(state, now) {
     return state !== undefined && state.since > 0 && now >= state.probeAt;
 }
 /** Classify one authoring run's verdict about the primary (src/tick/tick-usage.ts records the
- * same flags for the fleet-wide hold). A run that was aborted, quiet-killed, or timed out is
+ * same flags for the team-wide hold). A run that was aborted, quiet-killed, or timed out — or
+ * that read an image its model cannot see (the runner killed it, plans/image-input.md) — is
  * inconclusive even when it also reports provider evidence: the harness killed it, so it is
  * no verdict about the primary's health. */
 export function modelFallbackVerdict(pi) {
-    if (pi.aborted || pi.quietKilled || pi.timedOut)
+    if (pi.aborted || pi.quietKilled || pi.timedOut || pi.imageBlind)
         return "inconclusive";
     if (!pi.ok && (pi.transientRateLimit || pi.transientBackend))
         return "provider-failure";

package/dist/src/loop/revision.js

@@ -1,15 +1,24 @@
 import { gitTry } from "../git/git-run.js";
 import { resetWorktreeToMain } from "../git/worktree.js";
-import { conflictedFiles } from "../landing/landing-git.js";
-/** The most revision rounds one rejected change gets before its rejection is final
- * (plans/revise-rejected.md): the gate rejected the change, the author re-applies the rejected
- * diff onto current main, fixes the named objections and re-submits. Past this the change is
- * dropped and a plain rejection stands, so a non-converging author cannot revise forever. */
-export const REVISION_LIMIT = 2;
+import { conflictedFiles } from "../merge/merge-git.js";
+/** The persistence count at which one repeated objection makes a rejection final
+ * (plans/revise-rejected.md; the repeat-finality policy in BUGS.md 2026-10-14): each numbered
+ * reason records how many consecutive revisions it has survived — a new (untagged) objection is
+ * 0, a `(prior N)` restatement is 1 plus the prior round's count for that objection — and when
+ * any reason reaches this count it was raised and then survived two revisions, so the change has
+ * stopped converging and the rejection is final. A converging chain keeps revising while each
+ * round's objections differ. */
+export const REVISION_FINAL_ON_REPEAT = 2;
+/** The hard backstop on one change's revision chain (plans/revise-rejected.md; BUGS.md
+ * 2026-10-14): at this many total rejections the rejection is final even when the objections
+ * never repeat, so a non-converging author cannot revise forever. Replaces the old fixed
+ * `REVISION_LIMIT = 2`, which ended a converging chain at its third rejection whenever each
+ * round raised a new objection. */
+export const REVISION_BACKSTOP = 6;
 /** Re-apply a rejected change `sha` onto current main as uncommitted edits in `wt`
  * (plans/revise-rejected.md): the author's next tick starts from the rejected diff instead of
  * re-deriving it. `git cherry-pick --no-commit <merge-base>..<sha>` leaves the edits in the
- * worktree without committing. On any git failure — most often a conflict with what main landed
+ * worktree without committing. On any git failure — most often a conflict with what main merged
  * since the rejection, but also a missing object — the cherry-pick is aborted and the worktree
  * reset to main, and false is returned so the caller falls back to a plain rejection note. */
 export async function applyRevision(wt, mainBranch, sha) {

package/dist/src/merge/backlog-conflicts.js

@@ -0,0 +1,155 @@
+/** Deterministic first pass over a conflicted rebase for the backlog markdown files
+ * (plans/parallel-work-instances.md, "Insert-only backlog conflicts", part 3/7).
+ *
+ * Every finished entry lands as the first one under `## Done` or `## Fixed` — at the top of
+ * PLANS-DONE.md or BUGS-FIXED.md once tumwater archives it (plans/backlog-archive.md) — so two
+ * merges off the same base insert different entries at the same location. Git's diff3 conflict
+ * for that shape has an empty base section and both sides non-empty; keeping both inserted sides
+ * adds no authored bytes, so no model run is needed.
+ *
+ * One more shape settles the same way: inside a live `## Done`/`## Fixed` section, the change
+ * added whole `### ` entries right above lines that main has since removed or rewritten — a
+ * change committed before its repository's history moved to the archive, whose entries sat
+ * right below the insertion point. The change's side is then its new entries followed by
+ * exactly the base lines, and keeping those entries on top of main's side again adds no
+ * authored bytes. Anything else — the same entry edited on both sides, a code file, a deleted
+ * side — goes to the pi resolver untouched. */
+import fs from "node:fs";
+import path from "node:path";
+import { BACKLOG_FILES, FINISHED_ARCHIVES } from "../backlog/backlog-md.js";
+import { writeTextAtomic } from "../files/files.js";
+import { git } from "../git/git-run.js";
+/** The lines the change inserted in `hunk`, when it is one of the two shapes this pass settles,
+ * or null. Insert-only: an empty base section and both sides carrying lines — all of the
+ * change's side. Entries above a rewritten history (see the module comment): the hunk sits in a
+ * finished section, and the change's side is whole `### ` entries followed by exactly the base
+ * lines — the part before them. */
+function insertedLines(hunk, lines) {
+    if (hunk.base.length === 0)
+        return hunk.ours.length > 0 && hunk.theirs.length > 0 ? hunk.theirs : null;
+    if (!inFinishedSection(lines, hunk.start) || hunk.theirs.length <= hunk.base.length)
+        return null;
+    const cut = hunk.theirs.length - hunk.base.length;
+    if (hunk.theirs.slice(cut).some((line, i) => line !== hunk.base[i]))
+        return null;
+    const inserted = hunk.theirs.slice(0, cut);
+    const first = inserted.find((line) => line.trim() !== "");
+    return first?.startsWith("### ") ? inserted : null;
+}
+/** True when the nearest `## ` heading above line `at` is a finished section (`## Done` or
+ * `## Fixed`), with no conflict marker in between — an earlier hunk's sides leave the section
+ * unknown, so the answer is then no. */
+function inFinishedSection(lines, at) {
+    for (let i = at - 1; i >= 0; i--) {
+        const line = lines[i] ?? "";
+        if (/^(<{7}|\|{7}|={7}|>{7})/.test(line))
+            return false;
+        if (line.startsWith("## "))
+            return FINISHED_SECTIONS.has(line.slice(3).trim());
+    }
+    return false;
+}
+/** The finished sections' titles, from FINISHED_ARCHIVES. */
+const FINISHED_SECTIONS = new Set(FINISHED_ARCHIVES.map((a) => a.section));
+/** Rewrite every settleable conflict hunk in `text` and return the result, or null when any
+ * hunk is neither shape insertedLines accepts (or the markers are malformed) — the caller then
+ * leaves the file for the model resolver. Each hunk is replaced by the lines the change (theirs)
+ * inserted, a blank separator when neither side already supplies one, then main's (ours)
+ * lines, so the later merge stays first. */
+export function resolveInsertOnlyText(text) {
+    const lines = text.split("\n");
+    const hunks = parseHunks(lines);
+    if (hunks === null)
+        return null;
+    if (hunks.length === 0)
+        return null;
+    const inserted = hunks.map((hunk) => insertedLines(hunk, lines));
+    if (inserted.some((ins) => ins === null))
+        return null;
+    // Replace from the end so earlier indices stay valid.
+    for (let h = hunks.length - 1; h >= 0; h--) {
+        const hunk = hunks[h];
+        const theirs = inserted[h];
+        const separated = hunk.ours.length === 0 || theirs[theirs.length - 1] === "" || hunk.ours[0] === "";
+        const replacement = separated ? [...theirs, ...hunk.ours] : [...theirs, "", ...hunk.ours];
+        lines.splice(hunk.start, hunk.end - hunk.start + 1, ...replacement);
+    }
+    return lines.join("\n");
+}
+/** Split `lines` into conflict hunks. Returns null when a marker sequence is malformed (an
+ * unterminated hunk, or a missing `|||||||`/`=======`), so the caller can bail out. */
+function parseHunks(lines) {
+    const hunks = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (!lines[i].startsWith("<<<<<<<")) {
+            i++;
+            continue;
+        }
+        const start = i;
+        const ours = [];
+        const base = [];
+        const theirs = [];
+        // Consume each side up to its marker (the `<<<<<<<` line itself is skipped by starting
+        // at i + 1); a missing marker means the diff3 hunk is malformed and the parse aborts.
+        const afterOurs = collectUntilMarker(lines, i + 1, "|||||||", ours);
+        if (afterOurs === null)
+            return null; // no base marker
+        const afterBase = collectUntilMarker(lines, afterOurs, "=======", base);
+        if (afterBase === null)
+            return null; // no separator
+        const afterTheirs = collectUntilMarker(lines, afterBase, ">>>>>>>", theirs);
+        if (afterTheirs === null)
+            return null; // no end marker
+        hunks.push({ start, end: afterTheirs - 1, ours, base, theirs });
+        i = afterTheirs;
+    }
+    return hunks;
+}
+/** Append lines from `start` into `into` until one starts with `marker` (the marker itself is
+ * consumed, not kept), and return the index just past it. Returns null when no line from
+ * `start` on carries the marker — the malformed-hunk signal parseHunks turns into a bail-out.
+ * The one home of the drain-until-marker step shared by parseHunks's three sides, so the
+ * marker-consumption rule cannot drift between `|||||||`, `=======`, and `>>>>>>>`. */
+function collectUntilMarker(lines, start, marker, into) {
+    let i = start;
+    while (i < lines.length && !lines[i].startsWith(marker))
+        into.push(lines[i++]);
+    return i >= lines.length ? null : i + 1;
+}
+/** Settle the insert-only conflicts among `files` in `wt` (plans/parallel-work-instances.md,
+ * part 3/7): every conflicted repo-root backlog file (BACKLOG_FILES: PLANS.md, BUGS.md,
+ * QUESTIONS.md and the two archive files) whose hunks all settle is rewritten without markers and
+ * staged. Returns the files still conflicted —
+ * every file that was not fully settled, including non-backlog files and files with any other
+ * hunk — so the caller runs the model resolver only over those. */
+export async function resolveBacklogInsertConflicts(wt, files) {
+    const remaining = [];
+    for (const file of files) {
+        if (path.dirname(file) !== "." || !BACKLOG_FILES.has(file)) {
+            remaining.push(file);
+            continue;
+        }
+        const p = path.join(wt, file);
+        let text;
+        try {
+            text = fs.readFileSync(p, "utf8");
+        }
+        catch {
+            remaining.push(file); // deleted side or unreadable path — leave it to the resolver
+            continue;
+        }
+        const resolved = resolveInsertOnlyText(text);
+        if (resolved === null) {
+            remaining.push(file);
+            continue;
+        }
+        // Atomic (tmp + rename): a merge process killed mid-write (SIGKILL, the timeout
+        // group-kill) must leave either the conflicted file or the fully resolved one, never a
+        // truncated backlog — the CLI's backlog writers (backlog-write.ts, question-answer.ts)
+        // already write these unbounded-history files through this helper.
+        writeTextAtomic(p, resolved);
+        await git(wt, "add", "--", file);
+    }
+    return remaining;
+}