@visorcraft/idlehands 2.0.1 → 2.0.2

package/dist/anton/controller.js

@@ -11,7 +11,7 @@ import { ensureCleanWorkingTree, getWorkingDiff, commitAll, restoreTrackedChange
 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';
@@ -64,6 +64,12 @@ function isL2MissingImplementation(reason) {
     ];
     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.
@@ -136,6 +142,15 @@ function buildL2EnhancedRetryContext(l2Reason, l2FailCount, projectDir, taskText
     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:
@@ -152,6 +167,19 @@ function isStructuredResultParseFailure(reason) {
         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;
@@ -386,181 +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));
+                // 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;
-                // 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,
-                            retryHint: discoveryRetryHint,
-                        });
-                        let discoveryTimeoutHandle;
-                        const discoveryRes = await Promise.race([
-                            discoverySession.ask(discoveryPrompt).finally(() => clearTimeout(discoveryTimeoutHandle)),
-                            new Promise((_, reject) => {
-                                discoveryTimeoutHandle = 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,
-                        });
-                        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 (discoveryTry < preflightMaxRetries) {
-                            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;
-                        }
-                        // 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}`);
-                        }
-                        else {
-                            progress.onStage?.(`⚠️ Discovery failed after ${preflightTotalTries} tries (${short}). Reusing existing plan and continuing: ${plannedFilePath}`);
-                        }
-                        taskPlanByTaskKey.set(currentTask.key, plannedFilePath);
-                        discoveryOk = true;
-                        break;
-                    }
-                    finally {
+                // 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);
-                            let reviewTimeoutHandle;
-                            const reviewRes = await Promise.race([
-                                reviewSession.ask(reviewPrompt).finally(() => clearTimeout(reviewTimeoutHandle)),
+                            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) => {
-                                    reviewTimeoutHandle = setTimeout(() => {
+                                    discoveryTimeoutHandle = setTimeout(() => {
                                         try {
-                                            reviewSession?.cancel();
+                                            preflightSession?.cancel();
                                         }
                                         catch {
                                             // best effort
                                         }
-                                        reject(new Error('preflight-review-timeout'));
-                                    }, reviewTimeoutMs);
+                                        reject(new Error('preflight-discovery-timeout'));
+                                    }, discoveryTimeoutMs);
                                 }),
                             ]);
-                            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}`);
+                            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 {
+                                        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 (forceError) {
+                                        // Force-decision also failed, throw original error
+                                        throw parseError;
+                                    }
+                                }
+                                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) {
@@ -568,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...');
@@ -631,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.