chati-dev 4.0.11 → 4.1.0

package/src/security/bash-security.js

@@ -0,0 +1,335 @@
+/**
+ * Bash Security — 23-check shell injection defense system.
+ *
+ * Inspired by Claude Code's bashSecurity.ts which runs every bash command
+ * through 23 numbered security checks protecting against shell injection,
+ * unicode attacks, IFS manipulation, and prompt injection via bash.
+ *
+ * This is critical for chati.dev because autonomous agents (run-agent.js)
+ * spawn bash processes. A malicious codebase being analyzed could exploit
+ * shell injection vectors to escape the sandbox.
+ *
+ * Each check has:
+ *   - id: Unique check identifier (matches Claude Code's naming)
+ *   - name: Human-readable description
+ *   - pattern: RegExp to detect the threat
+ *   - severity: critical | high | medium
+ *   - description: What the attack does
+ */
+
+/**
+ * @typedef {Object} SecurityCheck
+ * @property {string} id - Check identifier
+ * @property {string} name - Human-readable name
+ * @property {RegExp} pattern - Detection pattern
+ * @property {string} severity - critical | high | medium
+ * @property {string} description - What this check catches
+ */
+
+/** @type {SecurityCheck[]} */
+export const SECURITY_CHECKS = [
+  // --- Category: Command Structure Attacks ---
+  {
+    id: 'INCOMPLETE_COMMANDS',
+    name: 'Incomplete command with dangling operators',
+    pattern: /[|&;]\s*$/,
+    severity: 'high',
+    description: 'Command ends with pipe/semicolon/ampersand, expecting injected continuation',
+  },
+  {
+    id: 'JQ_SYSTEM_FUNCTION',
+    name: 'jq system() function call',
+    pattern: /jq\b.*\bsystem\s*\(/i,
+    severity: 'critical',
+    description: 'jq system() executes arbitrary shell commands',
+  },
+  {
+    id: 'JQ_FILE_ARGUMENTS',
+    name: 'jq with file argument injection',
+    pattern: /jq\b.*--from-file|jq\b.*-f\s+[^|&;]+/i,
+    severity: 'high',
+    description: 'jq --from-file can read arbitrary files',
+  },
+
+  // --- Category: Flag/Argument Obfuscation ---
+  {
+    id: 'OBFUSCATED_FLAGS',
+    name: 'Obfuscated command flags',
+    pattern: /\$[({].*[)}].*-/,
+    severity: 'high',
+    description: 'Variable expansion used to construct flags, hiding dangerous options',
+  },
+  {
+    id: 'SHELL_METACHARACTERS',
+    name: 'Shell metacharacter injection',
+    pattern: /[`]|(?:\$\((?!.*\becho\b))/,
+    severity: 'critical',
+    description: 'Backticks or $() command substitution (excluding safe echo patterns)',
+  },
+  {
+    id: 'DANGEROUS_VARIABLES',
+    name: 'Dangerous environment variable manipulation',
+    pattern: /(?:^|\s)(?:PATH|LD_PRELOAD|LD_LIBRARY_PATH|DYLD_INSERT_LIBRARIES|PYTHONPATH|NODE_PATH|RUBYLIB|PERL5LIB)\s*=/,
+    severity: 'critical',
+    description: 'Overwriting PATH/LD_PRELOAD can hijack command resolution or inject libraries',
+  },
+
+  // --- Category: Whitespace & Encoding Attacks ---
+  {
+    id: 'NEWLINES',
+    name: 'Embedded newlines in command',
+    pattern: /(?<!\\)\n.*(?:rm|curl|wget|chmod|chown|sudo|eval|exec)/,
+    severity: 'high',
+    description: 'Newlines can hide dangerous commands after an innocent-looking first line',
+  },
+  {
+    id: 'BACKSLASH_ESCAPED_WHITESPACE',
+    name: 'Backslash-escaped whitespace hiding arguments',
+    pattern: /\\\s+(?:-|\/)/,
+    severity: 'medium',
+    description: 'Escaped whitespace can hide flags or paths from visual inspection',
+  },
+  {
+    id: 'CONTROL_CHARACTERS',
+    name: 'ASCII control characters',
+    // eslint-disable-next-line no-control-regex
+    pattern: /[\x00-\x08\x0e-\x1f\x7f]/,
+    severity: 'critical',
+    description: 'Control characters can manipulate terminal behavior or hide content',
+  },
+  {
+    id: 'UNICODE_WHITESPACE',
+    name: 'Unicode zero-width or invisible characters',
+    pattern: /[\u200B-\u200F\u2028-\u202F\uFEFF\u00A0\u2060\u180E]/,
+    severity: 'critical',
+    description: 'Zero-width spaces and invisible unicode can hide injected commands',
+  },
+
+  // --- Category: Shell Expansion Attacks ---
+  {
+    id: 'DANGEROUS_PATTERNS_COMMAND_SUBSTITUTION',
+    name: 'Command substitution in dangerous context',
+    pattern: /\$\(.*(?:curl|wget|nc|bash|sh|python|perl|ruby|node)\b/i,
+    severity: 'critical',
+    description: 'Command substitution executing network or interpreter commands',
+  },
+  {
+    id: 'DANGEROUS_PATTERNS_INPUT_REDIRECTION',
+    name: 'Input redirection from sensitive sources',
+    pattern: /<\s*(?:\/etc\/(?:passwd|shadow|sudoers)|\/proc\/|~\/\.ssh\/|~\/\.aws\/)/,
+    severity: 'critical',
+    description: 'Reading sensitive system files via input redirection',
+  },
+  {
+    id: 'DANGEROUS_PATTERNS_OUTPUT_REDIRECTION',
+    name: 'Output redirection to sensitive targets',
+    pattern: />\s*(?:\/etc\/|~\/\.ssh\/|~\/\.bashrc|~\/\.zshrc|~\/\.profile|~\/\.gitconfig)/,
+    severity: 'critical',
+    description: 'Overwriting sensitive system or user configuration files',
+  },
+  {
+    id: 'IFS_INJECTION',
+    name: 'IFS variable manipulation',
+    pattern: /\bIFS\s*=/,
+    severity: 'critical',
+    description: 'Changing Internal Field Separator can alter how shell parses commands',
+  },
+  {
+    id: 'BRACE_EXPANSION',
+    name: 'Dangerous brace expansion',
+    pattern: /\{.*(?:rm|curl|wget|chmod|eval|exec|sudo).*[,}]/,
+    severity: 'high',
+    description: 'Brace expansion can generate multiple dangerous commands from one expression',
+  },
+
+  // --- Category: Git & Process Attacks ---
+  {
+    id: 'GIT_COMMIT_SUBSTITUTION',
+    name: 'Git command with embedded substitution',
+    pattern: /git\s+(?:commit|push|tag).*\$[({]/,
+    severity: 'high',
+    description: 'Variable expansion in git commands can inject arbitrary content',
+  },
+  {
+    id: 'PROC_ENVIRON_ACCESS',
+    name: 'Process environment access',
+    pattern: /\/proc\/(?:self|\d+)\/(?:environ|cmdline|maps|mem)/,
+    severity: 'critical',
+    description: 'Accessing /proc can leak secrets, memory contents, or environment variables',
+  },
+
+  // --- Category: Token & Parsing Attacks ---
+  {
+    id: 'MALFORMED_TOKEN_INJECTION',
+    name: 'Malformed token or escape sequence',
+    pattern: /\\x[0-9a-f]{2}|\\u[0-9a-f]{4}|\\[0-7]{3}/i,
+    severity: 'high',
+    description: 'Hex/unicode/octal escape sequences can encode hidden characters',
+  },
+  {
+    id: 'MID_WORD_HASH',
+    name: 'Hash character in non-comment position',
+    pattern: /\w#\w/,
+    severity: 'medium',
+    description: 'Hash in mid-word position may indicate parameter expansion trick',
+  },
+  {
+    id: 'COMMENT_QUOTE_DESYNC',
+    name: 'Comment/quote desynchronization',
+    pattern: /#.*['"][^'"]*$/,
+    severity: 'medium',
+    description: 'Unclosed quotes after comment can desync parsing across lines',
+  },
+  {
+    id: 'QUOTED_NEWLINE',
+    name: 'Newline inside quoted string hiding commands',
+    pattern: /["'][^"']*\n[^"']*["']/,
+    severity: 'high',
+    description: 'Newlines inside quotes can hide command sequences',
+  },
+
+  // --- Category: Zsh-Specific Attacks ---
+  {
+    id: 'ZSH_DANGEROUS_COMMANDS',
+    name: 'Zsh-specific dangerous builtins',
+    pattern: /\b(?:zmodload|sysopen|sysread|syswrite|zsystem|zselect|ztcp)\b/,
+    severity: 'critical',
+    description: 'Zsh builtins that can load modules, open sockets, or access raw file descriptors',
+  },
+  {
+    id: 'BACKSLASH_ESCAPED_OPERATORS',
+    name: 'Backslash-escaped shell operators',
+    pattern: /\\[|;&]/,
+    severity: 'medium',
+    description: 'Escaped operators may bypass naive pipe/semicolon filtering',
+  },
+];
+
+/**
+ * Run all 23 security checks against a bash command.
+ *
+ * @param {string} command - Bash command to validate
+ * @returns {{ safe: boolean, findings: Array<{id: string, name: string, severity: string, description: string}> }}
+ */
+export function runSecurityChecks(command) {
+  if (!command || typeof command !== 'string') {
+    return { safe: true, findings: [], checksRun: SECURITY_CHECKS.length };
+  }
+
+  const findings = [];
+
+  for (const check of SECURITY_CHECKS) {
+    check.pattern.lastIndex = 0; // Reset for global patterns
+    if (check.pattern.test(command)) {
+      findings.push({
+        id: check.id,
+        name: check.name,
+        severity: check.severity,
+        description: check.description,
+      });
+    }
+  }
+
+  return {
+    safe: findings.length === 0,
+    findings,
+    checksRun: SECURITY_CHECKS.length,
+    criticalCount: findings.filter(f => f.severity === 'critical').length,
+    highCount: findings.filter(f => f.severity === 'high').length,
+    mediumCount: findings.filter(f => f.severity === 'medium').length,
+  };
+}
+
+/**
+ * Quick check — returns true if command has any critical findings.
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function hasCriticalRisk(command) {
+  if (!command) return false;
+  return SECURITY_CHECKS
+    .filter(c => c.severity === 'critical')
+    .some(c => {
+      c.pattern.lastIndex = 0;
+      return c.pattern.test(command);
+    });
+}
+
+/**
+ * Get security check summary for dashboard/reporting.
+ */
+export function getSecurityCheckSummary() {
+  const bySeverity = { critical: 0, high: 0, medium: 0 };
+  for (const check of SECURITY_CHECKS) {
+    bySeverity[check.severity]++;
+  }
+  return {
+    totalChecks: SECURITY_CHECKS.length,
+    bySeverity,
+    categories: [
+      'Command Structure Attacks',
+      'Flag/Argument Obfuscation',
+      'Whitespace & Encoding Attacks',
+      'Shell Expansion Attacks',
+      'Git & Process Attacks',
+      'Token & Parsing Attacks',
+      'Zsh-Specific Attacks',
+    ],
+  };
+}
+
+/**
+ * Language-specific security checks for SAST scanning.
+ * Complements the 23 bash security checks with code-level patterns
+ * for JavaScript, TypeScript, and Python.
+ */
+export const LANGUAGE_SECURITY_CHECKS = {
+  javascript: [
+    { id: 'JS_EVAL', pattern: /\beval\s*\(/, severity: 'critical', description: 'eval() enables remote code execution' },
+    { id: 'JS_NEW_FUNCTION', pattern: /new\s+Function\s*\(/, severity: 'critical', description: 'new Function() enables RCE' },
+    { id: 'JS_INNERHTML', pattern: /\.innerHTML\s*=/, severity: 'critical', description: 'innerHTML enables XSS attacks' },
+    { id: 'JS_OUTERHTML', pattern: /\.outerHTML\s*=/, severity: 'critical', description: 'outerHTML enables XSS attacks' },
+    { id: 'JS_DOCUMENT_WRITE', pattern: /document\.write\s*\(/, severity: 'critical', description: 'document.write enables XSS' },
+    { id: 'JS_DANGEROUSLY_SET', pattern: /dangerouslySetInnerHTML/, severity: 'critical', description: 'React XSS vector' },
+    { id: 'JS_NULL_DOM', pattern: /getElementById\s*\([^)]+\)\s*\./, severity: 'high', description: 'DOM query without null check may crash' },
+    { id: 'JS_QUERYSELECTOR_NULL', pattern: /querySelector\s*\([^)]+\)\s*\./, severity: 'high', description: 'querySelector without null check may crash' },
+  ],
+  typescript: [
+    { id: 'TS_EVAL', pattern: /\beval\s*\(/, severity: 'critical', description: 'eval() enables RCE' },
+    { id: 'TS_INNERHTML', pattern: /\.innerHTML\s*=/, severity: 'critical', description: 'innerHTML enables XSS' },
+    { id: 'TS_DANGEROUSLY_SET', pattern: /dangerouslySetInnerHTML/, severity: 'critical', description: 'React XSS vector' },
+    { id: 'TS_ANY_CAST', pattern: /as\s+any\b/, severity: 'medium', description: 'Type assertion to any bypasses type safety' },
+    { id: 'TS_NULL_DOM', pattern: /getElementById\s*\([^)]+\)\s*\./, severity: 'high', description: 'DOM query without null check' },
+  ],
+  python: [
+    { id: 'PY_EVAL', pattern: /\beval\s*\(/, severity: 'critical', description: 'eval() enables RCE' },
+    { id: 'PY_EXEC', pattern: /\bexec\s*\(/, severity: 'critical', description: 'exec() enables RCE' },
+    { id: 'PY_COMPILE', pattern: /\bcompile\s*\(/, severity: 'high', description: 'compile() can enable code injection' },
+    { id: 'PY_SHELL_TRUE', pattern: /shell\s*=\s*True/, severity: 'critical', description: 'shell=True enables command injection' },
+    { id: 'PY_PICKLE', pattern: /pickle\.loads?\s*\(/, severity: 'critical', description: 'pickle from untrusted source is unsafe' },
+    { id: 'PY_YAML_LOAD', pattern: /yaml\.load\s*\([^)]*\)\s*(?!.*Loader)/, severity: 'high', description: 'yaml.load without SafeLoader is unsafe' },
+  ],
+};
+
+/**
+ * Run language-specific security checks against source code content.
+ * @param {string} content - Source code to scan
+ * @param {string} language - Language identifier (javascript, typescript, python)
+ * @returns {{ safe: boolean, findings: Array, checksRun: number }}
+ */
+export function runLanguageSecurityChecks(content, language) {
+  const checks = LANGUAGE_SECURITY_CHECKS[language] || [];
+  if (!content || checks.length === 0) return { safe: true, findings: [], checksRun: 0 };
+
+  const findings = [];
+  for (const check of checks) {
+    if (check.pattern.test(content)) {
+      findings.push({ id: check.id, severity: check.severity, description: check.description });
+    }
+  }
+  return {
+    safe: findings.length === 0,
+    findings,
+    checksRun: checks.length,
+  };
+}

package/src/security/index.js

@@ -0,0 +1,9 @@
+// Barrel exports for security system
+export {
+  runSecurityChecks,
+  hasCriticalRisk,
+  getSecurityCheckSummary,
+  SECURITY_CHECKS,
+  LANGUAGE_SECURITY_CHECKS,
+  runLanguageSecurityChecks,
+} from './bash-security.js';

package/src/telemetry/config.js

@@ -41,7 +41,7 @@ export function getTelemetryConfig(targetDir) {
       anonymousId: telemetry.anonymous_id || null,
       endpoint: telemetry.endpoint || defaults.endpoint,
     };
-  } catch {
+  } catch { /* expected: file may not exist */
     return defaults;
   }
 }
@@ -81,7 +81,7 @@ export function setEnabled(targetDir, enabled) {
     }
 
     writeFileSync(configPath, yaml.dump(config, { lineWidth: -1 }), 'utf-8');
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Silently fail — telemetry config is non-critical
   }
 }
@@ -108,7 +108,7 @@ export function getAnonymousId(targetDir) {
       if (!parsed.telemetry) parsed.telemetry = {};
       parsed.telemetry.anonymous_id = id;
       writeFileSync(configPath, yaml.dump(parsed, { lineWidth: -1 }), 'utf-8');
-    } catch {
+    } catch { /* expected: file may not exist */
       // Return generated ID even if persistence fails
     }
   }

package/src/telemetry/sender.js

@@ -72,7 +72,7 @@ export async function sendEvents(events, config) {
 
       clearTimeout(timeout);
       if (res.ok || res.status < 500) return true; // 4xx = don't retry
-    } catch {
+    } catch { /* expected: network may be unavailable */
       // Network error or timeout — retry if attempts remain
       if (attempt < 3) {
         await new Promise(r => setTimeout(r, attempt * 500)); // 500ms, 1000ms

package/src/terminal/cli-registry.js

@@ -173,7 +173,7 @@ export async function isProviderAvailable(name) {
     const cmd = process.platform === 'win32' ? 'where' : 'which';
     execFileSync(cmd, [provider.command], { stdio: 'ignore' });
     return true;
-  } catch {
+  } catch { /* expected: git command may fail */
     return false;
   }
 }

package/src/terminal/cost-tracker.js

@@ -23,9 +23,8 @@ export const COST_PER_1K = {
   // Gemini models
   pro: 0.007,
   flash: 0.001,
-  // Codex/Copilot
+  // Codex
   codex: 0.010,
-  copilot: 0.010,
   mini: 0.003,
   // Fallback
   unknown: 0.015,

package/src/terminal/prompt-builder.js

@@ -160,8 +160,8 @@ export function buildAgentPrompt(config) {
     if (gotchasSection) {
       sections.push('<!-- GOTCHAS -->\n' + gotchasSection);
     }
-  } catch {
-    // Gotchas are advisory — never block prompt building
+  } catch (err) {
+    process.stderr.write(`[chati] prompt-builder gotchas: ${err.message}\n`);
   }
 
   // 5. Additional context (user input relay for needs_input)
@@ -516,7 +516,7 @@ export function loadPreset(stack, projectDir) {
       const raw = readFileSync(presetPath, 'utf-8');
       const preset = parsePresetYaml(raw);
       return { loaded: true, preset, stack };
-    } catch {
+    } catch { /* expected: file may not exist */
       continue;
     }
   }
@@ -549,7 +549,7 @@ export function detectPreset(projectDir) {
   let presetFiles;
   try {
     presetFiles = readdirSync(presetsDir).filter(f => f.endsWith('.yaml'));
-  } catch {
+  } catch { /* expected: directory may not exist */
     return null;
   }
 
@@ -708,10 +708,7 @@ function buildOutputInstructions(config) {
   const modelValue = config?.model || 'unknown';
 
   return `<!-- OUTPUT INSTRUCTIONS -->
-## Output Instructions (MANDATORY)
-
-When you complete your work, you MUST include a structured handoff block at the END of your response.
-This block is how the orchestrator reads your results. Without it, your work cannot be collected.
+At the END of your response, include this handoff block:
 
 \`\`\`
 <chati-handoff>
@@ -719,29 +716,16 @@ status: complete
 score: 95
 provider: ${providerValue}
 model: ${modelValue}
-summary: One to three sentence summary of what was accomplished.
+summary: One to three sentence summary.
 outputs:
-  - path/to/artifact1.md
-  - path/to/artifact2.md
+  - path/to/artifact.md
 decisions:
-  key1: value1
-  key2: value2
-blockers:
-  - Description of any unresolved blocker
+  key: value
+blockers: []
 needs_input_question: null
 </chati-handoff>
 \`\`\`
 
-### Status values:
-- **complete**: All work finished successfully (score >= 95 required)
-- **partial**: Some work done but not all criteria met
-- **needs_input**: You need information from the user to continue. Set \`needs_input_question\` to your question.
-- **error**: Something went wrong that you cannot recover from
-
-### Important:
-- The \`<chati-handoff>\` block MUST appear in your response
-- Score must be 0-100 (95+ to pass quality gate)
-- List ALL artifacts you created/modified in outputs
-- The \`provider\` and \`model\` fields MUST match: provider: ${providerValue}, model: ${modelValue}
-- If you need user input, set status to "needs_input" and write your question in needs_input_question`;
+Status: complete (score >= 95) | partial | needs_input (set question) | error
+List ALL created/modified artifacts in outputs. Provider: ${providerValue}, model: ${modelValue}.`;
 }

package/src/terminal/rate-limiter.js

@@ -19,7 +19,6 @@ export const DEFAULT_LIMITS = {
   claude: 20,
   gemini: 15,
   codex: 10,
-  copilot: 10,
 };
 
 /** Sliding window size in milliseconds (1 minute). */
@@ -41,7 +40,7 @@ const WINDOW_MS = 60_000;
 /**
  * Create a rate limiter instance for a specific provider.
  *
- * @param {string} provider - Provider name (claude, gemini, codex, copilot)
+ * @param {string} provider - Provider name (claude, gemini, codex)
  * @param {{ limit?: number }} [customLimits={}]
  * @returns {{ canSpawn: () => boolean, recordSpawn: () => void, waitForSlot: () => Promise<void>, getStats: () => RateLimiterStats, reset: () => void }}
  */

package/src/terminal/run-agent.js

@@ -78,8 +78,8 @@ async function main() {
       const raw = readFileSync(sessionPath, 'utf-8');
       sessionState = parseSimpleYaml(raw);
     }
-  } catch {
-    // Session state is optional — continue without it
+  } catch (err) {
+    process.stderr.write(`[chati] run-agent session-parse: ${err.message}\n`);
   }
 
   // Build the agent prompt
@@ -248,7 +248,7 @@ async function flushAndSend(projectDir) {
   try {
     const tConfig = getTelemetryConfig(projectDir);
     await sendEvents(events, { ...tConfig, version: tConfig.chatiVersion || 'unknown' });
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Silently fail — telemetry must never block agent execution
   }
 }

package/src/terminal/spawner.js

@@ -23,8 +23,15 @@ export const DEFAULT_CONCURRENCY = 3;
 export const TRANSIENT_PATTERNS = [
   /rate limit/i, /too many requests/i, /429/, /503/,
   /timeout/i, /ECONNRESET/, /ECONNREFUSED/,
+  /529/, /overloaded/i, /capacity/i,
 ];
 
+/** Model downgrade map for fallback on overload errors. */
+const MODEL_DOWNGRADE_MAP = { opus: 'sonnet', pro: 'flash' };
+
+/** Patterns that indicate overload (triggers model fallback). */
+const OVERLOAD_PATTERNS = [/529/, /overloaded/i, /capacity/i, /too many requests/i];
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -156,7 +163,8 @@ export function buildSpawnCommand(config) {
   if (config.contextPayload) {
     try {
       env.CHATI_CONTEXT = JSON.stringify(config.contextPayload);
-    } catch {
+    } catch (err) {
+      process.stderr.write(`[chati] spawner context-serialize: ${err.message}\n`);
       env.CHATI_CONTEXT = '{}';
     }
   }
@@ -431,7 +439,7 @@ export function killTerminal(handle) {
     const forceKillTimer = setTimeout(() => {
       try {
         handle.process.kill('SIGKILL');
-      } catch {
+      } catch { /* expected: process may already be dead */
         // already dead -- ignore
       }
     }, 5000);
@@ -445,7 +453,7 @@ export function killTerminal(handle) {
 
     try {
       handle.process.kill('SIGTERM');
-    } catch {
+    } catch { /* expected: process may already be dead */
       clearTimeout(forceKillTimer);
       handle.status = 'killed';
       resolve({ killed: false, exitCode: handle.exitCode });
@@ -509,6 +517,7 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
   const maxRetries = retryOptions.maxRetries ?? 2;
   const baseDelay = retryOptions.baseDelay ?? 2000;
   const shouldRetry = retryOptions.shouldRetry || isTransientFailure;
+  const enableModelFallback = retryOptions.enableModelFallback ?? true;
 
   let lastHandle = null;
 
@@ -536,7 +545,35 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
     }
 
     // Non-transient or out of retries — return as-is
-    return handle;
+    break;
+  }
+
+  // Model fallback: if all retries exhausted with overload errors, try with downgraded model
+  if (enableModelFallback && lastHandle && lastHandle.exitCode !== 0) {
+    const stderrStr = Array.isArray(lastHandle.stderr) ? lastHandle.stderr.join('') : (lastHandle.stderr || '');
+    const isOverload = OVERLOAD_PATTERNS.some(p => p.test(stderrStr));
+    const fallbackModel = MODEL_DOWNGRADE_MAP[config.model];
+
+    if (isOverload && fallbackModel) {
+      const fallbackConfig = { ...config, model: fallbackModel };
+      const fallbackHandle = spawnTerminal(fallbackConfig);
+
+      await new Promise((resolve) => {
+        if (!fallbackHandle.process) { resolve(); return; }
+        if (fallbackHandle.status !== 'running') { resolve(); return; }
+        fallbackHandle.process.once('exit', () => resolve());
+      });
+
+      // Record fallback metadata
+      fallbackHandle.modelFallback = {
+        original: config.model,
+        actual: fallbackModel,
+        reason: 'overload_exhausted_retries',
+        timestamp: new Date().toISOString(),
+      };
+
+      return fallbackHandle;
+    }
   }
 
   return lastHandle;

package/src/upgrade/checker.js

@@ -13,7 +13,7 @@ export function getCurrentVersion(targetDir) {
   try {
     const config = yaml.load(readFileSync(configPath, 'utf-8'));
     return config?.version || null;
-  } catch {
+  } catch { /* expected: file may not exist */
     return null;
   }
 }
@@ -82,7 +82,7 @@ export function updateConfigVersion(targetDir, newVersion) {
     config.version = newVersion;
     writeFileSync(configPath, yaml.dump(config, { lineWidth: -1 }), 'utf-8');
     return true;
-  } catch {
+  } catch { /* expected: file may not exist */
     return false;
   }
 }

package/src/upgrade/migrator.js

@@ -38,7 +38,7 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
           rollback: content.rollback || [],
         });
       }
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       // Skip invalid migration files
     }
   }

package/src/utils/config-parser.js

@@ -91,7 +91,7 @@ export async function isCommandAvailable(command) {
     const cmd = process.platform === 'win32' ? 'where' : 'which';
     execFileSync(cmd, [command], { stdio: 'ignore' });
     return true;
-  } catch {
+  } catch { /* expected: git command may fail */
     return false;
   }
 }

package/src/utils/file-lock.js

@@ -45,7 +45,7 @@ function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
+  } catch { /* expected: process may already be dead */
     return false;
   }
 }
@@ -60,7 +60,7 @@ function readLockFile(lockPath) {
   try {
     const content = readFileSync(lockPath, 'utf-8');
     return JSON.parse(content);
-  } catch {
+  } catch { /* expected: file may not exist */
     return null;
   }
 }
@@ -182,7 +182,7 @@ export function releaseLock(lockPath) {
         unlinkSync(lockPath);
       }
     }
-  } catch {
+  } catch { /* expected: file may already be deleted */
     // Lock may already be released — ignore
   }
 }