Add model fallback strategy for agent execution failures

[snipcodeit]

Description

When an agent fails after retry exhaustion, implement a model fallback strategy: try re-running with a different model tier (e.g., opus -> sonnet -> haiku for analysis tasks). Integrate with gsd-tools resolve-model to get the fallback model chain. Add a fallback_attempts field to diagnostic logs. Configurable via .mgw/config.json retry.model_fallback: true/false.

Acceptance Criteria

• Add model fallback strategy for agent execution failures

Milestone Context

• Milestone: v8 — Agent Reliability & Failure Recovery
• Phase: Phase 45: Retry Policies & Fallback Strategies
• GSD Route: plan-phase

Dependencies

implement-configurable-retry-policy-engine

[snipcodeit]

MGW · work-started · 2026-03-06T07:10:49Z
Milestone: v8 | Phase 45: Retry Policies & Fallback Strategies

Work Started

Issue	#233 — Add model fallback strategy for agent execution failures
Route	plan-phase
Phase	45 — Retry Policies & Fallback Strategies
Progress	4/9 complete

[snipcodeit]

MGW · work-starting · 2026-03-06T07:13:30Z
Milestone: v8 | Phase 45: Retry Policies MILESTONE_PLACEHOLDER Fallback Strategies

Work Starting

Route	plan-phase — structured implementation with dependency on retry-policy.cjs and agent-errors.cjs taxonomy
Scope	medium — 4 files across lib, .mgw
Conflicts	none — depends on #232 lib/retry-policy.cjs (PR #241 open)

Work begins on branch issue/233-add-model-fallback-strategy-for-agent-ex.

Affected Files

• lib/model-fallback.cjs (new)
• lib/retry-policy.cjs (modify — add fallback integration)
• lib/gsd-adapter.cjs (modify — add fallback chain resolution)
• .mgw/config.json (modify — add retry.model_fallback setting)

[snipcodeit]

---

phase: 8
plan: 1
type: quick-full
wave: 1
depends_on: []
files_modified:

• lib/model-fallback.cjs
• lib/retry-policy.cjs
• lib/gsd-adapter.cjs
  autonomous: true
  requirements:
