@contentful/experience-design-system-cli 2.12.0 → 2.12.1-dev-build-589b615.0

package/dist/src/import/tui/WizardApp.js

@@ -4,10 +4,19 @@ import { Box, Text, useStdout } from 'ink';
 import { join, resolve } from 'node:path';
 import { appendFileSync, writeFileSync } from 'node:fs';
 import { access, readFile, stat } from 'node:fs/promises';
-import { homedir, tmpdir } from 'node:os';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { execFile, spawn } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { buildRunTeaserLine } from './run-teaser.js';
+import { PathPrompt } from '../../runs/path-prompt.js';
+import { RunPicker } from '../../runs/run-picker.js';
+import { SaveConflictGate } from '../../runs/save-conflict.js';
+import { detectSaveConflict, buildTimestampedSubdir, resolveSavePath, } from '../../runs/save-path-resolver.js';
+import { appendRun } from '../../runs/store.js';
+import { buildSourceFingerprint, buildSavedFingerprint } from '../../runs/fingerprint.js';
 import { TopBar } from '../../analyze/select/tui/components/TopBar.js';
+import { CustomPromptBanner } from './CustomPromptBanner.js';
 import { WelcomeStep } from './steps/WelcomeStep.js';
 import { PathValidationStep } from './steps/PathValidationStep.js';
 import { RunningStep } from './steps/RunningStep.js';
@@ -17,30 +26,97 @@ import { WizardPreviewStep } from './steps/WizardPreviewStep.js';
 import { DoneStep } from './steps/DoneStep.js';
 import { ErrorStep } from './steps/ErrorStep.js';
 import { TokenInputStep } from './steps/TokenInputStep.js';
-import { GenerateReviewStep } from './steps/GenerateReviewStep.js';
 import { PreviewValidationErrorStep } from './steps/PreviewValidationErrorStep.js';
+import { PushingStep } from './steps/PushingStep.js';
+import { computePushExpected } from './push-progress.js';
+import { nextStateAfterPrint } from './run-print-files-helpers.js';
+import { PushDecisionGateStep } from './steps/PushDecisionGateStep.js';
+import { chooseGateAction } from './push-decision-gate-helpers.js';
 import { ImportApiClient, ApiError } from '../../apply/api-client.js';
 import { handlePreview422, applySkipValidationErrors, clearedValidationErrorState } from './wizard-422-helpers.js';
+import { parseGenerateStderrChunk } from './wizard-generate-progress.js';
+import { spawnGenerateChild } from './spawn-generate.js';
 import { readTokensFromPath, hasBreakingChangesWithImpact } from '../../apply/manifest.js';
 import { buildManifest } from '@contentful/experience-design-system-types';
-import { openPipelineDb, loadCDFComponents, seedCDFFromPreviewResponse, seedDefaultsFromChangedItems, backfillUnclassifiedProps, } from '../../session/db.js';
+import { openPipelineDb, loadCDFComponents, loadScopeComponents, seedCDFFromPreviewResponse, seedDefaultsFromChangedItems, backfillUnclassifiedProps, } from '../../session/db.js';
+import { ScopeGateHost } from './scope-gate-host.js';
+import { FinalReviewHost } from './final-review-host.js';
+import { runScopeGate } from './runScopeGate.js';
+import { buildAutoFilterErrorTail } from './auto-filter-error.js';
 import { checkAgentAuth } from '../../generate/agent-runner.js';
 import { normalizePath } from '../path-utils.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../../host-utils.js';
 import { writeExperiencesCredentials } from '../../credentials-store.js';
+import { nextStepAfterScopeGate, nextStepAfterCredentialsValidated, shouldBypassPreview, buildSkippedPreviewTransition, shouldRefusePush, buildSkippedPushTransition, } from './wizard-state-transitions.js';
 function findCliPath() {
     return join(fileURLToPath(import.meta.url), '..', '..', '..', '..', '..', 'bin', 'cli.js');
 }
