blitzstrike 1.0.93 → 1.0.94

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to Blitz Strike are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.94] — 2026-09-13
+
+### Added — model fallback (mature: classify → decide, not blind fallback)
+
+- New `model_fallback` MCP tool + `intelligence/model_fallback.json`: classifies
+  a model/sub-agent failure into 10 classes, each with a retryable + backoff
+  flag and a per-class action (retry with exponential backoff / fall back /
+  shrink scope / fix credentials / abort), plus a fallback chain that forbids
+  downgrading to a weaker model and an explicit backoff schedule.
+- More mature than a naive "fall back on any error": quota/auth/permission are
+  non-retryable (fix, don't retry); rate-limit/timeout/5xx are retryable with
+  backoff; context-length means shrink, not retry.
+- `retry_guidance` model_failed and the PERSISTENCE doctrine now route model
+  errors through `model_fallback`.
+
 ## [1.0.93] — 2026-09-13
 
 ### Added — catalog usage trigger

package/dist/index.js

@@ -31703,6 +31703,34 @@ function orchestration(part) {
     suggestions: ["lifecycle", "team", "handoff", "termination", ...data.lifecycle.map((p) => String(p.phase)), ...data.team.map((r) => String(r.id))]
   };
 }
+function modelFallback(signal) {
+  const data = loadJson("model_fallback");
+  if (!data)
+    return { found: false, error: "model_fallback.json not found" };
+  if (!signal) {
+    return {
+      found: true,
+      error_classes: data.error_classes.map((c) => ({ id: c.id, retryable: c.retryable, backoff: c.backoff })),
+      fallback_chain: data.fallback_chain,
+      backoff: data.backoff
+    };
+  }
+  const q = signal.toLowerCase();
+  for (const c of data.error_classes) {
+    if (c.signals.some((s) => q.includes(s.toLowerCase()))) {
+      return {
+        found: true,
+        class: c.id,
+        retryable: c.retryable,
+        backoff: c.backoff,
+        action: c.action,
+        fallback_chain: data.fallback_chain,
+        backoff_schedule: c.backoff ? data.backoff : null
+      };
+    }
+  }
+  return { found: false, signal, suggestions: data.error_classes.map((c) => c.id) };
+}
 
 // src/active.ts
 var TIMEOUT_MS2 = 20000;
