rl-rockcli 0.0.9 → 0.0.11

package/commands/attach/repl.js

@@ -0,0 +1,791 @@
+'use strict';
+
+const logger = require('../../utils/logger');
+const i18n = require('../../utils/i18n');
+const { t } = i18n;
+const { CLI_NAME } = require('../../utils/cli');
+const SessionManager = require('./session-manager');
+const HistoryManager = require('./history-manager');
+// ink-repl is ESM, use dynamic import
+const configManager = require('../../utils/configManager');
+const { SandboxClient, SandboxConfig } = require('../../utils/sandbox-client');
+const { selectAttachUiMode, INK_MIN_NODE_MAJOR, isBunRuntime, findBunBinary, getBunVersion } = require('./ui-mode');
+const { startBasicREPL } = require('./basic-repl');
+const { ensureHistorySession } = require('./history-session');
+const cleanupManager = require('./cleanup-manager');
+const { getLogoLines } = require('../../utils/asciiArt');
+
+const isOpenSource = process.env.ROCKCLI_MODE === 'opensource';
+const DEFAULT_OPEN_SOURCE_BASE_URL = 'http://127.0.0.1:8080';
+
+/**
+ * List of all builtin commands available in the REPL
+ */
+const BUILTIN_COMMANDS = [
+  { name: 'log', description: 'View sandbox logs' },
+  { name: 'upload', description: 'Upload file to sandbox' },
+  { name: 'download', description: 'Download file from sandbox' },
+  { name: 'status', description: 'Show sandbox status' },
+  { name: 'stop', description: 'Stop the sandbox' },
+  { name: 'sessions', description: 'List attach sessions' },
+  // { name: 'resume', description: 'Restore previous session' },  // Disabled
+  { name: 'clear', description: 'Clear terminal screen' },
+  { name: 'stats', description: 'Show session statistics' },
+  { name: 'copy', description: 'Copy output of last command to clipboard' },
+  { name: 'about', description: 'Show about information' },
+  { name: 'docs', description: 'Open documentation' },
+  { name: 'bug', description: 'Report a bug' },
+  { name: 'help', description: 'Show help message' },
+  { name: 'exit', description: 'Exit the REPL (session kept alive)' },
+  { name: 'close', description: 'Close session permanently and exit' },
+  { name: 'retry', description: 'Retry last failed command' },
+  { name: 'cleanup-history', description: 'Clean up history sessions. Usage: /cleanup-history [--sandbox <id>] [--all]' },
+];
+
+/**
+ * Get ASCII art logo from unified source
+ */
+function getAsciiLogo() {
+  return getLogoLines();
+}
+
+/**
+ * SandboxREPL - Interactive REPL for sandbox interaction
+ */
+class SandboxREPL {
+  /**
+   * Create a new SandboxREPL instance
+   * @param {string} sandboxId - The sandbox ID to connect to
+   * @param {Object} argv - Command line arguments
+   */
+  constructor(sandboxId, argv = {}) {
+    this.sandboxId = sandboxId;
+    this.argv = argv;
+    this.sessionManager = null;
+    this.historyManager = null;
+    this.client = null;
+    this.startTime = null;
+  }
+
+  /**
+   * Start the REPL
+   */
+  async start() {
+    // Validate auth BEFORE any UI initialization
+    const apiKey = configManager.getApiKeyWithPriority(this.argv);
+    if (!apiKey) {
+      const err = new Error('API key required. Set ROCK_API_KEY env var or use --api-key.');
+      err.exitCode = 1;
+      throw err;
+    }
+
+    // Initialize client
+    const config = configManager.readConfig();
+    const sandboxConfig = config?.sandbox || {};
+    const envBaseUrl = process.env.ROCKCLI_BASE_URL || process.env.ROCK_BASE_URL;
+
+    const baseUrl =
+      this.argv.baseUrl ||
+      envBaseUrl ||
+      sandboxConfig.base_url ||
+      (isOpenSource ? DEFAULT_OPEN_SOURCE_BASE_URL : undefined);
+
+    const sdkConfig = new SandboxConfig({
+      xrlAuthorization: apiKey,
+      baseUrl,
+      cluster: configManager.getClusterWithPriority(this.argv),
+      userId: configManager.getUserIdWithPriority(this.argv),
+      experimentId: configManager.getExperimentIdWithPriority(this.argv),
+    });
+
+    this.client = new SandboxClient(sdkConfig, { requireImage: false });
+    this.client._sandboxId = this.sandboxId;
+
+    // Initialize managers
+    this.sessionManager = new SessionManager(this.client, this.sandboxId);
+    this.historyManager = new HistoryManager(this.sandboxId);
+
+    // Unified exit & signal handling (best-effort)
+    cleanupManager.installSignalHandlers();
+    cleanupManager.registerSyncCleanup(() => {
+      try {
+        if (process.stdin && process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') {
+          process.stdin.setRawMode(false);
+        }
+      } catch {
+        // ignore
+      }
+    });
+    cleanupManager.registerCleanup(async () => {
+      await this._cleanup();
+    });
+
+    // Determine UI mode early to decide how to show connecting screen
+    const uiModeCheck = selectAttachUiMode({ argv: this.argv, env: process.env, nodeVersion: process.versions.node });
+    const useOpenTuiUI = uiModeCheck.mode === 'opentui';
+    const useInkUI = uiModeCheck.mode === 'ink';
+
+    // Spinner frames for animation (ASCII based for better compatibility)
+    const SPINNER_FRAMES = ['|', '/', '-', '\\'];
+    let spinnerIndex = 0;
+    let spinnerTimer = null;
+
+    // Connecting animation state
+    let currentAttempt = 0;
+    let connectingScreen = null;
+
+    // ASCII banner for opentui/ink connecting screen
+    const ASCII_LINES = getAsciiLogo();
+
+    const centerText = (text, width) => {
+      const textWidth = this._getDisplayWidth ? this._getDisplayWidth(text) : text.length;
+      const padding = Math.max(0, Math.floor((width - textWidth) / 2));
+      return ' '.repeat(padding) + text;
+    };
+
+    let lastAttempt = 0;
+
+    // Function to render opentui connecting screen with ANSI codes
+    // Logo 全局居中，Logo 正下方显示连接状态
+    const renderOpenTuiConnecting = (attempt, maxAttempts, isInitial = false) => {
+      const spinner = SPINNER_FRAMES[spinnerIndex];
+      const shortId = this.sandboxId.slice(0, 8);
+      const terminalWidth = process.stdout.columns || 80;
+
+      // Calculate vertical center for logo
+      const logoHeight = ASCII_LINES.length;
+      const terminalHeight = process.stdout.rows || 24;
+      const topPadding = Math.max(2, Math.floor((terminalHeight - logoHeight - 3) / 2)); // -3 for status line and padding
+
+      // Status line position (right after logo)
+      const statusLine = topPadding + logoHeight + 2;
+
+      if (isInitial) {
+        // Clear screen and render everything once
+        let output = '\x1b[H\x1b[2J'; // Clear screen
+
+        // Top padding
+        output += '\n'.repeat(topPadding);
+
+        // Render ASCII banner with gradient
+        const colors = ['38;2;37;99;235', '38;2;59;130;246', '38;2;79;70;229', '38;2;99;102;241', '38;2;124;58;237', '38;2;139;92;246'];
+        ASCII_LINES.forEach((line, i) => {
+          const centeredLine = centerText(line, terminalWidth);
+          output += `\x1b[${colors[i % colors.length]}m\x1b[1m${centeredLine}\x1b[0m\n`;
+        });
+
+        // Empty line before status
+        output += '\n';
+
+        process.stdout.write(output);
+      }
+
+      // Build status text
+      const statusText = attempt > 1 ? `(${attempt}/${maxAttempts})` : '';
+      const line = `${spinner} 正在连接：${this.sandboxId} ${statusText}`;
+      const centeredLine = centerText(line, terminalWidth);
+
+      // Move to status line and write
+      process.stdout.write(`\x1b[${statusLine};1H\x1b[K\x1b[36m${centeredLine}\x1b[0m`);
+    };
+
+    if (useOpenTuiUI) {
+      // For OpenTUI, use ANSI-based connecting animation (not TUI) to avoid entering alternate screen early
+      // This prevents getting stuck in alternate screen if sandbox is not ready
+      process.stdout.write('\x1bc'); // Clear screen
+      renderOpenTuiConnecting(1, 30, true); // Initial render
+      // Start spinner timer for animation (120ms for smooth rotation)
+      spinnerTimer = setInterval(() => {
+        spinnerIndex = (spinnerIndex + 1) % SPINNER_FRAMES.length;
+        renderOpenTuiConnecting(currentAttempt || 1, 30, false);
+      }, 120);
+    } else if (useInkUI) {
+      // Use Ink's ConnectingScreen component
+      try {
+        const React = await import('react');
+        const { render } = await import('ink');
+        const { ThemeProvider } = await import('./ink-repl/contexts/ThemeContext.js');
+        const { ConnectingScreen } = await import('./ink-repl/components/ConnectingScreen.js');
+        const h = React.default.createElement;
+
+        process.stdout.write('\x1bc');
+
+        connectingScreen = render(
+          h(ThemeProvider, { initialTheme: 'catppuccin-mocha' },
+            h(ConnectingScreen, {
+              sandboxId: this.sandboxId,
+              attempt: currentAttempt,
+              maxAttempts: 30,
+            })
+          ),
+          { exitOnCtrlC: false }
+        );
+      } catch (e) {
+        logger.debug('Failed to render Ink connecting screen:', e);
+        process.stdout.write(`Connecting to ${this.sandboxId}...`);
+      }
+    } else {
+      process.stdout.write(`Connecting to ${this.sandboxId}...`);
+    }
+
+    // Wait for sandbox to be ready
+    const readyResult = await this.sessionManager.waitForReady({
+      maxAttempts: 30,
+      intervalMs: 1000,
+      onProgress: (attempt, max) => {
+        currentAttempt = attempt;
+        if (useOpenTuiUI) {
+          // For OpenTUI, update attempt counter (spinner is handled by timer)
+          // No need to manually trigger render, the timer updates spinner
+        } else if (useInkUI && connectingScreen) {
+          try {
+            const React = require('react');
+            const { ThemeProvider } = require('./ink-repl/contexts/ThemeContext.js');
+            const { ConnectingScreen } = require('./ink-repl/components/ConnectingScreen.js');
+            const h = React.createElement;
+
+            connectingScreen.rerender(
+              h(ThemeProvider, { initialTheme: 'catppuccin-mocha' },
+                h(ConnectingScreen, {
+                  sandboxId: this.sandboxId,
+                  attempt: currentAttempt,
+                  maxAttempts: max,
+                })
+              )
+            );
+          } catch (e) {
+            // Ignore rerender errors
+          }
+        } else if (attempt > 1) {
+          process.stdout.write(`\rConnecting to ${this.sandboxId}... (${attempt}/${max})`);
+        }
+      },
+    });
+
+    const isReady = readyResult.ready;
+    const specificError = readyResult.error;
+    const sandboxStatus = readyResult.status;
+
+    // Stop spinner animation (only relevant for Ink mode)
+    if (spinnerTimer) {
+      clearInterval(spinnerTimer);
+      spinnerTimer = null;
+      // Keep the animation on screen for a moment before transitioning (1.5s for better visibility)
+      await new Promise(resolve => setTimeout(resolve, 1500));
+    }
+
+    if (!isReady) {
+      // Check if sandbox is in Failed state (destroyed or not exist) - handle immediately
+      if (sandboxStatus === 'Failed') {
+        const errorMessage = `Sandbox ${this.sandboxId} has been destroyed or does not exist.`;
+
+        // Clear screen and show error
+        process.stdout.write('\x1b[H\x1b[2J');
+        console.log('');
+        console.log(`   ❌ ${errorMessage}`);
+        console.log('');
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        process.exit(1);
+        return;
+      }
+
+      // Unmount/clear connecting screen
+      if (connectingScreen) {
+        connectingScreen.unmount();
+      }
+
+      // Determine the specific error message
+      let errorMessage = 'Sandbox is not ready. It may be starting up or stopped.';
+      let suggestion = `Try: ${CLI_NAME} sandbox ${this.sandboxId} status`;
+
+      // Check if we have a specific error from getStatus that indicates the sandbox doesn't exist
+      if (specificError && specificError.message && specificError.message.includes('not found')) {
+        errorMessage = `Sandbox ${this.sandboxId} does not exist.`;
+        suggestion = `Please verify the sandbox ID is correct. Try: ${CLI_NAME} sandbox list`;
+      }
+
+      if (useOpenTuiUI || useInkUI) {
+        // For TUI modes, show error in the TUI rather than just clearing screen
+        try {
+          if (useOpenTuiUI) {
+            // Clear screen and show error in a clean way
+            process.stdout.write('\x1b[H\x1b[2J'); // Clear screen
+            console.log(''); // Empty line for spacing
+            console.log(`   ❌ ${errorMessage}`);
+            console.log(`   💡 ${suggestion}`);
+            console.log(''); // Empty line for spacing
+            console.log('   Press any key to exit...');
+
+            try {
+              // Ensure stdout is flushed before setting raw mode
+              process.stdout.write('', () => {
+                try {
+                  process.stdin.setRawMode(true);
+                  process.stdin.resume();
+                  process.stdin.once('data', () => {
+                    process.exit(1);
+                  });
+                } catch (err) {
+                  // If raw mode fails, just exit after a short delay
+                  console.log('\nExiting in 3 seconds...');
+                  setTimeout(() => process.exit(1), 3000);
+                }
+              });
+            } catch (err) {
+              // If anything goes wrong, exit after showing the message
+              console.log('\nExiting in 3 seconds...');
+              setTimeout(() => process.exit(1), 3000);
+            }
+            // Don't throw error, let the process exit via keypress
+            return;
+          } else if (useInkUI) {
+            // Clear the connecting screen
+            process.stdout.write('\x1b[H\x1b[2J');
+          }
+        } catch (e) {
+          // If TUI error display fails, fall back to basic error
+          process.stdout.write('\x1b[H\x1b[2J');
+        }
+      }
+      console.log(' failed');
+      logger.error(errorMessage);
+      logger.error(suggestion);
+      const err = new Error(errorMessage);
+      err.exitCode = 1;
+      throw err;
+    }
+
+    // Unmount/clear connecting screen on success
+    if (connectingScreen) {
+      connectingScreen.unmount();
+    }
+    if (!useOpenTuiUI && !useInkUI) {
+      console.log(' done');
+    }
+
+    // Get host IP and hostname from status
+    let hostIp = null;
+    let hostName = null;
+    try {
+      const status = await this.client.getStatus();
+      hostIp = status.hostIp || null;
+      // Extract first part of hostname (e.g., "rock-worker-zb-a-216" from "rock-worker-zb-a-216.xxx.local")
+      if (status.hostName) {
+        hostName = status.hostName.split('.')[0];
+      }
+    } catch (e) {
+      logger.debug('Failed to get host info:', e.message);
+    }
+
+    try {
+      // Record start time for session duration
+      this.startTime = Date.now();
+
+      // Check if --session is specified
+      // Note: When called via 'sandbox <id> attach -s', the value might be in argv.s instead of argv.session
+      let reuseSession = this.argv.session || this.argv.s || null;
+
+      if (reuseSession) {
+        logger.debug(`Attempting to resume session: ${reuseSession}`);
+      }
+
+      // Connect to session
+      const { sessionId, initialPrompt, user, reused } = await this.sessionManager.connect({
+        reuseSession,
+      });
+
+      // Restore or create transcript history for this shell session.
+      // If user specified -s, try to resume history from that session (even if shell session is dead).
+      // Otherwise, if we reused an existing shell session, prefer resuming the matching history session.
+      const historyShellSessionName = reuseSession || sessionId;
+      const shouldPreferResume = !!reuseSession || !!reused;
+      logger.debug(`History lookup: shellSessionName=${historyShellSessionName}, preferResume=${shouldPreferResume}, reuseSession=${reuseSession}, sessionId=${sessionId}, reused=${reused}`);
+      await ensureHistorySession({
+        historyManager: this.historyManager,
+        shellSessionName: historyShellSessionName,
+        preferResume: shouldPreferResume,
+      });
+      this.shellSessionId = sessionId; // Store for exit banner
+
+      if (reused && !(useInkUI || useOpenTuiUI)) {
+        // Only show resume message for basic REPL mode
+        // For TUI modes (Ink/OpenTUI), the session restoration is handled in-app
+        console.log(`  Resumed session: ${sessionId.substring(0, 20)}...`);
+      }
+
+      // Start heartbeat to keep sandbox alive
+      this.sessionManager.startHeartbeat();
+
+      // Determine hostname for prompt: prefer hostName from status, fallback to sandboxId
+      const actualUser = user || 'root';
+      const actualHostname = hostName || this.sandboxId;
+
+      // Parse cwd from initialPrompt if available, otherwise default to /
+      // Format: <user>@<hostname>:<cwd>#
+      const cwdMatch = initialPrompt?.match(/:([^#]+)#/);
+      const initialCwd = cwdMatch ? cwdMatch[1] : '/';
+      const shellPrompt = `${actualUser}@${actualHostname}:${initialCwd}# `;
+
+      logger.debug(`Host info: hostName=${hostName}, hostIp=${hostIp}, actualHostname=${actualHostname}`);
+      logger.debug(`Prompt: user=${actualUser}, cwd=${initialCwd}, shellPrompt=${shellPrompt}`);
+
+      const ui = selectAttachUiMode({ argv: this.argv, env: process.env, nodeVersion: process.versions.node });
+
+      // Get version from package.json (read once at startup)
+      const { version: cliVersion } = require('../../package.json');
+
+      if (ui.mode === 'basic') {
+        console.log(`  Using basic attach UI (${ui.reason}).`);
+        console.log(`  Tip: upgrade Node to >= ${INK_MIN_NODE_MAJOR} or use ROCK_ATTACH_UI=ink to force Ink UI.`);
+        await startBasicREPL({
+          sandboxId: this.sandboxId,
+          hostname: actualHostname,
+          hostIp,
+          user: user || 'root',
+          client: this.client,
+          sessionManager: this.sessionManager,
+          historyManager: this.historyManager,
+          initialPrompt: shellPrompt,
+          version: cliVersion,
+          onExit: async () => {
+            await cleanupManager.runExitCleanup({ reason: 'basic-ui-exit' });
+            this._showExitBanner();
+          },
+        });
+        return;
+      }
+
+      // If opentui mode is selected but we're not running under Bun,
+      // re-exec the entire command under Bun runtime.
+      if (ui.mode === 'opentui' && !isBunRuntime()) {
+        const bunPath = findBunBinary();
+        if (bunPath) {
+          // Check Bun version before re-exec (Bun 1.0+ required for --preload)
+          const bunVersionInfo = getBunVersion(bunPath);
+          if (bunVersionInfo && bunVersionInfo.major < 1) {
+            logger.warn(`Bun ${bunVersionInfo.version} found, but OpenTUI requires Bun >= 1.0`);
+            logger.warn('Falling back to Ink UI mode...');
+            ui.mode = 'ink';
+            ui.reason = `bun ${bunVersionInfo.version} < 1.0, fallback to ink`;
+          } else {
+            try {
+              logger.debug(`Re-executing under Bun: ${bunPath}`);
+              const { spawnSync } = require('child_process');
+              const path = require('path');
+              const fs = require('fs');
+
+              // Find the entry script (all.js in dev, index.js in npm package)
+              let entryScript = path.resolve(__dirname, '..', '..', 'all.js');
+              if (!fs.existsSync(entryScript)) {
+                // Fallback to index.js (npm package)
+                entryScript = path.resolve(__dirname, '..', '..', 'index.js');
+                if (!fs.existsSync(entryScript)) {
+                  throw new Error('Cannot find entry script (all.js or index.js)');
+                }
+              }
+
+              logger.debug(`Entry script: ${entryScript}`);
+              const args = process.argv.slice(2);
+              // --preload is required for @opentui/solid JSX transform
+              // Remove BUN_CONFIG_FILE override so preload works correctly
+              const bunEnv = { ...process.env };
+              delete bunEnv.BUN_CONFIG_FILE;
+              const result = spawnSync(bunPath, ['--preload', '@opentui/solid/preload', entryScript, ...args], {
+                stdio: 'inherit',
+                env: bunEnv,
+              });
+
+              // Check if bun execution failed
+              if (result.error) {
+                throw result.error;
+              }
+
+              process.exit(result.status || 0);
+              return;
+            } catch (bunError) {
+              logger.warn('Failed to re-execute with Bun:', bunError.message);
+              logger.debug('Bun error:', bunError);
+              logger.warn('Falling back to Ink UI mode...');
+              ui.mode = 'ink';
+              ui.reason = 'bun re-execution failed, fallback to ink';
+            }
+          }
+        } else {
+          // No bun binary available, fallback to ink mode
+          logger.debug('Bun binary not found, falling back to ink mode');
+          ui.mode = 'ink';
+          ui.reason = 'opentui requires Bun runtime, bun not found, fallback to ink';
+        }
+      }
+
+      if (ui.mode === 'opentui') {
+        try {
+          // Register @opentui/solid JSX transform plugin before loading .tsx files
+          // This must happen before any .tsx import so Bun knows how to compile Solid JSX
+          logger.debug('Registering @opentui/solid preload plugin...');
+          // Try to import the preload module - Bun can handle both .ts and .js
+          // First try the package export, fallback to direct path if needed
+          try {
+            await import('@opentui/solid/preload');
+          } catch (preloadErr) {
+            logger.debug('Package export preload failed, trying direct path:', preloadErr.message);
+            const preloadPath = require.resolve('@opentui/solid/scripts/preload.js');
+            await import(preloadPath);
+          }
+
+          logger.debug('Loading opentui-repl module...');
+          const { startOpenTuiREPL, createSlashTrigger } = await import('./opentui-repl/index.js');
+          logger.debug('opentui-repl module loaded successfully');
+
+          const slashTrigger = createSlashTrigger(BUILTIN_COMMANDS);
+          const initialTheme = configManager.getUIConfig('theme');
+
+          logger.debug('Starting OpenTUI REPL...');
+          await startOpenTuiREPL({
+            sandboxId: this.sandboxId,
+            hostname: actualHostname,
+            hostIp,
+            user: user || 'root',
+            client: this.client,
+            sessionManager: this.sessionManager,
+            historyManager: this.historyManager,
+            initialPrompt: shellPrompt,
+            version: cliVersion,
+            triggers: [slashTrigger],
+            theme: initialTheme,
+            onThemeChange: (name) => {
+              configManager.setUIConfig('theme', name);
+            },
+            onExit: async () => {
+              await cleanupManager.runExitCleanup({ reason: 'opentui-ui-exit' });
+              this._showExitBanner();
+            },
+          });
+          // Force exit to ensure program terminates
+          process.exit(0);
+          return;
+        } catch (opentuiError) {
+          // Use console.error for critical errors so user can see them without -v flag
+          console.error('Failed to start OpenTUI REPL:', opentuiError.message);
+          logger.debug('OpenTUI error stack:', opentuiError.stack);
+          logger.warn('Falling back to Ink UI mode...');
+          // Fallback to ink mode
+          ui.mode = 'ink';
+          ui.reason = 'opentui failed, fallback to ink';
+        }
+      }
+
+      try {
+        // Dynamic import for ESM ink-repl module (may fail on older Node)
+        const { startInkREPL, createSlashTrigger } = await import('./ink-repl/index.js');
+
+        // Create slash command trigger
+        const slashTrigger = createSlashTrigger(BUILTIN_COMMANDS);
+
+        // Start Ink REPL
+        const initialTheme = configManager.getUIConfig('theme');
+
+        await startInkREPL({
+          sandboxId: this.sandboxId,
+          hostname: actualHostname,
+          hostIp,
+          user: user || 'root',
+          client: this.client,
+          sessionManager: this.sessionManager,
+          historyManager: this.historyManager,
+          initialPrompt: shellPrompt,
+          version: cliVersion,
+          triggers: [slashTrigger],
+          theme: initialTheme,
+          onThemeChange: (name) => {
+            configManager.setUIConfig('theme', name);
+          },
+          onExit: async () => {
+            await cleanupManager.runExitCleanup({ reason: 'ink-ui-exit' });
+            this._showExitBanner();
+          },
+        });
+      } catch (e) {
+        const msg = e && e.message ? e.message : String(e);
+        const name = e && e.name ? e.name : '';
+
+        // If the user explicitly asked for Ink UI, surface the error.
+        if (this.argv && this.argv.ui === 'ink') {
+          console.error(`Ink UI error: ${msg}`);
+          throw e;
+        }
+
+        const looksLikeSyntax =
+          name === 'SyntaxError' ||
+          /Unexpected token/.test(msg) ||
+          /Cannot use import statement outside a module/.test(msg);
+
+        if (!looksLikeSyntax) {
+          console.error(`Ink UI error: ${msg}`);
+          throw e;
+        }
+
+        console.log(`  Ink UI failed to start (${msg}). Falling back to basic attach UI.`);
+        await startBasicREPL({
+          sandboxId: this.sandboxId,
+          hostname: actualHostname,
+          hostIp,
+          user: user || 'root',
+          client: this.client,
+          sessionManager: this.sessionManager,
+          historyManager: this.historyManager,
+          initialPrompt: shellPrompt,
+          version: cliVersion,
+          onExit: async () => {
+            await cleanupManager.runExitCleanup({ reason: 'basic-ui-exit' });
+            this._showExitBanner();
+          },
+        });
+      }
+
+    } catch (error) {
+      // Use console.error for critical errors so user can see them without -v flag
+      console.error(`Error: ${error.message}`);
+      logger.debug(error.stack);
+      await cleanupManager.runExitCleanup({ reason: 'repl-error', exitCode: error && typeof error.exitCode === 'number' ? error.exitCode : 1 });
+    }
+  }
+
+  /**
+   * Cleanup on exit
+   */
+  async _cleanup() {
+    try {
+      if (this.historyManager) {
+        await this.historyManager.close();
+      }
+      if (this.sessionManager) {
+        await this.sessionManager.disconnect();
+      }
+    } catch (error) {
+      logger.debug('Cleanup error:', error.message);
+    }
+  }
+
+  /**
+   * Format duration in human readable format
+   */
+  _formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+      const m = minutes % 60;
+      return `${hours}h ${m}m`;
+    } else if (minutes > 0) {
+      const s = seconds % 60;
+      return `${minutes}m ${s}s`;
+    } else {
+      return `${seconds}s`;
+    }
+  }
+
+  /**
+   * Calculate display width of a string (CJK characters count as 2)
+   */
+  _getDisplayWidth(str) {
+    let width = 0;
+    for (const char of str) {
+      const code = char.charCodeAt(0);
+      // CJK Unified Ideographs: 0x4E00-0x9FFF
+      // CJK symbols and punctuation: 0x3000-0x303F
+      // Fullwidth ASCII variants: 0xFF00-0xFFEF
+      // Hiragana: 0x3040-0x309F
+      // Katakana: 0x30A0-0x30FF
+      if ((code >= 0x4E00 && code <= 0x9FFF) ||
+        (code >= 0x3000 && code <= 0x303F) ||
+        (code >= 0xFF00 && code <= 0xFFEF) ||
+        (code >= 0x3040 && code <= 0x309F) ||
+        (code >= 0x30A0 && code <= 0x30FF)) {
+        width += 2;
+      } else {
+        width += 1;
+      }
+    }
+    return width;
+  }
+
+  /**
+   * Show exit banner with resume hint
+   */
+  _showExitBanner() {
+    // Clear screen first to remove any leftover content (like loading animation)
+    // Also exit alternate screen and reset terminal attributes
+    process.stdout.write('\x1b[?1049l\x1b[0m\x1b[2J\x1b[H');
+
+    const duration = this.startTime ? this._formatDuration(Date.now() - this.startTime) : '';
+    const newSessionCmd = `${CLI_NAME} sandbox ${this.sandboxId} attach`;
+    const resumeSessionCmd = this.shellSessionId
+      ? `${CLI_NAME} sandbox ${this.sandboxId} attach -s ${this.shellSessionId}`
+      : '';
+
+    // Use i18n for labels
+    const durationLabel = t('exit.session.duration');
+    const newSessionLabel = t('exit.new.session');
+    const resumeSessionLabel = t('exit.resume.session');
+
+    // Calculate display width for alignment (CJK characters count as 2)
+    const durationWidth = this._getDisplayWidth(durationLabel);
+    const newSessionWidth = this._getDisplayWidth(newSessionLabel);
+    const resumeSessionWidth = this._getDisplayWidth(resumeSessionLabel);
+
+    // Find max label width
+    const maxLabelWidth = Math.max(durationWidth, newSessionWidth, resumeSessionWidth);
+
+    // Calculate padding for each label to align commands
+    const durationPadding = ' '.repeat(maxLabelWidth - durationWidth);
+    const newSessionPadding = ' '.repeat(maxLabelWidth - newSessionWidth);
+    const resumeSessionPadding = ' '.repeat(maxLabelWidth - resumeSessionWidth);
+
+    // Calculate box width based on content
+    const contentWidth = Math.max(
+      this._getDisplayWidth(`${durationLabel}${durationPadding} ${duration}`),
+      this._getDisplayWidth(`${newSessionLabel}${newSessionPadding} ${newSessionCmd}`),
+      resumeSessionCmd ? this._getDisplayWidth(`${resumeSessionLabel}${resumeSessionPadding} ${resumeSessionCmd}`) : 0,
+      61 // minimum width for ASCII art
+    );
+    const boxWidth = contentWidth + 4; // 2 chars padding on each side
+
+    const horizontalLine = '═'.repeat(boxWidth);
+    const emptyLine = '║' + ' '.repeat(boxWidth) + '║';
+    const padLine = (text) => {
+      const textWidth = this._getDisplayWidth(text);
+      const padding = boxWidth - 2 - textWidth;
+      return '║  ' + text + ' '.repeat(Math.max(0, padding)) + '║';
+    };
+
+    // Use process.stdout.write instead of console.log to avoid any redirection issues
+    process.stdout.write('\n');
+    process.stdout.write('╔' + horizontalLine + '╗\n');
+    process.stdout.write(emptyLine + '\n');
+    process.stdout.write(padLine(`${durationLabel}${durationPadding} ${duration}`) + '\n');
+    process.stdout.write(emptyLine + '\n');
+    process.stdout.write(padLine('██████╗   ██████    ██████╗ ██╗  ██╗     ██████╗ ██╗      ██╗') + '\n');
+    process.stdout.write(padLine('██╔══██╗ ██╔═══██╗ ██╔════╝ ██║ ██╔╝    ██╔════╝ ██║      ██║') + '\n');
+    process.stdout.write(padLine('██████╔╝ ██║   ██║ ██║      █████╔╝     ██║      ██║      ██║') + '\n');
+    process.stdout.write(padLine('██╔══██╗ ██║   ██║ ██║      ██╔═██╗     ██║      ██║      ██║') + '\n');
+    process.stdout.write(padLine('██║  ██║ ╚██████╔╝ ╚██████╗ ██║  ██╗    ╚██████╗ ███████╗ ██║') + '\n');
+    process.stdout.write(padLine('╚═╝  ╚═╝  ╚═════╝   ╚═════╝ ╚═╝  ╚═╝     ╚═════╝ ╚══════╝ ╚═╝') + '\n');
+    process.stdout.write(emptyLine + '\n');
+    process.stdout.write(padLine(`${newSessionLabel}${newSessionPadding} ${newSessionCmd}`) + '\n');
+    if (resumeSessionCmd) {
+      process.stdout.write(padLine(`${resumeSessionLabel}${resumeSessionPadding} ${resumeSessionCmd}`) + '\n');
+    }
+    process.stdout.write(emptyLine + '\n');
+    process.stdout.write('╚' + horizontalLine + '╝\n');
+    process.stdout.write('\n');
+  }
+}
+
+// Export for backwards compatibility with tests
+module.exports = {
+  SandboxREPL,
+  BUILTIN_COMMANDS: BUILTIN_COMMANDS.map(c => c.name),
+  getAsciiLogo,
+};