@sangyaahub/pi-marg 1.0.3 → 1.0.5

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.3"
+    "version": "1.0.5"
   },
   "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.3",
+      "version": "1.0.5",
       "author": {
         "name": "Sangyaa",
         "email": "contact@sangyaa.co"

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.5 — 2026-09-26
+
+- Documented how to register CheaperInference in Oh My Pi so Kimi and GLM models can be chosen at every A/B/C/D stage.
+- Recorded the distinct-model rule and a high/low backup example for that provider.
+
+## 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.

package/MODEL-SETUP.md

@@ -11,6 +11,9 @@ 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.
@@ -46,6 +49,27 @@ omp models
 
 The OMP adapter reads `ctx.models.list()`, which supplies authenticated and enabled models, and activates an exact catalog entry with `pi.setModel()`.
 
+## CheaperInference example
+
+This is one custom Oh My Pi provider, not a pinned PiMarg default. After it is authenticated, every model below is selectable at A, B, C, and D. A and C must still be different underlying models, and B and D must still be different underlying models.
+
+Create a CheaperInference key (`ci_live_...`) and save it as `CHEAPER_INFERENCE_API_KEY` in `~/.omp/agent/.env`. Point `providers.cheaperinference.apiKey` at that variable name. The base URL is `https://api.cheaperinference.com/v1`. Confirm ids with `GET /v1/models` before use, because the catalog can change.
+
+Register `kimi-k3`, `glm-5.3`, `glm-5.3-flash`, and `glm-5.2` under that provider, then verify with `omp models find cheaperinference`. The copy-paste provider block is in the README section [CheaperInference (Kimi and GLM)](README.md#cheaperinference-kimi-and-glm).
+
+One assignment that satisfies the distinct-model rule:
+
+| Stage | Selector |
+|---|---|
+| A | `cheaperinference/kimi-k3` |
+| C | `cheaperinference/glm-5.3` |
+| B | `cheaperinference/glm-5.3` |
+| D | `cheaperinference/kimi-k3` |
+| high backup | `cheaperinference/kimi-k3` |
+| low backup | `cheaperinference/glm-5.3-flash` |
+
+Any of those four models can be chosen for any stage. Calls spend CheaperInference wallet balance.
+
 ## Selection workflow
 
 1. Run `/pi-marg` for the full native intake, or `/auto-models choose` to change saved models.
@@ -56,6 +80,8 @@ The OMP adapter reads `ctx.models.list()`, which supplies authenticated and enab
 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`)
 
@@ -68,6 +94,10 @@ auto_model_route action=catalog workType=<n> provider=<provider-name>
 
 # 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.

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.3" src="https://img.shields.io/badge/version-1.0.3-0451F7"></a>
+  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.5" src="https://img.shields.io/badge/version-1.0.5-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.3 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
+**Version 1.0.5 · 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
 
@@ -124,6 +124,92 @@ Authenticate providers using the active runtime's normal login flow, then run:
 
 The router shows every model in the live authenticated and enabled registry. Stage-appropriate choices appear first and all other enabled choices remain selectable. It does not promise that a subscription route is free or unlimited. See [MODEL-SETUP.md](MODEL-SETUP.md).
 
+### CheaperInference (Kimi and GLM)
+
+Oh My Pi does not ship [CheaperInference](https://cheaperinference.com). Register it once, then `/auto-models choose` and `/pi-marg` offer its models at every stage. A and C must be different models. B and D must be different models.
+
+1. Create a dashboard key. Current keys begin with `ci_live_`.
+2. Store it in `~/.omp/agent/.env`, which Oh My Pi loads on startup:
+
+```bash
+CHEAPER_INFERENCE_API_KEY=ci_live_your_key
+```
+
+3. Add the provider to `~/.omp/agent/models.yml`. `apiKey` is the environment-variable name, not the secret. Confirm the live ids before relying on this list:
+
+```bash
+curl https://api.cheaperinference.com/v1/models \
+  -H "Authorization: Bearer $CHEAPER_INFERENCE_API_KEY"
+```
+
+```yaml
+providers:
+  cheaperinference:
+    baseUrl: https://api.cheaperinference.com/v1
+    api: openai-completions
+    apiKey: CHEAPER_INFERENCE_API_KEY
+    authHeader: true
+    compat:
+      supportsStore: false
+      supportsDeveloperRole: false
+      supportsReasoningEffort: true
+      supportsStrictMode: false
+      toolStrictMode: none
+      thinkingFormat: openai
+      reasoningContentField: reasoning_content
+      requiresReasoningContentForToolCalls: true
+      maxTokensField: max_tokens
+      reasoningEffortMap:
+        xhigh: max
+        max: max
+    models:
+      - id: kimi-k3
+        name: Kimi K3
+        reasoning: true
+        input: [text, image]
+        contextWindow: 1000000
+        maxTokens: 131072
+        tokenizer: kimi-k2
+      - id: glm-5.3
+        name: GLM 5.3
+        reasoning: true
+        input: [text]
+        contextWindow: 1000000
+        maxTokens: 131072
+        tokenizer: glm5
+      - id: glm-5.3-flash
+        name: GLM 5.3 Flash
+        reasoning: true
+        input: [text, image]
+        contextWindow: 1048576
+        maxTokens: 131072
+        tokenizer: glm5
+      - id: glm-5.2
+        name: GLM 5.2
+        reasoning: true
+        input: [text]
+        contextWindow: 1048576
+        maxTokens: 131072
+        tokenizer: glm5
+```
+
+4. Check that Oh My Pi can see them, then pick any of them at each stage:
+
+```bash
+omp models find cheaperinference
+```
+
+| Stage | One valid pick |
+|---|---|
+| A discover | `cheaperinference/kimi-k3` |
+| C plan review | `cheaperinference/glm-5.3` |
+| B build | `cheaperinference/glm-5.3` |
+| D code review | `cheaperinference/kimi-k3` |
+| high backup | `cheaperinference/kimi-k3` |
+| low backup | `cheaperinference/glm-5.3-flash` |
+
+Swap any row. The picker rejects the run only when A equals C, or B equals D. Recovery stays off until both backups are saved. This route bills a wallet on each call. The same steps are in [MODEL-SETUP.md](MODEL-SETUP.md).
+
 ## Start a workflow
 
 From a terminal in the repository you want to work on, run either:
@@ -141,11 +227,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,17 +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,
@@ -45,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));
@@ -83,30 +98,79 @@ async function chooseModel(
     return undefined;
   }
 
-  const providers = uniqueProviders(eligible);
+  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(eligible, name).length})`),
-    description: `All authenticated ${name} models for ${STAGE_PURPOSE[stage]}`,
+    label: numberedOptionLabel(index, `${name} (${candidatesForProvider(candidates, name).length})`),
+    description: copy.providerDescription(name),
   }));