@@ -53577,7 +53605,7 @@ function createServer() {
     name: "blitzstrike",
     version: "1.0.0"
   }, {
-    instructions: "Blitz Strike is a universal penetration-testing toolbelt with three tiers — " + "BLITZ (reconnaissance / attack-surface mapping), EAGLE-EYE (source-to-sink " + "analysis), STRIKE (live validation) — plus a canonical evidence-first finding " + "engine and a multi-language taint engine.\\n\\n" + "CORE MENTAL MODEL:\\n" + "- A scanner hit is a HYPOTHESIS, not a finding. Live verification (or data-flow " + "  proof) is the verdict. Never report an unverified hit as a vulnerability.\\n" + "- Distinguish REACHABLE from mere PRESENT: a sink is only a finding when tainted " + "  input reaches it AND it is not neutralized by a sanitizer and not guarded by an " + "  auth gate.\\n\\n" + "HOW TO RUN AN AUDIT (start here):\\n" + "0. ROUTE BY TARGET. Classify the target automatically - no need to ask. A " + "   URL - with or without http/https (example.com, 192.168.1.1, host:8080) - " + "   is LIVE (scope-gated, then live_recon + active_scan + strike_verify). A " + "   filesystem path (exists on disk, or a code extension) is SOURCE audit " + "   (blitz_scan + eagle_eye2 + complex_scan/route_scan). If the scheme is " + "   missing, prepend https://. run_engagement auto-detects both internally.\\n" + "1. SCOPE FIRST. Call scope_check(target, scope, mode) before ANY active testing. " + "   Passive analysis (reading source, fingerprinting public pages) needs no gate; " + "   active probing (exploitation, fuzzing, path brute-force) is blocked until scope " + "   authorizes it.\\n" + "2. MAP THE SURFACE (BLITZ). For a source tree use blitz_scan (tree) or blitz_file " + "   (single file) then enrich_scan to match sinks to escalation chains. For a live " + "   URL use live_recon for a full pass (fingerprint/WAF/tech/version/crawler/params/" + "   subdomains/API endpoints/intel correlation) — it returns next_steps. active_scan " + "   is the lighter gated alternative. Both re-check scope internally.\\n" + "3. TRACE REACHABILITY (EAGLE-EYE). For every sink, determine whether attacker " + "   input actually reaches it:\\n" + "   - PHP/JS/TS/Python/Java source: taint_file (auto-detects language) or " + "     taint_scan/taint_tree (PHP AST). list_languages shows what's supported.\\n" + "   - Any language: trace_data_flow (window heuristic) and eagle_eye/eagle_grep " + "     (function-scoped view of sinks + auth gates). Beyond taint: route_scan (route confusion / dispatch abuse / batch forwarding) and complex_scan (deserialization->POP, type juggling, mass assignment) catch classes plain taint misses.\\n" + "   A sink counts only if tainted input reaches it unsanitized and unguarded.\\n" + "4. VALIDATE (STRIKE). Confirm live with strike_verify using a MARKER plus a " + "   NEGATIVE CONTROL plus a BASELINE. The verdict is deterministic: marker " + "   reflected AND control inert = confirmed; both reflected = false_positive; " + "   marker not reflected = unconfirmed. Feed the verdict to strike_resolve to " + "   advance the finding lifecycle (hypothesis->validating->confirmed). Use " + "   read_tool_manual for the exploit tool's manual, payload_lookup for payloads, " + "   detect_waf/tech_correlation for context.\\n" + "5. RECORD + REPORT. Create a canonical finding with finding_create, advance it " + "   through the lifecycle with finding_transition, attach confidence_score, and " + "   redact any secrets before persisting. Only report findings that survived " + "   verification.\\n\\n" + "SUPPORTING LAYERS:\\n" + "- run_engagement: ONE call does the whole audit (no babysitting). Source path -> " + "  full static pipeline + inline report (markdown/JSON/SARIF). URL target -> " + "  autonomous live marker sweep + confirmed findings + report. Prefer this first.\\n" + "- list_chains: 57 escalation chains (source -> sink -> impact).\\n" + "- list_languages / taint_file: multi-language taint (PHP, JS/TS, Python, Java).\\n" + "- tool_lookup / ensure_tool / list_tools: 130-tool catalog, auto-install.\\n" + "- read_playbook / list_playbooks: 17 engagement playbooks (web-app, api-security, " + "  source-code-audit, active-directory, mobile, external-attack-surface, ...).\\n" + "- skill_lookup / read_skill / list_skills: 38 skills (6 bs-* agent doctrine + " + "  technique playbooks: WP/PHP 0-day, AD, malware, mobile, cloud).\\n" + "- read_tool_manual / list_manuals: 317 tool manuals (sqlmap, nmap, commix, ...).\\n" + "- payload_lookup / read_payload: 66 payload collections (sqli, xss, ssti, xxe, lfi).\\n" + "- detect_waf / tech_correlation / cve_correlation / port_correlation: signature " + "  + correlation intelligence.\\n" + "- nvd_lookup / fofa_search: CVE lookup + asset reconnaissance (FOFA needs env creds).\\n" + "- remember / memory_lookup / memory_list: persist + recall verified knowledge.\\n\\n" + "RESOURCE MAP (know what to reach for):\\n" + "- ORCHESTRATION = the engagement framework. orchestration() returns the " + "  lifecycle (scope->recon->analyze->deep->verify->report, each with " + "  entry/exit criteria) + sub-agent team + handoff contract + termination " + "  criteria. Load it at engagement start.\\n" + "- TOOL = acts (scan, taint, verify, record, correlate). Call it to DO something.\\n" + "- PLAYBOOK = campaign plan for a target TYPE. read_playbook(web-application) " + "  BEFORE a full engagement of that type.\\n" + "- SKILL = procedure doctrine. Load the bs-* skill for the phase you are on " + "  (orchestrate, scope, source-audit, verify, review, report); load a technique " + "  skill for the specific technique (WP 0-day, AD, malware).\\n" + "- MANUAL = deep reference for ONE tool. read_tool_manual right before using it.\\n" + "- CATALOG = external tools (130: sqlmap, nmap, nuclei, ffuf, ysoserial, ...). " + "  Blitz Strike's OWN tools find + verify; the catalog is for deeper EXTERNAL " + "  exploitation/enumeration. After your own analysis confirms a finding, run " + "  tool_lookup -> ensure_tool (auto-install) -> read_tool_manual to drive the " + "  external tool that demonstrates impact.\\n" + "- PAYLOAD = attack payloads for a class. payload_lookup before crafting a probe.\\n" + "- INTELLIGENCE = knowledge. list_attack_vectors (34 categories) maps the " + "  full surface during RECON; list_chains (57) turns a finding into impact; " + "  chain_links composes chains for complex bugs; bypass_lookup when blocked; " + "  payload_lookup when crafting a probe. Reach for them at that moment.\\n\\n" + "NO-BABYSITTING (while scanning + testing):\\n" + "- Scan the WHOLE surface before reporting - every file, entry point, and sink. " + "  Do not stop after the first hit to ask; keep enumerating the full tree.\\n" + "- Test every hypothesis through its full verification cycle - vary probes on " + "  failure, apply bypasses when blocked, keep going. Do not pause to ask.\\n" + "- Persist through partial results: a scan that surfaces few sinks is NOT done - " + "  widen the surface, escalate detectors, dig into each reachable sink.\\n" + "- Only surface to the user when: scope/authorization is genuinely unclear, a " + "  destructive or DoS action needs explicit consent, or the engagement is complete.\\n\\n" + "PERSISTENCE (complex bugs - do not give up):\\n" + "- On any failure (empty output, blocked probe, failed sub-agent/model), call " + "  retry_guidance(signal) for concrete recovery actions before giving up.\\n" + "- One failed probe != not vulnerable. Vary: alternative sinks, other params, " + "  encoding/case/whitespace bypasses, different injection context.\\n" + "- Empty output != no findings. Re-run (server may be stale after an upgrade - " + "  /reload-mcp), or escalate to route_scan / complex_scan for classes taint " + "  misses (POP chains, type juggling, mass assignment, route confusion).\\n" + "- A 'sanitized' sink may not be safe. Challenge the sanitizer: loose == vs ===, " + "  missing EXTR_SKIP, int cast truncation, weak regex.\\n" + "- An unconfirmed hypothesis is KEPT as hypothesis - try alternate verification, " + "  then let adversarial review decide.\\n" + "- Complex chains (deserialization->POP, LFI->RCE) need the FULL chain traced, " + `  not just the first sink.\\n
+    instructions: "Blitz Strike is a universal penetration-testing toolbelt with three tiers — " + "BLITZ (reconnaissance / attack-surface mapping), EAGLE-EYE (source-to-sink " + "analysis), STRIKE (live validation) — plus a canonical evidence-first finding " + "engine and a multi-language taint engine.\\n\\n" + "CORE MENTAL MODEL:\\n" + "- A scanner hit is a HYPOTHESIS, not a finding. Live verification (or data-flow " + "  proof) is the verdict. Never report an unverified hit as a vulnerability.\\n" + "- Distinguish REACHABLE from mere PRESENT: a sink is only a finding when tainted " + "  input reaches it AND it is not neutralized by a sanitizer and not guarded by an " + "  auth gate.\\n\\n" + "HOW TO RUN AN AUDIT (start here):\\n" + "0. ROUTE BY TARGET. Classify the target automatically - no need to ask. A " + "   URL - with or without http/https (example.com, 192.168.1.1, host:8080) - " + "   is LIVE (scope-gated, then live_recon + active_scan + strike_verify). A " + "   filesystem path (exists on disk, or a code extension) is SOURCE audit " + "   (blitz_scan + eagle_eye2 + complex_scan/route_scan). If the scheme is " + "   missing, prepend https://. run_engagement auto-detects both internally.\\n" + "1. SCOPE FIRST. Call scope_check(target, scope, mode) before ANY active testing. " + "   Passive analysis (reading source, fingerprinting public pages) needs no gate; " + "   active probing (exploitation, fuzzing, path brute-force) is blocked until scope " + "   authorizes it.\\n" + "2. MAP THE SURFACE (BLITZ). For a source tree use blitz_scan (tree) or blitz_file " + "   (single file) then enrich_scan to match sinks to escalation chains. For a live " + "   URL use live_recon for a full pass (fingerprint/WAF/tech/version/crawler/params/" + "   subdomains/API endpoints/intel correlation) — it returns next_steps. active_scan " + "   is the lighter gated alternative. Both re-check scope internally.\\n" + "3. TRACE REACHABILITY (EAGLE-EYE). For every sink, determine whether attacker " + "   input actually reaches it:\\n" + "   - PHP/JS/TS/Python/Java source: taint_file (auto-detects language) or " + "     taint_scan/taint_tree (PHP AST). list_languages shows what's supported.\\n" + "   - Any language: trace_data_flow (window heuristic) and eagle_eye/eagle_grep " + "     (function-scoped view of sinks + auth gates). Beyond taint: route_scan (route confusion / dispatch abuse / batch forwarding) and complex_scan (deserialization->POP, type juggling, mass assignment) catch classes plain taint misses.\\n" + "   A sink counts only if tainted input reaches it unsanitized and unguarded.\\n" + "4. VALIDATE (STRIKE). Confirm live with strike_verify using a MARKER plus a " + "   NEGATIVE CONTROL plus a BASELINE. The verdict is deterministic: marker " + "   reflected AND control inert = confirmed; both reflected = false_positive; " + "   marker not reflected = unconfirmed. Feed the verdict to strike_resolve to " + "   advance the finding lifecycle (hypothesis->validating->confirmed). Use " + "   read_tool_manual for the exploit tool's manual, payload_lookup for payloads, " + "   detect_waf/tech_correlation for context.\\n" + "5. RECORD + REPORT. Create a canonical finding with finding_create, advance it " + "   through the lifecycle with finding_transition, attach confidence_score, and " + "   redact any secrets before persisting. Only report findings that survived " + "   verification.\\n\\n" + "SUPPORTING LAYERS:\\n" + "- run_engagement: ONE call does the whole audit (no babysitting). Source path -> " + "  full static pipeline + inline report (markdown/JSON/SARIF). URL target -> " + "  autonomous live marker sweep + confirmed findings + report. Prefer this first.\\n" + "- list_chains: 57 escalation chains (source -> sink -> impact).\\n" + "- list_languages / taint_file: multi-language taint (PHP, JS/TS, Python, Java).\\n" + "- tool_lookup / ensure_tool / list_tools: 130-tool catalog, auto-install.\\n" + "- read_playbook / list_playbooks: 17 engagement playbooks (web-app, api-security, " + "  source-code-audit, active-directory, mobile, external-attack-surface, ...).\\n" + "- skill_lookup / read_skill / list_skills: 38 skills (6 bs-* agent doctrine + " + "  technique playbooks: WP/PHP 0-day, AD, malware, mobile, cloud).\\n" + "- read_tool_manual / list_manuals: 317 tool manuals (sqlmap, nmap, commix, ...).\\n" + "- payload_lookup / read_payload: 66 payload collections (sqli, xss, ssti, xxe, lfi).\\n" + "- detect_waf / tech_correlation / cve_correlation / port_correlation: signature " + "  + correlation intelligence.\\n" + "- nvd_lookup / fofa_search: CVE lookup + asset reconnaissance (FOFA needs env creds).\\n" + "- remember / memory_lookup / memory_list: persist + recall verified knowledge.\\n\\n" + "RESOURCE MAP (know what to reach for):\\n" + "- ORCHESTRATION = the engagement framework. orchestration() returns the " + "  lifecycle (scope->recon->analyze->deep->verify->report, each with " + "  entry/exit criteria) + sub-agent team + handoff contract + termination " + "  criteria. Load it at engagement start.\\n" + "- TOOL = acts (scan, taint, verify, record, correlate). Call it to DO something.\\n" + "- PLAYBOOK = campaign plan for a target TYPE. read_playbook(web-application) " + "  BEFORE a full engagement of that type.\\n" + "- SKILL = procedure doctrine. Load the bs-* skill for the phase you are on " + "  (orchestrate, scope, source-audit, verify, review, report); load a technique " + "  skill for the specific technique (WP 0-day, AD, malware).\\n" + "- MANUAL = deep reference for ONE tool. read_tool_manual right before using it.\\n" + "- CATALOG = external tools (130: sqlmap, nmap, nuclei, ffuf, ysoserial, ...). " + "  Blitz Strike's OWN tools find + verify; the catalog is for deeper EXTERNAL " + "  exploitation/enumeration. After your own analysis confirms a finding, run " + "  tool_lookup -> ensure_tool (auto-install) -> read_tool_manual to drive the " + "  external tool that demonstrates impact.\\n" + "- PAYLOAD = attack payloads for a class. payload_lookup before crafting a probe.\\n" + "- INTELLIGENCE = knowledge. list_attack_vectors (34 categories) maps the " + "  full surface during RECON; list_chains (57) turns a finding into impact; " + "  chain_links composes chains for complex bugs; bypass_lookup when blocked; " + "  payload_lookup when crafting a probe. Reach for them at that moment.\\n\\n" + "NO-BABYSITTING (while scanning + testing):\\n" + "- Scan the WHOLE surface before reporting - every file, entry point, and sink. " + "  Do not stop after the first hit to ask; keep enumerating the full tree.\\n" + "- Test every hypothesis through its full verification cycle - vary probes on " + "  failure, apply bypasses when blocked, keep going. Do not pause to ask.\\n" + "- Persist through partial results: a scan that surfaces few sinks is NOT done - " + "  widen the surface, escalate detectors, dig into each reachable sink.\\n" + "- Only surface to the user when: scope/authorization is genuinely unclear, a " + "  destructive or DoS action needs explicit consent, or the engagement is complete.\\n\\n" + "PERSISTENCE (complex bugs - do not give up):\\n" + "- On any failure (empty output, blocked probe, failed sub-agent/model), call " + "  retry_guidance(signal) for concrete recovery actions before giving up.\\n" + "- On a model/sub-agent error (rate-limit, quota, timeout, 5xx, auth, " + "  unavailable), model_fallback(signal) classifies it and returns the exact " + "  recovery (retry+backoff / fall back / shrink scope / fix credentials / " + "  abort). Do not fall back blindly - the class decides.\\n" + "- One failed probe != not vulnerable. Vary: alternative sinks, other params, " + "  encoding/case/whitespace bypasses, different injection context.\\n" + "- Empty output != no findings. Re-run (server may be stale after an upgrade - " + "  /reload-mcp), or escalate to route_scan / complex_scan for classes taint " + "  misses (POP chains, type juggling, mass assignment, route confusion).\\n" + "- A 'sanitized' sink may not be safe. Challenge the sanitizer: loose == vs ===, " + "  missing EXTR_SKIP, int cast truncation, weak regex.\\n" + "- An unconfirmed hypothesis is KEPT as hypothesis - try alternate verification, " + "  then let adversarial review decide.\\n" + "- Complex chains (deserialization->POP, LFI->RCE) need the FULL chain traced, " + `  not just the first sink.\\n
 ` + "- When a probe is BLOCKED by a WAF/filter/sanitizer, call bypass_lookup(defense) " + "  for concrete techniques (encoding, case, comment insertion, chunked, null byte, " + "  double-encoding, verb tampering, header spoofing) and apply them - do not give up.\\n" + "- CHAIN findings: a low-severity finding may escalate — do not assume it is the " + "  end of the story. list_chains / chain_links show whether it composes into a " + "  multi-stage chain (e.g. SSRF->metadata, SQLi->RCE, LFI->RCE, upload->shell). " + "  Check before concluding, and do not overclaim an escalation that is not there.\\n\\n" + "- Complex bugs chain ACROSS chains: after confirming one chain, chain_links " + "  shows what follows (SSRF->metadata then default-creds->pivot via stolen IAM). " + "  Trace the full composition, not just a single chain.\\n\\n" + "HYPOTHESIS EXPANSION (from each finding, enumerate + verify every follow-up):\\n" + "- A confirmed finding is the START, not the end. From each one, enumerate " + "  the follow-ups: ESCALATE (list_chains + chain_links), CHAIN (chain_links " + "  from->to), BYPASS (bypass_lookup), PIVOT (new endpoints/sinks now reachable).\\n" + "- Every follow-up (this might happen, this could chain, maybe bypassable) is " + "  a HYPOTHESIS, not a finding. Verify EACH via strike_verify (marker + negative " + "  control) before it enters the report.\\n" + "- Never report speculation: might / could / possibly live in the " + "  hypothesis list, never in the report. Every report line is a verified fact.\\n\\n" + "PROFESSIONAL JUDGMENT (act like a senior tester, not a checklist runner):\\n" + "- PRIORITIZE by severity, computed deterministically with cvss_score (impact x " + "  exploitability) and weighted by escalation potential (chain_links). Do NOT rank " + "  by bug class - a critical stored XSS that yields account takeover outranks an " + "  unreachable blind RCE. Weight by the engagement context (which asset/data is " + "  most sensitive for THIS target).\\n" + "- Recognize dead ends: if a branch yields nothing after a few varied probes, " + "  note it and move on. Do not tunnel-vision one sink at the expense of the rest.\\n" + "- Live-test with care: respect rate limits, do not lock accounts, do not " + "  trigger DoS. Test non-destructively and prove impact with the smallest payload.\\n" + "- Know when done: stop when the termination criteria are met, not when you feel " + "  tired. A thorough audit over a rushed one, every time.\\n\\n" + "IRON RULES:\\n" + "- Scope first; authorized targets only. Refuse out-of-scope or destructive/DoS work.\\n" + "- A hit is a hypothesis; a verified exploit (or proven data-flow) is the finding.\\n" + "- Prefer the one-call run_engagement path; fall back to granular tools when you " + "  need finer control."
   });
   server.registerTool("blitz_scan", {
@@ -54099,6 +54127,15 @@ ${statusLine}` : statusLine },
   }, async ({ part }) => {
     return { content: [{ type: "text", text: JSON.stringify(orchestration(part)) }] };
   });
