overarch-linux-arm64 0.8.0

package/dist/src/cli/repl.js

@@ -0,0 +1,821 @@
+import * as readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { styleText, promisify } from 'node:util';
+import { exec } from 'node:child_process';
+import { SessionManager } from '../session/manager.js';
+import { AgentRuntime } from '../agent/runtime.js';
+import { buildContext, inspectProjectContext } from '../agent/context.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { resetAbort } from '../security/guardrails.js';
+import { createProvider, resolveModel, listModels, OfflineProvider } from '../providers/factory.js';
+import { runSetup } from './commands/onboarding.js';
+import { doctor } from './commands/doctor.js';
+import { init } from './commands/init.js';
+import { status } from './commands/status.js';
+import { handleConfigCommand } from './commands/config.js';
+import { handleMemoryCommand, handleLearnCommand } from './commands/memory.js';
+import { handleCompanionCommand } from './commands/companion.js';
+import { loadConfig, saveGlobalConfig, autoEnsureOverarch, getApiKey } from '../config/index.js';
+import { petdexBridge } from '../companion/petdex_bridge.js';
+import { parseCcssCommand, CCSS_MODE_CONFIGS } from '../agent/planner.js';
+import { CheckpointManager } from '../tools/checkpoint.js';
+import * as ui from './ui.js';
+const execAsync = promisify(exec);
+function resolveRuntimeProvider(config, modelOverride) {
+    if (config.mode === 'offline') {
+        return {
+            provider: new OfflineProvider(),
+            model: 'offline',
+            displayName: 'Offline Mode (AI disabled)',
+            isOffline: true
+        };
+    }
+    const modelId = modelOverride || config.defaultModel;
+    let resolved = modelId ? resolveModel(modelId) : undefined;
+    // 1. If an explicit model is requested or configured, try initializing it
+    if (resolved && resolved.provider !== 'none') {
+        const hasKey = config.providers[resolved.provider]?.apiKey || getApiKey(resolved.provider);
+        if (hasKey) {
+            try {
+                const providerConfig = config.providers[resolved.provider] || {};
+                const provider = createProvider(resolved.provider, providerConfig);
+                return { provider, model: resolved.model, displayName: resolved.displayName, isOffline: false };
+            }
+            catch (err) {
+                ui.warn(`Failed to initialize provider '${resolved.provider}': ${err.message}`);
+            }
+        }
+    }
+    // 2. Fallback: Automatically check environment for any available provider key!
+    // Priority: OpenRouter (multi-provider), Anthropic, OpenAI, Gemini
+    const providerCandidates = [
+        { id: 'openrouter', defaultModel: 'openrouter/auto', name: 'OpenRouter' },
+        { id: 'anthropic', defaultModel: 'claude-3-5-sonnet-20241022', name: 'Anthropic' },
+        { id: 'openai', defaultModel: 'gpt-4o', name: 'OpenAI' },
+        { id: 'gemini', defaultModel: 'gemini-2.5-flash', name: 'Google Gemini' }
+    ];
+    for (const candidate of providerCandidates) {
+        const key = config.providers[candidate.id]?.apiKey || getApiKey(candidate.id);
+        if (key) {
+            try {
+                const provider = createProvider(candidate.id, config.providers[candidate.id] || {});
+                const autoResolved = resolveModel(candidate.defaultModel, candidate.id) || {
+                    provider: candidate.id,
+                    model: candidate.defaultModel,
+                    displayName: `${candidate.name} (${candidate.defaultModel})`
+                };
+                config.defaultModel = autoResolved.model;
+                if (modelId && resolved && resolved.provider !== candidate.id) {
+                    ui.info(`Provider '${resolved.provider}' key not detected. Automatically using active ${candidate.name} key.`);
+                }
+                return {
+                    provider,
+                    model: autoResolved.model,
+                    displayName: autoResolved.displayName,
+                    isOffline: false
+                };
+            }
+            catch { }
+        }
+    }
+    // 3. Clean offline fallback when no provider keys exist
+    return {
+        provider: new OfflineProvider(),
+        model: 'offline',
+        displayName: 'Offline Mode (No API key found — run /setup)',
+        isOffline: true
+    };
+}
+export async function startRepl(initialConfig, args) {
+    let config = initialConfig;
+    // Apply UI accent and avatar from config
+    if (config.ui?.accentColor) {
+        ui.setAccent(config.ui.accentColor);
+    }
+    if (config.ui?.avatar) {
+        ui.setAvatar(config.ui.avatar);
+    }
+    let cwd = process.cwd();
+    await autoEnsureOverarch(cwd);
+    // Initialize optional Petdex companion bridge (non-blocking)
+    await petdexBridge.start().catch(() => { });
+    let checkpointManager = new CheckpointManager(cwd);
+    let sessionManager = new SessionManager(undefined, cwd);
+    let providerResult = resolveRuntimeProvider(config, args.model);
+    // Session resolution: resume by ID prefix or latest
+    let session;
+    if (args.resume) {
+        if (args.prompt && /^[0-9a-f-]{4,36}$/i.test(args.prompt.trim())) {
+            session = await sessionManager.findSession(args.prompt.trim());
+            if (session) {
+                args.prompt = undefined;
+            }
+        }
+        if (!session) {
+            session = await sessionManager.latest();
+        }
+    }
+    if (!session) {
+        session = await sessionManager.create(cwd, providerResult.model);
+    }
+    else {
+        ui.info(`Resumed session ${ui.bold(session.id.slice(0, 8))} (${session.messages.length} messages)`);
+    }
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const registry = ToolRegistry.createDefault();
+    let agentRuntime = new AgentRuntime(providerResult.provider, registry, {
+        ...config,
+        defaultModel: providerResult.model,
+    }, { autoApprove: args.yes || config.agentMode === 'autonomous', rl, cwd });
+    if (session && session.messages.length > 0) {
+        const pastMessages = session.messages.map(m => ({
+            role: m.role,
+            content: m.content,
+            toolCallId: m.toolCallId,
+            toolCalls: m.toolCalls
+        }));
+        agentRuntime.setMessages(pastMessages);
+    }
+    let systemContext = await buildContext(cwd, config);
+    // Clean Header
+    console.log();
+    ui.banner();
+    console.log(styleText('dim', '────────────────────────────────────────'));
+    console.log(`  ${styleText('dim', 'Project:')}    ${cwd}`);
+    console.log(`  ${styleText('dim', 'Model:')}      ${providerResult.displayName} ${styleText('dim', `(${providerResult.model})`)}`);
+    console.log(`  ${styleText('dim', 'Session:')}    ${session.id.slice(0, 8)} ${session.messages.length > 0 ? styleText('dim', '(resumed)') : styleText('dim', '(new)')}`);
+    console.log(`  ${styleText('dim', 'Agent Mode:')} ${config.agentMode} | CCSS: ${config.ccss} | Ponytail: ${config.ponytail}`);
+    console.log(styleText('dim', '────────────────────────────────────────'));
+    console.log(`${ui.dim('Type')} /help ${ui.dim('for categorized commands, or enter a prompt to begin.\n')}`);
+    let isGenerating = false;
+    let isExiting = false;
+    process.on('SIGINT', async () => {
+        if (isGenerating) {
+            agentRuntime.abort();
+            console.log(`\n${ui.yellow('!')} Operation aborted.`);
+            isGenerating = false;
+        }
+        else {
+            if (!isExiting) {
+                isExiting = true;
+                try {
+                    await sessionManager.save(session);
+                }
+                catch { }
+                console.log(`\n${ui.accent(ui.getAvatar())} Session saved. Goodbye!`);
+                process.exit(0);
+            }
+        }
+    });
+    const toolTimers = new Map();
+    let thinkingSpin = null;
+    const stopThinking = () => {
+        if (thinkingSpin) {
+            thinkingSpin.stop();
+            thinkingSpin = null;
+        }
+    };
+    const callbacks = {
+        onText: (chunk) => {
+            stopThinking();
+            process.stdout.write(chunk);
+        },
+        onToolStart: (name, params) => {
+            stopThinking();
+            const summary = Object.entries(params).map(([k, v]) => {
+                const val = typeof v === 'string' ? (v.length > 40 ? v.slice(0, 40) + '...' : v) : JSON.stringify(v);
+                return `${k}=${val}`;
+            }).join(' ');
+            toolTimers.set(name, performance.now());
+            ui.toolStart(name, summary);
+        },
+        onToolEnd: (name, result) => {
+            const start = toolTimers.get(name);
+            const ms = start ? Math.round(performance.now() - start) : 0;
+            ui.toolEnd(name, result.success, ms);
+            if (result.metadata?.diff) {
+                const diffOutput = ui.formatDiff(String(result.metadata.diff));
+                if (diffOutput) {
+                    console.log(diffOutput);
+                }
+            }
+            if (!result.success && result.error) {
+                ui.fail(`${name}: ${result.error}`);
+            }
+            // Resume thinking spinner while LLM processes tool result
+            thinkingSpin = ui.thinkingSpinner();
+        },
+        onPlan: (plan) => {
+            stopThinking();
+            console.log();
+            ui.heading('Task Roadmap');
+            plan.steps.forEach((s, i) => {
+                const status = s.status === 'done' ? 'done' : s.status === 'failed' ? 'failed' : s.status === 'running' ? 'in-progress' : 'pending';
+                ui.planStep(i + 1, s.description, status);
+            });
+            console.log();
+        },
+        onError: (error) => {
+            stopThinking();
+            ui.error(error.message);
+        },
+        onStateChange: (newState, message) => {
+            petdexBridge.broadcastState(newState, message);
+            if (newState === 'thinking') {
+                if (!thinkingSpin) {
+                    thinkingSpin = ui.thinkingSpinner(message);
+                }
+                else if (message) {
+                    thinkingSpin.setAction(message);
+                }
+            }
+            else {
+                stopThinking();
+            }
+        },
+        onReport: (report) => {
+            stopThinking();
+            if (report.filesModified.length > 0) {
+                console.log(`\n${ui.dim('◆')} ${ui.accent('Changes:')} ${report.filesModified.length} file(s) modified ${ui.dim(`(${report.verificationStatus})`)}`);
+            }
+        }
+    };
+    const runAgent = async (promptText) => {
+        if (providerResult.isOffline) {
+            ui.warn('Offline Mode is active. AI completions are disabled.');
+            console.log(ui.dim('Run /setup or /config provider to connect an AI provider.'));
+            return;
+        }
+        isGenerating = true;
+        resetAbort();
+        sessionManager.addMessage(session, {
+            role: 'user',
+            content: promptText,
+            timestamp: new Date().toISOString(),
+        });
+        console.log(`\n${ui.dim(`─── ${ui.getAvatar()} Overarch ──────────────────────────────`)}`);
+        const start = performance.now();
+        try {
+            thinkingSpin = ui.thinkingSpinner();
+            await agentRuntime.run(promptText, systemContext, callbacks);
+        }
+        catch (err) {
+            stopThinking();
+            if (err.name !== 'AbortError' && err.message !== 'Aborted') {
+                ui.error(`\nProvider Error: ${err.message}`);
+            }
+        }
+        finally {
+            stopThinking();
+        }
+        const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+        console.log(`\n${ui.dim(`──────────────────────────────────── (${elapsed}s)`)}\n`);
+        // Sync messages
+        const currentMessages = agentRuntime.getMessages();
+        const newMessages = currentMessages.slice(session.messages.length);
+        for (const msg of newMessages) {
+            sessionManager.addMessage(session, {
+                role: msg.role,
+                content: msg.content,
+                toolCallId: msg.toolCallId,
+                toolCalls: msg.toolCalls,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        await sessionManager.save(session);
+        isGenerating = false;
+    };
+    if (args.prompt) {
+        ui.userMessage(args.prompt);
+        await runAgent(args.prompt);
+    }
+    while (!isExiting) {
+        let input;
+        try {
+            input = await rl.question(ui.prompt());
+        }
+        catch {
+            break;
+        }
+        const command = input.trim();
+        if (!command)
+            continue;
+        // ─────────────────────────────────────────────────────────────
+        // 1. SESSION COMMANDS
+        // ─────────────────────────────────────────────────────────────
+        if (command === '/exit' || command === '/quit') {
+            await sessionManager.save(session);
+            ui.success('Session saved. Goodbye!');
+            isExiting = true;
+            break;
+        }
+        if (command === '/clear') {
+            agentRuntime.setMessages([]);
+            session.messages = [];
+            await sessionManager.save(session);
+            ui.info('Conversation history cleared.');
+            continue;
+        }
+        if (command === '/new') {
+            await sessionManager.save(session);
+            session = await sessionManager.create(cwd, providerResult.model);
+            agentRuntime.setMessages([]);
+            ui.success(`Created fresh session: ${ui.bold(session.id.slice(0, 8))}`);
+            continue;
+        }
+        if (command.startsWith('/resume')) {
+            const targetId = command.replace(/^\/resume\s*/, '').trim();
+            const targetSession = targetId ? await sessionManager.findSession(targetId) : await sessionManager.latest();
+            if (!targetSession) {
+                ui.warn(`No session matching '${targetId || 'latest'}' found.`);
+                continue;
+            }
+            await sessionManager.save(session);
+            session = targetSession;
+            agentRuntime.setMessages(session.messages.map(m => ({
+                role: m.role,
+                content: m.content,
+                toolCallId: m.toolCallId,
+                toolCalls: m.toolCalls
+            })));
+            ui.success(`Resumed session ${ui.bold(session.id.slice(0, 8))} (${session.messages.length} messages)`);
+            continue;
+        }
+        if (command === '/sessions') {
+            const list = await sessionManager.list();
+            ui.heading('Saved Sessions');
+            if (list.length === 0) {
+                console.log(ui.dim('No saved sessions.'));
+            }
+            else {
+                for (const s of list.slice(0, 8)) {
+                    const isCur = s.id === session.id ? ui.accent('*') : ' ';
+                    const summary = s.summary ? ` — "${s.summary}"` : '';
+                    console.log(` ${isCur} ${ui.bold(s.id.slice(0, 8))} ${ui.dim(`[${s.model}]`)} ${ui.dim(`(${s.messageCount} msgs)`)}${summary}`);
+                    console.log(`     ${ui.dim(new Date(s.lastActiveAt).toLocaleString())} ${ui.dim(s.cwd)}`);
+                }
+            }
+            continue;
+        }
+        // ─────────────────────────────────────────────────────────────
+        // 2. PROJECT & CONTEXT COMMANDS
+        // ─────────────────────────────────────────────────────────────
+        if (command === '/init') {
+            await init();
+            systemContext = await buildContext(cwd, config);
+            continue;
+        }
+        if (command === '/context') {
+            const metrics = await inspectProjectContext(cwd);
+            ui.statusCard('Workspace Context Intelligence', {
+                'Directory': metrics.cwd,
+                'Project Stacks': metrics.projectTypes.join(', ') || 'General',
+                'Git Branch / Status': `${metrics.gitBranch} (${metrics.gitStatus})`,
+                'Discovered Files': `${metrics.filesDiscovered} files (${metrics.filesSample.join(', ')}...)`,
+                'Instructions File': metrics.instructionsSource || 'None loaded',
+                'Memory Entries': `${metrics.memoryEntriesCount} entries in .overarch/memory.md`,
+                'Estimated Tokens': `~${metrics.estimatedTokens} tokens`
+            });
+            continue;
+        }
+        if (command === '/reload' || command === '/refresh') {
+            config = await loadConfig();
+            systemContext = await buildContext(cwd, config);
+            if (config.ui?.accentColor)
+                ui.setAccent(config.ui.accentColor);
+            if (config.ui?.avatar)
+                ui.setAvatar(config.ui.avatar);
+            ui.success('Project context, instructions, and configuration reloaded.');
+            continue;
+        }
+        if (command === '/project' || command.startsWith('/project ')) {
+            const targetDir = command.replace(/^\/project\s*/, '').trim();
+            if (!targetDir || targetDir === 'status') {
+                const metrics = await inspectProjectContext(cwd);
+                ui.statusCard('Active Project Information', {
+                    'Directory': cwd,
+                    'Tech Ecosystem': metrics.projectTypes.join(', ') || 'General',
+                    'Git Branch': metrics.gitBranch,
+                    'Files Discovered': metrics.filesDiscovered,
+                    'Instructions': metrics.instructionsSource || 'None',
+                    'Memory Log': `${metrics.memoryEntriesCount} items`
+                });
+            }
+            else if (targetDir === 'recent') {
+                const sessions = await sessionManager.list();
+                const projects = Array.from(new Set(sessions.map(s => s.cwd)));
+                ui.heading('Recently Accessed Projects');
+                projects.slice(0, 6).forEach((p, idx) => {
+                    const isCur = p === cwd ? ui.accent(' (current)') : '';
+                    console.log(`  ${idx + 1}. ${p}${isCur}`);
+                });
+            }
+            else {
+                const resolved = path.resolve(cwd, targetDir);
+                try {
+                    const stats = await fs.stat(resolved);
+                    if (!stats.isDirectory()) {
+                        ui.error(`Not a directory: ${resolved}`);
+                        continue;
+                    }
+                    process.chdir(resolved);
+                    cwd = resolved;
+                    await autoEnsureOverarch(cwd);
+                    sessionManager = new SessionManager(undefined, cwd);
+                    checkpointManager = new CheckpointManager(cwd);
+                    systemContext = await buildContext(cwd, config);
+                    session = await sessionManager.create(cwd, session.model);
+                    agentRuntime.setMessages([]);
+                    ui.success(`Switched workspace to: ${cwd}`);
+                    ui.info(`Fresh session created for workspace: ${session.id.slice(0, 8)}`);
+                }
+                catch (e) {
+                    ui.error(`Cannot switch directory: ${e.message}`);
+                }
+            }
+            continue;
+        }
+        if (command === '/memory' || command.startsWith('/memory ')) {
+            const rest = command.replace(/^\/memory\s*/, '').trim();
+            const parts = rest.split(/\s+/);
+            const sub = parts[0] || 'show';
+            const arg1 = parts.slice(1).join(' ');
+            if (sub === 'search') {
+                await handleMemoryCommand('search', arg1);
+            }
+            else if (sub === 'forget') {
+                await handleMemoryCommand('forget', parts[1]);
+            }
+            else if (sub === 'show' || sub === 'list' || !rest) {
+                await handleMemoryCommand('show');
+            }
+            else {
+                // If user typed a raw note e.g. /memory Use pnpm for tests
+                await handleMemoryCommand('learn', rest);
+            }
+            continue;
+        }
+        if (command === '/learn' || command.startsWith('/learn ')) {
+            const lessonText = command.replace(/^\/learn\s*/, '').trim();
+            await handleLearnCommand(lessonText);
+            continue;
+        }
+        // ─────────────────────────────────────────────────────────────
+        // 3. AI, MODEL & AGENT MODE COMMANDS
+        // ─────────────────────────────────────────────────────────────
+        if (command.startsWith('/model')) {
+            const newModel = command.replace(/^\/model\s*/, '').trim();
+            if (!newModel) {
+                const models = listModels();
+                ui.heading('Available Models');
+                models.forEach(m => {
+                    const isCur = m.id === session.model ? ui.accent(' (active)') : '';
+                    console.log(`  ${ui.bold(m.id)} ${ui.dim(`[${m.provider}]`)} — ${m.name}${isCur}`);
+                });
+                console.log(`\nUsage: /model <model_id> (e.g. /model claude-3-5-sonnet-20241022 or /model gpt-4o)`);
+                continue;
+            }
+            try {
+                const resolved = resolveModel(newModel);
+                if (!resolved) {
+                    ui.warn(`Model '${newModel}' could not be resolved automatically. Attempting raw switch.`);
+                }
+                const modelId = resolved ? resolved.model : newModel;
+                session.model = modelId;
+                config.defaultModel = modelId;
+                config.mode = 'online';
+                providerResult = resolveRuntimeProvider(config, modelId);
+                agentRuntime = new AgentRuntime(providerResult.provider, registry, {
+                    ...config,
+                    defaultModel: providerResult.model
+                }, { autoApprove: args.yes || config.agentMode === 'autonomous', rl });
+                agentRuntime.setMessages(session.messages.map(m => ({ role: m.role, content: m.content })));
+                await saveGlobalConfig({ defaultModel: modelId, mode: 'online' });
+                ui.success(`Switched model to: ${ui.bold(providerResult.displayName)} (${providerResult.model})`);
+            }
+            catch (err) {
+                ui.error(`Failed to switch model: ${err.message}`);
+            }
+            continue;
+        }
+        if (command === '/plan' || command.startsWith('/plan ')) {
+            const arg = command.replace(/^\/plan\s*/, '').trim().toLowerCase();
+            if (arg === 'on') {
+                config.agentMode = 'plan';
+                ui.success('Plan Mode: ENABLED. Overarch will structure explicit roadmaps before code changes.');
+            }
+            else if (arg === 'off') {
+                config.agentMode = 'approval';
+                ui.info('Plan Mode: DISABLED (Standard approval mode).');
+            }
+            else {
+                const isPlan = config.agentMode === 'plan';
+                config.agentMode = isPlan ? 'approval' : 'plan';
+                ui.info(`Plan Mode toggled: ${config.agentMode === 'plan' ? ui.green('ON') : ui.dim('OFF')}`);
+            }
+            agentRuntime.setConfig(config);
+            continue;
+        }
+        // ─────────────────────────────────────────────────────────────
+        // 4. PRESERVED & ENHANCED TRIAD COMMANDS: /ponytail, /ccss-5-0, /cchcfai, /design-critique
+        // ─────────────────────────────────────────────────────────────
+        if (command === '/ponytail' || command.startsWith('/ponytail ')) {
+            const level = command.replace(/^\/ponytail\s*/, '').trim().toLowerCase();
+            if (level === 'lite' || level === 'full' || level === 'ultra') {
+                config.ponytail = level;
+                await saveGlobalConfig({ ponytail: level });
+                systemContext = await buildContext(cwd, config);
+                ui.success(`Ponytail mode set to: ${ui.bold(level.toUpperCase())}`);
+                console.log(ui.dim(level === 'ultra' ? 'Ultra YAGNI: shortest diff, zero extra abstractions, stdlib first.' : 'Enforcing senior dev simplicity ladder.'));
+            }
+            else {
+                console.log(`\n${ui.accent(ui.getAvatar())} ${ui.bold('Ponytail Mode')}: ${config.ponytail.toUpperCase()}`);
+                console.log('The lazy senior dev ladder: YAGNI, stdlib over deps, shortest working diff.');
+                console.log(`Usage: /ponytail lite | full | ultra\n`);
+            }
+            continue;
+        }
+        if (command === '/ccss' || command === '/ccss-5-0' || command.startsWith('/ccss ') || command.startsWith('/ccss-5-0 ')) {
+            const parsed = parseCcssCommand(command);
+            if (parsed.isStatus) {
+                const activeCfg = CCSS_MODE_CONFIGS[config.ccss || 'auto'];
+                ui.statusCard('CCSS 5.0 Orchestration Status', {
+                    'Active Mode': activeCfg.name,
+                    'Description': activeCfg.description,
+                    'Planning Depth': activeCfg.planningDepth,
+                    'Pre-Mutation Checkpoint': activeCfg.requireCheckpoint ? 'Enforced' : 'Optional',
+                    'Verification Intensity': activeCfg.verificationIntensity.toUpperCase(),
+                    'Parallel Inspection': activeCfg.parallelInspection ? 'Enabled' : 'Disabled',
+                    'Approval Gate': activeCfg.approvalGate
+                });
+                continue;
+            }
+            if (parsed.mode) {
+                config.ccss = parsed.mode;
+                await saveGlobalConfig({ ccss: parsed.mode });
+                agentRuntime.setConfig(config);
+                systemContext = await buildContext(cwd, config);
+                ui.success(`CCSS 5.0 mode set to: ${ui.bold(parsed.mode.toUpperCase())}`);
+                if (parsed.prompt) {
+                    ui.userMessage(parsed.prompt);
+                    await runAgent(parsed.prompt);
+                }
+                continue;
+            }
+            if (parsed.prompt) {
+                await runAgent(parsed.prompt);
+                continue;
+            }
+            console.log(`\n${ui.accent(ui.getAvatar())} ${ui.bold('CCSS 5.0 Mission Orchestration')}: ${config.ccss.toUpperCase()}`);
+            console.log('Orchestrate complex tasks with capability discovery, verification checkpoints, and recovery.');
+            console.log(`Usage: /ccss auto | master | god | control [prompt]\n`);
+            continue;
+        }
+        if (command === '/checkpoint' || command.startsWith('/checkpoint ')) {
+            const name = command.replace(/^\/checkpoint\s*/, '').trim() || 'manual';
+            try {
+                const info = await checkpointManager.create(name);
+                ui.success(`Created checkpoint: ${ui.bold(info.id)} (${info.name}) [${info.type}]`);
+            }
+            catch (err) {
+                ui.error(`Failed to create checkpoint: ${err.message}`);
+            }
+            continue;
+        }
+        if (command === '/checkpoints') {
+            const list = await checkpointManager.list();
+            ui.heading('Saved Checkpoints');
+            if (list.length === 0) {
+                console.log(ui.dim('No checkpoints saved yet. Create one using: /checkpoint [name]'));
+            }
+            else {
+                list.slice(0, 10).forEach((c, idx) => {
+                    console.log(`  ${idx + 1}. ${ui.bold(c.id)} — ${c.name} ${ui.dim(`(${c.type} at ${new Date(c.timestamp).toLocaleTimeString()})`)}`);
+                });
+            }
+            continue;
+        }
+        if (command === '/rollback' || command.startsWith('/rollback ')) {
+            const targetId = command.replace(/^\/rollback\s*/, '').trim() || undefined;
+            const res = await checkpointManager.rollback(targetId);
+            if (res.success) {
+                ui.success(`Rolled back successfully to checkpoint ${targetId || 'latest'}.`);
+                if (res.output)
+                    console.log(ui.dim(res.output));
+            }
+            else {
+                ui.fail(`Rollback failed: ${res.error}`);
+            }
+            continue;
+        }
+        if (command === '/diff' || command === '/changes') {
+            try {
+                const { stdout: diffOut } = await execAsync('git diff HEAD', { cwd });
+                if (!diffOut.trim()) {
+                    ui.info('Working tree is clean (no uncommitted diffs).');
+                }
+                else {
+                    const formatted = ui.formatDiff(diffOut);
+                    console.log(formatted || diffOut);
+                }
+            }
+            catch {
+                ui.warn('Git diff unavailable in current directory.');
+            }
+            continue;
+        }
+        if (command === '/retry') {
+            const userMsgs = session.messages.filter(m => m.role === 'user');
+            const lastMsg = userMsgs[userMsgs.length - 1];
+            if (!lastMsg) {
+                ui.warn('No previous prompt to retry.');
+                continue;
+            }
+            ui.info(`Retrying last prompt: "${ui.bold(lastMsg.content)}"`);
+            await runAgent(lastMsg.content);
+            continue;
+        }
+        if (command === '/cchcfai' || command.startsWith('/cchcfai ')) {
+            const action = command.replace(/^\/cchcfai\s*/, '').trim().toLowerCase();
+            if (action === 'gate') {
+                config.agentMode = 'approval';
+                ui.success('CCHCFAI Gate: Human approval required for all state-mutating actions.');
+            }
+            else if (action === 'halt' || action === 'stop') {
+                agentRuntime.abort();
+                ui.warn('CCHCFAI Emergency Stop: Agent paused and yielded control.');
+            }
+            else if (action === 'audit') {
+                ui.statusCard('CCHCFAI Human Control Audit', {
+                    'Autonomy Mode': config.agentMode.toUpperCase(),
+                    'Auto-Approved': config.permissions.autoApprove.join(', '),
+                    'Requires Approval': config.permissions.requireApproval.join(', '),
+                    'Denied Tools': config.permissions.deny.join(', ') || 'none',
+                    'Emergency Stop': 'Active (Ctrl+C or /halt)'
+                });
+            }
+            else {
+                console.log(`\n${ui.accent(ui.getAvatar())} ${ui.bold('CCHCFAI Human Control Architecture')}`);
+                console.log('Autonomy is bounded, observable, interruptible, and subordinate to the human.');
+                console.log(`Usage: /cchcfai gate | audit | halt | status\n`);
+            }
+            continue;
+        }
+        if (command === '/design-critique' || command.startsWith('/design-critique ')) {
+            ui.heading('Design & UX Review Mode');
+            console.log('Overarch evaluates visual hierarchy, layout, typography, and accessibility.');
+            console.log('Enter prompt describing UI component, terminal output, or design spec to critique.\n');
+            continue;
+        }
+        // ─────────────────────────────────────────────────────────────
+        // 5. FLOATING DESKTOP COMPANION: /companion, /petdex [start|stop|pets|select|install|status]
+        // ─────────────────────────────────────────────────────────────
+        if (command === '/companion' || command.startsWith('/companion ') || command === '/petdex' || command.startsWith('/petdex ')) {
+            const isPetdex = command.startsWith('/petdex');
+            const prefix = isPetdex ? /^\/petdex\s*/ : /^\/companion\s*/;
+            const rest = command.replace(prefix, '').trim();
+            const parts = rest.split(/\s+/);
+            const sub = parts[0] || 'status';
+            const arg = parts.slice(1).join(' ');
+            await handleCompanionCommand(sub, arg);
+            continue;
+        }
+        // ─────────────────────────────────────────────────────────────
+        // 6. SYSTEM & DIAGNOSTIC COMMANDS: /doctor, /status, /config, /setup, /tools
+        // ─────────────────────────────────────────────────────────────
+        if (command === '/doctor') {
+            await doctor();
+            continue;
+        }
+        if (command === '/status') {
+            await status();
+            continue;
+        }
+        if (command.startsWith('/config')) {
+            const rawParts = command.replace(/^\/config\s*/, '').trim().split(/\s+/);
+            const sub = rawParts[0] || 'show';
+            const key = rawParts[1];
+            const val = rawParts.slice(2).join(' ');
+            await handleConfigCommand(sub, key, val);
+            continue;
+        }
+        if (command === '/setup') {
+            await runSetup(rl);
+            config = await loadConfig();
+            providerResult = resolveRuntimeProvider(config);
+            agentRuntime = new AgentRuntime(providerResult.provider, registry, {
+                ...config,
+                defaultModel: providerResult.model
+            }, { autoApprove: args.yes || config.agentMode === 'autonomous', rl });
+            systemContext = await buildContext(cwd, config);
+            ui.success('Overarch configuration updated and reloaded.');
+            continue;
+        }
+        if (command === '/tools') {
+            const tools = registry.list();
+            ui.heading('Registered Tools & MCP Connectors');
+            for (const t of tools) {
+                const isMcp = t.name.startsWith('mcp_') ? ui.accent('[MCP] ') : '';
+                console.log(`  ${ui.accent('▸')} ${isMcp}${ui.bold(t.name)} ${ui.dim(`[${t.tier}]`)} — ${t.description}`);
+            }
+            continue;
+        }
+        if (command === '/compact') {
+            args.compact = !args.compact;
+            ui.info(`Compact terminal mode: ${args.compact ? 'enabled' : 'disabled'}`);
+            continue;
+        }
+        if (command === '/abort' || command === '/halt') {
+            agentRuntime.abort();
+            ui.info('Aborted current action.');
+            continue;
+        }
+        // ─────────────────────────────────────────────────────────────
+        // 7. CATEGORIZED /HELP & CONTEXTUAL HELP
+        // ─────────────────────────────────────────────────────────────
+        if (command === '/help' || command.startsWith('/help ')) {
+            const topic = command.replace(/^\/help\s*/, '').trim().toLowerCase();
+            if (topic === 'petdex') {
+                console.log(`\n${ui.bold('Help: Petdex Integration')}\nOptional bridge to external Petdex desktop companion app via local event server.\nCommands: /petdex status, /petdex launch, /petdex pets, /petdex select <id>`);
+            }
+            else if (topic === 'model') {
+                console.log(`\n${ui.bold('Help: Model Switching')}\nSwitch active models mid-session: /model <name>\nExamples: /model claude-3-5-sonnet-20241022, /model gpt-4o, /model gemini-2.5-flash`);
+            }
+            else if (topic === 'project') {
+                console.log(`\n${ui.bold('Help: Project Management')}\nManage repository workspace context: /project [dir], /project recent, /init, /context, /reload, /memory`);
+            }
+            else if (topic === 'ponytail') {
+                console.log(`\n${ui.bold('Help: Ponytail Ladder')}\nEnforce senior dev minimalism: /ponytail lite | full | ultra\nYAGNI, stdlib before custom code, shortest working diff.`);
+            }
+            else if (topic === 'ccss') {
+                console.log(`\n${ui.bold('Help: CCSS 5.0')}\nMission orchestration: /ccss auto | master | god | control\nDecomposes tasks into verified checkpoints.`);
+            }
+            else if (topic === 'cchcfai') {
+                console.log(`\n${ui.bold('Help: CCHCFAI')}\nHuman control framework: /cchcfai gate | audit | halt | status\nEnforces 4-state separation and confirmation gates.`);
+            }
+            else {
+                console.log(`
+${ui.bold('SESSION')}
+  /status             Display diagnostic dashboard card
+  /new                Start a fresh session in current project
+  /resume [id]        Resume past session by ID or prefix
+  /sessions           List saved sessions with summaries
+  /clear              Clear conversation history
+  /exit, /quit        Save session and exit cleanly
+
+${ui.bold('PROJECT & REPOSITORY')}
+  /project [dir]      Inspect current workspace or switch directory
+  /project recent     List recently accessed projects
+  /init               Initialize .overarch subsystem for this project
+  /context            Deep inspection of files, stack, and tokens
+  /reload             Re-scan workspace context and instructions
+  /memory [note]      View or append notes in .overarch/memory.md
+  /checkpoint [name]  Create an instant git/snapshot checkpoint
+  /checkpoints        List all saved checkpoints
+  /rollback [id]      Revert repository to a previous checkpoint
+  /diff, /changes     Inspect uncommitted git working tree changes
+
+${ui.bold('AI & AGENT')}
+  /model [name]       List available models or switch active model
+  /plan [on|off]      Toggle Plan Mode (roadmap before changes)
+  /retry              Re-execute last prompt with updated approach
+  /ponytail [level]   Set Ponytail minimalism: lite | full | ultra
+  /ccss [mode]        Set CCSS mission orchestration: auto | master | god | control
+  /cchcfai [action]   Human control layer: gate | audit | halt | status
+  /design-critique    Design review mode for UI, layout, and a11y
+  /tools              List available tools, permission tiers, and MCP
+
+${ui.bold('PERSISTENT LEARNING & MEMORY')}
+  /memory [show]      Display project memory & learned episodic lessons
+  /memory search <q>  Search lessons, conventions, and architectural decisions
+  /memory forget <id> Remove a specific learned memory
+  /learn "<lesson>"   Record a new engineering insight into memory
+
+${ui.bold('FLOATING DESKTOP COMPANION (PETDEX)')}
+  /companion start    Launch floating transparent desktop companion
+  /companion stop     Close desktop companion
+  /companion status   Display companion window state and active pet
+  /companion pets     List all installed Petdex companions
+  /companion select   Switch active desktop companion
+  /companion install  Install any pet from Petdex (e.g. /companion install savage-codex-hacker)
+
+${ui.bold('SYSTEM')}
+  /doctor             Run full health and diagnostic checks
+  /config [target]    Direct configuration (provider, model, accent, permissions)
+  /setup              Reopen guided setup wizard
+  /compact            Toggle compact terminal output
+  /abort, /halt       Emergency stop current agent operation
+`);
+            }
+            continue;
+        }
+        if (command.startsWith('/')) {
+            ui.warn(`Unknown command: ${command}. Type /help for available commands.`);
+            continue;
+        }
+        await runAgent(command);
+    }
+    rl.close();
+}