wiggum-cli 0.12.0 → 0.13.0

package/dist/tui/app.js

@@ -5,73 +5,43 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * The root component for the Ink-based TUI. Routes to different screens
  * based on the current screen state. Manages session state and navigation.
  *
- * Uses a "continuous thread" model like Claude Code - all output stays
- * visible in the terminal as a growing thread, rather than clearing screens.
+ * Uses an AppShell-based layout where each screen wraps itself in
+ * <AppShell> with a shared header element. No Static/thread model -
+ * screen transitions are clean React mount/unmount cycles.
  */
-import { useState, useCallback, useEffect } from 'react';
-import { render, Static, Box, Text } from 'ink';
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { useState, useCallback, useEffect, useMemo } from 'react';
+import { Box, Text, render, useStdout } from 'ink';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfigWithDefaults } from '../utils/config.js';
+import { logger } from '../utils/logger.js';
 import { InterviewScreen } from './screens/InterviewScreen.js';
 import { InitScreen } from './screens/InitScreen.js';
 import { RunScreen } from './screens/RunScreen.js';
 import { MainShell } from './screens/MainShell.js';
-import { WiggumBanner } from './components/WiggumBanner.js';
-import { StatusLine } from './components/StatusLine.js';
-import { PHASE_CONFIGS } from './hooks/useSpecGenerator.js';
-import { colors, theme } from './theme.js';
-import { formatNumber } from './utils/loop-status.js';
+import { HeaderContent } from './components/HeaderContent.js';
+import { useBackgroundRuns } from './hooks/useBackgroundRuns.js';
 /**
  * Main App component for the Ink-based TUI
  *
- * Routes to different screens based on the current screen state.
- * Manages session state and provides navigation between screens.
- *
- * @example
- * ```tsx
- * renderApp({
- *   screen: 'welcome',
- *   initialSessionState: sessionState,
- *   version: '0.8.0',
- *   onExit: () => process.exit(0),
- * });
- * ```
- */
-/**
- * Generate a unique ID for thread items
+ * Simple routing + shared state. Each screen wraps itself in AppShell
+ * and receives a shared headerElement prop.
  */
