@visorcraft/idlehands 2.0.0 → 2.0.2

package/dist/anton/controller.js

@@ -4,17 +4,182 @@
  * Coordinates all components: parser, prompt, verifier, lock, git, session.
  * Structured as a deterministic orchestration flow for autonomous task execution.
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { isToolLoopBreak, AUTO_CONTINUE_PROMPT } from '../bot/auto-continue.js';
 import { ensureCleanWorkingTree, getWorkingDiff, commitAll, restoreTrackedChanges, cleanUntracked, createBranch, getUntrackedFiles, removeUntrackedFiles, } from '../git.js';
 import { estimateTokens } from '../utils.js';
 import { acquireAntonLock, releaseAntonLock, touchAntonLock } from './lock.js';
 import { parseTaskFile, findRunnablePendingTasks, markTaskChecked, insertSubTasks, autoCompleteAncestors, } from './parser.js';
-import { ensureAgentsTasksDir, makeUniqueTaskPlanFilename, buildDiscoveryPrompt, parseDiscoveryResult, buildRequirementsReviewPrompt, parseRequirementsReviewResult, ensurePlanFileExistsOrBootstrap, } from './preflight.js';
+import { ensureAgentsTasksDir, makeUniqueTaskPlanFilename, buildDiscoveryPrompt, parseDiscoveryResult, buildRequirementsReviewPrompt, parseRequirementsReviewResult, ensurePlanFileExistsOrBootstrap, FORCE_DISCOVERY_DECISION_PROMPT, FORCE_REVIEW_DECISION_PROMPT, } from './preflight.js';
 import { buildAntonPrompt, parseAntonResult, classifyTaskComplexity } from './prompt.js';
 import { formatDryRunPlan } from './reporter.js';
 import { classifyInfraError, ensureAntonRuntimeReady } from './runtime-ready.js';
 import { buildSessionConfig, buildPreflightConfig, buildDecomposeConfig, buildVerifyConfig, defaultCreateSession, } from './session.js';
 import { captureLintBaseline, detectVerificationCommands, runVerification } from './verifier.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// L2 Retry Enhancement Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract file paths mentioned in an L2 failure reason.