-export function buildAnalyzeSelectArgs(opts) {
-    const args = ['analyze', 'select', '--session', opts.sessionId];
-    if (opts.acceptAll) {
-        // The wizard pre-shows validation errors in the analyze-extract TUI before
-        // reaching this gate, so the user has already seen what will be excluded.
-        // Pass --exclude-invalid to bypass the headless fail-loud gate (which is
-        // for CI / scripted callers that need to fail loud) — the wizard surfaces
-        // the auto-rejection via formatAcceptanceSummary on the next screen.
-        args.push('--select-all', '--exclude-invalid');
+export function buildSelectAgentArgs(opts) {
+    // Feature 3: the wizard auto-filter run should never fail-loud on validation
+    // errors — those components surface in the AI-excluded section with a
+    // synthesized reason, not an exit-1 abort. So we always pass --exclude-invalid.
+    const args = ['analyze', 'select-agent', '--agent', opts.agent, '--session', opts.sessionId, '--exclude-invalid'];
+    if (opts.model)
+        args.push('--model', opts.model);
+    if (opts.selectPromptPath)
+        args.push('--select-prompt-path', opts.selectPromptPath);
+    if (opts.noCache)
+        args.push('--no-cache');
+    return args;
+}
+export function parseAutoFilterProgressLine(line) {
+    // Format: progress=select-agent:N/M:<decision>:<name>:<url-encoded-reason>
+    // Name and reason CANNOT contain `:` raw (name comes from component identifier
+    // which forbids colons; reason is URL-encoded). We split with a limit so any
+    // stray colon inside the URL-encoded reason wouldn't matter — but the encoder
+    // also handles `:` as `%3A` so this is defensive.
+    const prefix = 'progress=select-agent:';
+    if (!line.startsWith(prefix))
+        return null;
+    const rest = line.slice(prefix.length);
+    const parts = rest.split(':');
+    if (parts.length < 4)
+        return null;
+    const [counter, decision, name, ...reasonParts] = parts;
+    if (!counter)
+        return null;
+    const counterMatch = /^(\d+)\/(\d+)$/.exec(counter);
+    if (!counterMatch)
+        return null;
+    if (decision !== 'accepted' && decision !== 'rejected')
+        return null;
+    if (!name)
+        return null;
+    const encodedReason = reasonParts.join(':');
+    let reason = '';
+    try {
+        reason = decodeURIComponent(encodedReason);
     }
+    catch {
+        reason = encodedReason;
+    }
+    return {
+        n: Number(counterMatch[1]),
+        total: Number(counterMatch[2]),
+        decision,
+        name,
+        reason,
+    };
+}
+export function buildGenerateComponentsArgs(opts) {
+    // Default behavior preserves the SHA cache (re-runs only re-classify
+    // changed components). The operator opts into a full re-classify pass via
+    // `experiences import --no-cache`, which forwards through to the spawned
+    // `generate components` subprocess. See wizard-cache.test.ts.
+    const args = ['generate', 'components', '--agent', opts.agent, '--session', opts.sessionId];
+    if (opts.tokensPath)
+        args.push('--tokens', opts.tokensPath);
+    if (opts.model)
+        args.push('--model', opts.model);
+    if (opts.noCache)
+        args.push('--no-cache');
+    if (opts.generatePromptPath)
+        args.push('--generate-prompt-path', opts.generatePromptPath);
     return args;
 }
 export function formatAcceptanceSummary(opts) {
@@ -49,16 +125,6 @@ export function formatAcceptanceSummary(opts) {
         return `${acceptedClause}.`;
     return `${acceptedClause}, ${opts.autoRejected} excluded due to validation errors.`;
 }
-export function formatGeneratedSummary(opts) {
-    const generatedClause = `Generated definitions for ${opts.generated} component${opts.generated === 1 ? '' : 's'}.`;
-    const renamedClause = opts.renamedSlots > 0
-        ? ` ${opts.renamedSlots} unnamed slot${opts.renamedSlots === 1 ? '' : 's'} renamed (children / slot_<n>) so the LLM could classify them.`
-        : '';
-    const exclusionClause = opts.autoRejected > 0
-        ? ` ${opts.autoRejected} component${opts.autoRejected === 1 ? '' : 's'} excluded earlier due to validation errors.`
-        : '';
-    return `${generatedClause}${renamedClause}${exclusionClause}`;
-}
 function runCli(args) {
     return new Promise((res) => {
         execFile('node', [findCliPath(), ...args], (error, stdout, stderr) => {
@@ -66,12 +132,22 @@ function runCli(args) {
         });
     });
 }
+/**
+ * Parse the `wrote tokens.json (N tokens)` confirmation line emitted by
+ * `experiences print tokens`. Returns 0 when the line cannot be parsed —
+ * the wizard still records the run; downstream consumers should treat 0 as
+ * "unknown" rather than "no tokens".
+ */
+export function parsePrintTokensCount(stdout) {
+    const m = /\((\d+)\s+token/.exec(stdout);
+    return m ? Number(m[1]) : 0;
+}
 const WIZARD_LOG = join(tmpdir(), 'experiences-import-wizard.log');
 function logStep(entry) {
     const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n';
     appendFileSync(WIZARD_LOG, line);
 }
-export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialProjectPath, host, } = {}) {
+export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope = false, noCache = false, autoFilter = true, livePreview = true, noPush = false, noSave = false, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, initialStep, initialRawTokensPath, initialRuns, onRunPicked, } = {}) {
     const defaultConfiguredHost = toConfiguredHost(host || process.env['EDS_HOST']) ?? DEFAULT_CONFIGURED_HOST;
     const resolveWizardHost = (hostValue) => hostValue || defaultConfiguredHost;
     const { stdout } = useStdout();
@@ -86,18 +162,57 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         extractSessionId: null,
         tokensPath: '',
     });
+    // Feature 3: holds the spawned `analyze select-agent` subprocess so the
+    // scope-gate's `q` (during running) can SIGTERM it for cancellation.
+    const autoFilterChildRef = useRef(null);
+    // Promise that resolves when the auto-filter subprocess fully exits. Used
+    // by `cancelAutoFilterAndWait` so scope-gate confirm can guarantee its
+    // snapshot write goes AFTER the subprocess's last write.
+    const autoFilterDonePromiseRef = useRef(null);
+    // Background `generate components` subprocess spawned from scope-gate
+    // confirm so its LLM call overlaps with the operator's credential entry.
+    // Held in refs so we can SIGTERM on credential failure / quit, and await
+    // the promise from inside `validateCredentials` once creds come back OK.
+    const generateChildRef = useRef(null);
+    const generatePromiseRef = useRef(null);
+    // Modify-entry short-circuit: when the launcher passes seed session IDs
+    // and `initialStep: 'final-review'`, skip the welcome/token-input bootstrap
+    // and land directly on the post-generate review screen. The DB-backed
+    // GenerateReviewStep loads its data off `state.extractSessionId`, so all
+    // we need to do here is seed the IDs and the step.
+    const modifyEntryReady = !!seedExtractSessionId && initialStep === 'final-review';
+    // Headless raw-tokens entry: when the operator passed `--raw-tokens <path>`
+    // the CLI seeds this prop. Skip welcome + token-input and land on the
+    // `generating-tokens` step which already drives the token-classification
+    // subprocess off `state.rawTokensPath`. Modify-entry wins if both are set.
+    const rawTokensEntryReady = !modifyEntryReady && !!initialRawTokensPath;
+    const initialStepResolved = modifyEntryReady
+        ? 'final-review'
+        : rawTokensEntryReady
+            ? 'generating-tokens'
+            : initialProjectPath
+                ? 'token-input'
+                : 'welcome';
+    const initialOutDir = initialProjectPath ? join(resolve(initialProjectPath), '.contentful') : '';
+    const initialTokensPath = modifyEntryReady && initialOutDir ? join(initialOutDir, 'tokens.json') : '';
     const [state, setState] = useState({
-        step: initialProjectPath ? 'token-input' : 'welcome',
+        step: modifyEntryReady || rawTokensEntryReady
+            ? initialStepResolved
+            : initialRuns && initialRuns.length > 0
+                ? 'run-picker'
+                : initialStepResolved,
         agent: initialAgent ?? 'claude',
+        ...(initialModel ? { agentModel: initialModel } : {}),
         projectPath: initialProjectPath ?? '',
-        outDir: initialProjectPath ? join(resolve(initialProjectPath), '.contentful') : '',
-        rawTokensPath: '',
-        tokensPath: '',
+        outDir: initialOutDir,
+        rawTokensPath: rawTokensEntryReady ? initialRawTokensPath : '',
+        tokensPath: initialTokensPath,
         tokenSourceChanged: null,
         skipComponents: false,
-        tokenSessionId: null,
-        extractSessionId: null,
-        generateSessionId: null,
+        tokenSessionId: seedTokenSessionId ?? null,
+        tokenCount: 0,
+        extractSessionId: seedExtractSessionId ?? null,
+        generateSessionId: seedGenerateSessionId ?? null,
         extractedCount: 0,
         acceptedCount: 0,
         autoRejectedCount: 0,
@@ -115,9 +230,10 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         serverPreview: null,
         manifest: null,
         pushProgress: null,
+        pushExpected: null,
         pushResult: {
-            componentTypes: { created: 0, updated: 0, failed: 0 },
-            designTokens: { created: 0, updated: 0, failed: 0 },
+            componentTypes: { created: 0, updated: 0, removed: 0, failed: 0 },
+            designTokens: { created: 0, updated: 0, removed: 0, failed: 0 },
         },
         errorStep: '',
         errorMessage: '',
@@ -125,6 +241,15 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         authCheckStepNumber: 1,
         previewValidationErrors: [],
         previewValidationMissingNames: [],
+        aiFilterStatus: 'idle',
+        aiFilterProgress: null,
+        aiDecisions: {},
+        aiFilterError: null,
+        credentialsValidating: false,
+        generatePrefetchStatus: 'idle',
+        generatePrefetchError: null,
+        credentialsSkipped: false,
+        lastRunId: null,
     });
     useEffect(() => {
         sessionRef.current = {
@@ -209,15 +334,10 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     // ── Step runners ────────────────────────────────────────────────────────
     const runGenerateTokens = async (rawTokensPath, outDir) => {
         const result = await new Promise((res) => {
-            const child = spawn('node', [
-                findCliPath(),
-                'generate',
-                'tokens',
-                '--agent',
-                state.agent,
-                '--raw-tokens',
-                rawTokensPath,
-            ]);
+            const tokenArgs = [findCliPath(), 'generate', 'tokens', '--agent', state.agent, '--raw-tokens', rawTokensPath];
+            if (state.agentModel)
+                tokenArgs.push('--model', state.agentModel);
+            const child = spawn('node', tokenArgs);
             let stdout = '';
             let stderr = '';
             child.stdout.on('data', (d) => {
@@ -251,7 +371,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
             return;
         }
-        update({ step: 'path-validation', tokensPath, tokenSessionId });
+        const tokenCount = parsePrintTokensCount(r.stdout);
+        update({ step: 'path-validation', tokensPath, tokenSessionId, tokenCount });
     };
     const runExtract = async (projectPath) => {
         const outDir = join(resolve(projectPath), '.contentful');
@@ -321,93 +442,249 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             return;
         }
         update({
-            step: 'review-extraction-gate',
+            step: 'scope-gate',
             extractSessionId,
             extractedCount,
+            aiFilterStatus: autoFilter ? 'running' : 'idle',
+            aiFilterProgress: autoFilter ? { done: 0, total: extractedCount } : null,
+            aiDecisions: {},
+            aiFilterError: null,
         });
+        if (autoFilter && extractSessionId) {
+            autoFilterDonePromiseRef.current = runAutoFilter(extractSessionId);
+        }
     };
-    const runAnalyzeSelect = async (sessionId, extractedCount, tokensPath, acceptAll) => {
-        logStep({
-            fn: 'runAnalyzeSelect:enter',
-            sessionId,
-            extractedCount,
-            acceptAll,
+    // Feature 3: spawn `analyze select-agent` after extract and stream decisions
+    // into wizard state via stderr progress lines. The subprocess writes
+    // `raw_components.status` + `reject_reason` itself (see Task 2), so the
+    // scope-gate UI re-loads via `loadScopeComponents` to get fresh data on every
+    // render — but we also keep a memory-side `aiDecisions` map for streaming UX.
+    const runAutoFilter = (sessionId) => {
+        return new Promise((res) => {
+            const args = buildSelectAgentArgs({
+                sessionId,
+                agent: state.agent,
+                ...(state.agentModel ? { model: state.agentModel } : {}),
+                selectPromptPath,
+                noCache,
+            });
+            const child = spawn('node', [findCliPath(), ...args]);
+            autoFilterChildRef.current = child;
+            let stderr = '';
+            child.stderr.on('data', (d) => {
+                const chunk = String(d);
+                stderr += chunk;
+                for (const line of chunk.split('\n')) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    const parsed = parseAutoFilterProgressLine(trimmed);
+                    if (!parsed)
+                        continue;
+                    setState((prev) => ({
+                        ...prev,
+                        aiFilterProgress: { done: parsed.n, total: parsed.total },
+                        aiDecisions: {
+                            ...prev.aiDecisions,
+                            [parsed.name]: { decision: parsed.decision, reason: parsed.reason },
+                        },
+                    }));
+                }
+            });
+            // Use 'close' (not 'exit') so the status flip happens after the child's
+            // stdio AND its inherited SQLite WAL/SHM file handles have been fully
+            // released by the OS. 'exit' fires the instant the process terminates;
+            // setting state then triggers a wizard re-render that re-opens
+            // pipeline.db from the scope-gate step, and the lock from the dead
+            // child's still-mapped WAL handle surfaces as "database is locked".
+            child.on('close', (code, signal) => {
+                autoFilterChildRef.current = null;
+                if (signal === 'SIGTERM') {
+                    setState((prev) => ({ ...prev, aiFilterStatus: 'cancelled' }));
+                }
+                else if ((code ?? 0) !== 0) {
+                    const tail = buildAutoFilterErrorTail(stderr);
+                    setState((prev) => ({
+                        ...prev,
+                        aiFilterStatus: 'failed',
+                        aiFilterError: tail || `exit ${code}`,
+                    }));
+                }
+                else {
+                    setState((prev) => ({ ...prev, aiFilterStatus: 'complete' }));
+                }
+                res();
+            });
+            child.on('error', (err) => {
+                autoFilterChildRef.current = null;
+                setState((prev) => ({
+                    ...prev,
+                    aiFilterStatus: 'failed',
+                    aiFilterError: err.message,
+                }));
+                res();
+            });
         });
-        let acceptedCount;
-        if (!acceptAll && state.serverPreview && !process.env['EDS_PREVIEW_ANNOTATIONS']) {
-            process.env['EDS_PREVIEW_ANNOTATIONS'] = JSON.stringify(buildPreviewAnnotations(state.serverPreview));
-        }
-        if (!acceptAll) {
-            update({ step: 'analyze-select' });
+    };
+    const cancelAutoFilter = () => {
+        const child = autoFilterChildRef.current;
+        if (child && !child.killed) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // best-effort
+            }
         }
-        const args = buildAnalyzeSelectArgs({ sessionId, acceptAll });
-        const r = acceptAll ? await runCli(args) : await runCliInteractive(args);
-        logStep({ fn: 'runAnalyzeSelect:post-spawn', exitCode: r.exitCode, args });
-        if (!acceptAll)
-            clearPreviewEnvVars();
-        if (r.exitCode !== 0) {
-            update({
-                step: 'error',
-                errorStep: 'analyze select',
-                errorMessage: r.stderr.trim() || 'Unknown error',
-            });
+    };
+    // Variant that returns a Promise resolving when the subprocess has fully
+    // exited. Used by scope-gate confirm to guarantee operator-write-last
+    // ordering on the review-state snapshot (PR #43 race fix).
+    const cancelAutoFilterAndWait = async () => {
+        const child = autoFilterChildRef.current;
+        const donePromise = autoFilterDonePromiseRef.current;
+        if (!child || child.killed) {
+            // Subprocess already gone (or never started). If the Promise is still
+            // pending — e.g. exit handler hasn't fired yet — await it; otherwise
+            // resolve immediately.
+            if (donePromise)
+                await donePromise;
             return;
         }
-        // Read accepted count from the review state file (since TUI subprocess inherits stdio
-        // in the manual review path; in the bulk path we also persist to the same file).
-        // Also extract auto-rejected count (components with error-severity validation issues
-        // dropped by the gate) so the user sees what was excluded on the next step.
-        const artifactsRoot = process.env['EDS_REVIEW_ARTIFACTS_DIR']
-            ? resolve(process.env['EDS_REVIEW_ARTIFACTS_DIR'])
-            : resolve(homedir(), '.contentful', 'experience-design-system-cli', 'reviews');
-        const reviewStatePath = resolve(artifactsRoot, sessionId, 'current-review-state.json');
-        let autoRejectedCount = 0;
         try {
-            const reviewState = JSON.parse(await readFile(reviewStatePath, 'utf8'));
-            acceptedCount = reviewState.components.filter((c) => c.status === 'accepted').length;
-            autoRejectedCount = reviewState.components.filter((c) => c.status === 'rejected' && (c.originalProposal.validationIssues ?? []).some((i) => i.severity === 'error')).length;
+            child.kill('SIGTERM');
         }
         catch {
-            acceptedCount = extractedCount;
+            // best-effort
         }
-        update({ acceptedCount, autoRejectedCount });
-        if (acceptedCount > 0) {
-            if (await runAgentAuthCheck('generating')) {
-                void runGenerate(sessionId, tokensPath, acceptedCount);
+        if (donePromise)
+            await donePromise;
+    };
+    // Cancel a running generation prefetch (SIGTERM the child + clear refs +
+    // reset state). Best-effort — if the child has already exited, this is a
+    // no-op aside from clearing the prefetch status.
+    const cancelGeneratePrefetch = () => {
+        const child = generateChildRef.current;
+        if (child && !child.killed) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // best-effort
             }
         }
-        else {
-            advanceToPushFlow(0);
-        }
+        generateChildRef.current = null;
+        generatePromiseRef.current = null;
+        setState((prev) => ({
+            ...prev,
+            generatePrefetchStatus: 'idle',
+            generatePrefetchError: null,
+            generateProgress: null,
+        }));
+    };
+    // Spawn `generate components` in the background. Wires up the same
+    // stderr-progress streaming as `runGenerate` but stores the in-flight
+    // promise in a ref so the post-credentials path can await it.
+    const startGeneratePrefetch = (extractSessionId, tokensPath) => {
+        const args = [
+            findCliPath(),
+            ...buildGenerateComponentsArgs({
+                sessionId: extractSessionId,
+                tokensPath,
+                agent: state.agent,
+                ...(state.agentModel ? { model: state.agentModel } : {}),
+                noCache,
+            }),
+        ];
+        let progressCursor = null;
+        const { child, donePromise } = spawnGenerateChild({
+            command: 'node',
+            args,
+            onStderr: (chunk) => {
+                const nextProgress = parseGenerateStderrChunk(chunk, progressCursor);
+                if (nextProgress !== progressCursor) {
+                    progressCursor = nextProgress;
+                    setState((prev) => ({ ...prev, generateProgress: nextProgress }));
+                }
+            },
+        });
+        generateChildRef.current = child;
+        generatePromiseRef.current = donePromise;
+        setState((prev) => ({
+            ...prev,
+            generatePrefetchStatus: 'running',
+            generatePrefetchError: null,
+        }));
+        donePromise
+            .then((result) => {
+            // Clear the child ref regardless of how it ended.
+            generateChildRef.current = null;
+            if (result.signal === 'SIGTERM') {
+                // Caller already reset state via cancelGeneratePrefetch.
+                return;
+            }
+            if (result.exitCode !== 0) {
+                const tail = result.stderr.trim().split('\n').slice(-3).join('\n') || `exit ${result.exitCode}`;
+                setState((prev) => ({
+                    ...prev,
+                    generatePrefetchStatus: 'failed',
+                    generatePrefetchError: tail,
+                    generateProgress: null,
+                }));
+                return;
+            }
+            const sessionMatch = /^session=(.+)$/m.exec(result.stdout);
+            const generateSessionId = sessionMatch ? sessionMatch[1].trim() : null;
+            const countMatch = /(\d+) components?/.exec(result.stderr);
+            const generatedCount = countMatch ? Number(countMatch[1]) : 0;
+            const renamedMatch = /^renamed-slots:\s*(\d+)$/m.exec(result.stdout);
+            const renamedSlotsCount = renamedMatch ? Number(renamedMatch[1]) : 0;
+            // Persist generated state but DO NOT auto-advance — the credentials
+            // path will pick this up via `advanceAfterCredentialsValidated`.
+            setState((prev) => ({
+                ...prev,
+                generateSessionId,
+                generatedCount,
+                renamedSlotsCount,
+                generateProgress: null,
+                generatePrefetchStatus: 'complete',
+            }));
+        })
+            .catch(() => {
+            generateChildRef.current = null;
+            setState((prev) => ({
+                ...prev,
+                generatePrefetchStatus: 'failed',
+                generatePrefetchError: 'subprocess error',
+            }));
+        });
+        return donePromise;
     };
     const runGenerate = async (extractSessionId, tokensPath, acceptedCount) => {
-        const result = await new Promise((res) => {
-            const args = [findCliPath(), 'generate', 'components', '--agent', state.agent, '--session', extractSessionId];
-            if (tokensPath)
-                args.push('--tokens', tokensPath);
-            const child = spawn('node', args);
-            let stdout = '';
-            let stderr = '';
-            child.stdout.on('data', (d) => {
-                stdout += String(d);
-            });
-            child.stderr.on('data', (d) => {
-                const chunk = String(d);
-                stderr += chunk;
-                for (const line of chunk.split('\n')) {
-                    const m = /\[(\d+)\/(\d+)\]\s+(.+)/.exec(line);
-                    if (m)
-                        update({
-                            generateProgress: {
-                                done: Number(m[1]),
-                                total: Number(m[2]),
-                                current: m[3].trim(),
-                            },
-                        });
+        const args = [
+            findCliPath(),
+            ...buildGenerateComponentsArgs({
+                sessionId: extractSessionId,
+                tokensPath,
+                agent: state.agent,
+                ...(state.agentModel ? { model: state.agentModel } : {}),
+                noCache,
+                generatePromptPath,
+            }),
+        ];
+        let progressCursor = state.generateProgress;
+        const { donePromise } = spawnGenerateChild({
+            command: 'node',
+            args,
+            onStderr: (chunk) => {
+                const nextProgress = parseGenerateStderrChunk(chunk, progressCursor);
+                if (nextProgress !== progressCursor) {
+                    progressCursor = nextProgress;
+                    update({ generateProgress: nextProgress });
                 }
-            });
-            child.on('exit', (code) => res({ exitCode: code ?? 0, stdout, stderr }));
+            },
         });
+        const result = await donePromise;
         if (result.exitCode !== 0) {
             update({
                 step: 'error',
@@ -423,7 +700,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         const renamedMatch = /^renamed-slots:\s*(\d+)$/m.exec(result.stdout);
         const renamedSlotsCount = renamedMatch ? Number(renamedMatch[1]) : 0;
         update({
-            step: 'review-generated-gate',
+            step: 'final-review',
             generateSessionId,
             generatedCount,
             renamedSlotsCount,
@@ -433,97 +710,9 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const advanceToPushFlow = (generatedAcceptedCount) => {
         update({ generatedAcceptedCount, step: 'credentials' });
     };
-    const runGenerateEdit = async (sessionId, generatedCount, acceptAll, returnToPreview = false) => {
-        let generatedAcceptedCount;
-        if (acceptAll) {
-            generatedAcceptedCount = generatedCount;
-        }
-        else {
-            update({ step: 'generate-edit' });
-            if (sessionId) {
-                const r = await runCliInteractive(['generate', 'components', 'edit', '--session', sessionId]);
-                if (r.exitCode !== 0) {
-                    update({
-                        step: 'error',
-                        errorStep: 'generate edit',
-                        errorMessage: r.stderr.trim() || 'Unknown error',
-                    });
-                    return;
-                }
-                const acceptedMatch = /Accepted: (\d+)/.exec(r.stderr);
-                generatedAcceptedCount = acceptedMatch ? Number(acceptedMatch[1]) : generatedCount;
-            }
-            else {
-                generatedAcceptedCount = generatedCount;
-            }
-        }
-        if (returnToPreview) {
-            const { extractSessionId, tokensPath } = sessionRef.current;
-            void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
-        }
-        else {
-            advanceToPushFlow(generatedAcceptedCount);
-        }
-    };
-    const setPreviewEnvVars = () => {
-        const creds = credentialsRef.current;
-        const cmaToken = creds?.cmaToken || state.cmaToken;
-        const spaceId = creds?.spaceId || state.spaceId;
-        const environmentId = creds?.environmentId || state.environmentId;
-        if (cmaToken)
-            process.env['EDS_CMA_TOKEN'] = cmaToken;
-        if (spaceId)
-            process.env['EDS_SPACE_ID'] = spaceId;
-        if (environmentId)
-            process.env['EDS_ENVIRONMENT_ID'] = environmentId;
-        process.env['EDS_TOKENS_PATH'] = state.tokensPath || '';
-    };
-    const clearPreviewEnvVars = () => {
-        delete process.env['EDS_PREVIEW_ANNOTATIONS'];
-        delete process.env['EDS_PREVIEW_COUNTS'];
-        delete process.env['EDS_CMA_TOKEN'];
-        delete process.env['EDS_SPACE_ID'];
-        delete process.env['EDS_ENVIRONMENT_ID'];
-        delete process.env['EDS_TOKENS_PATH'];
-    };
-    const runEditFromPreview = async (preview) => {
-        const sessionId = state.extractSessionId;
-        if (!sessionId) {
-            update({
-                step: 'error',
-                errorStep: 'edit definitions',
-                errorMessage: 'No session available for editing',
-            });
-            return;
-        }
-        process.env['EDS_PREVIEW_ANNOTATIONS'] = JSON.stringify(buildPreviewAnnotations(preview));
-        if (preview) {
-            process.env['EDS_PREVIEW_COUNTS'] = JSON.stringify({
-                compNew: preview.components.new.length,
-                compChanged: preview.components.changed.length,
-                compRemoved: preview.components.removed.length,
-                compUnchanged: preview.components.unchanged.length,
-                tokNew: preview.tokens.new.length,
-                tokChanged: preview.tokens.changed.length,
-                tokRemoved: preview.tokens.removed.length,
-                tokUnchanged: preview.tokens.unchanged.length,
-            });
-        }
-        setPreviewEnvVars();
-        update({ step: 'analyze-select' });
-        const r = await runCliInteractive(['analyze', 'select', '--session', sessionId]);
-        clearPreviewEnvVars();
-        if (r.exitCode !== 0) {
-            update({
-                step: 'error',
-                errorStep: 'edit definitions',
-                errorMessage: 'Editor exited with an error',
-            });
-            return;
-        }
-        // Re-preview with updated definitions
-        const { extractSessionId: sid, tokensPath: tp } = sessionRef.current;
-        void runPreview(sid, tp, state.spaceId, state.environmentId, state.cmaToken, state.host);
+    const runEditFromPreview = async () => {
+        // Post-preview edits land in the unified final-review screen.
+        update({ step: 'final-review' });
     };
     const runSkipValidationErrorsAndRetry = async (errors) => {
         await applySkipValidationErrors(state.extractSessionId, errors);
@@ -533,14 +722,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const advanceWithCredentials = (spaceId, environmentId, cmaToken, host) => {
         const resolvedHost = resolveWizardHost(host);
         credentialsRef.current = { spaceId, environmentId, cmaToken };
-        update({
-            spaceId,
-            environmentId,
-            cmaToken,
-            host: resolvedHost,
-            credentialsError: '',
-            step: 'credential-test-gate',
-        });
+        // The dedicated `credential-test-gate` screen was dropped — credentials are
+        // now always validated immediately after they're persisted. The inline
+        // `credentialsValidating` status (PR #54) handles the visual feedback while
+        // the API ping is in flight. The literal `'credential-test-gate'` is kept
+        // in the WizardStep union for back-compat, but is never set as a step.
+        void validateCredentials(spaceId, environmentId, cmaToken, resolvedHost);
     };
     const confirmCredentials = async (spaceId, environmentId, cmaToken, host) => {
         const resolvedHost = resolveWizardHost(host);
@@ -566,7 +753,9 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
     };
     const validateCredentials = async (spaceId, environmentId, cmaToken, host) => {
-        update({ step: 'validating-credentials' });
+        // Inline validation: stay on the credentials step, flip the validating
+        // boolean so CredentialsStep locks input + renders an inline status.
+        update({ step: 'credentials', credentialsValidating: true, credentialsError: '' });
         try {
             const resolvedHost = resolveWizardHost(host);
             const client = new ImportApiClient({
@@ -576,24 +765,89 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 host: resolvedHost,
             });
             await client.validateToken();
-            const { extractSessionId, tokensPath } = sessionRef.current;
-            void runPreview(extractSessionId, tokensPath, spaceId, environmentId, cmaToken, resolvedHost);
+            update({ credentialsValidating: false });
+            await advanceAfterCredentialsValidated();
         }
         catch (e) {
             if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
-                update({ step: 'credentials', credentialsError: e.message });
+                // Validation failure: cancel any in-flight generate prefetch so we
+                // don't leave an orphaned subprocess running after the operator backs
+                // out (Risk #1 in the spec).
+                cancelGeneratePrefetch();
+                update({ step: 'credentials', credentialsValidating: false, credentialsError: e.message });
                 return;
             }
             const msg = e instanceof Error ? e.message : 'Credential check failed';
+            cancelGeneratePrefetch();
             update({
                 step: 'error',
                 errorStep: 'validating-credentials',
                 errorMessage: msg,
                 errorAllowCredentialRetry: false,
+                credentialsValidating: false,
             });
         }
     };
+    // Branch after credentials are known good (validated, or skipped via the
+    // credential-test-gate skip path). Either runs the generator (if there are
+    // accepted components) or jumps straight to push-decision-gate (if scope
+    // rejected everything but tokens/removals still need to be pushed).
+    const advanceAfterCredentialsValidated = async () => {
+        // If we already ran the generator (re-entering credentials from a late
+        // 401/403 raised by runPreview), skip back to push-decision-gate rather
+        // than re-running the LLM.
+        if (state.generateSessionId) {
+            update({ step: 'push-decision-gate' });
+            return;
+        }
+        const next = nextStepAfterCredentialsValidated({ acceptedCount: state.acceptedCount });
+        if (next === 'generating') {
+            const sid = sessionRef.current.extractSessionId;
+            if (!sid) {
+                update({
+                    step: 'error',
+                    errorStep: 'post-credentials',
+                    errorMessage: 'Internal error: extract session ID missing after credential validation.',
+                });
+                return;
+            }
+            // Prefetch path: if a background generate is already running or has
+            // already completed, await it (or use its result) instead of spawning
+            // a second LLM call. Transition to 'generating' first so the operator
+            // sees the familiar RunningStep progress screen while we wait —
+            // matching the no-prefetch flow's visual.
+            const inflight = generatePromiseRef.current;
+            if (inflight) {
+                update({ step: 'generating' });
+                const result = await inflight;
+                generatePromiseRef.current = null;
+                if (result.exitCode === 0 && result.signal !== 'SIGTERM') {
+                    // The donePromise.then() handler already populated
+                    // generateSessionId / generatedCount in state. Advance to
+                    // final-review using the latest values via functional setState so
+                    // we read whichever update landed last.
+                    setState((prev) => ({ ...prev, step: 'final-review' }));
+                    return;
+                }
+                // Prefetch failed — fall through to retry via a fresh runGenerate.
+            }
+            if (await runAgentAuthCheck('generating')) {
+                void runGenerate(sid, state.tokensPath, state.acceptedCount);
+            }
+            return;
+        }
+        update({ step: 'push-decision-gate' });
+    };
     const runPreview = async (extractSessionId, tokensPath, spaceId, environmentId, cmaToken, host) => {
+        // Skip-credentials short-circuit. When the operator pressed `s` on the
+        // credentials screen, we never got a working token — calling
+        // previewImport would 401/403 (or worse, send a half-formed manifest
+        // somewhere). Jump straight to the push-decision-gate; Task 3 disables
+        // the push options downstream.
+        if (shouldBypassPreview(state)) {
+            update(buildSkippedPreviewTransition());
+            return;
+        }
         update({ step: 'previewing' });
         const resolvedHost = resolveWizardHost(host);
         try {
@@ -721,6 +975,16 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
     };
     const runPush = async (manifest, spaceId, environmentId, cmaToken, host, acknowledgeBreakingChanges, preview) => {
+        // Skip-credentials defensive guard. The push-decision-gate disables
+        // push-emitting choices when `credentialsSkipped` is true, so we
+        // should never get here in practice. But if a state-machine bug or
+        // future regression ever did, refuse to issue the API call — there
+        // is no validated token and the operator explicitly opted out of
+        // push. Route back to the local-save (print-gate) path instead.
+        if (shouldRefusePush(state)) {
+            update(buildSkippedPushTransition());
+            return;
+        }
         if (preview) {
             const hasComponentChanges = preview.components.new.length > 0 ||
                 preview.components.changed.length > 0 ||
@@ -730,14 +994,15 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 update({
                     step: 'done',
                     pushResult: {
-                        componentTypes: { created: 0, updated: 0, failed: 0 },
-                        designTokens: { created: 0, updated: 0, failed: 0 },
+                        componentTypes: { created: 0, updated: 0, removed: 0, failed: 0 },
+                        designTokens: { created: 0, updated: 0, removed: 0, failed: 0 },
                     },
                 });
                 return;
             }
         }
-        update({ step: 'pushing' });
+        const pushExpected = preview ? computePushExpected(preview) : null;
+        update({ step: 'pushing', pushExpected, pushProgress: null });
         try {
             const resolvedHost = resolveWizardHost(host);
             const client = new ImportApiClient({
@@ -760,7 +1025,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 process.stderr.write(`[eds] log write failed: ${err instanceof Error ? err.message : String(err)}\n`);
             }
             update({
-                pushProgress: `Queued (operation ${operation.sys.id.slice(0, 8)}...)`,
+                pushProgress: { kind: 'queued', operationId: operation.sys.id },
             });
             let pollCount = 0;
             operation = await client.pollOperation(operation.sys.id, {
@@ -769,7 +1034,15 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     const s = op.summary;
                     if (s) {
                         const done = s.total - s.pending;
-                        update({ pushProgress: `${done}/${s.total} entities processed` });
+                        const items = op.items ?? [];
+                        // Best-effort fresh signal: pick the most recently succeeded item
+                        // (the API does not surface an in-progress status today). Falls
+                        // back to null and the PushingStep hides the line.
+                        const lastDone = items.length > 0 ? items[items.length - 1] : null;
+                        const current = lastDone && lastDone.status === 'succeeded' ? lastDone.id : null;
+                        update({
+                            pushProgress: { kind: 'progress', processed: done, total: s.total, current },
+                        });
                     }
                     try {
                         logStep({
@@ -806,11 +1079,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     componentTypes: {
                         created: items.filter((i) => i.entityType === 'ComponentType' && i.action === 'create' && i.status === 'succeeded').length,
                         updated: items.filter((i) => i.entityType === 'ComponentType' && i.action === 'update' && i.status === 'succeeded').length,
+                        removed: items.filter((i) => i.entityType === 'ComponentType' && i.action === 'delete' && i.status === 'succeeded').length,
                         failed: items.filter((i) => i.entityType === 'ComponentType' && i.status === 'failed').length,
                     },
                     designTokens: {
                         created: items.filter((i) => i.entityType === 'DesignToken' && i.action === 'create' && i.status === 'succeeded').length,
                         updated: items.filter((i) => i.entityType === 'DesignToken' && i.action === 'update' && i.status === 'succeeded').length,
+                        removed: items.filter((i) => i.entityType === 'DesignToken' && i.action === 'delete' && i.status === 'succeeded').length,
                         failed: items.filter((i) => i.entityType === 'DesignToken' && i.status === 'failed').length,
                     },
                     summary: operation.summary,
@@ -822,11 +1097,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     componentTypes: {
                         created: preview?.components.new.length ?? 0,
                         updated: preview?.components.changed.length ?? 0,
+                        removed: preview?.components.removed.length ?? 0,
                         failed: 0,
                     },
                     designTokens: {
                         created: preview?.tokens.new.length ?? 0,
                         updated: preview?.tokens.changed.length ?? 0,
+                        removed: preview?.tokens.removed.length ?? 0,
                         failed: 0,
                     },
                     summary: operation.summary,
@@ -844,7 +1121,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
         }
     };
-    const runPrintFiles = async (extractSessionId, outDir) => {
+    const runPrintFiles = async (extractSessionId, outDir, opts = {}) => {
         update({ step: 'printing' });
         const componentsPath = join(outDir, 'components.json');
         const printArgs = ['print', 'components', '--out', componentsPath];
@@ -857,10 +1134,142 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 errorStep: 'print components',
                 errorMessage: r.stderr.trim() || 'Unknown error',
             });
+            return { ok: false };
+        }
+        // Co-locate tokens.json with components.json. Without this, `--out-dir`
+        // would move components.json to the operator's chosen path while leaving
+        // tokens.json behind at <projectPath>/.contentful/tokens.json.
+        let emittedTokensPath;
+        let emittedTokenCount;
+        if (opts.tokenSessionId) {
+            const tokensOut = join(outDir, 'tokens.json');
+            const tokenArgs = ['print', 'tokens', '--out', tokensOut, '--session', opts.tokenSessionId];
+            const tr = await runCli(tokenArgs);
+            if (tr.exitCode !== 0) {
+                update({
+                    step: 'error',
+                    errorStep: 'print tokens',
+                    errorMessage: tr.stderr.trim() || 'Unknown error',
+                });
+                return { ok: false };
+            }
+            emittedTokensPath = tokensOut;
+            emittedTokenCount = parsePrintTokensCount(tr.stdout);
+        }
+        update(nextStateAfterPrint({ skipGate: opts.skipGate, componentsPath }));
+        return {
+            ok: true,
+            ...(emittedTokensPath ? { tokensPath: emittedTokensPath } : {}),
+            ...(typeof emittedTokenCount === 'number' ? { tokenCount: emittedTokenCount } : {}),
+        };
+    };
+    const runSaveAndPush = async () => {
+        await startSaveFlow({ skipGate: true, andPush: true });
+    };
+    // ── Task 4: save-path orchestration ────────────────────────────────────────
+    // Wraps every `runPrintFiles` site. When `--out-dir` is set we skip the
+    // inline prompt and conflict gate entirely. Otherwise the wizard transitions
+    // to the path-prompt step; the operator's submit handler calls back into
+    // `proceedToWrite` (which may surface the conflict gate).
+    const pendingSaveOptionsRef = useRef({});
+    const startSaveFlow = async (opts = {}) => {
+        pendingSaveOptionsRef.current = opts;
+        if (outDirOverride) {
+            await mkdir(outDirOverride, { recursive: true });
+            if (onConflictMode) {
+                const resolved = await resolveSavePath(outDirOverride, { onConflict: onConflictMode });
+                if (resolved.kind === 'fail') {
+                    const files = resolved.conflict.files.join(', ');
+                    process.stderr.write(`Error: --on-conflict fail — refusing to overwrite ${files} at ${resolved.conflict.path}.\n`);
+                    process.exit(1);
+                    return;
+                }
+                if (resolved.kind === 'write') {
+                    await mkdir(resolved.path, { recursive: true });
+                    await proceedToWrite(resolved.path);
+                    return;
+                }
+            }
+            await proceedToWrite(outDirOverride);
             return;
         }
-        // tokensPath is already on disk from generate-tokens step; just record it
-        update({ step: 'print-gate', componentsPath });
+        setState((prev) => ({ ...prev, step: 'path-prompt' }));
+    };
+    const proceedToWrite = async (path) => {
+        setState((prev) => ({ ...prev, outDir: path }));
+        const { extractSessionId, tokensPath } = sessionRef.current;
+        const { skipGate, andPush } = pendingSaveOptionsRef.current;
+        const result = await runPrintFiles(extractSessionId, path, {
+            ...(skipGate ? { skipGate: true } : {}),
+            ...(state.tokenSessionId ? { tokenSessionId: state.tokenSessionId } : {}),
+        });
+        if (!result.ok)
+            return;
+        // Prefer the freshly emitted path/count (covers --out-dir); fall back to
+        // the values captured during the original generate-tokens step.
+        const recordedTokensPath = result.tokensPath ?? (state.tokenSessionId ? tokensPath || null : null);
+        const recordedTokenCount = result.tokenCount ?? state.tokenCount;
+        if (result.ok) {
+            // Append a run record on every successful write. Best-effort: append
+            // failures must not break the wizard flow (they surface on stderr).
+            try {
+                // Build the v3 fingerprints. Both are best-effort: if any step
+                // throws (missing source file, hash failure, db lookup error) we
+                // fall back to null fingerprints rather than aborting the save.
+                let sourceFingerprint = null;
+                let savedFingerprint = null;
+                try {
+                    if (state.extractSessionId) {
+                        const db = openPipelineDb();
+                        try {
+                            sourceFingerprint = await buildSourceFingerprint({
+                                db,
+                                extractSessionId: state.extractSessionId,
+                                rawTokensPath: state.rawTokensPath || null,
+                            });
+                        }
+                        finally {
+                            db.close();
+                        }
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`Warning: failed to compute source fingerprint: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+                try {
+                    const componentsBuf = await readFile(join(path, 'components.json')).catch(() => null);
+                    const tokensBuf = recordedTokensPath ? await readFile(recordedTokensPath).catch(() => null) : null;
+                    savedFingerprint = buildSavedFingerprint({
+                        componentsJson: componentsBuf,
+                        tokensJson: tokensBuf,
+                    });
+                }
+                catch (err) {
+                    process.stderr.write(`Warning: failed to compute saved fingerprint: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+                const record = await appendRun({
+                    projectPath: state.projectPath,
+                    savePath: path,
+                    componentCount: state.generatedAcceptedCount || state.generatedCount,
+                    tokenCount: recordedTokenCount,
+                    tokensPath: recordedTokensPath || null,
+                    tokenSessionId: state.tokenSessionId,
+                    agent: state.agent,
+                    pushedTo: null,
+                    extractSessionId: state.extractSessionId ?? '',
+                    generateSessionId: state.generateSessionId,
+                    sourceFingerprint,
+                    savedFingerprint,
+                });
+                setState((prev) => ({ ...prev, lastRunId: record.id }));
+            }
+            catch (err) {
+                process.stderr.write(`Warning: failed to record run: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        if (andPush) {
+            void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
+        }
     };
     // ── Effect: kick off automatic steps ───────────────────────────────────────────────
     const tokenReuseChecked = useRef(false);
@@ -895,6 +1304,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     }, [state.step]); // intentional: only re-run when step changes
     // ── Render ────────────────────────────────────────────────────────────────────────────
     const noQuitSteps = [
+        'run-picker',
         'checking-claude-auth',
         'validating-credentials',
         'generating-tokens',
@@ -911,6 +1321,18 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const totalSteps = 3 + (hasTokens ? 1 : 0) + (hasComponents ? 2 : 0);
     const stepContent = (() => {
         switch (state.step) {
+            case 'run-picker':
+                return (_jsx(RunPicker, { runs: initialRuns ?? [], onSelect: (selection) => {
+                        if (selection.action === 'new') {
+                            update({ step: 'welcome' });
+                            return;
+                        }
+                        // Push / modify routing exits the wizard back into the CLI
+                        // surface so `replayRun` / `modifyRun` (which spin their own
+                        // UI / spawn their own Ink trees) can take over. The CLI
+                        // entry point in `command.ts` provides `onRunPicked`.
+                        onRunPicked?.(selection);
+                    }, onCancel: () => process.exit(0) }));
             case 'welcome':
                 return (_jsx(WelcomeStep, { onContinue: (path) => {
                         const projectPath = normalizePath(path);
@@ -939,7 +1361,17 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             case 'path-validation':
                 return (_jsx(PathValidationStep, { projectPath: state.projectPath, onConfirm: (path) => {
                         void runExtract(path);
-                    }, onSkipComponents: () => update({ step: 'push-decision-gate', skipComponents: true }), onChangePath: () => update({ step: 'welcome' }), onQuit: () => process.exit(0) }));
+                    }, onSkipComponents: () => {
+                        // No components — only design tokens to push. Still gather creds
+                        // first (unless --no-push, in which case there is nothing to do
+                        // and we save files instead).
+                        if (noPush) {
+                            update({ skipComponents: true, acceptedCount: 0 });
+                            void startSaveFlow();
+                            return;
+                        }
+                        update({ step: 'credentials', skipComponents: true, acceptedCount: 0 });
+                    }, onChangePath: () => update({ step: 'welcome' }), onQuit: () => process.exit(0) }));
             case 'extracting': {
                 const ep = state.extractProgress;
                 let extractDetail;
@@ -954,32 +1386,59 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 }
                 return (_jsx(RunningStep, { stepNumber: hasTokens ? 2 : 1, totalSteps: totalSteps, title: "Extracting components", description: "I'm scanning your files and figuring out what components exist, what props they have, and how they're structured. This is fully automatic \u2014 sit tight.", detail: extractDetail }));
             }
-            case 'review-extraction-gate': {
-                const stepNum = hasTokens ? 2 : 1;
-                return (_jsx(GateStep, { successMessage: `Step ${stepNum} complete`, summary: `Found ${state.extractedCount} component${state.extractedCount === 1 ? '' : 's'}.`, context: "Ready to review what was extracted? You can correct any props the extractor got wrong, or approve everything and move on.", continueLabel: "Review components", skipLabel: "Approve all and skip", onContinue: () => {
-                        if (!state.extractSessionId) {
-                            update({
-                                step: 'error',
-                                errorStep: 'analyze extract',
-                                errorMessage: 'Extract session ID missing — please re-run.',
-                            });
-                            return;
-                        }
-                        void runAnalyzeSelect(state.extractSessionId, state.extractedCount, state.tokensPath, false);
-                    }, onSkip: () => {
-                        if (!state.extractSessionId) {
-                            update({
-                                step: 'error',
-                                errorStep: 'analyze extract',
-                                errorMessage: 'Extract session ID missing — please re-run.',
-                            });
-                            return;
-                        }
-                        void runAnalyzeSelect(state.extractSessionId, state.extractedCount, state.tokensPath, true);
+            case 'scope-gate': {
+                if (!state.extractSessionId) {
+                    return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: "red", children: "Error: extract session ID missing \u2014 please re-run." }) }));
+                }
+                const sessionId = state.extractSessionId;
+                const db = openPipelineDb();
+                let components;
+                try {
+                    components = loadScopeComponents(db, sessionId);
+                }
+                finally {
+                    db.close();
+                }
+                return (_jsx(ScopeGateHost, { components: components, autoAccept: autoAcceptScope, aiFilterStatus: state.aiFilterStatus, aiFilterProgress: state.aiFilterProgress, aiFilterError: state.aiFilterError, onCancelAutoFilter: cancelAutoFilter, onConfirm: (decisions) => {
+                        void runScopeGate({
+                            sessionId,
+                            decisions,
+                            cancelAutoFilter: state.aiFilterStatus === 'running' ? cancelAutoFilterAndWait : undefined,
+                            onAdvanceToGenerate: async ({ sessionId: sid, acceptedCount }) => {
+                                update({ acceptedCount, autoRejectedCount: 0 });
+                                const next = nextStepAfterScopeGate({ acceptedCount, noPush });
+                                if (next === 'generating') {
+                                    if (await runAgentAuthCheck('generating')) {
+                                        void runGenerate(sid, state.tokensPath, acceptedCount);
+                                    }
+                                    return;
+                                }
+                                // next === 'credentials' (push enabled). Kick off the
+                                // generate child in the background so the LLM call overlaps
+                                // with the operator's credential entry. We only prefetch
+                                // when we have accepted components to classify AND push is
+                                // enabled (noPush path is already excluded — the scope-gate
+                                // helper would have returned 'generating' there).
+                                if (acceptedCount > 0 && !noPush) {
+                                    if (await runAgentAuthCheck('credentials')) {
+                                        startGeneratePrefetch(sid, state.tokensPath);
+                                    }
+                                }
+                                update({ step: 'credentials' });
+                            },
+                            onAdvanceToPushFlow: (count) => {
+                                update({ acceptedCount: count, autoRejectedCount: 0 });
+                                const next = nextStepAfterScopeGate({ acceptedCount: count, noPush });
+                                if (next === 'print-gate') {
+                                    void startSaveFlow();
+                                    return;
+                                }
+                                // 'credentials' — still need creds for tokens/removals push.
+                                advanceToPushFlow(count);
+                            },
+                        });
                     }, onQuit: () => process.exit(0) }));
             }
-            case 'analyze-select':
-                return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { dimColor: true, children: "Launching component review... (the TUI will appear shortly)" }) }));
             case 'generating': {
                 const p = state.generateProgress;
                 const stepNum = hasTokens ? 4 : 3;
@@ -988,34 +1447,32 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     : `Starting up ${state.agent}... (this can take 10–30 minutes for large libraries — grab a coffee)`;
                 return (_jsx(RunningStep, { stepNumber: stepNum, totalSteps: totalSteps, title: "Generating definitions", description: `${formatAcceptanceSummary({ accepted: state.acceptedCount, autoRejected: state.autoRejectedCount })} ${state.agent} is mapping your TypeScript types to Contentful's CDF format.${hasTokens ? ' Using your design tokens for prop resolution.' : ''}`, detail: progressDetail }));
             }
-            case 'review-generated-gate': {
-                const stepNum = hasTokens ? 4 : 3;
-                return (_jsx(GateStep, { successMessage: `Step ${stepNum} complete — definitions generated`, summary: formatGeneratedSummary({
-                        generated: state.generatedCount,
-                        renamedSlots: state.renamedSlotsCount,
-                        autoRejected: state.autoRejectedCount,
-                    }), context: "Take a final look before pushing to Contentful. You can accept, reject, or inspect each component's generated definition.", continueLabel: "Review definitions", skipLabel: "Approve all and skip", onContinue: () => {
-                        update({ step: 'generate-review' });
-                    }, onSkip: () => {
-                        void runGenerateEdit(state.generateSessionId, state.generatedCount, true);
-                    }, onQuit: () => process.exit(0) }));
-            }
-            case 'generate-review': {
-                if (!state.extractSessionId) {
-                    return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: "red", children: "Error: no session ID \u2014 cannot load generated definitions." }) }));
-                }
-                return (_jsx(GenerateReviewStep, { extractSessionId: state.extractSessionId, onFinalize: (accepted, rejected) => {
-                        update({
-                            generatedAcceptedCount: accepted,
-                            step: 'push-decision-gate',
-                        });
-                        void Promise.resolve();
-                        // log so orchestrator can read it
-                        process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}\n`);
+            case 'final-review': {
+                return (_jsx(FinalReviewHost, { extractSessionId: state.extractSessionId, generatedCount: state.generatedCount, autoAccept: autoAcceptScope, livePreview: livePreview, spaceId: state.spaceId, environmentId: state.environmentId, cmaToken: state.cmaToken, host: state.host, tokensPath: state.tokensPath, onFinalize: (accepted, rejected, unresolved) => {
+                        process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}  Unresolved: ${unresolved}\n`);
+                        if (noPush) {
+                            update({ generatedAcceptedCount: accepted });
+                            void startSaveFlow();
+                            return;
+                        }
+                        if (noSave) {
+                            update({ generatedAcceptedCount: accepted });
+                            const { extractSessionId, tokensPath } = sessionRef.current;
+                            void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
+                            return;
+                        }
+                        if (autoAcceptScope) {
+                            // Headless run with neither --no-save nor --no-push: pick the
+                            // default "both" path automatically to preserve scripted
+                            // (auto-accept-scope) UX from before the gate gained a third
+                            // option. Operators who want push-only must pass --no-save.
+                            update({ generatedAcceptedCount: accepted });
+                            void runSaveAndPush();
+                            return;
+                        }
+                        update({ generatedAcceptedCount: accepted, step: 'push-decision-gate' });
                     }, onQuit: () => process.exit(0) }));
             }
-            case 'generate-edit':
-                return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { dimColor: true, children: "Launching definition review... (the TUI will appear shortly)" }) }));
             case 'push-decision-gate': {
                 const tokenDesc = hasTokens ? 'tokens.json' : null;
                 const compDesc = hasComponents ? 'components.json' : null;
@@ -1026,96 +1483,120 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     : hasTokens
                         ? 'Design tokens ready.'
                         : 'Ready to continue.';
-                return (_jsx(GateStep, { successMessage: "Generation complete", summary: summary, context: `Push directly to your Contentful space now, or save ${files || 'the output files'} to disk first.`, continueLabel: "Push to Contentful", skipLabel: `Save ${files || 'files'} to disk`, onContinue: () => {
-                        update({ step: 'credentials' });
-                    }, onSkip: () => {
-                        void runPrintFiles(state.extractSessionId, state.outDir);
+                return (_jsx(PushDecisionGateStep, { summary: summary, context: `Save ${files || 'output files'} to disk, push to your Contentful space, or both.`, fileList: files || 'files', pushDisabled: state.credentialsSkipped, onChoice: (choice) => {
+                        const action = chooseGateAction(choice);
+                        if (action === 'save-and-push') {
+                            void runSaveAndPush();
+                            return;
+                        }
+                        if (action === 'push-only') {
+                            const { extractSessionId, tokensPath } = sessionRef.current;
+                            void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
+                            return;
+                        }
+                        // save-only
+                        void startSaveFlow();
                     }, onQuit: () => process.exit(0) }));
             }
             case 'credentials':
-                return (_jsx(CredentialsStep, { initialSpaceId: state.spaceId, initialEnvironmentId: state.environmentId, initialCmaToken: state.cmaToken, initialHost: state.host, error: state.credentialsError || undefined, onConfirm: (spaceId, environmentId, cmaToken, host) => {
+                return (_jsx(CredentialsStep, { initialSpaceId: state.spaceId, initialEnvironmentId: state.environmentId, initialCmaToken: state.cmaToken, initialHost: state.host, error: state.credentialsError || undefined, validating: state.credentialsValidating, generatePrefetchStatus: state.generatePrefetchStatus, generatePrefetchError: state.generatePrefetchError, onConfirm: (spaceId, environmentId, cmaToken, host) => {
                         void confirmCredentials(spaceId, environmentId, cmaToken, host);
-                    }, onContinue: advanceWithCredentials, onQuit: () => process.exit(0) }));
-            case 'credential-test-gate':
-                return (_jsx(GateStep, { successMessage: "Credentials entered", summary: `Space: ${state.spaceId}  ·  Environment: ${state.environmentId}`, context: "Verify your credentials work before running the import, or skip and find out during the push step.", continueLabel: "Test credentials", skipLabel: "Skip and continue", showSkip: true, onContinue: () => {
-                        void validateCredentials(state.spaceId, state.environmentId, state.cmaToken, state.host);
-                    }, onSkip: () => {
-                        const { extractSessionId, tokensPath } = sessionRef.current;
-                        void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
-                    }, onQuit: () => process.exit(0) }));
-            case 'validating-credentials':
-                return (_jsx(RunningStep, { stepNumber: totalSteps - 1, totalSteps: totalSteps, title: "Validating credentials", description: "Checking that your space ID and CMA token are valid..." }));
+                    }, onContinue: advanceWithCredentials, onRetryPrefetch: state.generatePrefetchStatus === 'failed' && sessionRef.current.extractSessionId
+                        ? () => {
+                            const sid = sessionRef.current.extractSessionId;
+                            void startGeneratePrefetch(sid, state.tokensPath);
+                        }
+                        : undefined, onSkip: () => {
+                        // Skip-credentials: mark the wizard as skipped, clear any
+                        // stale credentialsError banner, and advance through the
+                        // normal post-credentials branch. The in-flight generate
+                        // prefetch (PR #54) is intentionally NOT cancelled here —
+                        // the operator still wants to see classifications.
+                        update({ credentialsSkipped: true, credentialsError: '' });
+                        void advanceAfterCredentialsValidated();
+                    }, onQuit: () => {
+                        cancelGeneratePrefetch();
+                        process.exit(0);
+                    } }));
+            // 'credential-test-gate' is intentionally NOT rendered as a dedicated
+            // screen any more (the post-#54 inline credentials-validating status made
+            // the gate redundant). The step value is kept in the union for back-compat
+            // with existing imports/tests but is never actually set as a step —
+            // `advanceWithCredentials` calls `validateCredentials` directly.
+            //
+            // 'validating-credentials' is intentionally NOT rendered as a dedicated
+            // screen any more (see CredentialsStep `validating` prop). The step
+            // value is kept in the union for back-compat with existing imports/tests
+            // but should never actually be set — `validateCredentials` keeps the
+            // step on 'credentials' and toggles `credentialsValidating` instead.
             case 'previewing':
                 return (_jsx(RunningStep, { stepNumber: totalSteps, totalSteps: totalSteps, title: "Computing diff", description: "Computing diff against your Contentful space..." }));
             case 'preview-gate':
                 return (_jsx(WizardPreviewStep, { preview: state.serverPreview, spaceId: state.spaceId, environmentId: state.environmentId, stepNumber: totalSteps, totalSteps: totalSteps, onConfirm: (acknowledge) => {
                         void runPush(state.manifest, state.spaceId, state.environmentId, state.cmaToken, state.host, acknowledge, state.serverPreview);
                     }, onEdit: () => {
-                        void runEditFromPreview(state.serverPreview);
+                        void runEditFromPreview();
                     }, onSaveFiles: () => {
-                        void runPrintFiles(state.extractSessionId, state.outDir);
+                        void startSaveFlow();
                     }, onQuit: () => process.exit(0) }));
             case 'pushing':
-                return (_jsx(RunningStep, { stepNumber: totalSteps, totalSteps: totalSteps, title: "Push to Contentful", description: "Writing component types and design tokens to your Contentful space...", detail: state.pushProgress ?? undefined }));
+                return (_jsx(PushingStep, { stepNumber: totalSteps, totalSteps: totalSteps, expected: state.pushExpected, progress: state.pushProgress }));
+            case 'path-prompt':
+                return (_jsx(PathPrompt, { defaultPath: state.outDir, onSubmit: (submitted) => {
+                        void (async () => {
+                            await mkdir(submitted, { recursive: true });
+                            const hasConflict = await detectSaveConflict(submitted);
+                            if (hasConflict) {
+                                setState((prev) => ({ ...prev, step: 'save-conflict-gate', outDir: submitted }));
+                                return;
+                            }
+                            await proceedToWrite(submitted);
+                        })();
+                    }, onCancel: () => process.exit(0) }));
+            case 'save-conflict-gate':
+                return (_jsx(SaveConflictGate, { path: state.outDir, onOverwrite: () => {
+                        void proceedToWrite(state.outDir);
+                    }, onNew: () => {
+                        const subdir = buildTimestampedSubdir(state.outDir);
+                        void (async () => {
+                            await mkdir(subdir, { recursive: true });
+                            await proceedToWrite(subdir);
+                        })();
+                    }, onCancel: () => setState((prev) => ({ ...prev, step: 'path-prompt' })) }));
             case 'printing':
                 return (_jsx(RunningStep, { stepNumber: totalSteps, totalSteps: totalSteps, title: "Writing files", description: "Writing output files to disk..." }));
-            case 'print-gate':
+            case 'print-gate': {
+                const teaser = buildRunTeaserLine(state.lastRunId);
                 return (_jsx(GateStep, { successMessage: "Files saved", summary: [
                         hasComponents && state.componentsPath ? `components.json → ${state.componentsPath}` : null,
                         hasTokens && state.tokensPath ? `tokens.json → ${state.tokensPath}` : null,
                     ]
                         .filter(Boolean)
-                        .join('\n'), context: "Your files are saved to disk. Run `experiences import` again when you're ready to push to Contentful.", continueLabel: "Exit", showSkip: false, onContinue: () => process.exit(0), onQuit: () => process.exit(0) }));
+                        .join('\n'), context: teaser
+                        ? `Your files are saved to disk. ${teaser}`
+                        : "Your files are saved to disk. Run `experiences import` again when you're ready to push to Contentful.", continueLabel: "Exit", showSkip: false, onContinue: () => process.exit(0), onQuit: () => process.exit(0) }));
+            }
             case 'done': {
                 const totalFailed = state.pushResult.componentTypes.failed + state.pushResult.designTokens.failed;
-                return (_jsx(DoneStep, { componentTypes: state.pushResult.componentTypes, designTokens: state.pushResult.designTokens, summary: state.pushResult.summary, spaceId: state.spaceId, environmentId: state.environmentId, onExit: () => process.exit(totalFailed > 0 ? 1 : 0) }));
+                const teaser = buildRunTeaserLine(state.lastRunId);
+                return (_jsx(DoneStep, { componentTypes: state.pushResult.componentTypes, designTokens: state.pushResult.designTokens, summary: state.pushResult.summary, spaceId: state.spaceId, environmentId: state.environmentId, host: state.host, ...(teaser ? { runTeaser: teaser } : {}), onExit: () => process.exit(totalFailed > 0 ? 1 : 0) }));
             }
             case 'preview-validation-error': {
                 return (_jsx(PreviewValidationErrorStep, { errors: state.previewValidationErrors, missingNames: state.previewValidationMissingNames, onEdit: () => {
-                        void runEditFromPreview(null);
+                        void runEditFromPreview();
                     }, onSkip: () => {
                         void runSkipValidationErrorsAndRetry(state.previewValidationErrors);
                     }, onQuit: () => process.exit(0) }));
             }
             case 'error':
                 return (_jsx(ErrorStep, { stepName: state.errorStep, message: state.errorMessage, onExit: () => process.exit(1), onRetryCredentials: state.errorAllowCredentialRetry ? () => update({ step: 'credentials', credentialsError: '' }) : undefined }));
+            // 'validating-credentials' kept in the WizardStep union for back-compat
+            // but is no longer reachable as a step (validateCredentials toggles the
+            // `credentialsValidating` boolean while leaving step on 'credentials').
+            // Default-return null so the switch is exhaustive.
+            default:
+                return null;
         }
     })();
-    return (_jsxs(Box, { flexDirection: "column", width: terminalWidth, children: [_jsx(TopBar, { subcommand: "import", hints: hints }), stepContent] }));
-}
-function buildPreviewAnnotations(preview) {
-    const annotations = {};
-    if (!preview)
-        return annotations;
-    for (const item of preview.components.new) {
-        const key = item.key ?? '';
-        if (key)
-            annotations[key] = 'new';
-    }
-    for (const item of preview.components.removed) {
-        annotations[item.name] = 'removed';
-    }
-    for (const item of preview.components.changed) {
-        if (item.changeClassification?.classification === 'breaking') {
-            annotations[item.current.name] = 'breaking';
-        }
-        else {
-            annotations[item.current.name] = 'changed';
-        }
-    }
-    return annotations;
-}
-// Interactive subprocess helper — uses spawn with inherited stdio so child isTTY is true
-function runCliInteractive(args) {
-    logStep({
-        fn: 'runCliInteractive:spawn',
-        args,
-    });
-    return new Promise((res) => {
-        const child = spawn('node', [findCliPath(), ...args], { stdio: 'inherit' });
-        child.on('exit', (code) => {
-            logStep({ fn: 'runCliInteractive:exit', args, exitCode: code ?? 0 });
-            res({ exitCode: code ?? 0, stdout: '', stderr: '' });
-        });
-    });
+    return (_jsxs(Box, { flexDirection: "column", width: terminalWidth, children: [_jsx(TopBar, { subcommand: "import", hints: hints }), _jsx(CustomPromptBanner, { selectPromptPath: selectPromptPath, generatePromptPath: generatePromptPath }), stepContent] }));
 }