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

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { StreamDefinitionSchema } from './types.js';
-import { analyzeError } from './intelligence/error-analyzer.js';
+import { analyzeError, evaluateCompletion, DEFAULT_THRESHOLDS, categorizeStream, getRecommendedLimit, getThresholds, createDetector, generateAllSuggestions, getSuggestionsSummary, parsePlanDocument, getSectionsAtLevel, isUnpopulatedTemplate, createDiagnostics, detectOwnershipConflicts, autoMergeOwnershipConflicts, extractDeliverables, processDeliverables, formatDeliverablesReport, buildDependencyGraph, formatDependencyReport, generateStreams, formatStreamsForReview, toInitFormat, extractPrerequisites, } from './intelligence/index.js';
 import { initOrchestration, loadManifest, saveManifest, updateStreamStatus, addStream, archiveOrchestration, manifestExists, recoverStuckStreams, } from './manifest.js';
 import { createLogger } from './logger.js';
 import { createLogger as createPinoLogger } from './logging.js';
@@ -11,19 +11,11 @@ import { createExecutor, getProviderStatus } from './executors/index.js';
 import { broadcaster } from './execution-broadcaster.js';
 import { calculateRunCost } from './cost.js';
 import { circuitBreakers } from './executors/circuit-breaker.js';
-import { getTier } from './tiers.js';
+import { getTier, getEffectiveLimits, TRIAL_WINDOW_DAYS } from './tiers.js';
 import { checkTierLimits, getWaveCountWarning } from './tier-gating.js';
-import { loadConfig, validateCloudConfig, getConfiguredProvider } from './config.js';
-import { DEFAULT_THRESHOLDS, categorizeStream, getRecommendedLimit, getThresholds, } from './intelligence/learning-engine.js';
-import { createDetector, } from './intelligence/anti-pattern-detector.js';
-import { generateAllSuggestions, getSuggestionsSummary, } from './intelligence/split-suggester.js';
-// Phase 8B-B: Plan-to-Streams imports
-import { parsePlanDocument, getSectionsAtLevel, isUnpopulatedTemplate } from './intelligence/plan-parser.js';
-import { createDiagnostics, detectOwnershipConflicts } from './intelligence/diagnostics.js';
-import { extractDeliverables, processDeliverables, formatDeliverablesReport, } from './intelligence/deliverable-extractor.js';
-import { buildDependencyGraph, formatDependencyReport, } from './intelligence/dependency-inferrer.js';
-import { generateStreams, formatStreamsForReview, toInitFormat, extractPrerequisites, } from './intelligence/stream-generator.js';
+import { loadConfig, validateCloudConfig, validateCloudProvider, getConfiguredProvider, getProviderApiKey } from './config.js';
 import * as fs from 'fs/promises';
+import * as path from 'path';
 /**
  * Analyze stream definitions for potential budget issues.
  * Uses learned thresholds (LE.3) to warn about streams that may exceed limits.
@@ -161,24 +153,57 @@ async function withToolLogging(toolName, params, fn) {
         return fail(`Tool "${toolName}" failed: ${err.message ?? String(err)}`, { code: 'TOOL_INTERNAL_ERROR', retryable: true, suggestion: 'Retry the operation or check execution logs.' });
     }
 }
+/** Resolve promotion-aware tier limits for the current user. */
+async function resolveUserTier(context) {
+    // Cloud mode: server is authoritative, use existing promotion-based resolution
+    if (context?.promotionStore) {
+        const tierId = context.userTier ?? 'free';
+        const promotion = await context.promotionStore.getActiveByUserId(context.userId);
+        return getEffectiveLimits(tierId, promotion);
+    }
+    // Local mode: load config for tier info when no ToolContext
+    let configTier = context?.userTier ?? 'free';
+    let configCreatedAt = context?.userCreatedAt;
+    let configTrialRuns = 0;
+    if (!context) {
+        try {
+            const { loadConfig } = await import('./config.js');
+            const config = await loadConfig();
+            configTier = config.tier ?? 'free';
+            configCreatedAt = config.accountCreatedAt;
+            configTrialRuns = config.trialRunsRemaining ?? 0;
+        }
+        catch {
+            // Config load failed — fall through with defaults
+        }
+    }
+    // Try JWT entitlement first, fall back to config tier
+    try {
+        const { resolveEntitledTier, loadPublicKey } = await import('./entitlements/resolve.js');
+        const publicKey = await loadPublicKey();
+        return resolveEntitledTier({
+            tier: configTier,
+            accountCreatedAt: configCreatedAt,
+            trialRunsRemaining: configTrialRuns,
+        }, publicKey);
+    }
+    catch {
+        return getTier(configTier);
+    }
+}
 const FREE_LEARN_LIMIT = 3;
