@sangyaahub/pi-marg 1.0.1 → 1.0.4

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "PiMarg — a governed development path for Pi Agent and Oh My Pi.",
-    "version": "1.0.1"
+    "version": "1.0.4"
   },
   "plugins": [
     {
       "name": "pi-marg",
       "description": "Intent-led development workflow with live A/B/C/D routing, capability detection, verification, and approval gates.",
       "source": "./",
-      "version": "1.0.1",
+      "version": "1.0.4",
       "author": {
         "name": "Sangyaa",
         "email": "contact@sangyaa.co"

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.0.4 — 2026-09-17
+
+- Added two runtime-only recovery choices: a strong **high** backup followed by an economical **low** backup.
+- Automatically switches and resumes after OMP or Pi settles a usage-limit/quota failure, with a visible notification and a no-repeat-side-effects continuation instruction.
+- Handles direct runtime-model failures and detected model-execution tool failures (including external Devin and subagents); old v1 session routes migrate without losing their A/B/C/D selections.
+- Deduplicates repeated failure events, ignores transient throttles, advances to low only when the active high model fails, restores Pi tree-navigation state, and warns without stranding the run if ledger persistence fails after activation.
+
+## 1.0.3 — 2026-09-14
+
+- Made model routing explicitly model-agnostic: live OMP/Pi authenticated catalogs are the only source of truth, with soft preferred-class ranking that never requires a maintainer's subscriptions.
+- Promotes provider/subscription setup when the live catalog is empty (`/login` + `omp models` on OMP; `pi --list-models` on Pi).
+- Shows required A/B/C/D stage options and catalog sections in ascending letter order.
+
+## 1.0.2 — 2026-09-12
+
+- Changed live catalog presentation to a provider-first numbered two-step: list every authenticated provider, then every model for the chosen provider.
+- Added optional `provider` filter on `auto_model_route` catalog so agents can request one provider's full model list without truncating giant catalogs.
+- Documented an OMP catalog advisory when both `cursor` and `openai-codex` are live: mid-session switches can hit a harness `call_id` max-length 64 rejection (tracked upstream in `@oh-my-pi/pi-coding-agent`); recover with a fresh session that does not replay the affected tool history.
+
 ## 1.0.1 — 2026-09-10
 
 - Added the global `pi-marg start` and `pi-marg "<work prompt>"` OMP launch commands.

package/MODEL-SETUP.md

@@ -1,6 +1,6 @@
 # Model setup
 
-PiMarg reads the active Pi or OMP model registry whenever `auto_model_route` runs. Exact selectors are deliberately absent from this document because providers rename and replace models.
+PiMarg reads the active Pi or OMP model registry whenever `auto_model_route` runs. It is model-agnostic: whatever subscriptions or providers someone has configured are what appear in the catalog. Exact selectors are deliberately absent from this document because providers rename and replace models.
 
 ```text
 LIVE AUTHENTICATED CATALOG
@@ -11,15 +11,20 @@ LIVE AUTHENTICATED CATALOG
    A / C          B / D
      │             │
      └─ different ─┘ within each pair
+            │
+            ▼ quota failure
+   high backup ──► low backup
 ```
 
+If the live catalog is empty, PiMarg stops and promotes provider/subscription setup instead of guessing models.
+
 ## Roles
 
-| Stage | Purpose | Preferred class |
+| Stage | Purpose | Preferred class (optional ranking) |
 |---|---|---|
-| A | Discovery and difficult reasoning | Latest eligible Claude frontier, OpenAI frontier, or Grok frontier |
+| A | Discovery and difficult reasoning | Latest eligible Claude frontier, OpenAI frontier, or Grok frontier when present |
+| B | Execute the accepted plan | Claude/OpenAI mid-layer, Cursor Composer, eligible zero-metered route, or Devin SWE when present |
 | C | Independent plan review | A different frontier model/family from A |
-| B | Execute the accepted plan | Claude/OpenAI mid-layer, Cursor Composer, eligible zero-metered route, or Devin SWE |
 | D | Independent implementation review | A different execution model/family from B |
 
 “Zero-metered” means the runtime reports zero token price for that route. Subscription quotas and pool limits can still apply.
@@ -48,15 +53,54 @@ The OMP adapter reads `ctx.models.list()`, which supplies authenticated and enab
 
 1. Run `/pi-marg` for the full native intake, or `/auto-models choose` to change saved models.
 2. Confirm the work type so PiMarg knows which stages are required.
-3. Select A and C when discovery/review is required; recommended frontier choices appear first.
-4. Select B and D when implementation is required; recommended execution choices appear first.
-5. Resolve any A=C or B=D identity conflict before continuing.
-6. Activate the saved selector immediately before its stage.
+3. Required stage prompts and catalog sections are always shown in ascending order: **A, then B, then C, then D** (skipping stages that do not apply).
+4. For each required stage, choose a **provider** first (numbered `1. …`), then a **model** from that provider (numbered `1. …`). Exact `provider/id` selectors are the selection keys—not display numbers alone.
+5. Select A and C when discovery/review is required; recommended frontier choices appear first within their lists when recognizable, but every live model remains selectable.
+6. Select B and D when implementation is required; recommended execution choices appear first within their lists when recognizable, but every live model remains selectable.
+7. Resolve any A=C or B=D identity conflict before continuing.
+8. Activate the saved selector immediately before its stage.
+9. Choose a runtime-only **high backup** (strongest recovery fit) and a distinct runtime-only **low backup** (economical recovery fit). External-agent entries cannot be backups because PiMarg must be able to activate them in the current session.
+10. Automatic recovery becomes active only after both backups are saved. On a positively identified terminal usage-limit failure, PiMarg preserves the stage, waits for the runtime to settle, switches high then low, notifies the user, and resumes from the last safe point. Duplicate events and temporary throttles do not consume another backup.
+
+### Tool form (`auto_model_route`)
+
+```text
+# 1) Overview: every provider, no model dump
+auto_model_route action=catalog workType=<n>
+
+# 2) Full model list for one authenticated provider
+auto_model_route action=catalog workType=<n> provider=<provider-name>
 
-Every authenticated and enabled runtime model remains selectable at every required stage. The preferred classes above control ranking, not visibility.
+# 3) Persist and activate an exact selector
+auto_model_route action=select stage=<A|B|C|D> target=<provider>/<model-id> workType=<n>
+
+# 4) Persist the automatic recovery pair (does not activate either model yet)
+auto_model_route action=select_fallback fallback=high target=<provider>/<model-id>
+auto_model_route action=select_fallback fallback=low target=<provider>/<model-id>
+```
+
+Never present a hand-curated subset that omits a logged-in provider. Every authenticated and enabled runtime model remains selectable at every required stage. Soft preferred-class ranking controls order, not visibility.
 
 The normalized identity check treats the same underlying model reached through different providers as the same candidate when their identifiers normalize equally.
 
+### OMP cursor → openai-codex note
+
+On OMP with `@oh-my-pi/pi-coding-agent` 18.1.17, switching from a `cursor` stage to an `openai-codex` stage in the **same** session can fail if prior `cursor-agent` tool ids are replayed (`call_id` longer than 64). PiMarg surfaces this as a catalog advisory when both providers are live. Workaround: start a **fresh session** that does not replay the affected tool history. The durable fix belongs in the harness, not in PiMarg selectors.
+
+## Provider recommendation (optional ranking only)
+
+These names are soft ranking hints for common catalogs. They are never required. If your subscriptions expose different models, PiMarg still lists every authenticated entry and lets you choose.
+
+- Cursor Composer or a zero-metered Cursor route: economical B/D work when present in the live catalog.
+- Claude Fable/Opus: A/C product thinking, architecture, specification, and cross-family review.
+- Claude Sonnet: B/D mid-layer implementation or review.
+- OpenAI Astra/Sol: A/C complex discovery and plan review.
+- OpenAI Terra/Luna/Codex-class: B/D implementation and review, chosen by task risk and cost.
+- Latest matching Grok 4.6-or-newer model: A/C independent frontier analysis or current web/social context.
+- Native Devin SWE: B/D when exposed by the runtime. External Devin: bounded delegation with acceptance criteria and a quota limit.
+
+Use Pi or OMP's own authentication and model UI as the authority for what the account can actually access. When nothing is authenticated, set up any subscription first (`/login` on OMP, or Pi provider credentials), then re-run PiMarg.
+
 ## Devin
 
 Native Devin model entries are ordinary B/D candidates when the runtime catalog exposes them. A separate external Devin session appears only when a Devin tool is detected. Creating that session is a web mutation and requires one-use `post-web` approval.

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.1" src="https://img.shields.io/badge/version-1.0.1-0451F7"></a>
+  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.4" src="https://img.shields.io/badge/version-1.0.4-0451F7"></a>
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-C27B1A"></a>
   <a href="https://pi.dev/packages?name=pi-marg"><img alt="Pi package" src="https://img.shields.io/badge/Pi-package-0338A8"></a>
   <a href="https://omp.sh"><img alt="Oh My Pi plugin" src="https://img.shields.io/badge/OMP-plugin-021E5C"></a>
@@ -11,7 +11,7 @@
 
 # PiMarg
 
-**Version 1.0.1 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
+**Version 1.0.4 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
 
 PiMarg turns an ordinary prompt into a governed development path. It identifies the work boundary, selects one engineering method, discovers the models and tools the active runtime really provides, separates thinking from execution, records evidence, and stops before protected actions.
 
@@ -55,14 +55,14 @@ The same model-selection and approval logic lives in `core/`. Runtime-specific c
 |---|---|---|
 | Ordinary prompts enter the workflow | Pi bootstrap hook | OMP global rule |
 | Shared skills and decision flow | Yes | Yes |
-| Dynamic A/B/C/D model routing | Pi model registry | OMP model registry |
+| Dynamic A/B/C/D model routing + high/low failover | Pi model registry | OMP model registry |
 | Approval guard | Pi event adapter | OMP event adapter |
 | Slash workflow entry points | Pi prompt templates | OMP commands |
 | CodeGraph | CLI/integration when detected | MCP integration when configured |
 | Advisor, checkpoint, security scan, Hindsight | Extension/fallback when detected | Native capability when enabled |
 | Parallel agents | Only when a compatible task extension exists | Native `task`/workflow routes when available |
 
-Tested locally against Pi Agent `0.85.1` and OMP `18.1.15`. Optional features are always capability-detected, so their absence produces a recorded fallback rather than a false success claim.
+Tested locally against Pi Agent `0.85.1` and OMP `18.2.1`. Optional features are always capability-detected, so their absence produces a recorded fallback rather than a false success claim.
 
 ## Try the demo
 
@@ -141,11 +141,25 @@ pi-marg "add CSV export to this repository"
 /auto add CSV export to this repository
 ```
 
-The native picker asks for work boundary, work type, workflow skill, and every model required by that work type. It shows only models reported as authenticated and enabled by OMP, with recommended stage fits first.
+The native picker asks for work boundary, work type, workflow skill, every model required by that work type, then two distinct runtime backups: **high** first and **low** second. Automatic recovery stays disabled until both are saved. It shows only models reported as authenticated and enabled by OMP, with recommended fits first.
+
+```text
+stage model hits quota
+          │
+          ▼
+   OMP/Pi native retry
+          │ still failed
+          ▼
+   high backup ──fails──► low backup
+          │                    │
+          └──── notify + resume┘
+```
+
+PiMarg switches only after a positively identified terminal usage-limit/quota failure (or a settled model-execution tool failure such as external Devin or a subagent); a temporary 429/rate-limit response does not consume a backup. It records and deduplicates each failure, advances from high to low only when the active high model itself fails, notifies the user, and resumes with an instruction to inspect current state before repeating any side effect. If both backups are exhausted, it stops with an actionable request to run the model chooser again.
 
 Useful entry points:
 
-- `/auto-models choose` — refresh A/B/C/D choices.
+- `/auto-models choose` — refresh A/B/C/D choices and the high/low recovery pair.
 - `/auto-runtime status` — show detected capabilities and fallbacks.
 - `/auto-review plan|code` — run the independent review contract.
 - `/auto-status` — show the current ledger and evidence.

package/adapters/omp/extensions/model-router.ts

@@ -1,12 +1,27 @@
 import {
+  FALLBACK_LEVELS,
   MODEL_STATE_TYPE,
   STAGES,
+  buildFallbackCatalog,
   buildModelCatalog,
+  candidatesForProvider,
+  emptyCatalogSetupMessage,
   emptyModelRouteState,
+  executeAutomaticFailover,
   executeModelRoute,
+  failedModelSelector,
+  findTerminalUsageLimitFailure,
+  formatFailoverRecoveryMessage,
+  hasConfiguredFallback,
+  matchNumberedOption,
+  modelFailureKey,
+  modelToolUsageLimitFailure,
+  numberedOptionLabel,
   requiredStagesForWorkType,
   restoreModelRouteState,
+  uniqueProviders,
   type AutoStage,
+  type FallbackLevel,
   type ModelCandidate,
   type ModelLike,
   type ModelRouteParams,
@@ -14,7 +29,7 @@ import {
 } from "../../../core/model-routing";
 import { normalizeCapabilityNames } from "../../../core/runtime-capabilities";
 
-const WORK_BOUNDARIES = ["Job/client", "Personal"] as const;
+const WORK_BOUNDARIES = ["1. Job/client", "2. Personal"] as const;
 
 const WORK_TYPES = [
   "1. New idea or development from scratch",
@@ -40,6 +55,11 @@ const STAGE_PURPOSE: Record<AutoStage, string> = {
   D: "implementation second-eye review",
 };
 
+const FALLBACK_PURPOSE: Record<FallbackLevel, string> = {
+  high: "strong recovery model used first",
+  low: "economical recovery model used if high is unavailable or exhausted",
+};
+
 function hasExternalDevin(pi: any): boolean {
   return normalizeCapabilityNames(pi.getAllTools?.() ?? [])
     .some((name) => /(?:^|[_-])devin(?:[_-]|$)/i.test(name));
@@ -77,28 +97,99 @@ async function chooseModel(
     );
     return undefined;
   }
-  const options = eligible.map((candidate) => ({
-    label: optionLabel(candidate),
-    description: optionDescription(stage, candidate),
+
+  return chooseCandidateByProvider(ctx, eligible, {
+    providerTitle: `Stage ${stage} provider`,
+    modelTitle: `Stage ${stage} model`,
+    purpose: STAGE_PURPOSE[stage],
+    providerDescription: (name) => `All authenticated ${name} models for ${STAGE_PURPOSE[stage]}`,
+    modelDescription: (candidate) => optionDescription(stage, candidate),
+  });
+}
+
+async function chooseFallbackModel(
+  ctx: any,
+  level: FallbackLevel,
+  candidates: ModelCandidate[],
+  other?: ModelCandidate,
+): Promise<ModelCandidate | undefined> {
+  const eligible = candidates.filter((candidate) => (
+    candidate.access === "runtime-model" && (!other || candidate.identity !== other.identity)
+  ));
+  const title = level === "high" ? "High" : "Low";
+  if (eligible.length === 0) {
+    ctx.ui.notify(
+      "Automatic recovery requires two distinct authenticated runtime models. Configure another model, then run /pi-marg again.",
+      "error",
+    );
+    return undefined;
+  }
+
+  return chooseCandidateByProvider(ctx, eligible, {
+    providerTitle: `${title} backup provider`,
+    modelTitle: `${title} backup model`,
+    purpose: FALLBACK_PURPOSE[level],
+    providerDescription: (name) => `Authenticated ${name} models · ${FALLBACK_PURPOSE[level]}`,
+    modelDescription: (candidate) => (
+      `${FALLBACK_PURPOSE[level]}${candidate.billingNote ? ` · ${candidate.billingNote}` : ""}`
+    ),
+  });
+}
+
+async function chooseCandidateByProvider(
+  ctx: any,
+  candidates: ModelCandidate[],
+  copy: {
+    providerTitle: string;
+    modelTitle: string;
+    purpose: string;
+    providerDescription(provider: string): string;
+    modelDescription(candidate: ModelCandidate): string;
+  },
+): Promise<ModelCandidate | undefined> {
+  const providers = uniqueProviders(candidates);
+  const providerOptions = providers.map((name, index) => ({
+    label: numberedOptionLabel(index, `${name} (${candidatesForProvider(candidates, name).length})`),
+    description: copy.providerDescription(name),
   }));
-  const answer = await ctx.ui.select(`Stage ${stage} model`, options, {
+  const providerAnswer = await ctx.ui.select(copy.providerTitle, providerOptions, {
     selectionMarker: "radio",
-    helpText: `${eligible.length} authenticated and enabled choices · ${STAGE_PURPOSE[stage]}`,
+    helpText: `${providers.length} providers · ${candidates.length} models · ${copy.purpose}`,
   });
-  return eligible.find((candidate) => optionLabel(candidate) === answer);
+  const provider = matchNumberedOption(
+    providerAnswer,
+    providers,
+    (name) => `${name} (${candidatesForProvider(candidates, name).length})`,
+  );
+  if (!provider) return undefined;
+
+  const providerModels = candidatesForProvider(candidates, provider);
+  const modelOptions = providerModels.map((candidate, index) => ({
+    label: numberedOptionLabel(index, optionLabel(candidate)),
+    description: copy.modelDescription(candidate),
+  }));
+  const answer = await ctx.ui.select(copy.modelTitle, modelOptions, {
+    selectionMarker: "radio",
+    helpText: `${providerModels.length} ${provider} choices · ${copy.purpose}`,
+  });
+  return matchNumberedOption(answer, providerModels, optionLabel);
 }
 
 function selectedState(
   workType: number,
   selected: Partial<Record<AutoStage, ModelCandidate>>,
+  fallbacks: Record<FallbackLevel, ModelCandidate>,
 ): ModelRouteState {
   const selectedAt = new Date().toISOString();
   return {
-    version: 1,
+    version: 2,
     workType,
     selections: Object.fromEntries(
       Object.entries(selected).map(([stage, candidate]) => [stage, { ...candidate, selectedAt }]),
     ) as ModelRouteState["selections"],
+    fallbacks: Object.fromEntries(
+      Object.entries(fallbacks).map(([level, candidate]) => [level, { ...candidate, selectedAt }]),
+    ) as ModelRouteState["fallbacks"],
   };
 }
 
@@ -108,6 +199,7 @@ function intakeMessage(
   workType: string,
   skillMode: string,
   selected: Partial<Record<AutoStage, ModelCandidate>>,
+  fallbacks: Record<FallbackLevel, ModelCandidate>,
 ): string {
   const models = STAGES
     .filter((stage) => selected[stage])
@@ -122,15 +214,23 @@ function intakeMessage(
     `- Work type: ${workType}`,
     `- Workflow skill: ${skillMode}`,
     models,
+    `- High backup: ${fallbacks.high.selector}`,
+    `- Low backup: ${fallbacks.low.selector}`,
     "",
-    "Load auto-mode-router, record these choices in the session ledger, activate each saved model before its stage, and continue the workflow. Ask interactively only for information that is still missing.",
+    "Load auto-mode-router, record these choices in the session ledger, activate each saved model before its stage, and continue the workflow. If a terminal usage-limit failure occurs, PiMarg will switch high then low and resume from the last safe point. Ask interactively only for information that is still missing.",
   ].join("\n");
 }
 
 export default function modelRouter(pi: any) {
   const z = pi.zod;
   let state = emptyModelRouteState();
+  let recoveryToken: symbol | undefined;
+  let sessionGeneration = 0;
+  let pendingToolFailure: { selector: string; key: string } | undefined;
   const restore = (_event: unknown, ctx: any) => {
+    sessionGeneration += 1;
+    recoveryToken = undefined;
+    pendingToolFailure = undefined;
     state = restoreModelRouteState(ctx.sessionManager.getBranch());
   };
 
@@ -139,6 +239,93 @@ export default function modelRouter(pi: any) {
   pi.on("session_branch", restore);
   pi.on("session_tree", restore);
 
+  const recoverFromUsageLimit = async (failure: { selector: string; key: string }, ctx: any) => {
+    if (recoveryToken) return;
+    if (!hasConfiguredFallback(state)) return;
+    const generation = sessionGeneration;
+    const token = Symbol("pi-marg-recovery");
+    recoveryToken = token;
+    try {
+      const execution = await executeAutomaticFailover(state, failure.selector, {
+        runtimeName: "OMP",
+        models: ctx.models.list() as ModelLike[],
+        hasExternalDevin: hasExternalDevin(pi),
+        activate: (model) => pi.setModel(model),
+        persist: (nextState) => {
+          if (sessionGeneration !== generation) throw new Error("session changed during automatic recovery");
+          pi.appendEntry(MODEL_STATE_TYPE, nextState);
+        },
+      }, failure.key);
+      if (sessionGeneration !== generation) {
+        ctx.ui?.notify?.(
+          "PiMarg stopped an in-flight recovery because the session changed. Verify the active model before continuing.",
+          "warning",
+        );
+        return;
+      }
+      if (execution.ignoredDuplicate) return;
+      state = execution.state;
+      if (!execution.switched) {
+        if (!execution.stateChanged) return;
+        ctx.ui?.notify?.(
+          "PiMarg could not resume automatically because no configured backup model remains. Run /auto-models choose after restoring provider access.",
+          "error",
+        );
+        if (execution.persistenceError) {
+          ctx.ui?.notify?.(
+            `PiMarg updated recovery state only in memory because the session ledger could not be saved: ${execution.persistenceError}`,
+            "error",
+          );
+        }
+        return;
+      }
+
+      const title = execution.switched.level === "high" ? "High" : "Low";
+      ctx.ui?.notify?.(
+        execution.reusedCurrent
+          ? `PiMarg kept the ${title} backup ${execution.switched.selection.selector} active after ${failure.selector} reached its limit and is resuming safely.`
+          : `PiMarg switched ${failure.selector} to the ${title} backup ${execution.switched.selection.selector} and is resuming automatically.`,
+        "warning",
+      );
+      if (execution.persistenceError) {
+        ctx.ui?.notify?.(
+          `The model switched, but PiMarg could not save the recovery state to the session ledger: ${execution.persistenceError}`,
+          "error",
+        );
+      }
+      pi.sendUserMessage(
+        formatFailoverRecoveryMessage(
+          state,
+          failure.selector,
+          execution.switched.level,
+          execution.switched.selection.selector,
+          execution.reusedCurrent,
+        ),
+        { deliverAs: "aside" },
+      );
+    } finally {
+      if (recoveryToken === token) recoveryToken = undefined;
+    }
+  };
+
+  pi.on("agent_end", async (event: any, ctx: any) => {
+    if (event?.willContinue || event?.isTerminal === false) return;
+    const failed = findTerminalUsageLimitFailure(event?.messages ?? []);
+    const failure = failed
+      ? {
+          selector: failedModelSelector(failed, ctx.models?.current?.() ?? ctx.model),
+          key: modelFailureKey(failed),
+        }
+      : pendingToolFailure;
+    pendingToolFailure = undefined;
+    if (!failure) return;
+    await recoverFromUsageLimit(failure, ctx);
+  });
+
+  pi.on("tool_execution_end", (event: any) => {
+    pendingToolFailure = modelToolUsageLimitFailure(event) ?? pendingToolFailure;
+  });
+
   pi.registerCommand("pi-marg", {
     description: "Start PiMarg with interactive intake, or pass a work prompt.",
     async handler(args: string, ctx: any) {
@@ -164,7 +351,8 @@ export default function modelRouter(pi: any) {
       const boundaryLabel = await ctx.ui.select("Work boundary", [...WORK_BOUNDARIES], {
         selectionMarker: "radio",
       });
-      if (!WORK_BOUNDARIES.includes(boundaryLabel)) return;
+      const boundary = matchNumberedOption(boundaryLabel, ["Job/client", "Personal"], (item) => item);
+      if (!boundary) return;
 
       const workTypeLabel = await ctx.ui.select("Work type", [...WORK_TYPES], { selectionMarker: "radio" });
       const workType = Number.parseInt(workTypeLabel?.match(/^([1-7])\./)?.[1] ?? "", 10);
@@ -175,10 +363,11 @@ export default function modelRouter(pi: any) {
 
       const liveModels = ctx.models.list() as ModelLike[];
       if (liveModels.length === 0) {
-        ctx.ui.notify("No authenticated and enabled OMP models were found. Configure a provider, then run /pi-marg again.", "error");
+        ctx.ui.notify(emptyCatalogSetupMessage("OMP"), "error");
         return;
       }
       const catalog = buildModelCatalog(liveModels, hasExternalDevin(pi));
+      const fallbackCatalog = buildFallbackCatalog(catalog);
       const selected: Partial<Record<AutoStage, ModelCandidate>> = {};
       for (const stage of requiredStagesForWorkType(workType)) {
         const choice = await chooseModel(ctx, stage, catalog[stage], selected);
@@ -186,22 +375,30 @@ export default function modelRouter(pi: any) {
         selected[stage] = choice;
       }
 
-      const nextState = selectedState(workType, selected);
+      const high = await chooseFallbackModel(ctx, "high", fallbackCatalog.high);
+      if (!high) return;
+      const low = await chooseFallbackModel(ctx, "low", fallbackCatalog.low, high);
+      if (!low) return;
+      const fallbacks = { high, low };
+
+      const nextState = selectedState(workType, selected, fallbacks);
       state = nextState;
       pi.appendEntry(MODEL_STATE_TYPE, nextState);
-      pi.sendUserMessage(intakeMessage(request, boundaryLabel, workTypeLabel!, skillMode, selected));
+      pi.sendUserMessage(intakeMessage(request, boundary, workTypeLabel!, skillMode, selected, fallbacks));
     },
   });
 
   pi.registerTool({
     name: "auto_model_route",
     label: "PiMarg Model Router",
-    description: "Discover, select, and activate live A/B/C/D model choices while enforcing A different from C and B different from D.",
+    description: "Discover, select, and activate live A/B/C/D models plus distinct high/low automatic usage-limit backups.",
     parameters: z.object({
-      action: z.enum(["catalog", "select", "activate", "status"]),
+      action: z.enum(["catalog", "select", "select_fallback", "activate", "status"]),
       stage: z.enum(STAGES).optional(),
+      fallback: z.enum(FALLBACK_LEVELS).optional(),
       target: z.string().optional(),
       workType: z.number().optional(),
+      provider: z.string().optional(),
     }),
     async execute(_toolCallId: string, params: ModelRouteParams, _signal: unknown, _onUpdate: unknown, ctx: any) {
       const models = ctx.models.list() as ModelLike[];