-function generateThreadId() {
-    return `thread-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
-}
-export function App({ screen: initialScreen, initialSessionState, version = '0.8.0', interviewProps, onComplete, onExit, }) {
+export function App({ screen: initialScreen, initialSessionState, version = '0.12.1', // Fallback if package.json read fails (keep in sync with index.ts)
+interviewProps, onComplete, onExit, }) {
     const [currentScreen, setCurrentScreen] = useState(initialScreen);
     const [screenProps, setScreenProps] = useState(interviewProps ? { featureName: interviewProps.featureName } : null);
     const [sessionState, setSessionState] = useState(initialSessionState);
-    const renderBannerContent = useCallback((state) => (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsx(WiggumBanner, {}), _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: colors.pink, children: ["v", version] }), _jsx(Text, { dimColor: true, children: theme.statusLine.separator }), state.provider ? (_jsxs(Text, { color: colors.blue, children: [state.provider, "/", state.model] })) : (_jsx(Text, { color: colors.orange, children: "not configured" })), _jsx(Text, { dimColor: true, children: theme.statusLine.separator }), _jsx(Text, { color: state.initialized ? colors.green : colors.orange, children: state.initialized ? 'Ready' : 'Not initialized' })] }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ["Tip: ", state.initialized ? '/new <feature> to create spec' : '/init to set up', ", /help for commands"] }) })] })), [version]);
-    // Thread history - preserves all output as a continuous thread
-    const [threadHistory, setThreadHistory] = useState(() => {
-        // Start with banner if showing welcome screen
-        if (initialScreen === 'welcome') {
-            return [{
-                    id: generateThreadId(),
-                    type: 'banner',
-                    content: renderBannerContent(initialSessionState),
-                }];
-        }
-        return [];
-    });
-    const [completionQueue, setCompletionQueue] = useState(null);
-    const [isTransitioning, setIsTransitioning] = useState(false);
-    const [threadResetKey, setThreadResetKey] = useState(0);
-    /**
-     * Add an item to the thread history
-     */
-    const addToThread = useCallback((type, content) => {
-        const id = generateThreadId();
-        setThreadHistory(prev => [...prev, { id, type, content }]);
-        return id;
-    }, []);
+    // Background run tracking
+    const { runs: backgroundRuns, background, dismiss } = useBackgroundRuns();
+    // Terminal dimensions for compact mode and resize reactivity
+    const { stdout } = useStdout();
+    const columns = stdout?.columns ?? 80;
+    const rows = stdout?.rows ?? 24;
+    const compact = rows < 20 || columns < 60;
+    // Shared header element - includes columns/rows in deps so the
+    // header subtree re-renders on terminal resize (banner auto-compacts)
+    const headerElement = useMemo(() => (_jsx(HeaderContent, { version: version, sessionState: sessionState, backgroundRuns: backgroundRuns, compact: compact })), [version, sessionState, backgroundRuns, compact, columns, rows]);
     /**
      * Navigate to a different screen
      */
@@ -80,196 +50,63 @@ export function App({ screen: initialScreen, initialSessionState, version = '0.8
         setCurrentScreen(target);
     }, []);
     /**
-     * Handle interview completion - save spec to disk and add to thread
+     * Handle interview completion - save spec to disk and navigate to shell
      */
-    const handleInterviewComplete = useCallback(async (spec, messages) => {
-        // Get feature name from navigation props or initial interview props
-        const featureName = screenProps?.featureName || interviewProps?.featureName;
-        let specPath = '';
-        if (featureName && typeof featureName === 'string') {
-            try {
-                // Load config to get specs directory
-                const config = await loadConfigWithDefaults(sessionState.projectRoot);
-                const specsDir = join(sessionState.projectRoot, config.paths.specs);
-                // Create specs directory if it doesn't exist
-                if (!existsSync(specsDir)) {
-                    mkdirSync(specsDir, { recursive: true });
+    const handleInterviewComplete = useCallback(async (spec, messages, specPath) => {
+        try {
+            const featureName = screenProps?.featureName || interviewProps?.featureName;
+            let savedPath = specPath;
+            if (featureName && typeof featureName === 'string') {
+                try {
+                    const config = await loadConfigWithDefaults(sessionState.projectRoot);
+                    const specsDir = join(sessionState.projectRoot, config.paths.specs);
+                    if (!existsSync(specsDir)) {
+                        mkdirSync(specsDir, { recursive: true });
+                    }
+                    savedPath = join(specsDir, `${featureName}.md`);
+                    writeFileSync(savedPath, spec, 'utf-8');
+                    onComplete?.(savedPath);
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    logger.error(`Failed to save spec: ${reason}`);
+                    // Pass specPath (not raw spec content) to keep the onComplete contract consistent
+                    onComplete?.(specPath);
+                    if (initialScreen !== 'interview') {
+                        navigate('shell', { message: `Warning: spec generated but could not be saved to disk (${reason}).` });
+                    }
+                    else {
+                        onExit?.();
+                    }
+                    return;
                 }
-                // Write spec to file
-                specPath = join(specsDir, `${featureName}.md`);
-                writeFileSync(specPath, spec, 'utf-8');
-                // Call onComplete with the spec path for logging
-                onComplete?.(specPath);
             }
-            catch (error) {
-                // If saving fails, still call onComplete with spec content
+            else {
                 onComplete?.(spec);
             }
-        }
-        else {
-            onComplete?.(spec);
-        }
-        // Prefer previewing the spec from disk if available (ensures consistent output)
-        let specForPreview = typeof spec === 'string' ? spec : '';
-        if (specPath && existsSync(specPath)) {
-            try {
-                specForPreview = readFileSync(specPath, 'utf-8');
-            }
-            catch {
-                // Ignore read errors and fall back to in-memory spec
+            // If started on interview screen directly (--tui mode), exit
+            if (initialScreen === 'interview') {
+                onExit?.();
+                return;
             }
+            navigate('shell', { message: `Spec saved to ${savedPath}` });
         }
-        const specLines = specForPreview ? specForPreview.split('\n') : [];
-        const totalLines = specLines.length;
-        const previewLines = specLines.slice(0, 5);
-        const remainingLines = Math.max(0, totalLines - 5);
-        const MAX_RECAP_SOURCE_LENGTH = 1200;
-        const userMessages = messages
-            .filter((msg) => msg.role === 'user')
-            .map((msg) => msg.content.trim())
-            .filter((content) => content.length > 0 && content.length <= MAX_RECAP_SOURCE_LENGTH);
-        const nonUrlUserMessages = userMessages.filter((content) => !/^https?:\/\//i.test(content) && !/^www\./i.test(content));
-        const assistantParagraphs = messages
-            .filter((msg) => msg.role === 'assistant' && msg.content && msg.content.length <= MAX_RECAP_SOURCE_LENGTH)
-            .flatMap((msg) => msg.content.split('\n\n'))
-            .map((para) => para.replace(/\s+/g, ' ').trim())
-            .filter((para) => para.length > 0 && para.length <= 320);
-        const recapCandidates = assistantParagraphs
-            .map((para) => para.replace(/^[^a-z0-9]+/i, '').trim())
-            .filter((para) => /^(you want|understood|got it)/i.test(para))
-            .map((para) => para.split(/next question:/i)[0].trim())
-            .filter((para) => para.length > 0);
-        const normalizeRecap = (text) => {
-            let result = text.trim();
-            result = result.replace(/^[^a-z0-9]+/i, '');
-            result = result.replace(/^you want\s*/i, '');
-            result = result.replace(/^understood[:,]?\s*/i, '');
-            result = result.replace(/^got it[-—:]*\s*/i, '');
-            return result.charAt(0).toUpperCase() + result.slice(1);
-        };
-        const normalizeUserDecision = (text) => {
-            let result = text.trim();
-            result = result.replace(/^[^a-z0-9]+/i, '');
-            result = result.replace(/^i (?:would like|want|need|prefer|expect) to\s*/i, '');
-            result = result.replace(/^i (?:would like|want|need|prefer|expect)\s*/i, '');
-            result = result.replace(/^please\s*/i, '');
-            result = result.replace(/^up to you[:,]?\s*/i, '');
-            result = result.replace(/^both\s*/i, 'Both ');
-            if (result && !/[.!?]$/.test(result)) {
-                result += '.';
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error(`Unexpected error in handleInterviewComplete: ${reason}`);
+            if (initialScreen !== 'interview') {
+                navigate('shell', { message: `Error completing interview: ${reason}` });
             }
-            return result.charAt(0).toUpperCase() + result.slice(1);
-        };
-        const goalCandidate = recapCandidates.length > 0
-            ? normalizeRecap(recapCandidates[0])
-            : (nonUrlUserMessages.find((content) => content.length > 20)
-                ? normalizeUserDecision(nonUrlUserMessages.find((content) => content.length > 20))
-                : (nonUrlUserMessages[0] ? normalizeUserDecision(nonUrlUserMessages[0]) : `Define "${featureName}"`));
-        const summarizeText = (text, max = 160) => {
-            if (text.length <= max)
-                return text;
-            return `${text.slice(0, max - 1)}…`;
-        };
-        const decisions = [];
-        const seen = new Set();
-        const isUsefulDecision = (entry) => {
-            const normalized = entry.trim().toLowerCase();
-            if (normalized.length < 8)
-                return false;
-            const wordCount = normalized.split(/\s+/).length;
-            if (wordCount < 3)
-                return false;
-            if (['yes', 'no', 'both', 'ok', 'okay'].includes(normalized))
-                return false;
-            return true;
-        };
-        for (let i = nonUrlUserMessages.length - 1; i >= 0; i -= 1) {
-            const entry = nonUrlUserMessages[i];
-            const normalized = entry.toLowerCase();
-            if (entry === goalCandidate)
-                continue;
-            if (!isUsefulDecision(entry))
-                continue;
-            if (entry.length > 160)
-                continue;
-            if (seen.has(normalized))
-                continue;
-            decisions.unshift(normalizeUserDecision(entry));
-            seen.add(normalized);
-            if (decisions.length >= 4)
-                break;
-        }
-        if (recapCandidates.length > 1) {
-            decisions.length = 0;
-            seen.clear();
-            for (let i = 1; i < recapCandidates.length; i += 1) {
-                const entry = normalizeRecap(recapCandidates[i]);
-                const normalized = entry.toLowerCase();
-                if (!isUsefulDecision(entry))
-                    continue;
-                if (seen.has(normalized))
-                    continue;
-                decisions.push(entry);
-                seen.add(normalized);
-                if (decisions.length >= 4)
-                    break;
+            else {
+                process.stderr.write(`\nError: ${reason}\n`);
+                onExit?.();
             }
         }
-        const summaryContent = (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(StatusLine, { action: "New Spec", phase: `Complete (${PHASE_CONFIGS.complete.number}/${PHASE_CONFIGS.complete.number})`, path: featureName }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Summary" }), _jsxs(Text, { children: ["- Goal: ", summarizeText(goalCandidate)] }), _jsxs(Text, { children: ["- Outcome: Spec written to ", specPath || `${featureName}.md`, " (", totalLines, " lines)"] })] }), decisions.length > 0 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Key decisions" }), decisions.map((decision, idx) => (_jsxs(Text, { children: [idx + 1, ". ", summarizeText(decision, 120)] }, `${decision}-${idx}`)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: colors.green, children: [theme.chars.bullet, " "] }), _jsx(Text, { bold: true, children: "Write" }), _jsxs(Text, { dimColor: true, children: ["(", specPath || `${featureName}.md`, ")"] })] }), _jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2514 Wrote ", totalLines, " lines"] }) }), _jsxs(Box, { marginLeft: 4, flexDirection: "column", children: [previewLines.map((line, i) => (_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { dimColor: true, children: [String(i + 1).padStart(4), " "] }), _jsx(Text, { dimColor: true, children: line })] }, i))), remainingLines > 0 && (_jsxs(Text, { dimColor: true, children: ["\u2026 +", remainingLines, " lines"] }))] }), _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: colors.green, children: [theme.chars.bullet, " "] }), _jsx(Text, { children: "Done. Specification generated successfully." })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "What's next:" }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsx(Text, { dimColor: true, children: "Review the spec in your editor" })] }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsx(Text, { color: colors.blue, children: "/help" }), _jsx(Text, { dimColor: true, children: "See all commands" })] })] })] }));
-        // Hide the live interview UI before appending to the static thread
-        setIsTransitioning(true);
-        setCompletionQueue({
-            summaryContent,
-            summaryType: 'spec-complete',
-            action: initialScreen === 'interview' ? 'exit' : 'shell',
-        });
-    }, [onComplete, navigate, initialScreen, onExit, screenProps, interviewProps, sessionState.projectRoot, addToThread]);
-    // Append completion items after the interview UI is hidden
-    useEffect(() => {
-        if (!isTransitioning || !completionQueue)
-            return;
-        const completionItem = {
-            id: generateThreadId(),
-            type: completionQueue.summaryType,
-            content: completionQueue.summaryContent,
-        };
-        const clearScrollback = completionQueue.summaryType === 'spec-complete' ? '\x1b[3J' : '';
-        process.stdout.write(`${clearScrollback}\x1b[2J\x1b[0;0H`);
-        if (completionQueue.summaryType === 'spec-complete') {
-            // Replace the interview thread with banner + completion summary only.
-            const bannerItem = {
-                id: generateThreadId(),
-                type: 'banner',
-                content: renderBannerContent(sessionState),
-            };
-            setThreadHistory([bannerItem, completionItem]);
-        }
-        else {
-            setThreadHistory((prev) => [...prev, completionItem]);
-        }
-        setThreadResetKey((prev) => prev + 1);
-        const action = completionQueue.action;
-        setCompletionQueue(null);
-        setTimeout(() => {
-            if (action === 'exit') {
-                if (onExit) {
-                    onExit();
-                    return;
-                }
-                navigate('shell');
-                setIsTransitioning(false);
-                return;
-            }
-            navigate('shell');
-            setIsTransitioning(false);
-        }, 0);
-    }, [isTransitioning, completionQueue, navigate, onExit]);
+    }, [screenProps, interviewProps, sessionState.projectRoot, onComplete, initialScreen, onExit, navigate]);
     /**
      * Handle interview cancel
      */
     const handleInterviewCancel = useCallback(() => {
-        // If started on interview (--tui mode), call onExit to resolve promise
-        // Otherwise, return to shell
         if (initialScreen === 'interview') {
             onExit?.();
         }
@@ -278,109 +115,87 @@ export function App({ screen: initialScreen, initialSessionState, version = '0.8
         }
     }, [navigate, initialScreen, onExit]);
     /**
-     * Handle welcome continue
+     * Handle init completion - update state and navigate to shell
      */
-    const handleWelcomeContinue = useCallback(() => {
-        navigate('shell');
-    }, [navigate]);
-    /**
-     * Handle session state changes
-     */
-    const handleSessionStateChange = useCallback((newState) => {
+    const handleInitComplete = useCallback((newState, generatedFiles) => {
         setSessionState(newState);
-    }, []);
+        const fileCount = generatedFiles?.length ?? 0;
+        const msg = fileCount > 0
+            ? `\u2713 Initialization complete. Generated ${fileCount} configuration file${fileCount === 1 ? '' : 's'}.`
+            : '\u2713 Initialization complete.';
+        navigate('shell', { message: msg, generatedFiles });
+    }, [navigate]);
     /**
-     * Handle init completion - add summary to thread and update state
+     * Handle run completion - dismiss background run if any, navigate to shell
      */
-    const handleInitComplete = useCallback((newState, generatedFiles) => {
-        // Add init completion to thread
-        addToThread('init-complete', (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [generatedFiles && generatedFiles.slice(0, 5).map((file) => (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: colors.green, children: [theme.chars.bullet, " "] }), _jsx(Text, { bold: true, children: "Write" }), _jsxs(Text, { dimColor: true, children: ["(", file, ")"] })] }), _jsx(Box, { marginLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2514 Created ", file] }) })] }, file))), generatedFiles && generatedFiles.length > 5 && (_jsxs(Text, { dimColor: true, children: ["  ... and ", generatedFiles.length - 5, " more files"] })), _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: colors.green, children: [theme.chars.bullet, " "] }), _jsx(Text, { children: "Done. Created Ralph configuration files." })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "What's next:" }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsxs(Text, { color: colors.blue, children: ["/new ", '<feature>'] }), _jsx(Text, { dimColor: true, children: "Create a feature specification" })] }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsx(Text, { color: colors.blue, children: "/help" }), _jsx(Text, { dimColor: true, children: "See all commands" })] })] })] })));
-        setSessionState(newState);
+    const handleRunComplete = useCallback((summary) => {
+        // Dismiss from background tracking if it was backgrounded
+        dismiss(summary.feature);
         navigate('shell');
-    }, [addToThread, navigate]);
+    }, [dismiss, navigate]);
     /**
-     * Handle run completion - add summary to thread
+     * Handle run background - add to background tracking, navigate to shell
      */
-    const handleRunComplete = useCallback((summary) => {
-        const totalTokens = summary.tokensInput + summary.tokensOutput;
-        const stoppedCodes = new Set([130, 143]);
-        const exitState = summary.exitCode === 0
-            ? { label: 'Complete', color: colors.green, message: 'Done. Feature loop completed successfully.' }
-            : stoppedCodes.has(summary.exitCode)
-                ? { label: 'Stopped', color: colors.orange, message: 'Stopped. Feature loop interrupted.' }
-                : { label: 'Failed', color: colors.pink, message: `Done. Feature loop exited with code ${summary.exitCode}.` };
-        addToThread('run-complete', (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(StatusLine, { action: "Run Loop", phase: exitState.label, path: summary.feature }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Summary" }), _jsxs(Text, { children: ["- Feature: ", summary.feature] }), _jsxs(Text, { children: ["- Iterations: ", summary.iterations, "/", summary.maxIterations] }), _jsxs(Text, { children: ["- Tasks: ", summary.tasksDone, "/", summary.tasksTotal] }), _jsxs(Text, { children: ["- Tokens: ", formatNumber(totalTokens), " (in:", formatNumber(summary.tokensInput), " out:", formatNumber(summary.tokensOutput), ")"] }), summary.branch && summary.branch !== '-' && (_jsxs(Text, { children: ["- Branch: ", summary.branch] }))] }), _jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsxs(Text, { color: exitState.color, children: [theme.chars.bullet, " "] }), _jsx(Text, { children: exitState.message })] }), (summary.errorTail || summary.logPath) && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [summary.logPath && (_jsxs(Text, { dimColor: true, children: ["Log: ", summary.logPath] })), summary.errorTail && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Last output:" }), summary.errorTail.split('\n').map((line, idx) => (_jsx(Text, { dimColor: true, children: line }, `${line}-${idx}`)))] }))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "What's next:" }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsx(Text, { dimColor: true, children: "Review changes and open a PR if needed" })] }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsxs(Text, { color: colors.blue, children: ["/new ", '<feature>'] }), _jsx(Text, { dimColor: true, children: "Create another feature specification" })] }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Text, { color: colors.green, children: "\u203A" }), _jsx(Text, { color: colors.blue, children: "/help" }), _jsx(Text, { dimColor: true, children: "See all commands" })] })] })] })));
+    const handleRunBackground = useCallback((featureName) => {
+        background(featureName);
         navigate('shell');
-    }, [addToThread, navigate]);
-    // Render current screen content
-    const renderCurrentScreen = () => {
-        // Hide screens while we transition interview output to static thread
-        if (isTransitioning) {
-            return null;
+    }, [background, navigate]);
+    // Guard: redirect to shell if screen has invalid props (avoids setState during render)
+    useEffect(() => {
+        if (currentScreen === 'interview') {
+            const featureName = screenProps?.featureName || interviewProps?.featureName;
+            if (!featureName || typeof featureName !== 'string') {
+                navigate('shell', { message: 'Feature name is required for the interview screen.' });
+                return;
+            }
+            if (!sessionState.provider) {
+                navigate('shell', { message: 'No AI provider configured. Run /init first.' });
+            }
         }
-        switch (currentScreen) {
-            case 'welcome':
-            // Banner is already in thread history, fall through to shell
-            case 'shell':
-                return (_jsx(MainShell, { sessionState: sessionState, onNavigate: navigate, onSessionStateChange: handleSessionStateChange }));
-            case 'interview': {
-                // Get feature name from props or navigation
-                const featureName = screenProps?.featureName || interviewProps?.featureName;
-                if (!featureName || typeof featureName !== 'string') {
-                    // Missing feature name, go back to shell
-                    navigate('shell');
-                    return null;
-                }
-                if (!sessionState.provider) {
-                    // No provider configured, can't run interview
-                    navigate('shell');
-                    return null;
-                }
-                return (_jsx(InterviewScreen, { featureName: featureName, projectRoot: sessionState.projectRoot, provider: sessionState.provider, model: sessionState.model, scanResult: sessionState.scanResult, specsPath: sessionState.config?.paths.specs, onComplete: handleInterviewComplete, onCancel: handleInterviewCancel }));
+        else if (currentScreen === 'run') {
+            const featureName = screenProps?.featureName;
+            if (!featureName || typeof featureName !== 'string') {
+                navigate('shell', { message: 'Feature name is required for the run screen.' });
             }
-            case 'init': {
-                return (_jsx(InitScreen, { projectRoot: sessionState.projectRoot, sessionState: sessionState, onComplete: handleInitComplete, onCancel: () => navigate('shell') }));
+        }
+        else if (currentScreen !== 'shell' && currentScreen !== 'init') {
+            // Unknown screen — redirect to shell on next tick
+            navigate('shell', { message: `Internal error: unknown screen "${currentScreen}". Returned to shell.` });
+        }
+    }, [currentScreen, screenProps, interviewProps, sessionState.provider, navigate]);
+    // Render current screen
+    switch (currentScreen) {
+        case 'shell':
+            return (_jsx(MainShell, { header: headerElement, sessionState: sessionState, onNavigate: navigate, backgroundRuns: backgroundRuns, initialMessage: typeof screenProps?.message === 'string' ? screenProps.message : undefined, initialFiles: Array.isArray(screenProps?.generatedFiles) ? screenProps.generatedFiles : undefined }, screenProps?.message ? String(screenProps.message) : 'shell'));
+        case 'interview': {
+            const featureName = screenProps?.featureName || interviewProps?.featureName;
+            if (!featureName || typeof featureName !== 'string' || !sessionState.provider) {
+                return null; // useEffect will redirect to shell
             }
-            case 'run': {
-                const featureName = screenProps?.featureName;
-                if (!featureName || typeof featureName !== 'string') {
-                    navigate('shell');
-                    return null;
-                }
-                return (_jsx(RunScreen, { featureName: featureName, projectRoot: sessionState.projectRoot, sessionState: sessionState, onComplete: handleRunComplete, onCancel: () => navigate('shell') }));
+            return (_jsx(InterviewScreen, { header: headerElement, featureName: featureName, projectRoot: sessionState.projectRoot, provider: sessionState.provider, model: sessionState.model, scanResult: sessionState.scanResult, specsPath: sessionState.config?.paths.specs, onComplete: handleInterviewComplete, onCancel: handleInterviewCancel }));
+        }
+        case 'init':
+            return (_jsx(InitScreen, { header: headerElement, projectRoot: sessionState.projectRoot, sessionState: sessionState, onComplete: handleInitComplete, onCancel: () => navigate('shell') }));
+        case 'run': {
+            const featureName = screenProps?.featureName;
+            const monitorOnly = screenProps?.monitorOnly === true;
+            if (!featureName || typeof featureName !== 'string') {
+                return null; // useEffect will redirect to shell
             }
-            default:
-                return null;
+            return (_jsx(RunScreen, { header: headerElement, featureName: featureName, projectRoot: sessionState.projectRoot, sessionState: sessionState, monitorOnly: monitorOnly, onComplete: handleRunComplete, onBackground: handleRunBackground, onCancel: () => navigate('shell') }));
+        }
+        default: {
+            // Return fallback UI instead of calling navigate() during render (which would be setState during render).
+            // The useEffect guard above will redirect to shell on next tick.
+            const unknownScreen = currentScreen;
+            logger.error(`Unknown screen: ${unknownScreen}`);
+            return (_jsx(Box, { flexDirection: "column", padding: 1, children: _jsxs(Text, { color: "red", children: ["Internal error: unknown screen \"", unknownScreen, "\". Redirecting to shell..."] }) }));
         }
-    };
-    // Render with thread history (Static) + current screen
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: threadHistory, children: (item) => (_jsx(Box, { children: item.content }, item.id)) }, threadResetKey), !isTransitioning && renderCurrentScreen()] }));
+    }
 }
 /**
  * Render the App component to the terminal
- *
- * Helper function that wraps Ink's render() to provide a clean API
- * for starting the TUI from command handlers.
- *
- * @param options - Render options
- * @returns Ink Instance that can be used to control/cleanup the render
- *
- * @example
- * ```typescript
- * const instance = renderApp({
- *   screen: 'welcome',
- *   initialSessionState: state,
- *   version: '0.8.0',
- *   onExit: () => instance.unmount(),
- * });
- *
- * await instance.waitUntilExit();
- * ```
  */
 export function renderApp(options) {
-    if (options.screen === 'welcome') {
-        process.stdout.write('\x1b[3J\x1b[2J\x1b[0;0H');
-    }
     return render(_jsx(App, { screen: options.screen, initialSessionState: options.initialSessionState, version: options.version, interviewProps: options.interviewProps, onComplete: options.onComplete, onExit: options.onExit }));
 }
-//# sourceMappingURL=app.js.map

package/dist/tui/components/ActionOutput.d.ts

@@ -78,4 +78,3 @@ export interface ActionListProps {
  * Displays a list of actions with their outputs.
  */
 export declare function ActionList({ actions, previewLines, }: ActionListProps): React.ReactElement;
-//# sourceMappingURL=ActionOutput.d.ts.map

package/dist/tui/components/ActionOutput.js

@@ -99,4 +99,3 @@ export function ActionOutput({ actionName, description, status, output, error, p
 export function ActionList({ actions, previewLines = 3, }) {
     return (_jsx(Box, { flexDirection: "column", gap: 1, children: actions.map((action) => (_jsx(ActionOutput, { actionName: action.actionName, description: action.description, status: action.status, output: action.output, error: action.error, previewLines: previewLines }, action.id))) }));
 }
-//# sourceMappingURL=ActionOutput.js.map

package/dist/tui/components/AppShell.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AppShell - Inline layout wrapper for TUI screens
+ *
+ * Provides a 6-zone inline layout that renders at natural height
+ * after the shell prompt. Screen transitions are clean React
+ * mount/unmount cycles.
+ *
+ * Zones:
+ *  1. Header: banner + status meta
+ *  2. TipsBar: contextual hints (1 row or 0)
+ *  3. Content: screen-specific (natural height)
+ *  4. Spinner: WorkingIndicator (1 row when active, 0 otherwise)
+ *  5. Error toast: error message (1 row when present, 0 otherwise)
+ *  6. Footer: input + status line
+ */
+import React from 'react';
+import { type FooterStatusBarProps } from './FooterStatusBar.js';
+/**
+ * Props for the AppShell component
+ */
+export interface AppShellProps {
+    /** Pre-built header element (HeaderContent) */
+    header: React.ReactNode;
+    /** Tip text (null/undefined to hide tips bar) */
+    tips?: string | null;
+    /** Content area - screen-specific */
+    children: React.ReactNode;
+    /** Show spinner bar */
+    isWorking?: boolean;
+    /** Spinner text */
+    workingStatus?: string;
+    /** Spinner hint (e.g. "esc to cancel") */
+    workingHint?: string;
+    /** Error message to display as a toast above the footer */
+    error?: string | null;
+    /** Input component: ChatInput, MultiSelect, Select, etc. */
+    input?: React.ReactNode;
+    /** Footer status bar props */
+    footerStatus: FooterStatusBarProps;
+}
+/**
+ * AppShell component
+ *
+ * Compact inline layout. Renders at natural height right after
+ * the shell prompt. Each zone stacks vertically with gap spacing.
+ */
+export declare function AppShell({ header, tips, children, isWorking, workingStatus, workingHint, error, input, footerStatus, }: AppShellProps): React.ReactElement;

package/dist/tui/components/AppShell.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { TipsBar } from './TipsBar.js';
+import { WorkingIndicator } from './WorkingIndicator.js';
+import { FooterStatusBar } from './FooterStatusBar.js';
+import { phase, theme } from '../theme.js';
+/**
+ * AppShell component
+ *
+ * Compact inline layout. Renders at natural height right after
+ * the shell prompt. Each zone stacks vertically with gap spacing.
+ */
+export function AppShell({ header, tips, children, isWorking = false, workingStatus = '', workingHint, error, input, footerStatus, }) {
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Box, { marginTop: 1, flexDirection: "column", children: header }), tips && _jsx(TipsBar, { text: tips }), children, isWorking && (_jsx(WorkingIndicator, { state: {
+                    isWorking: true,
+                    status: workingStatus,
+                    hint: workingHint,
+                }, variant: "active" })), error && (_jsxs(Text, { color: theme.colors.error, children: [phase.error, " ", error] })), _jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [input, _jsx(FooterStatusBar, { ...footerStatus })] })] }));
+}

package/dist/tui/components/ChatInput.d.ts

@@ -62,4 +62,3 @@ export interface ChatInputProps {
  * ```
  */
 export declare function ChatInput({ onSubmit, placeholder, disabled, allowEmpty, commands, onCommand, }: ChatInputProps): React.ReactElement;
-//# sourceMappingURL=ChatInput.d.ts.map

package/dist/tui/components/ChatInput.js

@@ -252,4 +252,3 @@ export function ChatInput({ onSubmit, placeholder = 'Type your message...', disa
     const remainder = rightText ? rightText.slice(1) : '';
     return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: theme.colors.prompt, bold: true, children: [theme.chars.prompt, ' '] }), value.length === 0 ? (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { inverse: true, children: ' ' }), _jsx(Text, { dimColor: true, children: placeholder })] })) : (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: leftText }), _jsx(Text, { inverse: true, children: cursorChar }), _jsx(Text, { children: remainder })] }))] }), showDropdown && isSlashCommand && !hasSpace && (_jsx(CommandDropdown, { commands: commands, filter: commandFilter, onSelect: handleCommandSelect, onCancel: handleDropdownCancel }))] }));
 }
-//# sourceMappingURL=ChatInput.js.map

package/dist/tui/components/CommandDropdown.d.ts

@@ -52,4 +52,3 @@ export declare function CommandDropdown({ commands, filter, onSelect, onCancel,
  * Default commands available in wiggum
  */
 export declare const DEFAULT_COMMANDS: Command[];
-//# sourceMappingURL=CommandDropdown.d.ts.map

package/dist/tui/components/CommandDropdown.js

@@ -89,4 +89,3 @@ export const DEFAULT_COMMANDS = [
     { name: 'clear', description: 'Clear conversation history' },
     { name: 'exit', description: 'Exit wiggum' },
 ];
-//# sourceMappingURL=CommandDropdown.js.map

package/dist/tui/components/Confirm.d.ts

@@ -36,4 +36,3 @@ export interface ConfirmProps {
  * ```
  */
 export declare function Confirm({ message, onConfirm, onCancel, initialValue, }: ConfirmProps): React.ReactElement;
-//# sourceMappingURL=Confirm.d.ts.map