magi-ai 0.1.0

package/dist/src/repl/magi-repl.js

@@ -0,0 +1,1008 @@
+/**
+ * MagiRepl — Interactive REPL for the MAGI System.
+ *
+ * Provides a Claude Code-like experience: type questions naturally,
+ * context persists across turns, and the full-screen Evangelion TUI
+ * takes over during deliberation.
+ *
+ * Key design decision (Gemini review):
+ *   readline is **close → recreate** per deliberation rather than
+ *   pause/resume, to avoid stdin state conflicts with the TUI's raw mode.
+ */
+import { createInterface } from 'node:readline/promises';
+import * as readline from 'node:readline';
+import { randomBytes } from 'node:crypto';
+import chalk from 'chalk';
+import { Magi } from '../index.js';
+import { initializeTui } from '../cli/tui-setup.js';
+import { CURSOR_SHOW, ALT_SCREEN_LEAVE, ERASE_LINE, ERASE_TO_END, moveUp } from '../tui/ansi.js';
+import { EVA_PALETTE } from '../tui/colors.js';
+import { logger } from '../utils/logger.js';
+import { ReplContext } from './context.js';
+import { createSlashCommands, parseInput, suggestCommand, } from './slash-commands.js';
+import { JobRegistry } from './job-registry.js';
+import { printBanner } from './banner.js';
+import { assertTransition } from './repl-state.js';
+import { buildPrompt, DEFAULT_SESSION_STATE } from './prompt-builder.js';
+import { createReplHistory } from './history.js';
+import { createCompleter } from './completer.js';
+import { formatResultDisplay } from './result-display.js';
+import { runReplBoot } from './boot-animation.js';
+import { createReplEventListener } from './event-listener.js';
+import { sanitizeForTerminal } from './terminal-sanitize.js';
+import { estimateTokens } from '../metrics/token-tracker.js';
+import { runHandoffAnimation } from './handoff-animation.js';
+import { createMultilineCollector, isContinuationLine, joinContinuationLines, MAX_CONTINUATION_LINES } from './multiline-input.js';
+import { createSessionStats, recordInput, recordSlashCommand, recordDeliberation, formatSessionSummary } from './session-stats.js';
+import { shouldSkipAnimation } from './accessibility.js';
+import { formatDeliberationAsJson, formatDeliberationAsMarkdown } from './export-formatter.js';
+import { emitKeypressEvents } from 'node:readline';
+import { lstat } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { safeWriteFile } from '../utils/safe-fs.js';
+import { createGhostTextEngine, isGhostTextDisabled } from './ghost-text.js';
+import { loadUserConfigSafe, mergeWithDefaults } from '../config/user-config.js';
+const { frame, abstain, approve, warning } = EVA_PALETTE;
+const FRAME_CHALK = chalk.rgb(frame.r, frame.g, frame.b);
+const DIM = chalk.rgb(abstain.r, abstain.g, abstain.b);
+const OK_C = chalk.rgb(approve.r, approve.g, approve.b);
+const WARN_C = chalk.rgb(warning.r, warning.g, warning.b);
+const TRANSITION = FRAME_CHALK;
+const MAX_INPUT_LENGTH = 100_000;
+const ENGRAM_CONTEXT_CAP = 5_000;
+const MAX_READLINE_RETRIES = 3;
+// Module-scoped: emitKeypressEvents should only be called once per process.stdin
+let keypressInitialized = false;
+function isConfirmationDispatch(result) {
+    return typeof result === 'object' && result !== null && 'confirm' in result;
+}
+function isInteractiveDispatch(result) {
+    return typeof result === 'object' && result !== null && 'interactive' in result;
+}
+export class MagiRepl {
+    magi;
+    context;
+    slashCommands;
+    soundEnabled = false;
+    state = 'INIT';
+    abortController;
+    sessionState = { ...DEFAULT_SESSION_STATE };
+    history;
+    completerFn;
+    shownEngramIds = new Set();
+    stats = createSessionStats();
+    multilineCollector = createMultilineCollector();
+    lastSigintTime = 0;
+    lastDeliberation;
+    options;
+    ghostEngine;
+    jobRegistry = new JobRegistry();
+    currentRl;
+    watchJobId;
+    watchPollIntervalMs;
+    constructor(options) {
+        this.options = options ?? {};
+        this.magi = new Magi({ logLevel: 'warn', ...this.options.magiConfig });
+        this.context = new ReplContext();
+        this.slashCommands = createSlashCommands();
+        this.history = createReplHistory(this.options.historyDir);
+        this.soundEnabled = this.options.soundEnabled ?? false;
+        // Build completer from slash command registry
+        const completableCommands = [];
+        for (const [name, cmd] of this.slashCommands) {
+            completableCommands.push({ name, argKind: cmd.argKind, aliases: cmd.aliases });
+        }
+        // Ghost text engine — inline dim gray suggestions
+        // (initialized before completer so it can be passed as suppression source)
+        const ghostSource = {
+            getSlashCommands: () => [...this.slashCommands.keys()].map(k => `/${k}`),
+            getHistory: () => this.history.getEntries(),
+            getDeliberationTitles: () => this.context.getHistory().map(e => e.title),
+        };
+        this.ghostEngine = createGhostTextEngine(ghostSource, {
+            enabled: !isGhostTextDisabled(),
+        });
+        this.completerFn = createCompleter(completableCommands, {
+            ghostEngine: this.ghostEngine,
+        });
+    }
+    get currentState() {
+        return this.state;
+    }
+    get running() {
+        return this.state !== 'DISPOSING';
+    }
+    transition(to) {
+        const from = this.state;
+        assertTransition(from, to);
+        this.state = to;
+        logger.debug('REPL state transition', { from, to });
+    }
+    async start() {
+        this.transition('READY');
+        // First-run: auto-launch setup if no config exists
+        const existingConfig = await loadUserConfigSafe();
+        if (!existingConfig) {
+            const { runSetup } = await import('../cli/commands/setup.js');
+            await runSetup();
+            // Rebuild Magi instance with the newly saved config
+            const freshConfig = await loadUserConfigSafe();
+            if (freshConfig) {
+                const merged = mergeWithDefaults(freshConfig);
+                this.magi = new Magi({ logLevel: 'warn', ...merged });
+                this.soundEnabled = freshConfig.tui?.soundEnabled ?? false;
+            }
+        }
+        // Boot animation (replaces static banner)
+        if (!this.options.skipBootAnimation) {
+            await runReplBoot({ write: s => process.stdout.write(s) });
+        }
+        // Load history for readline
+        const historyEntries = await this.history.load();
+        // Startup health check (non-blocking, updates prompt)
+        this.checkUnitsOnStartup();
+        while (this.running) {
+            const pendingTask = await this.readInputLoop(historyEntries);
+            if (!pendingTask)
+                break; // quit or EOF
+            if (pendingTask === 'continue')
+                continue;
+            await this.runDeliberation(pendingTask.task, pendingTask.berserk);
+        }
+        await this.dispose();
+    }
+    // ── Input loop ──────────────────────────────────────────────
+    async readInputLoop(historyEntries, retryCount = 0) {
+        this.transition('READING_INPUT');
+        let rl;
+        try {
+            rl = this.createReadline(historyEntries);
+        }
+        catch (error) {
+            logger.debug('readInputLoop: createReadline failed', { error: String(error) });
+            console.error(chalk.red(`\n  Failed to create readline: ${String(error)}\n`));
+            this.sessionState.hasError = true;
+            if (this.running && retryCount < MAX_READLINE_RETRIES) {
+                return this.readInputLoop(historyEntries, retryCount + 1);
+            }
+            return undefined;
+        }
+        // Continuation line buffer (for trailing-backslash mode)
+        let continuationBuffer = [];
+        try {
+            for await (const line of rl) {
+                const trimmed = line.trim();
+                // ── Multiline collecting mode (/paste) ──
+                if (this.state === 'MULTILINE_COLLECTING') {
+                    const res = this.multilineCollector.feed(line);
+                    if (res.status === 'collecting') {
+                        rl.setPrompt(DIM('... '));
+                        rl.prompt();
+                        continue;
+                    }
+                    this.multilineCollector.reset();
+                    this.transition('READING_INPUT');
+                    if (res.status === 'aborted') {
+                        console.log(DIM('  Multiline input aborted.'));
+                        rl.setPrompt(buildPrompt(this.sessionState));
+                        rl.prompt();
+                        continue;
+                    }
+                    // res.status === 'complete'
+                    if (!res.text.trim()) {
+                        rl.setPrompt(buildPrompt(this.sessionState));
+                        rl.prompt();
+                        continue;
+                    }
+                    // Treat collected text as deliberation input
+                    const result = await this.handleInput(res.text.trim());
+                    if (!result || result === 'paste') {
+                        this.transition('READING_INPUT');
+                        rl.setPrompt(buildPrompt(this.sessionState));
+                        rl.prompt();
+                        continue;
+                    }
+                    if (result === 'quit') {
+                        rl.close();
+                        return undefined;
+                    }
+                    if (isConfirmationDispatch(result)) {
+                        rl.close();
+                        await this.handleConfirmation(result.confirm);
+                        return 'continue';
+                    }
+                    if (isInteractiveDispatch(result)) {
+                        rl.close();
+                        try {
+                            await result.interactive();
+                        }
+                        catch { /* handled inline */ }
+                        return 'continue';
+                    }
+                    rl.close();
+                    this.transition('READY');
+                    return result;
+                }
+                // ── Continuation line mode (trailing backslash) ──
+                if (continuationBuffer.length > 0) {
+                    continuationBuffer.push(line);
+                    if (continuationBuffer.length > MAX_CONTINUATION_LINES) {
+                        console.log(chalk.yellow(`\n  Continuation too long (max ${MAX_CONTINUATION_LINES} lines). Input discarded.\n`));
+                        continuationBuffer = [];
+                        rl.setPrompt(buildPrompt(this.sessionState));
+                        rl.prompt();
+                        continue;
+                    }
+                    if (!isContinuationLine(trimmed)) {
+                        // Last line — join and process
+                        const joined = joinContinuationLines(continuationBuffer);
+                        continuationBuffer = [];
+                        this.transition('READING_INPUT');
+                        const result = await this.handleInput(joined.trim());
+                        if (!result || result === 'paste') {
+                            this.transition('READING_INPUT');
+                            rl.setPrompt(buildPrompt(this.sessionState));
+                            rl.prompt();
+                            continue;
+                        }
+                        if (result === 'quit') {
+                            rl.close();
+                            return undefined;
+                        }
+                        if (isConfirmationDispatch(result)) {
+                            rl.close();
+                            await this.handleConfirmation(result.confirm);
+                            return 'continue';
+                        }
+                        if (isInteractiveDispatch(result)) {
+                            rl.close();
+                            try {
+                                await result.interactive();
+                            }
+                            catch { /* handled inline */ }
+                            return 'continue';
+                        }
+                        rl.close();
+                        this.transition('READY');
+                        return result;
+                    }
+                    // Still continuing
+                    rl.setPrompt(DIM('... '));
+                    rl.prompt();
+                    continue;
+                }
+                if (!trimmed)
+                    continue;
+                if (trimmed.length > MAX_INPUT_LENGTH) {
+                    console.log(chalk.yellow(`\n  Input too long (${trimmed.length.toLocaleString()} chars, max ${MAX_INPUT_LENGTH.toLocaleString()}). Please shorten.\n`));
+                    continue;
+                }
+                // Check for continuation line
+                if (isContinuationLine(trimmed)) {
+                    continuationBuffer = [line];
+                    rl.setPrompt(DIM('... '));
+                    rl.prompt();
+                    continue;
+                }
+                // Record to persistent history
+                this.history.addEntry(trimmed);
+                // Reset error state on valid input
+                this.sessionState.hasError = false;
+                const result = await this.handleInput(trimmed);
+                if (!result) {
+                    // Handled inline, keep reading
+                    this.transition('READING_INPUT');
+                    rl.setPrompt(buildPrompt(this.sessionState));
+                    rl.prompt();
+                    continue;
+                }
+                if (result === 'quit') {
+                    rl.close();
+                    return undefined;
+                }
+                if (result === 'paste') {
+                    // Enter multiline collecting mode
+                    this.multilineCollector.reset();
+                    this.transition('MULTILINE_COLLECTING');
+                    console.log(DIM('  Paste your text. End with "." on its own line. /abort to cancel.'));
+                    rl.setPrompt(DIM('... '));
+                    rl.prompt();
+                    continue;
+                }
+                if (isConfirmationDispatch(result)) {
+                    rl.close();
+                    await this.handleConfirmation(result.confirm);
+                    return 'continue';
+                }
+                if (isInteractiveDispatch(result)) {
+                    // Close readline to release stdin for the interactive UI
+                    rl.close();
+                    try {
+                        await result.interactive();
+                    }
+                    catch (error) {
+                        console.error(WARN_C(`  コマンド実行異常: ${String(error)}`));
+                        this.sessionState.hasError = true;
+                    }
+                    return 'continue'; // readInputLoop will be re-entered with fresh readline
+                }
+                // Deliberation requested — close readline and return task
+                rl.close();
+                this.transition('READY');
+                return result;
+            }
+        }
+        catch (error) {
+            const isNormalClose = error instanceof Error &&
+                'code' in error && error.code === 'ERR_USE_AFTER_CLOSE';
+            if (!isNormalClose) {
+                logger.debug('readInputLoop: readline error', { error: String(error) });
+                console.error(chalk.red(`\n  Readline error: ${String(error)}\n`));
+                this.sessionState.hasError = true;
+                // Recover: recreate readline with retry limit
+                if (this.running && retryCount < MAX_READLINE_RETRIES) {
+                    try {
+                        rl.close();
+                    }
+                    catch { /* best-effort */ }
+                    return this.readInputLoop(historyEntries, retryCount + 1);
+                }
+            }
+        }
+        // EOF (Ctrl+D)
+        return undefined;
+    }
+    createReadline(historyEntries) {
+        const prompt = buildPrompt(this.sessionState);
+        // P0-3: autoClose: false prevents stdin from being destroyed on rl.close(),
+        // allowing readline to be recreated per deliberation cycle.
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: process.stdin.isTTY ?? false,
+            prompt,
+            completer: this.completerFn,
+            history: historyEntries,
+            historySize: 1000,
+            removeHistoryDuplicates: true,
+            autoClose: false,
+        });
+        rl.on('SIGINT', () => {
+            const now = Date.now();
+            if (now - this.lastSigintTime < 1500) {
+                // Double-tap → graceful exit
+                console.log('');
+                rl.close();
+                return;
+            }
+            this.lastSigintTime = now;
+            rl.write('', { ctrl: true, name: 'u' });
+            console.log('');
+            console.log(DIM('  (Press Ctrl+C again to exit)'));
+            rl.setPrompt(buildPrompt(this.sessionState));
+            rl.prompt();
+        });
+        // Ghost text: keypress-driven inline suggestions (TTY only)
+        if (process.stdin.isTTY && !isGhostTextDisabled()) {
+            if (!keypressInitialized) {
+                emitKeypressEvents(process.stdin);
+                keypressInitialized = true;
+            }
+            let rlClosed = false;
+            const ghostHandler = (_str, key) => {
+                if (!key || rlClosed)
+                    return;
+                // Tab → accept ghost suggestion
+                if (key.name === 'tab' && !key.shift) {
+                    const accepted = this.ghostEngine.accept();
+                    if (accepted) {
+                        rl.write(accepted);
+                        return;
+                    }
+                }
+                // After any other key, update ghost text on next tick
+                // Uses Node.js internal `rl.line` (stable since v0.x, not in public API)
+                setImmediate(() => {
+                    if (rlClosed)
+                        return;
+                    const line = rl.line ?? '';
+                    const cursor = rl.cursor ?? line.length;
+                    const promptText = buildPrompt(this.sessionState);
+                    this.ghostEngine.clear(s => process.stdout.write(s));
+                    if (cursor !== line.length) {
+                        return;
+                    }
+                    const suggestion = this.ghostEngine.suggest(line);
+                    this.ghostEngine.render(line, promptText, suggestion, s => process.stdout.write(s));
+                });
+            };
+            process.stdin.on('keypress', ghostHandler);
+            // Cleanup on readline close — prevents post-close ghost writes
+            rl.once('close', () => {
+                rlClosed = true;
+                process.stdin.removeListener('keypress', ghostHandler);
+                this.ghostEngine.clear(s => process.stdout.write(s));
+            });
+        }
+        this.currentRl = rl;
+        rl.once('close', () => { this.currentRl = undefined; });
+        rl.prompt();
+        return rl;
+    }
+    // ── Input dispatch ────────────────────────────────────────
+    async handleInput(input) {
+        this.transition('DISPATCHING');
+        recordInput(this.stats);
+        const parsed = parseInput(input);
+        if (parsed.isSlash) {
+            return this.handleSlashCommand(parsed.command, parsed.args);
+        }
+        // Natural language → deliberation
+        const task = {
+            type: 'custom',
+            title: input.slice(0, 80),
+            description: input,
+            context: this.context.buildContextString(),
+        };
+        // EngRam: inject related past deliberations
+        this.injectEngramContext(task);
+        return { task, berserk: false };
+    }
+    async handleSlashCommand(command, args) {
+        const cmd = this.slashCommands.get(command);
+        if (!cmd) {
+            const suggestion = suggestCommand(command, this.slashCommands.keys());
+            const hint = suggestion ? ` Did you mean /${suggestion}?` : '';
+            console.log(WARN_C(`  未定義のコマンドパターン: /${command}.${hint} Type /help for available commands.`));
+            this.sessionState.hasError = true;
+            return undefined;
+        }
+        recordSlashCommand(this.stats);
+        let result;
+        try {
+            result = await cmd.execute(args, this.magi, this.context);
+        }
+        catch (error) {
+            console.error(WARN_C(`  コマンド実行異常: ${String(error)}`));
+            this.sessionState.hasError = true;
+            return undefined;
+        }
+        if (result.output) {
+            console.log(result.output);
+        }
+        if (result.action === 'quit') {
+            return 'quit';
+        }
+        if (result.action === 'paste') {
+            return 'paste';
+        }
+        if (result.action === 'clear') {
+            console.clear();
+            printBanner();
+            return undefined;
+        }
+        if (result.action === 'reset') {
+            this.context.clear();
+            this.sessionState.contextEntryCount = 0;
+            console.log(DIM('  Context reset. Deliberation history cleared.'));
+            return undefined;
+        }
+        if (result.action === 'toggle-sound') {
+            this.soundEnabled = !this.soundEnabled;
+            const status = this.soundEnabled ? OK_C('ON ♪') : DIM('OFF');
+            console.log(`  ${FRAME_CHALK('SOUND:')} ${status}`);
+            return undefined;
+        }
+        if (result.action === 'export') {
+            await this.exportDeliberation(result.output || '');
+            return undefined;
+        }
+        if (result.action === 'jobs') {
+            this.handleJobsCommand(result.output || '');
+            return undefined;
+        }
+        if (result.watch) {
+            this.handleWatchCommand(result.watch);
+            return undefined;
+        }
+        // Handle interactive commands (need exclusive stdin access)
+        // Return to readInputLoop which will close readline before executing.
+        if (result.interactive) {
+            return { interactive: result.interactive };
+        }
+        // Handle background job request
+        if (result.background) {
+            const bg = result.background;
+            try {
+                this.jobRegistry.add(bg.name, async (signal) => {
+                    await bg.run(signal);
+                }, {
+                    onSettled: (job) => {
+                        this.sessionState.backgroundJobCount = this.jobRegistry.getRunningCount();
+                        if (job.status === 'failed' && job.error) {
+                            this.writeAbovePrompt(WARN_C(`  Job "${bg.name}" failed: ${job.error}`));
+                        }
+                        else if (!job.abort.signal.aborted) {
+                            this.writeAbovePrompt(DIM(`  Job "${bg.name}" completed.`));
+                        }
+                    },
+                });
+                this.sessionState.backgroundJobCount = this.jobRegistry.getRunningCount();
+            }
+            catch (error) {
+                this.sessionState.hasError = true;
+                console.error(WARN_C(`  コマンド実行異常: ${String(error)}`));
+            }
+            return undefined;
+        }
+        // Handle confirmation request (dangerous operations)
+        if (result.confirm) {
+            return { confirm: result.confirm };
+        }
+        if (result.deliberation) {
+            // Merge auto-collected context with REPL session context
+            const sessionContext = this.context.buildContextString();
+            const autoContext = result.deliberation.task.context;
+            let mergedContext;
+            if (sessionContext && autoContext) {
+                mergedContext = `${autoContext}\n\n${sessionContext}`;
+            }
+            else {
+                mergedContext = autoContext ?? sessionContext;
+            }
+            const task = {
+                ...result.deliberation.task,
+                context: mergedContext,
+            };
+            // EngRam: inject related past deliberations
+            this.injectEngramContext(task);
+            return {
+                task,
+                berserk: result.deliberation.berserk ?? false,
+            };
+        }
+        return undefined;
+    }
+    // ── Confirmation flow (dangerous operations) ────────────────
+    async handleConfirmation(confirm) {
+        this.transition('CONFIRMING');
+        console.log(confirm.description);
+        const required = confirm.requiredInput ?? this.createConfirmationToken();
+        const timeoutMs = confirm.timeoutMs ?? 30_000;
+        try {
+            await this.drainPendingInput();
+            const rl = createInterface({
+                input: process.stdin,
+                output: process.stdout,
+                terminal: process.stdin.isTTY ?? false,
+                autoClose: false,
+            });
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), timeoutMs);
+            let answer;
+            try {
+                answer = await rl.question(DIM(`  続行するには "${required}" と入力してください (${Math.round(timeoutMs / 1000)}秒でタイムアウト): `), { signal: ac.signal });
+            }
+            catch (error) {
+                if (ac.signal.aborted || (error instanceof Error && error.name === 'AbortError')) {
+                    console.log(WARN_C('\n  タイムアウト — 操作を中止しました。'));
+                }
+                else if (error instanceof Error && (error.message.includes('readline was closed') || error.code === 'ERR_USE_AFTER_CLOSE')) {
+                    console.log(WARN_C('\n  操作を中止しました。'));
+                }
+                else {
+                    this.sessionState.hasError = true;
+                    console.error(WARN_C(`  確認入力異常: ${String(error)}`));
+                }
+                return;
+            }
+            finally {
+                clearTimeout(timer);
+                rl.close();
+            }
+            if (answer.trim() !== required) {
+                console.log(DIM('  操作を中止しました。'));
+                return;
+            }
+            this.transition('DISPATCHING');
+            try {
+                const result = await confirm.execute();
+                if (result.output) {
+                    console.log(result.output);
+                }
+            }
+            catch (error) {
+                this.sessionState.hasError = true;
+                console.error(WARN_C(`  操作実行異常: ${String(error)}`));
+            }
+        }
+        catch (error) {
+            this.sessionState.hasError = true;
+            logger.debug('Confirmation flow error', { error: String(error) });
+            console.error(WARN_C(`  確認フロー異常: ${String(error)}`));
+        }
+        finally {
+            // Return to READY so the next loop can recreate readline cleanly.
+            if (this.state === 'CONFIRMING' || this.state === 'DISPATCHING') {
+                this.transition('READY');
+            }
+        }
+    }
+    // ── Background job management ──────────────────────────────
+    async drainPendingInput() {
+        await new Promise(resolve => setImmediate(resolve));
+        if (!process.stdin.readable)
+            return;
+        while (process.stdin.read() !== null) {
+            // Discard buffered input so confirmation requires a new explicit entry.
+        }
+    }
+    createConfirmationToken() {
+        return `yes-${randomBytes(2).toString('hex')}`;
+    }
+    handleWatchCommand(command) {
+        if (command.command === 'status') {
+            const activeJob = this.watchJobId === undefined ? undefined : this.jobRegistry.get(this.watchJobId);
+            if (!activeJob || activeJob.status !== 'running') {
+                console.log(DIM('  Angel watch is stopped.'));
+                return;
+            }
+            const intervalLabel = this.watchPollIntervalMs ? ` (${this.watchPollIntervalMs}ms)` : '';
+            console.log(OK_C(`  Angel watch is running as job #${activeJob.id}${intervalLabel}.`));
+            return;
+        }
+        if (command.command === 'stop') {
+            const activeJob = this.watchJobId === undefined ? undefined : this.jobRegistry.get(this.watchJobId);
+            if (!activeJob || activeJob.status !== 'running') {
+                console.log(DIM('  Angel watch is not running.'));
+                return;
+            }
+            this.magi.runtime.stopWatch();
+            this.jobRegistry.cancel(activeJob.id);
+            this.watchJobId = undefined;
+            this.watchPollIntervalMs = undefined;
+            this.sessionState.backgroundJobCount = this.jobRegistry.getRunningCount();
+            console.log(DIM('  Angel watch stopped.'));
+            return;
+        }
+        const activeJob = this.watchJobId === undefined ? undefined : this.jobRegistry.get(this.watchJobId);
+        if (activeJob && activeJob.status === 'running') {
+            console.log(WARN_C(`  Angel watch is already running as job #${activeJob.id}.`));
+            return;
+        }
+        try {
+            const job = this.jobRegistry.add('Angel Watch', async (signal) => {
+                this.magi.runtime.startWatch({ pollIntervalMs: command.pollIntervalMs, signal });
+                await new Promise((resolve) => {
+                    signal.addEventListener('abort', () => resolve(), { once: true });
+                });
+            }, {
+                onSettled: (settledJob) => {
+                    if (this.watchJobId === settledJob.id) {
+                        this.watchJobId = undefined;
+                        this.watchPollIntervalMs = undefined;
+                    }
+                    this.sessionState.backgroundJobCount = this.jobRegistry.getRunningCount();
+                    if (settledJob.status === 'failed' && settledJob.error) {
+                        this.writeAbovePrompt(WARN_C(`  Job "${settledJob.name}" failed: ${settledJob.error}`));
+                        return;
+                    }
+                    if (!settledJob.abort.signal.aborted) {
+                        this.writeAbovePrompt(DIM(`  Job "${settledJob.name}" completed.`));
+                    }
+                },
+            });
+            this.watchJobId = job.id;
+            this.watchPollIntervalMs = command.pollIntervalMs;
+            this.sessionState.backgroundJobCount = this.jobRegistry.getRunningCount();
+            console.log(OK_C(`  Angel watch started as job #${job.id}${command.pollIntervalMs ? ` (${command.pollIntervalMs}ms)` : ''}.`));
+        }
+        catch (error) {
+            this.sessionState.hasError = true;
+            console.error(WARN_C(`  Angel watch failed: ${String(error)}`));
+        }
+    }
+    handleJobsCommand(args) {
+        const parts = args.trim().split(/\s+/);
+        if (parts[0] === 'cancel' && parts[1]) {
+            const id = parseInt(parts[1], 10);
+            if (Number.isNaN(id)) {
+                console.log(WARN_C('  Usage: /jobs cancel <id>'));
+                return;
+            }
+            const ok = this.jobRegistry.cancel(id);
+            if (ok) {
+                if (this.watchJobId === id) {
+                    this.magi.runtime.stopWatch();
+                    this.watchJobId = undefined;
+                    this.watchPollIntervalMs = undefined;
+                }
+                this.sessionState.backgroundJobCount = this.jobRegistry.getRunningCount();
+                console.log(OK_C(`  Job #${id} cancelled.`));
+            }
+            else {
+                console.log(WARN_C(`  Job #${id} not found or already finished.`));
+            }
+            return;
+        }
+        const jobs = this.jobRegistry.list();
+        if (jobs.length === 0) {
+            console.log(DIM('  No background jobs.'));
+            return;
+        }
+        const lines = ['', FRAME_CHALK.bold('  Background Jobs:'), ''];
+        for (const job of jobs) {
+            const elapsed = Math.round((Date.now() - job.startedAt) / 1000);
+            const statusColor = job.status === 'running' ? OK_C
+                : job.status === 'failed' ? WARN_C : DIM;
+            lines.push(`  #${job.id} ${statusColor(job.status.toUpperCase().padEnd(7))} ${job.name} (${elapsed}s)`);
+            if (job.error)
+                lines.push(`     ${WARN_C(job.error)}`);
+        }
+        lines.push('');
+        console.log(lines.join('\n'));
+    }
+    writeAbovePrompt(message) {
+        if (!this.currentRl)
+            return;
+        const output = process.stdout;
+        readline.clearLine(output, 0);
+        readline.cursorTo(output, 0);
+        output.write(message + '\n');
+        this.currentRl.prompt(true);
+    }
+    // ── EngRam integration ──────────────────────────────────────
+    injectEngramContext(task) {
+        try {
+            const engram = this.magi.getEngramManager();
+            const query = `${task.title} ${task.description}`;
+            const similar = engram.findSimilar(query, 3);
+            // Deduplicate: filter out entries already in ReplContext or shown this session
+            const contextIds = new Set(this.context.getHistory().map(e => e.id));
+            const filtered = similar.filter(m => !contextIds.has(m.deliberationId) && !this.shownEngramIds.has(m.deliberationId));
+            if (filtered.length === 0)
+                return;
+            // Track shown IDs at session level to avoid re-injection
+            for (const m of filtered) {
+                this.shownEngramIds.add(m.deliberationId);
+            }
+            // Show related deliberations (sanitize external data)
+            console.log(DIM('  Related deliberations:'));
+            for (const m of filtered) {
+                console.log(DIM(`    ⬢ ${sanitizeForTerminal(m.taskTitle)} (${m.decision})`));
+            }
+            // Inject into context (capped)
+            const engramContext = filtered
+                .map(m => `[Past] "${m.taskTitle}" → ${m.decision}: ${(m.keyPoints || []).slice(0, 2).join(', ')}`)
+                .join('\n')
+                .slice(0, ENGRAM_CONTEXT_CAP);
+            task.context = [task.context, engramContext].filter(Boolean).join('\n\n');
+        }
+        catch {
+            // EngRam is optional — graceful degradation
+            logger.debug('EngRam context injection failed');
+        }
+    }
+    // ── Deliberation execution ────────────────────────────────
+    async runDeliberation(task, berserk) {
+        this.transition('DELIBERATING');
+        // Update session state
+        this.sessionState.berserkActive = berserk;
+        let handoffLineCount;
+        // Handoff animation before TUI takes over
+        if (shouldSkipAnimation()) {
+            console.log('');
+            console.log(TRANSITION('  DELIBERATION SEQUENCE — 思考回路 展開'));
+            console.log('');
+            handoffLineCount = 3;
+        }
+        else {
+            handoffLineCount = await runHandoffAnimation({
+                write: s => process.stdout.write(s),
+                taskTitle: task.title,
+                berserk,
+                unitCount: this.sessionState.totalUnits,
+            });
+        }
+        this.abortController = new AbortController();
+        const { signal } = this.abortController;
+        // Ctrl+C during deliberation → abort instead of default behavior
+        const cancelHandler = () => { this.abortController?.abort(); };
+        process.once('SIGINT', cancelHandler);
+        let tuiInstance;
+        let eventListener;
+        let disposeStreaming;
+        try {
+            const setup = await initializeTui(this.magi.getEventBus(), this.options.tuiEnabled ?? true, { soundEnabled: this.soundEnabled });
+            tuiInstance = setup.tuiInstance;
+            disposeStreaming = setup.disposeStreaming;
+            // If TUI is not available AND no streaming reporter active, use inline listener
+            if (!tuiInstance && !setup.streamingActive) {
+                eventListener = createReplEventListener({
+                    eventBus: this.magi.getEventBus(),
+                    write: s => process.stdout.write(s),
+                });
+                eventListener.subscribe();
+            }
+            let result;
+            if (berserk) {
+                result = await this.magi.deliberateBerserk(task, { signal });
+            }
+            else {
+                result = await this.magi.deliberate(task, { signal });
+            }
+            if (tuiInstance)
+                await tuiInstance.waitForDismiss();
+            tuiInstance?.dispose();
+            tuiInstance = undefined;
+            this.transition('SHOWING_RESULT');
+            if (handoffLineCount > 0) {
+                process.stdout.write(this.clearRecentLines(handoffLineCount));
+            }
+            process.stdout.write(ERASE_TO_END);
+            // Rich result display (replaces old printResultSummary)
+            console.log(formatResultDisplay(result));
+            this.lastDeliberation = result;
+            this.context.add(result);
+            this.sessionState.deliberationCount++;
+            this.sessionState.contextEntryCount = this.context.getHistory().length;
+            this.sessionState.berserkActive = false;
+            // Record session statistics — estimate tokens using CJK-aware heuristic
+            const tokens = result.rounds.reduce((sum, r) => sum + (r.opinions?.reduce((s, o) => s + estimateTokens(o.rawOutput ?? ''), 0) ?? 0), 0);
+            recordDeliberation(this.stats, result.consensus.decision, result.totalDurationMs, tokens, berserk);
+            this.stats.contextEntriesUsed = this.context.getHistory().length;
+            this.transition('READY');
+        }
+        catch (error) {
+            // Safety net: ensure terminal is restored
+            if (tuiInstance) {
+                try {
+                    tuiInstance.dispose();
+                }
+                catch { /* intentional: cleanup must not throw */ }
+            }
+            // P0-4: Force-restore raw mode in case TUI dispose() failed
+            if (process.stdin.isTTY && process.stdin.isRaw) {
+                try {
+                    process.stdin.setRawMode(false);
+                }
+                catch { /* best-effort */ }
+            }
+            process.stdout.write(CURSOR_SHOW + ALT_SCREEN_LEAVE);
+            const msg = signal.aborted ? '思考ルーチン中断' : `思考ルーチンに異常発生: ${String(error)}`;
+            console.error(WARN_C(`\n  ${msg}\n`));
+            this.sessionState.hasError = true;
+            this.sessionState.berserkActive = false;
+            // Recover to READY if not already disposing
+            if (this.state !== 'DISPOSING') {
+                const from = this.state;
+                this.state = 'READY'; // Direct assignment: error recovery from DELIBERATING or SHOWING_RESULT
+                logger.debug('REPL state transition (recovery)', { from, to: 'READY' });
+            }
+        }
+        finally {
+            eventListener?.unsubscribe();
+            disposeStreaming?.();
+            process.removeListener('SIGINT', cancelHandler);
+            this.abortController = undefined;
+        }
+    }
+    // ── Lifecycle ─────────────────────────────────────────────
+    checkUnitsOnStartup() {
+        // Fire-and-forget: update prompt with actual unit status
+        this.magi.healthCheck().then(results => {
+            let online = 0;
+            let total = 0;
+            for (const [, result] of results) {
+                total++;
+                if (!(result instanceof Error))
+                    online++;
+            }
+            this.sessionState.onlineUnits = online;
+            this.sessionState.totalUnits = total;
+        }).catch(() => {
+            // Keep default 3/3 on failure
+        });
+    }
+    /**
+     * Graceful resource cleanup — idempotent, callable from any state.
+     * Use for programmatic shutdown without process.exit().
+     */
+    async dispose() {
+        if (this.state === 'DISPOSING')
+            return;
+        // Abort in-flight deliberation
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = undefined;
+        }
+        // Direct state assignment: dispose must succeed from ANY state
+        const from = this.state;
+        this.state = 'DISPOSING';
+        logger.debug('REPL state transition (dispose)', { from, to: 'DISPOSING' });
+        // Abort background jobs and flush history
+        this.jobRegistry.dispose();
+        await this.history.flush();
+        this.history.dispose();
+        this.ghostEngine.dispose();
+        // Session summary (only if deliberations were run)
+        const summary = formatSessionSummary(this.stats);
+        if (summary) {
+            console.log('');
+            console.log(summary);
+        }
+        // Terminal state restoration
+        if (process.stdin.isTTY && process.stdin.isRaw) {
+            try {
+                process.stdin.setRawMode(false);
+            }
+            catch { /* best-effort */ }
+        }
+        process.stdout.write(CURSOR_SHOW + ALT_SCREEN_LEAVE);
+        console.log('');
+        console.log(DIM('  MAGI SYSTEM — session terminated — 全回路 正常切断'));
+        console.log('');
+    }
+    // ── Export ────────────────────────────────────────────────
+    async exportDeliberation(args) {
+        const flagJson = args.includes('--json');
+        const cleanArgs = args.replace('--json', '').trim();
+        // Generate filename — infer format from extension if user specified a filename
+        const now = new Date();
+        const ts = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        const isJson = cleanArgs
+            ? flagJson || cleanArgs.endsWith('.json')
+            : flagJson;
+        const ext = isJson ? 'json' : 'md';
+        const filename = cleanArgs || `magi-export-${ts}.${ext}`;
+        // Security: path traversal defense BEFORE deliberation check
+        if (filename.includes('\0')) {
+            console.log(WARN_C('  Error: invalid file path.'));
+            return;
+        }
+        const cwd = process.cwd();
+        const filePath = resolve(cwd, filename);
+        const rel = relative(cwd, filePath);
+        if (rel.startsWith('..') || resolve(rel) === rel) {
+            console.log(WARN_C('  Error: path traversal denied.'));
+            return;
+        }
+        if (!this.lastDeliberation) {
+            console.log(WARN_C('  No deliberation to export.'));
+            return;
+        }
+        const content = isJson
+            ? formatDeliberationAsJson(this.lastDeliberation)
+            : formatDeliberationAsMarkdown(this.lastDeliberation);
+        try {
+            // Security: reject symlinks and warn on existing files
+            try {
+                const stat = await lstat(filePath);
+                if (stat.isSymbolicLink()) {
+                    console.log(WARN_C('  Error: symlink target rejected.'));
+                    return;
+                }
+                // File exists — overwrite with warning
+                console.log(DIM(`  (overwriting existing ${rel})`));
+            }
+            catch {
+                // File does not exist — OK to create
+            }
+            await safeWriteFile(filePath, content);
+            console.log(OK_C(`  Exported to ${rel}`));
+        }
+        catch (error) {
+            console.error(WARN_C(`  Export failed: ${String(error)}`));
+        }
+    }
+    clearRecentLines(lineCount) {
+        let sequence = '';
+        for (let i = 0; i < lineCount; i++) {
+            sequence += `\r${ERASE_LINE}`;
+            if (i < lineCount - 1) {
+                sequence += moveUp(1);
+            }
+        }
+        return sequence;
+    }
+}