@wundam/orchex 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/model-validator.js

@@ -0,0 +1,125 @@
+import { readModelCache, fetchAndCacheModels } from './model-cache.js';
+import { DEFAULT_MODELS, getProviderApiKey } from './config.js';
+import { createLogger } from './logging.js';
+const log = createLogger('model-validator');
+/**
+ * Static fallback chains — used only when registry + cache are both unavailable.
+ */
+export const MODEL_FALLBACKS = {
+    anthropic: ['claude-sonnet-4-5-20250929', 'claude-3-5-sonnet-20241022', 'claude-3-haiku-20240307'],
+    openai: ['gpt-4.1', 'gpt-4o', 'gpt-4o-mini', 'gpt-3.5-turbo'],
+    gemini: ['gemini-2.5-pro', 'gemini-2.0-flash', 'gemini-1.5-flash'],
+    deepseek: ['deepseek-chat', 'deepseek-coder'],
+    bedrock: ['claude-3.5-sonnet', 'claude-3-haiku'],
+    ollama: ['llama3.3:70b', 'llama3.2:latest'],
+};
+/**
+ * Query Ollama for installed models (local-only).
+ */
+async function queryOllamaModels() {
+    const baseUrl = process.env.OLLAMA_BASE_URL ?? process.env.OLLAMA_HOST ?? 'http://localhost:11434';
+    try {
+        const resp = await fetch(`${baseUrl}/api/tags`, { signal: AbortSignal.timeout(3000) });
+        if (!resp.ok)
+            return [];
+        const data = await resp.json();
+        return data.models.map(m => m.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve a model to an available one using the registry/cache.
+ * Resolution chain: cache → server fetch → static fallback
+ */
+export async function resolveModel(provider, preferredModel, apiUrl) {
+    // Special case: Ollama models are local-only, query directly
+    if (provider === 'ollama') {
+        const ollamaModels = await queryOllamaModels();
+        if (ollamaModels.length > 0) {
+            if (ollamaModels.includes(preferredModel)) {
+                return { originalModel: preferredModel, resolvedModel: preferredModel, wasFallback: false };
+            }
+            // Find partial match (e.g., "llama3.3" matches "llama3.3:70b")
+            const partial = ollamaModels.find(m => m.startsWith(preferredModel) || preferredModel.startsWith(m.split(':')[0]));
+            if (partial) {
+                return {
+                    originalModel: preferredModel,
+                    resolvedModel: partial,
+                    wasFallback: true,
+                    reason: `Partial match: ${partial}`,
+                };
+            }
+            return {
+                originalModel: preferredModel,
+                resolvedModel: ollamaModels[0],
+                wasFallback: true,
+                reason: `${preferredModel} not installed, using ${ollamaModels[0]}`,
+            };
+        }
+        // Ollama not running — fall through to static fallback
+    }
+    // 1. Try cache
+    let cache = await readModelCache();
+    // 2. If cache miss/expired and we have a server URL, fetch fresh
+    if (!cache && apiUrl) {
+        cache = await fetchAndCacheModels(apiUrl);
+    }
+    // 3. If we have cached data, check if model exists
+    if (cache?.providers[provider]) {
+        const providerModels = cache.providers[provider];
+        const found = providerModels.some(m => m.modelId === preferredModel);
+        if (found) {
+            return { originalModel: preferredModel, resolvedModel: preferredModel, wasFallback: false };
+        }
+        // Model not in registry — find first available from fallback chain
+        const fallbacks = MODEL_FALLBACKS[provider] ?? [];
+        for (const fb of fallbacks) {
+            if (providerModels.some(m => m.modelId === fb)) {
+                log.warn({ provider, original: preferredModel, fallback: fb }, 'model_fallback');
+                return {
+                    originalModel: preferredModel,
+                    resolvedModel: fb,
+                    wasFallback: true,
+                    reason: `${preferredModel} not found in ${provider} model registry, using ${fb}`,
+                };
+            }
+        }
+        // None of the fallbacks exist in registry either — use first available from registry
+        if (providerModels.length > 0) {
+            const first = providerModels[0].modelId;
+            log.warn({ provider, original: preferredModel, fallback: first }, 'model_fallback_registry_first');
+            return {
+                originalModel: preferredModel,
+                resolvedModel: first,
+                wasFallback: true,
+                reason: `${preferredModel} not found, using first available: ${first}`,
+            };
+        }
+    }
+    // 4. No cache, no server — use static fallback
+    const fallbacks = MODEL_FALLBACKS[provider] ?? [];
+    if (fallbacks.includes(preferredModel)) {
+        return { originalModel: preferredModel, resolvedModel: preferredModel, wasFallback: false };
+    }
+    const fallback = fallbacks[0] ?? DEFAULT_MODELS[provider] ?? preferredModel;
+    if (fallback !== preferredModel) {
+        log.warn({ provider, original: preferredModel, fallback }, 'model_fallback_static');
+        return {
+            originalModel: preferredModel,
+            resolvedModel: fallback,
+            wasFallback: true,
+            reason: `Offline — ${preferredModel} unverified, using safe default ${fallback}`,
+        };
+    }
+    return { originalModel: preferredModel, resolvedModel: preferredModel, wasFallback: false };
+}
+/**
+ * Check if a provider has a valid API key configured.
+ */
+export function isProviderAvailable(provider) {
+    if (provider === 'ollama' || provider === 'bedrock')
+        return true; // No key needed / AWS creds
+    return !!getProviderApiKey(provider);
+}

package/dist/orchestrator.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutorStrategy, ExecuteResponse, StreamResult, BudgetViolationType, FileContext } from './types.js';
+import { type ErrorCategory } from './intelligence/index.js';
 /**
  * Extended stream result with context budget metrics (Orchex Learn).
  */
@@ -6,6 +7,8 @@ export interface StreamResultWithBudget extends StreamResult {
     /** Context budget metrics */
     contextMetrics?: {
         estimatedTokens: number;
+        /** Actual input tokens from LLM API response */
+        actualTokens?: number;
         budgetUtilization: number;
         violationType: BudgetViolationType;
         budgetLimit: number;
@@ -28,6 +31,17 @@ export declare function gatherStreamFileContext(projectDir: string, stream: {
     owns?: string[];
     reads?: string[];
 }): Promise<FileContext[]>;
+export interface CircuitBreakerResult {
+    tripped: boolean;
+    category?: ErrorCategory;
+    /** True if the tripped category is selfHealable — fix streams should still be generated. */
+    selfHealable?: boolean;
+    failedCount: number;
+    totalCount: number;
+    message?: string;
+    suggestion?: string;
+}
+export declare function checkWaveCircuitBreaker(waveResults: StreamResult[], threshold?: number): CircuitBreakerResult;
 /**
  * Execute a single wave of the orchestration.
  * Steps: resolve → setup → context → execute → validate → apply → verify → report

package/dist/orchestrator.js

@@ -1,20 +1,17 @@
-import { loadManifest, updateStreamStatus, addStream, recoverStuckStreams, cleanStaleLock } from './manifest.js';
+import { loadManifest, saveManifest, updateStreamStatus, addStream, recoverStuckStreams, cleanStaleLock } from './manifest.js';
 import { createLogger, clearExecutionLog } from './logger.js';
 import { createLogger as createPinoLogger } from './logging.js';
 const log = createPinoLogger('orchestrator');
-import { generateFixStream } from './intelligence/self-healer.js';
-import { analyzeError } from './intelligence/error-analyzer.js';
-import { cleanupOrphanFixStreams } from './intelligence/fix-stream-manager.js';
+import { generateFixStream, analyzeError, cleanupOrphanFixStreams, streamResultToTelemetryEvent, appendLocalEvents, runLearningCycle, routeStream, loadRoutingRules, } from './intelligence/index.js';
 import { calculateWaves } from './waves.js';
 import { buildFullPrompt, buildFullPromptOptimized } from './context-builder.js';
-import { applyArtifact, writeArtifact, validateArtifactSanity, createStreamBackup, withStreamIsolation, writeBackup, readAllBackups, deleteBackup, recoverFromIsolationCrash } from './artifacts.js';
+import { applyArtifact, writeArtifact, validateArtifactSanity, createStreamBackup, revertStreamBackup, withStreamIsolation, writeBackup, readAllBackups, deleteBackup, recoverFromIsolationCrash } from './artifacts.js';
 import { runCommands } from './commands.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { loadConfig, getConfiguredModel } from './config.js';
-import { getTier } from './tiers.js';
+import { loadConfig, getConfiguredModel, DEFAULT_MODELS } from './config.js';
+import { getEffectiveTier, getEffectiveLimits } from './tiers.js';
 import { broadcaster } from './execution-broadcaster.js';
-import { streamResultToTelemetryEvent, appendLocalEvents, runLearningCycle, } from './intelligence/learning-engine.js';
 const DEFAULT_MAX_TOKENS = 16384;
 const LOCK_FILE = '.orchex/active/.lock';
 /**
@@ -44,6 +41,35 @@ export async function gatherStreamFileContext(projectDir, stream) {
     }
     return context;
 }
+export function checkWaveCircuitBreaker(waveResults, threshold = 0.75) {
+    const totalCount = waveResults.length;
+    const failed = waveResults.filter(r => r.status === 'failed' && r.errorDetail);
+    const failedCount = failed.length;
+    if (failedCount === 0 || totalCount === 0) {
+        return { tripped: false, failedCount: 0, totalCount };
+    }
+    const ratio = failedCount / totalCount;
+    if (ratio < threshold) {
+        return { tripped: false, failedCount, totalCount };
+    }
+    const categories = new Set(failed.map(r => r.errorDetail.category));
+    if (categories.size !== 1) {
+        return { tripped: false, failedCount, totalCount };
+    }
+    const category = [...categories][0];
+    const suggestion = failed[0].errorDetail.suggestion;
+    // selfHealable is true only when ALL failed streams agree (any false → false)
+    const selfHealable = failed.every(r => r.errorDetail.selfHealable);
+    return {
+        tripped: true,
+        category,
+        selfHealable,
+        failedCount,
+        totalCount,
+        message: `${failedCount}/${totalCount} streams failed with ${category}`,
+        suggestion,
+    };
+}
 /**
  * Execute a single wave of the orchestration.
  * Steps: resolve → setup → context → execute → validate → apply → verify → report
@@ -103,7 +129,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
     }
     // 1. RESOLVE — load manifest, calculate waves, find target
     const manifest = await loadManifest(projectDir);
-    const { waves, errors, blocked } = calculateWaves(manifest);
+    const { waves, errors, blocked } = calculateWaves(manifest, projectDir);
     // Only fail when there are truly no runnable waves.
     // Blocked stream messages are informational — other streams may still be runnable
     // (e.g., fix streams whose deps are satisfied while the original's dependents are blocked).
@@ -145,7 +171,16 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
         };
     }
     const totalWaves = waves.length;
-    const model = options.model ?? getConfiguredModel(config);
+    const baseModel = options.model ?? DEFAULT_MODELS[executor.provider] ?? getConfiguredModel(config);
+    // Validate base model before execution
+    const { resolveModel: resolveBaseModel } = await import('./model-validator.js');
+    const { resolveApiUrl: resolveBaseApiUrl } = await import('./config.js');
+    const baseApiUrl = config.mode === 'cloud' && config.apiKey ? await resolveBaseApiUrl() : undefined;
+    const baseValidation = await resolveBaseModel(executor.provider, baseModel, baseApiUrl);
+    const model = baseValidation.resolvedModel;
+    if (baseValidation.wasFallback) {
+        log.warn({ original: baseValidation.originalModel, resolved: model, reason: baseValidation.reason }, 'wave_model_fallback');
+    }
     const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
     const waveLog = log.child({ orchestrationId: manifest.feature, waveNumber: targetWave.number });
     const streamResults = [];
@@ -174,14 +209,14 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
             const failed = results.find((r) => !r.success);
             if (failed) {
                 const setupError = `Setup command failed: ${failed.command}`;
-                const setupAnalysis = analyzeError(failed.error ?? failed.stderr ?? setupError);
+                const setupAnalysis = analyzeError(failed.error ?? failed.stderr ?? setupError, 'setup');
                 await updateStreamStatus(projectDir, stream.id, 'failed', `Setup failed: ${failed.error ?? failed.stderr}`);
                 streamResults.push({
                     id: stream.id,
                     name: stream.name,
                     status: 'failed',
                     error: setupError,
-                    errorDetail: { category: setupAnalysis.category, retryable: setupAnalysis.retryable, suggestion: setupAnalysis.suggestion },
+                    errorDetail: { category: setupAnalysis.category, retryable: setupAnalysis.retryable, selfHealable: setupAnalysis.selfHealable, suggestion: setupAnalysis.suggestion },
                 });
                 broadcaster.broadcast(manifest.feature, {
                     type: 'stream_failed',
@@ -237,6 +272,38 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
     // Track wave execution timing
     const waveStartTime = Date.now();
     const waveStartedAt = new Date().toISOString();
+    // Smart routing — opt-in via ~/.orchex/config.json routing rules
+    const routingRules = loadRoutingRules();
+    const routeDecisions = new Map();
+    if (routingRules.defaultProvider || routingRules.overrides) {
+        for (const stream of activeStreams) {
+            const streamDef = updatedManifest.streams[stream.id];
+            const decision = routeStream({ id: stream.id, name: stream.name, owns: stream.owns ?? [], reads: stream.reads ?? [], plan: streamDef?.plan }, routingRules);
+            routeDecisions.set(stream.id, decision);
+            if (decision.provider !== executor.provider) {
+                log.info({ streamId: stream.id, provider: decision.provider, model: decision.model, reasoning: decision.reasoning }, 'smart_route_applied');
+            }
+        }
+    }
+    // Validate and resolve models before execution
+    const { resolveModel } = await import('./model-validator.js');
+    const { resolveApiUrl } = await import('./config.js');
+    const apiUrl = config.mode === 'cloud' && config.apiKey ? await resolveApiUrl() : undefined;
+    const modelFallbacks = [];
+    for (const [streamId, decision] of routeDecisions) {
+        const validation = await resolveModel(decision.provider, decision.model, apiUrl);
+        if (validation.wasFallback) {
+            routeDecisions.set(streamId, {
+                ...decision,
+                model: validation.resolvedModel,
+                reasoning: `${decision.reasoning} [fallback: ${validation.reason}]`,
+            });
+            modelFallbacks.push(`${streamId}: ${validation.originalModel} → ${validation.resolvedModel}`);
+        }
+    }
+    if (modelFallbacks.length > 0) {
+        log.warn({ fallbacks: modelFallbacks }, 'model_fallbacks_applied');
+    }
     const executePromises = activeStreams.map(async (stream) => {
         const streamLog = waveLog.child({ streamId: stream.id });
         const streamStartTime = Date.now();
@@ -247,6 +314,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
             const useOptimization = options.optimize !== false; // Default to true
             let prompt;
             let structuredPrompt;
+            const streamDef = updatedManifest.streams[stream.id];
             if (useOptimization) {
                 // Use optimized builder with caching hints and budget checking
                 const promptOptions = {
@@ -254,7 +322,12 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                     model,
                     // Don't enforce hard limit here - just warn and continue
                     enforceHardLimit: false,
+                    isFixStream: !!streamDef?.parentStreamId,
                 };
+                // Log model routing suggestion if present
+                if (streamDef?.suggestedProvider && !streamDef.provider) {
+                    streamLog.info({ streamId: stream.id, suggestedProvider: streamDef.suggestedProvider }, 'model_routing_suggestion');
+                }
                 const optimized = await buildFullPromptOptimized(projectDir, stream.id, updatedManifest, promptOptions);
                 prompt = optimized.fullPrompt;
                 structuredPrompt = optimized;
@@ -291,11 +364,14 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                 };
             }
             // 4. EXECUTE — call LLM API
-            const streamDef = updatedManifest.streams[stream.id];
-            const timeoutMs = streamDef.timeoutMs ?? 120000;
+            const routeDecision = routeDecisions.get(stream.id);
+            const streamModel = routeDecision?.model ?? model;
+            const isCloud = (config?.mode === 'cloud') || executor.provider === 'orchex-cloud';
+            const defaultTimeoutMs = isCloud ? 600_000 : 120_000; // 10min cloud, 2min local
+            const timeoutMs = streamDef.timeoutMs ?? defaultTimeoutMs;
             const request = {
                 prompt,
-                model,
+                model: streamModel,
                 maxTokens,
                 streamId: stream.id,
                 structuredPrompt,
@@ -327,6 +403,10 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                 stopHeartbeat();
             }
             const executionTimeMs = Date.now() - streamStartTime;
+            // Enrich budgetCheck with actual token count from API response
+            if (budgetCheck && result.tokensUsed?.input) {
+                budgetCheck.actualTokens = result.tokensUsed.input;
+            }
             if (!result.success || !result.artifact) {
                 // Log truncated rawResponse for debugging artifact extraction failures
                 const responsePreview = result.rawResponse
@@ -339,7 +419,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                     responsePreview,
                 });
                 const apiError = result.error ?? 'No artifact produced';
-                const apiAnalysis = analyzeError(apiError);
+                const apiAnalysis = analyzeError(apiError, 'transport');
                 broadcaster.broadcast(manifest.feature, {
                     type: 'stream_failed',
                     orchestrationId: manifest.feature,
@@ -351,7 +431,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                     name: stream.name,
                     status: 'failed',
                     error: apiError,
-                    errorDetail: { category: apiAnalysis.category, retryable: apiAnalysis.retryable, suggestion: apiAnalysis.suggestion },
+                    errorDetail: { category: apiAnalysis.category, retryable: apiAnalysis.retryable, selfHealable: apiAnalysis.selfHealable, suggestion: apiAnalysis.suggestion },
                     tokensUsed: result.tokensUsed,
                     provider: executor.provider,
                     model,
@@ -366,11 +446,23 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
             });
             // 5. VALIDATE — artifact is already parsed by executor
             const artifact = result.artifact;
+            // Check if stream was skipped by sibling fix completion while we were executing
+            const freshManifest = await loadManifest(projectDir);
+            const freshStatus = freshManifest.streams[stream.id]?.status;
+            if (freshStatus === 'skipped') {
+                log.info({ id: stream.id }, 'stream_skipped_by_sibling — discarding result');
+                return {
+                    id: stream.id,
+                    name: stream.name,
+                    status: 'skipped',
+                    summary: 'Skipped — sibling fix already resolved this stream',
+                };
+            }
             // 5a. SANITY CHECK — reject degenerate outputs before applying
             const sanity = validateArtifactSanity(artifact);
             if (!sanity.passed) {
                 const sanityError = `Sanity check failed: ${sanity.violations.join('; ')}`;
-                const sanityAnalysis = analyzeError(sanityError);
+                const sanityAnalysis = analyzeError(sanityError, 'artifact');
                 await logger.error('sanity_check_failed', {
                     id: stream.id,
                     violations: sanity.violations,
@@ -380,7 +472,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                     name: stream.name,
                     status: 'failed',
                     error: sanityError,
-                    errorDetail: { category: sanityAnalysis.category, retryable: sanityAnalysis.retryable, suggestion: sanityAnalysis.suggestion },
+                    errorDetail: { category: sanityAnalysis.category, retryable: sanityAnalysis.retryable, selfHealable: sanityAnalysis.selfHealable, suggestion: sanityAnalysis.suggestion },
                     tokensUsed: result.tokensUsed,
                     provider: executor.provider,
                     model,
@@ -395,7 +487,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
             const applyResult = await applyArtifact(projectDir, stream.id, { force: false });
             if (!applyResult.success) {
                 const applyError = applyResult.error ?? 'Apply failed';
-                const applyAnalysis = analyzeError(applyError);
+                const applyAnalysis = analyzeError(applyError, 'artifact');
                 await logger.error('stream_failed', {
                     id: stream.id,
                     phase: 'apply',
@@ -412,7 +504,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                     name: stream.name,
                     status: 'failed',
                     error: applyResult.error,
-                    errorDetail: { category: applyAnalysis.category, retryable: applyAnalysis.retryable, suggestion: applyAnalysis.suggestion },
+                    errorDetail: { category: applyAnalysis.category, retryable: applyAnalysis.retryable, selfHealable: applyAnalysis.selfHealable, suggestion: applyAnalysis.suggestion },
                     tokensUsed: result.tokensUsed,
                     provider: executor.provider,
                     model,
@@ -449,7 +541,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
         }
         catch (error) {
             const catchError = error.message;
-            const catchAnalysis = analyzeError(catchError);
+            const catchAnalysis = analyzeError(catchError, 'transport');
             await logger.error('stream_failed', {
                 id: stream.id,
                 phase: 'execution',
@@ -466,7 +558,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                 name: stream.name,
                 status: 'failed',
                 error: catchError,
-                errorDetail: { category: catchAnalysis.category, retryable: catchAnalysis.retryable, suggestion: catchAnalysis.suggestion },
+                errorDetail: { category: catchAnalysis.category, retryable: catchAnalysis.retryable, selfHealable: catchAnalysis.selfHealable, suggestion: catchAnalysis.suggestion },
                 provider: executor.provider,
                 model,
                 executionTimeMs: Date.now() - streamStartTime,
@@ -481,7 +573,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
         name: activeStreams[i]?.name ?? 'unknown',
         status: 'failed',
         error: err.message ?? String(err),
-        errorDetail: { category: 'unknown', retryable: true, suggestion: 'Check orchestrator logs' },
+        errorDetail: { category: 'unknown', retryable: true, selfHealable: false, suggestion: 'Check orchestrator logs' },
         tokensUsed: { input: 0, output: 0 },
     })));
     // Promise.allSettled — one failure doesn't kill the wave
@@ -496,13 +588,13 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
         }
         else {
             const rejectedError = result.reason?.message ?? 'Unknown error';
-            const rejectedAnalysis = analyzeError(rejectedError);
+            const rejectedAnalysis = analyzeError(rejectedError, 'transport');
             streamResults.push({
                 id: 'unknown',
                 name: 'unknown',
                 status: 'failed',
                 error: rejectedError,
-                errorDetail: { category: rejectedAnalysis.category, retryable: rejectedAnalysis.retryable, suggestion: rejectedAnalysis.suggestion },
+                errorDetail: { category: rejectedAnalysis.category, retryable: rejectedAnalysis.retryable, selfHealable: rejectedAnalysis.selfHealable, suggestion: rejectedAnalysis.suggestion },
             });
         }
     }
@@ -578,7 +670,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                 .join('\n')
                 || 'unknown error';
             const errorSummary = `Verify failed: ${failed.command}: ${verifyError.slice(0, 500)}`;
-            const verifyAnalysis = analyzeError(verifyError);
+            const verifyAnalysis = analyzeError(verifyError, 'verify');
             verifyDetails.push(`${sr.id}: ${errorSummary}`);
             await updateStreamStatus(projectDir, sr.id, 'failed', errorSummary);
             await logger.error('verify_failed', {
@@ -588,9 +680,20 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
                 error: verifyError.slice(0, 1000),
                 isolated: otherBackups.length > 0,
             });
+            // Rollback file changes for failed verify — prevents leaving orphan files on disk
+            const streamBackup = successBackups.find(b => b.streamId === sr.id);
+            if (streamBackup) {
+                try {
+                    await revertStreamBackup(projectDir, streamBackup);
+                    await logger.info('verify_rollback', { stream: sr.id, files: streamBackup.entries.length + streamBackup.createdFiles.length });
+                }
+                catch (rollbackErr) {
+                    await logger.warn('verify_rollback_failed', { stream: sr.id, error: rollbackErr.message });
+                }
+            }
             sr.status = 'failed';
             sr.error = errorSummary;
-            sr.errorDetail = { category: verifyAnalysis.category, retryable: verifyAnalysis.retryable, suggestion: verifyAnalysis.suggestion };
+            sr.errorDetail = { category: verifyAnalysis.category, retryable: verifyAnalysis.retryable, selfHealable: verifyAnalysis.selfHealable, suggestion: verifyAnalysis.suggestion };
         }
         else {
             verifyPassed++;
@@ -621,15 +724,41 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
             });
         }
     }
+    // 7a. CIRCUIT BREAKER — detect systemic wave-level failures
+    const circuitBreaker = checkWaveCircuitBreaker(streamResults);
+    if (circuitBreaker.tripped) {
+        const firstFailedError = streamResults.find(sr => sr.status === 'failed')?.error;
+        log.warn({
+            category: circuitBreaker.category,
+            failedCount: circuitBreaker.failedCount,
+            totalCount: circuitBreaker.totalCount,
+            firstError: firstFailedError?.slice(0, 500),
+        }, 'circuit_breaker_tripped');
+        const cbManifest = await loadManifest(projectDir);
+        cbManifest.status = 'circuit_breaker';
+        await saveManifest(projectDir, cbManifest);
+    }
     // 7a. SELF-HEAL — generate fix streams for failed streams (tier-gated)
     const fixStreamsGenerated = [];
     const currentManifest = await loadManifest(projectDir);
-    const tier = getTier(config.tier ?? 'free');
-    if (tier.selfHealing === 'full') {
+    const effectiveTierId = config.mode === 'cloud' && config.apiKey
+        ? getEffectiveTier({
+            tier: config.tier ?? 'free',
+            createdAt: config.accountCreatedAt ?? new Date().toISOString(),
+            trialRunsRemaining: config.trialRunsRemaining ?? 0,
+        })
+        : (config.tier ?? 'free');
+    const tier = getEffectiveLimits(effectiveTierId, null);
+    // Circuit breaker blocks self-healing only for non-selfHealable categories (infra failures).
+    // When all streams fail with a selfHealable category (code errors), fix streams are still useful.
+    const cbBlocksHealing = circuitBreaker.tripped && !(circuitBreaker.selfHealable ?? false);
+    if (tier.selfHealing === 'full' && !cbBlocksHealing) {
         for (const sr of streamResults) {
             if (sr.status !== 'failed' || sr.id === 'unknown')
                 continue;
-            const fixResult = generateFixStream(currentManifest, sr.id);
+            // Pass the in-memory errorDetail (computed with origin hint) so generateFixStream
+            // can use the correct selfHealable flag rather than re-analyzing without origin.
+            const fixResult = generateFixStream(currentManifest, sr.id, sr.errorDetail);
             if (fixResult) {
                 await addStream(projectDir, fixResult.fixStreamId, fixResult.fixStream);
                 fixStreamsGenerated.push(fixResult.fixStreamId);
@@ -662,7 +791,7 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
     }
     // 8. REPORT — check for remaining waves
     const finalManifest = await loadManifest(projectDir);
-    const { waves: remainingWaves } = calculateWaves(finalManifest);
+    const { waves: remainingWaves } = calculateWaves(finalManifest, projectDir);
     const done = remainingWaves.length === 0;
     const hasCompleted = streamResults.some((s) => s.status === 'complete');
     const completedCount = streamResults.filter((s) => s.status === 'complete').length;
@@ -694,6 +823,36 @@ async function executeWaveInternal(projectDir, executor, options, logger) {
             // Learning is best-effort
             log.warn({ err }, 'learning_cycle_failed');
         }
+        // 8c. PATTERN DETECTION (L2) — analyze reports every 5 runs
+        try {
+            const { detectPatterns, savePatterns, adaptReport } = await import('./intelligence/index.js');
+            const reportsDir = path.join(projectDir, '.orchex', 'reports');
+            const reportFiles = await fs.readdir(reportsDir).catch(() => []);
+            if (reportFiles.length > 0 && reportFiles.length % 5 === 0) {
+                const reports = [];
+                for (const file of reportFiles) {
+                    if (!file.endsWith('.json'))
+                        continue;
+                    try {
+                        const content = await fs.readFile(path.join(reportsDir, file), 'utf-8');
+                        const canonical = JSON.parse(content);
+                        reports.push(adaptReport(canonical));
+                    }
+                    catch { /* skip invalid */ }
+                }
+                if (reports.length >= 5) {
+                    const patterns = detectPatterns(reports);
+                    if (patterns.length > 0) {
+                        await savePatterns(projectDir, patterns);
+                        log.info({ patternCount: patterns.length }, 'patterns_detected');
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // Non-fatal — don't fail execution for pattern detection errors
+            log.warn({ err }, 'pattern_detection_error');
+        }
     }
     // Clean up disk backups after wave completion (all verify/isolation done)
     for (const backup of successBackups) {

package/dist/setup/ide-registry.d.ts

@@ -0,0 +1,13 @@
+export interface IdeConfig {
+    name: string;
+    slug: string;
+    detect: (projectDir: string) => boolean;
+    configPath: (projectDir: string) => string;
+    scope: 'project' | 'global';
+}
+export declare const IDE_REGISTRY: IdeConfig[];
+export declare function detectIdes(projectDir: string): IdeConfig[];
+export declare function findBySlug(slug: string): IdeConfig | undefined;
+export declare function FALLBACK_CONFIG_PATH(projectDir: string): string;
+export declare function generateMcpConfig(): Record<string, unknown>;
+export declare function mergeConfig(existing: Record<string, unknown>, orchexEntry: Record<string, unknown>): Record<string, unknown>;

package/dist/setup/ide-registry.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const IDE_REGISTRY = [
+    {
+        name: 'Cursor',
+        slug: 'cursor',
+        detect: (projectDir) => {
+            return Boolean(process.env.CURSOR_TRACE_DIR) || fs.existsSync(path.join(projectDir, '.cursor'));
+        },
+        configPath: (projectDir) => path.join(projectDir, '.cursor/mcp.json'),
+        scope: 'project'
+    },
+    {
+        name: 'Windsurf',
+        slug: 'windsurf',
+        detect: (projectDir) => {
+            return Boolean(process.env.WINDSURF_SESSION_ID) || fs.existsSync(path.join(os.homedir(), '.codeium'));
+        },
+        configPath: (projectDir) => path.join(os.homedir(), '.codeium/windsurf/mcp_config.json'),
+        scope: 'global'
+    }
+];
+export function detectIdes(projectDir) {
+    return IDE_REGISTRY.filter(ide => ide.detect(projectDir));
+}
+export function findBySlug(slug) {
+    return IDE_REGISTRY.find(ide => ide.slug === slug);
+}
+export function FALLBACK_CONFIG_PATH(projectDir) {
+    return path.join(projectDir, '.mcp.json');
+}
+export function generateMcpConfig() {
+    return {
+        mcpServers: {
+            orchex: {
+                command: 'npx',
+                args: ['-y', '@wundam/orchex']
+            }
+        }
+    };
+}
+export function mergeConfig(existing, orchexEntry) {
+    return {
+        ...existing,
+        mcpServers: {
+            ...(existing.mcpServers || {}),
+            orchex: orchexEntry
+        }
+    };
+}

package/dist/setup/index.d.ts

@@ -0,0 +1 @@
+export declare function handleSetupCommand(args: string[], projectDir?: string): Promise<void>;