@cr1ms0n/pi-subagent 0.10.0 → 0.11.0

package/skills/subagent/SKILL.md

@@ -109,7 +109,7 @@ Pi path are **refused**, not silently degraded:
 - Prefer `max_turns`, `max_cost`, and/or `timeout_ms` on long or write-capable runs.
   `timeout_ms` is absolute: local preflight, Jev selection, setup, queue and
   runtime all count against it.
-- `output_schema` asks the child for a fenced `json:result` block (one repair round).
+- `output_schema` asks the child for a fenced `json:result` block. An otherwise successful invalid answer gets one repair round; a failed provider attempt neither repairs nor publishes structured output.
 - `context: "fork"` continues from a fork of the parent session.
 - Do not poll `status` in a tight loop. Use `wait` / `subagent_wait`, or let the
   completion notification arrive for `async: true` runs.
@@ -121,16 +121,17 @@ Pi path are **refused**, not silently degraded:
 
 Omit `model` and `fallback_models` on every new call: both are legacy fields,
 and an explicit value is rejected rather than bypassing selection. Jev chooses
-one execution model from the user's dedicated candidate list plus an individual
-include/exclude decision per eligible tool. The local policy then re-validates
+an initial execution model and probabilities for the user's eligible candidates, plus one task-based include/exclude decision per eligible tool shared by all attempts. The local policy then re-validates
 the answer: unknown or unsafe tools cannot launch, explore/review stay read-only,
 and management actions need no routing config or credential.
 
-There are no emergency or fallback models, and low confidence is accepted rather
-than treated as a threshold. A Jev timeout or API failure stops the affected new
-dispatch with an actionable error; existing runs stay queryable and cancellable.
-Transient child failures retry the already selected model and tool set within the
-original deadline, up to `max_retries`; a quality failure never reselects.
+A Jev timeout or invalid decision still stops new dispatch; there is no emergency model. A valid route retains every candidate probability and tries higher values first. Tied maxima keep the returned choice first; other ties follow configured order. Low confidence and zero probability are accepted, not thresholds. Per-model probability is a selector preference, not uptime or a separate confidence score.
+
+Recognized settled model-unavailable, temporary rate-limit/service and transport errors can advance to the next candidate only before any tool execution begins in the current invocation. Once a tool starts, or protocol evidence is uncertain, do not restart the child on another or the same model. Auth/configuration, quota/billing, context, invalid requests, task/schema quality, cancellation and exhausted budgets never trigger model switching. Historical resume/fork messages are not new tool execution.
+
+`max_retries` limits all extension-level extra attempts: 0 means one initial attempt; 2 means at most three attempts. The built-in default remains 1. Availability failure advances directly to the next candidate; candidate exhaustion never wraps. Conclusively pre-work infrastructure failures may retry the same model within that budget. Every attempt shares tools, absolute deadline and cumulative reported cost/turn budgets, with fresh exact-model/tool startup verification. Switching makes no extra Jev call. Pi's internal provider retries are separate, unchanged and may delay fallback.
+
+Plan/status distinguish original choice, ranked alternatives and actual attempts. Earlier failed output is retained as attributed previews/session pointers, not mixed into a later structured answer. All-failed tasks keep their final failure. Existing runs remain manageable without selector configuration or a credential.
 
 An optional candidate `thinking` value is an opaque Pi thinking-level string;
 common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and

package/src/backend.ts

@@ -24,7 +24,7 @@
  */
 
 import type { ProtocolUpdate } from "./protocol.js";
