tumwater 0.4.0 → 0.4.2

package/dist/src/run/stage-backlog-checks.js

@@ -6,10 +6,9 @@
 import { finishedTitle, readdedHeadings } from "../backlog/backlog-structure.js";
 import { fenceAwareHeadingLines, headingTitle, parseEntryDetails, sectionBodyLines, } from "../backlog/backlog-md.js";
 import { DONE_DATE_RE, FIXED_DATE_RE } from "../backlog/backlog.js";
-import { refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
+import { refusalNote } from "../backlog/backlog-eligibility.js";
 import { entryKey, partKey, planDependencyProblems, seriesPart } from "../backlog/backlog-parts.js";
-import { WAITING_FOR_FAILURE_NOTE } from "../roles/role-guidance.js";
-import { moreSuffix } from "../text/phrases.js";
+import { moreSuffix, plural } from "../text/phrases.js";
 import { collapseWhitespace, truncate } from "../text/text.js";
 /** The finding for the heading `requires` clause problems that `head` (the edited PLANS.md)
  * adds over `base` (its text at the merge-base), or undefined when it adds none; `archivedTitles`
@@ -90,31 +89,6 @@ export function finishedDuplicateFindings(spec, live, archive) {
     }
     return findings;
 }
-/** The number of `- **Progress …` lines in an entry body. */
-function progressCount(body) {
-    return body.split("\n").filter((l) => /^-\s+\*\*Progress\b/.test(l.trim())).length;
-}
-/** The finding for a BUGS.md bug that `head` (the edited file) shows with more Progress notes
- * than `base` (its text at the merge-base) while it stays under `## Open` with neither a Waiting
- * note nor a Refused note — bugfix's step 2 asks a run that cannot reproduce a bug to write the
- * Waiting note, and runs that skip it leave the bug open to re-investigation. A newly filed bug
- * is not a re-investigation. Names the first such bug in file order, with a count of the rest. */
-export function waitingNoteFinding(head, base) {
-    const was = new Map(parseEntryDetails(base, "Open").map((e) => [entryKey(e.title), e.body]));
-    const counting = parseEntryDetails(head, "Open").filter((e) => {
-        const before = was.get(entryKey(e.title));
-        return (before !== undefined &&
-            progressCount(e.body) > progressCount(before) &&
-            waitingNote(e.body) === null &&
-            refusalNote(e.body) === null);
-    });
-    if (counting.length === 0)
-        return undefined;
-    return (`BUGS.md bug "${counting[0].title}" gained a Progress note but stays open with no Waiting for the next ` +
-        `failure note — if this run could not reproduce it, add ${WAITING_FOR_FAILURE_NOTE} as its own line under ` +
-        `the heading so later runs wait for new evidence (bugfix's step 2); if it did reproduce, leave the entry ` +
-        `as it is${moreSuffix(counting.length - 1)}`);
-}
 /** The skeleton placeholder that marks an empty backlog section. */
 const PLACEHOLDER_LINE = "_None yet._";
 /** The live backlog files; the archives have no placeholder sections. */
@@ -142,7 +116,7 @@ export function strayPlaceholderFinding(file, head, base) {
     if (stray.length === 0)
         return undefined;
     const [title, n] = stray[0];
-    return (`${file}'s "## ${title}" section holds ${n} entr${n === 1 ? "y" : "ies"}, but this change left the ` +
+    return (`${file}'s "## ${title}" section holds ${plural(n, "entry", "entries")}, but this change left the ` +
         `empty-section placeholder ${PLACEHOLDER_LINE} in it — delete that line: it marks a section with no ` +
         `entries${moreSuffix(stray.length - 1)}`);
 }
@@ -222,8 +196,7 @@ function groundedRefusalReason(reason, own) {
  * role's own notes, or a different series part (the `b9664a461` case). `head` is the edited
  * text, `base` its text at the merge-base. A refusal already on main is not this change's and
  * is skipped; only a newly added (or edited) one is judged. Names the first offending entry in
- * file order, with a count of the rest. Stages after `waitingNoteFinding`, sharing its guard.
- * Undefined when the change adds no such refusal. */
+ * file order, with a count of the rest. Undefined when the change adds no such refusal. */
 export function ungroundedRefusalFinding(file, head, base) {
     const refusalByKey = (md) => {
         const out = new Map();

package/dist/src/run/stage-check.js

@@ -43,14 +43,13 @@
  * not after `-`, `.` or `/`, "that that" and "had had" excepted). Like the path checks, the gate
  * does not run it.
  *
- * The backlog-record findings named below (`planDependencyFinding`, `waitingNoteFinding`,
+ * The backlog-record findings named below (`planDependencyFinding`,
  * `finishedDuplicateFindings`, `strayPlaceholderFinding`) live in stage-backlog-checks.ts, which
  * also holds the claim-move findings run-stage.ts uses.
  *
  * `planDependencyFinding` is staging-only: it is not part of the review gate or the in-lock
  * merge re-check, because `tumwater doctor`'s plan-dependency warning is the backstop for
- * anything that gets past the fix-up turn. `waitingNoteFinding` is staging-only and bugfix-only
- * for the same reason: it nudges a bugfix run that left a Progress note without the hold.
+ * anything that gets past the fix-up turn.
  * Like `planDependencyFinding`, `finishedDuplicateFindings` runs only at staging. The gate does
  * not run it, because the sweep that creates the second copy runs after it.
  * `strayPlaceholderFinding` is staging-only too. It flags a `_None yet._` line the change left in a
@@ -69,9 +68,8 @@ import { changeBaseRev, fileContentAt } from "../git/git.js";
 import { readTextOrNull } from "../files/files.js";
 import { FINISHED_ARCHIVES, finishedArchiveOf, parseEntryDetails, } from "../backlog/backlog-md.js";
 import { DONE_DATE_RE } from "../backlog/backlog.js";
-import { baseRoleOf } from "../roles/runner-ids.js";
 import { acceptanceGrepFindings } from "./acceptance-greps.js";
-import { PLACEHOLDER_FILES, finishedDuplicateFindings, finishedKey, planDependencyFinding, strayPlaceholderFinding, ungroundedRefusalFinding, waitingNoteFinding, } from "./stage-backlog-checks.js";
+import { PLACEHOLDER_FILES, finishedDuplicateFindings, finishedKey, planDependencyFinding, strayPlaceholderFinding, ungroundedRefusalFinding, } from "./stage-backlog-checks.js";
 import { gitLevelFindings } from "./stage-path-checks.js";
 /** Where finished plans are archived (plans/backlog-archive.md). */
 const PLANS_ARCHIVE = finishedArchiveOf("PLANS.md").archive;
@@ -97,7 +95,7 @@ const pushReason = async (findings, check) => {
 };
 /** The findings likely to get this uncommitted change rejected at merge, or an empty list when
  * it is clean: the merge gate's own deterministic checks plus the staging-only heuristics (plan
- * dependencies, the bugfix Waiting note, path drift). Checks the worktree at `wt` against
+ * dependencies, path drift). Checks the worktree at `wt` against
  * `mainBranch`'s merge-base; `exemptPaths` are the config's review-exemption globs that scope
  * the false-fix check.
  *
@@ -146,12 +144,6 @@ export async function stageCheckFindings(wt, mainBranch, exemptPaths, role) {
         })().catch(() => []);
         findings.push(...greps);
     }
-    if (baseRoleOf(role) === "bugfix" && files.includes("BUGS.md")) {
-        const { head, base } = await headAndBase(wt, mainBranch, "BUGS.md");
-        const waiting = base === undefined ? undefined : waitingNoteFinding(head, base);
-        if (waiting !== undefined)
-            findings.push(waiting);
-    }
     if (files.includes("BUGS.md")) {
         const { head, base } = await headAndBase(wt, mainBranch, "BUGS.md");
         const refusal = base === undefined ? undefined : ungroundedRefusalFinding("BUGS.md", head, base);

package/dist/src/run/stage-checks-shared.js

@@ -16,6 +16,21 @@ export const MAX_STALE_PATHS = 10;
 export function diffPlusPath(line) {
     return line.slice(4).replace(/^b\//, "");
 }
+/** Parse `git grep -n` stage output into `file:line:text` hits. `git grep -n` prints one
+ * `path:line:text` per match, and the four name/path checks (stage-name-checks.ts's
+ * staleNameFindings and movedNameFindings, stage-path-checks.ts's movedSourceFindings and
+ * staleReferenceFindings) all read that grammar to turn the raw output into individual hits;
+ * malformed (or trailing empty) lines are dropped. Callers then filter the hits and keep the
+ * `file:no` coordinate they want. */
+export function gitGrepHits(out) {
+    const hits = [];
+    for (const line of out.split("\n")) {
+        const m = /^([^:]+):(\d+):(.*)$/.exec(line);
+        if (m)
+            hits.push({ file: m[1], no: m[2], text: m[3] ?? "" });
+    }
+    return hits;
+}
 /** True for record prose: a backlog file (BACKLOG_FILES: PLANS.md, BUGS.md, QUESTIONS.md and the
  * finished-entry archives) or a markdown design doc under `plans/`. They record history and
  * describe planned work, so a path there is correct as written even when it is absent from the

package/dist/src/run/stage-name-checks.js

@@ -8,7 +8,7 @@
  * not run any of them. */
 import path from "node:path";
 import { gitTry } from "../git/git-run.js";
-import { JS_FILE, MAX_STALE_HITS, MAX_STALE_PATHS, cappedList, isRecordProse, standalonePathIndexes, } from "./stage-checks-shared.js";
+import { JS_FILE, MAX_STALE_HITS, MAX_STALE_PATHS, cappedList, gitGrepHits, isRecordProse, standalonePathIndexes, } from "./stage-checks-shared.js";
 /** How many removed identifiers one stale-name check looks up. */
 const MAX_STALE_NAMES = 40;
 /** The most characters between a moved name and its old file's name for a line to count as
@@ -86,12 +86,7 @@ export async function staleNameFindings(wt, diff) {
     const out = await gitTry(wt, "grep", "-n", "-w", "-I", "--cached", ...candidates.flatMap((n) => ["-e", n]));
     if (!out)
         return [];
-    const lines = [];
-    for (const line of out.split("\n")) {
-        const m = /^([^:]+):(\d+):(.*)$/.exec(line);
-        if (m)
-            lines.push({ file: m[1], no: m[2], text: m[3] ?? "" });
-    }
+    const lines = gitGrepHits(out);
     const findings = [];
     for (const name of candidates) {
         if (findings.length >= MAX_STALE_PATHS)
@@ -162,12 +157,7 @@ export async function movedNameFindings(wt, diff) {
     const out = await gitTry(wt, "grep", "-n", "-w", "-I", "--cached", ...picked.flatMap((m) => ["-e", m.name]));
     if (!out)
         return [];
-    const lines = [];
-    for (const line of out.split("\n")) {
-        const m = /^([^:]+):(\d+):(.*)$/.exec(line);
-        if (m)
-            lines.push({ file: m[1], no: m[2], text: m[3] ?? "" });
-    }
+    const lines = gitGrepHits(out);
     const findings = [];
     for (const { name, from, to } of picked) {
         if (findings.length >= MAX_STALE_PATHS)

package/dist/src/run/stage-path-checks.js

@@ -12,7 +12,7 @@
 import { changeBaseRev } from "../git/git.js";
 import { gitTry } from "../git/git-run.js";
 import { pathTokens } from "../text/text.js";
-import { MAX_STALE_HITS, MAX_STALE_PATHS, cappedList, diffPlusPath, hasStandalonePathOccurrence, isRecordProse, } from "./stage-checks-shared.js";
+import { MAX_STALE_HITS, MAX_STALE_PATHS, cappedList, diffPlusPath, gitGrepHits, hasStandalonePathOccurrence, isRecordProse, } from "./stage-checks-shared.js";
 import { movedNameFindings, staleNameFindings } from "./stage-name-checks.js";
 import { detachedDocFindings, garbledWordingFindings, newlineFindings } from "./stage-prose-checks.js";
 /** How many nonexistent added paths one finding names before it stops. */
@@ -71,6 +71,29 @@ export async function gitLevelFindings(wt, mainBranch) {
         await gitTry(wt, "reset");
     }
 }
+/** `git grep --cached` for `needle`, returning its matching `file:line` strings that sit outside
+ * record prose and (when given) `excludeFile`, and that name `needle` as a path of its own. The
+ * single home of the two stale-reference sweeps, movedSourceFindings and staleReferenceFindings:
+ * both run the same fixed-string grep and filter its hits the same way before capping at
+ * MAX_STALE_HITS, so one helper keeps them from drifting. */
+async function pathGrepHits(wt, needle, excludeFile) {
+    // `git grep` exits 1 with no output when nothing matches — the common, clean case — and
+    // gitTry maps that to null exactly as it maps a real failure, both of which mean "no hits".
+    const out = await gitTry(wt, "grep", "-n", "-F", "-I", "--cached", "-e", needle);
+    if (!out)
+        return [];
+    const hits = [];
+    for (const { file, no, text } of gitGrepHits(out)) {
+        if (file === excludeFile || isRecordProse(file))
+            continue;
+        if (!hasStandalonePathOccurrence(text, needle))
+            continue;
+        hits.push(`${file}:${no}`);
+        if (hits.length >= MAX_STALE_HITS)
+            break;
+    }
+    return hits;
+}
 /** (f) References to a file the change moved code out of. A modified (`M`) file is a source
  * when at least MOVED_LINES_MIN of its removed `-U0` lines (trimmed, at least MOVED_LINE_MIN_CHARS
  * long) were added verbatim to another file. Each hit of the source's path outside record prose
@@ -120,20 +143,7 @@ async function movedSourceFindings(wt, diff, entries) {
         const moved = src.removed.filter((l) => others.some(([, v]) => v.added.has(l))).length;
         if (moved < MOVED_LINES_MIN)
             continue;
-        const out = await gitTry(wt, "grep", "-n", "-F", "-I", "--cached", "-e", e.path);
-        if (!out)
-            continue;
-        const hits = [];
-        for (const line of out.split("\n")) {
-            const m = /^([^:]+):(\d+):(.*)$/.exec(line);
-            if (!m || m[1] === e.path || isRecordProse(m[1]))
-                continue;
-            if (!hasStandalonePathOccurrence(m[3] ?? "", e.path))
-                continue;
-            hits.push(`${m[1]}:${m[2]}`);
-            if (hits.length >= MAX_STALE_HITS)
-                break;
-        }
+        const hits = await pathGrepHits(wt, e.path, e.path);
         if (hits.length === 0)
             continue;
         findings.push(`${e.path} had ${moved} lines moved to ${cappedList(receivers, MAX_STALE_PATHS)}, but it is ` +
@@ -155,20 +165,7 @@ async function staleReferenceFindings(wt, entries) {
         if (reported >= MAX_STALE_PATHS)
             break;
         const old = e.oldPath ?? e.path;
-        // `git grep` exits 1 with no output when nothing matches — the common, clean case — and
-        // gitTry maps that to null exactly as it maps a real failure, both of which mean "no hits".
-        const out = await gitTry(wt, "grep", "-n", "-F", "-I", "--cached", "-e", old);
-        if (!out)
-            continue;
-        const hits = [];
-        for (const line of out.split("\n")) {
-            const m = /^([^:]+):(\d+):(.*)$/.exec(line);
-            if (!m || isRecordProse(m[1]) || !hasStandalonePathOccurrence(m[3] ?? "", old))
-                continue;
-            hits.push(`${m[1]}:${m[2]}`);
-            if (hits.length >= MAX_STALE_HITS)
-                break;
-        }
+        const hits = await pathGrepHits(wt, old);
         if (hits.length === 0)
             continue;
         const moved = e.status === "R" ? `was renamed to ${e.path}` : "was deleted";

package/dist/src/runner/leftover.js

@@ -76,6 +76,17 @@ export async function pinnedRetrySha(root, role, mainBranch, state) {
 export async function hasUnmergedPin(root, role) {
     return (await refSha(root, mergeRefName(role)).catch(() => null)) !== null;
 }
+/** The main_red wait outcome a kept change returns while `ctx.mainRedRetry` is the only
+ * outstanding hold — same kept sha and same "waits for main to move past red" message for both
+ * recovery paths (the pinned ref and the no-pin adopted tip), so the wording cannot drift per
+ * path and the two branches stay byte-stable. */
+function mainRedWait(sha, head) {
+    return {
+        kind: "main_red_wait",
+        sha,
+        message: `kept change ${shortSha(sha)} waits for main to move past red ${shortSha(head)} before its next merge`,
+    };
+}
 /** Queue a commit a previous run 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
@@ -127,8 +138,7 @@ export async function recoverLeftover(ctx) {
         if (heldTip)
             return { kind: "held", sha, message: heldTip.message };
         if (ctx.mainRedRetry) {
-            const message = `kept change ${shortSha(sha)} waits for main to move past red ${shortSha(ctx.mainRedRetry.head)} before its next merge`;
-            return { kind: "main_red_wait", sha, message };
+            return mainRedWait(sha, ctx.mainRedRetry.head);
         }
         // 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/merge/discard,
@@ -150,8 +160,7 @@ export async function recoverLeftover(ctx) {
     // `requeueMainRedPin` owns the re-queue of a main_red pin, once main's head moves. Queuing it
     // here would pay a full gate check against the same red head, whose result is already known.
     if (ctx.mainRedRetry) {
-        const message = `kept change ${shortSha(sha)} waits for main to move past red ${shortSha(ctx.mainRedRetry.head)} before its next merge`;
-        return { kind: "main_red_wait", sha, message };
+        return mainRedWait(sha, ctx.mainRedRetry.head);
     }
     const attempts = conflictAttempts(ctx.mergeConflicts, sha);
     if (attempts >= MERGE_CONFLICT_LIMIT) {

package/dist/src/runner/revision.js

@@ -3,13 +3,13 @@ import { readTextIfExists, readTextOrNull, writeTextAtomic } from "../files/file
 import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { gitTry, gitTryStarted } from "../git/git-run.js";
 import { resetWorktreeToMain } from "../git/worktree.js";
-import { resolveBacklogInsertConflicts } from "../merge/backlog-conflicts.js";
+import { resolveBacklogInsertConflicts } from "../merge/merge-backlog-conflicts.js";
 import { conflictedFiles } from "../merge/merge-git.js";
 import { formatDate } from "../text/datetime.js";
 import { stampedSubject } from "../git/commit-message.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { entryKey } from "../backlog/backlog-parts.js";
-import { actionableEntryRanges } from "../backlog/backlog-structure.js";
+import { actionableEntryRanges } from "../backlog/backlog-index-data.js";
 import { CONVERGENCE_HOLD_MARKER } from "../roles/role-guidance.js";
 import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
 import { logEventBestEffort } from "../events/events.js";

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

@@ -3,7 +3,7 @@ import { modelFallbackVerdict, providerFailureReason, recordModelFallback } from
 /** Fold one AUTHORING agent run's verdict into the role's model-fallback state
  * (src/runner/model-fallback.ts) and emit the episode's started/ended events. Only the agent run
  * that actually happened is evidence: a run that never invoked pi (a skipped director
- * inbox, a recovered leftover, a red-main block) returns from runOnce before this is
+ * inbox, a recovered leftover, a merge-side `main_red` pin) returns from runOnce before this is
  * reached, and modelFallbackVerdict reports an aborted/killed/timed-out agent run as
  * inconclusive — so neither can end an episode without the primary having answered.
  * A role whose tier resolves to no fallback pair never trips, and an episode persisted from a

package/dist/src/runner/runner-outcome.js

@@ -62,11 +62,6 @@ export async function handlePiResultPhase(ctx, pi, userPrompt, revisionRound, wt
         flow,
         filed,
         ci,
-        // The image-reroute arm resolves its target from the live config and the current
-        // regime, and names the model this run ran on as the handoff's `from`.
-        config: ctx.config,
-        rerouteRegime: ctx.rerouteRegime(piStartedAt),
-        runModel: cfg.model,
         warn: (message) => ctx.warn(message),
         merge: (w, sum) => mergePhase(ctx, w, sum),
         finishAbortedRun: () => ctx.finishAbortedRun(userPrompt, wt),

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

@@ -232,67 +232,90 @@ export class RunnerPi {
         const pi = await runPi(opts);
         this.warnFallbackClone(pi);
         this.observeFreeModelCost(pi, opts.config);
-        if (!pi.aborted &&
-            !pi.timedOut &&
-            !pi.quietKilled &&
-            (pi.transientServerTimeout ||
-                pi.transientPiCrash ||
-                pi.transientRateLimit ||
-                this.retryCoversBackendKind(pi)) &&
-            !pi.ok &&
-            // 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 run ends and the kept session
-            // 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"})${on} — 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`})${on} — retrying the agent run once`
-                    : pi.backendKind === "stream-severed"
-                        ? `provider severed the in-flight stream (terminated)${on} — retrying the agent run once`
-                        : pi.backendKind === "timeout"
-                            ? `provider request timed out after accepting the connection${on} — retrying the agent run once`
-                            : `model server timed out an idle predict stream (e.g. machine sleep)${on} — retrying the agent run once`);
+        if (this.transientRetryAdmits(pi)) {
+            this.host.warn(this.transientRetryWarning(pi, on));
             // The failed attempt folds NOW, before the wait and the retry: a 429 it ended on is the
             // team-wide rate-limit hold's input (RoleRunner.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
-            // pi crash is a failure of the local path, retried at once, while a 429 must wait its
-            // per-minute bucket out. A hint-less 429 defaults to that minute-scale refill pause
-            // instead of 0 — an immediate retry lands in the same exhausted bucket and burns the
-            // run's only retry (BUGS.md 2026-09-25). A present hint wins; the cap bounds either.
-            // A hint of 0 (or any non-positive value) is no usable hint — "retry now" is exactly
-            // the burned-retry bug a hint-less 429 causes — so it falls back to the refill pause
-            // just like a missing hint, keeping the warning text and the actual wait in agreement.
-            // The timeout kind (BUGS.md 2026-09-30) takes that same minute-scale pause: the
-            // provider accepted the request and failed to answer it, an overload shape — an
-            // immediate re-request lands at the back of the same queue and burns the run's only
-            // retry, so the retry waits the refill pause out first.
-            const hintS = pi.retryAfterSeconds && pi.retryAfterSeconds > 0 ? pi.retryAfterSeconds : RATE_LIMIT_NO_HINT_RETRY_S;
-            const waitS = pi.transientRateLimit
-                ? Math.min(hintS, RATE_LIMIT_RETRY_AFTER_CAP_S)
-                : pi.backendKind === "timeout"
-                    ? RATE_LIMIT_NO_HINT_RETRY_S
-                    : 0;
+            const waitS = this.transientRetryWaitSeconds(pi);
             if (waitS > 0)
                 await (this.host.sleep?.(waitS * 1000) ?? sleepFor(waitS * 1000));
-            // Within-run continuity only: resume the session the first attempt created, so its
-            // partial progress is not re-done. The next run 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, on);
-            return retry;
+            return this.retryContinuingSession(opts, on, foldFinal, fold);
         }
         this.warnBackendKindFloor(pi, on);
         if (foldFinal)
             fold(pi);
         return pi;
     }
+    /** The retry's admission predicate: whether this run qualifies for the one bounded transient
+     * retry — not cleanly ended or killed, but ended on a transient server condition (a server
+     * timeout, a pi crash, a 429, or a backend kind the retry covers) and not a subscription
+     * usage-window rejection. */
+    transientRetryAdmits(run) {
+        return (!run.aborted &&
+            !run.timedOut &&
+            !run.quietKilled &&
+            (run.transientServerTimeout ||
+                run.transientPiCrash ||
+                run.transientRateLimit ||
+                this.retryCoversBackendKind(run)) &&
+            !run.ok &&
+            // 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 run ends and the kept session
+            // resumes once the team hold lifts (plans/agent-backends.md §8, part 6e).
+            !subscriptionWindowRejected(run));
+    }
+    /** The per-run retry warning text, keyed off which transient condition the first attempt
+     * ended on. */
+    transientRetryWarning(run, on) {
+        return run.transientPiCrash
+            ? `pi crashed on malformed JSON (${run.errorMessage ?? "no detail"})${on} — resuming the session once`
+            : run.transientRateLimit
+                ? `provider rate-limited the request (429${run.retryAfterSeconds ? `, retry after ${run.retryAfterSeconds}s` : `, no hint — waiting ${RATE_LIMIT_NO_HINT_RETRY_S}s`})${on} — retrying the agent run once`
+                : run.backendKind === "stream-severed"
+                    ? `provider severed the in-flight stream (terminated)${on} — retrying the agent run once`
+                    : run.backendKind === "timeout"
+                        ? `provider request timed out after accepting the connection${on} — retrying the agent run once`
+                        : `model server timed out an idle predict stream (e.g. machine sleep)${on} — retrying the agent run once`;
+    }
+    /** The seconds to wait before the bounded retry, the pause taken from the moved wait ladder;
+     * the sleep itself stays in the caller. */
+    transientRetryWaitSeconds(run) {
+        // The pause is the rate-limit branch's, plus the timeout kind's: a server timeout or
+        // pi crash is a failure of the local path, retried at once, while a 429 must wait its
+        // per-minute bucket out. A hint-less 429 defaults to that minute-scale refill pause
+        // instead of 0 — an immediate retry lands in the same exhausted bucket and burns the
+        // run's only retry (BUGS.md 2026-09-25). A present hint wins; the cap bounds either.
+        // A hint of 0 (or any non-positive value) is no usable hint — "retry now" is exactly
+        // the burned-retry bug a hint-less 429 causes — so it falls back to the refill pause
+        // just like a missing hint, keeping the warning text and the actual wait in agreement.
+        // The timeout kind (BUGS.md 2026-09-30) takes that same minute-scale pause: the
+        // provider accepted the request and failed to answer it, an overload shape — an
+        // immediate re-request lands at the back of the same queue and burns the run's only
+        // retry, so the retry waits the refill pause out first.
+        const hintS = run.retryAfterSeconds && run.retryAfterSeconds > 0 ? run.retryAfterSeconds : RATE_LIMIT_NO_HINT_RETRY_S;
+        return run.transientRateLimit
+            ? Math.min(hintS, RATE_LIMIT_RETRY_AFTER_CAP_S)
+            : run.backendKind === "timeout"
+                ? RATE_LIMIT_NO_HINT_RETRY_S
+                : 0;
+    }
+    /** The one bounded retry: resume the session the first attempt created on the same opts, so
+     * its partial progress is not re-done (the next run still starts fresh), folding the retried
+     * run when foldFinal is set and warning the backend-kind floor for its returned agent run. */
+    async retryContinuingSession(opts, on, foldFinal, fold) {
+        // Within-run continuity only: resume the session the first attempt created, so its
+        // partial progress is not re-done. The next run 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, on);
+        return retry;
+    }
     /** The backend-kind floor (BUGS.md 2026-09-29): a failed agent 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