@sangyaahub/pi-marg 1.0.3 → 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.3"
+    "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.3",
+      "version": "1.0.4",
       "author": {
         "name": "Sangyaa",
         "email": "contact@sangyaa.co"

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

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.
@@ -56,6 +59,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 +73,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.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.3 · 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,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(),

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

@@ -1,9 +1,17 @@
 import { Type } from "typebox";
 
 import {
+  FALLBACK_LEVELS,
   MODEL_STATE_TYPE,
   emptyModelRouteState,
+  executeAutomaticFailover,
   executeModelRoute,
+  failedModelSelector,
+  findTerminalUsageLimitFailure,
+  formatFailoverRecoveryMessage,
+  hasConfiguredFallback,
+  modelFailureKey,
+  modelToolUsageLimitFailure,
   restoreModelRouteState,
   type ModelLike,
   type ModelRouteParams,
@@ -26,22 +34,123 @@ function availableModels(ctx: any): ModelLike[] {
 
 export default function modelRouter(pi: any) {
   let state = emptyModelRouteState();
-  pi.on("session_start", (_event: unknown, ctx: any) => {
+  let recoveryToken: symbol | undefined;
+  let sessionGeneration = 0;
+  let pendingModelFailure: { selector: string; key: string } | undefined;
+  let pendingToolFailure: { selector: string; key: string } | undefined;
+  const restore = (_event: unknown, ctx: any) => {
+    sessionGeneration += 1;
+    recoveryToken = undefined;
+    pendingModelFailure = undefined;
+    pendingToolFailure = undefined;
     state = restoreModelRouteState(ctx.sessionManager.getBranch());
+  };
+
+  pi.on("session_start", 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: "Pi",
+        models: availableModels(ctx),
+        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. Re-run the model chooser 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: "followUp" },
+      );
+    } finally {
+      if (recoveryToken === token) recoveryToken = undefined;
+    }
+  };
+
+  pi.on("agent_end", (event: any, ctx: any) => {
+    const failed = findTerminalUsageLimitFailure(event?.messages ?? []);
+    pendingModelFailure = failed
+      ? { selector: failedModelSelector(failed, ctx.model), key: modelFailureKey(failed) }
+      : undefined;
+  });
+
+  pi.on("tool_execution_end", (event: any) => {
+    pendingToolFailure = modelToolUsageLimitFailure(event) ?? pendingToolFailure;
+  });
+
+  pi.on("agent_settled", async (_event: unknown, ctx: any) => {
+    const failure = pendingModelFailure ?? pendingToolFailure;
+    pendingModelFailure = undefined;
+    pendingToolFailure = undefined;
+    if (!failure) return;
+    await recoverFromUsageLimit(failure, ctx);
   });
 
   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: Type.Object({
       action: Type.Union([
         Type.Literal("catalog"),
         Type.Literal("select"),
+        Type.Literal("select_fallback"),
         Type.Literal("activate"),
         Type.Literal("status"),
       ]),
       stage: Type.Optional(Type.Union([Type.Literal("A"), Type.Literal("B"), Type.Literal("C"), Type.Literal("D")])),
+      fallback: Type.Optional(Type.Union(FALLBACK_LEVELS.map((level) => Type.Literal(level)))),
       target: Type.Optional(Type.String()),
       workType: Type.Optional(Type.Number()),
       provider: Type.Optional(Type.String()),

package/adapters/pi/prompts/auto-models.md

@@ -1,12 +1,12 @@
 ---
-description: List or change the active Auto Mode A/B/C/D model selections from Pi's live authenticated catalog.
+description: List or change A/B/C/D models and the high/low automatic recovery pair from Pi's live authenticated catalog.
 argument-hint: [status | choose]
 ---
 
 Load `auto-mode-router` and read its model-routing reference.
 
-- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors and separation checks.
-- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Present only required stages and exact available selectors. Save each answer with `action: select`.
+- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors, separation checks, high/low backups, active fallback, and last failover.
+- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Present required stages and exact available selectors. Save each stage with `action: select`, then save two distinct runtime models with `action: select_fallback`, first `fallback: high`, then `fallback: low`.
 - Do not type or persist a model ID that the live catalog did not return.
 - Treat any model returned by Pi's registry as a normal in-session route. Treat Devin or another external coding-agent session as a capability-gated external route; creating one requires `post-web` approval.
 - C/D are the authoritative independent review selectors. Any detected advisor or watcher is supplemental and must not weaken the A≠C or B≠D checks.

package/agents/auto-intake.md

@@ -7,4 +7,4 @@ blocking: true
 autoloadSkills: [auto-mode-router]
 ---
 
-Complete only the intake and availability checks from `auto-mode-router`. Ask in the required order: work context, work type, skill mode, live A/B/C/D selections, then add-ons. Call `auto_runtime_status` before recommending runtime capabilities. Return the proposed `[AUTO-MODE]` state. Do not plan, implement, or change project files.
+Complete only the intake and availability checks from `auto-mode-router`. Ask in the required order: work context, work type, skill mode, live A/B/C/D selections, high and low runtime backups, then add-ons. Call `auto_runtime_status` before recommending runtime capabilities. Return the proposed `[AUTO-MODE]` state. Do not plan, implement, or change project files.

package/commands/auto-models.md

@@ -1,12 +1,12 @@
 ---
-description: List or change the active Auto Mode A/B/C/D model selections from OMP's live authenticated catalog.
+description: List or change A/B/C/D models and the high/low automatic recovery pair from OMP's live authenticated catalog.
 argument-hint: [status | choose]
 ---
 
 Load `auto-mode-router` and read its model-routing reference.
 
-- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors and separation checks.
-- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Present only required stages and exact available selectors. Save each answer with `action: select`.
+- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors, separation checks, high/low backups, active fallback, and last failover.
+- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Present required stages and exact available selectors. Save each stage with `action: select`, then save two distinct runtime models with `action: select_fallback`, first `fallback: high`, then `fallback: low`.
 - Do not type or persist a model ID that the live catalog did not return.
 - Distinguish native `devin/swe-*` OMP models from the optional external `devin/mcp-session` route. Only creating the external session requires `post-web` approval.
 - C/D are the authoritative independent review selectors. A configured OMP advisor is supplemental and must not weaken the A≠C or B≠D checks.