@neurcode-ai/cli 0.9.27 → 0.9.29

package/dist/commands/plan.js

@@ -37,6 +37,7 @@ exports.detectIntentMode = detectIntentMode;
 exports.planCommand = planCommand;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const crypto_1 = require("crypto");
 const config_1 = require("../config");
 const api_client_1 = require("../api-client");
 const project_detector_1 = require("../utils/project-detector");
@@ -267,6 +268,125 @@ function renderCacheMissReason(reason, bestIntentSimilarity) {
     }
     return reasonText[reason];
 }
+function hasPersistedPlanId(planId) {
+    return typeof planId === 'string' && planId.trim().length > 0 && planId !== 'unknown';
+}
+function toUnixPath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+function parsePositiveInt(raw) {
+    if (!raw)
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return null;
+    return Math.floor(parsed);
+}
+function parseSnapshotMode(raw) {
+    if (!raw)
+        return null;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'auto' || normalized === 'full' || normalized === 'off') {
+        return normalized;
+    }
+    return null;
+}
+function resolveSnapshotMode(optionMode) {
+    if (process.env.NEURCODE_PLAN_SKIP_SNAPSHOTS === '1') {
+        return 'off';
+    }
+    const optionParsed = parseSnapshotMode(optionMode);
+    const envMode = parseSnapshotMode(process.env.NEURCODE_PLAN_SNAPSHOT_MODE);
+    return optionParsed || envMode || 'auto';
+}
+function resolveSnapshotMaxFiles(mode, optionValue) {
+    const envOverride = parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_MAX_FILES);
+    const configured = optionValue && optionValue > 0 ? Math.floor(optionValue) : envOverride;
+    if (configured && configured > 0)
+        return configured;
+    return mode === 'full' ? 500 : 40;
+}
+function resolveSnapshotBudgetMs(mode, optionValue) {
+    const envOverride = parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_BUDGET_MS);
+    const configured = optionValue && optionValue > 0 ? Math.floor(optionValue) : envOverride;
+    if (typeof configured === 'number' && configured > 0)
+        return configured;
+    return mode === 'full' ? 0 : 60_000;
+}
+function resolveSnapshotMaxBytes(mode) {
+    const envOverride = parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_MAX_BYTES);
+    if (typeof envOverride === 'number' && envOverride > 0)
+        return envOverride;
+    return mode === 'full' ? 0 : 256 * 1024;
+}
+function resolveSnapshotBatchSize(mode) {
+    const envOverride = parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_BATCH_SIZE);
+    if (typeof envOverride === 'number' && envOverride > 0) {
+        return Math.min(100, Math.max(1, envOverride));
+    }
+    return mode === 'full' ? 30 : 20;
+}
+function resolveSnapshotBatchTimeoutMs(singleRequestTimeoutMs, mode) {
+    const envOverride = parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_BATCH_TIMEOUT_MS);
+    if (typeof envOverride === 'number' && envOverride > 0)
+        return envOverride;
+    const multiplier = mode === 'full' ? 5 : 4;
+    return Math.max(singleRequestTimeoutMs * multiplier, 12000);
+}
+function isBatchSnapshotEndpointUnsupported(error) {
+    if (!(error instanceof Error))
+        return false;
+    const message = error.message.toLowerCase();
+    return (message.includes('status 404') ||
+        message.includes('not found') ||
+        message.includes('not_found') ||
+        message.includes('method not allowed'));
+}
+function getSnapshotManifestPath(projectRoot) {
+    return (0, path_1.join)(projectRoot, '.neurcode', 'snapshot-manifest.json');
+}
+function loadSnapshotManifest(projectRoot) {
+    const manifestPath = getSnapshotManifestPath(projectRoot);
+    if (!(0, fs_1.existsSync)(manifestPath)) {
+        return {
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            entries: {},
+        };
+    }
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(manifestPath, 'utf-8'));
+        if (parsed && parsed.version === 1 && parsed.entries && typeof parsed.entries === 'object') {
+            return {
+                version: 1,
+                updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+                entries: parsed.entries,
+            };
+        }
+    }
+    catch {
+        // Ignore manifest parse errors and start fresh.
+    }
+    return {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        entries: {},
+    };
+}
+function saveSnapshotManifest(projectRoot, manifest) {
+    const manifestPath = getSnapshotManifestPath(projectRoot);
+    const manifestDir = (0, path_1.join)(projectRoot, '.neurcode');
+    if (!(0, fs_1.existsSync)(manifestDir)) {
+        (0, fs_1.mkdirSync)(manifestDir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+function computeSnapshotHash(content) {
+    return (0, crypto_1.createHash)('sha256').update(content, 'utf-8').digest('hex');
+}
+function emitPlanJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
 function emitCachedPlanHit(input) {
     if (input.touchKey) {
         try {
@@ -283,14 +403,33 @@ function emitCachedPlanHit(input) {
     else {
         console.log(chalk.dim(`⚡ Using cached plan (created: ${createdAtLabel})\n`));
     }
-    displayPlan(input.response.plan);
-    console.log(chalk.dim(`\nGenerated at: ${new Date(input.response.timestamp).toLocaleString()} (cached)`));
-    if (input.response.planId && input.response.planId !== 'unknown') {
-        console.log(chalk.bold.cyan(`\n📌 Plan ID: ${input.response.planId} (Cached)`));
-        console.log(chalk.dim('   Run \'neurcode prompt\' to generate a Cursor/AI prompt.'));
+    const persistedPlan = hasPersistedPlanId(input.response.planId);
+    if (input.jsonMode) {
+        emitPlanJson({
+            success: persistedPlan,
+            cached: true,
+            mode: input.intentMode,
+            planId: persistedPlan ? input.response.planId : null,
+            sessionId: input.response.sessionId || null,
+            projectId: input.projectId || null,
+            timestamp: input.response.timestamp,
+            telemetry: input.response.telemetry,
+            message: persistedPlan
+                ? `Using ${input.mode === 'near' ? 'near-' : ''}cached plan`
+                : 'Plan generated but could not be persisted (missing planId)',
+            plan: input.response.plan,
+        });
+    }
+    else {
+        displayPlan(input.response.plan);
+        console.log(chalk.dim(`\nGenerated at: ${new Date(input.response.timestamp).toLocaleString()} (cached)`));
+        if (persistedPlan) {
+            console.log(chalk.bold.cyan(`\n📌 Plan ID: ${input.response.planId} (Cached)`));
+            console.log(chalk.dim('   Run \'neurcode prompt\' to generate a Cursor/AI prompt.'));
+        }
     }
     try {
-        if (input.response.planId && input.response.planId !== 'unknown') {
+        if (persistedPlan) {
             (0, state_1.setActivePlanId)(input.response.planId);
             (0, state_1.setLastPlanGeneratedAt)(new Date().toISOString());
         }
@@ -311,15 +450,47 @@ function emitCachedPlanHit(input) {
     catch {
         // ignore state write errors
     }
+    return persistedPlan;
 }
 async function planCommand(intent, options) {
     try {
         if (!intent || !intent.trim()) {
+            if (options.json) {
+                emitPlanJson({
+                    success: false,
+                    cached: false,
+                    mode: 'implementation',
+                    planId: null,
+                    sessionId: null,
+                    projectId: options.projectId || null,
+                    timestamp: new Date().toISOString(),
+                    message: 'Intent cannot be empty',
+                });
+            }
             console.error(chalk.red('❌ Error: Intent cannot be empty. What are you building?'));
             console.log(chalk.dim('Usage: neurcode plan "<your intent description>"'));
             console.log(chalk.dim('Example: neurcode plan "Add user authentication to login page"'));
             process.exit(1);
         }
+        if (options.snapshotMode) {
+            const parsedSnapshotMode = parseSnapshotMode(String(options.snapshotMode));
+            if (!parsedSnapshotMode) {
+                if (options.json) {
+                    emitPlanJson({
+                        success: false,
+                        cached: false,
+                        mode: 'implementation',
+                        planId: null,
+                        sessionId: null,
+                        projectId: options.projectId || null,
+                        timestamp: new Date().toISOString(),
+                        message: `Invalid --snapshot-mode "${options.snapshotMode}". Expected: auto | full | off.`,
+                    });
+                }
+                console.error(chalk.red(`❌ Invalid --snapshot-mode "${options.snapshotMode}". Expected: auto | full | off.`));
+                process.exit(1);
+            }
+        }
         // Load configuration first (needed for TicketService)
         const config = (0, config_1.loadConfig)();
         // API URL is automatically set to production - no need to check
@@ -376,14 +547,18 @@ async function planCommand(intent, options) {
             });
             const cached = (0, plan_cache_1.readCachedPlan)(cwd, key);
             if (cached) {
-                emitCachedPlanHit({
+                const persisted = emitCachedPlanHit({
                     cwd,
                     response: cached.response,
                     createdAt: cached.createdAt,
                     mode: 'exact',
                     orgId,
                     projectId: finalProjectIdEarly,
+                    jsonMode: options.json === true,
+                    intentMode,
                 });
+                if (!persisted)
+                    process.exit(2);
                 return;
             }
             const near = (0, plan_cache_1.findNearCachedPlan)(cwd, {
@@ -398,7 +573,7 @@ async function planCommand(intent, options) {
                 minIntentSimilarity: nearIntentSimilarityFloor,
             });
             if (near) {
-                emitCachedPlanHit({
+                const persisted = emitCachedPlanHit({
                     cwd,
                     response: near.entry.response,
                     createdAt: near.entry.createdAt,
@@ -407,7 +582,11 @@ async function planCommand(intent, options) {
                     orgId,
                     projectId: finalProjectIdEarly,
                     touchKey: near.entry.key,
+                    jsonMode: options.json === true,
+                    intentMode,
                 });
+                if (!persisted)
+                    process.exit(2);
                 return;
             }
             const miss = (0, plan_cache_1.diagnosePlanCacheMiss)(cwd, {
@@ -586,14 +765,18 @@ async function planCommand(intent, options) {
             });
             const cached = (0, plan_cache_1.readCachedPlan)(cwd, key);
             if (cached) {
-                emitCachedPlanHit({
+                const persisted = emitCachedPlanHit({
                     cwd,
                     response: cached.response,
                     createdAt: cached.createdAt,
                     mode: 'exact',
                     orgId,
                     projectId: finalProjectIdForGuard,
+                    jsonMode: options.json === true,
+                    intentMode,
                 });
+                if (!persisted)
+                    process.exit(2);
                 return;
             }
             const near = (0, plan_cache_1.findNearCachedPlan)(cwd, {
@@ -608,7 +791,7 @@ async function planCommand(intent, options) {
                 minIntentSimilarity: nearIntentSimilarityFloor,
             });
             if (near) {
-                emitCachedPlanHit({
+                const persisted = emitCachedPlanHit({
                     cwd,
                     response: near.entry.response,
                     createdAt: near.entry.createdAt,
@@ -617,7 +800,11 @@ async function planCommand(intent, options) {
                     orgId,
                     projectId: finalProjectIdForGuard,
                     touchKey: near.entry.key,
+                    jsonMode: options.json === true,
+                    intentMode,
                 });
+                if (!persisted)
+                    process.exit(2);
                 return;
             }
             const miss = (0, plan_cache_1.diagnosePlanCacheMiss)(cwd, {
@@ -876,8 +1063,9 @@ async function planCommand(intent, options) {
                 // Brain progression tracking should never block plan generation.
             }
         }
+        const persistedPlanId = hasPersistedPlanId(response.planId);
         // Persist in local cache for instant repeat plans.
-        if (shouldUseCache && orgId && finalProjectIdForGuard) {
+        if (persistedPlanId && shouldUseCache && orgId && finalProjectIdForGuard) {
             // Recompute repo fingerprint right before writing to cache so Neurcode-managed
             // housekeeping (e.g. `.neurcode/config.json`, `.gitignore` updates) doesn't
             // cause immediate cache misses on the next identical run.
@@ -918,60 +1106,301 @@ async function planCommand(intent, options) {
         if (orgId && finalProjectIdForGuard) {
             (0, neurcode_context_1.appendPlanToOrgProjectMemory)(cwd, orgId, finalProjectIdForGuard, intent, response);
         }
-        // Pre-Flight Snapshot: Capture current state of files that will be MODIFIED
-        // This ensures we have a baseline to revert to if AI destroys files
-        const modifyFiles = response.plan.files.filter(f => f.action === 'MODIFY');
-        const skipSnapshotsByEnv = process.env.NEURCODE_PLAN_SKIP_SNAPSHOTS === '1';
+        // Pre-flight snapshots: capture current state for MODIFY targets.
+        const modifyFiles = response.plan.files.filter((f) => f.action === 'MODIFY');
+        const snapshotMode = resolveSnapshotMode(options.snapshotMode);
+        const snapshotMaxFiles = resolveSnapshotMaxFiles(snapshotMode, options.snapshotMaxFiles);
+        const snapshotBudgetMs = resolveSnapshotBudgetMs(snapshotMode, options.snapshotBudgetMs);
+        const snapshotMaxBytes = resolveSnapshotMaxBytes(snapshotMode);
+        let snapshotSummary;
         if (isReadOnlyAnalysis) {
             console.log(chalk.dim('\n🔎 Analysis mode: skipping pre-flight file snapshots'));
+            snapshotSummary = {
+                mode: snapshotMode,
+                attempted: 0,
+                processed: 0,
+                saved: 0,
+                failed: 0,
+                skippedUnchanged: 0,
+                skippedMissing: 0,
+                skippedLarge: 0,
+                skippedBudget: 0,
+                capped: 0,
+                usedBatchApi: false,
+                batchFallbackToSingle: false,
+                durationMs: 0,
+            };
         }
-        else if (skipSnapshotsByEnv) {
-            console.log(chalk.dim('\n⚡ Snapshot capture skipped by runtime flag (fast ship mode)'));
+        else if (snapshotMode === 'off') {
+            console.log(chalk.dim('\n⚡ Snapshot capture disabled (snapshot mode: off)'));
+            snapshotSummary = {
+                mode: snapshotMode,
+                attempted: 0,
+                processed: 0,
+                saved: 0,
+                failed: 0,
+                skippedUnchanged: 0,
+                skippedMissing: 0,
+                skippedLarge: 0,
+                skippedBudget: 0,
+                capped: 0,
+                usedBatchApi: false,
+                batchFallbackToSingle: false,
+                durationMs: 0,
+            };
         }
         else if (modifyFiles.length > 0) {
-            console.log(chalk.dim(`\n📸 Capturing pre-flight snapshots for ${modifyFiles.length} file(s)...`));
+            const snapshotStartedAt = Date.now();
+            const snapshotCandidates = modifyFiles.slice(0, snapshotMaxFiles);
+            const cappedCount = Math.max(0, modifyFiles.length - snapshotCandidates.length);
+            const snapshotTimeoutMs = Math.max(1000, parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_TIMEOUT_MS) ?? (snapshotMode === 'full' ? 15000 : 8000));
+            const snapshotConcurrency = Math.min(16, Math.max(1, parsePositiveInt(process.env.NEURCODE_PLAN_SNAPSHOT_CONCURRENCY) ?? (snapshotMode === 'full' ? 8 : 6)));
+            const snapshotBatchSize = resolveSnapshotBatchSize(snapshotMode);
+            const snapshotBatchTimeoutMs = resolveSnapshotBatchTimeoutMs(snapshotTimeoutMs, snapshotMode);
+            const deadline = snapshotBudgetMs > 0 ? Date.now() + snapshotBudgetMs : 0;
+            const forceResnapshot = process.env.NEURCODE_PLAN_SNAPSHOT_FORCE === '1';
+            console.log(chalk.dim(`\n📸 Capturing pre-flight snapshots for ${snapshotCandidates.length}/${modifyFiles.length} file(s)` +
+                ` [mode=${snapshotMode}, batch=${snapshotBatchSize}, fallback-concurrency=${snapshotConcurrency}` +
+                `${snapshotBudgetMs > 0 ? `, budget=${snapshotBudgetMs}ms` : ', budget=unbounded'}]...`));
+            const withTimeout = async (promise, timeoutMs) => {
+                return await Promise.race([
+                    promise,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`snapshot timeout after ${timeoutMs}ms`)), timeoutMs)),
+                ]);
+            };
+            const manifest = loadSnapshotManifest(cwd);
+            let manifestDirty = false;
+            const preparedSnapshots = [];
+            let snapshotsProcessed = 0;
             let snapshotsSaved = 0;
             let snapshotsFailed = 0;
-            for (const file of modifyFiles) {
+            let snapshotsSkippedMissing = 0;
+            let snapshotsSkippedUnchanged = 0;
+            let snapshotsSkippedLarge = 0;
+            let snapshotsSkippedBudget = 0;
+            let usedBatchApi = false;
+            let batchFallbackToSingle = false;
+            for (const current of snapshotCandidates) {
+                if (deadline > 0 && Date.now() >= deadline) {
+                    snapshotsSkippedBudget = snapshotCandidates.length - snapshotsProcessed;
+                    break;
+                }
+                snapshotsProcessed++;
                 try {
-                    // Resolve file path relative to current working directory
-                    const filePath = (0, path_1.resolve)(cwd, file.path);
-                    // Check if file exists locally
+                    const normalizedPath = toUnixPath(current.path);
+                    const filePath = (0, path_1.resolve)(cwd, current.path);
                     if (!(0, fs_1.existsSync)(filePath)) {
-                        console.log(chalk.yellow(`   ⚠️  Skipping ${file.path} (file not found locally)`));
+                        snapshotsSkippedMissing++;
+                        if (process.env.DEBUG) {
+                            console.log(chalk.yellow(`   ⚠️  Skipping ${current.path} (file not found locally)`));
+                        }
                         continue;
                     }
-                    // Read current file content
                     const fileContent = (0, fs_1.readFileSync)(filePath, 'utf-8');
-                    // Save as backup version with descriptive reason
-                    const reason = `Pre-Plan Snapshot for "${intent.trim()}"`;
-                    await client.saveFileVersion(file.path, fileContent, finalProjectId, reason, 'modify', // Pre-flight snapshot is a modification checkpoint
-                    0, // No lines added yet (this is the baseline)
-                    0 // No lines removed yet (this is the baseline)
-                    );
-                    snapshotsSaved++;
-                    console.log(chalk.green(`   ✓ Snapshot saved: ${file.path}`));
+                    const fileSize = Buffer.byteLength(fileContent, 'utf-8');
+                    if (snapshotMaxBytes > 0 && fileSize > snapshotMaxBytes) {
+                        snapshotsSkippedLarge++;
+                        if (process.env.DEBUG) {
+                            console.log(chalk.yellow(`   ⚠️  Skipping ${current.path} (size ${fileSize}B > ${snapshotMaxBytes}B)`));
+                        }
+                        continue;
+                    }
+                    const fileHash = computeSnapshotHash(fileContent);
+                    const previous = manifest.entries[normalizedPath];
+                    if (snapshotMode === 'auto' &&
+                        !forceResnapshot &&
+                        previous &&
+                        previous.sha256 === fileHash &&
+                        previous.size === fileSize) {
+                        snapshotsSkippedUnchanged++;
+                        continue;
+                    }
+                    preparedSnapshots.push({
+                        path: current.path,
+                        normalizedPath,
+                        content: fileContent,
+                        size: fileSize,
+                        sha256: fileHash,
+                    });
                 }
                 catch (error) {
                     snapshotsFailed++;
-                    console.warn(chalk.yellow(`   ⚠️  Failed to save snapshot for ${file.path}: ${error instanceof Error ? error.message : 'Unknown error'}`));
-                    // Continue with other files even if one fails
+                    if (process.env.DEBUG) {
+                        console.warn(chalk.yellow(`   ⚠️  Failed to prepare snapshot for ${current.path}: ${error instanceof Error ? error.message : 'Unknown error'}`));
+                    }
+                }
+            }
+            const reason = `Pre-Plan Snapshot for "${intent.trim()}"`;
+            const markSnapshotSaved = (snapshot, snapshotAt) => {
+                snapshotsSaved++;
+                manifest.entries[snapshot.normalizedPath] = {
+                    sha256: snapshot.sha256,
+                    size: snapshot.size,
+                    snapshotAt: snapshotAt || new Date().toISOString(),
+                };
+                manifestDirty = true;
+            };
+            let pendingFallbackSnapshots = [];
+            if (preparedSnapshots.length > 0) {
+                try {
+                    usedBatchApi = true;
+                    for (let idx = 0; idx < preparedSnapshots.length; idx += snapshotBatchSize) {
+                        if (deadline > 0 && Date.now() >= deadline) {
+                            const remaining = preparedSnapshots.length - idx;
+                            snapshotsSkippedBudget += Math.max(0, remaining);
+                            break;
+                        }
+                        const chunk = preparedSnapshots.slice(idx, idx + snapshotBatchSize);
+                        const result = await withTimeout(client.saveFileVersionsBatch(chunk.map((snapshot) => ({
+                            filePath: snapshot.path,
+                            fileContent: snapshot.content,
+                            changeType: 'modify',
+                            linesAdded: 0,
+                            linesRemoved: 0,
+                        })), finalProjectId, reason), snapshotBatchTimeoutMs);
+                        const chunkByPath = new Map();
+                        for (const snapshot of chunk) {
+                            chunkByPath.set(snapshot.path, snapshot);
+                        }
+                        for (const saved of result.saved || []) {
+                            const prepared = chunkByPath.get(saved.filePath);
+                            if (!prepared)
+                                continue;
+                            markSnapshotSaved(prepared, saved.version?.createdAt);
+                            chunkByPath.delete(saved.filePath);
+                        }
+                        for (const failed of result.failed || []) {
+                            if (chunkByPath.has(failed.filePath)) {
+                                chunkByPath.delete(failed.filePath);
+                            }
+                            snapshotsFailed++;
+                            if (process.env.DEBUG) {
+                                console.warn(chalk.yellow(`   ⚠️  Failed to save snapshot for ${failed.filePath}: ${failed.error}`));
+                            }
+                        }
+                        // Any residual paths were not explicitly reported by API; preserve via fallback.
+                        if (chunkByPath.size > 0) {
+                            pendingFallbackSnapshots.push(...chunkByPath.values());
+                        }
+                    }
+                }
+                catch (error) {
+                    // Backward compatibility: old API versions won't have save-batch endpoint.
+                    if (isBatchSnapshotEndpointUnsupported(error)) {
+                        batchFallbackToSingle = true;
+                        pendingFallbackSnapshots = [...preparedSnapshots];
+                        if (process.env.DEBUG || !options.json) {
+                            console.log(chalk.dim('   Batch snapshot endpoint unavailable; falling back to single-file snapshot uploads.'));
+                        }
+                    }
+                    else {
+                        snapshotsFailed += preparedSnapshots.length;
+                        if (process.env.DEBUG) {
+                            console.warn(chalk.yellow(`   ⚠️  Batch snapshot upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`));
+                        }
+                    }
+                }
+            }
+            if (pendingFallbackSnapshots.length > 0) {
+                let fallbackCursor = 0;
+                const fallbackWorkers = Array.from({ length: Math.min(snapshotConcurrency, pendingFallbackSnapshots.length) }, async () => {
+                    while (true) {
+                        const index = fallbackCursor++;
+                        if (index >= pendingFallbackSnapshots.length) {
+                            return;
+                        }
+                        const snapshot = pendingFallbackSnapshots[index];
+                        if (deadline > 0 && Date.now() >= deadline) {
+                            snapshotsSkippedBudget++;
+                            continue;
+                        }
+                        try {
+                            await withTimeout(client.saveFileVersion(snapshot.path, snapshot.content, finalProjectId, reason, 'modify', 0, 0), snapshotTimeoutMs);
+                            markSnapshotSaved(snapshot);
+                        }
+                        catch (error) {
+                            snapshotsFailed++;
+                            if (process.env.DEBUG) {
+                                console.warn(chalk.yellow(`   ⚠️  Failed to save snapshot for ${snapshot.path}: ${error instanceof Error ? error.message : 'Unknown error'}`));
+                            }
+                        }
+                    }
+                });
+                await Promise.all(fallbackWorkers);
+            }
+            if (manifestDirty) {
+                try {
+                    manifest.updatedAt = new Date().toISOString();
+                    saveSnapshotManifest(cwd, manifest);
+                }
+                catch (manifestError) {
+                    if (process.env.DEBUG) {
+                        console.warn(chalk.yellow(`   ⚠️  Could not persist snapshot manifest: ${manifestError instanceof Error ? manifestError.message : 'Unknown error'}`));
+                    }
                 }
             }
             if (snapshotsSaved > 0) {
                 console.log(chalk.green(`\n✅ ${snapshotsSaved} pre-flight snapshot(s) saved successfully`));
-                if (snapshotsFailed > 0) {
-                    console.log(chalk.yellow(`   ${snapshotsFailed} snapshot(s) failed (plan will continue)`));
-                }
-                console.log(chalk.dim('   You can revert these files using: neurcode revert <filePath> --to-version <version>\n'));
+                console.log(chalk.dim('   You can revert these files using: neurcode revert <filePath> --to-version <version>'));
             }
             else if (snapshotsFailed > 0) {
                 console.log(chalk.yellow(`\n⚠️  No snapshots were saved (${snapshotsFailed} failed)`));
-                console.log(chalk.dim('   Plan will continue, but revert functionality may be limited\n'));
+                console.log(chalk.dim('   Plan will continue, but revert functionality may be limited'));
             }
             else {
-                console.log(chalk.dim('\n   No files to snapshot\n'));
+                console.log(chalk.dim('\n   No new snapshots were required'));
+            }
+            if (snapshotsSkippedUnchanged > 0) {
+                console.log(chalk.dim(`   ${snapshotsSkippedUnchanged} file(s) skipped (unchanged since last snapshot)`));
+            }
+            if (snapshotsSkippedMissing > 0) {
+                console.log(chalk.dim(`   ${snapshotsSkippedMissing} file(s) skipped (not found locally)`));
+            }
+            if (snapshotsSkippedLarge > 0) {
+                console.log(chalk.dim(`   ${snapshotsSkippedLarge} file(s) skipped (size limit)`));
+            }
+            if (cappedCount > 0) {
+                console.log(chalk.dim(`   ${cappedCount} file(s) deferred by snapshot max-file cap (${snapshotMaxFiles})`));
             }
+            if (snapshotsSkippedBudget > 0) {
+                console.log(chalk.dim(`   ${snapshotsSkippedBudget} file(s) deferred by snapshot budget`));
+            }
+            if (usedBatchApi) {
+                console.log(chalk.dim(`   Snapshot transport: batch${batchFallbackToSingle ? ' (with single-file fallback)' : ''}`));
+            }
+            console.log('');
+            snapshotSummary = {
+                mode: snapshotMode,
+                attempted: snapshotCandidates.length,
+                processed: snapshotsProcessed,
+                saved: snapshotsSaved,
+                failed: snapshotsFailed,
+                skippedUnchanged: snapshotsSkippedUnchanged,
+                skippedMissing: snapshotsSkippedMissing,
+                skippedLarge: snapshotsSkippedLarge,
+                skippedBudget: snapshotsSkippedBudget,
+                capped: cappedCount,
+                usedBatchApi,
+                batchFallbackToSingle,
+                durationMs: Date.now() - snapshotStartedAt,
+            };
+        }
+        else {
+            snapshotSummary = {
+                mode: snapshotMode,
+                attempted: 0,
+                processed: 0,
+                saved: 0,
+                failed: 0,
+                skippedUnchanged: 0,
+                skippedMissing: 0,
+                skippedLarge: 0,
+                skippedBudget: 0,
+                capped: 0,
+                usedBatchApi: false,
+                batchFallbackToSingle: false,
+                durationMs: 0,
+            };
         }
         // Step 3: Post-Generation Hallucination Check (DEEP SCAN)
         // Scan ALL plan content for phantom packages - not just summaries, but full proposed code
@@ -1105,6 +1534,26 @@ async function planCommand(intent, options) {
                 console.log(chalk.green('✅ No hallucinations detected'));
             }
         }
+        if (!persistedPlanId) {
+            const missingPlanMessage = 'Plan generated but failed to persist (planId missing). Cannot continue with prompt/apply/ship.';
+            if (options.json) {
+                emitPlanJson({
+                    success: false,
+                    cached: false,
+                    mode: intentMode,
+                    planId: null,
+                    sessionId: response.sessionId || null,
+                    projectId: finalProjectId || null,
+                    timestamp: response.timestamp,
+                    telemetry: response.telemetry,
+                    snapshot: snapshotSummary,
+                    message: missingPlanMessage,
+                    plan: response.plan,
+                });
+            }
+            console.error(chalk.red(`\n❌ ${missingPlanMessage}`));
+            process.exit(2);
+        }
         // Display the plan (AFTER hallucination warnings)
         if (isReadOnlyAnalysis) {
             const writableTargets = response.plan.files.filter((file) => file.action !== 'BLOCK').length;
@@ -1113,13 +1562,13 @@ async function planCommand(intent, options) {
         displayPlan(response.plan);
         console.log(chalk.dim(`\nGenerated at: ${new Date(response.timestamp).toLocaleString()}`));
         // Display plan ID if available
-        if (response.planId && response.planId !== 'unknown') {
+        if (persistedPlanId) {
             console.log(chalk.bold.cyan(`\n📌 Plan ID: ${response.planId} (Saved)`));
             console.log(chalk.dim('   Run \'neurcode prompt \' to generate a Cursor/AI prompt. (Ready now)'));
         }
         // Save sessionId and planId to state file (.neurcode/config.json)
         try {
-            if (response.planId && response.planId !== 'unknown') {
+            if (persistedPlanId) {
                 // Save active plan ID (primary) and lastPlanId (backward compatibility)
                 (0, state_1.setActivePlanId)(response.planId);
                 (0, state_1.setLastPlanGeneratedAt)(new Date().toISOString());
@@ -1135,8 +1584,35 @@ async function planCommand(intent, options) {
                 console.warn(chalk.yellow(`⚠️  Could not save sessionId/planId to state: ${stateError instanceof Error ? stateError.message : 'Unknown error'}`));
             }
         }
+        if (options.json) {
+            emitPlanJson({
+                success: true,
+                cached: false,
+                mode: intentMode,
+                planId: response.planId,
+                sessionId: response.sessionId || null,
+                projectId: finalProjectId || null,
+                timestamp: response.timestamp,
+                telemetry: response.telemetry,
+                snapshot: snapshotSummary,
+                message: 'Plan generated and persisted',
+                plan: response.plan,
+            });
+        }
     }
     catch (error) {
+        if (options.json) {
+            emitPlanJson({
+                success: false,
+                cached: false,
+                mode: 'implementation',
+                planId: null,
+                sessionId: null,
+                projectId: options.projectId || null,
+                timestamp: new Date().toISOString(),
+                message: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
         console.error(chalk.red('\n❌ Error generating plan:'));
         if (error instanceof Error) {
             console.error(chalk.red(error.message));