+  server.registerTool("model_fallback", {
+    title: "Model/sub-agent failure recovery",
+    description: "ORCHESTRATION: classify a model or sub-agent failure and decide the recovery. Pass the error text (rate limit / 429 / quota / context length / timeout / 500 / auth / connection / unavailable / aborted) and get the error class, whether it is retryable, whether to back off, the per-class action (retry+backoff vs fall back vs shrink scope vs fix credentials vs abort), the fallback chain, and the backoff schedule.",
+    inputSchema: {
+      signal: string2().optional().describe("The error text or signal. Omit to list all error classes + the fallback chain.")
+    }
+  }, async ({ signal }) => {
+    return { content: [{ type: "text", text: JSON.stringify(modelFallback(signal)) }] };
+  });
   server.registerTool("engagement_start", {
     title: "Start an engagement",
     description: "ORCHESTRATION: open an engagement and track its state. Call at the start of a full audit so subsequent engagement_phase / engagement_track / engagement_status calls have a state to update. The LLM is the brain; this is the deterministic bookkeeping hand.",

package/intelligence/model_fallback.json

@@ -0,0 +1,86 @@
+{
+  "_comment": "Model failure classification + recovery. More mature than a naive 'fall back on any error': each error class decides whether to retry (with exponential backoff), fall back, shrink scope, fix credentials, or abort — and the fallback chain forbids downgrading to a model that cannot do the task.",
+  "error_classes": [
+    {
+      "id": "rate_limit",
+      "signals": ["rate limit", "429", "too many requests", "rate limited"],
+      "retryable": true,
+      "backoff": true,
+      "action": "exponential backoff (wait base * factor^n before the n-th retry) on the SAME model; if it persists past max_retries, fall back to the next model"
+    },
+    {
+      "id": "quota_exceeded",
+      "signals": ["quota", "insufficient credits", "billing", "exceeded your current quota", "free usage limit"],
+      "retryable": false,
+      "backoff": false,
+      "action": "switch provider or model — never retry the same model, it will not succeed"
+    },
+    {
+      "id": "context_length",
+      "signals": ["context length", "too many tokens", "maximum context", "token limit", "context window"],
+      "retryable": false,
+      "backoff": false,
+      "action": "shrink the scope (one file, one sink class) or fall back to a longer-context model — retrying the same prompt will fail again"
+    },
+    {
+      "id": "timeout",
+      "signals": ["timeout", "timed out", "took too long"],
+      "retryable": true,
+      "backoff": true,
+      "action": "retry once with a smaller scope; if it persists, fall back to the next model"
+    },
+    {
+      "id": "model_unavailable",
+      "signals": ["model not found", "unavailable", "overloaded", "not available", "model down"],
+      "retryable": true,
+      "backoff": true,
+      "action": "retry with backoff, then fall back to the next model in the chain"
+    },
+    {
+      "id": "auth_error",
+      "signals": ["401", "unauthorized", "invalid api key", "authentication", "invalid key"],
+      "retryable": false,
+      "backoff": false,
+      "action": "fix the credentials — neither retry nor fall back will help"
+    },
+    {
+      "id": "connection_error",
+      "signals": ["connection", "network", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "socket"],
+      "retryable": true,
+      "backoff": true,
+      "action": "retry with backoff; if persistent, fall back to the next model"
+    },
+    {
+      "id": "server_error",
+      "signals": ["500", "502", "503", "504", "internal server error", "server error", "bad gateway"],
+      "retryable": true,
+      "backoff": true,
+      "action": "retry with backoff; if persistent, fall back to the next model"
+    },
+    {
+      "id": "permission_denied",
+      "signals": ["permission", "forbidden", "403", "not allowed"],
+      "retryable": false,
+      "backoff": false,
+      "action": "fix the permission or scope — neither retry nor fall back will help"
+    },
+    {
+      "id": "message_aborted",
+      "signals": ["aborted", "cancelled", "interrupted", "abort"],
+      "retryable": true,
+      "backoff": false,
+      "action": "retry immediately — the abort is likely a transient signal, not a model failure"
+    }
+  ],
+  "fallback_chain": [
+    "prefer the same provider's fallback model first (e.g. deepseek-v4-pro -> deepseek-v4-flash)",
+    "then a different provider with the same capability",
+    "never fall back to a model that cannot do the task (do not send deep reasoning to a small model)"
+  ],
+  "backoff": {
+    "base_seconds": 2,
+    "factor": 2,
+    "max_retries": 3,
+    "note": "wait base * factor^n seconds before the n-th retry; give up (or fall back) after max_retries"
+  }
+}

package/intelligence/retry_guidance.json

@@ -41,9 +41,9 @@
       "id": "model_failed",
       "signal": "a sub-agent/model returns a rate-limit, quota, context-length, or model-unavailable error",
       "actions": [
-        "fall back to a different model",
-        "shrink the sub-agent's scope (one file, one sink class)",
-        "run the step yourself with granular tools"
+        "model_fallback(signal) to classify the error and get the exact recovery — retryable? backoff? fall back / shrink scope / fix credentials / abort",
+        "do not fall back blindly: the class decides retry vs fallback vs shrink",
+        "run the step yourself with granular tools if the model cannot recover"
       ]
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blitzstrike",
-  "version": "1.0.93",
+  "version": "1.0.94",
   "description": "Blitz Strike — a universal MCP security-audit toolbelt. BLITZ sweeps the attack surface, EAGLE-EYE traces source-to-sink, STRIKE verifies live. 57 attack chains, 130-tool catalog, intelligence data layer. One server, every agent.",
   "type": "module",
   "bin": {