-const FREE_LEARN_TRIAL_DAYS = 30;
-function checkLearnAccess(ctx) {
-    const tier = getTier(ctx.userTier);
-    // Paid tiers with smartPlanning enabled — always allowed
+async function checkLearnAccess(ctx) {
+    const tier = await resolveUserTier(ctx);
+    // Paid tiers (including trial users who resolve to 'pro') — always allowed
     if (tier.smartPlanning === 'full') {
         return { allowed: true };
     }
-    // Free tier (smartPlanning === 'none') — apply trial logic
-    const accountAgeDays = (Date.now() - new Date(ctx.userCreatedAt).getTime()) / (1000 * 60 * 60 * 24);
-    if (accountAgeDays > FREE_LEARN_TRIAL_DAYS) {
-        return {
-            allowed: false,
-            error: `Free trial expired. Your account is ${Math.floor(accountAgeDays)} days old (trial: ${FREE_LEARN_TRIAL_DAYS} days).`,
-            suggestion: 'Upgrade to Pro ($19/mo) for unlimited learn calls: /pricing',
-        };
-    }
-    return { allowed: true };
+    // Free tier (post-trial or never-trial) — not allowed
+    return {
+        allowed: false,
+        error: 'Learn requires a Pro or higher plan.',
+        suggestion: 'Upgrade to Pro ($19/mo) for learn and smart planning: /pricing',
+    };
 }
 // ============================================================================
 // Plan Template Generator
@@ -313,6 +338,7 @@ export function registerTools(server, executor, context) {
     server.registerTool('init', {
         title: 'Initialize Orchestration',
         description: 'Initialize a new orchestration for a feature. Creates .orchex/active/manifest.yaml with streams.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: {
             feature: z.string().describe('Feature name (e.g., "user-authentication")'),
             streams: z
@@ -324,7 +350,7 @@ export function registerTools(server, executor, context) {
         return withToolLogging('init', { feature, streamCount: Object.keys(streams).length }, async () => {
             const projectDir = resolveProjectDir(project_dir);
             // Use cloud tier if available, otherwise default to 'free' (local MCP mode)
-            const tier = getTier(context?.userTier ?? 'free');
+            const tier = await resolveUserTier(context);
             // Enforce tier limits (waves, providers, etc) for this orchestration
             const tierLimitResult = checkTierLimits({
                 tier,
@@ -404,6 +430,7 @@ export function registerTools(server, executor, context) {
     server.registerTool('add_stream', {
         title: 'Add Stream',
         description: 'Add a new stream to the active orchestration.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: {
             id: z.string().describe('Unique stream ID'),
             name: z.string().describe('Human-readable stream name'),
@@ -471,6 +498,7 @@ export function registerTools(server, executor, context) {
     server.registerTool('status', {
         title: 'Orchestration Status',
         description: 'Get the current orchestration status and progress.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             project_dir: z.string().optional().describe('Project directory'),
         },
@@ -478,6 +506,33 @@ export function registerTools(server, executor, context) {
         return withToolLogging('status', {}, async () => {
             const projectDir = resolveProjectDir(project_dir);
             if (!(await manifestExists(projectDir))) {
+                // Check if auto-plan generation is in progress
+                try {
+                    const autoPlanPath = path.join(projectDir, '.orchex', 'active', 'auto-plan-result.json');
+                    const raw = await fs.readFile(autoPlanPath, 'utf-8');
+                    const autoPlanResult = JSON.parse(raw);
+                    if (autoPlanResult.status === 'generating') {
+                        return ok('Auto-plan generation in progress.', {
+                            autoPlan: { status: 'generating', intent: autoPlanResult.intent, startedAt: autoPlanResult.startedAt },
+                            hint: 'Call auto again to check if the plan is ready.',
+                        });
+                    }
+                    if (autoPlanResult.status === 'complete') {
+                        return ok('Auto-plan ready. Call auto again to review or approve.', {
+                            autoPlan: { status: 'complete', message: autoPlanResult.message },
+                            hint: 'Call auto with approve: true to execute.',
+                        });
+                    }
+                    if (autoPlanResult.status === 'failed') {
+                        return fail(`Auto-plan generation failed: ${autoPlanResult.error}`, {
+                            code: 'AUTO_PLAN_FAILED', retryable: true,
+                            suggestion: 'Call auto again to retry.',
+                        });
+                    }
+                }
+                catch {
+                    // No auto-plan file — normal "no orchestration" case
+                }
                 return fail('No active orchestration found.', {
                     code: 'NO_ACTIVE_ORCHESTRATION', retryable: false, suggestion: 'Run init to create an orchestration first.',
                 });
@@ -571,8 +626,8 @@ export function registerTools(server, executor, context) {
                 }
             }
             // Use cloud tier if available, otherwise default to 'free' (local MCP mode)
-            const tier = getTier(context?.userTier ?? 'free');
-            return ok(`Orchestration: "${manifest.feature}"`, {
+            const tier = await resolveUserTier(context);
+            const responseData = {
                 feature: manifest.feature,
                 status: manifest.status,
                 progress: { completed, failed, total, percentage: Math.round((completed / total) * 100) },
@@ -597,7 +652,14 @@ export function registerTools(server, executor, context) {
                     maxWaves: tier.maxWaves,
                     maxProviders: tier.maxProviders,
                 },
-            });
+            };
+            if (manifest.status === 'circuit_breaker') {
+                responseData.circuitBreaker = {
+                    status: 'paused',
+                    hint: 'Fix the root cause, then run recover with include_failed: true to resume.',
+                };
+            }
+            return ok(`Orchestration: "${manifest.feature}"`, responseData);
         });
     });
     // --------------------------------------------------------------------------
@@ -608,6 +670,7 @@ export function registerTools(server, executor, context) {
         description: 'Run the orchestration. Each call executes one wave of streams in parallel via LLM API, ' +
             'applies artifacts to the codebase, and runs verification commands. ' +
             'Call repeatedly for each wave, or use auto mode.',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         inputSchema: {
             mode: z.enum(['auto', 'wave']).optional().default('wave')
                 .describe('auto: execute all waves sequentially. wave: execute one wave and return.'),
@@ -617,9 +680,13 @@ export function registerTools(server, executor, context) {
                 .describe('Preview without executing (default: false)'),
             model: z.string().optional()
                 .describe('LLM model override (auto-detected based on provider)'),
+            iterate: z.boolean().optional().default(false)
+                .describe('When true with mode=auto, re-plan and re-execute if failures remain. Max 3 iterations.'),
+            max_iterations: z.number().optional().default(3)
+                .describe('Maximum iterations for iterative mode (default: 3, max: 5).'),
             project_dir: z.string().optional().describe('Project directory'),
         },
-    }, async ({ mode, wave: waveNum, dry_run, model, project_dir }) => {
+    }, async ({ mode, wave: waveNum, dry_run, model, iterate, max_iterations, project_dir }) => {
         return withToolLogging('execute', { mode, wave: waveNum, dry_run }, async () => {
             const projectDir = resolveProjectDir(project_dir);
             if (!(await manifestExists(projectDir))) {
@@ -627,6 +694,22 @@ export function registerTools(server, executor, context) {
                     code: 'NO_ACTIVE_ORCHESTRATION', retryable: false, suggestion: 'Run init to create an orchestration first.',
                 });
             }
+            const executeManifest = await loadManifest(projectDir);
+            if (executeManifest.status === 'circuit_breaker') {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Orchestration paused by circuit breaker. Fix the root cause, then run recover with include_failed: true to resume.',
+                                data: {
+                                    status: 'circuit_breaker',
+                                    hint: 'Use orchex.recover(include_failed: true) after fixing the issue.',
+                                },
+                            }),
+                        }],
+                };
+            }
             // Create executor (use injected one if provided, otherwise check config)
             let exec;
             if (executor) {
@@ -643,6 +726,13 @@ export function registerTools(server, executor, context) {
                             suggestion: 'Set your API key: orchex config --staging --api-key <key>',
                         });
                     }
+                    const providerError = validateCloudProvider(config);
+                    if (providerError) {
+                        return fail(providerError, {
+                            code: 'CLOUD_PROVIDER_UNSUPPORTED', retryable: false,
+                            suggestion: 'Switch to Anthropic: orchex config --provider anthropic',
+                        });
+                    }
                     try {
                         const { CloudExecutor } = await import('./cloud-executor.js');
                         exec = new CloudExecutor(config.apiUrl, config.apiKey);
@@ -684,16 +774,23 @@ export function registerTools(server, executor, context) {
                     }
                 }
                 else {
-                    // Local mode: auto-detect provider from environment variables
+                    // Local mode: auto-detect provider from environment variables,
+                    // falling back to cached BYOK keys from login sync
                     try {
                         const provider = getConfiguredProvider(config);
-                        exec = createExecutor({ provider });
+                        let apiKey = getProviderApiKey(provider);
+                        // Fallback: cached BYOK key
+                        if (!apiKey && provider !== 'ollama' && provider !== 'bedrock') {
+                            const { getCachedApiKey } = await import('./key-cache.js');
+                            apiKey = await getCachedApiKey(provider);
+                        }
+                        exec = createExecutor({ provider, ...(apiKey ? { apiKey } : {}) });
                     }
                     catch (error) {
                         const status = getProviderStatus();
                         return fail(`Failed to create executor. ${status.message}`, {
                             code: 'EXECUTOR_CREATE_FAILED', retryable: false,
-                            suggestion: 'Set an API key for a supported provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, or OLLAMA_HOST).',
+                            suggestion: 'Set an API key for a supported provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, or OLLAMA_HOST), or store a key at orchex.dev/dashboard/keys and run `orchex login`.',
                         });
                     }
                 }
@@ -783,8 +880,69 @@ export function registerTools(server, executor, context) {
                             // Continue past failures — stop only when no runnable streams remain
                             done = result.done || !result.next;
                         }
+                        // Iterative execution: re-plan and retry if failures remain
+                        if (iterate && totalFailed > 0) {
+                            const maxIter = Math.min(max_iterations ?? 3, 5);
+                            let iteration = 1;
+                            while (iteration < maxIter) {
+                                const summaries = [...allStreamResults.values()].map(s => ({
+                                    id: s.id,
+                                    status: (s.status === 'complete' ? 'complete' : 'failed'),
+                                    verifyPassed: s.status === 'complete',
+                                    error: s.error,
+                                }));
+                                const decision = evaluateCompletion({
+                                    intent: manifest.feature,
+                                    streamResults: summaries,
+                                    iterationNumber: iteration,
+                                    maxIterations: maxIter,
+                                });
+                                if (decision.complete)
+                                    break;
+                                // Re-plan based on failures (uses auto-planner from P-AUTO)
+                                // This is a placeholder — requires P-AUTO's generatePlan() to be implemented
+                                iteration++;
+                                toolLog.info({ iteration, nextIntent: decision.nextIntent?.slice(0, 100) }, 'iteration_replanning');
+                            }
+                        }
                         broadcaster.unsubscribe(orchestrationId, progressListener);
-                        // Persist run to history store
+                        // Generate execution report first (so we have runId for history save)
+                        let report;
+                        try {
+                            const { generateReport, saveReportLocally } = await import('./intelligence/index.js');
+                            const { generateLearningSummary } = await import('./intelligence/index.js');
+                            const reportManifest = await loadManifest(projectDir);
+                            report = generateReport(reportManifest, [{
+                                    success: totalFailed === 0,
+                                    wave: { number: wavesCompleted, totalWaves: wavesCompleted },
+                                    streams: [...allStreamResults.values()],
+                                    verify: { passed: allStreamResults.size - totalFailed, failed: totalFailed },
+                                    done: true,
+                                }]);
+                            await saveReportLocally(projectDir, report);
+                            // Sync to cloud if locally authenticated (no ToolContext historyStore)
+                            if (!context?.historyStore) {
+                                try {
+                                    const { loadConfig } = await import('./config.js');
+                                    const { syncReportToCloud } = await import('./cloud-sync.js');
+                                    const syncConfig = await loadConfig();
+                                    await syncReportToCloud(syncConfig, report);
+                                }
+                                catch {
+                                    // Sync is best-effort
+                                }
+                            }
+                            const summary = generateLearningSummary(report);
+                            await logger.info('execution_report_saved', {
+                                runId: report.runId,
+                                qualityScore: report.planQualityScore,
+                                learningSummary: summary,
+                            });
+                        }
+                        catch {
+                            // Report generation is best-effort
+                        }
+                        // Persist run to history store (after report for runId)
                         if (context?.historyStore) {
                             try {
                                 const finalManifest = await loadManifest(projectDir);
@@ -805,6 +963,7 @@ export function registerTools(server, executor, context) {
                                 await context.historyStore.saveRun({
                                     userId: context.userId,
                                     organizationId: context.organizationId,
+                                    runId: report?.runId,
                                     feature: finalManifest.feature,
                                     status: totalFailed === 0 ? 'complete' : 'failed',
                                     streamCount: streamRecords.length,
@@ -879,38 +1038,67 @@ export function registerTools(server, executor, context) {
                         await logger.info('wave_cost', { wave: result.wave.number, costUsd: waveCost });
                     }
                     broadcaster.unsubscribe(orchestrationId, progressListener);
-                    // Persist run to history store on final wave or failure
-                    if (context?.historyStore && (result.done || !result.next)) {
+                    // Generate execution report first (for runId)
+                    if (result.done || !result.next) {
+                        let report;
                         try {
-                            const finalManifest = await loadManifest(projectDir);
-                            // Build lookup from current wave's execution results
-                            const waveResultMap = new Map(result.streams.map(sr => [sr.id, sr]));
-                            const streamRecords = Object.entries(finalManifest.streams).map(([sid, s]) => {
-                                const execResult = waveResultMap.get(sid);
-                                return {
-                                    streamId: sid,
-                                    name: s.name,
-                                    status: s.status,
-                                    waveNumber: finalManifest.waveAssignments?.[sid] ?? 0,
-                                    filesChanged: s.owns ?? [],
-                                    tokensInput: execResult?.tokensUsed?.input ?? 0,
-                                    tokensOutput: execResult?.tokensUsed?.output ?? 0,
-                                    provider: execResult?.provider,
-                                    model: execResult?.model,
-                                };
+                            const { generateReport, saveReportLocally } = await import('./intelligence/index.js');
+                            const { generateLearningSummary } = await import('./intelligence/index.js');
+                            const reportManifest = await loadManifest(projectDir);
+                            report = generateReport(reportManifest, [result]);
+                            await saveReportLocally(projectDir, report);
+                            if (!context?.historyStore) {
+                                try {
+                                    const { loadConfig } = await import('./config.js');
+                                    const { syncReportToCloud } = await import('./cloud-sync.js');
+                                    const syncConfig = await loadConfig();
+                                    await syncReportToCloud(syncConfig, report);
+                                }
+                                catch { /* Sync is best-effort */ }
+                            }
+                            const summary = generateLearningSummary(report);
+                            await logger.info('execution_report_saved', {
+                                runId: report.runId,
+                                qualityScore: report.planQualityScore,
+                                learningSummary: summary,
                             });
-                            await context.historyStore.saveRun({
-                                userId: context.userId,
-                                organizationId: context.organizationId,
-                                feature: finalManifest.feature,
-                                status: result.verify.failed === 0 ? 'complete' : 'failed',
-                                streamCount: streamRecords.length,
-                                waveCount: currentWave.number,
-                                startedAt: new Date().toISOString(),
-                            }, streamRecords);
                         }
-                        catch (err) {
-                            toolLog.warn({ err }, 'history_save_failed');
+                        catch {
+                            // Report generation is best-effort
+                        }
+                        // Persist to history store (after report for runId)
+                        if (context?.historyStore) {
+                            try {
+                                const finalManifest = await loadManifest(projectDir);
+                                const waveResultMap = new Map(result.streams.map(sr => [sr.id, sr]));
+                                const streamRecords = Object.entries(finalManifest.streams).map(([sid, s]) => {
+                                    const execResult = waveResultMap.get(sid);
+                                    return {
+                                        streamId: sid,
+                                        name: s.name,
+                                        status: s.status,
+                                        waveNumber: finalManifest.waveAssignments?.[sid] ?? 0,
+                                        filesChanged: s.owns ?? [],
+                                        tokensInput: execResult?.tokensUsed?.input ?? 0,
+                                        tokensOutput: execResult?.tokensUsed?.output ?? 0,
+                                        provider: execResult?.provider,
+                                        model: execResult?.model,
+                                    };
+                                });
+                                await context.historyStore.saveRun({
+                                    userId: context.userId,
+                                    organizationId: context.organizationId,
+                                    runId: report?.runId,
+                                    feature: finalManifest.feature,
+                                    status: result.verify.failed === 0 ? 'complete' : 'failed',
+                                    streamCount: streamRecords.length,
+                                    waveCount: currentWave.number,
+                                    startedAt: new Date().toISOString(),
+                                }, streamRecords);
+                            }
+                            catch (err) {
+                                toolLog.warn({ err }, 'history_save_failed');
+                            }
                         }
                     }
                     await logger.info('background_wave_completed', {
@@ -962,6 +1150,7 @@ export function registerTools(server, executor, context) {
     server.registerTool('complete', {
         title: 'Complete',
         description: 'Mark a stream as complete, or archive the entire orchestration.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             stream_id: z.string().optional().describe('Stream ID to mark complete'),
             archive: z.boolean().optional().default(false).describe('Archive the orchestration'),
@@ -1014,6 +1203,7 @@ export function registerTools(server, executor, context) {
     server.registerTool('recover', {
         title: 'Recover Stuck Streams',
         description: 'Recover streams stuck in in_progress state or failed state. Auto-detects stuck streams and resets them to pending for retry, or skips them.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             mode: z.enum(['retry', 'skip']).optional().default('retry')
                 .describe('retry: reset stuck streams to pending. skip: mark them as skipped.'),
@@ -1061,6 +1251,12 @@ export function registerTools(server, executor, context) {
                     await updateStreamStatus(projectDir, stream_id, 'skipped');
                     newStatus = 'skipped';
                 }
+                // Reset circuit_breaker status on recovery
+                const updatedManifest = await loadManifest(projectDir);
+                if (updatedManifest.status === 'circuit_breaker') {
+                    updatedManifest.status = 'pending';
+                    await saveManifest(projectDir, updatedManifest);
+                }
                 return ok(`Stream '${stream_id}' recovered (set to ${newStatus})`, {
                     stream_id,
                     status: newStatus,
@@ -1083,6 +1279,12 @@ export function registerTools(server, executor, context) {
                     }
                     changedIds = recoveredIds;
                 }
+                // Reset circuit_breaker status on recovery
+                const updatedManifest = await loadManifest(projectDir);
+                if (updatedManifest.status === 'circuit_breaker') {
+                    updatedManifest.status = 'pending';
+                    await saveManifest(projectDir, updatedManifest);
+                }
                 return ok(`Recovered ${changedIds.length} stuck stream(s): [${changedIds.join(', ')}]${mode === 'skip' ? ' (set to skipped)' : ''}`, {
                     recovered: changedIds,
                     status: mode === 'skip' ? 'skipped' : 'pending',
@@ -1095,7 +1297,8 @@ export function registerTools(server, executor, context) {
     // --------------------------------------------------------------------------
     server.registerTool('learn', {
         title: 'Learn from Plan',
-        description: 'Parse a planning document and generate stream definitions. Returns proposed streams for review before initialization.',
+        description: 'Parse a structured implementation plan into stream definitions. Internal pipeline stage — use auto for most workflows. Expects markdown with code deliverables, not PRDs or specs.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             document_path: z.string().describe('Path to the markdown planning document'),
             document_content: z.string().optional().describe('Plan document contents as string. When provided, used instead of reading document_path from disk. Useful for cloud mode where the server cannot access local files.'),
@@ -1106,28 +1309,26 @@ export function registerTools(server, executor, context) {
         },
     }, async ({ document_path, document_content, deliverable_level, prefix, validate_antipatterns, project_dir }) => {
         return withToolLogging('learn', { document_path }, async () => {
-            // Free trial gating (cloud mode only)
+            // Tier gating (both local and cloud modes)
             let learnCallsRemaining;
-            if (context) {
-                const access = checkLearnAccess(context);
-                if (!access.allowed) {
-                    return fail(access.error, {
-                        code: 'LEARN_TRIAL_EXPIRED',
+            const access = await checkLearnAccess(context);
+            if (!access.allowed) {
+                return fail(access.error, {
+                    code: 'LEARN_TRIAL_EXPIRED',
+                    retryable: false,
+                    suggestion: access.suggestion,
+                });
+            }
+            if (context?.userTier === 'free') {
+                const user = await context.userStore.getUserById(context.userId);
+                if (user && user.learnCallsCount >= FREE_LEARN_LIMIT) {
+                    return fail(`Free trial limit reached. You have used all ${FREE_LEARN_LIMIT} free learn calls.`, {
+                        code: 'LEARN_QUOTA_EXCEEDED',
                         retryable: false,
-                        suggestion: access.suggestion,
+                        suggestion: 'Upgrade to Pro ($19/mo) for unlimited learn calls: /pricing',
                     });
                 }
-                if (context.userTier === 'free') {
-                    const user = await context.userStore.getUserById(context.userId);
-                    if (user && user.learnCallsCount >= FREE_LEARN_LIMIT) {
-                        return fail(`Free trial limit reached. You have used all ${FREE_LEARN_LIMIT} free learn calls.`, {
-                            code: 'LEARN_QUOTA_EXCEEDED',
-                            retryable: false,
-                            suggestion: 'Upgrade to Pro ($19/mo) for unlimited learn calls: /pricing',
-                        });
-                    }
-                    learnCallsRemaining = user ? FREE_LEARN_LIMIT - user.learnCallsCount - 1 : undefined;
-                }
+                learnCallsRemaining = user ? FREE_LEARN_LIMIT - user.learnCallsCount - 1 : undefined;
             }
             const projectDir = resolveProjectDir(project_dir);
             const diagnostics = createDiagnostics();
@@ -1217,6 +1418,14 @@ export function registerTools(server, executor, context) {
                 projectDir,
                 diagnostics,
             });
+            // Sequential edit diagnostics (P2.13)
+            const { detectSequentialEdits } = await import('./intelligence/index.js');
+            const seqDiagnostics = detectSequentialEdits(result.streams);
+            if (seqDiagnostics.length > 0) {
+                for (const diag of seqDiagnostics) {
+                    diagnostics.warnings.push(`Sequential edit conflict: ${diag.suggestion}`);
+                }
+            }
             // Calculate waves from the generated streams
             const streamDefs = Object.fromEntries(Object.entries(result.streams).map(([id, s]) => [
                 id,
@@ -1234,22 +1443,27 @@ export function registerTools(server, executor, context) {
             ]));
             const { waves } = calculateWaves({ feature: plan.title, streams: streamDefs, status: 'pending', created: new Date().toISOString() });
             // Warn if wave count approaches or exceeds tier limit
-            if (context) {
-                const tier = getTier(context.userTier);
+            {
+                const tier = await resolveUserTier(context);
                 const waveWarning = getWaveCountWarning(waves.length, tier);
                 if (waveWarning) {
                     diagnostics.warnings.push(waveWarning);
                 }
             }
-            // Extract prerequisites (e.g., package installs) from plan text
-            const initFormatStreams = toInitFormat(result);
-            // Check for cross-stream ownership conflicts
-            diagnostics.ownershipConflicts = detectOwnershipConflicts(result.streams);
-            if (diagnostics.ownershipConflicts.length > 0) {
-                for (const conflict of diagnostics.ownershipConflicts) {
-                    diagnostics.warnings.push(`Ownership conflict: ${conflict}`);
+            // Auto-merge ownership conflicts BEFORE toInitFormat
+            const ownershipMerge = autoMergeOwnershipConflicts(result.streams);
+            if (ownershipMerge.merges.length > 0) {
+                result.streams = ownershipMerge.streams;
+                result.count = Object.keys(ownershipMerge.streams).length;
+                for (const msg of ownershipMerge.merges) {
+                    diagnostics.warnings.push(`Auto-merged: ${msg}`);
                 }
+                diagnostics.ownershipConflicts = [];
+            }
+            else {
+                diagnostics.ownershipConflicts = detectOwnershipConflicts(result.streams);
             }
+            const initFormatStreams = toInitFormat(result);
             const prerequisites = extractPrerequisites(initFormatStreams);
             // Build summary message
             let message = `Generated ${result.count} streams from "${plan.title}"`;
@@ -1303,13 +1517,14 @@ export function registerTools(server, executor, context) {
                 learnTrial: learnCallsRemaining !== undefined ? {
                     remaining: learnCallsRemaining,
                     limit: FREE_LEARN_LIMIT,
-                    trialDays: FREE_LEARN_TRIAL_DAYS,
+                    trialDays: TRIAL_WINDOW_DAYS,
                 } : undefined,
                 reports: {
                     deliverables: formatDeliverablesReport(rawDeliverables),
                     dependencies: formatDependencyReport(graph),
                     streams: formatStreamsForReview(result),
                 },
+                sequentialEditConflicts: seqDiagnostics.length > 0 ? seqDiagnostics : undefined,
                 diagnostics,
             });
         });
@@ -1319,7 +1534,8 @@ export function registerTools(server, executor, context) {
     // --------------------------------------------------------------------------
     server.registerTool('init-plan', {
         title: 'Generate Plan Template',
-        description: 'Generate an annotated markdown plan template that teaches users how to structure documents for orchex learn. Creates a starter plan file with inline comments explaining what the learn pipeline parses.',
+        description: 'Generate an annotated plan template for manual editing. Advanced workflow — use auto for most cases.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             feature_name: z.string().optional().default('my-feature').describe('Feature name for the plan (used in title and example stream IDs)'),
             output_path: z.string().optional().describe('Output file path. Defaults to docs/plans/YYYY-MM-DD-<feature>-plan.md'),
@@ -1358,11 +1574,552 @@ export function registerTools(server, executor, context) {
         });
     });
     // --------------------------------------------------------------------------
-    // 9. reload — Restart MCP server to pick up rebuilt code
+    // 10. auto — One-shot orchestration from intent (P-AUTO)
+    // --------------------------------------------------------------------------
+    /** Heartbeat interval during plan generation to keep MCP transport alive. */
+    const AUTO_HEARTBEAT_MS = 5_000;
+    /** File name for async auto-plan results in .orchex/active/ */
+    const AUTO_PLAN_RESULT_FILE = 'auto-plan-result.json';
+    server.registerTool('auto', {
+        title: 'Auto-Orchestrate',
+        description: 'Start here. Takes any input (intent, PRD, spec, bug report), generates an implementation plan, previews streams, and optionally executes. ' +
+            'The primary entry point for all orchestrations.',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+        inputSchema: {
+            intent: z.string().describe('What you want to build (e.g., "Add user authentication with JWT")'),
+            project_dir: z.string().optional().describe('Project directory (defaults to cwd)'),
+            provider: z.string().optional().describe('LLM provider override'),
+            model: z.string().optional().describe('LLM model override'),
+            approve: z.boolean().optional().default(false).describe('If true, execute immediately after preview. If false (default), return preview only.'),
+            approved_streams: z.array(z.string()).optional().describe('Stream IDs to approve for execution. Non-listed pending streams will be skipped. ' +
+                'Omit this parameter to approve all streams (default behavior).'),
+        },
+    }, async ({ intent, project_dir, provider: providerOverride, model: modelOverride, approve, approved_streams }) => {
+        return withToolLogging('auto', { intent, approve }, async () => {
+            const projectDir = resolveProjectDir(project_dir);
+            // 1. Create executor
+            let exec;
+            if (executor) {
+                exec = executor;
+            }
+            else {
+                const config = await loadConfig();
+                if (config.mode === 'cloud') {
+                    const validationError = validateCloudConfig(config);
+                    if (validationError) {
+                        return fail(validationError, { code: 'CLOUD_CONFIG_INVALID', retryable: false });
+                    }
+                    const providerError = validateCloudProvider(config);
+                    if (providerError) {
+                        return fail(providerError, {
+                            code: 'CLOUD_PROVIDER_UNSUPPORTED', retryable: false,
+                            suggestion: 'Switch to Anthropic: orchex config --provider anthropic',
+                        });
+                    }
+                    try {
+                        const { CloudExecutor } = await import('./cloud-executor.js');
+                        exec = new CloudExecutor(config.apiUrl, config.apiKey);
+                    }
+                    catch {
+                        return fail('Cloud mode requires the orchex server. Visit orchex.dev for details.', {
+                            code: 'CLOUD_NOT_AVAILABLE', retryable: false,
+                            suggestion: 'Cloud execution is not available in the local MCP package. Sign up at orchex.dev for cloud features, or use local mode with your own API key.',
+                        });
+                    }
+                }
+                else {
+                    const resolvedProvider = providerOverride
+                        ? providerOverride
+                        : getConfiguredProvider(await loadConfig());
+                    let autoApiKey = getProviderApiKey(resolvedProvider);
+                    // Fallback: cached BYOK key
+                    if (!autoApiKey && resolvedProvider !== 'ollama' && resolvedProvider !== 'bedrock') {
+                        const { getCachedApiKey } = await import('./key-cache.js');
+                        autoApiKey = await getCachedApiKey(resolvedProvider);
+                    }
+                    exec = createExecutor({ provider: resolvedProvider, ...(autoApiKey ? { apiKey: autoApiKey } : {}) });
+                }
+            }
+            // 1a. First-run detection
+            const { isFirstRun, getFirstRunSuggestion, markFirstRunComplete } = await import('./intelligence/index.js');
+            const firstRun = await isFirstRun(projectDir);
+            let firstRunHint = '';
+            if (firstRun) {
+                firstRunHint = '\n\n---\n' + getFirstRunSuggestion();
+            }
+            // 1b. Load pattern hints from execution history (L2)
+            const { loadPatterns, patternsToPromptHints } = await import('./intelligence/index.js');
+            const patterns = await loadPatterns(projectDir);
+            const patternHints = patternsToPromptHints(patterns);
+            // 2. Check for existing async plan result
+            const autoPlanPath = path.join(projectDir, '.orchex', 'active', AUTO_PLAN_RESULT_FILE);
+            let cachedPlan = null;
+            try {
+                const raw = await fs.readFile(autoPlanPath, 'utf-8');
+                cachedPlan = JSON.parse(raw);
+            }
+            catch {
+                // No cached plan — first call or already cleaned up
+            }
+            // If plan is still generating, return status
+            if (cachedPlan?.status === 'generating') {
+                // Stale detection: if older than 10 minutes, treat as failed
+                const startedAt = cachedPlan.startedAt;
+                if (startedAt && Date.now() - new Date(startedAt).getTime() > 600_000) {
+                    await fs.unlink(autoPlanPath).catch(() => { });
+                    // Fall through to start fresh generation
+                    cachedPlan = null;
+                }
+                else {
+                    return ok('Auto-plan generation in progress. Call status to check, or wait and call auto again.', {
+                        status: 'generating',
+                        intent: cachedPlan.intent,
+                        startedAt: cachedPlan.startedAt,
+                    });
+                }
+            }
+            // If plan is complete and not approved, return cached result
+            if (cachedPlan?.status === 'complete' && !approve) {
+                return ok(cachedPlan.message, {
+                    ...cachedPlan,
+                    hint: 'Call auto again with approve: true to execute this plan.',
+                });
+            }
+            // If plan failed, clear and allow retry
+            if (cachedPlan?.status === 'failed' && !approve) {
+                await fs.unlink(autoPlanPath).catch(() => { });
+                cachedPlan = null;
+            }
+            // Resolve tier BEFORE plan generation so we can pass stream budget to the LLM
+            const autoTier = await resolveUserTier(context);
+            const autoMaxStreams = autoTier.maxParallelAgents === -1 ? undefined : autoTier.maxParallelAgents;
+            // 3. Preview mode (approve: false) — generate plan asynchronously
+            if (!approve) {
+                // Ensure .orchex/active/ directory exists
+                await fs.mkdir(path.join(projectDir, '.orchex', 'active'), { recursive: true });
+                // Write generating status
+                await fs.writeFile(autoPlanPath, JSON.stringify({
+                    status: 'generating',
+                    intent,
+                    startedAt: new Date().toISOString(),
+                }, null, 2));
+                // Fire-and-forget: plan generation runs in background
+                (async () => {
+                    try {
+                        // Heartbeat for logging (informational, does not reset client timeout)
+                        const heartbeatInterval = setInterval(() => {
+                            try {
+                                server.server.sendLoggingMessage({
+                                    level: 'info',
+                                    data: { phase: 'plan-generation', status: 'in_progress', intent: intent.substring(0, 100) },
+                                    logger: 'orchex-auto',
+                                });
+                            }
+                            catch { /* ignore */ }
+                        }, AUTO_HEARTBEAT_MS);
+                        const { generatePlan: autoGeneratePlan } = await import('./intelligence/index.js');
+                        let planResult;
+                        try {
+                            planResult = await autoGeneratePlan(intent, projectDir, exec, {
+                                model: modelOverride,
+                                provider: exec.provider,
+                                maxStreams: autoMaxStreams,
+                                extraContext: patternHints || undefined,
+                            });
+                        }
+                        finally {
+                            clearInterval(heartbeatInterval);
+                        }
+                        // Learn pipeline
+                        const diagnostics = createDiagnostics();
+                        const plan = parsePlanDocument(planResult.planMarkdown);
+                        const rawDeliverables = extractDeliverables(plan, { diagnostics });
+                        const deliverables = processDeliverables(rawDeliverables);
+                        diagnostics.splitCount = deliverables.length - rawDeliverables.length;
+                        if (deliverables.length === 0) {
+                            await fs.writeFile(autoPlanPath, JSON.stringify({
+                                status: 'failed',
+                                error: 'Auto-plan produced no deliverables. Try a more specific intent.',
+                            }, null, 2));
+                            return;
+                        }
+                        const graph = buildDependencyGraph(deliverables, { diagnostics });
+                        const genResult = generateStreams(deliverables, graph, {
+                            validateAntiPatterns: true, projectDir, diagnostics,
+                        });
+                        const { detectSequentialEdits: detectSeq } = await import('./intelligence/index.js');
+                        const seqDiagnostics = detectSeq(genResult.streams);
+                        const { classifyTask, suggestProvider } = await import('./intelligence/index.js');
+                        const rawInitStreams = toInitFormat(genResult);
+                        // Auto-merge ownership conflicts BEFORE model routing
+                        const mergeResult = autoMergeOwnershipConflicts(rawInitStreams);
+                        const initStreams = mergeResult.streams;
+                        if (mergeResult.merges.length > 0) {
+                            for (const msg of mergeResult.merges) {
+                                diagnostics.warnings.push(`Auto-merged: ${msg}`);
+                            }
+                            try {
+                                server.server.sendLoggingMessage({
+                                    level: 'info',
+                                    data: { phase: 'ownership-merge', merges: mergeResult.merges },
+                                    logger: 'orchex-auto',
+                                });
+                            }
+                            catch { /* ignore */ }
+                        }
+                        for (const [, stream] of Object.entries(initStreams)) {
+                            const owns = stream.owns ?? [];
+                            let totalOwnedLines = 0;
+                            for (const fp of owns) {
+                                try {
+                                    const content = await fs.readFile(path.join(projectDir, fp), 'utf-8');
+                                    totalOwnedLines += content.split('\n').length;
+                                }
+                                catch {
+                                    totalOwnedLines += 100;
+                                }
+                            }
+                            const chars = classifyTask(stream.plan ?? '', owns, totalOwnedLines);
+                            const sug = suggestProvider(chars);
+                            if (sug.provider && sug.confidence >= 0.5) {
+                                stream.suggestedProvider = sug.provider;
+                            }
+                        }
+                        const streamDefs = Object.fromEntries(Object.entries(initStreams).map(([id, s]) => [id, {
+                                name: s.name, deps: s.deps || [], owns: s.owns || [],
+                                reads: s.reads || [], setup: [], plan: s.plan,
+                                verify: s.verify || [], status: 'pending', attempts: 0,
+                            }]));
+                        const { waves } = calculateWaves({
+                            feature: plan.title, streams: streamDefs,
+                            status: 'pending', created: new Date().toISOString(),
+                        });
+                        const { formatPlanPreview, estimatePlannedCost } = await import('./intelligence/index.js');
+                        const waveList = waves.map(w => ({ number: w.number, streams: w.streams.map(s => s.id) }));
+                        const allWarnings = [...genResult.warnings, ...diagnostics.warnings];
+                        // Validate models for each stream and build model decisions map
+                        const { resolveModel } = await import('./model-validator.js');
+                        const { resolveApiUrl, loadConfig, DEFAULT_MODELS } = await import('./config.js');
+                        const toolConfig = await loadConfig();
+                        const toolApiUrl = toolConfig.mode === 'cloud' && toolConfig.apiKey ? await resolveApiUrl() : undefined;
+                        const modelDecisions = {};
+                        for (const [id, stream] of Object.entries(initStreams)) {
+                            const suggestedProvider = stream.suggestedProvider ?? exec.provider;
+                            const suggestedModel = modelOverride ?? DEFAULT_MODELS[suggestedProvider] ?? suggestedProvider;
+                            const validation = await resolveModel(suggestedProvider, suggestedModel, toolApiUrl);
+                            // Estimate cost
+                            const ownedLines = (stream.owns ?? []).length * 100;
+                            const costEstimate = estimatePlannedCost(ownedLines * 4, validation.resolvedModel);
+                            modelDecisions[id] = {
+                                provider: suggestedProvider,
+                                model: validation.resolvedModel,
+                                estimatedCostUsd: costEstimate.finalCost,
+                                fallback: validation.wasFallback ? `${validation.originalModel} → ${validation.resolvedModel}` : undefined,
+                            };
+                        }
+                        const preview = formatPlanPreview(initStreams, waveList, allWarnings, seqDiagnostics, modelDecisions);
+                        const message = `Auto-plan generated: "${plan.title}" — ${preview.summary.streamCount} streams in ${preview.summary.waveCount} waves. Call auto again with approve: true to execute.`;
+                        await fs.writeFile(autoPlanPath, JSON.stringify({
+                            status: 'complete',
+                            message,
+                            planMarkdown: planResult.planMarkdown,
+                            planTokensUsed: planResult.tokensUsed,
+                            preview,
+                            streams: initStreams,
+                            waves: waveList,
+                            warnings: allWarnings.length > 0 ? allWarnings : undefined,
+                            sequentialEditConflicts: seqDiagnostics.length > 0 ? seqDiagnostics : undefined,
+                            diagnostics,
+                        }, null, 2));
+                        // Notify completion
+                        try {
+                            server.server.sendLoggingMessage({
+                                level: 'info',
+                                data: { phase: 'plan-generation', status: 'complete', title: plan.title, streams: preview.summary.streamCount },
+                                logger: 'orchex-auto',
+                            });
+                        }
+                        catch { /* ignore */ }
+                    }
+                    catch (err) {
+                        await fs.writeFile(autoPlanPath, JSON.stringify({
+                            status: 'failed',
+                            error: err.message,
+                        }, null, 2)).catch(() => { });
+                    }
+                })();
+                return ok('Auto-plan generation started in background. Call auto again (or use status) to check progress.', {
+                    status: 'generating',
+                    intent,
+                    hint: 'Plan generation takes 10-60s depending on project size. Call auto again to get the result.',
+                });
+            }
+            // 4. Approve mode — load cached plan or generate synchronously
+            let planTitle;
+            let planMarkdown;
+            let initStreams;
+            let streamDefs;
+            if (cachedPlan?.status === 'complete') {
+                // Use cached plan from async generation
+                planTitle = parsePlanDocument(cachedPlan.planMarkdown).title;
+                planMarkdown = cachedPlan.planMarkdown;
+                initStreams = cachedPlan.streams;
+                // Auto-merge ownership conflicts from cached plan
+                const mergeResult = autoMergeOwnershipConflicts(initStreams);
+                initStreams = mergeResult.streams;
+                streamDefs = Object.fromEntries(Object.entries(initStreams).map(([id, s]) => [id, {
+                        name: s.name, deps: s.deps || [], owns: s.owns || [],
+                        reads: s.reads || [], setup: [], plan: s.plan ?? '',
+                        verify: s.verify || [], status: 'pending', attempts: 0,
+                    }]));
+                // Clean up cached result
+                await fs.unlink(autoPlanPath).catch(() => { });
+            }
+            else {
+                // No cached plan — generate synchronously (direct approve without preview)
+                const heartbeatInterval = setInterval(() => {
+                    try {
+                        server.server.sendLoggingMessage({
+                            level: 'info',
+                            data: { phase: 'plan-generation', status: 'in_progress', intent: intent.substring(0, 100) },
+                            logger: 'orchex-auto',
+                        });
+                    }
+                    catch { /* ignore */ }
+                }, AUTO_HEARTBEAT_MS);
+                const { generatePlan: autoGeneratePlan } = await import('./intelligence/index.js');
+                let planResult;
+                try {
+                    planResult = await autoGeneratePlan(intent, projectDir, exec, {
+                        model: modelOverride,
+                        provider: exec.provider,
+                        maxStreams: autoMaxStreams,
+                        extraContext: patternHints || undefined,
+                    });
+                }
+                catch (err) {
+                    return fail(`Auto-plan generation failed: ${err.message}`, {
+                        code: 'AUTO_PLAN_FAILED', retryable: true,
+                        suggestion: 'Check your LLM provider configuration and try again.',
+                    });
+                }
+                finally {
+                    clearInterval(heartbeatInterval);
+                }
+                const diagnostics = createDiagnostics();
+                const plan = parsePlanDocument(planResult.planMarkdown);
+                planTitle = plan.title;
+                planMarkdown = planResult.planMarkdown;
+                const rawDeliverables = extractDeliverables(plan, { diagnostics });
+                const deliverables = processDeliverables(rawDeliverables);
+                diagnostics.splitCount = deliverables.length - rawDeliverables.length;
+                if (deliverables.length === 0) {
+                    return fail('Auto-plan produced no deliverables. Try a more specific intent.', {
+                        code: 'NO_DELIVERABLES', retryable: true,
+                    });
+                }
+                const graph = buildDependencyGraph(deliverables, { diagnostics });
+                const genResult = generateStreams(deliverables, graph, {
+                    validateAntiPatterns: true, projectDir, diagnostics,
+                });
+                const { detectSequentialEdits: detectSeq, autoFixSequentialEdits: autoFixSeq } = await import('./intelligence/index.js');
+                const seqDiagnostics = detectSeq(genResult.streams);
+                if (seqDiagnostics.length > 0)
+                    autoFixSeq(genResult.streams);
+                initStreams = toInitFormat(genResult);
+                const syncMergeResult = autoMergeOwnershipConflicts(initStreams);
+                initStreams = syncMergeResult.streams;
+                streamDefs = Object.fromEntries(Object.entries(initStreams).map(([id, s]) => [id, {
+                        name: s.name, deps: s.deps || [], owns: s.owns || [],
+                        reads: s.reads || [], setup: [], plan: s.plan ?? '',
+                        verify: s.verify || [], status: 'pending', attempts: 0,
+                    }]));
+            }
+            // 5. Approved — init and execute all waves
+            if (await manifestExists(projectDir)) {
+                return fail('An active orchestration already exists. Complete or archive it first.', {
+                    code: 'ACTIVE_ORCHESTRATION_EXISTS', retryable: false,
+                    suggestion: 'Run orchex.complete(archive: true) to archive, then retry.',
+                });
+            }
+            // Tier checks
+            {
+                const tier = await resolveUserTier(context);
+                const limits = checkTierLimits({
+                    tier,
+                    streams: streamDefs,
+                    projectDir,
+                    mode: tier.cloudOrchestrations !== 0 ? 'cloud' : 'local',
+                });
+                if (!limits.allowed) {
+                    return fail(limits.error, {
+                        code: limits.code || 'TIER_LIMIT_EXCEEDED', retryable: false,
+                        suggestion: limits.suggestion,
+                    });
+                }
+            }
+            // Init orchestration
+            await initOrchestration(projectDir, planTitle, initStreams);
+            // Apply partial approval if approved_streams is specified
+            if (approved_streams !== undefined) {
+                const { applyPartialApproval } = await import('./intelligence/index.js');
+                await applyPartialApproval(projectDir, approved_streams);
+            }
+            // Execute all waves
+            const { generateReport, saveReportLocally } = await import('./intelligence/index.js');
+            const { generateLearningSummary } = await import('./intelligence/index.js');
+            const allResponses = [];
+            let done = false;
+            while (!done) {
+                const response = await executeWave(projectDir, exec, {
+                    model: modelOverride,
+                });
+                allResponses.push(response);
+                done = response.done;
+            }
+            // Generate execution report
+            const manifest = await loadManifest(projectDir);
+            const report = generateReport(manifest, allResponses);
+            await saveReportLocally(projectDir, report);
+            // Persist run to history store (server-side)
+            if (context?.historyStore) {
+                try {
+                    const allStreamResultsMap = new Map(allResponses.flatMap(r => r.streams).map(sr => [sr.id, sr]));
+                    const streamRecords = Object.entries(manifest.streams).map(([sid, s]) => {
+                        const execResult = allStreamResultsMap.get(sid);
+                        return {
+                            streamId: sid,
+                            name: s.name,
+                            status: s.status,
+                            waveNumber: manifest.waveAssignments?.[sid] ?? 0,
+                            filesChanged: s.owns ?? [],
+                            tokensInput: execResult?.tokensUsed?.input ?? 0,
+                            tokensOutput: execResult?.tokensUsed?.output ?? 0,
+                            provider: execResult?.provider,
+                            model: execResult?.model,
+                        };
+                    });
+                    const allComplete = Object.values(manifest.streams).every(s => s.status === 'complete');
+                    await context.historyStore.saveRun({
+                        userId: context.userId,
+                        organizationId: context.organizationId,
+                        runId: report.runId,
+                        feature: manifest.feature,
+                        status: allComplete ? 'complete' : 'failed',
+                        streamCount: streamRecords.length,
+                        waveCount: allResponses.length,
+                        startedAt: report.timestamp,
+                    }, streamRecords);
+                }
+                catch (err) {
+                    toolLog.warn({ err }, 'history_save_failed');
+                }
+            }
+            // Sync to cloud if locally authenticated
+            if (!context?.historyStore) {
+                try {
+                    const { loadConfig } = await import('./config.js');
+                    const { syncReportToCloud } = await import('./cloud-sync.js');
+                    const syncConfig = await loadConfig();
+                    await syncReportToCloud(syncConfig, report);
+                }
+                catch { /* Sync is best-effort */ }
+            }
+            const summary = generateLearningSummary(report);
+            if (firstRun) {
+                await markFirstRunComplete(projectDir);
+            }
+            return ok(`Orchestration complete: "${planTitle}"${firstRunHint}`, {
+                planMarkdown,
+                report: {
+                    runId: report.runId,
+                    planQualityScore: report.planQualityScore,
+                    totalStreams: report.totalStreams,
+                    totalWaves: report.totalWaves,
+                    tokenUsage: report.tokenUsage,
+                    waveEfficiency: report.waveEfficiency,
+                    failurePatterns: report.failurePatterns,
+                },
+                learningSummary: summary,
+                responses: allResponses,
+            });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // 11. reset-learning — Reset learning data (A11)
+    // --------------------------------------------------------------------------
+    server.registerTool('reset-learning', {
+        title: 'Reset Learning',
+        description: 'Reset learning data: thresholds, events, patterns, and/or reports.',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        inputSchema: {
+            confirm: z.boolean().describe('Must be true to proceed'),
+            patterns_only: z.boolean().optional().default(false).describe('Only reset patterns'),
+            reports_only: z.boolean().optional().default(false).describe('Only reset reports'),
+            project_dir: z.string().optional().describe('Project directory'),
+        },
+    }, async ({ confirm, patterns_only, reports_only, project_dir }) => {
+        return withToolLogging('reset-learning', { confirm, patterns_only, reports_only }, async () => {
+            const projectDir = resolveProjectDir(project_dir);
+            const { resetLearning } = await import('./intelligence/index.js');
+            try {
+                const result = await resetLearning(projectDir, {
+                    confirm,
+                    patternsOnly: patterns_only,
+                    reportsOnly: reports_only,
+                });
+                return ok(result.message, {
+                    deleted: result.deleted,
+                    totalDeleted: result.totalDeleted,
+                });
+            }
+            catch (err) {
+                return fail(err.message, {
+                    code: 'RESET_LEARNING_ERROR',
+                    retryable: false,
+                    suggestion: 'Use confirm: true to proceed.',
+                });
+            }
+        });
+    });
+    // --------------------------------------------------------------------------
+    // 12. rollback-stream — Revert file changes from a stream (P2.8)
+    // --------------------------------------------------------------------------
+    server.registerTool('rollback-stream', {
+        title: 'Rollback Stream',
+        description: 'Revert file changes made by a specific stream using git.',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        inputSchema: {
+            stream_id: z.string().describe('Stream ID to rollback'),
+            project_dir: z.string().optional().describe('Project directory'),
+        },
+    }, async ({ stream_id, project_dir }) => {
+        return withToolLogging('rollback-stream', { stream_id }, async () => {
+            const projectDir = resolveProjectDir(project_dir);
+            const manifest = await loadManifest(projectDir);
+            const stream = manifest.streams[stream_id];
+            if (!stream) {
+                return fail(`Stream '${stream_id}' not found`, {
+                    code: 'STREAM_NOT_FOUND', retryable: false,
+                });
+            }
+            const { rollbackStream } = await import('./intelligence/index.js');
+            const result = await rollbackStream(projectDir, stream_id, stream.owns ?? []);
+            if (result.errors.length > 0) {
+                return fail(`Rollback partial: ${result.errors.join('; ')}`, {
+                    code: 'ROLLBACK_PARTIAL', retryable: false,
+                });
+            }
+            return ok(`Rolled back ${result.reverted.length} file(s) for stream "${stream_id}"`, { reverted: result.reverted });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // 13. reload — Restart MCP server to pick up rebuilt code
     // --------------------------------------------------------------------------
     server.registerTool('reload', {
         title: 'Reload MCP Server',
         description: 'Restart the MCP server to pick up rebuilt code. MCP client will reconnect automatically.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {},
     }, async () => {
         setTimeout(() => process.exit(0), 100);