• Model fallback chain resolution via gsd-tools resolve-model
• Integration with RetryPolicyEngine from lib/retry-policy.cjs
• fallback_attempts field in diagnostic logs
• Configurable via .mgw/config.json retry.model_fallback setting
  must_haves:
  truths:
  • lib/model-fallback.cjs exports ModelFallbackEngine class
  • ModelFallbackEngine.resolveFallbackChain returns ordered model list
  • ModelFallbackEngine.executeWithFallback wraps fn with model-tier retry
  • fallback_attempts tracked in returned result metadata
  • Configuration loaded from .mgw/config.json retry.model_fallback field
  • Integration with RetryPolicyEngine._classifyError for fallback triggers
  • gsd-adapter.cjs exports resolveFallbackChain wrapper function
    artifacts:
  • lib/model-fallback.cjs
    key_links:
  • lib/retry-policy.cjs (RetryPolicyEngine, dependency from Implement configurable retry policy engine for agent failures #232)
  • lib/agent-errors.cjs (AGENT_FAILURE_TYPES, dependency from Define agent failure taxonomy with structured error codes #229)
  • lib/gsd-adapter.cjs (resolveModel, existing adapter layer)
  • lib/errors.cjs (MgwError base class)
  • lib/retry.cjs (classifyFailure, getBackoffMs)

---

Objective

Implement a model fallback strategy for GSD agent execution failures. When an agent fails
after retry exhaustion at a given model tier, automatically attempt re-execution with a
lower-tier model (e.g., opus -> sonnet -> haiku for analysis tasks). This extends the
existing RetryPolicyEngine from #232 with model-tier awareness.

Context

Architecture

The fallback engine sits BETWEEN the retry policy engine and the agent spawn call:

MGW orchestrator
  → RetryPolicyEngine.executeWithPolicy(fn, { agentType })    ← existing (#232)
    → on policy exhaustion at current model tier:
      → ModelFallbackEngine.executeWithFallback(fn, { agentType })  ← NEW (#233)
        → resolves fallback chain: [opus, sonnet, haiku]
        → tries fn(model) for each tier until success or chain exhausted

Design Decisions

1. Fallback chain is per-agent-type — different agent types have different model chains
   (e.g., gsd-planner needs opus/sonnet, gsd-executor can use sonnet/haiku)
2. Configurable via .mgw/config.json — retry.model_fallback: true/false master switch,
   plus per-agent-type chain overrides
3. Non-breaking — when model_fallback is false (default), behavior is identical to pre-Add model fallback strategy for agent execution failures #233
4. Integrates with gsd-adapter — uses resolveModel for primary model, adds
   resolveFallbackChain for the ordered fallback list

Dependencies

• lib/retry-policy.cjs (from Implement configurable retry policy engine for agent failures #232 PR feat(retry): configurable retry policy engine for agent failures #241) — RetryPolicyEngine class
• lib/agent-errors.cjs (from Define agent failure taxonomy with structured error codes #229 PR feat(lib): define agent failure taxonomy with structured error codes #238) — AGENT_FAILURE_TYPES, classifyAgentFailure
• lib/gsd-adapter.cjs — resolveModel, invokeGsdTool

Tasks

Task 1: Create lib/model-fallback.cjs

files: lib/model-fallback.cjs (new)
action: Create the ModelFallbackEngine class that:

1. DEFAULT_FALLBACK_CHAINS — frozen map of agent-type to model chain:

   gsd-planner:      [inherit, sonnet, haiku]
   gsd-executor:     [sonnet, haiku]
   gsd-verifier:     [sonnet, haiku]
   gsd-plan-checker: [sonnet, haiku]
   general-purpose:  [sonnet, haiku]
   

   Where "inherit" means "use the model running the current session" (passthrough).

2. Constructor — accepts opts for chain overrides and config path. Loads config
   from .mgw/config.json retry.model_fallback section if present. Merge priority:
   DEFAULT < config file < constructor opts.

3. resolveFallbackChain(agentType) — returns the ordered model list for an agent type.
   If model_fallback is disabled, returns only the primary model (no fallback).

4. executeWithFallback(fn, opts) — async wrapper:

   • Takes fn(modelName) as argument
   • Resolves the fallback chain for the agent type
   • For each model in chain: calls fn(model)
   • If fn succeeds: return { result, model, fallback_attempts, total_models_tried }
   • If fn throws: classify error; if non-retryable (hallucination, permission-denied),
     throw immediately without trying next model
   • If all models exhausted: throw ModelFallbackError with fallback_attempts count

5. ModelFallbackError — extends MgwError with fallback-specific fields:
   failureType, agentType, modelsAttempted, fallback_attempts

6. Static loadConfig(configPath) — loads from .mgw/config.json:

   {
     "retry": {
       "model_fallback": true,
       "fallback_chains": {
         "gsd-planner": ["inherit", "sonnet"],
         "gsd-executor": ["sonnet", "haiku"]
       }
     }
   }

verify: node -e "const m = require('./lib/model-fallback.cjs'); const e = new m.ModelFallbackEngine(); console.log(e.resolveFallbackChain('gsd-planner'));" returns array with >= 2 models
done: lib/model-fallback.cjs exists, exports ModelFallbackEngine, ModelFallbackError

Task 2: Add resolveFallbackChain to gsd-adapter.cjs

files: lib/gsd-adapter.cjs (modify)
action: Add a resolveFallbackChain(agentType) wrapper function to gsd-adapter.cjs that:

1. Creates a ModelFallbackEngine instance (or uses cached singleton)
2. Calls engine.resolveFallbackChain(agentType)
3. Returns the ordered model list
4. Export the new function

Also add getModelFallbackEngine() that returns the singleton engine for use by
callers who need the full executeWithFallback capability.

verify: node -e "const a = require('./lib/gsd-adapter.cjs'); console.log(a.resolveFallbackChain('gsd-planner'));" returns array
done: gsd-adapter.cjs exports resolveFallbackChain and getModelFallbackEngine

Task 3: Integrate fallback with RetryPolicyEngine

files: lib/retry-policy.cjs (modify)
action: Extend RetryPolicyEngine.executeWithPolicy to optionally invoke model fallback
when retries are exhausted:

1. Add optional modelFallback field to executeWithPolicy opts
2. When retries exhaust and modelFallback is enabled:
   • Instead of throwing immediately, check if ModelFallbackEngine is available
   • If available and model_fallback is enabled in config: call
     engine.executeWithFallback with the next model in the chain
   • Track fallback_attempts in the returned result
3. Add fallback_attempts to RetryPolicyError fields
4. Safe import of model-fallback.cjs (like existing safe import of agent-errors.cjs)

verify: RetryPolicyEngine constructor works with and without model-fallback.cjs present
done: lib/retry-policy.cjs references model-fallback.cjs safely, fallback_attempts field present

Verification

• lib/model-fallback.cjs exports ModelFallbackEngine and ModelFallbackError
• ModelFallbackEngine.resolveFallbackChain returns array of model names
• ModelFallbackEngine.executeWithFallback wraps async fn with model-tier retry
• fallback_attempts tracked in result and error objects
• Config loaded from .mgw/config.json retry.model_fallback when present
• Default behavior (no config) is model_fallback disabled (backward compatible)
• gsd-adapter.cjs exports resolveFallbackChain wrapper
• RetryPolicyEngine integration is safe (works without model-fallback.cjs)
• No hardcoded model names — uses gsd-tools resolve-model pattern

Success Criteria

1. New file lib/model-fallback.cjs with ModelFallbackEngine class
2. gsd-adapter.cjs extended with resolveFallbackChain and getModelFallbackEngine
3. retry-policy.cjs extended with optional model fallback integration
4. All safe imports — no breaking changes when dependency files are absent
5. Configuration schema documented in config loading code

Output

• lib/model-fallback.cjs (new)
• lib/gsd-adapter.cjs (modified)
• lib/retry-policy.cjs (modified)

[snipcodeit]

Summary: Add Model Fallback Strategy for Agent Execution Failures

One Liner

Added ModelFallbackEngine to provide per-agent-type model tier fallback when retry policy is exhausted, configurable via .mgw/config.json.

Changes

New Files

• lib/model-fallback.cjs — ModelFallbackEngine class with:
  • DEFAULT_FALLBACK_CHAINS per agent type (gsd-planner: [inherit, sonnet, haiku], etc.)
  • resolveFallbackChain(agentType) — returns ordered model list
  • executeWithFallback(fn, opts) — wraps async fn with model-tier retry
  • ModelFallbackError — error class with fallback_attempts tracking
  • loadConfig() — reads .mgw/config.json retry.model_fallback settings
  • NON_FALLBACK_FAILURE_TYPES set (hallucination, permission-denied skip fallback)

Modified Files

• lib/gsd-adapter.cjs — Added:

  • resolveFallbackChain(agentType) wrapper function
  • getModelFallbackEngine() singleton accessor
  • Safe import of model-fallback.cjs (no-op when absent)

• lib/retry-policy.cjs — Added:

  • Safe import of model-fallback.cjs
  • fallback_attempts field to RetryPolicyError
  • modelFallback option to executeWithPolicy
  • _attemptModelFallback() private method for fallback delegation
  • onFallback callback option for logging model tier transitions

Dependency Files (from other PRs, included for worktree compatibility)

• lib/agent-errors.cjs — from Define agent failure taxonomy with structured error codes #229 (defines AGENT_FAILURE_TYPES, classifyAgentFailure)
• lib/retry-policy.cjs — originally from Implement configurable retry policy engine for agent failures #232, extended here

Key Files

• lib/model-fallback.cjs
• lib/gsd-adapter.cjs
• lib/retry-policy.cjs

Technical Decisions

1. Disabled by default — model_fallback is false unless explicitly enabled in .mgw/config.json to preserve backward compatibility
2. Per-agent-type chains — different agents have different model needs; planners start with inherit (opus-level), executors start with sonnet
3. Non-fallback failure types — hallucination and permission-denied skip fallback because model change won't fix them
4. Safe imports everywhere — every dependency uses try/catch import so each module works independently

Commits

1. feat(lib): add model fallback engine for agent execution failures — lib/model-fallback.cjs
2. feat(adapter): add model fallback chain resolution to gsd-adapter — lib/gsd-adapter.cjs
3. feat(retry): integrate model fallback with retry policy engine — lib/retry-policy.cjs, lib/agent-errors.cjs

[snipcodeit]

Verification: Add Model Fallback Strategy

VERIFICATION PASSED

Must-Haves Check

Requirement	Status	Evidence
lib/model-fallback.cjs exports ModelFallbackEngine class	PASS	require('./lib/model-fallback.cjs').ModelFallbackEngine is a function
ModelFallbackEngine.resolveFallbackChain returns ordered model list	PASS	Returns ['inherit', 'sonnet', 'haiku'] for gsd-planner when enabled
ModelFallbackEngine.executeWithFallback wraps fn with model-tier retry	PASS	Integration test: fails on model 1, succeeds on model 2
fallback_attempts tracked in returned result metadata	PASS	Result includes { fallback_attempts: 1, total_models_tried: 2 }
Configuration loaded from .mgw/config.json retry.model_fallback	PASS	ModelFallbackEngine.loadConfig() reads retry.model_fallback boolean
Integration with RetryPolicyEngine._classifyError for fallback triggers	PASS	_attemptModelFallback() delegates to ModelFallbackEngine
gsd-adapter.cjs exports resolveFallbackChain wrapper function	PASS	require('./lib/gsd-adapter.cjs').resolveFallbackChain is a function

Behavioral Verification

Test	Result
Successful on first model — no fallback needed	PASS: fallback_attempts=0, model='inherit'
First model fails, succeeds on second model	PASS: fallback_attempts=1, model='sonnet'
All models fail — ModelFallbackError thrown	PASS: error has modelsAttempted, fallback_attempts
Hallucination failure — skips fallback (non-fallback type)	PASS: throws original error, not ModelFallbackError
Disabled by default — returns primary model only	PASS: resolveFallbackChain returns ['inherit'] when disabled
Safe import — works without model-fallback.cjs	PASS: retry-policy.cjs and gsd-adapter.cjs both use try/catch import
RetryPolicyError has fallback_attempts field	PASS: new RetryPolicyError('test', { fallback_attempts: 2 }).fallback_attempts === 2

Files Created/Modified

• lib/model-fallback.cjs (new, 421 lines)
• lib/gsd-adapter.cjs (modified, +68 lines)
• lib/retry-policy.cjs (modified, +83 lines)
• lib/agent-errors.cjs (dependency from Define agent failure taxonomy with structured error codes #229, included for worktree compatibility)