-  const providerAnswer = await ctx.ui.select(`Stage ${stage} provider`, providerOptions, {
+  const providerAnswer = await ctx.ui.select(copy.providerTitle, providerOptions, {
     selectionMarker: "radio",
-    helpText: `${providers.length} providers · ${eligible.length} models · ${STAGE_PURPOSE[stage]}`,
+    helpText: `${providers.length} providers · ${candidates.length} models · ${copy.purpose}`,
   });
   const provider = matchNumberedOption(
     providerAnswer,
     providers,
-    (name) => `${name} (${candidatesForProvider(eligible, name).length})`,
+    (name) => `${name} (${candidatesForProvider(candidates, name).length})`,
   );
   if (!provider) return undefined;
 
-  const providerModels = candidatesForProvider(eligible, provider);
+  const providerModels = candidatesForProvider(candidates, provider);
   const modelOptions = providerModels.map((candidate, index) => ({
     label: numberedOptionLabel(index, optionLabel(candidate)),
-    description: optionDescription(stage, candidate),
+    description: copy.modelDescription(candidate),
   }));
-  const answer = await ctx.ui.select(`Stage ${stage} model`, modelOptions, {
+  const answer = await ctx.ui.select(copy.modelTitle, modelOptions, {
     selectionMarker: "radio",
-    helpText: `${providerModels.length} ${provider} choices · ${STAGE_PURPOSE[stage]}`,
+    helpText: `${providerModels.length} ${provider} choices · ${copy.purpose}`,
   });
   return matchNumberedOption(answer, providerModels, optionLabel);
 }
@@ -114,14 +178,18 @@ async function chooseModel(
 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"],
   };
 }
 
@@ -131,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])
@@ -145,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());
   };
 
@@ -162,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) {
@@ -203,6 +367,7 @@ export default function modelRouter(pi: any) {
         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);
@@ -210,20 +375,27 @@ 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, boundary, 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(),