+ * Looks for patterns like: app/Models/Channel.php, src/foo/bar.ts, etc.
+ */
+function extractFilePathsFromL2Reason(reason) {
+    const patterns = [
+        // PHP/Laravel style: app/Models/Channel.php, app/Http/Controllers/Foo.php
+        /\b(app\/[\w\/]+\.php)\b/gi,
+        // General file paths with extensions
+        /\b((?:src|lib|tests?)\/[\w\/.-]+\.\w+)\b/gi,
+        // Model names that can be mapped to files: "Channel model" -> app/Models/Channel.php
+        /\b(\w+)\s+model\b/gi,
+    ];
+    const found = new Set();
+    for (const pattern of patterns) {
+        const matches = reason.matchAll(pattern);
+        for (const match of matches) {
+            const p = match[1];
+            // If it's a model name reference like "Channel model", convert to path
+            if (/model$/i.test(match[0]) && !/\.php$/i.test(p)) {
+                found.add(`app/Models/${p}.php`);
+            }
+            else {
+                found.add(p);
+            }
+        }
+    }
+    return [...found];
+}
+/**
+ * Detect if L2 reason indicates a "missing implementation" pattern.
+ * Returns true if the model wrote tests but forgot the actual implementation.
+ */
+function isL2MissingImplementation(reason) {
+    const missingPatterns = [
+        /missing\s+(?:from|in)\s+/i,
+        /no\s+(?:corresponding|evidence|actual)/i,
+        /relationship\s+(?:method\s+)?is\s+missing/i,
+        /but\s+(?:the|there['']?s?\s+no)/i,
+        /tests?\s+(?:expect|added|written).*but/i,
+        /should\s+be\s+(?:hasMany|hasOne|belongsTo|morphMany)/i,
+    ];
+    return missingPatterns.some((p) => p.test(reason));
+}
+function isRecoverablePreflightDiscoveryError(errMsg) {
+    return (/preflight-json-missing-object|preflight-discovery-invalid-status|preflight-discovery-invalid-filename|preflight-discovery-filename/i.test(errMsg) || /identical call repeated|breaking loop|tool\s+edit_range/i.test(errMsg));
+}
+function isRecoverablePreflightReviewError(errMsg) {
+    return /preflight-json-missing-object|preflight-review-invalid-status|preflight-review-invalid-filename|preflight-review-filename/i.test(errMsg);
+}
+/**
+ * Try to read a file's contents for injection into retry context.
+ * Returns null if file doesn't exist or is too large.
+ */
+function readFileForL2Injection(projectDir, filePath) {
+    const MAX_FILE_SIZE = 15000; // ~15KB, reasonable for injection
+    try {
+        const fullPath = path.resolve(projectDir, filePath);
+        if (!fs.existsSync(fullPath))
+            return null;
+        const stat = fs.statSync(fullPath);
+        if (stat.size > MAX_FILE_SIZE)
+            return null;
+        return fs.readFileSync(fullPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build enhanced retry context when L2 fails due to missing implementation.
+ * - On first L2 failure: Add strong guidance about which files to modify
+ * - On 2+ L2 failures: Inject the actual file contents so model can see what's missing
+ */
+function buildL2EnhancedRetryContext(l2Reason, l2FailCount, projectDir, taskText) {
+    const parts = [];
+    const filePaths = extractFilePathsFromL2Reason(l2Reason);
+    const isMissingImpl = isL2MissingImplementation(l2Reason);
+    if (!isMissingImpl || filePaths.length === 0) {
+        // Not a "missing implementation" pattern, no enhancement needed
+        return '';
+    }
+    parts.push('');
+    parts.push('═══════════════════════════════════════════════════════════════════════');
+    parts.push('⚠️  CRITICAL: AI REVIEW FAILED — MISSING IMPLEMENTATION DETECTED');
+    parts.push('═══════════════════════════════════════════════════════════════════════');
+    parts.push('');
+    parts.push(`The AI review found that you wrote tests but FORGOT THE ACTUAL IMPLEMENTATION.`);
+    parts.push(`Task: "${taskText}"`);
+    parts.push('');
+    parts.push('YOU MUST MODIFY THESE FILES:');
+    for (const fp of filePaths) {
+        parts.push(`  → ${fp}`);
+    }
+    parts.push('');
+    // After 2+ identical L2 failures, inject file contents
+    if (l2FailCount >= 2) {
+        parts.push('Since you have failed this verification multiple times, here are the current');
+        parts.push('contents of the files you need to modify:');
+        parts.push('');
+        for (const fp of filePaths) {
+            const contents = readFileForL2Injection(projectDir, fp);
+            if (contents !== null) {
+                parts.push(`┌─── ${fp} ───`);
+                parts.push(contents);
+                parts.push(`└─── end of ${fp} ───`);
+                parts.push('');
+            }
+            else {
+                parts.push(`[Could not read ${fp} — file may not exist or is too large]`);
+                parts.push('');
+            }
+        }
+    }
+    parts.push('INSTRUCTIONS:');
+    parts.push('1. READ the files listed above (they are your existing code)');
+    parts.push('2. ADD the missing method/relationship to the model file');
+    parts.push('3. Do NOT just modify tests — the MODEL/SOURCE file must change');
+    parts.push('4. The L2 review expects to see your implementation in the diff');
+    parts.push('');
+    return parts.join('\n');
+}
+const ANTON_RESULT_SYSTEM_CONTRACT = `[Anton output contract]
+Every final implementation/decompose answer MUST contain exactly one structured block:
+<anton-result>
+status: done|failed|blocked|decompose
+reason: <optional>
+subtasks:
+- <only when status=decompose>
+</anton-result>
+Do not omit this block.`;
+const STRUCTURED_RESULT_RECOVERY_PROMPT = `Your previous reply did not include a valid <anton-result> block.
+Do NOT call tools.
+Return ONLY this block shape and nothing else:
+<anton-result>
+status: done|failed|blocked|decompose
+reason: <optional>
+subtasks:
+- <only when status=decompose>
+</anton-result>`;
+function isStructuredResultParseFailure(reason) {
+    if (!reason)
+        return false;
+    return (reason === 'Agent did not emit structured result' ||
+        reason === 'No status line found in result block' ||
+        reason.startsWith('Unknown status:'));
+}
+function injectAntonResultContract(session) {
+    try {
+        const current = String(session.getSystemPrompt?.() ?? '').trim();
+        if (!current)
+            return;
+        if (current.includes('<anton-result>') || current.includes('[Anton output contract]'))
+            return;
+        session.setSystemPrompt(`${current}\n\n${ANTON_RESULT_SYSTEM_CONTRACT}`);
+    }
+    catch {
+        // best effort
+    }
+}
 export async function runAnton(opts) {
     const { config, idlehandsConfig, progress, abortSignal, apiKey, vault, lens } = opts;
     const createSessionFn = opts.createSession || defaultCreateSession;
@@ -31,6 +196,7 @@ export async function runAnton(opts) {
     const taskRetryCount = new Map();
     const lastFailureReason = new Map();
     const consecutiveIdenticalCount = new Map();
+    const l2FailCount = new Map(); // Track consecutive L2 failures per task
     let lockHeartbeatTimer = null;
     // SIGINT handler
     const handleAbort = () => {
@@ -131,8 +297,15 @@ export async function runAnton(opts) {
                         parts.push('- Test command failed');
                     if (v.l1_lint === false)
                         parts.push('- Lint command failed');
-                    if (v.l2_ai === false && v.l2_reason)
+                    if (v.l2_ai === false && v.l2_reason) {
                         parts.push(`- AI review: ${v.l2_reason}`);
+                        // Enhanced L2 retry context: stronger guidance + file injection on repeated failures
+                        const currentL2Count = l2FailCount.get(currentTask.key) || 0;
+                        const l2Enhancement = buildL2EnhancedRetryContext(v.l2_reason, currentL2Count, config.projectDir, currentTask.text);
+                        if (l2Enhancement) {
+                            parts.push(l2Enhancement);
+                        }
+                    }
                     // Include error output (filtered to errors only, no warnings) so the
                     // agent can see and fix the exact issues.
                     if (v.commandOutput) {
@@ -241,171 +414,117 @@ export async function runAnton(opts) {
                 let discoveryOk = false;
                 await ensureAgentsTasksDir(config.projectDir);
                 const plannedFilePath = taskPlanByTaskKey.get(currentTask.key) ?? makeUniqueTaskPlanFilename(config.projectDir);
-                let discoveryIterationCap = Math.max(1, Math.floor(config.preflightSessionMaxIterations ?? 500));
-                // Stage 1: discovery (retry discovery only).
-                for (let discoveryTry = 0; discoveryTry <= preflightMaxRetries; discoveryTry++) {
-                    const stageStart = Date.now();
-                    const discoveryTimeoutSec = config.preflightDiscoveryTimeoutSec ?? config.taskTimeoutSec;
-                    const discoveryTimeoutMs = discoveryTimeoutSec * 1000;
-                    let discoverySession;
-                    try {
-                        progress.onStage?.('🔎 Discovery: checking if already done...');
-                        discoverySession = await createSessionFn(buildPreflightConfig(idlehandsConfig, config, discoveryTimeoutSec, discoveryIterationCap), apiKey);
-                        const discoveryPrompt = buildDiscoveryPrompt({
-                            task: currentTask,
-                            taskFilePath: config.taskFile,
-                            projectDir: config.projectDir,
-                            planFilePath: plannedFilePath,
-                        });
-                        const discoveryRes = await Promise.race([
-                            discoverySession.ask(discoveryPrompt),
-                            new Promise((_, reject) => setTimeout(() => {
-                                try {
-                                    discoverySession?.cancel();
-                                }
-                                catch {
-                                    // best effort
-                                }
-                                reject(new Error('preflight-discovery-timeout'));
-                            }, discoveryTimeoutMs)),
-                        ]);
-                        const discoveryTokens = discoverySession.usage.prompt + discoverySession.usage.completion;
-                        totalTokens += discoveryTokens;
-                        const discovery = parseDiscoveryResult(discoveryRes.text, config.projectDir);
-                        preflightRecords.push({
-                            taskKey: currentTask.key,
-                            stage: 'discovery',
-                            durationMs: Date.now() - stageStart,
-                            tokensUsed: discoveryTokens,
-                            status: discovery.status,
-                            filename: discovery.filename || undefined,
-                        });
-                        if (discovery.status === 'complete') {
-                            await markTaskChecked(config.taskFile, currentTask.key);
-                            await autoCompleteAncestors(config.taskFile, currentTask.key);
-                            autoCompleted += 1;
-                            progress.onStage?.(`✅ Discovery confirmed already complete: ${currentTask.text}`);
-                            preflightMarkedComplete = true;
-                            discoveryOk = true;
-                            break;
-                        }
-                        const discoveryPlanState = await ensurePlanFileExistsOrBootstrap({
-                            absPath: discovery.filename,
-                            task: currentTask,
-                            source: 'discovery',
-                        });
-                        if (discoveryPlanState === 'bootstrapped') {
-                            progress.onStage?.(`⚠️ Discovery returned a filename but did not write it. Created fallback plan file: ${discovery.filename}`);
-                        }
-                        taskPlanByTaskKey.set(currentTask.key, discovery.filename);
-                        progress.onStage?.(`📝 Discovery plan file: ${discovery.filename}`);
-                        discoveryOk = true;
-                        break;
-                    }
-                    catch (error) {
-                        const errMsg = error instanceof Error ? error.message : String(error);
-                        const timeout = /timeout/i.test(errMsg);
-                        preflightRecords.push({
-                            taskKey: currentTask.key,
-                            stage: 'discovery',
-                            durationMs: Date.now() - stageStart,
-                            tokensUsed: 0,
-                            status: timeout ? 'timeout' : 'error',
-                            error: errMsg,
-                        });
-                        if (discoveryTry < preflightMaxRetries) {
-                            const short = errMsg.length > 180 ? `${errMsg.slice(0, 177)}...` : errMsg;
-                            if (/max iterations exceeded/i.test(errMsg)) {
-                                const nextCap = Math.min(Math.max(discoveryIterationCap * 2, discoveryIterationCap + 2), 1000);
-                                if (nextCap > discoveryIterationCap) {
-                                    progress.onStage?.(`⚠️ Discovery hit max iterations (${discoveryIterationCap}). Increasing preflight cap to ${nextCap} and retrying...`);
-                                    discoveryIterationCap = nextCap;
-                                    continue;
-                                }
-                            }
-                            progress.onStage?.(`⚠️ Discovery failed (${discoveryTry + 1}/${preflightTotalTries}): ${short}. Retrying discovery...`);
-                            continue;
-                        }
-                        const preflightAttempt = {
-                            taskKey: currentTask.key,
-                            taskText: currentTask.text,
-                            attempt: attemptNumber,
-                            durationMs: Date.now() - stageStart,
-                            tokensUsed: 0,
-                            status: timeout ? 'timeout' : 'error',
-                            verification: undefined,
-                            error: `preflight-error(discovery): ${errMsg}`,
-                            commitHash: undefined,
-                        };
-                        attempts.push(preflightAttempt);
-                        taskRetryCount.set(currentTask.key, retries + 1);
-                        if (!config.skipOnFail)
-                            break mainLoop;
-                    }
-                    finally {
+                // Default to 50 iterations for discovery (was 500 - way too high for a simple JSON check)
+                let discoveryIterationCap = Math.max(1, Math.floor(config.preflightSessionMaxIterations ?? 50));
+                let discoveryRetryHint;
+                // Shared preflight session - reused between discovery and review stages to avoid
+                // session creation overhead. Created lazily, closed on error (for fresh retry state)
+                // or at end of preflight block.
+                let preflightSession;
+                const closePreflightSession = async () => {
+                    if (preflightSession) {
                         try {
-                            await discoverySession?.close();
+                            await preflightSession.close();
                         }
                         catch {
                             // best effort
                         }
+                        preflightSession = undefined;
                     }
-                }
-                // Discovery already marked complete -> next task.
-                if (preflightMarkedComplete) {
-                    continue;
-                }
-                if (!discoveryOk) {
-                    continue;
-                }
-                // Stage 2: requirements review (retry review only; keep same plan file).
-                if (config.preflightRequirementsReview) {
-                    const reviewPlanFile = taskPlanByTaskKey.get(currentTask.key) ?? plannedFilePath;
-                    let reviewOk = false;
-                    let reviewIterationCap = Math.max(1, Math.floor(config.preflightSessionMaxIterations ?? 500));
-                    for (let reviewTry = 0; reviewTry <= preflightMaxRetries; reviewTry++) {
+                };
+                try {
+                    // Stage 1: discovery (retry discovery only).
+                    for (let discoveryTry = 0; discoveryTry <= preflightMaxRetries; discoveryTry++) {
                         const stageStart = Date.now();
-                        const reviewTimeoutSec = config.preflightReviewTimeoutSec ?? config.taskTimeoutSec;
-                        const reviewTimeoutMs = reviewTimeoutSec * 1000;
-                        let reviewSession;
+                        const discoveryTimeoutSec = config.preflightDiscoveryTimeoutSec ?? config.taskTimeoutSec;
+                        const discoveryTimeoutMs = discoveryTimeoutSec * 1000;
                         try {
-                            progress.onStage?.('🧪 Requirements review: refining plan...');
-                            reviewSession = await createSessionFn(buildPreflightConfig(idlehandsConfig, config, reviewTimeoutSec, reviewIterationCap), apiKey);
-                            const reviewPrompt = buildRequirementsReviewPrompt(reviewPlanFile);
-                            const reviewRes = await Promise.race([
-                                reviewSession.ask(reviewPrompt),
-                                new Promise((_, reject) => setTimeout(() => {
+                            progress.onStage?.('🔎 Discovery: checking if already done...');
+                            // Create session if not already open (first try or after error closed it)
+                            if (!preflightSession) {
+                                preflightSession = await createSessionFn(buildPreflightConfig(idlehandsConfig, config, discoveryTimeoutSec, discoveryIterationCap), apiKey);
+                            }
+                            const discoveryPrompt = buildDiscoveryPrompt({
+                                task: currentTask,
+                                taskFilePath: config.taskFile,
+                                projectDir: config.projectDir,
+                                planFilePath: plannedFilePath,
+                                retryHint: discoveryRetryHint,
+                            });
+                            let discoveryTimeoutHandle;
+                            const discoveryRes = await Promise.race([
+                                preflightSession.ask(discoveryPrompt).finally(() => clearTimeout(discoveryTimeoutHandle)),
+                                new Promise((_, reject) => {
+                                    discoveryTimeoutHandle = setTimeout(() => {
+                                        try {
+                                            preflightSession?.cancel();
+                                        }
+                                        catch {
+                                            // best effort
+                                        }
+                                        reject(new Error('preflight-discovery-timeout'));
+                                    }, discoveryTimeoutMs);
+                                }),
+                            ]);
+                            let discoveryTokens = preflightSession.usage.prompt + preflightSession.usage.completion;
+                            totalTokens += discoveryTokens;
+                            // Try to parse discovery result; if invalid JSON, attempt force-decision prompt
+                            let discovery;
+                            try {
+                                discovery = parseDiscoveryResult(discoveryRes.text, config.projectDir);
+                            }
+                            catch (parseError) {
+                                const parseErrMsg = parseError instanceof Error ? parseError.message : String(parseError);
+                                // Only try force-decision for JSON/format errors, not file path errors
+                                if (/preflight-json-missing-object|preflight-discovery-invalid/i.test(parseErrMsg)) {
+                                    progress.onStage?.('⚠️ Discovery output invalid, requesting forced decision...');
                                     try {
-                                        reviewSession?.cancel();
+                                        const forceRes = await preflightSession.ask(FORCE_DISCOVERY_DECISION_PROMPT);
+                                        const forceTokens = preflightSession.usage.prompt + preflightSession.usage.completion - discoveryTokens;
+                                        discoveryTokens += forceTokens;
+                                        totalTokens += forceTokens;
+                                        discovery = parseDiscoveryResult(forceRes.text, config.projectDir);
+                                        progress.onStage?.('✅ Forced decision succeeded');
                                     }
-                                    catch {
-                                        // best effort
+                                    catch (forceError) {
+                                        // Force-decision also failed, throw original error
+                                        throw parseError;
                                     }
-                                    reject(new Error('preflight-review-timeout'));
-                                }, reviewTimeoutMs)),
-                            ]);
-                            const reviewTokens = reviewSession.usage.prompt + reviewSession.usage.completion;
-                            totalTokens += reviewTokens;
-                            const review = parseRequirementsReviewResult(reviewRes.text, config.projectDir);
-                            const reviewPlanState = await ensurePlanFileExistsOrBootstrap({
-                                absPath: review.filename,
-                                task: currentTask,
-                                source: 'requirements-review',
-                            });
-                            if (reviewPlanState === 'bootstrapped') {
-                                progress.onStage?.(`⚠️ Requirements review returned a filename but did not write it. Created fallback plan file: ${review.filename}`);
+                                }
+                                else {
+                                    throw parseError;
+                                }
                             }
                             preflightRecords.push({
                                 taskKey: currentTask.key,
-                                stage: 'requirements-review',
+                                stage: 'discovery',
                                 durationMs: Date.now() - stageStart,
-                                tokensUsed: reviewTokens,
-                                status: 'ready',
-                                filename: review.filename,
+                                tokensUsed: discoveryTokens,
+                                status: discovery.status,
+                                filename: discovery.filename || undefined,
+                            });
+                            if (discovery.status === 'complete') {
+                                await markTaskChecked(config.taskFile, currentTask.key);
+                                await autoCompleteAncestors(config.taskFile, currentTask.key);
+                                autoCompleted += 1;
+                                progress.onStage?.(`✅ Discovery confirmed already complete: ${currentTask.text}`);
+                                preflightMarkedComplete = true;
+                                discoveryOk = true;
+                                // No review needed - close session now
+                                await closePreflightSession();
+                                break;
+                            }
+                            const discoveryPlanState = await ensurePlanFileExistsOrBootstrap({
+                                absPath: discovery.filename,
+                                task: currentTask,
+                                source: 'discovery',
                             });
-                            taskPlanByTaskKey.set(currentTask.key, review.filename);
-                            progress.onStage?.(`✅ Requirements review ready: ${review.filename}`);
-                            reviewOk = true;
+                            if (discoveryPlanState === 'bootstrapped') {
+                                progress.onStage?.(`⚠️ Discovery returned a filename but did not write it. Created fallback plan file: ${discovery.filename}`);
+                            }
+                            taskPlanByTaskKey.set(currentTask.key, discovery.filename);
+                            progress.onStage?.(`📝 Discovery plan file: ${discovery.filename}`);
+                            discoveryOk = true;
                             break;
                         }
                         catch (error) {
@@ -413,53 +532,227 @@ export async function runAnton(opts) {
                             const timeout = /timeout/i.test(errMsg);
                             preflightRecords.push({
                                 taskKey: currentTask.key,
-                                stage: 'requirements-review',
+                                stage: 'discovery',
                                 durationMs: Date.now() - stageStart,
                                 tokensUsed: 0,
                                 status: timeout ? 'timeout' : 'error',
                                 error: errMsg,
                             });
-                            if (reviewTry < preflightMaxRetries) {
-                                const short = errMsg.length > 180 ? `${errMsg.slice(0, 177)}...` : errMsg;
+                            const short = errMsg.length > 180 ? `${errMsg.slice(0, 177)}...` : errMsg;
+                            discoveryRetryHint = `Previous discovery attempt failed: ${short}. Do not edit source files. Only update ${plannedFilePath} and return strict JSON.`;
+                            // If discovery returns malformed/non-JSON output (or loops on source edits),
+                            // degrade immediately to fallback plan instead of burning retries.
+                            if (isRecoverablePreflightDiscoveryError(errMsg)) {
+                                const fallbackState = await ensurePlanFileExistsOrBootstrap({
+                                    absPath: plannedFilePath,
+                                    task: currentTask,
+                                    source: 'discovery',
+                                });
+                                if (fallbackState === 'bootstrapped') {
+                                    progress.onStage?.(`⚠️ Discovery returned invalid output (${short}). Bootstrapped fallback plan and continuing: ${plannedFilePath}`);
+                                }
+                                else {
+                                    progress.onStage?.(`⚠️ Discovery returned invalid output (${short}). Reusing existing plan and continuing: ${plannedFilePath}`);
+                                }
+                                taskPlanByTaskKey.set(currentTask.key, plannedFilePath);
+                                discoveryOk = true;
+                                break;
+                            }
+                            if (discoveryTry < preflightMaxRetries) {
+                                // Close session on error so retry gets fresh state
+                                await closePreflightSession();
                                 if (/max iterations exceeded/i.test(errMsg)) {
-                                    const nextCap = Math.min(Math.max(reviewIterationCap * 2, reviewIterationCap + 2), 1000);
-                                    if (nextCap > reviewIterationCap) {
-                                        progress.onStage?.(`⚠️ Requirements review hit max iterations (${reviewIterationCap}). Increasing preflight cap to ${nextCap} and retrying...`);
-                                        reviewIterationCap = nextCap;
+                                    const nextCap = Math.min(Math.max(discoveryIterationCap * 2, discoveryIterationCap + 2), 1000);
+                                    if (nextCap > discoveryIterationCap) {
+                                        progress.onStage?.(`⚠️ Discovery hit max iterations (${discoveryIterationCap}). Increasing preflight cap to ${nextCap} and retrying...`);
+                                        discoveryIterationCap = nextCap;
                                         continue;
                                     }
                                 }
-                                progress.onStage?.(`⚠️ Requirements review failed (${reviewTry + 1}/${preflightTotalTries}): ${short}. Retrying review with existing plan file...`);
+                                progress.onStage?.(`⚠️ Discovery failed (${discoveryTry + 1}/${preflightTotalTries}): ${short}. Retrying discovery...`);
                                 continue;
                             }
-                            const preflightAttempt = {
-                                taskKey: currentTask.key,
-                                taskText: currentTask.text,
-                                attempt: attemptNumber,
-                                durationMs: Date.now() - stageStart,
-                                tokensUsed: 0,
-                                status: timeout ? 'timeout' : 'error',
-                                verification: undefined,
-                                error: `preflight-error(requirements-review): ${errMsg}`,
-                                commitHash: undefined,
-                            };
-                            attempts.push(preflightAttempt);
-                            taskRetryCount.set(currentTask.key, retries + 1);
-                            if (!config.skipOnFail)
-                                break mainLoop;
-                        }
-                        finally {
-                            try {
-                                await reviewSession?.close();
+                            // Final discovery failure: degrade gracefully by bootstrapping a fallback plan file
+                            // so Anton can still proceed to implementation/review instead of hard-failing task 1.
+                            const fallbackState = await ensurePlanFileExistsOrBootstrap({
+                                absPath: plannedFilePath,
+                                task: currentTask,
+                                source: 'discovery',
+                            });
+                            if (fallbackState === 'bootstrapped') {
+                                progress.onStage?.(`⚠️ Discovery failed after ${preflightTotalTries} tries (${short}). Bootstrapped fallback plan and continuing: ${plannedFilePath}`);
                             }
-                            catch {
-                                // best effort
+                            else {
+                                progress.onStage?.(`⚠️ Discovery failed after ${preflightTotalTries} tries (${short}). Reusing existing plan and continuing: ${plannedFilePath}`);
                             }
+                            taskPlanByTaskKey.set(currentTask.key, plannedFilePath);
+                            discoveryOk = true;
+                            break;
                         }
+                        // Note: session stays open for reuse in review stage (closed at end of preflight block)
+                    }
+                    // Discovery already marked complete -> next task.
+                    if (preflightMarkedComplete) {
+                        continue;
                     }
-                    if (!reviewOk) {
+                    if (!discoveryOk) {
                         continue;
                     }
+                    // Stage 2: requirements review (retry review only; keep same plan file).
+                    // NOTE: Discovery prompt now includes review instructions, producing a "reviewed" plan.
+                    // Separate review stage is skipped by default to save an LLM round-trip.
+                    // Set preflightRequirementsReview=true AND preflightSeparateReview=true to force separate review.
+                    const skipSeparateReview = !config.preflightSeparateReview;
+                    if (config.preflightRequirementsReview && !skipSeparateReview) {
+                        const reviewPlanFile = taskPlanByTaskKey.get(currentTask.key) ?? plannedFilePath;
+                        let reviewOk = false;
+                        // Default to 30 iterations for review (simpler than discovery, just refining existing plan)
+                        let reviewIterationCap = Math.max(1, Math.floor(config.preflightSessionMaxIterations ?? 30));
+                        for (let reviewTry = 0; reviewTry <= preflightMaxRetries; reviewTry++) {
+                            const stageStart = Date.now();
+                            const reviewTimeoutSec = config.preflightReviewTimeoutSec ?? config.taskTimeoutSec;
+                            const reviewTimeoutMs = reviewTimeoutSec * 1000;
+                            try {
+                                progress.onStage?.('🧪 Requirements review: refining plan...');
+                                // Reuse preflight session from discovery, or create new one if needed (e.g., after error)
+                                if (!preflightSession) {
+                                    preflightSession = await createSessionFn(buildPreflightConfig(idlehandsConfig, config, reviewTimeoutSec, reviewIterationCap), apiKey);
+                                }
+                                const reviewPrompt = buildRequirementsReviewPrompt(reviewPlanFile);
+                                let reviewTimeoutHandle;
+                                const reviewRes = await Promise.race([
+                                    preflightSession.ask(reviewPrompt).finally(() => clearTimeout(reviewTimeoutHandle)),
+                                    new Promise((_, reject) => {
+                                        reviewTimeoutHandle = setTimeout(() => {
+                                            try {
+                                                preflightSession?.cancel();
+                                            }
+                                            catch {
+                                                // best effort
+                                            }
+                                            reject(new Error('preflight-review-timeout'));
+                                        }, reviewTimeoutMs);
+                                    }),
+                                ]);
+                                let reviewTokens = preflightSession.usage.prompt + preflightSession.usage.completion;
+                                totalTokens += reviewTokens;
+                                // Try to parse review result; if invalid JSON, attempt force-decision prompt
+                                let review;
+                                try {
+                                    review = parseRequirementsReviewResult(reviewRes.text, config.projectDir);
+                                }
+                                catch (parseError) {
+                                    const parseErrMsg = parseError instanceof Error ? parseError.message : String(parseError);
+                                    // Only try force-decision for JSON/format errors
+                                    if (/preflight-json-missing-object|preflight-review-invalid/i.test(parseErrMsg)) {
+                                        progress.onStage?.('⚠️ Review output invalid, requesting forced decision...');
+                                        try {
+                                            const forceRes = await preflightSession.ask(FORCE_REVIEW_DECISION_PROMPT);
+                                            const forceTokens = preflightSession.usage.prompt + preflightSession.usage.completion - reviewTokens;
+                                            reviewTokens += forceTokens;
+                                            totalTokens += forceTokens;
+                                            review = parseRequirementsReviewResult(forceRes.text, config.projectDir);
+                                            progress.onStage?.('✅ Forced decision succeeded');
+                                        }
+                                        catch (forceError) {
+                                            // Force-decision also failed, throw original error
+                                            throw parseError;
+                                        }
+                                    }
+                                    else {
+                                        throw parseError;
+                                    }
+                                }
+                                const reviewPlanState = await ensurePlanFileExistsOrBootstrap({
+                                    absPath: review.filename,
+                                    task: currentTask,
+                                    source: 'requirements-review',
+                                });
+                                if (reviewPlanState === 'bootstrapped') {
+                                    progress.onStage?.(`⚠️ Requirements review returned a filename but did not write it. Created fallback plan file: ${review.filename}`);
+                                }
+                                preflightRecords.push({
+                                    taskKey: currentTask.key,
+                                    stage: 'requirements-review',
+                                    durationMs: Date.now() - stageStart,
+                                    tokensUsed: reviewTokens,
+                                    status: 'ready',
+                                    filename: review.filename,
+                                });
+                                taskPlanByTaskKey.set(currentTask.key, review.filename);
+                                progress.onStage?.(`✅ Requirements review ready: ${review.filename}`);
+                                reviewOk = true;
+                                break;
+                            }
+                            catch (error) {
+                                const errMsg = error instanceof Error ? error.message : String(error);
+                                const timeout = /timeout/i.test(errMsg);
+                                preflightRecords.push({
+                                    taskKey: currentTask.key,
+                                    stage: 'requirements-review',
+                                    durationMs: Date.now() - stageStart,
+                                    tokensUsed: 0,
+                                    status: timeout ? 'timeout' : 'error',
+                                    error: errMsg,
+                                });
+                                const short = errMsg.length > 180 ? `${errMsg.slice(0, 177)}...` : errMsg;
+                                // If review returns malformed/non-JSON output, keep moving with existing plan.
+                                if (isRecoverablePreflightReviewError(errMsg)) {
+                                    const fallbackState = await ensurePlanFileExistsOrBootstrap({
+                                        absPath: reviewPlanFile,
+                                        task: currentTask,
+                                        source: 'requirements-review',
+                                    });
+                                    if (fallbackState === 'bootstrapped') {
+                                        progress.onStage?.(`⚠️ Requirements review returned invalid output (${short}). Bootstrapped fallback plan and continuing: ${reviewPlanFile}`);
+                                    }
+                                    else {
+                                        progress.onStage?.(`⚠️ Requirements review returned invalid output (${short}). Reusing existing plan and continuing: ${reviewPlanFile}`);
+                                    }
+                                    taskPlanByTaskKey.set(currentTask.key, reviewPlanFile);
+                                    reviewOk = true;
+                                    break;
+                                }
+                                if (reviewTry < preflightMaxRetries) {
+                                    // Close session on error so retry gets fresh state
+                                    await closePreflightSession();
+                                    if (/max iterations exceeded/i.test(errMsg)) {
+                                        const nextCap = Math.min(Math.max(reviewIterationCap * 2, reviewIterationCap + 2), 1000);
+                                        if (nextCap > reviewIterationCap) {
+                                            progress.onStage?.(`⚠️ Requirements review hit max iterations (${reviewIterationCap}). Increasing preflight cap to ${nextCap} and retrying...`);
+                                            reviewIterationCap = nextCap;
+                                            continue;
+                                        }
+                                    }
+                                    progress.onStage?.(`⚠️ Requirements review failed (${reviewTry + 1}/${preflightTotalTries}): ${short}. Retrying review with existing plan file...`);
+                                    continue;
+                                }
+                                const preflightAttempt = {
+                                    taskKey: currentTask.key,
+                                    taskText: currentTask.text,
+                                    attempt: attemptNumber,
+                                    durationMs: Date.now() - stageStart,
+                                    tokensUsed: 0,
+                                    status: timeout ? 'timeout' : 'error',
+                                    verification: undefined,
+                                    error: `preflight-error(requirements-review): ${errMsg}`,
+                                    commitHash: undefined,
+                                };
+                                attempts.push(preflightAttempt);
+                                taskRetryCount.set(currentTask.key, retries + 1);
+                                if (!config.skipOnFail)
+                                    break mainLoop;
+                            }
+                            // Note: session stays open, will be closed at end of preflight block
+                        }
+                        if (!reviewOk) {
+                            continue;
+                        }
+                    }
+                }
+                finally {
+                    // Always close preflight session at end of preflight block
+                    await closePreflightSession();
                 }
             }
             progress.onStage?.('🛠️ Implementation: executing vetted plan...');
@@ -476,6 +769,7 @@ export async function runAnton(opts) {
                     : buildSessionConfig(idlehandsConfig, config);
                 console.error(`[anton:debug] task="${currentTask.text}" depth=${currentTask.depth} complexity=${taskComplexity} isComplexDecompose=${isComplexDecompose} no_tools=${!!sessionConfig.no_tools} max_iterations=${sessionConfig.max_iterations}`);
                 session = await createSessionFn(sessionConfig, apiKey);
+                injectAntonResultContract(session);
                 // Set up timeout + stop propagation for the currently running attempt.
                 // /anton stop flips abortSignal.aborted; we poll that and cancel session.ask immediately
                 // instead of waiting for the task attempt to naturally finish.
@@ -650,18 +944,41 @@ export async function runAnton(opts) {
                     }
                     const taskEndMs = Date.now();
                     const durationMs = taskEndMs - taskStartMs;
-                    const tokensUsed = session.usage.prompt + session.usage.completion;
+                    let tokensUsed = session.usage.prompt + session.usage.completion;
+                    // Parse structured result (with one-shot recovery for format-only failures).
+                    let agentResult = parseAntonResult(result.text);
+                    if (agentResult.status === 'blocked' &&
+                        isStructuredResultParseFailure(agentResult.reason) &&
+                        !abortSignal.aborted &&
+                        !controller.signal.aborted) {
+                        try {
+                            progress.onStage?.('⚠️ Agent omitted structured result. Requesting format-only recovery...');
+                            const repaired = await session.ask(STRUCTURED_RESULT_RECOVERY_PROMPT);
+                            iterationsUsed += repaired.turns;
+                            agentResult = parseAntonResult(repaired.text);
+                            tokensUsed = session.usage.prompt + session.usage.completion;
+                        }
+                        catch (repairErr) {
+                            console.error(`[anton:result-recovery] failed: ${repairErr}`);
+                        }
+                    }
+                    // If result is still parse-broken, treat as failed (retriable) instead of blocked (terminal).
+                    if (agentResult.status === 'blocked' && isStructuredResultParseFailure(agentResult.reason)) {
+                        agentResult = {
+                            status: 'failed',
+                            reason: `structured-result-parse-failure: ${agentResult.reason}`,
+                            subtasks: [],
+                        };
+                    }
                     // Per-attempt token cost guardrail (not just prompt size).
                     if (tokensUsed > config.maxPromptTokensPerAttempt) {
                         throw new Error(`attempt-token-budget-exceeded: used=${tokensUsed} max=${config.maxPromptTokensPerAttempt}`);
                     }
-                    // Parse structured result
-                    const agentResult = parseAntonResult(result.text);
                     console.error(`[anton:result] task="${currentTask.text.slice(0, 50)}" status=${agentResult.status} reason=${agentResult.reason ?? 'none'} subtasks=${agentResult.subtasks.length} tokens=${tokensUsed} duration=${Math.round(durationMs / 1000)}s`);
                     if (isComplexDecompose) {
                         console.error(`[anton:debug] decompose result: status=${agentResult.status} subtasks=${agentResult.subtasks.length} reason=${agentResult.reason ?? 'none'}`);
-                        if (agentResult.status === 'blocked' &&
-                            agentResult.reason === 'Agent did not emit structured result') {
+                        if (agentResult.status === 'failed' &&
+                            (agentResult.reason ?? '').startsWith('structured-result-parse-failure')) {
                             console.error(`[anton:debug] decompose raw output (first 500 chars): ${(result.text ?? '').slice(0, 500)}`);
                         }
                     }
@@ -874,6 +1191,15 @@ export async function runAnton(opts) {
                     consecutiveIdenticalCount.set(currentTask.key, 1);
                 }
                 lastFailureReason.set(currentTask.key, currentReason);
+                // Track L2-specific failures for enhanced retry context
+                if (attempt.verification?.l2_ai === false) {
+                    l2FailCount.set(currentTask.key, (l2FailCount.get(currentTask.key) || 0) + 1);
+                    console.error(`[anton:l2-fail] task="${currentTask.text.slice(0, 40)}" l2_fail_count=${l2FailCount.get(currentTask.key)}`);
+                }
+            }
+            else {
+                // Task passed — reset L2 fail count
+                l2FailCount.delete(currentTask.key);
             }
             // Report task end
             progress.onTaskEnd(currentTask, attempt, currentProgress);