tickmarkr 2.5.3 → 2.5.4

package/dist/gates/review.d.ts

@@ -64,9 +64,42 @@ export declare function matchClosureId(candidate: unknown, fingerprints: Iterabl
  * all route through matchClosureId.
  */
 export declare function isReviewClosureInvalid(v: Pick<ReviewVerdict, "resolved" | "reraised"> | null | undefined, priorIds: ReadonlySet<string> | readonly string[]): boolean;
+export type ReviewerFloorCause = "author-tier" | "task-floor" | "config" | "prior-reviewer";
+/**
+ * RF-1 (OBS-922 add.2/3): the tier a reviewer must meet is the maximum of the author's tier, the
+ * task-declared floor, a configured `review.floor` tier and, on a second round or a retry, the prior
+ * reviewer's tier. The cause names the input that reached the maximum (earlier inputs win a tie, so a
+ * floor the author's tier already satisfies is attributed to the author).
+ */
+export declare function resolveReviewerFloor(authorTier: Tier, taskFloor?: Tier, configFloor?: Tier, priorReviewerTier?: Tier): {
+    floor: Tier;
+    cause: ReviewerFloorCause;
+};
+/** A prior reviewer of THIS task: a channel key, or a journaled row's key plus the tier it was DISPATCHED at. */
+export type PriorReviewer = string | {
+    reviewer: string;
+    tier?: unknown;
+};
+/**
+ * The highest tier among the task's prior reviewers — the prior reviewer's tier for RF-1. A recorded
+ * dispatch tier is historical evidence and wins over the current pool; an unrecorded one falls back to
+ * the seat's channel; a seat neither establishes (it left the pool on resume, or the journal holds
+ * garbage) holds frontier — fail closed, never silently dropped.
+ */
+export declare function priorReviewerTier(channels: BillingChannel[], priorReviewers?: readonly PriorReviewer[]): Tier | undefined;
+/**
+ * The gate's floor: author tier, task floor, review.floor (a tier — `worker` names none) and the seats
+ * the caller names as THIS TASK's prior reviewers (earlier rounds' seats, a flaked seat). Eligibility
+ * exclusions are NOT evidence — a retry bans a flaked seat's whole adapter, and those sibling channels
+ * never reviewed — and neither is the run-scoped LRU rotation history, which names unrelated tasks' seats.
+ */
+export declare function gateReviewerFloor(task: Pick<Task, "routingHints">, cfg: TickmarkrConfig, author: Assignment, channels: BillingChannel[], priorReviewers?: readonly PriorReviewer[]): {
+    floor: Tier;
+    cause: ReviewerFloorCause;
+};
 export declare function pickReviewer(author: Assignment, channels: BillingChannel[], exclude?: string[], // v1.1 failover: reviewer channels that already produced garbage for this task
 prefer?: string[], // v1.53 T2: review.prefer — reorders eligible channels, never changes eligibility
-floor?: Tier, // task-declared only; config floors govern workers and must not silently move review seats
+floor?: Tier, // task/config/prior floor from the caller; the author's own tier is ALWAYS applied here (RF-1)
 history?: string[], // run-scoped picks, oldest to newest; empty preserves the established ranking
 onSeat?: (seat: number, count: number) => void, demoted?: ReadonlySet<string>): BillingChannel | null;
 export type ReviewUnparseableCause = VerdictUnparseableCause | "launch-never-started" | "truncated" | "silent";
@@ -76,4 +109,4 @@ export type ReviewUnparseableCause = VerdictUnparseableCause | "launch-never-sta
  * judgement rather than a guarantee made by this renderer.
  */
 export declare function renderDeclaredWriteScope(files: ReadonlyArray<string>): string;
-export declare function reviewGate(task: Task, worktree: string, baseRef: string, author: Assignment, channels: BillingChannel[], adapters: WorkerAdapter[], cfg: TickmarkrConfig, via?: GateVia, excludeReviewers?: string[], artifactDir?: string, reviewHistory?: string[], demotedReviewers?: ReadonlySet<string>, carriedFindings?: readonly StructuredFinding[]): Promise<GateResult>;
+export declare function reviewGate(task: Task, worktree: string, baseRef: string, author: Assignment, channels: BillingChannel[], adapters: WorkerAdapter[], cfg: TickmarkrConfig, via?: GateVia, excludeReviewers?: string[], artifactDir?: string, reviewHistory?: string[], demotedReviewers?: ReadonlySet<string>, carriedFindings?: readonly StructuredFinding[], priorReviewers?: readonly PriorReviewer[]): Promise<GateResult>;

package/dist/gates/review.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { channelKey, shq } from "../adapters/types.js";
 import { criticalPathHits, DEFAULT_DIFF_CAP, DEFAULT_REVIEW_CRITICAL_PATHS, declaredReviewPolicy, isReviewLeafPath, raiseReviewPolicy, REVIEW_VERSION_MIRRORS, TIER_RANK, } from "../config/config.js";
 import { filesGlob } from "../graph/files-glob.js";
-import { renderAcceptanceItem } from "../graph/schema.js";
+import { renderAcceptanceItem, TIERS } from "../graph/schema.js";
 import { getAdapter } from "../adapters/registry.js";
 import { shOk } from "../run/git.js";
 import { structuredFindings } from "../run/journal.js";
@@ -200,9 +200,52 @@ function reviewPreferIndex(c, prefer) {
     const i = prefer.findIndex((p) => p === c.adapter || p === channelKey(c));
     return i === -1 ? prefer.length : i;
 }
+/**
+ * RF-1 (OBS-922 add.2/3): the tier a reviewer must meet is the maximum of the author's tier, the
+ * task-declared floor, a configured `review.floor` tier and, on a second round or a retry, the prior
+ * reviewer's tier. The cause names the input that reached the maximum (earlier inputs win a tie, so a
+ * floor the author's tier already satisfies is attributed to the author).
+ */
+export function resolveReviewerFloor(authorTier, taskFloor, configFloor, priorReviewerTier) {
+    const inputs = [
+        [authorTier, "author-tier"], [taskFloor, "task-floor"], [configFloor, "config"], [priorReviewerTier, "prior-reviewer"],
+    ];
+    let best = { floor: authorTier, cause: "author-tier" };
+    for (const [tier, cause] of inputs) {
+        if (tier !== undefined && TIER_RANK[tier] > TIER_RANK[best.floor])
+            best = { floor: tier, cause };
+    }
+    return best;
+}
+/**
+ * The highest tier among the task's prior reviewers — the prior reviewer's tier for RF-1. A recorded
+ * dispatch tier is historical evidence and wins over the current pool; an unrecorded one falls back to
+ * the seat's channel; a seat neither establishes (it left the pool on resume, or the journal holds
+ * garbage) holds frontier — fail closed, never silently dropped.
+ */
+export function priorReviewerTier(channels, priorReviewers = []) {
+    let top;
+    for (const p of priorReviewers) {
+        const key = typeof p === "string" ? p : p.reviewer;
+        const seen = (typeof p === "string" ? undefined : p.tier) ?? channels.find((ch) => channelKey(ch) === key)?.tier;
+        const tier = TIERS.includes(seen) ? seen : "frontier";
+        if (top === undefined || TIER_RANK[tier] > TIER_RANK[top])
+            top = tier;
+    }
+    return top;
+}
+/**
+ * The gate's floor: author tier, task floor, review.floor (a tier — `worker` names none) and the seats
+ * the caller names as THIS TASK's prior reviewers (earlier rounds' seats, a flaked seat). Eligibility
+ * exclusions are NOT evidence — a retry bans a flaked seat's whole adapter, and those sibling channels
+ * never reviewed — and neither is the run-scoped LRU rotation history, which names unrelated tasks' seats.
+ */
+export function gateReviewerFloor(task, cfg, author, channels, priorReviewers = []) {
+    return resolveReviewerFloor(author.tier, task.routingHints?.floor, cfg.review.floor === "worker" ? undefined : cfg.review.floor, priorReviewerTier(channels, priorReviewers));
+}
 export function pickReviewer(author, channels, exclude = [], // v1.1 failover: reviewer channels that already produced garbage for this task
 prefer = [], // v1.53 T2: review.prefer — reorders eligible channels, never changes eligibility
-floor, // task-declared only; config floors govern workers and must not silently move review seats
+floor, // task/config/prior floor from the caller; the author's own tier is ALWAYS applied here (RF-1)
 history = [], // run-scoped picks, oldest to newest; empty preserves the established ranking
 onSeat, demoted = new Set()) {
     // FLEET-05 success criterion 2: an author not resolvable in the channel list yields NO reviewer.
@@ -213,6 +256,8 @@ onSeat, demoted = new Set()) {
     if (!authorChannel)
         return null;
     const authorProvider = modelProvider(author.model, authorChannel.vendor);
+    // RF-1: every caller inherits the author-tier floor — a reviewer is never seated below its author.
+    const effectiveFloor = resolveReviewerFloor(author.tier, floor).floor;
     const ranked = channels
         // Three independent axes: different vendor, different resolved provider identity (OBS-946: on initial pick
         // as well as failover, so an aggregator channel stamped "mixed" never seats the author's own provider),
@@ -222,7 +267,7 @@ onSeat, demoted = new Set()) {
         && modelProvider(c.model, c.vendor) !== authorProvider
         && modelId(c.model) !== modelId(author.model)
         && !exclude.includes(channelKey(c))
-        && (floor === undefined || TIER_RANK[c.tier] >= TIER_RANK[floor]))
+        && TIER_RANK[c.tier] >= TIER_RANK[effectiveFloor])
         .sort((a, b) => reviewPreferIndex(a, prefer) - reviewPreferIndex(b, prefer) || TIER_RANK[b.tier] - TIER_RANK[a.tier] || marginalCostRank(a) - marginalCostRank(b));
     const reviewer = [...ranked].sort((a, b) => Number(demoted.has(channelKey(a))) - Number(demoted.has(channelKey(b)))
         || history.lastIndexOf(channelKey(a)) - history.lastIndexOf(channelKey(b))
@@ -247,7 +292,10 @@ ${files.map((path) => `- ${path}`).join("\n")}`;
 export async function reviewGate(task, worktree, baseRef, author, channels, adapters, cfg, via, excludeReviewers, 
 // OBS-196: run dir for raw-output persistence on an unparseable verdict; absent (older callers,
 // direct tests) skips persistence and changes nothing else.
-artifactDir, reviewHistory, demotedReviewers, carriedFindings = []) {
+artifactDir, reviewHistory, demotedReviewers, carriedFindings = [], 
+// RF-1: channel keys of THIS task's prior reviewers (earlier rounds, a flaked seat) — task-scoped,
+// never the run-wide rotation history nor excludeReviewers; the seat holds the highest of their tiers.
+priorReviewers = []) {
     // R3 (OBS-186): participation is keyed on PATHS. The compiler's assignment comes from the DECLARED
     // files[]; the operator's floor may RAISE it to full and can never lower it. `complexityThreshold` is
     // retired — the branch that returned a green skip on a complexity comparison is gone, and with it the
@@ -317,20 +365,19 @@ artifactDir, reviewHistory, demotedReviewers, carriedFindings = []) {
         policy: "full",
         ...(promotedBy ? { promotedFrom: declaredPolicy, promotedBy } : {}),
     };
-    // A reviewer floor is opt-in at the task. Applying cfg.routing.floors here would change the
-    // historical seat for every task that never asked for review-tier coupling.
-    const reviewerFloor = task.routingHints?.floor;
+    // RF-1: the floor is max(author tier, task floor, review.floor tier, prior reviewer's tier). Only
+    // review.floor is read from config — cfg.routing.floors governs workers and never moves review seats.
+    const { floor: reviewerFloor, cause: reviewerFloorCause } = gateReviewerFloor(task, cfg, author, channels, priorReviewers);
+    const floorMeta = { reviewerFloor, reviewerFloorCause };
     let rotationSeat;
     const reviewer = pickReviewer(author, channels, excludeReviewers ?? [], cfg.review.prefer ?? [], reviewerFloor, reviewHistory, reviewHistory ? (seat) => { rotationSeat = seat; } : undefined, demotedReviewers);
     if (!reviewer) {
         // meta.noEligibleReviewer lets run-gates' review-retry keep the ORIGINAL unparseable result when
         // the retry finds no second seat — a truthful cause beats a synthetic no-reviewer failure.
-        const reason = reviewerFloor
-            ? `no cross-vendor reviewer available at or above task-declared ${reviewerFloor} floor (diversity rule)`
-            : "no cross-vendor reviewer available (diversity rule)";
+        const reason = `no cross-vendor reviewer available at or above ${reviewerFloor} floor (${reviewerFloorCause}; diversity rule)`;
         return cfg.review.required || priorMaterials.length > 0
-            ? { gate: "review", pass: false, details: `unreadable — ${reason}; ${priorMaterials.length ? "carried materials require a review verdict" : "set review.required:false to waive"}`, meta: { noEligibleReviewer: true, unreadable: true, ...(reviewerFloor ? { reviewerFloor } : {}) } }
-            : { gate: "review", pass: true, details: `WARNING: ${reason} — review waived by config`, meta: { noEligibleReviewer: true, ...(reviewerFloor ? { reviewerFloor } : {}) } };
+            ? { gate: "review", pass: false, details: `unreadable — ${reason}; ${priorMaterials.length ? "carried materials require a review verdict" : "set review.required:false to waive"}`, meta: { noEligibleReviewer: true, unreadable: true, ...floorMeta } }
+            : { gate: "review", pass: true, details: `WARNING: ${reason} — review waived by config`, meta: { noEligibleReviewer: true, ...floorMeta } };
     }
     reviewHistory?.push(channelKey(reviewer));
     const rotationMeta = rotationSeat === undefined ? {} : { rotationSeat };
@@ -369,6 +416,7 @@ Classify every concern as "material" (a correctness, security, or acceptance-cri
 block the merge) or "minor" (style, naming, or preference that should not block). ONLY material findings
 block approval. For a minor concern you have decided not to block on, set "defer": true and give a
 one-line "rationale" — it is recorded in the review, never dropped.
+A fix you prescribe that would break suites outside the task's declared write scope (files[]) is a scope finding, never a material one.
 
 Respond with ONLY this JSON:
 {"nonce": "${nonce}", "approve": true|false, "resolved": [], "reraised": [], "findings": [{"note": "...", "severity": "material"|"minor", "defer": false, "rationale": ""}], "comments": [{"path": "path/to/file", "line": 42, "body": "actionable feedback"}]}
@@ -453,7 +501,9 @@ The top-level comments array is optional. Use it only for actionable line-anchor
             meta: {
                 ...policyMeta,
                 ...rotationMeta,
+                ...floorMeta,
                 reviewer: channelKey(reviewer),
+                reviewerTier: reviewer.tier,
                 vendor: reviewer.vendor,
                 provider,
                 ...(cause === "malformed-verdict" ? { unparseable: true } : { noVerdict: true, classification: "infra", infra: true }),
@@ -488,15 +538,13 @@ The top-level comments array is optional. Use it only for actionable line-anchor
         pass: decided.pass,
         details,
         meta: {
-            ...policyMeta, ...rotationMeta, reviewer: channelKey(reviewer), vendor: reviewer.vendor, provider,
+            ...policyMeta, ...rotationMeta, ...floorMeta, reviewer: channelKey(reviewer), reviewerTier: reviewer.tier, vendor: reviewer.vendor, provider,
+            // OBS-990 b: the verbatim ids plus ONE normalised copy of each list — never a third alias.
             ...(priorMaterials.length ? {
                 resolved: v.resolved,
                 reraised: v.reraised,
-                normalisedMatches: (v.resolved ?? []).map((id) => matchClosureId(id, priorIds)).filter((id) => id !== undefined),
                 resolvedMatches: (v.resolved ?? []).map((id) => matchClosureId(id, priorIds)).filter((id) => id !== undefined),
                 reraisedMatches: (v.reraised ?? []).map((id) => matchClosureId(id, priorIds)).filter((id) => id !== undefined),
-                normalisedResolved: (v.resolved ?? []).map((id) => matchClosureId(id, priorIds)).filter((id) => id !== undefined),
-                normalisedReraised: (v.reraised ?? []).map((id) => matchClosureId(id, priorIds)).filter((id) => id !== undefined),
             } : {}),
             ...(reraised.length ? { findings: [
                     ...structuredFindings("review", details).filter((finding) => !reraised.some((prior) => prior.note === finding.note)),

package/dist/gates/run-gates.d.ts

@@ -3,6 +3,7 @@ import { type TickmarkrConfig } from "../config/config.js";
 import { type GateName, type Task } from "../graph/schema.js";
 import { type Baseline } from "./baseline.js";
 import { type GateVia } from "./llm.js";
+import { type PriorReviewer } from "./review.js";
 import type { GateResult } from "./types.js";
 import { type StructuredFinding } from "../run/journal.js";
 export type LoadProvider = () => number;
@@ -57,6 +58,7 @@ export interface GateContext {
     excludeReviewers?: string[];
     demotedReviewers?: Set<string>;
     reviewHistory?: string[];
+    priorReviewers?: PriorReviewer[];
     artifactDir?: string;
     pipeline?: "v185" | "legacy";
     selectTests?: boolean;

package/dist/gates/run-gates.js

@@ -11,7 +11,7 @@ import { evidenceGate } from "./evidence.js";
 import { captureLlmOutput } from "./llm.js";
 import { disallowedBy } from "../route/preference.js";
 import { marginalCostRank } from "../route/router.js";
-import { pickReviewer, reviewGate } from "./review.js";
+import { gateReviewerFloor, pickReviewer, reviewGate } from "./review.js";
 import { scopeGate } from "./scope.js";
 import { shGit } from "../run/git.js";
 import { withJudgeInvocationEvidence } from "../run/journal.js";
@@ -602,7 +602,11 @@ export async function runGates(task, ctx) {
             }
             return rv;
         };
-        let rv = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, ctx.via, ctx.excludeReviewers, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings));
+        // RF-1: THIS task's prior reviewers — earlier rounds' seats plus the seats that produced garbage for
+        // it (excludeReviewers names only dispatched seats). Kept apart from the eligibility exclusions the
+        // retry below adds for a flaked seat's whole adapter: those sibling channels never reviewed.
+        const priorReviewers = [...(ctx.priorReviewers ?? []), ...(ctx.excludeReviewers ?? [])];
+        let rv = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, ctx.via, ctx.excludeReviewers, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, priorReviewers));
         // OBS-193/574: an unparseable review verdict retries the REVIEW exactly once, preferring a
         // different adapter. Only a single-adapter eligible pool may fall back to another channel on the
         // flaked adapter. The flaked verdict never enters results; an exhausted pool preserves its cause.
@@ -622,10 +626,14 @@ export async function runGates(task, ctx) {
             const priorExclusions = ctx.excludeReviewers ?? [];
             const flakedAdapter = flaked.slice(0, flaked.indexOf(":"));
             const adapterExclusions = ctx.channels.filter((c) => c.adapter === flakedAdapter).map(channelKey);
-            const crossAdapter = pickReviewer(ctx.author, ctx.channels, [...priorExclusions, ...adapterExclusions], ctx.cfg.review.prefer ?? [], task.routingHints?.floor);
+            // RF-1: the retry filters by the floor reviewGate resolves — author tier, task floor, review.floor
+            // and the prior reviewers' tiers, the flaked seat's own included, so a retry never drops a tier.
+            const retryPrior = [...priorReviewers, flaked];
+            const retryFloor = gateReviewerFloor(task, ctx.cfg, ctx.author, ctx.channels, retryPrior).floor;
+            const crossAdapter = pickReviewer(ctx.author, ctx.channels, [...priorExclusions, ...adapterExclusions], ctx.cfg.review.prefer ?? [], retryFloor);
             const exclusion = crossAdapter ? "adapter" : "channel";
             const retryExclusions = [...priorExclusions, ...(crossAdapter ? adapterExclusions : [flaked])];
-            const second = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, retryExclusions, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings));
+            const second = await dispatch((adapters) => reviewGate(task, ctx.worktree, ctx.baseRef, ctx.author, ctx.channels, adapters, ctx.cfg, retryVia, retryExclusions, ctx.artifactDir, ctx.reviewHistory, ctx.demotedReviewers, ctx.carriedFindings, retryPrior));
             if (second.meta?.noEligibleReviewer !== true) {
                 const retried = typeof second.meta?.reviewer === "string" ? second.meta.reviewer : "none";
                 const route = exclusion === "adapter"
@@ -639,10 +647,11 @@ export async function runGates(task, ctx) {
                     meta: { ...second.meta, reviewRetry: { flaked, retried, exclusion } },
                 };
             }
-            else if (task.routingHints?.floor) {
-                // Preserve the original no-answer cause when no replacement exists, but name the declared
-                // floor that correctly refused a lower-tier fallback.
-                rv = { ...rv, details: `${rv.details}\nreview re-route refused: ${second.details}` };
+            else {
+                // Preserve the original no-answer cause when no replacement exists, but name the resolved
+                // floor that correctly refused a lower-tier fallback — in details AND in the row's meta.
+                const { reviewerFloor, reviewerFloorCause } = second.meta ?? {};
+                rv = { ...rv, details: `${rv.details}\nreview re-route refused: ${second.details}`, meta: { ...rv.meta, reviewerFloor, reviewerFloorCause } };
             }
         }
         return invocations.length ? { ...rv, meta: { ...rv.meta, invocations } } : rv;

package/dist/route/router.d.ts

@@ -33,3 +33,16 @@ export declare class RoutingError extends Error {
 export declare function marginalCostRank(c: BillingChannel): number;
 export declare function route(task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext, exclude?: ReadonlySet<string>, exploreCtx?: ExploreContext): Route;
 export declare function nextChannel(current: Assignment, task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile, exclude?: ReadonlySet<string>): Assignment | null;
+export type ClimbPick = Assignment & {
+    climbed: boolean;
+    reason?: string;
+};
+export type ClimbResult = ClimbPick;
+/**
+ * v2.5.4 OBS-986 (ES-1): climb one tier on request when untried channels exist in higher tiers.
+ * With routing.escalateTier on, returns the cheapest untried live channel strictly above current.tier,
+ * ordered as nextChannel orders (tier, then marginal cost, learned score strictly last), flagged climbed: true.
+ * When the knob is off, when current is frontier, or when no higher tier has an untried channel,
+ * returns nextChannel's same-or-higher pick flagged climbed: false naming the reason.
+ */
+export declare function climbChannel(current: Assignment, task: Task, cfg: TickmarkrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile, exclude?: ReadonlySet<string>): ClimbPick | null;

package/dist/route/router.js

@@ -328,15 +328,8 @@ export function route(task, cfg, channels, profile, preferCtx, exclude, exploreC
     maybeSlaLint(lints, task, profile, slaMinutes, eligible[0]);
     return { assignment: toAssignment(eligible[0]), ladder: ladderFor(task, entry), lints, provenance: `${degraded}${bound}, marginal-cost auto (${chosenBy})`, ...(deviation ? { deviation } : {}) };
 }
-export function nextChannel(current, task, cfg, channels, tried, profile, exclude) {
+function candidatePool(current, channels, tried, tierPredicate, exclude) {
     channels = withoutExcluded(channels, exclude);
-    // already cheapest-sufficient: TIER_RANK asc is the PRIMARY key so escalation climbs one band at a time.
-    // Do NOT "unify" this onto route()'s key order (marginal-cost first) — that reverses climb-one-band on mixed fleets (ROUTE-02, D2).
-    // ROUTE-13: learnedScore is the STRICTLY-LAST key — within-band tiebreak only. Precomputed
-    // outside the comparator (Pitfall 1), never arithmetic-combined with the band keys, no
-    // profile-dependent filter. NO exploration bonus here (route():110 has one; a probe on the
-    // failure path would spend a real retry). Absent profile ⇒ every score is 0 ⇒ third key
-    // all-ties ⇒ the stable sort preserves the exact v1.7 candidate ORDER.
     const triedKeys = new Set(tried);
     const triedIdentities = new Set(tried.map((key) => {
         const channel = channels.find((c) => channelKey(c) === key);
@@ -348,11 +341,71 @@ export function nextChannel(current, task, cfg, channels, tried, profile, exclud
         && channels.filter((c) => c.adapter === current.adapter).every((c) => triedKeys.has(channelKey(c)));
     const currentChannel = channels.find((c) => c.adapter === current.adapter && c.model === current.model);
     const excludedProvider = currentAdapterExcluded ? routingModelProvider(current.model, currentChannel?.vendor) : undefined;
-    const pool = channels.filter((c) => !triedIdentities.has(modelRouteIdentity(c.model, c.vendor))
+    return channels.filter((c) => !triedIdentities.has(modelRouteIdentity(c.model, c.vendor))
         && (!excludedProvider || routingModelProvider(c.model, c.vendor) !== excludedProvider)
-        && TIER_RANK[c.tier] >= TIER_RANK[current.tier]);
+        && tierPredicate(c.tier));
+}
+function rankFailoverCandidates(pool, task, cfg, profile) {
     const scores = new Map(pool.map((c) => [channelKey(c), profile ? learnedScore(profile, task.shape, channelKey(c), c.channel, { availWeight: cfg.routing.learnedTuning?.availWeight }) : 0]));
     const scoreOf = (c) => scores.get(channelKey(c));
-    const candidates = pool.sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier] || marginalCostRank(a) - marginalCostRank(b) || scoreOf(b) - scoreOf(a));
+    return pool.sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier] || marginalCostRank(a) - marginalCostRank(b) || scoreOf(b) - scoreOf(a));
+}
+export function nextChannel(current, task, cfg, channels, tried, profile, exclude) {
+    // already cheapest-sufficient: TIER_RANK asc is the PRIMARY key so escalation climbs one band at a time.
+    // Do NOT "unify" this onto route()'s key order (marginal-cost first) — that reverses climb-one-band on mixed fleets (ROUTE-02, D2).
+    // ROUTE-13: learnedScore is the STRICTLY-LAST key — within-band tiebreak only. Precomputed
+    // outside the comparator (Pitfall 1), never arithmetic-combined with the band keys, no
+    // profile-dependent filter. NO exploration bonus here (route():110 has one; a probe on the
+    // failure path would spend a real retry). Absent profile ⇒ every score is 0 ⇒ third key
+    // all-ties ⇒ the stable sort preserves the exact v1.7 candidate ORDER.
+    const pool = candidatePool(current, channels, tried, (tier) => TIER_RANK[tier] >= TIER_RANK[current.tier], exclude);
+    const candidates = rankFailoverCandidates(pool, task, cfg, profile);
     return candidates.length ? toAssignment(candidates[0]) : null;
 }
+function makeClimbPick(assignment, climbed, reason) {
+    const pick = {
+        adapter: assignment.adapter,
+        model: assignment.model,
+        channel: assignment.channel,
+        tier: assignment.tier,
+        climbed,
+        ...(climbed ? {} : { reason }),
+    };
+    Object.defineProperty(pick, "assignment", {
+        get() {
+            return {
+                adapter: this.adapter,
+                model: this.model,
+                channel: this.channel,
+                tier: this.tier,
+            };
+        },
+        enumerable: false,
+    });
+    return pick;
+}
+/**
+ * v2.5.4 OBS-986 (ES-1): climb one tier on request when untried channels exist in higher tiers.
+ * With routing.escalateTier on, returns the cheapest untried live channel strictly above current.tier,
+ * ordered as nextChannel orders (tier, then marginal cost, learned score strictly last), flagged climbed: true.
+ * When the knob is off, when current is frontier, or when no higher tier has an untried channel,
+ * returns nextChannel's same-or-higher pick flagged climbed: false naming the reason.
+ */
+export function climbChannel(current, task, cfg, channels, tried, profile, exclude) {
+    const escalateOn = cfg.routing.escalateTier !== "off";
+    if (!escalateOn) {
+        const pick = nextChannel(current, task, cfg, channels, tried, profile, exclude);
+        return pick ? makeClimbPick(pick, false, "routing.escalateTier knob is off") : null;
+    }
+    if (current.tier === "frontier") {
+        const pick = nextChannel(current, task, cfg, channels, tried, profile, exclude);
+        return pick ? makeClimbPick(pick, false, "no higher tier") : null;
+    }
+    const higherPool = candidatePool(current, channels, tried, (tier) => TIER_RANK[tier] > TIER_RANK[current.tier], exclude);
+    if (higherPool.length > 0) {
+        const candidates = rankFailoverCandidates(higherPool, task, cfg, profile);
+        return makeClimbPick(toAssignment(candidates[0]), true);
+    }
+    const pick = nextChannel(current, task, cfg, channels, tried, profile, exclude);
+    return pick ? makeClimbPick(pick, false, "no higher tier has an untried channel") : null;
+}