-import type { TaskResult, TaskSpec } from "./types.js";
+import type { TaskResult, TaskSpec, ToolActivity } from "./types.js";
 
 /** Normalized event-stream parser contract, implemented per backend. */
 export interface BackendParser {
@@ -40,6 +40,21 @@ export interface BackendParser {
   getLiveText(): string;
   /** Completed messages so far. */
   getMessages(): import("@earendil-works/pi-ai").Message[];
+  /**
+   * Optional sticky current-invocation tool-activity observation used by the
+   * ranked failover gate. Parsers that do not implement it provide no
+   * conclusive evidence (callers must treat activity as unknown on the ranked
+   * path); the legacy unranked path is unaffected.
+   */
+  getToolActivity?(): ToolActivity | undefined;
+  /**
+   * Optional stop reason of the latest completed assistant message, used to
+   * suppress the ranked structured-output repair prompt and final publication
+   * after a settled provider error/abort. Absent means "not observable".
+   */
+  getAssistantStopReason?(): string | undefined;
+  /** Latest completed assistant text; empty must not fall back to earlier turns. */
+  getAssistantText?(): string | undefined;
 }
 
 export interface BackendInvocation {

package/src/extension.ts

@@ -8,10 +8,13 @@ import { Value } from "typebox/value";
 import { defaultConfig, loadConfig, readConfigFile, type SubagentConfig } from "./config.js";
 import {
   formatDuration,
+  formatRankedPreview,
   formatStatusPreview,
   formatTokens,
   isActiveState,
   oneLine,
+  projectRoutingForDisplay,
+  projectAttemptsForDisplay,
   renderCallLine,
   renderRunLines,
   SPINNERS,
@@ -25,7 +28,7 @@ import { runTasks } from "./orchestrator.js";
 import { OutputManager } from "./output.js";
 import { parseDepth, parseSpawnPolicy, SPAWNS_ENV_VAR, validateSubagentRequest, type PreparedTask, type ParentContext, type PreparationOptions, type ResolvedTask } from "./policy.js";
 import type { ChildRunner } from "./runner.js";
-import { ProcessLockManager } from "./process-lock.js";
+import { ProcessLockManager, runRecordSessionIds } from "./process-lock.js";
 import { SessionScopedRunRegistry, snapshotFromLiveRun } from "./registry.js";
 import {
   ProviderSubagentParamsSchema,
@@ -49,6 +52,7 @@ import { eligibleModelCandidates, formatJevRoutingPrompt, toToolCandidates } fro
 import { JevRouter } from "./jev-router.js";
 import { routePreparedTasks, type RoutingCatalog } from "./dispatch-routing.js";
 import { runLocalPreflights } from "./dispatch-preflight.js";
+import { rankedMaxAttempts } from "./model-failover.js";
 import type { RoutingReceipt } from "./routing-types.js";
 import { buildRoutingEvent, foldRoutingReceipts, MAX_ROUTING_DELIVERY_IDS, ROUTING_ENTRY_TYPE, type PersistedRoutingEvent } from "./persistence.js";
 
@@ -318,7 +322,7 @@ function compactDetails(
       errorMessage: result.errorMessage?.slice(0, 1_000),
       usage: result.usage ?? emptyUsage(),
       model: result.model,
-      routing: result.routing,
+      routing: projectRoutingForDisplay(result.routing),
       thinking: result.thinking,
       profile: result.profile,
       canWrite: result.canWrite,
@@ -332,7 +336,8 @@ function compactDetails(
       wrappedUp: result.wrappedUp,
       stalledSince: result.stalledSince,
       attempts: result.attempts,
-      attemptedModels: result.attemptedModels,
+      ...projectAttemptsForDisplay(result, Math.min(4_096, perResultText)),
+      toolActivity: result.toolActivity,
       structuredOutput: result.structuredOutput,
       structuredError: result.structuredError,
     })),
@@ -430,7 +435,7 @@ async function runPlanPreflights(
   });
 }
 
-function formatPlanEntry(task: ResolvedTask, index: number) {
+function formatPlanEntry(task: ResolvedTask, index: number, maxRetriesDefault: number) {
   const agentNote = task.resolutionNotes.find((note) => note.startsWith("agent="));
   const agent = agentNote?.slice("agent=".length);
   return {
@@ -438,12 +443,16 @@ function formatPlanEntry(task: ResolvedTask, index: number) {
     label: task.label,
     agent,
     model: task.model,
-    fallbackModels: task.fallbackModels,
+    // The ranked route replaces legacy fallback semantics for this path: show
+    // the bounded ranked preview and the effective extension attempt budget.
+    rankedPreview: formatRankedPreview(task.routing?.rankedModels),
+    rankedTotal: task.routing?.rankedModels?.length,
+    maxAttempts: rankedMaxAttempts(task.maxRetries ?? maxRetriesDefault),
     thinking: task.thinking,
     profile: task.profile,
     access: task.canWrite ? "RW" : "RO" as const,
     tools: task.effectiveTools,
-    routing: task.routing,
+    routing: projectRoutingForDisplay(task.routing),
     budgets: {
       timeoutMs: task.timeoutMs,
       maxTurns: task.maxTurns,
@@ -466,8 +475,10 @@ function formatPlanText(mode: "single" | "parallel", plan: ReturnType<typeof for
     ].filter(Boolean).join(" ");
     return [
       `${entry.index + 1}. ${entry.label}${entry.agent ? ` [agent:${entry.agent}]` : ""} (${entry.profile}/${entry.access})`,
-      `   model=${entry.model ?? "(none)"} fallback_models=[${(entry.fallbackModels ?? []).join(", ")}] thinking=${entry.thinking ?? "(default)"} isolation=${entry.isolation}`,
-      `   tools=[${entry.tools.join(",")}]`,
+      `   model=${entry.model ?? "(none)"} thinking=${entry.thinking ?? "(default)"} isolation=${entry.isolation}`,
+      `   ranked_models=[${entry.rankedPreview ?? entry.model ?? "(none)"}]${entry.rankedTotal && entry.rankedTotal > 5 ? ` (total ${entry.rankedTotal})` : ""}`,
+      `   attempt_budget=${entry.maxAttempts} (max_retries limits EXTRA extension-level attempts; pre-tool availability failure advances the ranking, never wraps)`,
+      `   shared_tools=[${entry.tools.join(",")}]`,
       `   ${budgets}`,
       `   notes: ${entry.resolutionNotes.join(", ")}`,
     ].join("\n");
@@ -502,7 +513,7 @@ function guidelines(catalog?: Map<string, AgentDefinition>): string[] {
     "Profiles: explore/review are strictly read-only (safe for fanout); general offers the full available locally permitted catalog to Jev and may write. Explicit tools are a ceiling; agent tool defaults do not narrow candidates. Single tasks default to general, parallel tasks to explore.",
     "Parallel writers need isolation:'worktree' (each gets an isolated checkout; changed work lands on a branch). After a worktree run finishes, use action:'diff' to inspect, then 'apply' to bring changes into the main checkout or 'discard' to drop them.",
     "Set budgets: at max_turns/max_cost the child is steered to wrap up and given grace turns for a final answer (grace_turns tunes this); results end as 'partial' with wrappedUp:true when the child concluded. timeout_ms includes Jev selection, setup, queue and retries; max_cost excludes unreported TypeSafe currency; timeout results report the phase.",
-    "Transient child failures may retry on the already selected model/tools within the original deadline; no selector retries or fallback models. Task-quality failures never retry.",
+    "Transient child failures may retry within the same invocation: ranked Jev routes advance to the next probability-ranked candidate only for a recognized model-availability failure that settles before any tool execution, sharing one task-based tool set and the total max_retries attempt budget (0 = first attempt only; never wraps back). A tool that started, uncertain evidence, or auth/quota/context/schema failures stop without switching. No selector retries or emergency models are used. Task-quality failures never retry.",
     "context:'fork' starts a single child from a branched copy of this conversation — use it when the task depends on discussion context instead of re-explaining. Single-task only.",
     "Use async:true only when you have independent work meanwhile; then use action:'wait' with the run id (interruptible, does not cancel). action:'steer' injects mid-run guidance into a running child instead of cancel + retry.",
     "For parallel research, add synthesis:'<instruction>' to have one read-only child fold all outputs into a single brief, delivered first.",
@@ -614,7 +625,8 @@ function buildCompletionDetails(runtime: SessionRuntime, runIds: string[]): Comp
         tokens: (result.usage?.input ?? 0) + (result.usage?.output ?? 0),
         cost: result.usage?.cost ?? 0,
         model: result.model,
-        attemptedModels: result.attemptedModels,
+        attempts: result.attempts,
+        attemptedModels: projectAttemptsForDisplay({ attemptedModels: result.attemptedModels }).attemptedModels,
         pointers: taskPointers,
       };
     });
@@ -632,6 +644,7 @@ function buildCompletionDetails(runtime: SessionRuntime, runIds: string[]): Comp
       // Preserve the old top-level fields only for single-task consumers. The
       // complete per-task model/attempt data lives in tasks[].
       model: tasks.length === 1 ? first?.model : undefined,
+      attempts: tasks.length === 1 ? first?.attempts : undefined,
       attemptedModels: tasks.length === 1 ? first?.attemptedModels : undefined,
       pointers,
       tasks,
@@ -665,7 +678,7 @@ function scheduleMaintenance(runtime: SessionRuntime): void {
     const keep = new Set(runtime.registry.planSessionRetention().keep);
     const busy = new Set<string>();
     for (const record of runtime.locks.listRunRecords()) {
-      if (record.state === "running" && record.childSessionId) busy.add(record.childSessionId);
+      if (record.state === "running") for (const id of runRecordSessionIds(record)) busy.add(id);
     }
     for (const run of runtime.registry.getLiveRuns(runtime.key)) {
       for (const id of run.childSessionIds) busy.add(id);
@@ -912,6 +925,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
             state: run.state,
             preview: run.preview,
             model: run.model,
+            attempts: run.attempts,
             attemptedModels: run.attemptedModels,
             pointers: run.pointers,
             turns: run.turns,
@@ -920,7 +934,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           }];
           return tasks.map((task) => {
             const attemptText = task.attemptedModels && task.attemptedModels.length > 1
-              ? `; attempts: ${task.attemptedModels.join(" → ")}`
+              ? `; attempts${task.attempts ? ` (${task.attempts} total)` : ""}: ${task.attemptedModels.join(" → ")}`
               : "";
             const label = tasks.length > 1 ? `${run.label}/${task.label}` : task.label;
             return `- [${run.id.slice(0, 8)}] ${label}: ${task.state}${task.model ? ` on ${task.model}` : ""}${attemptText}${task.preview ? ` — ${task.preview}` : ""}${task.pointers.length ? ` (${task.pointers.join(", ")})` : ""}`;
@@ -1025,6 +1039,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           tokens: run.tokens,
           cost: run.cost,
           model: run.model,
+          attempts: run.attempts,
           attemptedModels: run.attemptedModels,
           pointers: run.pointers,
         }];
@@ -1041,7 +1056,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           lines.push(truncateToWidth(`${glyph} ${theme.fg("dim", task.model ?? "model unknown")} · ${theme.bold(theme.fg("toolTitle", label))} ${theme.fg("dim", `[${run.id.slice(0, 8)}] ${stats}`)}`, width));
           if (task.preview) lines.push(truncateToWidth(`  ${theme.fg("dim", "⎿")} ${theme.fg("toolOutput", task.preview)}`, width));
           if (task.attemptedModels && task.attemptedModels.length > 1) {
-            lines.push(truncateToWidth(`  ${theme.fg("warning", `models: ${task.attemptedModels.join(" → ")}`)}`, width));
+            lines.push(truncateToWidth(`  ${theme.fg("warning", `models: ${task.attemptedModels.join(" → ")}${task.attempts && task.attempts > task.attemptedModels.length ? ` (last ${task.attemptedModels.length} of ${task.attempts})` : ""}`)}`, width));
           }
           if ((expanded || tasks.length === 1) && task.pointers.length) {
             lines.push(truncateToWidth(theme.fg("dim", `  ${task.pointers.join(" · ")}`), width));
@@ -1339,7 +1354,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
             const planned = await routePreparedTasks(synthetic, catalog, router, {
               purpose: "plan", signal: routingScope.controller.signal, assertOwner: routingScope.assertOwner,
             });
-            synthesis = { state: "resolved", plan: formatPlanEntry(planned[0]!, 0) };
+            synthesis = { state: "resolved", plan: formatPlanEntry(planned[0]!, 0, runtime.config.maxRetries) };
           } catch (error) {
             routingScope.assertOwner();
             synthesis = { state: "blocked", error: error instanceof Error ? error.message : "Optional synthesis routing failed." };
@@ -1348,7 +1363,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
         routingScope.assertOwner();
         await requireRoutingPersistence(runtime);
         routingScope.assertOwner();
-        const plan = resolved.map((task, index) => formatPlanEntry(task, index));
+        const plan = resolved.map((task, index) => formatPlanEntry(task, index, runtime.config.maxRetries));
         const mode = validated.mode as "single" | "parallel";
         const receipts = [...routingScope.receipts.values()];
         const selectorUsage = await claimRoutingUsage(runtime, { ids: new Set(receipts.map((receipt) => receipt.requestId)) });
@@ -1612,6 +1627,9 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           wrappedUp: task.wrappedUp,
           stalledSince: task.stalledSince,
           attempts: task.attempts,
+          attemptedModels: task.attemptedModels,
+          toolActivity: task.toolActivity,
+          modelAttempts: task.modelAttempts,
           structuredOutput: task.structuredOutput,
           structuredError: task.structuredError,
         })),

package/src/format.ts

@@ -1,4 +1,7 @@
-import type { UsageStats, RunSnapshot, RunState, RunMode, TimeoutPhase } from './types.js';
+import type { UsageStats, RunSnapshot, RunState, RunMode, TimeoutPhase, ToolActivity, ModelAttemptRecord } from './types.js';
+import type { RankedModelOption } from './routing-types.js';
+import { utf8SafePrefix } from './model-failover.js';
+import { Buffer } from 'node:buffer';
 import type { Theme } from '@earendil-works/pi-coding-agent';
 import * as os from 'node:os';
 import { truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
@@ -67,7 +70,8 @@ export function formatUsage(usage: UsageStats, model?: string, compact = true):
 /**
  * Structural subset of the persisted Jev route metadata that the TUI can render.
  * `TaskRouting` structurally satisfies this; legacy/empty input yields `undefined` so
- * old runs simply render no route line.
+ * old runs simply render no route line. A truncated/ranked display preview is
+ * presentation only — it is never a valid routing decision or execution plan.
  */
 export interface RoutingLineInput {
   selectedModel?: string;
@@ -79,10 +83,86 @@ export interface RoutingLineInput {
   latencyMs?: number;
   outcome?: string;
   code?: string;
+  /** Display window of the probability ranking (bounded; never an execution plan). */
+  rankedModels?: readonly RankedModelOption[];
+  /** Total ranked candidates when the display window truncates the ranking. */
+  rankedTotal?: number;
 }
 
 const ROUTE_MAX_TOOLS = 8;
 const ROUTE_MAX_TOOL_NAME = 24;
+/** Ranked candidates named in compact/model-facing projections before counting. */
+export const RANKED_DISPLAY_LIMIT = 5;
+
+/**
+ * One shared bounded display projection for plan and compact details: keeps a
+ * small ranked window plus the total instead of echoing a maximum-size catalog
+ * into model-facing output. The truncated window is presentation only and is
+ * never reused as a routing decision or execution plan. Persisted/internal
+ * routing keeps the full bounded ranking.
+ */
+export function projectRoutingForDisplay<TRouting extends RoutingLineInput | undefined>(routing: TRouting): RoutingLineInput | undefined {
+  if (!routing || typeof routing !== 'object') return undefined;
+  const { rankedModels, ...rest } = routing;
+  if (!Array.isArray(rankedModels) || rankedModels.length === 0) return { ...rest };
+  return {
+    ...rest,
+    rankedModels: rankedModels.slice(0, RANKED_DISPLAY_LIMIT),
+    rankedTotal: rankedModels.length,
+  };
+}
+
+/**
+ * One bounded ranked preview: `a=.65>b=.25>c=.10` plus the total when more
+ * candidates exist. Model IDs are shortened to their last path segment so a
+ * large configured catalog stays inside display bounds; full bounded ranking
+ * remains available internally on the routing object.
+ */
+export function formatRankedPreview(
+  ranked: readonly RankedModelOption[] | undefined,
+  limit = RANKED_DISPLAY_LIMIT,
+): string | undefined {
+  if (!Array.isArray(ranked) || ranked.length === 0) return undefined;
+  const short = (model: unknown): string | undefined => {
+    if (typeof model !== 'string' || !model.trim()) return undefined;
+    const parts = model.split('/');
+    return parts[parts.length - 1] ?? model;
+  };
+  const shown: string[] = [];
+  for (const entry of ranked.slice(0, Math.max(1, limit))) {
+    if (!entry || typeof entry !== 'object') return undefined; // malformed shape: display-skip whole preview, never execute
+    const name = short(entry.model);
+    if (!name) return undefined;
+    const probability = typeof entry.probability === 'number' && Number.isFinite(entry.probability)
+      ? `=${entry.probability.toFixed(2)}`
+      : '';
+    shown.push(`${name}${probability}`);
+  }
+  const remaining = ranked.length - shown.length;
+  return remaining > 0 ? `${shown.join('>')} +${remaining}` : shown.join('>');
+}
+
+/** Descriptive tail preview only; full histories remain in the run store. */
+export function projectAttemptsForDisplay(
+  result: { modelAttempts?: readonly ModelAttemptRecord[]; attemptedModels?: readonly string[] },
+  maxBytes = 4_096,
+) {
+  const modelAttempts = result.modelAttempts?.slice(-RANKED_DISPLAY_LIMIT).map((record) => ({
+    ...record,
+    outputPreview: record.outputPreview ? utf8SafePrefix(record.outputPreview, 128) : undefined,
+  }));
+  const attemptedModels = result.attemptedModels?.slice(-RANKED_DISPLAY_LIMIT);
+  const projected = {
+    modelAttempts, modelAttemptsTotal: result.modelAttempts?.length,
+    attemptedModels, attemptedModelsTotal: result.attemptedModels?.length,
+  };
+  while (Buffer.byteLength(JSON.stringify(projected), 'utf8') > Math.max(256, maxBytes)
+    && (modelAttempts?.length || attemptedModels?.length)) {
+    modelAttempts?.shift();
+    attemptedModels?.shift();
+  }
+  return projected;
+}
 
 function summarizeRoutingTools(tools: readonly string[]): string {
   const shown = tools.slice(0, ROUTE_MAX_TOOLS).map((name) => (name.length > ROUTE_MAX_TOOL_NAME ? `${name.slice(0, ROUTE_MAX_TOOL_NAME - 1)}…` : name));
@@ -121,6 +201,11 @@ export function formatRouteLine(routing?: RoutingLineInput, max = 160): string |
   if (selectedModel) parts.push(selectedModel);
   const selector = selectorModel ? (selectorVersion ? `${selectorModel}@${selectorVersion}` : selectorModel) : selectorVersion;
   if (selector) parts.push(`sel ${selector}`);
+  const rankedPreview = formatRankedPreview(routing.rankedModels, ROUTE_MAX_TOOLS);
+  if (rankedPreview) {
+    const total = typeof routing.rankedTotal === 'number' && routing.rankedTotal > 0 ? routing.rankedTotal : (Array.isArray(routing.rankedModels) ? routing.rankedModels.length : 0);
+    parts.push(`rank ${rankedPreview}${total > RANKED_DISPLAY_LIMIT ? ` (of ${total})` : ''}`);
+  }
   if (confidence !== undefined) parts.push(`conf ${confidence.toFixed(2)}`);
   parts.push(`tools ${selectedTools && selectedTools.length ? summarizeRoutingTools(selectedTools) : 'none'}`);
   if (mandatoryTools && mandatoryTools.length) parts.push(`+${summarizeRoutingTools(mandatoryTools)}`);
@@ -210,6 +295,11 @@ export interface InlineTaskView {
   wrappedUp?: boolean;
   stalledSince?: number;
   attempts?: number;
+  attemptedModels?: string[];
+  /** Sticky pre-tool boundary state across this task's attempts. */
+  toolActivity?: ToolActivity;
+  /** Bounded ranked attempt history (reasons for switches; previews capped). */
+  modelAttempts?: ModelAttemptRecord[];
   structuredOutput?: unknown;
   structuredError?: string;
   /** Bounded Jev route metadata; rendered only on expanded surfaces. */
@@ -256,7 +346,12 @@ function statsText(agg: AggregateStats, durationMs?: number): string {
 
 function taskAnnotations(task: InlineTaskView, now: number): string[] {
   const notes: string[] = [];
-  if (task.attempts && task.attempts > 1) notes.push(`attempt ${task.attempts}`);
+  if (task.attempts && task.attempts > 1) {
+    const chain = Array.isArray(task.attemptedModels) && task.attemptedModels.length > 1
+      ? ` (${task.attemptedModels.slice(0, 3).map((m) => m.split('/').pop() ?? m).join('>')}${task.attemptedModels.length > 3 ? '…' : ''})`
+      : '';
+    notes.push(`attempt ${task.attempts}${chain}`);
+  }
   if (task.stalledSince && isActiveState(task.state)) notes.push(`stalled ${formatDuration(now - task.stalledSince)}`);
   if (!isActiveState(task.state)) {
     if (task.structuredOutput !== undefined) notes.push('✓ schema');

package/src/jev-router.ts

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { Semaphore } from "./semaphore.js";
 import { isThinkingLevel } from "./thinking.js";
 import { normalizeRoutingApiKey } from "./routing-policy.js";
+import { choiceIsMaximal, orderRankedModels } from "./model-failover.js";
 import {
   DEFAULT_ROUTING_CONCURRENCY,
   MAX_ROUTING_MODEL_ID_LENGTH,
@@ -25,6 +26,7 @@ import {
   type RoutingSelectInput,
   type RoutingSelectOptions,
   type RoutingToolCandidate,
+  type RankedModelOption,
 } from "./routing-types.js";
 
 // Re-exported so integration can import the selector contract from the router module.
@@ -56,6 +58,14 @@ export type {
  * Guarantees:
  * - One model Choice first, then one binary include/exclude Choice per eligible tool, packed
  *   into bounded requests. Every eligible tool is asked; nothing is truncated or ranked.
+ * - The model Choice's full validated probability distribution is retained as the
+ *   deterministic `rankedModels` ordering (descending probability, returned choice first
+ *   among a tied maximum, then configured order). The returned `choice` must be a
+ *   maximum-probability option; a contradictory answer is an invalid decision, never a
+ *   silently substituted model. Zero/low probabilities remain valid candidates.
+ * - Tool questions are task-based and model-independent: the selection state never
+ *   conditions on the chosen execution model, so one shared subset serves every ranked
+ *   attempt and fallback issues no further selector requests.
  * - A single logical deadline = min(config.timeoutMs, caller absolute deadline) spans every
  *   request and all limiter waiting. Concurrent HTTP requests are bounded to two by default.
  * - Only `https://api.typesafe.ai/v1/systemone` with `redirect:"error"`; the Bearer key comes
@@ -167,6 +177,8 @@ interface AnswerValidation {
   selectorVersion: string;
   choices: ReadonlyMap<string, string>;
   confidences: ReadonlyMap<string, number>;
+  /** Per-question option probabilities exactly as validated (full option coverage). */
+  probabilities: ReadonlyMap<string, ReadonlyMap<string, number>>;
 }
 
 interface AnswerInvalid {
@@ -188,8 +200,9 @@ const MODEL_INSTRUCTIONS =
 const TOOL_INSTRUCTIONS =
   "Decide whether this single tool should be enabled for the delegated task described in state. "
   + "Choose 'include' only when this tool is relevant to completing that task; otherwise choose "
-  + "'exclude'. The tool name and description are in the criteria; option keys are correlation "
-  + "IDs. Each question is independent.";
+  + "'exclude'. This decision is about the task alone and must not depend on which model "
+  + "executes it. The tool name and description are in the criteria; option keys are "
+  + "correlation IDs. Each question is independent.";
 
 const ROUTING_PROFILES = new Set<RoutingProfile>(["explore", "review", "general"]);
 const ROUTING_PURPOSES = new Set<RoutingPurpose>(["plan", "dispatch", "synthesis"]);
@@ -357,6 +370,7 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
 
   const choices = new Map<string, string>();
   const confidences = new Map<string, number>();
+  const probabilitySets = new Map<string, ReadonlyMap<string, number>>();
   for (const question of questions) {
     const answer = answers.get(question.id);
     if (answer === undefined) {
@@ -376,22 +390,24 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
       return invalid("invalid_decision", "The TypeSafe routing response chose an option that was not offered for one of the questions.");
     }
 
-    const probabilities = record.probabilities;
-    if (!probabilities || typeof probabilities !== "object" || Array.isArray(probabilities)) {
+    const rawProbabilities = record.probabilities;
+    if (!rawProbabilities || typeof rawProbabilities !== "object" || Array.isArray(rawProbabilities)) {
       return invalid("malformed_response", "A TypeSafe routing answer did not include an option probability set.");
     }
-    const probRecord = probabilities as Record<string, unknown>;
+    const probRecord = rawProbabilities as Record<string, unknown>;
     const keys = Object.keys(probRecord);
     if (keys.length !== question.options.length || question.options.some((option) => !keys.includes(option))) {
       return invalid("malformed_response", "A TypeSafe routing answer probability set did not match the offered options.");
     }
     let sum = 0;
+    const optionProbabilities = new Map<string, number>();
     for (const option of question.options) {
       const value = probRecord[option];
       if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
         return invalid("malformed_response", "A TypeSafe routing answer reported a probability outside the finite range 0..1.");
       }
       sum += value;
+      optionProbabilities.set(option, value);
     }
     if (Math.abs(sum - 1) > PROBABILITY_SUM_TOLERANCE) {
       return invalid("malformed_response", `A TypeSafe routing answer probability set did not sum to 1 within the documented tolerance (${PROBABILITY_SUM_TOLERANCE}).`);
@@ -404,8 +420,9 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
 
     choices.set(question.id, choice);
     confidences.set(question.id, confidence);
+    probabilitySets.set(question.id, optionProbabilities);
   }
-  return { ok: true, selectorVersion, choices, confidences };
+  return { ok: true, selectorVersion, choices, confidences, probabilities: probabilitySets };
 }
 
 function selectorStatusFailure(status: number): { code: RoutingFailureCode; message: string } {
@@ -424,7 +441,7 @@ function selectorStatusFailure(status: number): { code: RoutingFailureCode; mess
   return { code: "http_error", message: `TypeSafe returned an unexpected HTTP status (${status}) for the routing request.` };
 }
 
-function buildState(input: RoutingSelectInput, selectedModel: string | undefined): Record<string, unknown> {
+function buildState(input: RoutingSelectInput): Record<string, unknown> {
   const state: Record<string, unknown> = { task: input.task };
   const constraints = input.constraints;
   if (constraints) {
@@ -434,7 +451,8 @@ function buildState(input: RoutingSelectInput, selectedModel: string | undefined
       ...(constraints.structuredOutput === undefined ? {} : { structured_output: constraints.structuredOutput }),
     };
   }
-  if (selectedModel !== undefined) state.selected_model = selectedModel;
+  // Tool selection is deliberately model-independent: no selected_model is ever
+  // added, so one task-based tool subset is shared by every ranked execution attempt.
   return state;
 }
 
@@ -656,11 +674,11 @@ export class JevRouter {
       return this.fail("transport_error", "No fetch implementation is available for TypeSafe routing.", call);
     }
 
-    // Preflight grossly oversized single tool questions before paying for the model request.
-    // This uses the minimum state (no selected model yet); the residual case where adding the
-    // chosen model ID pushes a question over the bound is still rejected before tool HTTP.
+    // Preflight grossly oversized single tool questions before paying for the model
+    // request. Tool state is task-only and model-independent, so the probe state equals
+    // the real request state and the residual size case is fully preflighted here.
     if (tools.length > 0) {
-      const probe = packToolBatches(tools, buildState(input, undefined), this.config.selectorModel);
+      const probe = packToolBatches(tools, buildState(input), this.config.selectorModel);
       if ("error" in probe) return this.fail(probe.error.code, probe.error.message, call);
     }
 
@@ -679,7 +697,7 @@ export class JevRouter {
 
       // ---- 1. Model Choice ------------------------------------------------------------
       const modelQuestion = buildModelQuestion(models);
-      const modelRequest = serializeRequest(this.config.selectorModel, buildState(input, undefined), [modelQuestion]);
+      const modelRequest = serializeRequest(this.config.selectorModel, buildState(input), [modelQuestion]);
       if (!withinRequestLimit(modelRequest)) {
         return this.fail(
           "request_too_large",
@@ -704,7 +722,7 @@ export class JevRouter {
       }
       const modelChoice = modelValidation.choices.get("model");
       const modelIndex = modelChoice === undefined ? -1 : modelQuestion.options.indexOf(modelChoice);
-      if (modelIndex < 0) {
+      if (modelIndex < 0 || typeof modelChoice !== "string") {
         if (modelIssue.receipt) this.markReceiptFailed(modelIssue.receipt, "invalid_decision", call);
         return this.fail("invalid_decision", "The TypeSafe routing response did not select a valid candidate model.", call);
       }
@@ -713,10 +731,31 @@ export class JevRouter {
       const primaryVersion = modelValidation.selectorVersion;
       const versions: string[] = [primaryVersion];
 
-      // ---- 2. One binary Choice per eligible tool ------------------------------------
+      // ---- 1b. Probability ranking (retained distribution) ---------------------------
+      // Official Choice contract: `choice` is a highest-probability option. A response
+      // that contradicts its own distribution is rejected, never substituted.
+      const modelProbabilities = modelValidation.probabilities.get("model");
+      if (!modelProbabilities) {
+        if (modelIssue.receipt) this.markReceiptFailed(modelIssue.receipt, "malformed_response", call);
+        return this.fail("malformed_response", "The TypeSafe routing answer did not include the validated option probability set.", call);
+      }
+      const choiceProblem = choiceIsMaximal(modelProbabilities, modelChoice, selectedModel);
+      if (choiceProblem) {
+        if (modelIssue.receipt) this.markReceiptFailed(modelIssue.receipt, "invalid_decision", call);
+        return this.fail("invalid_decision", `The TypeSafe routing answer contradicts its own probability distribution: ${choiceProblem}.`, call);
+      }
+      const rankedModels: readonly RankedModelOption[] = Object.freeze(orderRankedModels(
+        models.map((candidate, index) => ({
+          model: candidate.model,
+          probability: modelProbabilities.get(modelQuestion.options[index]!) ?? 0,
+        })),
+        selectedModel,
+      ));
+
+      // ---- 2. One binary Choice per eligible tool (task-based, model-independent) ----
       const selectedTools: string[] = [];
       if (tools.length > 0) {
-        const packed = packToolBatches(tools, buildState(input, selectedModel), this.config.selectorModel);
+        const packed = packToolBatches(tools, buildState(input), this.config.selectorModel);
         if ("error" in packed) return this.fail(packed.error.code, packed.error.message, call);
 
         const settled = await Promise.all(packed.batches.map(async (batch, index) => {
@@ -761,6 +800,7 @@ export class JevRouter {
         ...(options.taskIndex === undefined ? {} : { taskIndex: options.taskIndex }),
         selectedModel,
         selectedTools: Object.freeze(selectedTools),
+        rankedModels,
         ...(modelConfidence === undefined ? {} : { confidence: modelConfidence }),
         selectorModel: this.config.selectorModel,
         selectorVersion: primaryVersion,