Tui.cs

using System.Collections.ObjectModel;
using System.Diagnostics;
using System.Runtime.InteropServices;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using AIOrchestrator;
using AgentBridge;
using AgentBridge.Resources;
using Terminal.Gui;
using Terminal.Gui.App;
using Terminal.Gui.Configuration;
using Terminal.Gui.Drawing;
using Terminal.Gui.Editor;
using Terminal.Gui.Editor.Document;
using Terminal.Gui.Editor.Rendering;
using Terminal.Gui.Input;
using Terminal.Gui.ViewBase;
using Terminal.Gui.Views;

// Terminal.Gui.Drawing.Attribute collides with System.Attribute (implicit using).
using TuiAttribute = Terminal.Gui.Drawing.Attribute;

// ═══════════════════════════════════════════════════════════════════════
//  Terminal.Gui v2 — LOCAL DEVELOPER GUIDE (READ BEFORE EDITING THIS TUI)
//  docs-dev/TUI-DEVELOPMENT.md is the offline reference for the pinned package
//  versions: API cheat-sheet, pitfalls (focus, Invoke, Editor document
//  mutation, console leak) and cross-platform (Windows/Linux/macOS) rules.
//  The official API XML docs ship with the NuGet packages (see guide §1).
// ═══════════════════════════════════════════════════════════════════════

/// <summary>
/// The Terminal.Gui terminal UI of AgentBridge: a menu bar, an AGENT logo panel, a
/// streaming chat panel with an input line, a status bar, slash-command and file
/// palettes, keyboard shortcuts and mouse support — while the HTTP server keeps
/// answering API calls in the same process. See README.md → "Terminal UI".
/// </summary>
public static class ConsoleTui
{
    /// <summary>Runs the terminal UI against the server at <paramref name="serverUrl"/> until the user exits.</summary>
    public static Task RunAsync(string serverUrl, string? hostError = null)
        => new Tui(serverUrl, hostError).RunAsync();

    private sealed class Tui : IDisposable
    {
        private readonly IApplication _app;
        private readonly HttpClient _http = new() { Timeout = TimeSpan.FromMinutes(10) };
        // The streamed chat call has NO total-time cap: the server executes agent tools
        // synchronously and only streams the reply once the work finishes, so a long run
        // (e.g. a CPU TTS podcast, several minutes without a single byte) would otherwise
        // be cancelled client-side at the fixed 10-minute timeout of _http while the work
        // was still progressing. The run stays cancellable via Esc (_chatCts) and ends on
        // connection loss (the local server always terminates the stream). All the short
        // control calls keep the capped _http client above.
        private readonly HttpClient _chatHttp = new() { Timeout = System.Threading.Timeout.InfiniteTimeSpan };
        private readonly string _serverUrl;
        private readonly string? _hostError;

        private readonly List<Entry> _history = new();
        private readonly List<string> _promptHistory = new();
        private readonly List<FileRef> _files = new();
        private readonly List<string> _attached = new();
        private readonly Dictionary<string, bool> _features = new();

        private Window? _mainWindow;
        private Editor? _chatView;
        private Editor? _inputField;
        private View? _inputArea;
        private Label? _statusLabel;
        private int _inputLines = 1;
        private Scheme _baseScheme = new();
        private bool _inputPlaceholderActive = true;
        private bool _suppressCommandMenu;
        private bool _disposed;
        private View? _asciiBanner;
        private bool _bannerVisible;

        // Shared state (files/attachments/features/chat control) is touched from the
        // background tasks (HTTP, streaming) as well as the UI thread: guard the
        // collections and the chat CancellationTokenSource with one lock, and make
        // the chat-running flag atomic so a double Enter cannot start two streams.
        private readonly object _stateLock = new();
        private bool _connected;
        private int _chatRunning;   // 0 idle, 1 generating (Interlocked)
        private CancellationTokenSource? _chatCts;
        private Entry? _pending;
        private bool _followBottom = true;
        private string _lastPrompt = "";
        private bool _lastFailed;
        private int _escCount;
        private int _histIndex = -1;
        private string _histDraft = "";

        private string _provider = "";
        private string _modelName = "";
        private string _interactionMode = "";
        private string _tokensLast = "";
        private string _tokensSession = "";
        private int _contextWindow;
        private int _historyTokens;
        private string _sessionId = "";
        private string _agentSet = "default-agent";
        // Non-null when the user enabled a custom tool combination in the /agent
        // checklist (overrides the agent-set preset in the chat request via `tools`).
        private List<string>? _customTools;
        private bool _ttsAvailable, _voiceAvailable;
        private string _ttsDetail = "", _voiceDetail = "";
        private string _statusNote = "";
        // Runtime payload tokens missing from this install (from capabilities.assets); empty
        // when complete. Shown to the user in human terms, never as a technical error.
        private string[] _assetsMissing = Array.Empty<string>();
        private bool _assetsNoteShown;
        // SIP telephony state (from GET /v1/sip/status; polled while the server reports it available).
        private bool _sipAvailable;
        private string _sipState = "";
        // Telegram chat medium state (from GET /v1/telegram/status; polled while enabled).
        private bool _telegramAvailable;
        private string _telegramState = "";

        private static readonly string[] SpinnerChars = { "⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷" };
        private int _spinnerIndex;
        private volatile bool _spinnerActive;
        private Label? _spinnerLabel;

        // Top-right busy indicator (right end of the menu-bar row): shows the most important
        // operation currently running — [indicizzazione…]/[indexing…] for the background
        // document reindex (from AIOrchestrator.Setup.IndexingChanged), the chat stream, voice
        // listening. Ops are tagged strings so several concurrent operations collapse into one.
        private readonly object _busyLock = new();
        private readonly HashSet<string> _busyOps = new(StringComparer.Ordinal);
        private Label? _busyLabel;

        private static readonly JsonSerializerOptions JsonOpts = new()
        {
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower,
            DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull
        };

        private const int MaxHistory = 1000;
        private const int MaxInputLines = 4;
        // Right-end slot on the menu-bar row reserved for the busy indicator (overlay label).
        private const int BusyLabelWidth = 20;

        // UI strings come from the localized dictionary (system language, English fallback) —
        // see Resources/Dictionary.*.resx. Command names (/help, /model...) are NOT translated.
        private static string PlaceholderText => Dictionary.InputPlaceholder;

        // Web GUI (Giraffe AI): a static chat client served by its own launcher, installed
        // and kept up to date next to the executable by WebClientUpdater (see that file).

        private sealed class Entry
        {
            public required string Role;
            public required string Text;
            public bool Error;
            // Files the agent attached to this message (done method's "attachments"): each is
            // saved to disk by the client so the terminal user can open/download it.
            public List<string>? Attachments;
        }

        private sealed class FileRef
        {
            public required string Id;
            public required string FileName;
            public string Status = "";
            public bool Attached;
        }

        // The single command registry: /help (alphabetical), the "/" palette and the menu
        // bars are all generated from this list. MenuGroup picks the top-level menu where
        // the command gets its voice (BuildUI logs a warning for commands that are
        // forgotten there); MenuTitle is the short localized label used by that voice.
        private sealed record CliCommand(
            string Name, string Args, string Help, Func<Tui, string, Task> Run,
            string[]? Aliases = null,
            string? MenuGroup = null, string? MenuTitle = null, Key Shortcut = default);

        private static readonly List<CliCommand> Commands = new()
        {
            // Chat
            new("new", "", Dictionary.CmdNew, (t, _) => t.NewSessionAsync(), new[] { "/reset" },
                MenuGroup: "chat", MenuTitle: Dictionary.MenuNewChat, Shortcut: Key.N.WithCtrl),
            new("clear", "", Dictionary.CmdClear, (t, _) => t.ClearHistoryAsync(),
                MenuGroup: "chat", MenuTitle: Dictionary.MenuClearHistory, Shortcut: Key.L.WithCtrl),
            new("tts", "[text]", Dictionary.CmdTts, (t, a) => t.TtsAsync(a),
                MenuGroup: "chat", MenuTitle: Dictionary.MenuTts),
            new("retry", "", Dictionary.CmdRetry, (t, _) => t.RetryAsync(),
                MenuGroup: "chat", MenuTitle: Dictionary.MenuRetryLast, Shortcut: Key.Y.WithCtrl),
            new("exit", "", Dictionary.CmdExit, (t, _) => t.ExitAsync(), new[] { "/quit" },
                MenuGroup: "chat", MenuTitle: Dictionary.MenuExit, Shortcut: Key.Q.WithCtrl),
            // File
            new("files", "add <path>|rm <id>|list", Dictionary.CmdFiles, (t, a) => t.FilesAsync(a),
                MenuGroup: "file", MenuTitle: Dictionary.MenuFiles),
            new("attach", "[id]", Dictionary.CmdAttach, (t, a) => t.AttachAsync(a),
                MenuGroup: "file", MenuTitle: Dictionary.MenuAttach),
            // Files the agent delivered in a reply are saved under attachments/ next to the
            // executable; /open reveals them (folder by default, a specific file by name).
            new("open", "[name]", Dictionary.CmdOpen, (t, a) => t.OpenAsync(a),
                MenuGroup: "file", MenuTitle: Dictionary.MenuOpenAttachments, Shortcut: Key.O.WithCtrl),
            // Settings (menu Impostazioni/Settings): three separate panels — LLM/Provider,
            // Email (SMTP+IMAP) and General — each with its own Save button and validation,
            // so a bad value in one area never blocks the others. Tool selection and the
            // SIP/Telegram bridges stay here. Voice is NOT a setting (it starts a one-shot
            // dictation) and lives under Session; /model switches only the CURRENT chat.
            new("providers", "", Dictionary.CmdProviders, (t, _) => t.ShowProvidersPanelAsync(), new[] { "/setup", "/modelsetup" },
                MenuGroup: "settings", MenuTitle: Dictionary.MenuProviders),
            new("email", "", Dictionary.CmdEmail, (t, _) => t.ShowEmailPanelAsync(),
                MenuGroup: "settings", MenuTitle: Dictionary.MenuEmailSettings),
            new("general", "", Dictionary.CmdGeneral, (t, _) => t.ShowGeneralPanelAsync(),
                MenuGroup: "settings", MenuTitle: Dictionary.MenuGeneralSettings),
            new("tools", "[name]", Dictionary.CmdAgent, (t, a) => t.SwitchAgentAsync(a), new[] { "/agent" },
                MenuGroup: "settings", MenuTitle: Dictionary.MenuTools),
            new("ttsengine", "[name]", Dictionary.CmdTtsEngine, (t, a) => t.TtsEngineAsync(a),
                MenuGroup: "settings", MenuTitle: Dictionary.MenuTtsEngine),
            new("sip", "status|config [set <key> <value>|reload]|call <sip-uri>|answer on|off|hangup", Dictionary.CmdSip, (t, a) => t.SipAsync(a),
                MenuGroup: "settings", MenuTitle: Dictionary.MenuSip),
            new("telegram", "status|config [set <key> <value>|reload]|login-code <code>|allow|disallow <user>", Dictionary.CmdTelegram, (t, a) => t.TelegramAsync(a),
                MenuGroup: "settings", MenuTitle: Dictionary.MenuTelegram),
            // Session
            new("model", "[name]", Dictionary.CmdModel, (t, a) => t.SwitchModelAsync(a),
                MenuGroup: "session", MenuTitle: Dictionary.MenuLlmModel),
            new("voice", "[lang]", Dictionary.CmdVoice, (t, a) => t.VoiceAsync(a),
                MenuGroup: "session", MenuTitle: Dictionary.MenuVoice),
            new("features", "[name] [on|off]", Dictionary.CmdFeatures, (t, a) => t.FeaturesAsync(a),
                MenuGroup: "session", MenuTitle: Dictionary.MenuFeatures),
            new("status", "", Dictionary.CmdStatus, (t, _) => t.ShowStatusAsync(),
                MenuGroup: "session", MenuTitle: Dictionary.MenuStatus),
            new("health", "", Dictionary.CmdHealth, (t, _) => t.HealthAsync(),
                MenuGroup: "session", MenuTitle: Dictionary.MenuHealth),
            // Web
            new("web", "", Dictionary.CmdWeb, (t, _) => t.LaunchWebClientAsync(),
                MenuGroup: "web", MenuTitle: Dictionary.MenuGui),
            new("officemanager", "", Dictionary.CmdOfficeManager, (t, _) => t.LaunchOfficeManagerAsync(),
                MenuGroup: "web", MenuTitle: Dictionary.MenuOfficeManager),
            // Help
            new("help", "", Dictionary.CmdHelp, (t, _) => t.ShowHelpAsync(), new[] { "/?" },
                MenuGroup: "help", MenuTitle: Dictionary.MenuHelpItem, Shortcut: Key.F1),
            new("shortcuts", "", Dictionary.CmdShortcuts, (t, _) => t.ShowShortcutsAsync(), new[] { "/keys" },
                MenuGroup: "help", MenuTitle: Dictionary.MenuShortcuts),
            new("docs", "", Dictionary.CmdDocs, (t, _) => t.OpenDocsAsync(),
                MenuGroup: "help", MenuTitle: Dictionary.MenuDocumentation),
            new("update", "", Dictionary.CmdUpdate, (t, _) => t.UpdateAsync(),
                MenuGroup: "help", MenuTitle: Dictionary.MenuCheckUpdates),
            // No menu voice: the Help menu hosts a dedicated state toggle for this one
            // (crashReportItem in BuildUI) — see ValidateMenuCoverage.
            new("crashreport", "", Dictionary.CmdCrashReport, (t, _) => t.CrashReportAsync()),
        };

        private const uint SndAsync = 0x0001;
        private const uint SndFilename = 0x00020000;
        [DllImport("winmm.dll", SetLastError = true)]
        private static extern bool PlaySound(string pszSound, IntPtr hmod, uint fdwSound);

        // ── AGENT ASCII art ──
        // ONE definition (embedded resource, see the csproj) used by both the startup
        // banner above the chat and Help → About. The per-line gradient follows the
        // Qwen CLI brand (#4796E4 → #847ACE → #C3677F → BrightBlue/BrightMagenta/BrightRed).
        private static readonly string[] AsciiArtLines = LoadAsciiArt();
        private static readonly TuiAttribute[] AsciiArtColors =
        {
            new(Color.BrightBlue, Color.Black),
            new(Color.BrightBlue, Color.Black),
            new(Color.BrightMagenta, Color.Black),
            new(Color.BrightMagenta, Color.Black),
            new(Color.BrightRed, Color.Black),
            new(Color.BrightRed, Color.Black),
        };

        private static string[] LoadAsciiArt()
        {
            try
            {
                using var s = typeof(ConsoleTui).Assembly
                    .GetManifestResourceStream("AgentBridge.assets.agent-ascii-art.txt");
                if (s == null) return Array.Empty<string>();
                using var r = new StreamReader(s);
                return r.ReadToEnd().Replace("\r\n", "\n")
                    .Split('\n', StringSplitOptions.RemoveEmptyEntries);
            }
            catch { return Array.Empty<string>(); }
        }

        private static readonly (string Keys, string What)[] ShortcutTable =
        {
            ("Enter", Dictionary.ShortEnter),
            ("/", Dictionary.ShortSlash),
            ("@", Dictionary.ShortAt),
            ("?", Dictionary.ShortQuestion),
            ("Tab", Dictionary.ShortTab),
            ("Esc", Dictionary.ShortEsc),
            ("Ctrl+C", Dictionary.ShortCtrlC),
            ("Ctrl+D", Dictionary.ShortCtrlD),
            ("Ctrl+Y", Dictionary.ShortCtrlY),
            ("Ctrl+O", Dictionary.ShortOpenAttachments),
            ("Ctrl+R", Dictionary.ShortCtrlR),
            ("Up / Down", Dictionary.ShortUpDown),
            ("Left / Right", Dictionary.ShortLeftRight),
            ("Ctrl+A / Ctrl+E", Dictionary.ShortCtrlAE),
            ("Ctrl+U / Ctrl+K", Dictionary.ShortCtrlUK),
            ("Ctrl+W", Dictionary.ShortCtrlW),
            ("PgUp / PgDn", Dictionary.ShortPgUpDn),
            ("F1", Dictionary.ShortF1),
            ("F10", Dictionary.ShortF10),
        };

        public Tui(string serverUrl, string? hostError)
        {
            _serverUrl = serverUrl;
            _hostError = hostError;
            _http.BaseAddress = new Uri(serverUrl);
            _chatHttp.BaseAddress = new Uri(serverUrl);
            _app = Application.Create().Init();
            PuppetMode._app = _app;  // Share instance with PuppetMode (debug-only control surface)
            if (PuppetMode.Enabled) PuppetMode.StartPump();
            // Surface auto-update progress in the status bar (fires from background tasks).
            AutoUpdate.OnStatus += OnUpdateStatus;

            // Background document reindex events → top-right busy indicator. Subscribing and
            // the IsIndexingNow probe never create the processor, so merely running the TUI
            // cannot trigger a multi-minute index (see AIOrchestrator.Setup).
            AIOrchestrator.Setup.IndexingChanged += OnIndexingChanged;
            if (AIOrchestrator.Setup.IsIndexingNow) SetBusy("indexing", true);

            // Modern dark theme for the whole main window (views reference it by name).
            _baseScheme = new Scheme
            {
                Normal = new TuiAttribute(Color.White, Color.Black),
                Focus = new TuiAttribute(Color.Black, Color.BrightCyan),
                HotNormal = new TuiAttribute(Color.BrightCyan, Color.Black),
                HotFocus = new TuiAttribute(Color.Black, Color.BrightMagenta),
            };
            SchemeManager.AddScheme("Dark", _baseScheme);
            SchemeManager.AddScheme("Hint", new Scheme
            {
                Normal = new TuiAttribute(Color.Gray, Color.Black),
                Focus = new TuiAttribute(Color.Gray, Color.Black),
            });
            // Busy indicator (top-right of the menu-bar row): its background is the MENU
            // BAR's own background (read from the theme's "Menu" scheme) rather than opaque
            // black, and the ink is dark gray — readable, yet distinct from the black menu
            // item labels it sits next to.
            SchemeManager.AddScheme("Busy", new Scheme
            {
                Normal = new TuiAttribute(Color.DarkGray, MenuBarBackground()),
                Focus = new TuiAttribute(Color.DarkGray, MenuBarBackground()),
            });
            for (int i = 0; i < Math.Min(AsciiArtLines.Length, AsciiArtColors.Length); i++)
                SchemeManager.AddScheme($"Ascii{i}", new Scheme { Normal = AsciiArtColors[i] });

            BuildUI();
            _history.Add(new Entry
            {
                Role = "system",
                Text = Dictionary.WelcomeMessage,
            });
            _history.Add(new Entry { Role = "system", Text = string.Format(Dictionary.ServerNote, _serverUrl) });
            if (!string.IsNullOrEmpty(_hostError))
                _history.Add(new Entry { Role = "system", Text = string.Format(Dictionary.HostErrorNote, _hostError) });

            // The /tools selection is persistent (toolset.json under PersistentData): the
            // custom combination or preset chosen in the last run is applied now, before the
            // first chat request, so the enabled tools survive a TUI restart.
            RestoreAgentSelection();
        }

        public Task RunAsync()
        {
            if (_mainWindow is { } window)
            {
                // Give the input the focus once the window is up. The framework's initial
                // focus lands on the first focusable child (the menu bar), so re-assert
                // the input focus after the first iterations: without it, typing and the
                // Esc/Ctrl+C/Ctrl+D exit handling never reach the input.
                window.Initialized += (_, _) => _inputField?.SetFocus();
                _app.AddTimeout(TimeSpan.FromMilliseconds(60), () =>
                {
                    _inputField?.SetFocus();
                    UpdateInputLayout();
                    return false;   // one-shot
                });
                _app.AddTimeout(TimeSpan.FromMilliseconds(100), () =>
                {
                    TickSpinner();
                    return true;   // recurring spinner animation
                });
                RefreshHistory();
                _ = Task.Run(RefreshServerStateAsync);
                StartSipPolling();
                try
                {
                    _app.Run(window);
                }
                finally
                {
                    CancelChat();
                    Dispose();
                }
            }
            return Task.CompletedTask;
        }

        public void Dispose()
        {
            if (_disposed) return;
            _disposed = true;
            AutoUpdate.OnStatus -= OnUpdateStatus;
            AIOrchestrator.Setup.IndexingChanged -= OnIndexingChanged;
            CancelChat();
            try { _app.Dispose(); } catch { }
            _http.Dispose();
            _chatHttp.Dispose();
        }

        private void CancelChat()
        {
            lock (_stateLock) _chatCts?.Cancel();
        }

        // ── UI-thread marshalling ──
        // Terminal.Gui mutates views only on the main loop thread. Every UI touch
        // goes through Ui(); background tasks (HTTP, streaming) queue their updates
        // via IApplication.Invoke. Actions posted after dispose are dropped.
        private void Ui(Action action)
        {
            if (_disposed) return;
            try { _app.Invoke(action); } catch { }
        }

        // ── Layout ──

        // Slash commands whose menu voice is a custom item (state shown in the title,
        // not just "run the command") — see ValidateMenuCoverage. "attach" is folded into
        // the unified File panel (its toggle lives there), so it keeps the slash command
        // but no separate menu voice.
        private static readonly HashSet<string> MenuVoiceExempt = new(StringComparer.Ordinal) { "crashreport", "attach" };

        // Commands placed in the menus by CommandMenuItem (see ValidateMenuCoverage).
        private readonly HashSet<string> _menuVoices = new(StringComparer.Ordinal);

        // Menu voice for a slash command: the label, the accelerator and the action come
        // from the command's registry entry, and the action runs through
        // RunCommandByName — the same guarded path as typing "/name". Every placed
        // command is recorded so ValidateMenuCoverage can flag forgotten ones.
        private MenuItem CommandMenuItem(string name)
        {
            var cmd = Commands.FirstOrDefault(c => c.Name == name);
            _menuVoices.Add(name);
            if (cmd == null)
            {
                Log.LogStep($"TUI menu: '/{name}' is not in the Commands registry", monitor: true);
                return new MenuItem(name, Key.Empty, () => { });
            }
            return new MenuItem(cmd.MenuTitle ?? cmd.Help, cmd.Shortcut, () => RunCommandByName(cmd.Name, ""));
        }

        // Every slash command must be reachable from the menus. New commands must either
        // get a CommandMenuItem("name") above or be listed in MenuVoiceExempt; anything
        // forgotten shows up here as a loud startup warning, so /help, the "/" palette
        // and the menu bars stay in sync by construction.
        private void ValidateMenuCoverage()
        {
            var missing = Commands.Select(c => c.Name)
                .Where(n => !_menuVoices.Contains(n) && !MenuVoiceExempt.Contains(n))
                .ToList();
            if (missing.Count == 0) return;
            Log.LogStep(
                $"TUI menu: commands without a menu voice: {string.Join(", ", missing.Select(n => "/" + n))} — add them in BuildUI (see Commands registry)",
                monitor: true);
        }

        private void BuildUI()
        {
            _mainWindow = new Window
            {
                Title = Dictionary.WindowTitle,
                X = 0, Y = 0, Width = Dim.Fill(), Height = Dim.Fill(),
                SchemeName = "Dark",
            };

            // Terminal.Gui v2 has no checkmark on menu items — the state is shown in the title.
            MenuItem autoUpdateItem = null!;
            autoUpdateItem = new MenuItem(string.Format(Dictionary.MenuAutoUpdate, AutoUpdate.Enabled ? Dictionary.On : Dictionary.Off), Key.Empty, () =>
            {
                AutoUpdate.Toggle();
                Log.LogStep($"TUI AutoUpdate toggled: {AutoUpdate.Enabled}", monitor: true);
                autoUpdateItem.Title = string.Format(Dictionary.MenuAutoUpdate, AutoUpdate.Enabled ? Dictionary.On : Dictionary.Off);
            });

            // Crash-diagnostics toggle: whether sanitized crash reports are sent to the GitHub
            // repository (see CrashReporter.cs). State shown in the title, like Auto-Update.
            MenuItem crashReportItem = null!;
            crashReportItem = new MenuItem(string.Format(Dictionary.MenuCrashReport, CrashReporter.Enabled ? Dictionary.On : Dictionary.Off), Key.Empty, () =>
            {
                CrashReporter.Toggle();
                Log.LogStep($"TUI CrashReport toggled: {CrashReporter.Enabled}", monitor: true);
                AddNote(CrashReporter.Enabled ? Dictionary.NoteCrashReportEnabled : Dictionary.NoteCrashReportDisabled);
                crashReportItem.Title = string.Format(Dictionary.MenuCrashReport, CrashReporter.Enabled ? Dictionary.On : Dictionary.Off);
            });

            // Menus are assembled from the Commands registry (single source): each item
            // below is a command whose label/accelerator/action come from its registry
            // entry, so /help, the "/" palette and the menus can never drift apart.
            // ValidateMenuCoverage warns when a command was forgotten here.
            var menu = new MenuBar(new MenuBarItem[]
            {
                new(Dictionary.MenuChat, new MenuItem[]
                {
                    CommandMenuItem("new"),
                    CommandMenuItem("clear"),
                    CommandMenuItem("tts"),
                    new MenuItem(Dictionary.MenuCommands, Key.Empty, () => ShowCommandMenu("")),
                    CommandMenuItem("retry"),
                    CommandMenuItem("exit"),
                }),
                new(Dictionary.MenuFile, new MenuItem[]
                {
                    CommandMenuItem("files"),
                    CommandMenuItem("open"),
                }),
                new(Dictionary.MenuSettings, new MenuItem[]
                {
                    CommandMenuItem("providers"),
                    CommandMenuItem("email"),
                    CommandMenuItem("general"),
                    CommandMenuItem("tools"),
                    CommandMenuItem("ttsengine"),
                    CommandMenuItem("sip"),
                    CommandMenuItem("telegram"),
                }),
                new(Dictionary.MenuSession, new MenuItem[]
                {
                    CommandMenuItem("model"),
                    CommandMenuItem("voice"),
                    CommandMenuItem("features"),
                    CommandMenuItem("status"),
                    CommandMenuItem("health"),
                }),
                new(Dictionary.MenuWeb, new MenuItem[]
                {
                    CommandMenuItem("web"),
                    CommandMenuItem("officemanager"),
                }),
                new(Dictionary.MenuHelp, new MenuItem[]
                {
                    autoUpdateItem,
                    crashReportItem,
                    CommandMenuItem("update"),
                    CommandMenuItem("help"),
                    CommandMenuItem("shortcuts"),
                    CommandMenuItem("docs"),
                    new MenuItem(Dictionary.MenuIssues, Key.Empty, () => OpenIssuesAsync()),
                    new MenuItem(Dictionary.MenuAbout, Key.Empty, () => ShowAbout()),
                }),
            });
            _mainWindow.Add(menu);

            // Busy indicator on the right end of the menu-bar row. Terminal.Gui's MenuBar
            // has no right-side widget slot, so a small overlay label (added after the menu,
            // therefore drawn above it) shows the current operation; it is hidden when idle.
            // The "Busy" scheme paints dark-gray ink over the MENU BAR's OWN background (see
            // MenuBarBackground) — the label's clear+fill is then invisible against the bar,
            // no black rectangle, and switching between operations cannot leave ghost text.
            _busyLabel = new Label
            {
                Text = "",
                X = Pos.AnchorEnd(BusyLabelWidth), Y = 0, Width = BusyLabelWidth,
                TextAlignment = Alignment.End,
                SchemeName = "Busy",
                Visible = false,
            };
            _mainWindow.Add(_busyLabel);
            ValidateMenuCoverage();

            // Esc never quits the app directly: it is handled by the focused view
            // (input line, dialogs, menus). Guard the window's default Esc→Quit
            // binding so an Esc pressed on a non-handling view (e.g. the send
            // button) cannot close the whole UI accidentally.
            _mainWindow.KeyDown += (_, key) =>
            {
                if (key == Key.Esc) key.Handled = true;
                // Puppet mode only: PrintScreen dumps the current screen to a file.
                else if (PuppetMode.Enabled && key == Key.PrintScreen)
                {
                    key.Handled = true;
                    PuppetCapture();
                }
            };

            // Content area below the menu bar (status line + StatusBar own the last
            // two rows). CanFocus: a plain View defaults to CanFocus=false, which
            // would block focus for every focusable child below it (the input field).
            var contentArea = new View
            {
                X = 0, Y = 1, Width = Dim.Fill(), Height = Dim.Fill() - 3,
                CanFocus = true,
            };
            _mainWindow.Add(contentArea);

            // Chat panel: history + input line, full width. The AGENT ASCII-art banner
            // (gradient) sits above the chat at startup — the welcome message is the
            // first history entry below it — and collapses on the first chat message.
            var chatFrame = new FrameView
            {
                Title = Dictionary.ChatFrameTitle,
                X = 0, Y = 0,
                Width = Dim.Fill(), Height = Dim.Fill(),
            };
            contentArea.Add(chatFrame);

            if (AsciiArtLines.Length > 0)
            {
                _asciiBanner = new View
                {
                    X = 0, Y = 0, Width = Dim.Fill(), Height = AsciiArtLines.Length + 1,
                };
                for (int i = 0; i < AsciiArtLines.Length; i++)
                    _asciiBanner.Add(new Label { Text = AsciiArtLines[i], X = 1, Y = i, SchemeName = $"Ascii{i}" });
                chatFrame.Add(_asciiBanner);
                _bannerVisible = true;
            }

            _chatView = new Editor
            {
                X = 0, Y = _bannerVisible ? Pos.Bottom(_asciiBanner!) : 0, Width = Dim.Fill(), Height = Dim.Fill() - 1,
                ReadOnly = true,
                WordWrap = true,
                CanFocus = false,
                SchemeName = "Dark",
            };
            // User messages are repainted in the menu-bar celeste so they never read as
            // agent text (both are otherwise the same white-on-black scheme).
            _chatView.LineTransformers.Add(new ChatRoleColorizer(_chatView, MenuBarBackground()));
            chatFrame.Add(_chatView);
            // Auto-follow the stream only while the user is at the bottom; scrolling
            // up (wheel or PgUp) stops the yank until they scroll down or send a message.
            _chatView.MouseEvent += (_, e) =>
            {
                if ((e.Flags & MouseFlags.WheeledUp) != 0) _followBottom = false;
                else if ((e.Flags & MouseFlags.WheeledDown) != 0) _followBottom = true;
            };

            var inputArea = new View
            {
                X = 0, Y = Pos.Bottom(_chatView), Width = Dim.Fill(), Height = 1,
                CanFocus = true,
            };
            chatFrame.Add(inputArea);
            _inputArea = inputArea;

            // One-character spinner shown next to the prompt while generating.
            _spinnerLabel = new Label
            {
                Text = " ",
                X = 0, Y = 0, Width = 1,
                SchemeName = "Dark",
            };
            inputArea.Add(_spinnerLabel);

            // Multi-line prompt box: soft-wraps and grows up to MaxInputLines rows (see
            // UpdateInputLayout); full width minus the spinner column, so it reaches
            // the right margin of the frame without covering the spinner.
            _inputField = new Editor
            {
                X = 1, Y = 0, Width = Dim.Fill() - 1, Height = 1,
                WordWrap = true,
                Multiline = true,
                GutterOptions = GutterOptions.None,
            };
            SetPlaceholder();
            _inputField.HasFocusChanged += OnInputFocusChanged;
            _inputField.KeyDown += OnInputKeyDown;
            _inputField.ContentChanged += (_, _) => { OnInputChanged(); UpdateInputLayout(); };
            _inputField.ViewportChanged += (_, _) => UpdateInputLayout();
            inputArea.Add(_inputField);

            // The Editor consumes the movement keys natively; at a text boundary the key
            // is left unhandled and would bubble up to the Application-level arrow-key
            // focus navigation, moving the focus out of the prompt. Swallow the movement
            // keys at the input's parent so the prompt can never lose focus to an arrow.
            inputArea.KeyDownNotHandled += (_, key) =>
            {
                if (key == Key.CursorLeft || key == Key.CursorRight
                    || key == Key.CursorUp || key == Key.CursorDown
                    || key == Key.CursorLeft.WithCtrl || key == Key.CursorRight.WithCtrl
                    || key == Key.CursorUp.WithCtrl || key == Key.CursorDown.WithCtrl
                    || key == Key.Home || key == Key.End
                    || key == Key.PageUp || key == Key.PageDown)
                    key.Handled = true;
            };

            // Status line (dynamic state: connection, provider/model, tools, context,
            // capabilities, notes) above a real StatusBar with the static key hints.
            _statusLabel = new Label
            {
                X = 0, Y = Pos.AnchorEnd(2), Width = Dim.Fill(), Height = 1,
                SchemeName = "Hint",
                Text = "",
            };
            _mainWindow.Add(_statusLabel);
            _mainWindow.Add(new StatusBar(new[]
            {
                new Shortcut { Title = Dictionary.StatusBarHints },
            }));
        }

        // ── Input field ──
        private void SetPlaceholder()
        {
            if (_inputField == null) return;
            _inputPlaceholderActive = true;
            _inputField.Text = PlaceholderText;
            _inputField.SchemeName = "Hint";
        }

        private void ClearPlaceholder()
        {
            if (_inputField == null) return;
            _inputPlaceholderActive = false;
            _inputField.Text = "";
            _inputField.SchemeName = "Dark";
        }

        private void OnInputFocusChanged(object? sender, HasFocusEventArgs e)
        {
            if (e.NewValue)
            {
                if (_inputPlaceholderActive) ClearPlaceholder();
            }
            else if (string.IsNullOrWhiteSpace(_inputField?.Text))
            {
                SetPlaceholder();
            }
        }

        private void OnInputChanged()
        {
            if (_suppressCommandMenu || _inputPlaceholderActive) return;
            var t = _inputField?.Text ?? "";
            if (t == "/")
            {
                _suppressCommandMenu = true;
                ShowCommandMenu("");
                _suppressCommandMenu = false;
                ClearInputWhen("/");
            }
            else if (t == "@")
            {
                _suppressCommandMenu = true;
                ShowFilesDialog();
                _suppressCommandMenu = false;
                ClearInputWhen("@");
            }
            else if (t == "?")
            {
                _suppressCommandMenu = true;
                _ = ShowShortcutsAsync();
                _suppressCommandMenu = false;
                ClearInputWhen("?");
            }
        }

        // Fallback for when a trigger character (/, @, ?) reaches the input by paste
        // (typing is intercepted in OnInputKeyDown before insertion). This handler runs
        // inside the Editor's DocumentChanged callback, so mutating the document here
        // throws "Cannot change document within another document change"; Application.Invoke
        // executes synchronously on the main thread, so the clear must go through a
        // main-loop timeout, which fires only after the change completes.
        private void ClearInputWhen(string expected)
        {
            _app.AddTimeout(TimeSpan.Zero, () =>
            {
                if (_inputField != null && _inputField.Text == expected) _inputField.Text = "";
                return false;   // one-shot
            });
        }

        private void OnInputKeyDown(object? sender, Key key)
        {
            if (_inputPlaceholderActive)
                ClearPlaceholder();   // the first keystroke dismisses the hint, then falls through

            // "/" "@" "?" only act as the first character. Intercepting them here
            // (before the Editor inserts the char) keeps the trigger character out of
            // the document: when the palette runs inside the Editor's DocumentChanged
            // handler, clearing it back throws "Cannot change document within another
            // document change" (Application.Invoke executes synchronously on the main
            // thread, so even a deferred clear failed). Consuming the key avoids the
            // insert entirely — no crash, no lingering "/".
            if (!_suppressCommandMenu && (_inputField?.Text ?? "").Length == 0)
            {
                // Opening a palette/dialog is a fresh start: reset the double-Esc exit
                // counter (these keys are consumed and no longer reach the reset below).
                if (key == (Key)'/')
                {
                    key.Handled = true;
                    _escCount = 0;
                    ShowCommandMenu("");
                    return;
                }
                if (key == (Key)'@')
                {
                    key.Handled = true;
                    _escCount = 0;
                    ShowFilesDialog();
                    return;
                }
                if (key == (Key)'?')
                {
                    key.Handled = true;
                    _escCount = 0;
                    _ = ShowShortcutsAsync();
                    return;
                }
            }

            if (key == Key.Enter && !key.IsShift)
            {
                key.Handled = true;
                Submit();
            }
            else if (key == Key.Enter.WithShift)
            {
                // Shift+Enter inserts a newline (the Editor binds only plain Enter to NewLine).
                key.Handled = true;
                if (_inputField is { Document: { } doc })
                {
                    var at = _inputField.CaretOffset;
                    doc.Insert(at, "\n");
                    _inputField.CaretOffset = at + 1;
                }
            }
            else if (key == Key.Esc)
            {
                // Keep the window's default "Esc quits" binding from firing: Esc here
                // clears the input, and twice on an empty input exits the app.
                key.Handled = true;
                if ((_inputField?.Text ?? "").Length > 0)
                {
                    _inputField!.Text = "";
                }
                else if (++_escCount >= 2)
                {
                    RequestExit();
                }
                else
                {
                    _statusNote = Dictionary.StatusEscAgain;
                    UpdateStatusUi();
                }
            }
            else if (key == Key.C.WithCtrl)
            {
                key.Handled = true;
                if (_chatRunning != 0)
                {
                    CancelChat();
                    _statusNote = Dictionary.StatusCancelling;
                    UpdateStatusUi();
                }
                else if ((_inputField?.Text ?? "").Length > 0)
                {
                    _inputField!.Text = "";
                }
                else if (++_escCount >= 2)
                {
                    RequestExit();
                }
                else
                {
                    _statusNote = Dictionary.StatusCtrlCAgain;
                    UpdateStatusUi();
                }
            }
            else if (key == Key.D.WithCtrl)
            {
                // Exit on an empty input; otherwise the Editor's native
                // "delete char in front" applies (same guard as the old TUI).
                if ((_inputField?.Text ?? "").Length == 0)
                {
                    key.Handled = true;
                    RequestExit();
                }
            }
            else if (key == Key.Y.WithCtrl)
            {
                key.Handled = true;
                _ = RetryAsync();
            }
            else if (key == Key.R.WithCtrl)
            {
                key.Handled = true;
                ReverseSearch();
            }
            else if (key == Key.F1)
            {
                key.Handled = true;
                _ = ShowHelpAsync();
            }
            else if (key == Key.O.WithCtrl)
            {
                // Open the attachments the agent delivered in replies (the folder; a specific
                // file via /open <name>). Ctrl+O is the plain "open" convention.
                key.Handled = true;
                _ = OpenAsync("");
            }
            else if (key == Key.P.WithCtrl || (key == Key.CursorUp && CaretOnFirstLine()))
            {
                key.Handled = true;
                HistoryPrev();
            }
            else if (key == Key.N.WithCtrl || (key == Key.CursorDown && CaretOnLastLine()))
            {
                key.Handled = true;
                HistoryNext();
            }
            else if (key == Key.U.WithCtrl)
            {
                // Delete from the start of the current line to the insertion point.
                key.Handled = true;
                if (_inputField is { Document: { } doc })
                {
                    var caret = _inputField.CaretOffset;
                    var line = doc.GetLineByOffset(caret);
                    doc.Remove(line.Offset, caret - line.Offset);
                }
            }
            else if (key == Key.K.WithCtrl)
            {
                // Delete from the insertion point to the end of the current line.
                key.Handled = true;
                if (_inputField is { Document: { } doc })
                {
                    var caret = _inputField.CaretOffset;
                    var line = doc.GetLineByOffset(caret);
                    doc.Remove(caret, line.Offset + line.Length - caret);
                }
            }
            else if (key == Key.W.WithCtrl)
            {
                // Delete the word before the insertion point.
                key.Handled = true;
                if (_inputField is { Document: { } doc })
                {
                    var caret = _inputField.CaretOffset;
                    var t = doc.Text;
                    var start = caret;
                    while (start > 0 && char.IsWhiteSpace(t[start - 1])) start--;
                    while (start > 0 && !char.IsWhiteSpace(t[start - 1])) start--;
                    if (start < caret) doc.Remove(start, caret - start);
                }
            }
            else if (key == Key.PageUp)
            {
                key.Handled = true;
                _followBottom = false;
                _chatView?.ScrollVertical(-(_chatView.Viewport.Height - 1));
            }
            else if (key == Key.PageDown)
            {
                key.Handled = true;
                _followBottom = true;
                _chatView?.ScrollVertical(_chatView.Viewport.Height - 1);
            }
            else
            {
                _escCount = 0;
            }
        }

        // ── Multi-line input layout ──
        // The prompt box height tracks its wrapped content (max MaxInputLines rows) and
        // the chat panel shrinks accordingly. Re-runs on content changes and viewport
        // resizes (the wrap column is the editor's viewport width).
        private void UpdateInputLayout()
        {
            if (_inputField is not { } ed || _inputArea is not { } area || _chatView is not { } chat) return;
            if (ed.Viewport.Width <= 0) return;   // not laid out yet
            var rows = Math.Clamp(EstimateWrapRows(ed.Text ?? "", ed.Viewport.Width), 1, MaxInputLines);
            if (rows == _inputLines) return;
            _inputLines = rows;
            ed.Height = rows;
            area.Height = rows;
            chat.Height = Dim.Fill() - rows - BannerRows;
        }

        // Rows the startup ASCII-art banner occupies above the chat (0 once collapsed).
        private int BannerRows => _bannerVisible ? AsciiArtLines.Length + 1 : 0;

        // The banner gives way to the conversation on the first chat message.
        private void CollapseBanner()
        {
            if (!_bannerVisible || _asciiBanner == null || _chatView == null) return;
            Log.LogStep("TUI banner collapsed (first chat message)", monitor: true);
            _bannerVisible = false;
            _asciiBanner.SuperView?.Remove(_asciiBanner);
            _chatView.Y = 0;
            _inputLines = 0;   // force UpdateInputLayout to recompute the chat height
            UpdateInputLayout();
        }

        // Approximate the soft-wrapped visual rows (the Editor wraps at the viewport width).
        private static int EstimateWrapRows(string text, int width)
        {
            if (text.Length == 0) return 1;
            var rows = 0;
            foreach (var line in text.Replace("\r\n", "\n").Split('\n'))
                rows += Math.Max(1, (line.Length + width - 1) / width);
            return rows;
        }

        // ── Spinner ──
        private void StartSpinner()
        {
            Log.LogStep("TUI spinner started");
            _spinnerActive = true;
            _spinnerIndex = 0;
            if (_spinnerLabel != null)
                _spinnerLabel.Text = SpinnerChars[0];
        }

        private void StopSpinner()
        {
            Log.LogStep("TUI spinner stopped");
            _spinnerActive = false;
            if (_spinnerLabel != null)
                _spinnerLabel.Text = " ";
        }

        private void TickSpinner()
        {
            if (_spinnerLabel == null || !_spinnerActive) return;
            _spinnerIndex = (_spinnerIndex + 1) % SpinnerChars.Length;
            _spinnerLabel.Text = SpinnerChars[_spinnerIndex];
        }

        private bool CaretOnFirstLine()
        {
            if (_inputField is not { Document: { } doc }) return true;
            var line = doc.GetLineByOffset(_inputField.CaretOffset);
            return line.Offset == 0;
        }

        private bool CaretOnLastLine()
        {
            if (_inputField is not { Document: { } doc }) return true;
            var line = doc.GetLineByOffset(_inputField.CaretOffset);
            return line.Offset + line.Length >= doc.TextLength;
        }

        private void HistoryPrev()
        {
            if (_promptHistory.Count == 0) return;
            if (_histIndex < 0)
            {
                _histDraft = _inputField?.Text ?? "";
                _histIndex = _promptHistory.Count - 1;
            }
            else if (_histIndex > 0)
            {
                _histIndex--;
            }
            if (_inputField != null)
            {
                _inputField.Text = _promptHistory[_histIndex];
                _inputField.CaretOffset = _inputField.Document?.TextLength ?? 0;
            }
        }

        private void HistoryNext()
        {
            if (_histIndex < 0) return;
            _histIndex++;
            if (_inputField == null) return;
            if (_histIndex >= _promptHistory.Count)
            {
                _histIndex = -1;
                _inputField.Text = _histDraft;
            }
            else
            {
                _inputField.Text = _promptHistory[_histIndex];
            }
            _inputField.CaretOffset = _inputField.Document?.TextLength ?? 0;
        }

        private void Submit()
        {
            var text = (_inputField?.Text ?? "").Trim();
            if (_inputPlaceholderActive || text.Length == 0) return;
            _inputField!.Text = "";
            _inputPlaceholderActive = false;
            _inputField.SchemeName = "Dark";
            _followBottom = true;

            if (text[0] == '/')
            {
                Log.LogStep($"TUI submit: {text}");
                RunCommandLine(text);
                return;
            }
            Log.LogStep($"TUI submit (chat): {(text.Length > 100 ? text[..100] + "…" : text)}", monitor: true);
            CollapseBanner();   // the conversation starts: the ASCII-art banner gives way
            _promptHistory.Add(text);
            if (_promptHistory.Count > 200) _promptHistory.RemoveAt(0);
            StartChat(text);
        }

        // ── Chat ──
        private void StartChat(string prompt) => _ = Task.Run(() => SendChatAsync(prompt));

        // Transcript of the conversation as every chat request sends it (OpenAI `messages` shape):
        // every user turn plus every successful agent reply — system notes, errors and progress
        // entries stay out. Sending the accumulated transcript (not just the newest prompt) is what
        // lets the server resume the conversation on a NEW session when the old one expired
        // (AgentBridge /v1/chat/completions seeds a fresh session from it). UI thread only: it
        // reads _history, which is owned by the main loop.
        private List<object> BuildTranscript()
        {
            var messages = new List<object>();
            foreach (var e in _history)
            {
                if (e.Role == "user" && !string.IsNullOrWhiteSpace(e.Text))
                    messages.Add(new { role = "user", content = e.Text });
                else if (e.Role == "agent" && !e.Error && !string.IsNullOrWhiteSpace(e.Text))
                    messages.Add(new { role = "assistant", content = e.Text });
            }
            return messages;
        }

        private async Task SendChatAsync(string prompt)
        {
            if (Interlocked.CompareExchange(ref _chatRunning, 1, 0) != 0)
            {
                _statusNote = Dictionary.StatusGenerating;
                UpdateStatusUi();
                return;
            }
            _lastPrompt = prompt;
            _lastFailed = false;
            lock (_stateLock) _chatCts = new CancellationTokenSource();
            SetBusy("generating", true);
            var sw = Stopwatch.StartNew();
            // The transcript is snapshotted ON the UI thread — the only owner of _history — inside
            // the same marshalled block that appends the user turn, and handed back through the task:
            // Ui() only QUEUES the action when called from a background thread, so the snapshot must
            // never be read from here directly.
            var transcript = new TaskCompletionSource<List<object>>(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                StartSpinner();
                _history.Add(new Entry { Role = "user", Text = prompt });
                _pending = new Entry { Role = "agent", Text = "" };
                RefreshHistory();
                UpdateStatus();
                transcript.TrySetResult(BuildTranscript());
            });

            try
            {
                if (!_connected) await RefreshServerStateAsync();
                if (string.IsNullOrEmpty(_sessionId))
                    throw new InvalidOperationException("no session — server unreachable");

                // Prompt-only fallback: the UI is gone (disposed) and will never run the block above,
                // so the request degrades to the historical single-message behaviour.
                List<object> outgoing;
                try { outgoing = await transcript.Task.WaitAsync(TimeSpan.FromSeconds(5)); }
                catch { outgoing = new List<object> { new { role = "user", content = prompt } }; }

                var attached = SnapshotAttached();
                // Additive extension: an explicit tool combination (custom checklist
                // selection) overrides the agent set resolved from `model`.
                var custom = _customTools is { Count: > 0 } ? _customTools : null;
                var body = JsonSerializer.Serialize(new
                {
                    model = _agentSet,
                    tools = custom,
                    // The accumulated transcript, not just the newest prompt: if the session expired
                    // server-side (or the server restarted) the conversation is resumed on a fresh
                    // session seeded from it, so the agent keeps the whole context. On a live session
                    // the server only uses the last user message as the prompt, so nothing is applied
                    // twice (see BuildTranscript).
                    messages = outgoing,
                    session_id = _sessionId,
                    file_ids = attached.Count > 0 ? attached : (List<string>?)null,
                    stream = true,
                }, JsonOpts);

                using var request = new HttpRequestMessage(HttpMethod.Post, "/v1/chat/completions")
                {
                    Content = new StringContent(body, Encoding.UTF8, "application/json"),
                };
                using var response = await _chatHttp.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, _chatCts.Token);

                if (!response.IsSuccessStatusCode)
                {
                    var err = await ReadErrorAsync(response);
                    FinishChat(new Entry { Role = "agent", Text = err, Error = true });
                    _lastFailed = true;
                    _statusNote = FriendlyHttp((int)response.StatusCode);
                    return;
                }

                await using var stream = await response.Content.ReadAsStreamAsync(_chatCts.Token);
                using var reader = new StreamReader(stream, Encoding.UTF8);
                while (true)
                {
                    _chatCts.Token.ThrowIfCancellationRequested();
                    var line = await reader.ReadLineAsync(_chatCts.Token);
                    if (line == null) break;
                    if (!line.StartsWith("data: ")) continue;
                    var data = line["data: ".Length..];
                    if (data == "[DONE]") break;
                    try
                    {
                        using var doc = JsonDocument.Parse(data);
                        // The server echoes the session id on a dedicated first chunk. A DIFFERENT id
                        // means the previous session had expired (or the server restarted) and a new
                        // one took over; session_resumed tells whether the previous turns came back
                        // from the transcript we sent. Rebind so the next prompt keeps the chat going,
                        // and note it discreetly in the log.
                        if (doc.RootElement.TryGetProperty("session_id", out var sidEl) && sidEl.ValueKind == JsonValueKind.String)
                        {
                            var sid = sidEl.GetString();
                            if (!string.IsNullOrEmpty(sid) && !string.Equals(sid, _sessionId, StringComparison.Ordinal))
                            {
                                _sessionId = sid;
                                var shortId = sid[..Math.Min(8, sid.Length)];
                                var resumed = doc.RootElement.TryGetProperty("session_resumed", out var rs)
                                    && rs.ValueKind == JsonValueKind.True;
                                AddNote(string.Format(
                                    resumed ? Dictionary.NoteSessionResumed : Dictionary.NoteNewSession, shortId));
                            }
                        }
                        // Agent-attached files (standard MCP embedded-resource shape): saved to
                        // disk next to the executable so the terminal user can open/download them.
                        if (doc.RootElement.TryGetProperty("attachments", out var atts) && atts.ValueKind == JsonValueKind.Array)
                        {
                            foreach (var att in atts.EnumerateArray())
                            {
                                try
                                {
                                    var name = att.TryGetProperty("name", out var n) ? n.GetString() : "attachment";
                                    var safe = string.Concat((name ?? "attachment").Where(c => !Path.GetInvalidFileNameChars().Contains(c)));
                                    Directory.CreateDirectory(AttachmentsDir);
                                    var path = Path.Combine(AttachmentsDir, $"{DateTime.Now:yyyyMMdd-HHmmss}-{safe}");
                                    if (!await SaveAttachmentAsync(att, path, _chatCts.Token))
                                    {
                                        Log.LogStep($"TUI chat: attachment '{name}' delivered with no payload and not found in the workspace");
                                        continue;
                                    }
                                    (_pending!.Attachments ??= new List<string>()).Add(path);
                                }
                                catch (Exception ex) { Log.LogStep($"TUI chat: attachment save failed — {ex.Message}"); }
                            }
                        }
                        var delta = doc.RootElement.GetProperty("choices")[0].GetProperty("delta");
                        if (delta.TryGetProperty("content", out var c) && c.ValueKind == JsonValueKind.String)
                        {
                            var chunk = c.GetString();
                            if (string.IsNullOrEmpty(chunk)) continue;
                            _pending!.Text += chunk;
                            if (sw.ElapsedMilliseconds > 80) { sw.Restart(); Ui(RefreshHistory); }
                        }
                    }
                    catch { }
                }

                _connected = true;
                _statusNote = string.Format(Dictionary.StatusReplied, sw.ElapsedMilliseconds / 1000.0);
                FinishChat(_pending);
            }
            catch (OperationCanceledException)
            {
                _statusNote = Dictionary.StatusCancelled;
                _lastFailed = true;
                FinishChat(new Entry { Role = "agent", Text = Dictionary.StatusCancelledEntry, Error = true });
            }
            catch (Exception ex)
            {
                _statusNote = Dictionary.StatusError;
                _lastFailed = true;
                _connected = false;
                FinishChat(new Entry { Role = "agent", Text = string.Format(Dictionary.StatusRequestFailed, ex.Message), Error = true });
            }
            finally
            {
                Interlocked.Exchange(ref _chatRunning, 0);
                SetBusy("generating", false);
                lock (_stateLock)
                {
                    _chatCts?.Dispose();
                    _chatCts = null;
                }
                Ui(() => { StopSpinner(); RefreshHistory(); UpdateStatus(); });
                _ = Task.Run(RefreshSessionStateAsync);
                Log.LogStep($"TUI chat finished: {sw.ElapsedMilliseconds} ms, reply {( _pending?.Text?.Length ?? 0)} chars, status: {_statusNote}");
            }
        }

        // Captures the completed reply on the background thread and appends it to the
        // history on the UI thread (the List<Entry> must only be touched on the main loop).
        private void FinishChat(Entry? done)
        {
            Ui(() =>
            {
                _pending = null;
                if (done != null) _history.Add(done);
                RefreshHistory();
                UpdateStatus();
            });
        }

        private async Task<string> ReadErrorAsync(HttpResponseMessage response)
        {
            try
            {
                var raw = await response.Content.ReadAsStringAsync();
                using var doc = JsonDocument.Parse(raw);
                var root = doc.RootElement;
                var err = root.TryGetProperty("error", out var e) ? e.GetString() : "error";
                var detail = root.TryGetProperty("detail", out var d) ? d.GetString() : null;
                return detail ?? err ?? $"HTTP {(int)response.StatusCode}";
            }
            catch { return $"HTTP {(int)response.StatusCode}"; }
        }

        // ── History rendering ──
        private void RefreshHistory()
        {
            if (_chatView == null) return;
            if (_history.Count > MaxHistory) _history.RemoveRange(0, _history.Count - MaxHistory);
            var sb = new StringBuilder();
            foreach (var e in _history) AppendEntry(sb, e);
            var pending = _pending;   // local copy: FinishChat clears it on the same thread
            if (pending != null) AppendEntry(sb, pending);
            if (_chatView.Document is { } doc)
            {
                doc.Text = sb.ToString();
            }
            else
            {
                _chatView.Document = new TextDocument(sb.ToString());
            }
            // Setting the caret scrolls the viewport so it stays visible (auto-follow),
            // but only while the user has not scrolled up (see _followBottom).
            if (_followBottom)
                _chatView.CaretOffset = Math.Max(0, (_chatView.Document?.TextLength ?? 1) - 1);
        }

        // Agent-delivered files (the done method's "attachments") are saved here, next to
        // the executable, so the terminal user can open or copy them (see /open and Ctrl+O).
        private static string AttachmentsDir =>
            Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "attachments");

        /// <summary>
        /// Saves one delivered attachment (the done method's "attachments") to <paramref name="target"/>
        /// via <see cref="AttachmentDelivery"/> — the workspace copy first (the server shares this
        /// machine, and a file above the inline limit arrives as a local reference with no payload), the
        /// inlined base64 payload as the fallback.
        /// </summary>
        private static async Task<bool> SaveAttachmentAsync(JsonElement att, string target, CancellationToken ct)
        {
            var (source, temporary) = await AttachmentDelivery.ResolveAsync(att, ct);
            if (source == null) return false;
            try
            {
                File.Copy(source, target, overwrite: true);
                return true;
            }
            finally
            {
                if (temporary) try { File.Delete(source); } catch { }
            }
        }

        private static void AppendEntry(StringBuilder sb, Entry e)
        {
            sb.Append(e.Role switch
            {
                "user" => Dictionary.HistoryYou,
                "agent" => e.Error ? Dictionary.HistoryError : Dictionary.HistoryAgent,
                _ => "·",
            }).Append('\n');
            sb.Append(e.Text.Replace("\r\n", "\n")).Append("\n\n");
            if (e.Attachments is { Count: > 0 })
            {
                // Full paths, not just the names: the user must see WHERE each delivered
                // file was saved so they can open or copy it (see /open and Ctrl+O).
                foreach (var path in e.Attachments)
                    sb.Append(string.Format(Dictionary.ChatAttachmentMarker, path)).Append('\n');
                sb.Append(Dictionary.ChatAttachmentHint).Append("\n\n");
            }
        }

        private void AddNote(string text)
        {
            Ui(() =>
            {
                _history.Add(new Entry { Role = "system", Text = text });
                RefreshHistory();
            });
        }

        // Thread-safe snapshots of the state collections (mutated by background tasks).
        private List<string> SnapshotAttached()
        {
            lock (_stateLock) return new List<string>(_attached);
        }

        // ── Status bar ──
        // One comprehensible line: connection, provider/model, the active tools,
        // context usage, capabilities and the transient note. No uuid and no cryptic
        // abbreviations (sess:, f:, tts:✓) — those told the user nothing.
        private void UpdateStatus()
        {
            if (_statusLabel == null) return;
            // host:port (not the full URL) tells the user which server they talk to.
            var parts = new List<string> { _connected ? "●" : "○", ShortServerUrl(_serverUrl) };
            if (_provider.Length > 0) parts.Add(_provider);
            if (_modelName.Length > 0 && !string.Equals(_modelName, _provider)) parts.Add(_modelName);
            var tools = EffectiveLoadedTools();
            if (tools.Length > 0)
                parts.Add($"{Dictionary.StatusTools}: {string.Join(", ", tools.Select(ToolShortName))}");
            if (_contextWindow > 0)
                parts.Add($"ctx {FormatTokens(_historyTokens)}/{FormatTokens(_contextWindow)}");
            parts.Add($"TTS {(_ttsAvailable ? "✓" : "✗")}");
            parts.Add($"mic {(_voiceAvailable ? "✓" : "✗")}");
            if (_sipAvailable && _sipState.Length > 0) parts.Add($"sip: {_sipState}");
            if (_telegramAvailable && _telegramState.Length > 0) parts.Add($"tg: {_telegramState}");
            if (_chatRunning != 0) parts.Add(Dictionary.StatusGeneratingShort);
            if (_statusNote.Length > 0) parts.Add(_statusNote);
            var text = string.Join(" · ", parts.Where(p => p.Length > 0));
            _statusLabel.Text = text.Length > 240 ? text[..240] : text;
        }

        // The tools that will actually run in the chat: the custom checklist selection
        // when set, otherwise the agent-set preset.
        private string[] EffectiveTools() => _customTools is { Count: > 0 }
            ? _customTools.ToArray()
            : AgentTools.Resolve(_agentSet);

        // The tools shown in the status bar: only the ones actually loaded at runtime
        // (a preset may name a plugin that is absent from Tools/ on this machine — the
        // server skips unknown names, so showing them would overstate the agent's tools).
        private string[] EffectiveLoadedTools()
        {
            var loaded = AgentTools.Catalog().Select(c => c.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
            return EffectiveTools().Where(t => loaded.Contains(t)).ToArray();
        }

        // What the status page shows as the agent set: the preset id, or "custom" with
        // the individually enabled tools when the /agent checklist was used.
        private string AgentSetDisplay() => _customTools is { Count: > 0 }
            ? $"custom ({string.Join(", ", _customTools.Select(ToolShortName))})"
            : _agentSet;

        // "FileTool" → "File", "EMailTool" → "Email": readable tool names for the UI.
        private static string ToolShortName(string name) =>
            string.Equals(name, "EMailTool", StringComparison.OrdinalIgnoreCase) ? "Email"
            : name.EndsWith("Tool", StringComparison.Ordinal) ? name[..^4]
            : name;

        private static string ShortServerUrl(string url)
        {
            try
            {
                var u = new Uri(url);
                return $"{u.Host}:{u.Port}";
            }
            catch { return url; }
        }

        private static string FormatTokens(int n) => n switch
        {
            >= 1_000_000 => $"{n / 1_000_000.0:0.#}M",
            >= 1_000 => $"{n / 1_000.0:0.#}k",
            _ => n.ToString(),
        };

        // A note the user can understand instead of a bare HTTP code.
        private static string FriendlyHttp(int code) => code switch
        {
            401 or 403 => string.Format(Dictionary.HttpStatusAuth, code),
            404 => string.Format(Dictionary.HttpStatusNotFound, code),
            429 => string.Format(Dictionary.HttpStatusRateLimited, code),
            >= 500 => string.Format(Dictionary.HttpStatusServer, code),
            _ => string.Format(Dictionary.HttpStatusOther, code),
        };

        private void OnUpdateStatus(string message) => Ui(() => { _statusNote = message; UpdateStatusUi(); });

        private void UpdateStatusUi() => Ui(UpdateStatus);

        // ── Top-right busy indicator ──
        private void OnIndexingChanged(bool indexing) => SetBusy("indexing", indexing);

        private void SetBusy(string op, bool on)
        {
            lock (_busyLock)
            {
                if (on) _busyOps.Add(op);
                else _busyOps.Remove(op);
            }
            Ui(UpdateBusyLabel);
        }

        private void UpdateBusyLabel()
        {
            if (_busyLabel == null) return;
            string text;
            lock (_busyLock)
            {
                text = _busyOps.Contains("indexing") ? Dictionary.BusyIndexing
                    : _busyOps.Contains("generating") ? Dictionary.BusyGenerating
                    : _busyOps.Contains("listening") ? Dictionary.BusyListening
                    : "";
            }
            _busyLabel.Visible = text.Length > 0;
            _busyLabel.Text = text;
        }

        /// <summary>The background color of the menu-bar row (the theme's "Menu" scheme), so
        /// the busy overlay can paint with the same backdrop instead of an opaque box.</summary>
        private static Color MenuBarBackground()
        {
            return SchemeManager.TryGetScheme("Menu", out var menu) ? menu.Normal.Background : Color.Black;
        }

        // The chat history lives in one read-only Editor, which paints every visual line
        // with a single attribute — per-message colors therefore go through a visual-line
        // transformer. The role of each document line is derived from the block headers
        // that AppendEntry writes (❯/◆/✗/"·" on their own line); user blocks are repainted
        // in the menu-bar celeste, so they stand apart from the white agent text.
        private sealed class ChatRoleColorizer(Editor chat, Color userColor) : IVisualLineTransformer
        {
            private const string UserRole = "user";
            private TuiAttribute? _userAttribute;
            private string _text = "";
            private string[] _roles = [];

            public void Transform(CellVisualLine line)
            {
                string text = chat.Document.Text;
                if (text != _text)
                {
                    _text = text;
                    _roles = ComputeRoles(text);
                }
                int index = line.DocumentLine.LineNumber - 1;
                if (index < 0 || index >= _roles.Length || _roles[index] != UserRole) return;
                _userAttribute ??= new TuiAttribute(userColor, Color.Black);
                foreach (CellVisualLineElement element in line.Elements)
                    element.Attribute = _userAttribute.Value;
            }

            // One role per document line: the trimmed line is a role header → switch the
            // block; anything else (body, blanks, attachments) inherits the block's role.
            private static string[] ComputeRoles(string text)
            {
                var roles = new List<string>();
                var isUser = false;
                var start = 0;
                for (var i = 0; i <= text.Length; i++)
                {
                    if (i < text.Length && text[i] != '\n') continue;
                    var line = text.AsSpan(start, i - start).TrimEnd('\r').Trim();
                    start = i + 1;
                    if (line.SequenceEqual(Dictionary.HistoryYou)) isUser = true;
                    else if (line.SequenceEqual(Dictionary.HistoryAgent)
                        || line.SequenceEqual(Dictionary.HistoryError)
                        || line.SequenceEqual("·"))
                        isUser = false;
                    roles.Add(isUser ? UserRole : "");
                }
                return roles.ToArray();
            }
        }

        // Puppet mode (PrintScreen): dumps the current screen to a timestamped file
        // next to the executable so an agent tester can read it later.
        private void PuppetCapture()
        {
            try
            {
                var dir = Path.Combine(AppContext.BaseDirectory, "tui-screenshots");
                Directory.CreateDirectory(dir);
                var file = Path.Combine(dir, $"puppet-{DateTime.Now:yyyyMMdd-HHmmss}.txt");
                File.WriteAllText(file, PuppetMode.ANSI_Tui_Capture());
                _statusNote = $"Puppet capture → {file}";
                Log.LogStep($"TUI PuppetCapture (PrintScreen) → {file}", monitor: true);
            }
            catch (Exception ex) { _statusNote = $"Puppet capture failed: {ex.Message}"; }
            UpdateStatusUi();
        }

        // ── Commands ──
        private void RunCommandLine(string text)
        {
            var rest = text[1..].TrimStart();
            var sp = rest.IndexOf(' ');
            var name = sp < 0 ? rest : rest[..sp];
            var args = sp < 0 ? "" : rest[(sp + 1)..].Trim();
            if (name.Length == 0)
            {
                ShowCommandMenu("");
                return;
            }
            var cmd = Commands.FirstOrDefault(c =>
                string.Equals(c.Name, name, StringComparison.OrdinalIgnoreCase) ||
                (c.Aliases?.Any(a => a.Equals("/" + name, StringComparison.OrdinalIgnoreCase)) ?? false));
            if (cmd == null)
            {
                AddNote(string.Format(Dictionary.NoteUnknownCommand, name));
                return;
            }
            RunCommand(cmd, args);
        }

        private void RunCommand(CliCommand cmd, string args) => _ = RunCommandAsync(cmd, args);

        // Menu items route through the same guarded path as the slash commands, so
        // every command has identical error handling and state refresh.
        private void RunCommandByName(string name, string args)
        {
            Log.LogStep($"TUI menu command: {name} {args}".TrimEnd(), monitor: true);
            var cmd = Commands.FirstOrDefault(c => c.Name == name);
            if (cmd != null) _ = RunCommandAsync(cmd, args);
        }

        private async Task RunCommandAsync(CliCommand cmd, string args)
        {
            Log.LogStep($"TUI running command: {cmd.Name} {(args.Length > 0 ? args : "")}".TrimEnd());
            try
            {
                await cmd.Run(this, args);
                Log.LogStep($"TUI command completed: {cmd.Name}");
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI command FAILED: {cmd.Name}: {ex.Message}");
                AddNote(string.Format(Dictionary.NoteCommandFailed, cmd.Name, ex.Message));
            }
            await RefreshSessionStateAsync();
            UpdateStatusUi();
        }

        private Task CrashReportAsync()
        {
            CrashReporter.Toggle();
            AddNote(CrashReporter.Enabled ? Dictionary.NoteCrashReportEnabled : Dictionary.NoteCrashReportDisabled);
            return Task.CompletedTask;
        }

        private Task ExitAsync()
        {
            Ui(RequestExit);
            return Task.CompletedTask;
        }

        private void RequestExit()
        {
            Log.LogStep("TUI exit requested", monitor: true);
            _app.RequestStop(_mainWindow);
        }

        private async Task HealthAsync()
        {
            var sw = Stopwatch.StartNew();
            try
            {
                using var resp = await _http.GetAsync("/health").WaitAsync(TimeSpan.FromSeconds(5));
                sw.Stop();
                AddNote(resp.IsSuccessStatusCode
                    ? string.Format(Dictionary.StatusServerHealthy, sw.ElapsedMilliseconds)
                    : string.Format(Dictionary.StatusServerHttp, (int)resp.StatusCode));
                _connected = resp.IsSuccessStatusCode;
                UpdateStatusUi();
            }
            catch (Exception ex)
            {
                AddNote(string.Format(Dictionary.StatusServerUnreachable, ex.Message));
                _connected = false;
                UpdateStatusUi();
            }
        }

        private async Task SipAsync(string args)
        {
            // No arguments → the interactive SIP panel (menu Impostazioni → SIP): live
            // status plus the editable settings that used to require memorising /sip
            // subcommands. The read-only status page stays available as /sip status.
            if (string.IsNullOrWhiteSpace(args))
            {
                await ShowSipDialogAsync();
                return;
            }
            var parts = args.Trim().Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
            var sub = parts.Length == 0 ? "status" : parts[0].ToLowerInvariant();
            var arg = parts.Length > 1 ? parts[1].Trim() : "";

            switch (sub)
            {
                case "call":
                {
                    if (string.IsNullOrEmpty(arg)) { AddNote(Dictionary.NoteSipUsage); return; }
                    AddNote(string.Format(Dictionary.NoteSipCalling, arg));
                    var body = JsonSerializer.Serialize(new { uri = arg }, JsonOpts);
                    using var resp = await _http.PostAsync("/v1/sip/call", new StringContent(body, Encoding.UTF8, "application/json"));
                    var text = await ReadErrorAsync(resp);
                    if (resp.StatusCode == System.Net.HttpStatusCode.OK)
                        AddNote(string.Format(Dictionary.NoteSipCallOk, arg));
                    else if (resp.StatusCode == System.Net.HttpStatusCode.NotFound)
                        AddNote(Dictionary.NoteSipUnavailableCall);
                    else
                        AddNote(string.Format(Dictionary.NoteSipCallFailed, arg, text));
                    break;
                }
                case "hangup":
                {
                    using var resp = await _http.PostAsync("/v1/sip/hangup", new StringContent("{}", Encoding.UTF8, "application/json"));
                    if (resp.IsSuccessStatusCode) AddNote(Dictionary.NoteSipHangup);
                    else AddNote(string.Format(Dictionary.NoteSipCallFailed, "hangup", await ReadErrorAsync(resp)));
                    break;
                }
                case "answer":
                {
                    var on = !arg.Equals("off", StringComparison.OrdinalIgnoreCase);
                    var body = JsonSerializer.Serialize(new { on }, JsonOpts);
                    using var resp = await _http.PostAsync("/v1/sip/answer", new StringContent(body, Encoding.UTF8, "application/json"));
                    if (resp.IsSuccessStatusCode)
                        AddNote(string.Format(Dictionary.NoteSipAnswerChanged, on ? Dictionary.On : Dictionary.Off));
                    else
                        AddNote(string.Format(Dictionary.NoteSipCallFailed, "answer", await ReadErrorAsync(resp)));
                    break;
                }
                case "config":
                {
                    var rest = arg.Length == 0 ? "" : arg;
                    var parts2 = rest.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
                    var sub2 = parts2.Length == 0 ? "" : parts2[0].ToLowerInvariant();

                    if (sub2 == "set")
                    {
                        var kv = parts2.Length > 1 ? parts2[1].Trim() : "";
                        var kvParts = kv.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
                        if (kvParts.Length == 0) { AddNote(Dictionary.NoteSipConfigUsage); return; }
                        var key = kvParts[0];
                        var value = kvParts.Length > 1 ? kvParts[1] : "";
                        var body = JsonSerializer.Serialize(new { key, value }, JsonOpts);
                        using var resp = await _http.PostAsync("/v1/sip/config", new StringContent(body, Encoding.UTF8, "application/json"));
                        if (resp.IsSuccessStatusCode)
                        {
                            using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                            var msg = GetStr(doc.RootElement, "message") ?? "";
                            AddNote(msg);
                            if (GetBool(doc.RootElement, "restart_required"))
                                AddNote(Dictionary.NoteSipConfigRestart);
                        }
                        else
                        {
                            AddNote(string.Format(Dictionary.NoteSipConfigFailed, await ReadErrorAsync(resp)));
                        }
                    }
                    else if (sub2 == "reload")
                    {
                        using var resp = await _http.PostAsync("/v1/sip/config/reload", new StringContent("{}", Encoding.UTF8, "application/json"));
                        if (resp.IsSuccessStatusCode)
                        {
                            using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                            var msg = GetStr(doc.RootElement, "message") ?? "";
                            AddNote(msg);
                            if (GetBool(doc.RootElement, "restart_required"))
                                AddNote(Dictionary.NoteSipConfigRestart);
                        }
                        else
                        {
                            AddNote(string.Format(Dictionary.NoteSipConfigFailed, await ReadErrorAsync(resp)));
                        }
                    }
                    else if (sub2.Length > 0)
                    {
                        AddNote(Dictionary.NoteSipConfigUsage);
                    }
                    else
                    {
                        using var resp = await _http.GetAsync("/v1/sip/config").WaitAsync(TimeSpan.FromSeconds(5));
                        if (!resp.IsSuccessStatusCode) { AddNote(string.Format(Dictionary.NoteSipUnavailable, (int)resp.StatusCode)); return; }
                        using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                        var sip = doc.RootElement.GetProperty("sip");
                        var allowed = sip.TryGetProperty("allowed_callers", out var ac) && ac.ValueKind == JsonValueKind.Array
                            ? string.Join(", ", ac.EnumerateArray().Select(x => x.GetString()))
                            : "";
                        var lines = new List<string>
                        {
                            $"{("enabled").PadRight(18)}{(GetBool(sip, "enabled") ? Dictionary.On : Dictionary.Off)}",
                            $"{("listen_port").PadRight(18)}{GetInt(sip, "listen_port")}",
                            $"{("registrar").PadRight(18)}{ValueOr(GetStr(sip, "registrar"), "(empty)")}",
                            $"{("username").PadRight(18)}{ValueOr(GetStr(sip, "username"), "(empty)")}",
                            $"{("password").PadRight(18)}{(GetBool(sip, "password_set") ? "set" : "not set")}",
                            $"{("answer_mode").PadRight(18)}{GetStr(sip, "answer_mode") ?? ""}",
                            $"{("pin").PadRight(18)}{(GetBool(sip, "pin_set") ? "set" : "not set")}",
                            $"{("max_pin_attempts").PadRight(18)}{GetInt(sip, "max_pin_attempts")}",
                            $"{("lockout_hours").PadRight(18)}{GetInt(sip, "lockout_hours")}",
                            $"{("register_expiry").PadRight(18)}{GetInt(sip, "register_expiry")}",
                            $"{("pin_timeout_seconds").PadRight(18)}{GetInt(sip, "pin_timeout_seconds")}",
                            $"{("indicator_delay_seconds").PadRight(18)}{GetInt(sip, "indicator_delay_seconds")}",
                            $"{("allowed_callers").PadRight(18)}{ValueOr(allowed, "(none)")}",
                            $"{("agent").PadRight(18)}{GetStr(sip, "agent") ?? ""}",
                            $"{("lang").PadRight(18)}{ValueOr(GetStr(sip, "lang"), "(system)")}",
                            $"{("stt_exe_path").PadRight(18)}{ValueOr(GetStr(sip, "stt_exe_path"), "(default)")}",
                            $"{("stt_model").PadRight(18)}{ValueOr(GetStr(sip, "stt_model"), "(small)")}",
                            $"{("stt_quant").PadRight(18)}{ValueOr(GetStr(sip, "stt_quant"), "(fp16)")}",
                            $"{("stt_device").PadRight(18)}{ValueOr(GetStr(sip, "stt_device"), "(auto)")}",
                            $"{("rtp_port_range").PadRight(18)}{ValueOr(GetStr(sip, "rtp_port_range"), "(default)")}",
                        };
                        await ShowPageUiAsync(Dictionary.PageSipConfig, lines);
                    }
                    break;
                }
                default:   // status
                {
                    using var resp = await _http.GetAsync("/v1/sip/status").WaitAsync(TimeSpan.FromSeconds(5));
                    if (!resp.IsSuccessStatusCode) { AddNote(string.Format(Dictionary.NoteSipUnavailable, (int)resp.StatusCode)); return; }
                    using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                    var sip = doc.RootElement.GetProperty("sip");
                    var lines = new List<string>
                    {
                        $"{Dictionary.StatusSip.PadRight(18)}{(GetBool(sip, "enabled") ? Dictionary.On : Dictionary.Off)}",
                        $"{Dictionary.StatusSipListen.PadRight(18)}{(GetBool(sip, "listening") ? Dictionary.Available : Dictionary.Unavailable)}",
                        $"{Dictionary.StatusSipAnswer.PadRight(18)}{(GetBool(sip, "answer_enabled") ? Dictionary.On : Dictionary.Off)} · mode: {GetStr(sip, "answer_mode") ?? ""}",
                        $"{Dictionary.StatusSipRegistered.PadRight(18)}{(GetBool(sip, "registered") ? Dictionary.On : Dictionary.Off)}",
                        $"{Dictionary.StatusSipCall.PadRight(18)}{PhaseLabel(GetStr(sip, "phase") ?? "idle")}{(GetStr(sip, "remote") is { } r && r.Length > 0 ? "  " + r : "")}",
                        $"{Dictionary.StatusSipPin.PadRight(18)}{GetInt(sip, "pin_remaining")}",
                        $"{Dictionary.StatusSipLocked.PadRight(18)}{GetStr(sip, "locked_until") ?? Dictionary.None}",
                        $"{Dictionary.StatusSipStt.PadRight(18)}{(GetBool(sip, "stt_available") ? Dictionary.Available : Dictionary.Unavailable)} · tts {(GetBool(sip, "tts_available") ? Dictionary.Available : Dictionary.Unavailable)}",
                    };
                    await ShowPageUiAsync(Dictionary.PageSipStatus, lines);
                    break;
                }
            }
            await RefreshSipStatusAsync();
        }

        private async Task ShowSipDialogAsync()
        {
            // Read the current (masked) SIP config so the panel opens on the real values.
            var cfg = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
            try
            {
                using var resp = await _http.GetAsync("/v1/sip/config").WaitAsync(TimeSpan.FromSeconds(5));
                if (!resp.IsSuccessStatusCode) { AddNote(string.Format(Dictionary.NoteSipUnavailable, (int)resp.StatusCode)); return; }
                using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                var sip = doc.RootElement.GetProperty("sip");
                cfg["enabled"] = GetBool(sip, "enabled") ? "true" : "false";
                cfg["listen_port"] = GetInt(sip, "listen_port").ToString();
                cfg["registrar"] = GetStr(sip, "registrar") ?? "";
                cfg["username"] = GetStr(sip, "username") ?? "";
                cfg["password_set"] = GetBool(sip, "password_set") ? "1" : "";
                cfg["answer_mode"] = GetStr(sip, "answer_mode") ?? "pin";
                cfg["pin_set"] = GetBool(sip, "pin_set") ? "1" : "";
                cfg["allowed_callers"] = sip.TryGetProperty("allowed_callers", out var ac) && ac.ValueKind == JsonValueKind.Array
                    ? string.Join(", ", ac.EnumerateArray().Select(x => x.GetString())) : "";
                cfg["agent"] = GetStr(sip, "agent") ?? "";
                cfg["lang"] = GetStr(sip, "lang") ?? "";
            }
            catch (Exception ex) { AddNote(string.Format(Dictionary.NoteSipConfigFailed, ex.Message)); return; }

            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() => { try { ShowSipDialog(cfg); tcs.SetResult(); } catch (Exception ex) { tcs.SetException(ex); } });
            await tcs.Task;
        }

        // Interactive SIP settings panel: the editable fields (enabled, port, registrar,
        // credentials, answer mode, PIN, allow-list, agent, language) with one Save that
        // persists each changed key through the bridge, plus the live call actions
        // (answer toggle, place a call, hang up). Secrets are write-only here: a blank
        // password/PIN leaves the stored value untouched, a typed one replaces it.
        private void ShowSipDialog(Dictionary<string, string> cfg)
        {
            Log.LogStep("TUI SIP panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.SipPanelTitle,
                Width = Dim.Percent(78),
                Height = Dim.Percent(92),
                SchemeName = "Dark",
            };

            var status = new Label { Text = "", X = 1, Y = 0, Width = Dim.Fill() - 2, Height = 2, SchemeName = "Hint" };
            void RefreshStatus()
            {
                var en = SipBridge.IsEnabled ? Dictionary.On : Dictionary.Off;
                status.Text = string.Format(Dictionary.SipPanelStatus, en, _sipState.Length > 0 ? _sipState : Dictionary.SipPhaseIdle);
            }
            RefreshStatus();

            var enabled = new CheckBox
            {
                Text = Dictionary.SetupSipEnabled,
                Value = cfg.GetValueOrDefault("enabled") == "true" ? CheckState.Checked : CheckState.UnChecked,
                X = 1, Y = 2,
            };
            var listenPort = AddField(dlg, Dictionary.SetupSipListenPort, cfg.GetValueOrDefault("listen_port"), 3);
            var registrar = AddField(dlg, Dictionary.SetupSipRegistrar, cfg.GetValueOrDefault("registrar"), 4);
            var username = AddField(dlg, Dictionary.SetupSipUsername, cfg.GetValueOrDefault("username"), 5);
            var password = AddField(dlg, Dictionary.SetupSipPassword, "", 6, secret: true);
            var passHint = new Label
            {
                Text = cfg.GetValueOrDefault("password_set") == "1" ? Dictionary.SetupSipSecretSet : "",
                X = 66, Y = 6, Width = 14, SchemeName = "Hint",
            };
            var answerMode = new DropDownList
            {
                ReadOnly = true, X = 20, Y = 7, Width = 20,
                Source = new ListWrapper<string>(new ObservableCollection<string>(new[] { "pin", "allowlist", "none" })),
                Text = cfg.GetValueOrDefault("answer_mode", "pin"),
            };
            dlg.Add(new Label { Text = Dictionary.SetupSipAnswerMode, X = 1, Y = 7, Width = 18 }, answerMode);
            var pin = AddField(dlg, Dictionary.SetupSipPin, "", 8, secret: true);
            var pinHint = new Label
            {
                Text = cfg.GetValueOrDefault("pin_set") == "1" ? Dictionary.SetupSipSecretSet : "",
                X = 66, Y = 8, Width = 14, SchemeName = "Hint",
            };
            var allowed = AddField(dlg, Dictionary.SetupSipAllowed, cfg.GetValueOrDefault("allowed_callers"), 9);
            var agent = AddField(dlg, Dictionary.SetupSipAgent, cfg.GetValueOrDefault("agent"), 10);
            var lang = AddField(dlg, Dictionary.SetupSipLang, cfg.GetValueOrDefault("lang"), 11);
            var saveErr = new Label { Text = "", X = 1, Y = 12, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            dlg.Add(status, enabled, passHint, pinHint, saveErr);

            var save = new Button { Text = Dictionary.SetupSave, X = 1, Y = 14 };
            save.Accepted += async (_, _) =>
            {
                saveErr.Text = "";
                // Each field is posted only when it actually changed (secrets only when a
                // new value was typed), so saving never clobbers an untouched secret.
                var posts = new List<(string Key, string Value)>
                {
                    ("Enabled", enabled.Value == CheckState.Checked ? "true" : "false"),
                    ("ListenPort", (listenPort.Text ?? "").Trim()),
                    ("Registrar", (registrar.Text ?? "").Trim()),
                    ("Username", (username.Text ?? "").Trim()),
                    ("AnswerMode", (answerMode.Text ?? "").Trim()),
                    ("AllowedCallers", (allowed.Text ?? "").Trim()),
                    ("Agent", (agent.Text ?? "").Trim()),
                    ("Lang", (lang.Text ?? "").Trim()),
                };
                if (!string.IsNullOrWhiteSpace(password.Text)) posts.Add(("Password", password.Text.Trim()));
                if (!string.IsNullOrWhiteSpace(pin.Text)) posts.Add(("Pin", pin.Text.Trim()));

                bool restart = false;
                foreach (var (key, value) in posts)
                {
                    var (error, restartRequired, _) = await SipBridge.SetConfigAsync(key, value);
                    if (error != null) { saveErr.Text = string.Format(Dictionary.NoteSipConfigFailed, $"{key}: {error}"); return; }
                    restart |= restartRequired;
                }
                password.Text = ""; pin.Text = "";
                passHint.Text = pinHint.Text = "";
                RefreshStatus();
                _ = RefreshSipStatusAsync();
                AddNote(restart ? Dictionary.NoteSipConfigRestart : Dictionary.SetupSipSaved);
                Log.LogStep($"TUI SIP panel saved (restart={restart})", monitor: true);
            };
            var reload = new Button { Text = Dictionary.SetupSipReload, X = Pos.Right(save) + 1, Y = 14 };
            reload.Accepted += async (_, _) =>
            {
                var (error, restart, message) = await SipBridge.ReloadConfigAsync();
                AddNote(error ?? message);
                RefreshStatus();
                _ = RefreshSipStatusAsync();
            };
            var answerBtn = new Button { Text = Dictionary.SetupSipAnswerToggle, X = Pos.Right(reload) + 1, Y = 14 };
            answerBtn.Accepted += async (_, _) =>
            {
                var on = !SipBridge.IsAnswerEnabled;
                var body = JsonSerializer.Serialize(new { on }, JsonOpts);
                using var resp = await _http.PostAsync("/v1/sip/answer", new StringContent(body, Encoding.UTF8, "application/json"));
                AddNote(resp.IsSuccessStatusCode
                    ? string.Format(Dictionary.NoteSipAnswerChanged, on ? Dictionary.On : Dictionary.Off)
                    : string.Format(Dictionary.NoteSipCallFailed, "answer", await ReadErrorAsync(resp)));
                RefreshStatus();
            };
            var callBtn = new Button { Text = Dictionary.SetupSipCall, X = 1, Y = 16 };
            callBtn.Accepted += async (_, _) =>
            {
                var uri = await PromptOnUiThreadAsync(Dictionary.SetupSipCall, "");
                if (string.IsNullOrWhiteSpace(uri)) return;
                var body = JsonSerializer.Serialize(new { uri }, JsonOpts);
                using var resp = await _http.PostAsync("/v1/sip/call", new StringContent(body, Encoding.UTF8, "application/json"));
                AddNote(resp.IsSuccessStatusCode
                    ? string.Format(Dictionary.NoteSipCallOk, uri)
                    : string.Format(Dictionary.NoteSipCallFailed, uri, await ReadErrorAsync(resp)));
                RefreshStatus();
            };
            var hangupBtn = new Button { Text = Dictionary.SetupSipHangup, X = Pos.Right(callBtn) + 1, Y = 16 };
            hangupBtn.Accepted += async (_, _) =>
            {
                using var resp = await _http.PostAsync("/v1/sip/hangup", new StringContent("{}", Encoding.UTF8, "application/json"));
                AddNote(resp.IsSuccessStatusCode ? Dictionary.NoteSipHangup : Dictionary.NoteSipUnavailableCall);
                RefreshStatus();
            };
            dlg.Add(save, reload, answerBtn, callBtn, hangupBtn);

            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI SIP panel closed"); _app.RequestStop(dlg); };
            dlg.AddButton(close);
            dlg.Initialized += (_, _) => enabled.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI SIP panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        private async Task TelegramAsync(string args)
        {
            // No arguments → the interactive panel (menu Tools → Telegram): live
            // status plus login-code / allow / disallow / config / reload / toggle.
            if (string.IsNullOrWhiteSpace(args))
            {
                await ShowTelegramDialogAsync();
                return;
            }
            var parts = args.Trim().Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
            var sub = parts.Length == 0 ? "status" : parts[0].ToLowerInvariant();
            var arg = parts.Length > 1 ? parts[1].Trim() : "";

            switch (sub)
            {
                case "login-code":
                {
                    if (string.IsNullOrEmpty(arg)) { AddNote(Dictionary.NoteTelegramLoginPending); return; }
                    var error = TelegramBridge.SubmitLoginInput(arg);
                    if (error == null)
                        AddNote(Dictionary.NoteTelegramLoginCodeSubmitted);
                    else
                        AddNote(string.Format(Dictionary.NoteTelegramLoginCodeFailed, error));
                    break;
                }
                case "allow":
                case "disallow":
                {
                    if (string.IsNullOrEmpty(arg)) { AddNote(Dictionary.NoteTelegramUsage); return; }
                    var (error, message) = sub == "allow"
                        ? TelegramBridge.AddAllowedUser(arg)
                        : TelegramBridge.RemoveAllowedUser(arg);
                    if (error == null)
                        AddNote(message);
                    else
                        AddNote(string.Format(Dictionary.NoteTelegramAllowFailed, error));
                    break;
                }
                case "config":
                {
                    var rest = arg.Length == 0 ? "" : arg;
                    var parts2 = rest.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
                    var sub2 = parts2.Length == 0 ? "" : parts2[0].ToLowerInvariant();

                    if (sub2 == "set")
                    {
                        var kv = parts2.Length > 1 ? parts2[1].Trim() : "";
                        var kvParts = kv.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
                        if (kvParts.Length == 0) { AddNote(Dictionary.NoteTelegramConfigUsage); return; }
                        var (error, restart, message) = await TelegramBridge.SetConfigAsync(kvParts[0], kvParts.Length > 1 ? kvParts[1] : "");
                        if (error == null)
                        {
                            AddNote(message);
                            if (restart) AddNote(Dictionary.NoteTelegramConfigRestart);
                        }
                        else
                        {
                            AddNote(string.Format(Dictionary.NoteTelegramConfigFailed, error));
                        }
                    }
                    else if (sub2 == "reload")
                    {
                        var (error, restart, message) = await TelegramBridge.ReloadConfigAsync();
                        if (error == null)
                        {
                            AddNote(message);
                            if (restart) AddNote(Dictionary.NoteTelegramConfigRestart);
                        }
                        else
                        {
                            AddNote(string.Format(Dictionary.NoteTelegramConfigFailed, error));
                        }
                    }
                    else if (sub2.Length > 0)
                    {
                        AddNote(Dictionary.NoteTelegramConfigUsage);
                    }
                    else
                    {
                        var c = TelegramBridge.ConfigSnapshot;
                        var allowed = string.Join(", ", c.AllowedUsers);
                        var lines = new List<string>
                        {
                            $"{("enabled").PadRight(18)}{(c.Enabled ? Dictionary.On : Dictionary.Off)}",
                            $"{("phone_number").PadRight(18)}{ValueOr(c.PhoneNumber, "(empty)")}",
                            $"{("session_path").PadRight(18)}{ValueOr(c.SessionPath, "(default)")}",
                            $"{("allowed_users").PadRight(18)}{ValueOr(allowed, "(all private chats)")}",
                            $"{("agent").PadRight(18)}{c.Agent}",
                        };
                        await ShowPageUiAsync("Telegram config", lines);
                    }
                    break;
                }
                default:   // status
                {
                    var s = TelegramBridge.Status;
                    var user = s.User == null ? Dictionary.None : $"{s.User.Name} (@{s.User.Username}, id {s.User.Id})";
                    var lines = new List<string>
                    {
                        $"{("enabled").PadRight(18)}{(s.Enabled ? Dictionary.On : Dictionary.Off)}",
                        $"{("phase").PadRight(18)}{TelegramPhaseLabel(TelegramBridge.Phase)}",
                        $"{("user").PadRight(18)}{user}",
                        $"{("allowed_users").PadRight(18)}{(s.AllowedUsers is { Count: > 0 } au ? string.Join(", ", au) : "(all)")}",
                        $"{("agent").PadRight(18)}{s.Agent}",
                    };
                    if (s.Error is { Length: > 0 } err)
                        lines.Add($"{"error".PadRight(18)}{err}");
                    await ShowPageUiAsync("Telegram status", lines);
                    break;
                }
            }
            await RefreshTelegramStatusAsync();
        }

        private Task ShowTelegramDialogAsync()
        {
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { ShowTelegramDialog(); tcs.SetResult(); }
                catch (Exception ex) { tcs.SetException(ex); }
            });
            return tcs.Task;
        }

        // Interactive Telegram panel: live status plus the actions that used to require
        // memorising /telegram subcommands (login code, allow/disallow, config, ...).
        private void ShowTelegramDialog()
        {
            Log.LogStep("TUI /telegram panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.DlgTelegramTitle,
                Width = Dim.Percent(80),
                Height = Dim.Percent(70),   // 62% was too short once the action buttons
                                            // spanned two rows (2+2): rows 10/12/14 overflowed
                                            // the drawn area and the last buttons were invisible.
                SchemeName = "Dark",
            };

            var status = new Label
            {
                X = 1, Y = 0, Width = Dim.Fill() - 2, Height = 4,
            };
            void RefreshStatus()
            {
                var s = TelegramBridge.Status;
                var user = s.User == null ? Dictionary.None : $"{s.User.Name} (@{s.User.Username}, id {s.User.Id})";
                var allowed = s.AllowedUsers is { Count: > 0 } au ? string.Join(", ", au) : "(all)";
                var err = s.Error is { Length: > 0 } e ? " · " + e : "";
                status.Text = string.Join("\n",
                    $"enabled: {(s.Enabled ? Dictionary.On : Dictionary.Off)} · phase: {TelegramPhaseLabel(TelegramBridge.Phase)}",
                    $"user: {user}",
                    $"allowed: {allowed}",
                    $"agent: {s.Agent}{err}");
            }
            RefreshStatus();

            var hint = new Label
            {
                Text = Dictionary.DlgTelegramHint,
                X = 1, Y = 4, Width = Dim.Fill() - 2,
                SchemeName = "Hint",
            };

            // First login / 2FA: verification code row.
            var codeLabel = new Label { Text = Dictionary.DlgTelegramLoginLabel, X = 1, Y = 6, Width = 30 };
            var codeField = new TextField { X = 32, Y = 6, Width = Dim.Fill() - 34 };
            var sendBtn = new Button { Text = Dictionary.DlgTelegramSend, X = 1, Y = 8 };
            void SubmitLoginCode(string code)
            {
                if (string.IsNullOrWhiteSpace(code)) return;
                Log.LogStep("TUI /telegram: invio codice di verifica", monitor: true);
                var error = TelegramBridge.SubmitLoginInput(code.Trim());
                if (error == null) AddNote(Dictionary.NoteTelegramLoginCodeSubmitted);
                else AddNote(string.Format(Dictionary.NoteTelegramLoginCodeFailed, error));
                codeField.Text = "";
                RefreshStatus();
                _ = RefreshTelegramStatusAsync();
            }
            sendBtn.Accepted += (_, _) => SubmitLoginCode(codeField.Text ?? "");
            codeField.KeyDown += (_, key) =>
            {
                if (key == Key.Enter) { key.Handled = true; SubmitLoginCode(codeField.Text ?? ""); }
            };

            // Buttons lay out SEQUENTIALLY (Pos.Right) so the auto-width text can never
            // overlap the next button — fixed X coordinates broke once the localized
            // labels grew longer than the gaps (seen live: "Consenti utente…" drawn over
            // "Blocca utente…"). The four action buttons span TWO rows (2+2) because a
            // single row (~89 cols with the Italian labels) overflows the 80%-width panel.
            var allowBtn = new Button { Text = Dictionary.DlgTelegramAllow, X = 1, Y = 10 };
            var disallowBtn = new Button { Text = Dictionary.DlgTelegramDisallow, X = Pos.Right(allowBtn) + 1, Y = 10 };
            var configBtn = new Button { Text = Dictionary.DlgTelegramConfig, X = 1, Y = 12 };
            var reloadBtn = new Button { Text = Dictionary.DlgTelegramReload, X = Pos.Right(configBtn) + 1, Y = 12 };
            var toggleBtn = new Button { Text = Dictionary.DlgTelegramToggleEnable, X = 1, Y = 14 };

            allowBtn.Accepted += async (_, _) =>
            {
                Log.LogStep("TUI /telegram: Consenti utente", monitor: true);
                var who = await PromptOnUiThreadAsync(Dictionary.DlgTelegramAllow, "");
                if (who != null)
                {
                    var (error, message) = TelegramBridge.AddAllowedUser(who);
                    if (error == null) AddNote(message);
                    else AddNote(string.Format(Dictionary.NoteTelegramAllowFailed, error));
                    RefreshStatus();
                    _ = RefreshTelegramStatusAsync();
                }
                codeField.SetFocus();   // the nested prompt refocused the main input — bring focus back into the panel
            };
            disallowBtn.Accepted += async (_, _) =>
            {
                Log.LogStep("TUI /telegram: Blocca utente", monitor: true);
                var who = await PromptOnUiThreadAsync(Dictionary.DlgTelegramDisallow, "");
                if (who != null)
                {
                    var (error, message) = TelegramBridge.RemoveAllowedUser(who);
                    if (error == null) AddNote(message);
                    else AddNote(string.Format(Dictionary.NoteTelegramAllowFailed, error));
                    RefreshStatus();
                    _ = RefreshTelegramStatusAsync();
                }
                codeField.SetFocus();   // the nested prompt refocused the main input — bring focus back into the panel
            };
            configBtn.Accepted += (_, _) => { Log.LogStep("TUI /telegram: Mostra configurazione"); RunCommandByName("telegram", "config"); };
            reloadBtn.Accepted += (_, _) => { Log.LogStep("TUI /telegram: Ricarica configurazione", monitor: true); RunCommandByName("telegram", "config reload"); };
            toggleBtn.Accepted += async (_, _) =>
            {
                Log.LogStep("TUI /telegram: toggle abilitazione", monitor: true);
                var (error, restart, message) = await TelegramBridge.SetConfigAsync("Enabled", TelegramBridge.IsEnabled ? "false" : "true");
                if (error == null)
                {
                    AddNote(message);
                    if (restart) AddNote(Dictionary.NoteTelegramConfigRestart);
                }
                else
                {
                    AddNote(string.Format(Dictionary.NoteTelegramConfigFailed, error));
                }
                RefreshStatus();
                _ = RefreshTelegramStatusAsync();
            };

            dlg.Add(status, hint, codeLabel, codeField, sendBtn, allowBtn, disallowBtn, configBtn, reloadBtn, toggleBtn);
            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI /telegram panel closed"); _app.RequestStop(dlg); };
            dlg.AddButton(close);
            dlg.Initialized += (_, _) => codeField.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI /telegram panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        // Modal single-field prompt (e.g. "allow user"); Enter/OK returns the trimmed
        // value, Esc/Cancel returns null.
        private string? RunPromptDialog(string title, string label)
        {
            var dlg = new Dialog
            {
                Title = title,
                Width = Dim.Percent(60),
                Height = 9,
                SchemeName = "Dark",
            };
            if (label.Length > 0)
                dlg.Add(new Label { Text = label, X = 1, Y = 0, Width = Dim.Fill() - 2 });
            var field = new TextField { X = 1, Y = 1, Width = Dim.Fill() - 2 };
            var hint = new Label
            {
                Text = Dictionary.DlgPromptHint,
                X = 1, Y = 3, Width = Dim.Fill() - 2,
                SchemeName = "Hint",
            };
            string? result = null;
            field.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    result = (field.Text ?? "").Trim();
                    _app.RequestStop(dlg);
                }
            };
            var ok = new Button { Text = Dictionary.Ok, IsDefault = true };
            ok.Accepted += (_, _) => { result = (field.Text ?? "").Trim(); _app.RequestStop(dlg); };
            var cancel = new Button { Text = Dictionary.Cancel };
            cancel.Accepted += (_, _) => _app.RequestStop(dlg);
            dlg.Add(field, hint);
            // AddButton makes the LAST button the Enter default: Cancel first, OK last so
            // Enter confirms (same convention as the provider edit dialog).
            dlg.AddButton(cancel);
            dlg.AddButton(ok);
            dlg.Initialized += (_, _) => field.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            return string.IsNullOrEmpty(result) ? null : result;
        }

        private Task<string?> PromptOnUiThreadAsync(string title, string label)
        {
            var tcs = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { tcs.TrySetResult(RunPromptDialog(title, label)); }
                catch (Exception ex) { tcs.TrySetException(ex); }
            });
            return tcs.Task;
        }

        private async Task SwitchModelAsync(string args)
        {
            string name = args.Trim();
            if (string.IsNullOrWhiteSpace(name))
            {
                List<(string Id, string Display)> providers;
                try
                {
                    using var resp = await _http.GetAsync("/v1/models").WaitAsync(TimeSpan.FromSeconds(8));
                    if (!resp.IsSuccessStatusCode) { AddNote(Dictionary.NoteCouldNotLoadProviders); return; }
                    using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                    providers = doc.RootElement.GetProperty("data").EnumerateArray()
                        .Where(x => GetStr(x, "owned_by") == "llm-provider")
                        .Select(x => (Id: GetStr(x, "id") ?? "",
                                      Display: $"{GetStr(x, "id")} — {GetStr(x, "model_name")} · ctx {GetInt(x, "context_window"):N0}"))
                        .ToList();
                }
                catch (Exception ex)
                {
                    AddNote(string.Format(Dictionary.NoteCouldNotLoadProvidersEx, ex.Message));
                    return;
                }
                if (providers.Count == 0) { AddNote(Dictionary.NoteNoProviders); return; }
                var pick = await PickProviderOnUiThreadAsync(Dictionary.PickSwitchProvider, providers);
                if (pick == null) return;   // Esc → cancel
                name = pick.Trim();
            }

            if (string.Equals(name, _provider, StringComparison.OrdinalIgnoreCase))
            {
                AddNote(string.Format(Dictionary.NoteAlreadyOn, name));
                return;
            }

            AddNote(string.Format(Dictionary.NoteSwitchingProvider, name));
            var body = JsonSerializer.Serialize(new { session_id = _sessionId, llm_provider = name }, JsonOpts);
            using var resp2 = await _http.PostAsync("/v1/control", new StringContent(body, Encoding.UTF8, "application/json"));
            if (resp2.IsSuccessStatusCode)
            {
                AddNote(string.Format(Dictionary.NoteProviderNow, name));
                // The switch is session-scoped by design (/model never touches the default
                // in the settings): refresh the session state so the status line and the
                // pickers reflect the provider actually in use right away.
                await RefreshSessionStateAsync();
            }
            else
            {
                AddNote(string.Format(Dictionary.NoteSwitchRefused, (int)resp2.StatusCode, await ReadErrorAsync(resp2)));
            }
        }

        // Asks the server to adopt the marked default provider for the current process: new
        // chat sessions start with it. Only the process-wide default changes — the session
        // currently open is NOT switched (that is /model's job).
        private async Task SetDefaultProviderAsync(string name)
        {
            try
            {
                var body = JsonSerializer.Serialize(new { set_default_provider = name }, JsonOpts);
                using var resp = await _http.PostAsync("/v1/control", new StringContent(body, Encoding.UTF8, "application/json"));
                if (!resp.IsSuccessStatusCode)
                    AddNote(string.Format(Dictionary.NoteSetDefaultFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
            }
            catch (Exception ex)
            {
                AddNote(string.Format(Dictionary.NoteSetDefaultFailed, ex.Message));
            }
        }

        private Task SwitchAgentAsync(string args)
        {
            if (string.IsNullOrWhiteSpace(args.Trim()))
                return ShowToolsDialogAsync();   // interactive checklist
            var name = args.Trim().ToLowerInvariant();
            if (!AgentTools.AllIds.Any(id => string.Equals(id, name, StringComparison.OrdinalIgnoreCase)))
            {
                AddNote(string.Format(Dictionary.NoteUnknownAgentSet, name,
                    string.Join(", ", AgentTools.AllIds)));
                return Task.CompletedTask;
            }
            ApplyPreset(name);
            return Task.CompletedTask;
        }

        // Applies an agent-set preset: the preset id becomes the chat `model` and any
        // custom tool combination is cleared (the preset wins).
        private void ApplyPreset(string id)
        {
            _agentSet = id;
            _customTools = null;
            AddNote(string.Format(Dictionary.NoteAgentSet, id));
            SaveAgentSelection();
            UpdateStatusUi();
        }

        // ── /tools selection persistence ──
        // The active agent-tool selection (the last preset id, or the custom combination
        // picked in the checklist) is saved to PersistentData\toolset.json on every change
        // and restored at startup — the settings menu choice must survive a TUI restart.
        // Format: {"agent_set": "default-agent", "tools": ["PodcastTool", ...]} — "tools"
        // present (non-empty) = the custom combination (overrides the preset); absent/empty
        // = the named preset resolves the tools.
        private void SaveAgentSelection()
        {
            try
            {
                var node = new JsonObject
                {
                    ["agent_set"] = _agentSet,
                    ["tools"] = _customTools is { Count: > 0 }
                        ? new JsonArray(_customTools.Select(t => JsonValue.Create(t)).ToArray())
                        : null,
                };
                Directory.CreateDirectory(Path.GetDirectoryName(AppConfig.ToolsetFile)!);
                File.WriteAllText(AppConfig.ToolsetFile,
                    node.ToJsonString(new JsonSerializerOptions { WriteIndented = true }));
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI /tools: cannot persist the tool selection ({ex.Message})");
            }
        }

        private void RestoreAgentSelection()
        {
            try
            {
                if (!File.Exists(AppConfig.ToolsetFile)) return;
                using var doc = JsonDocument.Parse(File.ReadAllText(AppConfig.ToolsetFile));
                var root = doc.RootElement;

                var marked = new List<string>();
                if (root.TryGetProperty("tools", out var tools) && tools.ValueKind == JsonValueKind.Array)
                    foreach (var t in tools.EnumerateArray())
                        if (t.ValueKind == JsonValueKind.String && t.GetString() is { Length: > 0 } name)
                            marked.Add(name);

                // A tool that is no longer loaded (plugin removed from Tools/) drops out of
                // the combination instead of lingering as a dead entry in every request.
                var loaded = AgentTools.Catalog().Select(c => c.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
                var restored = marked.Where(loaded.Contains).ToList();
                if (restored.Count > 0)
                {
                    _customTools = restored;
                    _agentSet = "default-agent";   // the `tools` field overrides the preset
                    Log.LogStep($"TUI /tools restored custom set: {string.Join(", ", restored)}", monitor: true);
                    return;
                }
                if (root.TryGetProperty("agent_set", out var preset) && preset.ValueKind == JsonValueKind.String
                    && preset.GetString() is { Length: > 0 } id
                    && AgentTools.AllIds.Any(p => string.Equals(p, id, StringComparison.OrdinalIgnoreCase)))
                {
                    _agentSet = id.ToLowerInvariant();
                    Log.LogStep($"TUI /tools restored preset: {_agentSet}", monitor: true);
                }
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI /tools: cannot restore the saved tool selection ({ex.Message})");
            }
        }

        private Task ShowToolsDialogAsync()
        {
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { ShowToolsDialog(); tcs.SetResult(); }
                catch (Exception ex) { tcs.SetException(ex); }
            });
            return tcs.Task;
        }

        // The /agent tool picker: an individual-tool checklist. Space toggles each row
        // independently; the marked tools become the custom combination (sent as `tools`).
        // Core tools are LOCKED: shown as a read-only line above the list (reflecting
        // tools.json), never toggleable — the custom combination always includes them.
        // The state is saved after the dialog closes by ANY means (Close button, Esc, ...).
        private void ShowToolsDialog()
        {
            Log.LogStep("TUI /agent tools dialog opened", monitor: true);
            var catalog = AgentTools.Catalog();
            var current = EffectiveTools();
            var dlg = new Dialog
            {
                Title = Dictionary.DlgToolsTitle,
                Width = Dim.Percent(80),
                Height = Dim.Percent(70),
                SchemeName = "Dark",
            };

            // The picker must never contradict the effective state: a core tool the config
            // disabled is not listed either (see docs-dev/ARCHITECTURE.md, "Agent sets & tool policy").
            var coreEnabled = AgentTools.CoreTools.Where(AgentTools.IsEnabled).ToArray();
            var toggleable = catalog.Where(c => !AgentTools.CoreTools.Contains(c.Name)).ToList();
            var coreLabel = new Label
            {
                Text = coreEnabled.Length > 0
                    ? string.Format(Dictionary.DlgToolsCore, string.Join(", ", coreEnabled))
                    : Dictionary.DlgToolsCoreNone,
                X = 1, Y = 1, Width = Dim.Fill() - 2,
            };

            var toolNames = toggleable.Select(c => c.Name).ToList();
            var source = new ListWrapper<string>(new ObservableCollection<string>(
                toggleable.Select(c => $"{c.Name} — {c.Description}")));
            var toolList = new ListView
            {
                X = 1, Y = 2, Width = Dim.Fill() - 2, Height = Dim.Fill() - 4,
                ShowMarks = true,
                MarkMultiple = true,   // independent checkboxes — SPACE toggles each row independently
                Source = source,
            };
            var hint = new Label
            {
                Text = Dictionary.DlgToolsHint,
                X = 1, Y = Pos.Bottom(toolList), Width = Dim.Fill() - 2,
            };
            dlg.Add(coreLabel, toolList, hint);

            // Reflect the currently active tools in the checklist (non-core rows only).
            for (int i = 0; i < toolNames.Count; i++)
                source.SetMark(i, current.Contains(toolNames[i], StringComparer.OrdinalIgnoreCase));

            // The Close button only closes the dialog — the checkbox state is saved below
            // right after Run returns, whatever path closed the dialog (button, Esc, ...).
            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => _app.RequestStop(dlg);
            dlg.AddButton(close);
            dlg.Initialized += (_, _) => toolList.SetFocus();
            _app.Run(dlg);

            // Save the checkbox state on ANY close path. The enabled core tools are always
            // included (locked, non-toggleable) — a custom combination can never drop them.
            var marked = new List<string>();
            for (int i = 0; i < toolNames.Count; i++)
                if (source.IsMarked(i)) marked.Add(toolNames[i]);
            foreach (var core in coreEnabled)
                if (!marked.Contains(core)) marked.Add(core);
            if (marked.Count > 0)
            {
                _agentSet = "default-agent";   // the `tools` field overrides it server-side
                _customTools = marked;
                AddNote(string.Format(Dictionary.NoteToolsApplied, string.Join(", ", marked.Select(ToolShortName))));
                Log.LogStep($"TUI /agent tools applied: {string.Join(", ", marked)}", monitor: true);
            }
            else
            {
                _customTools = null;
            }
            SaveAgentSelection();   // the selection must survive a restart (settings → tools)
            Log.LogStep("TUI /agent tools dialog closed");
            UpdateStatusUi();

            dlg.Dispose();
            _inputField?.SetFocus();
        }

        private async Task VoiceAsync(string lang)
        {
            if (!_voiceAvailable)
            {
                AddNote(string.Format(Dictionary.NoteVoiceUnavailable, string.IsNullOrEmpty(_voiceDetail) ? Dictionary.NoteVoiceDisabled : _voiceDetail));
                return;
            }
            var l = string.IsNullOrWhiteSpace(lang) ? SystemLang.Get() : lang.Trim();
            AddNote(Dictionary.NoteListening);
            SetBusy("listening", true);
            var body = JsonSerializer.Serialize(new { lang = l, timeout_seconds = 15 }, JsonOpts);
            try
            {
                using var resp = await _http.PostAsync("/v1/voice/listen", new StringContent(body, Encoding.UTF8, "application/json"));
                if (resp.IsSuccessStatusCode)
                {
                    using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                    var text = GetStr(doc.RootElement, "text") ?? "";
                    if (string.IsNullOrWhiteSpace(text)) { AddNote(Dictionary.NoteNoSpeech); return; }
                    Ui(() =>
                    {
                        if (_inputField == null) return;
                        _inputField.Text = text;
                        _inputPlaceholderActive = false;
                        _inputField.SchemeName = "Dark";
                        _inputField.CaretOffset = _inputField.Document?.TextLength ?? 0;
                    });
                    AddNote(string.Format(Dictionary.NoteDictated, text));
                }
                else
                {
                    var err = await ReadErrorAsync(resp);
                    AddNote(resp.StatusCode == System.Net.HttpStatusCode.RequestTimeout
                        ? Dictionary.NoteListeningTimeout
                        : string.Format(Dictionary.NoteVoiceFailedHttp, (int)resp.StatusCode, err));
                }
            }
            catch (Exception ex)
            {
                AddNote(string.Format(Dictionary.NoteVoiceFailed, ex.Message));
            }
            finally
            {
                SetBusy("listening", false);
            }
        }

        private async Task TtsAsync(string text)
        {
            if (!_ttsAvailable)
            {
                AddNote(string.Format(Dictionary.NoteTtsUnavailable, string.IsNullOrEmpty(_ttsDetail) ? Dictionary.NoteTtsDisabled : _ttsDetail));
                return;
            }
            if (string.IsNullOrWhiteSpace(text))
            {
                var last = _history.LastOrDefault(e => e.Role == "agent" && !e.Error)?.Text;
                if (string.IsNullOrWhiteSpace(last)) { AddNote(Dictionary.NoteNothingToSpeak); return; }
                text = last;
            }
            AddNote(Dictionary.NoteSynthesising);
            var body = JsonSerializer.Serialize(new { input = text, lang = SystemLang.Get(), speed = 1.0 }, JsonOpts);
            try
            {
                using var resp = await _http.PostAsync("/v1/audio/speech", new StringContent(body, Encoding.UTF8, "application/json"));
                if (!resp.IsSuccessStatusCode)
                {
                    AddNote(string.Format(Dictionary.NoteTtsFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
                    return;
                }
                var bytes = await resp.Content.ReadAsByteArrayAsync();
                var path = Path.Combine(Path.GetTempPath(), $"agent_tts_{DateTime.Now:yyyyMMddHHmmss}.wav");
                await File.WriteAllBytesAsync(path, bytes);
                AddNote(string.Format(Dictionary.NoteSaved, path, bytes.Length));
                if (OperatingSystem.IsWindows())
                {
                    if (!PlaySound(path, IntPtr.Zero, SndAsync | SndFilename))
                        AddNote(string.Format(Dictionary.NotePlaybackFailed, path));
                }
                else
                {
                    AddNote(Dictionary.NotePlaybackWindowsOnly);
                }
            }
            catch (Exception ex)
            {
                AddNote(string.Format(Dictionary.NoteTtsFailed, ex.Message));
            }
        }

        private Task TtsEngineAsync(string args)
        {
            var engine = args.Trim().ToLowerInvariant();
            if (string.IsNullOrWhiteSpace(engine))
            {
                ShowTtsEngineDialog();   // interactive panel (menu Impostazioni → Motore TTS)
                return Task.CompletedTask;
            }
            ApplyTtsEngine(engine);
            return Task.CompletedTask;
        }

        // Reads the effective TTS engine: the runtime override (PODCAST_TTS_ENGINE), then
        // the persisted appsettings Tts:Engine, then the built-in default.
        private static string CurrentTtsEngine()
        {
            var env = Environment.GetEnvironmentVariable("PODCAST_TTS_ENGINE");
            if (!string.IsNullOrWhiteSpace(env)) return env;
            try
            {
                var path = AppConfig.AppSettingsFile;
                if (File.Exists(path))
                {
                    var doc = JsonNode.Parse(File.ReadAllText(path)) as JsonObject;
                    var e = doc?["Tts"]?["Engine"]?.GetValue<string>();
                    if (!string.IsNullOrWhiteSpace(e)) return e!;
                }
            }
            catch { }
            return TtsEngineSupport.DefaultEngine;
        }

        // Validates and applies a TTS engine selection (runtime override + persisted).
        // Returns the human-readable outcome.
        private string ApplyTtsEngine(string engine)
        {
            var known = string.Join(", ", TtsEngineSupport.KnownEngines);
            if (!TtsEngineSupport.IsKnown(engine))
                return string.Format(Dictionary.TtsEngineUnknown, engine, known);
            if (!TtsEngineSupport.IsAvailable(engine, out var reason))
                return string.Format(Dictionary.TtsEngineUnavailable, engine, reason, TtsEngineSupport.DefaultEngine);
            Environment.SetEnvironmentVariable("PODCAST_TTS_ENGINE", engine);
            PersistTtsEngine(engine);
            return string.Format(Dictionary.TtsEngineSet, engine);
        }

        // TTS engine panel: the selectable engines with their availability, the current
        // selection, a "set selected" action and a "reset to default" action.
        private void ShowTtsEngineDialog()
        {
            Log.LogStep("TUI TTS engine panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.TtsEnginePanelTitle,
                Width = Dim.Percent(60),
                Height = Dim.Percent(70),
                SchemeName = "Dark",
            };

            var current = CurrentTtsEngine();
            var currentLabel = new Label
            {
                Text = string.Format(Dictionary.TtsEngineCurrent, current),
                X = 1, Y = 0, Width = Dim.Fill() - 2,
            };
            dlg.Add(new Label { Text = Dictionary.TtsEnginePick, X = 1, Y = 2, Width = Dim.Fill() });
            var engines = TtsEngineSupport.KnownEngines.ToList();
            var list = new ListView
            {
                X = 1, Y = 3, Width = Dim.Fill() - 2, Height = 5,
                Source = new ListWrapper<string>(new ObservableCollection<string>(
                    engines.Select(e =>
                    {
                        var avail = TtsEngineSupport.IsAvailable(e, out _);
                        var mark = string.Equals(e, current, StringComparison.OrdinalIgnoreCase) ? $"  {Dictionary.SetupActiveMarker}" : "";
                        return e + mark + (avail ? "" : $"  ({Dictionary.TtsEngineNotAvailable})");
                    }))),
            };
            var msg = new Label { Text = "", X = 1, Y = 9, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            dlg.Add(currentLabel, list, msg);

            var setBtn = new Button { Text = Dictionary.TtsEngineSetSelected, X = 1, Y = 11 };
            setBtn.Accepted += (_, _) =>
            {
                var i = list.SelectedItem;
                if (i is not { } idx || idx < 0 || idx >= engines.Count) { msg.Text = Dictionary.TtsEnginePickOne; return; }
                msg.Text = ApplyTtsEngine(engines[idx]);
                current = CurrentTtsEngine();
                currentLabel.Text = string.Format(Dictionary.TtsEngineCurrent, current);
                Log.LogStep($"TUI TTS engine set to {current}", monitor: true);
            };
            var resetBtn = new Button { Text = Dictionary.TtsEngineReset, X = Pos.Right(setBtn) + 1, Y = 11 };
            resetBtn.Accepted += (_, _) =>
            {
                msg.Text = ApplyTtsEngine(TtsEngineSupport.DefaultEngine);
                current = CurrentTtsEngine();
                currentLabel.Text = string.Format(Dictionary.TtsEngineCurrent, current);
                Log.LogStep("TUI TTS engine reset to default", monitor: true);
            };
            dlg.Add(setBtn, resetBtn);

            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI TTS engine panel closed"); _app.RequestStop(dlg); };
            dlg.AddButton(close);
            dlg.Initialized += (_, _) => list.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI TTS engine panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        /// <summary>Persists the preferred TTS engine into appsettings.json (Tts:Engine), the
        /// user-editable copy under PersistentData\ (AppConfig).</summary>
        private static void PersistTtsEngine(string engine)
        {
            try
            {
                var path = AppConfig.AppSettingsFile;
                if (!File.Exists(path)) return;
                var doc = JsonNode.Parse(File.ReadAllText(path)) as JsonObject;
                if (doc == null) return;
                var tts = doc["Tts"] as JsonObject ?? new JsonObject();
                tts["Engine"] = engine;
                doc["Tts"] = tts;
                File.WriteAllText(path, doc.ToJsonString(new JsonSerializerOptions { WriteIndented = true }));
            }
            catch { }
        }

        private async Task UpdateAsync()
        {
            AddNote(Dictionary.UpdateChecking);
            var result = await AutoUpdate.CheckAndApplyManualAsync();
            // When an update was found and applied, ApplyAsync spawns the updater and
            // exits the process — this note only surfaces when nothing was installed.
            AddNote(result.Status switch
            {
                AutoUpdate.ManualUpdateStatus.NotPublished => Dictionary.UpdateUseExecutable,
                AutoUpdate.ManualUpdateStatus.DebugBuild => Dictionary.UpdateDebugBuild,
                AutoUpdate.ManualUpdateStatus.NoArchive => Dictionary.UpdateNoArchive,
                AutoUpdate.ManualUpdateStatus.Unreachable => Dictionary.UpdateGitHubUnreachable,
                AutoUpdate.ManualUpdateStatus.UpToDate => string.Format(Dictionary.UpdateUpToDate, result.CurrentVersion),
                AutoUpdate.ManualUpdateStatus.NewerThanLatest => string.Format(Dictionary.UpdateNewerThanLatest, result.CurrentVersion, result.LatestVersion),
                AutoUpdate.ManualUpdateStatus.AgentsBusy => Dictionary.UpdateAgentsBusy,
                AutoUpdate.ManualUpdateStatus.AnotherInstance => Dictionary.UpdateAnotherInstance,
                AutoUpdate.ManualUpdateStatus.UpdateInProgress => Dictionary.UpdateInProgress,
                _ => string.Format(Dictionary.UpdateFailed, result.Detail ?? "unknown error"),
            });
        }

        private async Task FeaturesAsync(string args)
        {
            if (string.IsNullOrWhiteSpace(args))
            {
                string current;
                lock (_stateLock)
                    current = _features.Count == 0 ? Dictionary.NoneSet :
                        string.Join(", ", _features.Select(kv => $"{kv.Key}={(kv.Value ? "on" : "off")}"));
                AddNote(string.Format(Dictionary.NoteSessionFeatures, current));
                return;
            }
            var parts = args.Split(' ', StringSplitOptions.RemoveEmptyEntries);
            var name = parts[0].ToLowerInvariant();
            bool value;
            if (parts.Length >= 2 && parts[1].ToLowerInvariant() is "on" or "true") value = true;
            else if (parts.Length >= 2 && parts[1].ToLowerInvariant() is "off" or "false") value = false;
            else
            {
                lock (_stateLock) value = !(_features.TryGetValue(name, out var cur) && cur);
            }
            lock (_stateLock) _features[name] = value;
            var body = JsonSerializer.Serialize(new { session_id = _sessionId, features = new Dictionary<string, bool> { [name] = value } }, JsonOpts);
            using var resp = await _http.PostAsync("/v1/control", new StringContent(body, Encoding.UTF8, "application/json"));
            if (resp.IsSuccessStatusCode) AddNote(string.Format(Dictionary.NoteFeatureSet, name, value ? "on" : "off"));
            else AddNote(string.Format(Dictionary.NoteFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
        }

        private async Task NewSessionAsync()
        {
            using var resp = await _http.PostAsync("/v1/control", new StringContent("{\"create\":true}", Encoding.UTF8, "application/json"));
            if (!resp.IsSuccessStatusCode) { AddNote(string.Format(Dictionary.NoteCreateSessionFailed, (int)resp.StatusCode)); return; }
            using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
            _sessionId = GetStr(doc.RootElement, "session_id") ?? "";
            var shortId = _sessionId[..Math.Min(8, _sessionId.Length)];
            Ui(() =>
            {
                _history.Clear();
                lock (_stateLock)
                {
                    _attached.Clear();
                    foreach (var f in _files) f.Attached = false;
                }
                _history.Add(new Entry { Role = "system", Text = string.Format(Dictionary.NoteNewSession, shortId) });
                RefreshHistory();
            });
            await RefreshSessionStateAsync();
        }

        private async Task ClearHistoryAsync()
        {
            var body = JsonSerializer.Serialize(new { session_id = _sessionId, reset_history = true }, JsonOpts);
            using var resp = await _http.PostAsync("/v1/control", new StringContent(body, Encoding.UTF8, "application/json"));
            if (resp.IsSuccessStatusCode)
            {
                Ui(() =>
                {
                    _history.Clear();
                    _history.Add(new Entry { Role = "system", Text = Dictionary.NoteHistoryCleared });
                    RefreshHistory();
                });
            }
            else
            {
                AddNote(string.Format(Dictionary.NoteFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
            }
        }

        private Task ShowStatusAsync()
        {
            string feats, attached;
            lock (_stateLock)
            {
                feats = _features.Count == 0 ? Dictionary.None : string.Join(", ", _features.Select(kv => $"{kv.Key}={kv.Value}"));
                attached = _attached.Count == 0 ? Dictionary.None : string.Join(", ", _attached);
            }
            var lines = new List<string>
            {
                $"{Dictionary.StatusSession.PadRight(18)}{_sessionId}",
                $"{Dictionary.StatusProvider.PadRight(18)}{_provider}  ({_modelName}, {(_interactionMode.Length > 0 ? _interactionMode : Dictionary.InteractionModeDefault)})",
                string.Format(Dictionary.StatusContextWindow, _contextWindow, _historyTokens),
                $"{Dictionary.StatusTokensLast.PadRight(18)}{_tokensLast}",
                $"{Dictionary.StatusTokensSession.PadRight(18)}{_tokensSession}",
                $"{Dictionary.StatusAgentSet.PadRight(18)}{AgentSetDisplay()}",
                $"{Dictionary.StatusFeatures.PadRight(18)}{feats}",
                $"{Dictionary.StatusAttachments.PadRight(18)}{attached}",
                "",
                $"{Dictionary.StatusCapabilities.PadRight(18)}tts {(_ttsAvailable ? Dictionary.Available : Dictionary.Unavailable)} · voice {(_voiceAvailable ? Dictionary.Available : Dictionary.Unavailable)}",
                $"{"".PadRight(18)}server: {_serverUrl} {(_connected ? Dictionary.Connected : Dictionary.Unreachable)}",
                string.Format(Dictionary.StatusPromptHistory.PadRight(18) + "{0}", _promptHistory.Count),
            };
            if (_assetsMissing.Length > 0)
                lines.Add(string.Format(Dictionary.NoteAssetsIncomplete, string.Join(", ", _assetsMissing)));
            return ShowPageUiAsync(Dictionary.PageAgentStatus, lines);
        }

        private async Task FilesAsync(string args)
        {
            // No arguments → the unified File panel (menu File → File): the uploaded files
            // with their attach state, and the add / toggle-attach / remove actions in one
            // place (the old separate "Allega" menu is folded in here). "/files list" keeps
            // the plain read-only listing.
            if (string.IsNullOrWhiteSpace(args))
            {
                await ShowFilesPanelAsync();
                return;
            }
            if (args == "list")
            {
                await RefreshFilesAsync();
                List<string> lines;
                lock (_stateLock)
                {
                    if (_files.Count == 0) { AddNote(Dictionary.NoteNoFiles); return; }
                    // File names only — the internal file-… ids mean nothing to the user.
                    lines = _files.Select(f => $"{f.FileName} · {f.Status}{(f.Attached ? "  " + Dictionary.NoteAttachedSuffix : "")}").ToList();
                }
                await ShowPageUiAsync(Dictionary.PageUploadedFiles, lines);
                return;
            }
            var parts = args.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries);
            var sub = parts[0].ToLowerInvariant();
            if (sub == "add" && parts.Length == 2)
            {
                var path = parts[1].Trim('"');
                if (!File.Exists(path)) { AddNote(string.Format(Dictionary.NoteFileNotFound, path)); return; }
                AddNote(string.Format(Dictionary.NoteUploading, Path.GetFileName(path)));
                try
                {
                    await using var fs = File.OpenRead(path);
                    using var form = new MultipartFormDataContent();
                    form.Add(new StreamContent(fs), "file", Path.GetFileName(path));
                    form.Add(new StringContent("assistants"), "purpose");
                    using var resp = await _http.PostAsync("/v1/files", form);
                    if (!resp.IsSuccessStatusCode)
                    {
                        AddNote(string.Format(Dictionary.NoteUploadFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
                        return;
                    }
                    using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                    var id = GetStr(doc.RootElement, "id") ?? "";
                    var name = GetStr(doc.RootElement, "filename") ?? Path.GetFileName(path);
                    lock (_stateLock)
                    {
                        _files.RemoveAll(x => x.Id == id);
                        _files.Add(new FileRef { Id = id, FileName = name, Status = GetStr(doc.RootElement, "status") ?? "", Attached = true });
                        if (!_attached.Contains(id)) _attached.Add(id);
                    }
                    AddNote(string.Format(Dictionary.NoteUploaded, name, id));
                }
                catch (Exception ex)
                {
                    AddNote(string.Format(Dictionary.NoteUploadFailed, ex.Message));
                }
            }
            else if (sub == "rm")
            {
                var id = parts.Length > 1 ? parts[1].Trim() : "";
                if (id.Length == 0)
                {
                    // No cryptic ids in the UI: pick the file by name.
                    await RefreshFilesAsync();
                    List<FileRef> files;
                    lock (_stateLock) files = _files.ToList();
                    if (files.Count == 0) { AddNote(Dictionary.NoteNoFiles); return; }
                    var idx = await PickIndexOnUiThreadAsync(Dictionary.DlgPickFileToDelete,
                        files.Select(f => f.FileName).ToList());
                    if (idx is not { } i || i < 0 || i >= files.Count) return;
                    id = files[i].Id;
                }
                try
                {
                    using var resp = await _http.DeleteAsync($"/v1/files/{Uri.EscapeDataString(id)}");
                    if (resp.IsSuccessStatusCode)
                    {
                        lock (_stateLock)
                        {
                            _files.RemoveAll(x => x.Id == id);
                            _attached.Remove(id);
                        }
                        AddNote(string.Format(Dictionary.NoteDeleted, id));
                    }
                    else
                    {
                        AddNote(string.Format(Dictionary.NoteDeleteFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
                    }
                }
                catch (Exception ex)
                {
                    AddNote(string.Format(Dictionary.NoteDeleteFailed, ex.Message));
                }
            }
            else
            {
                AddNote(Dictionary.NoteFilesUsage);
            }
        }

        private async Task ShowFilesPanelAsync()
        {
            await RefreshFilesAsync();
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() => { try { ShowFilesPanel(); tcs.SetResult(); } catch (Exception ex) { tcs.SetException(ex); } });
            await tcs.Task;
        }

        // Unified File panel: the uploaded files with their attach state, and the three
        // actions that used to be split across /files and /attach — add a file, toggle
        // whether it is attached to the next chat message, and remove it — in one screen.
        private void ShowFilesPanel()
        {
            Log.LogStep("TUI File panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.FilesPanelTitle,
                Width = Dim.Percent(72),
                Height = Dim.Percent(70),
                SchemeName = "Dark",
            };
            var list = new ListView { X = 1, Y = 1, Width = Dim.Fill() - 2, Height = Dim.Fill() - 6 };
            var msg = new Label { Text = "", X = 1, Y = Pos.Bottom(list) + 1, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            void RefreshList()
            {
                List<FileRef> files;
                lock (_stateLock) files = _files.ToList();
                list.Source = new ListWrapper<string>(new ObservableCollection<string>(
                    files.Select(f => $"{f.FileName} · {f.Status}{(f.Attached ? "  " + Dictionary.AttachMarker : "")}")));
            }
            RefreshList();
            dlg.Add(list, msg);

            List<FileRef> Snapshot() { lock (_stateLock) return _files.ToList(); }
            bool TrySelected(out int idx)
            {
                idx = -1;
                var sel = list.SelectedItem;
                if (sel is not { } i || i < 0 || i >= Snapshot().Count) return false;
                idx = i;
                return true;
            }

            var addBtn = new Button { Text = Dictionary.FilesAdd, X = 1, Y = Pos.Bottom(msg) + 1 };
            addBtn.Accepted += async (_, _) =>
            {
                var path = await PromptOnUiThreadAsync(Dictionary.FilesAdd, Dictionary.FilesAddPrompt);
                if (string.IsNullOrWhiteSpace(path)) { list.SetFocus(); return; }
                path = path.Trim().Trim('"');
                if (!File.Exists(path)) { msg.Text = string.Format(Dictionary.NoteFileNotFound, path); list.SetFocus(); return; }
                try
                {
                    await using var fs = File.OpenRead(path);
                    using var form = new MultipartFormDataContent();
                    form.Add(new StreamContent(fs), "file", Path.GetFileName(path));
                    form.Add(new StringContent("assistants"), "purpose");
                    using var resp = await _http.PostAsync("/v1/files", form);
                    if (!resp.IsSuccessStatusCode) { msg.Text = string.Format(Dictionary.NoteUploadFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)); list.SetFocus(); return; }
                    using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                    var id = GetStr(doc.RootElement, "id") ?? "";
                    var name = GetStr(doc.RootElement, "filename") ?? Path.GetFileName(path);
                    lock (_stateLock)
                    {
                        _files.RemoveAll(x => x.Id == id);
                        _files.Add(new FileRef { Id = id, FileName = name, Status = GetStr(doc.RootElement, "status") ?? "", Attached = true });
                        if (!_attached.Contains(id)) _attached.Add(id);
                    }
                    msg.Text = string.Format(Dictionary.NoteUploaded, name, id);
                    RefreshList();
                }
                catch (Exception ex) { msg.Text = string.Format(Dictionary.NoteUploadFailed, ex.Message); }
                list.SetFocus();
            };
            var toggleBtn = new Button { Text = Dictionary.FilesToggleAttach, X = Pos.Right(addBtn) + 1, Y = Pos.Bottom(msg) + 1 };
            toggleBtn.Accepted += (_, _) =>
            {
                if (!TrySelected(out var idx)) { msg.Text = Dictionary.FilesPickOne; return; }
                ToggleAttach(Snapshot()[idx]);
                RefreshList();
                list.SetFocus();
            };
            var removeBtn = new Button { Text = Dictionary.FilesRemove, X = Pos.Right(toggleBtn) + 1, Y = Pos.Bottom(msg) + 1 };
            removeBtn.Accepted += async (_, _) =>
            {
                if (!TrySelected(out var idx)) { msg.Text = Dictionary.FilesPickOne; return; }
                var f = Snapshot()[idx];
                try
                {
                    using var resp = await _http.DeleteAsync($"/v1/files/{Uri.EscapeDataString(f.Id)}");
                    if (resp.IsSuccessStatusCode)
                    {
                        lock (_stateLock) { _files.RemoveAll(x => x.Id == f.Id); _attached.Remove(f.Id); }
                        msg.Text = string.Format(Dictionary.NoteDeleted, f.FileName);
                    }
                    else msg.Text = string.Format(Dictionary.NoteDeleteFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp));
                }
                catch (Exception ex) { msg.Text = string.Format(Dictionary.NoteDeleteFailed, ex.Message); }
                RefreshList();
                list.SetFocus();
            };
            dlg.Add(addBtn, toggleBtn, removeBtn);

            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI File panel closed"); _app.RequestStop(dlg); };
            dlg.AddButton(close);
            dlg.Initialized += (_, _) => list.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI File panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        private async Task AttachAsync(string args)
        {
            await RefreshFilesAsync();
            List<FileRef> files;
            lock (_stateLock) files = _files.ToList();
            if (string.IsNullOrWhiteSpace(args))
            {
                if (files.Count == 0) { AddNote(Dictionary.NoteNoFiles); return; }
                var choices = files.Select(f => $"{f.FileName}{(f.Attached ? "  " + Dictionary.AttachMarker : "")}").ToList();
                var idx = await PickIndexOnUiThreadAsync(Dictionary.DlgToggleAttach, choices);
                if (idx is { } i && i >= 0 && i < files.Count) ToggleAttach(files[i]);
                return;
            }
            var byArg = files.FirstOrDefault(x => x.Id == args.Trim() || x.FileName.Equals(args.Trim(), StringComparison.OrdinalIgnoreCase));
            if (byArg == null) { AddNote(string.Format(Dictionary.NoteUnknownFile, args.Trim())); return; }
            ToggleAttach(byArg);
        }

        private async Task RefreshFilesAsync()
        {
            try
            {
                using var resp = await _http.GetAsync("/v1/files").WaitAsync(TimeSpan.FromSeconds(8));
                if (!resp.IsSuccessStatusCode) return;
                using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                if (!doc.RootElement.TryGetProperty("data", out var data)) return;
                lock (_stateLock)
                {
                    _files.Clear();
                    foreach (var f in data.EnumerateArray())
                    {
                        var id = GetStr(f, "id") ?? "";
                        var name = GetStr(f, "filename") ?? id;
                        _files.Add(new FileRef { Id = id, FileName = name, Status = GetStr(f, "status") ?? "", Attached = _attached.Contains(id) });
                    }
                }
            }
            catch { }
        }

        private void ToggleAttach(FileRef f)
        {
            bool attached;
            lock (_stateLock)
            {
                f.Attached = !f.Attached;
                attached = f.Attached;
                if (attached) { if (!_attached.Contains(f.Id)) _attached.Add(f.Id); }
                else _attached.Remove(f.Id);
            }
            AddNote(attached
                ? string.Format(Dictionary.NoteAttached, f.FileName)
                : string.Format(Dictionary.NoteDetached, f.FileName));
        }

        // Opens a file the agent delivered in a reply. Agent-attached files are saved under
        // the attachments/ folder next to the executable (see AttachmentsDir); the reply
        // markers show their full paths. Without an argument the whole folder opens in the
        // OS file manager; with a name the newest matching file opens directly.
        private Task OpenAsync(string args)
        {
            var query = args.Trim().Trim('"');
            try
            {
                Directory.CreateDirectory(AttachmentsDir);
                var target = AttachmentsDir;
                var isFile = false;
                if (query.Length > 0)
                {
                    var newest = Directory.EnumerateFiles(AttachmentsDir)
                        .Where(f => Path.GetFileName(f).Contains(query, StringComparison.OrdinalIgnoreCase))
                        .OrderByDescending(File.GetLastWriteTimeUtc)
                        .FirstOrDefault();
                    if (newest == null)
                    {
                        AddNote(string.Format(Dictionary.NoteOpenFileNotFound, query, AttachmentsDir));
                        return Task.CompletedTask;
                    }
                    target = newest;
                    isFile = true;
                }
                Log.LogStep($"TUI Open: opening '{target}'", monitor: true);
                Process.Start(new ProcessStartInfo(target) { UseShellExecute = true });
                AddNote(isFile
                    ? string.Format(Dictionary.NoteOpenedFile, target)
                    : string.Format(Dictionary.NoteOpenedAttachments, target));
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI Open FAILED: {ex.Message}");
                AddNote(string.Format(Dictionary.NoteOpenFailed, ex.Message));
            }
            return Task.CompletedTask;
        }

        private Task RetryAsync()
        {
            if (string.IsNullOrEmpty(_lastPrompt))
            {
                AddNote(Dictionary.NoteNothingToRetry);
                return Task.CompletedTask;
            }
            if (!_lastFailed && _history.Count > 0) AddNote(Dictionary.NoteLastReplyOk);
            StartChat(_lastPrompt);
            return Task.CompletedTask;
        }

        private Task OpenDocsAsync()
        {
            const string url = "https://github.com/Graphene-Lab/AgentBridge/wiki";
            try
            {
                Log.LogStep($"TUI Docs: opening {url}", monitor: true);
                Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
                AddNote(string.Format(Dictionary.NoteOpenedUrl, url));
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI Docs FAILED: {ex.Message}");
                AddNote(string.Format(Dictionary.NoteOpenBrowserFailed, ex.Message));
            }
            return Task.CompletedTask;
        }

        private void OpenIssuesAsync()
        {
            const string url = "https://github.com/Graphene-Lab/AgentBridge/issues";
            try
            {
                Log.LogStep($"TUI OpenIssues: opening {url}", monitor: true);
                Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
                AddNote(string.Format(Dictionary.NoteOpenedUrl, url));
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI OpenIssues FAILED: {ex.Message}");
                AddNote(string.Format(Dictionary.NoteOpenBrowserFailed, ex.Message));
            }
        }

        // ── OfficeManager (agents' office) ──
        // The 16-bit office is served by THIS server at /OfficeManager (static files + the
        // /ws/office duplex hub — see OfficeBridge.cs): no external launcher or download needed.
        // /officemanager opens it in the OS default browser; on a server without a desktop
        // environment the browser cannot be started, so the command reports an error instead of
        // failing silently.
        private Task LaunchOfficeManagerAsync()
        {
            if (!HasDesktopSession())
            {
                AddNote(Dictionary.NoteOfficeManagerNoDesktop);
                return Task.CompletedTask;
            }
            var url = _serverUrl.TrimEnd('/') + "/OfficeManager";
            try
            {
                Log.LogStep($"TUI OfficeManager: opening {url}", monitor: true);
                Process.Start(new ProcessStartInfo(url) { UseShellExecute = true });
                AddNote(string.Format(Dictionary.NoteOpenedUrl, url));
            }
            catch (Exception ex)
            {
                Log.LogStep($"TUI OfficeManager FAILED: {ex.Message}");
                AddNote(string.Format(Dictionary.NoteOpenBrowserFailed, ex.Message));
            }
            return Task.CompletedTask;
        }

        // Desktop-session detection (same rule as AgentHarness.IsInteractiveDesktopSession): a
        // browser can only be launched from a machine with a graphical session — Windows/macOS
        // interactive console, or Linux with DISPLAY/WAYLAND_DISPLAY set (headless servers have
        // neither, so the office cannot be shown there).
        private static bool HasDesktopSession()
        {
            if (OperatingSystem.IsWindows() || OperatingSystem.IsMacOS())
                return Environment.UserInteractive;
            return !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("DISPLAY"))
                || !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("WAYLAND_DISPLAY"));
        }

        // ── Web client (Giraffe AI) ──
        // The web GUI is a tiny static app (single index.html + its own launcher) installed
        // next to the executable by WebClientUpdater (startup keeps it at the latest GitHub
        // release). /web joins that startup task (bounded internally: 15s version check, 5 min
        // download — no artificial timeout that would report a failure on a slow first
        // download), retries the install when it failed (e.g. the machine was offline at boot),
        // then the platform launcher (start.bat / start.sh) serves it on http://localhost:8000
        // and opens the browser. Connectivity failures surface as friendly notes instead of
        // crashing the UI.
        private async Task LaunchWebClientAsync()
        {
            var dir = WebClientUpdater.ClientDir;
            try
            {
                await WebClientUpdater.Startup;
                if (!WebClientUpdater.IsInstalled)
                {
                    AddNote(string.Format(Dictionary.NoteWebClientOutdated, dir, WebClientUpdater.Repo));
                    await WebClientUpdater.EnsureAsync();
                }
                var ver = WebClientUpdater.InstalledVersion is { } v ? $" (v{v})" : "";
                var upd = WebClientUpdater.LastStatus is { } s ? $" — {s}" : "";
                AddNote(string.Format(Dictionary.NoteLaunchingWebClient, dir) + ver + upd);
                LaunchWebClientProcess(dir);
            }
            catch (Exception ex)
            {
                AddNote(string.Format(Dictionary.NoteWebClientFailed, ex.Message));
            }
        }

        private void LaunchWebClientProcess(string dir)
        {
            // Auto-connect the web client to this server: the launcher appends the JSON to
            // the opened URL (?provider=...) and index.html registers+selects the provider.
            var provider = JsonSerializer.Serialize(new
            {
                name = "AgentBridge",
                format = "openai",
                model = _agentSet,
                endpoint = $"{_serverUrl.TrimEnd('/')}/v1/chat/completions",
            }, JsonOpts);

            if (OperatingSystem.IsWindows())
            {
                var bat = Path.Combine(dir, "start.bat");
                if (!File.Exists(bat)) throw new InvalidOperationException($"missing {bat}");
                // ⚠️ CONSOLE LEAK (see docs-dev/TUI-DEVELOPMENT.md §8): the launcher must never
                // share the TUI console — a child writing into the caller's console floods
                // the screen with raw ANSI (^[[8;30;120t spam). UseShellExecute=true gives
                // the .bat its OWN console window and detaches its std handles completely.
                // The JSON travels base64url-encoded (no padding): embedded quotes or '='
                // would be mangled by the cmd.exe command line (start.bat decodes it
                // before building the browser URL).
                var b64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(provider))
                    .TrimEnd('=').Replace('+', '-').Replace('/', '_');
                Process.Start(new ProcessStartInfo
                {
                    FileName = bat,
                    Arguments = $"--provider {b64}",
                    UseShellExecute = true,
                    WorkingDirectory = dir,
                });
            }
            else
            {
                var sh = Path.Combine(dir, "start.sh");
                if (!File.Exists(sh)) throw new InvalidOperationException($"missing {sh}");
                // Same console-leak rule: the launcher's output must never reach the TUI,
                // so its std handles are drained to a temp log instead of the terminal.
                // The drain tasks outlive this method (the launcher runs as a server).
                var logPath = Path.Combine(Path.GetTempPath(), $"giraffe_{DateTime.Now:yyyyMMddHHmmss}.log");
                var log = File.Create(logPath);
                var psi = new ProcessStartInfo("bash", new[] { sh, "--provider", provider })
                {
                    UseShellExecute = false,
                    WorkingDirectory = dir,
                    RedirectStandardOutput = true,
                    RedirectStandardError = true,
                };
                var proc = Process.Start(psi);
                if (proc != null)
                {
                    _ = Task.Run(() =>
                    {
                        // StreamReader.CopyTo needs a TextWriter — drain the raw stream.
                        try { proc.StandardOutput.BaseStream.CopyTo(log); } catch { }
                        try { proc.StandardError.BaseStream.CopyTo(log); } catch { }
                        try { log.Dispose(); } catch { }
                        try { proc.Dispose(); } catch { }
                    });
                }
                else
                {
                    try { log.Dispose(); } catch { }
                }
            }
        }

        private Task ShowHelpAsync()
        {
            var lines = new List<string>
            {
                Dictionary.HelpQuickStart,
                Dictionary.HelpQuickStart1,
                Dictionary.HelpQuickStart2,
                Dictionary.HelpQuickStart3,
                Dictionary.HelpQuickStart4,
                "",
                Dictionary.HelpCommands,
            };
            foreach (var c in Commands.OrderBy(c => c.Name, StringComparer.OrdinalIgnoreCase))
            {
                var alias = c.Aliases is { Length: > 0 } ? $"  (also {string.Join(", ", c.Aliases)})" : "";
                lines.Add($"  /{c.Name}{alias} {c.Args}".TrimEnd().PadRight(30) + c.Help);
            }
            lines.Add("");
            lines.Add(Dictionary.HelpShortcuts);
            foreach (var (keys, what) in ShortcutTable)
                lines.Add($"  {keys.PadRight(24)} {what}");
            lines.Add("");
            lines.Add(Dictionary.HelpMouse);
            lines.Add(Dictionary.HelpMouseWheel);
            lines.Add(Dictionary.HelpMouseClickInput);
            lines.Add(Dictionary.HelpMouseClickRow);
            lines.Add("");
            lines.Add(Dictionary.HelpApi);
            lines.Add(Dictionary.HelpApi1);
            lines.Add(Dictionary.HelpApi2);
            lines.Add(Dictionary.HelpApi3);
            lines.Add("");
            lines.Add(Dictionary.HelpOnline);
            lines.Add(Dictionary.HelpOnlineRepo);
            lines.Add(Dictionary.HelpOnlineReadme);
            return ShowPageUiAsync(Dictionary.PageAgentHelp, lines);
        }

        private Task ShowShortcutsAsync()
        {
            var lines = ShortcutTable.Select(s => $"  {s.Keys.PadRight(24)} {s.What}").ToList();
            lines.Insert(0, Dictionary.HelpShortcutsTitle);
            lines.Add("");
            lines.Add(Dictionary.HelpShortcutsFooter);
            return ShowPageUiAsync(Dictionary.PageShortcuts, lines);
        }

        private void ReverseSearch()
        {
            var dlg = new Dialog
            {
                Title = Dictionary.DlgReverseSearch,
                Width = Dim.Percent(85),
                Height = Dim.Percent(50),
                SchemeName = "Dark",
            };
            var q = new TextField { X = 0, Y = 0, Width = Dim.Fill() };
            var list = new ListView { X = 0, Y = 1, Width = Dim.Fill(), Height = Dim.Fill() - 2 };
            var hint = new Label
            {
                Text = Dictionary.DlgReverseHint,
                X = 0, Y = Pos.Bottom(list), Width = Dim.Fill(),
            };
            var matches = new List<string>();
            void Recompute()
            {
                var f = (q.Text ?? "").Trim();
                matches = _promptHistory.Where(p => p.Contains(f, StringComparison.OrdinalIgnoreCase)).ToList();
                list.Source = new ListWrapper<string>(new ObservableCollection<string>(matches));
                ClampSelection(list, matches.Count);
            }
            Recompute();
            q.ValueChanged += (_, _) => Recompute();
            string? picked = null;
            q.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    if (matches.Count > 0) picked = matches[Math.Max(0, list.SelectedItem ?? 0)];
                    _app.RequestStop(dlg);
                }
            };
            list.Accepted += (_, e) =>
            {
                e.Handled = true;
                if (matches.Count > 0) picked = matches[Math.Max(0, list.SelectedItem ?? 0)];
                _app.RequestStop(dlg);
            };
            dlg.Add(q, list, hint);
            dlg.Initialized += (_, _) => q.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            if (picked != null && _inputField != null)
            {
                _inputField.Text = picked;
                _inputPlaceholderActive = false;
                _inputField.SchemeName = "Dark";
                _inputField.CaretOffset = _inputField.Document?.TextLength ?? 0;
            }
            _inputField?.SetFocus();
        }

        // ── Dialogs ──
        // Runs a modal picker (title + items) on the UI thread; returns the selected
        // item or null when cancelled with Esc. Must only be called from Ui(...).
        private string? RunPickerDialog(string title, IReadOnlyList<string> items)
        {
            if (items.Count == 0) return null;
            var dlg = new Dialog
            {
                Title = title,
                Width = Dim.Percent(70),
                Height = Dim.Percent(60),
                SchemeName = "Dark",
            };
            var list = new ListView
            {
                X = 0, Y = 0, Width = Dim.Fill(), Height = Dim.Fill() - 1,
                Source = new ListWrapper<string>(new ObservableCollection<string>(items)),
                SelectedItem = 0,
            };
            var hint = new Label
            {
                Text = Dictionary.DlgPickerHint,
                X = 0, Y = Pos.Bottom(list), Width = Dim.Fill(),
            };
            string? result = null;
            // In v2.4.17 the ListView does NOT raise Accepted from the keyboard: its default
            // key bindings are only movement keys, and the inherited Enter→Accept command is
            // not handled by the list, so it bubbles to the Dialog which closes with no result.
            // Handle Enter here (the same pattern the provider picker uses on its filter) so
            // the hint "Enter selects" matches the behaviour; Accepted stays for mouse
            // double-click.
            list.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    result = items[Math.Max(0, list.SelectedItem ?? 0)];
                    _app.RequestStop(dlg);
                }
            };
            list.Accepted += (_, e) =>
            {
                e.Handled = true;
                result = items[Math.Max(0, list.SelectedItem ?? 0)];
                _app.RequestStop(dlg);
            };
            dlg.Add(list, hint);
            dlg.Initialized += (_, _) => list.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            _inputField?.SetFocus();
            return result;
        }

        // Like RunPickerDialog but returns the selected INDEX (the caller owns the items),
        // so the rendered rows never need parsing (e.g. to strip an id from a file name).
        private int? RunIndexPickerDialog(string title, IReadOnlyList<string> items)
        {
            if (items.Count == 0) return null;
            var dlg = new Dialog
            {
                Title = title,
                Width = Dim.Percent(70),
                Height = Dim.Percent(60),
                SchemeName = "Dark",
            };
            var list = new ListView
            {
                X = 0, Y = 0, Width = Dim.Fill(), Height = Dim.Fill() - 1,
                Source = new ListWrapper<string>(new ObservableCollection<string>(items)),
                // A picker must have a usable initial selection: with SelectedItem = null an
                // immediate Enter closes the dialog with no result. Start on the first row so
                // Enter selects out of the box.
                SelectedItem = 0,
            };
            var hint = new Label
            {
                Text = Dictionary.DlgPickerHint,
                X = 0, Y = Pos.Bottom(list), Width = Dim.Fill(),
            };
            // In v2.4.17 the ListView does NOT raise Accepted from the keyboard: its default
            // key bindings are only movement keys, and the inherited Enter→Accept command is
            // not handled by the list, so it bubbles to the Dialog which closes with no result.
            // Handle Enter here so the hint "Enter selects" matches the behaviour; Accepted
            // stays for mouse double-click. Do NOT call KeyBindings.Add(Key.Enter, …) — the
            // binding already exists and re-adding it throws "A binding for Enter exists".
            int? result = null;
            list.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    result = list.SelectedItem;
                    _app.RequestStop(dlg);
                }
            };
            list.Accepted += (_, e) =>
            {
                e.Handled = true;
                result = list.SelectedItem;
                _app.RequestStop(dlg);
            };
            dlg.Add(list, hint);
            dlg.Initialized += (_, _) => list.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            _inputField?.SetFocus();
            return result;
        }

        private Task<int?> PickIndexOnUiThreadAsync(string title, IReadOnlyList<string> items)
        {
            var tcs = new TaskCompletionSource<int?>(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { tcs.TrySetResult(RunIndexPickerDialog(title, items)); }
                catch (Exception ex) { tcs.TrySetException(ex); }
            });
            return tcs.Task;
        }

        private Task<string?> PickOnUiThreadAsync(string title, IReadOnlyList<string> items)
        {
            var tcs = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { tcs.TrySetResult(RunPickerDialog(title, items)); }
                catch (Exception ex) { tcs.TrySetException(ex); }
            });
            return tcs.Task;
        }

        // The "/model" provider picker: a live filter field above the provider list
        // (same palette pattern). Enter on the list selects that provider; Enter on
        // the filter field uses the typed text as the provider name — nobody remembers
        // the configured ids, so typing a name is as valid as picking from the list.
        // Returns the provider name, or null when cancelled with Esc.
        private string? RunProviderPickerDialog(string title, IReadOnlyList<(string Id, string Display)> items)
        {
            if (items.Count == 0) return null;
            var dlg = new Dialog
            {
                Title = title,
                Width = Dim.Percent(80),
                Height = Dim.Percent(60),
                SchemeName = "Dark",
            };
            var filter = new TextField { X = 0, Y = 0, Width = Dim.Fill() };
            var list = new ListView { X = 0, Y = 1, Width = Dim.Fill(), Height = Dim.Fill() - 2 };
            var hint = new Label
            {
                Text = Dictionary.DlgProviderPickerHint,
                X = 0, Y = Pos.Bottom(list), Width = Dim.Fill(),
            };
            var visible = new List<(string Id, string Display)>();
            void Recompute()
            {
                var f = (filter.Text ?? "").Trim();
                visible = items.Where(p =>
                        p.Id.StartsWith(f, StringComparison.OrdinalIgnoreCase)
                        || (f.Length > 0 && p.Display.Contains(f, StringComparison.OrdinalIgnoreCase)))
                    .ToList();
                // The currently active provider is marked with a bullet so the picker
                // always shows what is in use (not just what could be selected). The
                // non-active rows get the same leading width ("● " = 2 cells) so every
                // provider name starts at the same column.
                list.Source = new ListWrapper<string>(new ObservableCollection<string>(
                    visible.Select(p => string.Equals(p.Id, _provider, StringComparison.OrdinalIgnoreCase)
                        ? $"● {p.Display}" : $"  {p.Display}")));
                ClampSelection(list, visible.Count);
            }
            string? result = null;
            Recompute();
            filter.ValueChanged += (_, _) => Recompute();
            filter.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    var text = (filter.Text ?? "").Trim();
                    if (text.Length == 0 && visible.Count > 0)
                        result = visible[Math.Max(0, list.SelectedItem ?? 0)].Id;
                    else if (visible.FirstOrDefault(p => string.Equals(p.Id, text, StringComparison.OrdinalIgnoreCase)).Id is { } id)
                        result = id;
                    else
                        result = text;   // typed provider name, matched against the list when possible
                    _app.RequestStop(dlg);
                }
                else if (key == Key.Tab)
                {
                    key.Handled = true;
                    if (visible.Count > 0)
                    {
                        var p = visible[Math.Max(0, list.SelectedItem ?? 0)];
                        filter.Text = p.Id;
                    }
                }
            };
            list.Accepted += (_, e) =>
            {
                e.Handled = true;
                if (visible.Count > 0) result = visible[Math.Max(0, list.SelectedItem ?? 0)].Id;
                _app.RequestStop(dlg);
            };
            dlg.Add(filter, list, hint);
            dlg.Initialized += (_, _) => filter.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            _inputField?.SetFocus();
            return result;
        }

        private Task<string?> PickProviderOnUiThreadAsync(string title, IReadOnlyList<(string Id, string Display)> items)
        {
            var tcs = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { tcs.TrySetResult(RunProviderPickerDialog(title, items)); }
                catch (Exception ex) { tcs.TrySetException(ex); }
            });
            return tcs.Task;
        }

        // Full-screen page (help/status): a modal dialog closed by Esc/Close.
        // The read-only Editor is focusable so ↑↓ / PgUp / PgDn scroll the content
        // (an unfocusable page had dead arrow keys — see docs-dev/TUI-DEVELOPMENT.md §8).
        private void ShowPage(string title, IReadOnlyList<string> lines)
        {
            Log.LogStep($"TUI page opened: {title} ({lines.Count} righe)", monitor: true);
            var dlg = new Dialog
            {
                Title = title,
                Width = Dim.Percent(92),
                Height = Dim.Percent(92),
                SchemeName = "Dark",
            };
            var tv = new Editor
            {
                ReadOnly = true,
                WordWrap = false,
                CanFocus = true,   // focusable → ↑↓ / PgUp / PgDn scroll the page
                X = 0, Y = 0, Width = Dim.Fill(), Height = Dim.Fill() - 2,
                Document = new TextDocument(string.Join("\n", lines)),
            };
            var hint = new Label
            {
                Text = Dictionary.DlgPageHint,
                X = 0, Y = Pos.Bottom(tv), Width = Dim.Fill(),
            };
            dlg.Add(tv, hint);
            dlg.AddButton(new Button { Text = Dictionary.Close });
            dlg.Initialized += (_, _) => tv.SetFocus();
            _app.Run(dlg);
            Log.LogStep($"TUI page closed: {title}");
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        private Task ShowPageUiAsync(string title, IReadOnlyList<string> lines)
        {
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { ShowPage(title, lines); tcs.SetResult(); }
                catch (Exception ex) { tcs.SetException(ex); }
            });
            return tcs.Task;
        }

        // The "/" live palette: filter field + command list (filters as you type),
        // Enter runs the selected command (or the typed command line), Esc cancels.
        private void ShowCommandMenu(string initial)
        {
            Log.LogStep($"TUI command palette opened (initial: '{initial}')", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.DlgCommandsTitle,
                Width = Dim.Percent(80),
                Height = Dim.Percent(60),
                SchemeName = "Dark",
            };
            var filter = new TextField { Text = initial, X = 0, Y = 0, Width = Dim.Fill() };
            var list = new ListView { X = 0, Y = 1, Width = Dim.Fill(), Height = Dim.Fill() - 2 };
            var hint = new Label
            {
                Text = Dictionary.DlgCommandsHint,
                X = 0, Y = Pos.Bottom(list), Width = Dim.Fill(),
            };
            var visible = new List<CliCommand>();
            void Recompute()
            {
                // Tab completion fills the filter with "/command " — strip the leading
                // slash (MatchCommand compares against the command name only) so the
                // completed command stays visible in the list instead of clearing it.
                var f = (filter.Text ?? "").Trim().TrimStart('/');
                visible = Commands.Where(c => MatchCommand(c, f))
                                  .OrderBy(c => c.Name, StringComparer.OrdinalIgnoreCase)
                                  .ToList();
                list.Source = new ListWrapper<string>(new ObservableCollection<string>(
                    visible.Select(c => $"/{c.Name} {c.Args}".TrimEnd() + "  —  " + c.Help)));
                ClampSelection(list, visible.Count);
            }
            Recompute();
            filter.ValueChanged += (_, _) => Recompute();
            // The command is NOT run inside the palette's modal loop: running it there
            // keeps the palette alive while the command's own dialog runs nested inside
            // it, so any panel smaller than the palette (e.g. Motore TTS) shows the
            // palette bleeding through behind it and its lower buttons get clipped.
            // Instead we record the command, close the palette, and run it after Run
            // returns (see below), so the panel opens on the clean main screen.
            string? pendingCmd = null;
            void QueueRun() { pendingCmd = CommandTextFromDialog(filter.Text, visible, list); _app.RequestStop(dlg); }
            filter.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    QueueRun();
                }
                else if (key == Key.Tab)
                {
                    // Complete the selected command name into the filter (like the old TUI).
                    key.Handled = true;
                    if (visible.Count > 0)
                    {
                        var cmd = visible[Math.Max(0, list.SelectedItem ?? 0)];
                        filter.Text = "/" + cmd.Name + (cmd.Args.Length > 0 ? " " : "");
                        // Move cursor to end of the completed text so the user can keep typing.
                        filter.InsertionPoint = filter.Text.Length;
                    }
                }
            };
            // In v2.4.17 keyboard Enter on a focused ListView does NOT raise Accepted:
            // the inherited Enter→Accept is not handled by the list, so the key bubbles
            // to the Dialog which closes with no result. This bites as soon as the user
            // clicks a row (focus moves to the list) after the filter has narrowed the
            // results — the exact "Invio chiude senza eseguire" case. Handle Enter here
            // explicitly (same pattern as RunIndexPickerDialog); Accepted stays for the
            // mouse double-click.
            list.KeyDown += (_, key) =>
            {
                if (key == Key.Enter)
                {
                    key.Handled = true;
                    QueueRun();
                }
            };
            list.Accepted += (_, e) =>
            {
                e.Handled = true;
                QueueRun();
            };
            dlg.Add(filter, list, hint);
            dlg.Initialized += (_, _) => filter.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            _inputField?.SetFocus();
            // Run the queued command now that the palette's modal loop has fully
            // returned, so its panel opens on the clean main screen (not nested).
            if (pendingCmd != null) RunCommandLine(pendingCmd);
        }

        private static string CommandTextFromDialog(string? filterText, List<CliCommand> visible, ListView list)
        {
            var text = (filterText ?? "").Trim();
            var selected = visible.Count > 0 ? visible[Math.Max(0, list.SelectedItem ?? 0)] : null;
            if (selected != null)
            {
                // A typed prefix plus a list selection ("m" → /model) runs what the user
                // highlighted — otherwise Enter would submit an unknown "/m". Exact names
                // (with or without args) still run as typed.
                var first = text.Split(' ')[0];
                if (text.Length == 0
                    || (first.Length > 0 && selected.Name.StartsWith(first, StringComparison.OrdinalIgnoreCase)
                        && !string.Equals(first, selected.Name, StringComparison.OrdinalIgnoreCase)))
                    return "/" + selected.Name;
            }
            if (!text.StartsWith('/')) text = "/" + text;
            return text;
        }

        private static bool MatchCommand(CliCommand c, string filter)
        {
            if (filter.Length == 0) return true;
            var first = filter.Split(' ')[0];
            return c.Name.StartsWith(filter, StringComparison.OrdinalIgnoreCase)
                || (c.Name + " " + c.Args).StartsWith(filter, StringComparison.OrdinalIgnoreCase)
                || (c.Aliases?.Any(a => a.StartsWith("/" + filter, StringComparison.OrdinalIgnoreCase)) ?? false)
                || (first.Length > 0 && c.Name.StartsWith(first, StringComparison.OrdinalIgnoreCase));
        }

        // The "@" live palette: uploaded files, Enter toggles the attachment.
        private void ShowFilesDialog()
        {
            Log.LogStep("TUI @ files palette opened", monitor: true);
            _ = Task.Run(async () =>
            {
                try
                {
                    await RefreshFilesAsync();
                    Ui(() =>
                    {
                        List<FileRef> files;
                        lock (_stateLock) files = _files.ToList();
                        if (files.Count == 0) { AddNote(Dictionary.NoteNoFiles); return; }
                        var choices = files.Select(f => $"{f.FileName}{(f.Attached ? "  " + Dictionary.AttachMarker : "")}").ToList();
                        var idx = RunIndexPickerDialog(Dictionary.DlgToggleAttach, choices);
                        if (idx is { } i && i >= 0 && i < files.Count)
                        {
                            Log.LogStep($"TUI @ files: toggle allegato '{files[i].FileName}'", monitor: true);
                            ToggleAttach(files[i]);
                        }
                    });
                }
                catch (Exception ex)
                {
                    AddNote(string.Format(Dictionary.NoteLoadFilesFailed, ex.Message));
                }
            });
        }

        private void ShowAbout()
        {
            Ui(() =>
            {
                Log.LogStep("TUI About dialog opened", monitor: true);
                // A real About window: the AGENT ASCII art (same gradient as the startup
                // banner), the tagline and the © copyright with the project name.
                var dlg = new Dialog
                {
                    Title = Dictionary.AboutTitle,
                    Width = Dim.Percent(55),
                    Height = Dim.Percent(45),
                    SchemeName = "Dark",
                };
                int y = 1;
                for (int i = 0; i < AsciiArtLines.Length; i++)
                    dlg.Add(new Label { Text = AsciiArtLines[i], X = 2, Y = y++, SchemeName = $"Ascii{i}" });
                dlg.Add(new Label { Text = Dictionary.AboutText, X = 2, Y = y + 1, Width = Dim.Fill() - 4 });
                // AboutText spans two screen rows (it contains a line break); the version
                // and copyright lines follow below it.
                dlg.Add(new Label
                {
                    Text = string.Format(Dictionary.AboutVersion,
                        System.Reflection.Assembly.GetExecutingAssembly().GetName().Version),
                    X = 2, Y = y + 3, Width = Dim.Fill() - 4,
                    SchemeName = "Hint",
                });
                dlg.Add(new Label
                {
                    Text = string.Format(Dictionary.AboutCopyright, DateTime.Now.Year),
                    X = 2, Y = y + 4, Width = Dim.Fill() - 4,
                    SchemeName = "Hint",
                });
                var ok = new Button { Text = Dictionary.Ok, IsDefault = true };
                ok.Accepted += (_, _) => _app.RequestStop(dlg);
                dlg.AddButton(ok);
                _app.Run(dlg);
                dlg.Dispose();
                _inputField?.SetFocus();
            });
        }

        // ── Models & providers setup ──
        // A tabbed modal window (models/providers, email SMTP, IMAP, general) mirroring the
        // AIOrchestrator settings. Field edits are applied on Save; provider list operations
        // (Add/Edit/Remove) apply immediately and persist to providers.json.
        private Task ShowProvidersPanelAsync()
        {
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { ShowProvidersPanel(); tcs.SetResult(); }
                catch (Exception ex) { tcs.SetException(ex); }
            });
            return tcs.Task;
        }

        // LLM / Provider panel: ONE concept for the user — the "active provider". The
        // dropdown opens on the provider actually in use and is the only way to change it;
        // the list below mirrors the same selection with an "(attivo)" marker (no separate
        // "default" wording, which confused active vs default). Add/Edit/Remove manage the
        // configured providers. Save makes the dropdown selection the definitive active
        // provider (persisted as the default + adopted by the running chat) and closes the
        // panel only when validation passes.
        private void ShowProvidersPanel()
        {
            Log.LogStep("TUI Providers panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.SetupLlmTab,
                Width = Dim.Percent(80),
                // Fixed height (issue #13): the panel is a fixed 14-row stack (active
                // provider, active model, api key, validation, configured-providers
                // list, Add/Edit/Remove). With Dim.Percent(70) the dialog collapses on a
                // short console — the 25-row Windows console default gives ~17 rows, so
                // the Add/Edit/Remove row (Y=12-13) overlaps the Save/Close footer and a
                // mouse click on "Edit" lands on "Save", closing the whole panel. 18 rows
                // = 14 content + footer + borders, so the rows never collide on any
                // console tall enough to show the panel.
                Height = 18,
                SchemeName = "Dark",
            };

            var providerDropdown = new DropDownList { ReadOnly = true };
            var providersList = new ListView();

            providerDropdown.X = 17; providerDropdown.Y = 0; providerDropdown.Width = 46;
            dlg.Add(new Label { Text = Dictionary.SetupActiveProvider, X = 1, Y = 0, Width = 15 }, providerDropdown);

            // Active model indicator shown right below the provider dropdown.
            var activeModelLabel = new Label
            {
                Text = "",
                X = 1, Y = 1, Width = 62,
                SchemeName = "Hint",
            };
            dlg.Add(activeModelLabel);

            // API key of the provider the user is working with, editable right here
            // (issue #11: the key was only reachable through the provider's Edit dialog, so
            // users could not find where to paste it). The field follows the provider
            // highlighted in the configured-providers list (falling back to the active
            // provider in the dropdown) and Save writes the edited value back for that same
            // provider through the single key-mutation path (ProviderConfigs.SetApiKey).
            // Local providers simply leave it empty. The field is added to the view tree
            // AFTER the Add/Edit/Remove buttons so the keyboard focus order (dropdown →
            // list → Add → Edit) that the setup tests rely on is preserved.
            dlg.Add(new Label { Text = Dictionary.ProviderApiKey, X = 1, Y = 2, Width = 18 });
            var apiKeyField = new TextField { Text = "", X = 20, Y = 2, Width = 44, Secret = true };

            // Validation message shown next to the dropdown when no provider is selected.
            var validationLabel = new Label
            {
                Text = "", X = 1, Y = 3, Width = Dim.Fill() - 2,
                SchemeName = "Hint",
            };
            dlg.Add(validationLabel);

            int y = 4;
            dlg.Add(new Label { Text = Dictionary.SetupConfiguredProviders, X = 1, Y = y, Width = Dim.Fill() });
            y++;
            providersList.X = 1; providersList.Y = y; providersList.Width = 62; providersList.Height = 6;
            dlg.Add(providersList);
            y += 7;
            var addBtn = new Button { Text = Dictionary.SetupAdd, X = 1, Y = y };
            var editBtn = new Button { Text = Dictionary.SetupEdit, X = Pos.Right(addBtn) + 1, Y = y };
            var removeBtn = new Button { Text = Dictionary.SetupRemove, X = Pos.Right(editBtn) + 1, Y = y };
            dlg.Add(addBtn, editBtn, removeBtn);
            dlg.Add(apiKeyField);

            // The list mirrors the dropdown selection with a single "(attivo)" marker — the
            // user sees exactly one active provider, no redundant "default" tag.
            providerDropdown.ValueChanged += (_, _) =>
            {
                RefreshProviderList();
                // Move the list highlight to the provider shown in the dropdown so the key
                // field (which follows the list) stays in sync when the active provider
                // changes. One-way only: browsing the list does NOT change the active
                // provider, so there is no feedback loop.
                var idx = ProviderConfigs.All.ToList()
                    .FindIndex(p => string.Equals(p.ProviderName, providerDropdown.Text, StringComparison.OrdinalIgnoreCase));
                if (idx >= 0) providersList.SelectedItem = idx;
                LoadApiKeyForSelection();
            };
            // Keep the key field in sync with the provider highlighted in the list, so the
            // field always shows the key that Save will write back for (issue #13).
            providersList.ValueChanged += (_, _) => LoadApiKeyForSelection();
            void RefreshProviderList()
            {
                providersList.Source = new ListWrapper<string>(new ObservableCollection<string>(
                    ProviderConfigs.All.Select(p =>
                        string.Equals(p.ProviderName, providerDropdown.Text, StringComparison.OrdinalIgnoreCase)
                            ? p.ProviderName + $"  {Dictionary.SetupActiveMarker}"
                            : p.ProviderName)));
                // Active model: the REAL session model when the dropdown shows the provider
                // in use (the configured ModelName is often empty even though a concrete model
                // is active — the session knows the truth); otherwise the selected provider's
                // configured model as a preview of what would activate.
                var sel = ProviderConfigs.All.FirstOrDefault(p => p.ProviderName == providerDropdown.Text);
                if (sel != null && string.Equals(sel.ProviderName, _provider, StringComparison.OrdinalIgnoreCase)
                    && !string.IsNullOrWhiteSpace(_modelName))
                    activeModelLabel.Text = string.Format(Dictionary.SetupActiveModel, _modelName);
                else if (sel != null && !string.IsNullOrWhiteSpace(sel.ModelName))
                    activeModelLabel.Text = string.Format(Dictionary.SetupActiveModel, sel.ModelName);
                else
                    activeModelLabel.Text = Dictionary.SetupActiveModelDefault;
            }
            // Full refresh after a provider was added/edited/removed (dropdown included).
            void RefreshProviders()
            {
                var names = ProviderConfigs.All.Select(p => p.ProviderName).ToList();
                providerDropdown.Source = new ListWrapper<string>(new ObservableCollection<string>(names));
                // Show the CURRENT active provider on open; fall back to the default only
                // when the active one is not configured anymore (e.g. it was removed).
                if (string.IsNullOrWhiteSpace(providerDropdown.Text)
                    || !names.Contains(providerDropdown.Text, StringComparer.OrdinalIgnoreCase))
                    providerDropdown.Text = names.Contains(_provider, StringComparer.OrdinalIgnoreCase)
                        ? _provider
                        : ProviderConfigs.Default.ProviderName;
                RefreshProviderList();
                // Highlight the active provider in the list so the key field opens showing
                // its key (the field follows the list selection); the user then moves the
                // highlight to edit another provider's key.
                var activeIdx = names.FindIndex(n => string.Equals(n, providerDropdown.Text, StringComparison.OrdinalIgnoreCase));
                if (activeIdx >= 0) providersList.SelectedItem = activeIdx;
                LoadApiKeyForSelection();
            }
            // Loads the current API key into the panel's key field so the user can see and
            // edit it without opening the provider's Edit dialog (issue #11). The field
            // follows the provider the user is working with: the row highlighted in the
            // configured-providers list when there is one, otherwise the provider shown in
            // the "Active provider" dropdown — the same provider Save writes the key back
            // for. Previously it followed only the dropdown, so selecting a provider in the
            // list and typing its key looked like it did nothing (issue #13).
            void LoadApiKeyForSelection()
            {
                var name = SelectedProviderName() ?? providerDropdown.Text;
                apiKeyField.Text = !string.IsNullOrWhiteSpace(name)
                    && ProviderConfigs.TryGet(name, out var cfg) && cfg != null
                    ? cfg.ApiKey ?? ""
                    : "";
            }
            RefreshProviders();

            string? SelectedProviderName()
            {
                var i = providersList.SelectedItem;
                return i is >= 0 && i < ProviderConfigs.All.Count ? ProviderConfigs.All[i.Value].ProviderName : null;
            }

            addBtn.Accepted += (_, _) =>
            {
                Log.LogStep("TUI Providers: Add provider button", monitor: true);
                var cfg = ShowProviderDialog(null);
                if (cfg == null) return;
                if (ProviderConfigs.Add(cfg, persist: true))
                    AddNote(string.Format(Dictionary.SetupProviderAdded, cfg.ProviderName));
                else
                    AddNote(string.Format(Dictionary.SetupProviderExists, cfg.ProviderName));
                RefreshProviders();
            };
            editBtn.Accepted += (_, _) =>
            {
                // Edit the provider selected in the list; fall back to the active one when
                // nothing is highlighted so the button always opens the edit form.
                var name = SelectedProviderName() ?? providerDropdown.Text;
                if (string.IsNullOrWhiteSpace(name)) { AddNote(Dictionary.SetupSelectToEdit); return; }
                Log.LogStep($"TUI Providers: Edit provider '{name}'", monitor: true);
                var cfg = ShowProviderDialog(ProviderConfigs.Get(name));
                if (cfg == null) return;
                ProviderConfigs.Upsert(cfg, persist: true);
                AddNote(string.Format(Dictionary.SetupProviderUpdated, cfg.ProviderName));
                RefreshProviders();
            };
            removeBtn.Accepted += (_, _) =>
            {
                var name = SelectedProviderName();
                if (name == null) { AddNote(Dictionary.SetupSelectToRemove); return; }
                if (MessageBox.Query(_app, Dictionary.SetupRemoveProviderTitle,
                        string.Format(Dictionary.SetupRemoveProviderText, name), Dictionary.Cancel, Dictionary.SetupRemove) != 1)
                    return;
                Log.LogStep($"TUI Providers: Remove provider '{name}'", monitor: true);
                if (!ProviderConfigs.Remove(name, persist: true))
                {
                    AddNote(string.Format(Dictionary.SetupCannotRemove, name));
                    return;
                }
                AddNote(string.Format(Dictionary.SetupProviderRemoved, name));
                if (providerDropdown.Text == name)
                {
                    providerDropdown.Text = ProviderConfigs.Default.ProviderName;
                    _ = SwitchModelAsync(ProviderConfigs.Default.ProviderName);
                }
                RefreshProviders();
            };

            var save = new Button { Text = Dictionary.SetupSave, IsDefault = true };
            save.Accepted += (_, _) =>
            {
                var chosen = (providerDropdown.Text ?? "").Trim();
                if (chosen.Length == 0
                    || !ProviderConfigs.All.Any(p => string.Equals(p.ProviderName, chosen, StringComparison.OrdinalIgnoreCase)))
                {
                    validationLabel.Text = Dictionary.SetupNoProviderSelected;
                    return;
                }
                validationLabel.Text = "";
                // Persist an edited API key for the provider the user is working with — the
                // row highlighted in the configured-providers list, falling back to the
                // active-provider dropdown (issue #13: the key used to be written only for
                // the dropdown provider, so a key typed while a different provider was
                // selected in the list was stored against the wrong provider and looked
                // "not saved"). Written only when the value actually changed, so opening
                // and saving without touching the key never rewrites providers.json.
                var keyTarget = SelectedProviderName() ?? chosen;
                if (!string.IsNullOrWhiteSpace(keyTarget)
                    && ProviderConfigs.TryGet(keyTarget, out var chosenCfg) && chosenCfg != null)
                {
                    var newKey = (apiKeyField.Text ?? "").Trim();
                    if (!string.Equals(newKey, chosenCfg.ApiKey ?? "", StringComparison.Ordinal))
                        ProviderConfigs.SetApiKey(keyTarget, newKey, persist: true);
                }
                // The dropdown selection is the definitive active provider: persist it as the
                // default (new chats start from it) and adopt it for the running process.
                ProviderConfigs.SetDefault(chosen, persist: true);
                _ = SetDefaultProviderAsync(chosen);
                if (!string.Equals(chosen, _provider, StringComparison.OrdinalIgnoreCase))
                    _ = SwitchModelAsync(chosen);   // same path as /model (HTTP /v1/control)
                AddNote(string.Format(Dictionary.SetupActiveProviderSaved, chosen));
                Log.LogStep($"TUI Providers saved (active: {chosen})", monitor: true);
                _app.RequestStop(dlg);
            };
            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI Providers panel closed (Cancel)"); _app.RequestStop(dlg); };
            // AddButton makes the LAST button the Enter default: Close first, Save last.
            dlg.AddButton(close);
            dlg.AddButton(save);
            dlg.Initialized += (_, _) => providerDropdown.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI Providers panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        private Task ShowEmailPanelAsync()
        {
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { ShowEmailPanel(); tcs.SetResult(); }
                catch (Exception ex) { tcs.SetException(ex); }
            });
            return tcs.Task;
        }

        // Email panel: SMTP (sending) and IMAP (reading) in a single panel with one Save.
        // Ports are validated before anything is committed; on error the panel stays open
        // with the message beside the offending field.
        private void ShowEmailPanel()
        {
            Log.LogStep("TUI Email panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.SetupEmailPanelTitle,
                Width = Dim.Percent(70),
                Height = Dim.Percent(70),
                SchemeName = "Dark",
            };

            var smtpErr = new Label { Text = "", X = 1, Y = 6, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            var imapErr = new Label { Text = "", X = 1, Y = 12, Width = Dim.Fill() - 2, SchemeName = "Hint" };

            dlg.Add(new Label { Text = Dictionary.SetupSmtpSection, X = 1, Y = 0, Width = Dim.Fill() });
            var smtpServer = AddField(dlg, Dictionary.SetupSmtpServer, AIOrchestrator.Setup.SmtpServer, 1);
            var smtpPort = AddField(dlg, Dictionary.SetupSmtpPort, AIOrchestrator.Setup.SmtpPort.ToString(), 2);
            var smtpUser = AddField(dlg, Dictionary.SetupSmtpUser, AIOrchestrator.Setup.SmtpUser, 3);
            var smtpPswd = AddField(dlg, Dictionary.SetupSmtpPassword, AIOrchestrator.Setup.SmtpPassword, 4, secret: true);
            var recipientEmail = AddField(dlg, Dictionary.SetupRecipientEmail, AIOrchestrator.Setup.Email, 5);
            dlg.Add(smtpErr);

            dlg.Add(new Label { Text = Dictionary.SetupImapSection, X = 1, Y = 7, Width = Dim.Fill() });
            var imapServer = AddField(dlg, Dictionary.SetupImapServer, AIOrchestrator.Setup.ImapServer, 8);
            var imapPort = AddField(dlg, Dictionary.SetupImapPort, AIOrchestrator.Setup.ImapPort.ToString(), 9);
            var imapUser = AddField(dlg, Dictionary.SetupImapUser, AIOrchestrator.Setup.ImapUser, 10);
            var imapPswd = AddField(dlg, Dictionary.SetupImapPassword, AIOrchestrator.Setup.ImapPassword, 11, secret: true);
            dlg.Add(imapErr);

            var save = new Button { Text = Dictionary.SetupSave, IsDefault = true };
            save.Accepted += (_, _) =>
            {
                smtpErr.Text = "";
                imapErr.Text = "";
                bool ok = true;
                if (!string.IsNullOrWhiteSpace(smtpPort.Text) && !int.TryParse((smtpPort.Text ?? "").Trim(), out _))
                { smtpErr.Text = Dictionary.SetupInvalidSmtpPortText; ok = false; }
                if (!string.IsNullOrWhiteSpace(imapPort.Text) && !int.TryParse((imapPort.Text ?? "").Trim(), out _))
                { imapErr.Text = Dictionary.SetupInvalidImapPortText; ok = false; }
                if (!ok) return;

                AIOrchestrator.Setup.SmtpServer = (smtpServer.Text ?? "").Trim();
                if (int.TryParse((smtpPort.Text ?? "").Trim(), out var sp)) AIOrchestrator.Setup.SmtpPort = sp;
                AIOrchestrator.Setup.SmtpUser = (smtpUser.Text ?? "").Trim();
                AIOrchestrator.Setup.SmtpPassword = (smtpPswd.Text ?? "").Trim();
                AIOrchestrator.Setup.Email = (recipientEmail.Text ?? "").Trim();

                AIOrchestrator.Setup.ImapServer = (imapServer.Text ?? "").Trim();
                if (int.TryParse((imapPort.Text ?? "").Trim(), out var ip)) AIOrchestrator.Setup.ImapPort = ip;
                AIOrchestrator.Setup.ImapUser = (imapUser.Text ?? "").Trim();
                AIOrchestrator.Setup.ImapPassword = (imapPswd.Text ?? "").Trim();

                AddNote(Dictionary.SetupEmailSaved);
                Log.LogStep("TUI Email panel saved", monitor: true);
                _app.RequestStop(dlg);
            };
            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI Email panel closed (Cancel)"); _app.RequestStop(dlg); };
            dlg.AddButton(close);
            dlg.AddButton(save);
            dlg.Initialized += (_, _) => smtpServer.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI Email panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        private Task ShowGeneralPanelAsync()
        {
            var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
            Ui(() =>
            {
                try { ShowGeneralPanel(); tcs.SetResult(); }
                catch (Exception ex) { tcs.SetException(ex); }
            });
            return tcs.Task;
        }

        // General panel: step logging, auto-start at boot and the documents area path.
        // The documents path is validated (and persisted) via TrySetDocumentsPath before
        // the panel closes; an unusable path keeps the panel open with the reason shown.
        private void ShowGeneralPanel()
        {
            Log.LogStep("TUI General panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.SetupGeneralTab,
                Width = Dim.Percent(70),
                Height = Dim.Percent(45),
                SchemeName = "Dark",
            };

            var logEnabled = new CheckBox
            {
                Text = Dictionary.SetupStepLogging,
                Value = AIOrchestrator.Log.IsEnabled ? CheckState.Checked : CheckState.UnChecked,
                X = 1, Y = 0,
            };
            var autoStart = new CheckBox
            {
                Text = Dictionary.SetupAutoStart,
                Value = SystemExtra.Util.GetAutoStart() ? CheckState.Checked : CheckState.UnChecked,
                X = 1, Y = 1,
            };
            var docsPath = AddField(dlg, Dictionary.SetupDocumentsPath, AIOrchestrator.Setup.DocumentsPath, 3);
            var pathErr = new Label { Text = "", X = 1, Y = 4, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            dlg.Add(logEnabled, autoStart, pathErr);

            var save = new Button { Text = Dictionary.SetupSave, IsDefault = true };
            save.Accepted += (_, _) =>
            {
                pathErr.Text = "";
                if (!AIOrchestrator.Setup.TrySetDocumentsPath(docsPath.Text ?? "", out var pathNote))
                {
                    pathErr.Text = string.Format(Dictionary.SetupInvalidDocsPathText, pathNote);
                    return;
                }
                AIOrchestrator.Log.IsEnabled = logEnabled.Value == CheckState.Checked;
                SystemExtra.Util.SetAutoStart(autoStart.Value == CheckState.Checked);
                AddNote(pathNote == null ? Dictionary.SetupGeneralSaved : string.Format(Dictionary.SetupSavedWithNote, pathNote));
                Log.LogStep("TUI General panel saved", monitor: true);
                _app.RequestStop(dlg);
            };
            var close = new Button { Text = Dictionary.Close };
            close.Accepted += (_, _) => { Log.LogStep("TUI General panel closed (Cancel)"); _app.RequestStop(dlg); };
            dlg.AddButton(close);
            dlg.AddButton(save);
            dlg.Initialized += (_, _) => docsPath.SetFocus();
            _app.Run(dlg);
            Log.LogStep("TUI General panel closed", monitor: true);
            dlg.Dispose();
            _inputField?.SetFocus();
        }

        // Modal form to add a new provider or edit an existing one (returns the edited
        // config on OK, null on cancel). The API-key field serves every cloud provider
        // (any non-loopback endpoint); local providers simply leave it empty. Keys are
        // persisted with the provider to providers.json.
        private ProviderConfig? ShowProviderDialog(ProviderConfig? existing)
        {
            var dlg = new Dialog
            {
                Title = existing == null ? Dictionary.ProviderAddTitle : string.Format(Dictionary.ProviderEditTitle, existing.ProviderName),
                Width = 66,
                Height = 16,
                SchemeName = "Dark",
            };
            int y = 0;
            var nameField = AddField(dlg, Dictionary.ProviderName, existing?.ProviderName, y++);
            var protocol = new DropDownList
            {
                ReadOnly = true,
                X = 20, Y = y, Width = 32,
                Source = new ListWrapper<string>(new ObservableCollection<string>(Enum.GetNames<ProviderProtocol>())),
                Text = (existing?.Protocol ?? ProviderProtocol.OpenAI).ToString(),
            };
            dlg.Add(new Label { Text = Dictionary.ProviderProtocol, X = 1, Y = y, Width = 18 }, protocol);
            y++;
            // Interaction mode: Default leaves the decision to the model size (CLI for small
            // models, API for large ones — ProviderConfig.EffectiveAgentInteractionMode).
            var interactionMode = new DropDownList
            {
                ReadOnly = true,
                X = 20, Y = y, Width = 32,
                Source = new ListWrapper<string>(new ObservableCollection<string>(
                    new[] { Dictionary.InteractionModeDefault, nameof(AgentInteractionMode.API), nameof(AgentInteractionMode.CLI) })),
                Text = existing?.AgentInteractionMode?.ToString() ?? Dictionary.InteractionModeDefault,
            };
            dlg.Add(new Label { Text = Dictionary.ProviderInteractionMode, X = 1, Y = y, Width = 18 }, interactionMode);
            y++;
            var modelField = AddField(dlg, Dictionary.ProviderModel, existing?.ModelName, y++);
            var baseField = AddField(dlg, Dictionary.ProviderBaseAddress, existing?.BaseAddress.ToString(), y++);
            var endPointField = AddField(dlg, Dictionary.ProviderEndpoint, existing?.EndPoint, y++);
            // Masked API-key field (secret on screen); leave empty for local providers
            // (localhost/127.0.0.1 endpoint — they are treated as keyless regardless of name).
            var apiKeyField = AddField(dlg, Dictionary.ProviderApiKey, existing?.ApiKey, y++, secret: true);
            var ctxField = AddField(dlg, Dictionary.ProviderContextWindow, (existing?.ContextWindow ?? 32768).ToString(), y++);
            var timeoutField = AddField(dlg, Dictionary.ProviderTimeout, ((int)(existing?.Timeout.TotalSeconds ?? 30)).ToString(), y++);
            // Vision: the provider declares whether its model can understand images. Tools read
            // AIOrchestrator.Vision.Level and only use vision when this is on (a vision-language
            // model). VisionMaxPixels caps the image size sent to the model (0 = no cap).
            var visionCheck = new CheckBox
            {
                Text = Dictionary.ProviderSupportsVision,
                Value = (existing?.SupportsVision ?? false) ? CheckState.Checked : CheckState.UnChecked,
                X = 1, Y = y,
            };
            dlg.Add(visionCheck);
            y++;
            var visionMaxField = AddField(dlg, Dictionary.ProviderVisionMaxPixels, (existing?.VisionMaxPixels ?? 0).ToString(), y++);

            ProviderConfig? result = null;
            var ok = new Button { Text = Dictionary.Ok, IsDefault = true };
            ok.Accepted += (_, _) =>
            {
                var providerName = (nameField.Text ?? "").Trim();
                if (providerName.Length == 0)
                {
                    _ = MessageBox.Query(_app, Dictionary.ProviderAddTitle, Dictionary.ProviderNameRequired, Dictionary.Ok);
                    return;
                }
                if (!Uri.TryCreate((baseField.Text ?? "").Trim(), UriKind.Absolute, out var uri))
                {
                    _ = MessageBox.Query(_app, Dictionary.ProviderAddTitle, Dictionary.ProviderBaseAddressInvalid, Dictionary.Ok);
                    return;
                }
                if (!int.TryParse((ctxField.Text ?? "").Trim(), out var ctx) || ctx <= 0)
                {
                    _ = MessageBox.Query(_app, Dictionary.ProviderAddTitle, Dictionary.ProviderContextInvalid, Dictionary.Ok);
                    return;
                }
                if (!int.TryParse((timeoutField.Text ?? "").Trim(), out var secs) || secs <= 0) secs = 30;
                if (!Enum.TryParse<ProviderProtocol>((protocol.Text ?? "").Trim(), out var proto)) proto = ProviderProtocol.OpenAI;
                // Interaction mode: "Default" (localized) → null → the model-size default applies.
                var modeText = (interactionMode.Text ?? "").Trim();
                AgentInteractionMode? mode = null;
                if (string.Equals(modeText, nameof(AgentInteractionMode.API), StringComparison.OrdinalIgnoreCase)) mode = AgentInteractionMode.API;
                else if (string.Equals(modeText, nameof(AgentInteractionMode.CLI), StringComparison.OrdinalIgnoreCase)) mode = AgentInteractionMode.CLI;
                result = new ProviderConfig
                {
                    ProviderName = providerName,
                    Protocol = proto,
                    // Editing must never silently drop fields the dialog does not expose
                    // (issue #8: after a console edit the provider lost CacheType /
                    // ForceTextToolDefinitions / PauseBetweenRequests). For an ADD the
                    // provider does not exist yet, so those stay at their defaults.
                    CacheType = existing?.CacheType
                        ?? (ProviderConfigs.TryGet(providerName, out var currentAdd) ? currentAdd.CacheType : ProviderCacheType.PrefixCache),
                    AgentInteractionMode = mode,
                    // Editing a provider must never silently drop its default marker.
                    IsDefault = existing?.IsDefault ?? false,
                    ForceTextToolDefinitions = existing?.ForceTextToolDefinitions
                        ?? (ProviderConfigs.TryGet(providerName, out var currentForce) ? currentForce.ForceTextToolDefinitions : false),
                    PauseBetweenRequests = existing?.PauseBetweenRequests
                        ?? (ProviderConfigs.TryGet(providerName, out var currentPause) ? currentPause.PauseBetweenRequests : TimeSpan.Zero),
                    ModelName = (modelField.Text ?? "").Trim(),
                    BaseAddress = uri,
                    EndPoint = (endPointField.Text ?? "").Trim(),
                    ApiKey = (apiKeyField.Text ?? "").Trim(),
                    ContextWindow = ctx,
                    Timeout = TimeSpan.FromSeconds(secs),
                    SupportsVision = visionCheck.Value == CheckState.Checked,
                    VisionMaxPixels = int.TryParse((visionMaxField.Text ?? "").Trim(), out var vmp) && vmp > 0 ? vmp : 0,
                };
                Log.LogStep($"TUI Provider dialog OK: {providerName} ({proto})", monitor: true);
                _app.RequestStop(dlg);
            };
            var cancel = new Button { Text = Dictionary.Cancel };
            cancel.Accepted += (_, _) => { Log.LogStep("TUI Provider dialog cancelled"); _app.RequestStop(dlg); };
            // Last-added button becomes the Enter default (TG v2.4.17): Cancel first,
            // OK last so Enter CONFIRMS the edit (issue #8: edits appeared to not save
            // because Enter triggered Annulla instead).
            dlg.AddButton(cancel);
            dlg.AddButton(ok);
            dlg.Initialized += (_, _) => nameField.SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            return result;
        }

        // Adds a labelled single-line field to a form and returns the field.
        // When secret is true the typed text is masked on screen (e.g. API keys, passwords).
        private static TextField AddField(View parent, string label, string? value, int y, int labelWidth = 18, int fieldWidth = 44, bool secret = false)
        {
            parent.Add(new Label { Text = label, X = 1, Y = y, Width = labelWidth });
            var field = new TextField { Text = value ?? "", X = labelWidth + 2, Y = y, Width = fieldWidth, Secret = secret };
            parent.Add(field);
            return field;
        }

        // ── Server state ──
        private async Task RefreshServerStateAsync()
        {
            try
            {
                using var health = await _http.GetAsync("/health").WaitAsync(TimeSpan.FromSeconds(8));
                _connected = health.IsSuccessStatusCode;
                if (!_connected)
                {
                    _statusNote = Dictionary.StatusServerUnreachableHeadless;
                    UpdateStatusUi();
                    return;
                }

                if (string.IsNullOrEmpty(_sessionId))
                {
                    using var create = await _http.PostAsync("/v1/control",
                        new StringContent("{\"create\":true}", Encoding.UTF8, "application/json"));
                    if (create.IsSuccessStatusCode)
                    {
                        var json = await create.Content.ReadAsStringAsync();
                        using var doc = JsonDocument.Parse(json);
                        _sessionId = doc.RootElement.GetProperty("session_id").GetString() ?? "";
                    }
                }
                await RefreshSessionStateAsync();
            }
            catch (Exception ex)
            {
                _connected = false;
                _statusNote = string.Format(Dictionary.StatusServerUnreachable, ex.Message);
                UpdateStatusUi();
            }
        }

        /// <summary>Renders one usage object from /v1/control through the localized value template
        /// (StatusTokensValue), or Dictionary.None when the provider reported no usage at all — a
        /// zero would look like a measurement.</summary>
        private static string FormatUsage(JsonElement usageRoot, string name)
        {
            if (!usageRoot.TryGetProperty(name, out var usage) || usage.ValueKind != JsonValueKind.Object)
                return Dictionary.None;
            var prompt = GetInt(usage, "prompt_tokens");
            var completion = GetInt(usage, "completion_tokens");
            var calls = GetInt(usage, "calls");
            if (calls == 0 && prompt == 0 && completion == 0) return Dictionary.None;
            var cached = 0;
            if (usage.TryGetProperty("prompt_tokens_details", out var details) && details.ValueKind == JsonValueKind.Object)
                cached = GetInt(details, "cached_tokens");
            return string.Format(Dictionary.StatusTokensValue, prompt, completion, cached, calls);
        }

        private async Task RefreshSessionStateAsync()
        {
            try
            {
                if (string.IsNullOrEmpty(_sessionId)) return;
                using var resp = await _http.GetAsync($"/v1/control?session_id={Uri.EscapeDataString(_sessionId)}").WaitAsync(TimeSpan.FromSeconds(8));
                if (!resp.IsSuccessStatusCode) return;
                using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                var root = doc.RootElement;

                if (root.TryGetProperty("llm", out var llm))
                {
                    _provider = GetStr(llm, "provider") ?? "";
                    _modelName = GetStr(llm, "model_name") ?? "";
                    _interactionMode = GetStr(llm, "interaction_mode") ?? "";
                    _contextWindow = GetInt(llm, "context_window");
                    _historyTokens = GetInt(llm, "history_tokens_estimate");
                }
                // Token consumption as the provider reported it: the turn that just finished and
                // the session total (both include the delegated work, since it serves the same turn).
                if (root.TryGetProperty("usage", out var usage))
                {
                    _tokensLast = FormatUsage(usage, "last_turn");
                    _tokensSession = FormatUsage(usage, "session");
                }
                if (root.TryGetProperty("features", out var feats) && feats.ValueKind == JsonValueKind.Object)
                {
                    lock (_stateLock)
                    {
                        _features.Clear();
                        foreach (var p in feats.EnumerateObject()) _features[p.Name] = p.Value.GetBoolean();
                    }
                }
                if (root.TryGetProperty("capabilities", out var caps))
                {
                    if (caps.TryGetProperty("tts", out var tts))
                    {
                        _ttsAvailable = GetBool(tts, "available");
                        _ttsDetail = GetStr(tts, "detail") ?? "";
                    }
                    if (caps.TryGetProperty("voice", out var voice))
                    {
                        _voiceAvailable = GetBool(voice, "available");
                        _voiceDetail = GetStr(voice, "detail") ?? "";
                    }
                    if (caps.TryGetProperty("sip", out var sip))
                    {
                        _sipAvailable = GetBool(sip, "available");
                        if (sip.TryGetProperty("status", out var s))
                            _sipState = PhaseLabel(GetStr(s, "phase") ?? "");
                    }
                    // Telegram is an in-process chat medium (no HTTP surface): availability
                    // mirrors the telegram.json Enabled flag, refreshed directly from the bridge.
                    _telegramAvailable = TelegramBridge.IsEnabled;
                }
                // Runtime payload readiness: when an older install misses shipped models the
                // user is told ONCE, in plain language, that those features will activate with
                // the next update — never a technical error about missing files.
                if (caps.TryGetProperty("assets", out var assets)
                    && assets.TryGetProperty("missing", out var missingEl) && missingEl.ValueKind == JsonValueKind.Array)
                {
                    var missing = missingEl.EnumerateArray()
                        .Select(m => m.GetString() ?? "")
                        .Where(m => m.Length > 0)
                        .ToArray();
                    _assetsMissing = missing;
                    if (missing.Length > 0 && !_assetsNoteShown)
                    {
                        _assetsNoteShown = true;
                        AddNote(string.Format(Dictionary.NoteAssetsIncomplete, string.Join(", ", missing)));
                    }
                }
                UpdateStatusUi();
            }
            catch { }
        }

        // While the SIP server / Telegram bridge are available their state changes on their
        // own (incoming calls, login progress), so the status bar polls them every few seconds.
        private void StartSipPolling()
        {
            _app.AddTimeout(TimeSpan.FromSeconds(3), () =>
            {
                if (_sipAvailable) _ = RefreshSipStatusAsync();
                if (_telegramAvailable) _ = RefreshTelegramStatusAsync();
                return true;   // recurring
            });
        }

        private async Task RefreshSipStatusAsync()
        {
            try
            {
                using var resp = await _http.GetAsync("/v1/sip/status").WaitAsync(TimeSpan.FromSeconds(5));
                if (!resp.IsSuccessStatusCode) return;
                using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                if (!doc.RootElement.TryGetProperty("sip", out var sip)) return;
                _sipState = PhaseLabel(GetStr(sip, "phase") ?? "");
                UpdateStatusUi();
            }
            catch { }
        }

        private async Task RefreshTelegramStatusAsync()
        {
            try
            {
                _telegramState = TelegramPhaseLabel(TelegramBridge.Phase);
                UpdateStatusUi();
            }
            catch { }
        }

        private static string TelegramPhaseLabel(TelegramBridge.TelegramPhase phase) => phase switch
        {
            TelegramBridge.TelegramPhase.Connecting => Dictionary.TelegramPhaseConnecting,
            TelegramBridge.TelegramPhase.LoginPendingCode => Dictionary.TelegramPhaseLoginPendingCode,
            TelegramBridge.TelegramPhase.LoginPendingPassword => Dictionary.TelegramPhaseLoginPendingPassword,
            TelegramBridge.TelegramPhase.Connected => Dictionary.TelegramPhaseConnected,
            TelegramBridge.TelegramPhase.Failed => Dictionary.TelegramPhaseFailed,
            _ => Dictionary.TelegramPhaseDisabled,
        };

        private static string PhaseLabel(string phase) => phase switch
        {
            "ringing" => Dictionary.SipPhaseRinging,
            "pin" => Dictionary.SipPhasePin,
            "conversation" => Dictionary.SipPhaseConversation,
            "ended" => Dictionary.SipPhaseEnded,
            _ => "",
        };

        // Sets a ListView selection clamped to the item range; null (no selection) when
        // the list is empty — assigning a clamped 0 to an empty ListView throws
        // "SelectedItem must be greater than 0 or less than the number of items".
        private static void ClampSelection(ListView list, int count)
            => list.SelectedItem = count > 0 ? Math.Clamp(list.SelectedItem ?? 0, 0, count - 1) : null;

        private static string? GetStr(JsonElement e, string name) =>
            e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.String ? v.GetString() : null;
        private static int GetInt(JsonElement e, string name) =>
            e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.Number && v.TryGetInt32(out var i) ? i : 0;
        private static bool GetBool(JsonElement e, string name) =>
            e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.True;
        private static string ValueOr(string? value, string fallback) =>
            string.IsNullOrWhiteSpace(value) ? fallback : value;
    }
}

// ═══════════════════════════════════════════════════════════════════════
//  PUPPET MODE — automated-testing control surface (debug builds only)
//
//  Lets an external tester (agent/script) read the current TUI screen as
//  plain text and inject keyboard/mouse input, always marshalled onto the
//  Terminal.Gui main loop via IApplication.Invoke so no UI-thread race can
//  occur. Program.cs starts a localhost TCP listener that drives these
//  methods (see docs-dev/PUPPET-MODE-GUIDE.md).
// ═══════════════════════════════════════════════════════════════════════
public static class PuppetMode
{
    /// <summary>Reference to the running Terminal.Gui application, set by <see cref="ConsoleTui"/>.</summary>
    internal static IApplication? _app;

    /// <summary>
    /// True once the puppet TCP listener is active. Only ever set in DEBUG builds
    /// (Program.cs); the release binary has no puppet surface at all.
    /// </summary>
    public static bool Enabled { get; internal set; }

    // ── Pump design (thread-safety) ──
    // The puppet TCP handlers run on background threads. They must NEVER call
    // Application.Invoke/TimedEvents.Add directly: Terminal.Gui v2.4.17 holds the
    // TimedEvents lock across the whole callback run, and a modal dialog opened from
    // an injected key runs its nested RunLoop INSIDE that callback — so the lock is
    // held for the dialog's entire lifetime and every background Invoke would block
    // forever (seen live: all puppet handlers stuck in Monitor.Enter_Slowpath).
    // Instead the handlers only ENQUEUE work; a recurring timer registered on the UI
    // thread (StartPump) drains the queue and refreshes the capture snapshot.
    private static readonly System.Collections.Concurrent.ConcurrentQueue<Action> _injections = new();
    private static readonly System.Collections.Concurrent.ConcurrentQueue<(System.Drawing.Point Pos, TaskCompletionSource<string> Tcs)> _hitTests = new();
    private static string _snapshot = "(puppet mode: waiting for the first capture)";

    /// <summary>
    /// Registers the puppet pump timer. Must be called on the Terminal.Gui UI thread
    /// (done by <see cref="ConsoleTui"/>'s constructor); the timer runs even while a
    /// modal dialog is open because the nested RunLoop re-enters TimedEvents on the
    /// same thread.
    /// </summary>
    internal static void StartPump()
    {
        if (_app == null) return;
        try
        {
            _app.AddTimeout(TimeSpan.FromMilliseconds(250), Pump);
            Log.LogStep("Puppet pump started (250ms)", monitor: true);
        }
        catch (Exception ex) { Log.LogStep($"Puppet pump start failed: {ex.Message}"); }
    }

    // Runs on the UI thread every 250 ms: executes queued injections and keeps the
    // screen snapshot fresh. The timer is RE-ARMED FIRST on purpose: dispatching a
    // key can synchronously open a modal dialog (menu item → _app.Run(dlg)), which
    // blocks this callback inside the dialog's nested RunLoop for its whole
    // lifetime. Because the timer is already re-armed, it keeps firing inside that
    // nested loop (TimedEvents is re-entrant on the same thread), so queued
    // injections and the snapshot stay live while the dialog is open.
    private static bool Pump()
    {
        try { _app?.AddTimeout(TimeSpan.FromMilliseconds(250), Pump); }
        catch { /* keep pumping */ }

        try
        {
            int n = 0;
            while (_injections.TryDequeue(out var action))
            {
                n++;
                try { action(); }
                catch (Exception ex) { Log.LogStep($"Puppet injection failed: {ex.Message}"); }
            }
            if (n > 0) Log.LogStep($"Puppet pump: executed {n} queued injection(s)");

            // Hit-test requests are resolved on the UI thread too (same queue discipline:
            // no Application.Invoke from background threads — that deadlocks with dialogs).
            while (_hitTests.TryDequeue(out var h))
            {
                try { h.Tcs.SetResult(HitTestNow(h.Pos)); }
                catch (Exception ex) { h.Tcs.SetResult($"(hit-test error: {ex.Message})"); }
            }

            var top = _app?.TopRunnableView;
            if (top != null)
                _snapshot = _app!.Driver.ToString();
        }
        catch { /* keep the pump alive */ }
        return false;   // already re-armed above
    }

    private static string HitTestNow(System.Drawing.Point pos)
    {
        var top = _app?.TopRunnableView;
        if (top == null) return "(no Terminal.Gui window visible)";
        var views = top.GetViewsUnderLocation(pos, ViewportSettingsFlags.TransparentMouse);
        var sb = new StringBuilder();
        int i = 0;
        foreach (var v in views)
            sb.AppendLine($"{i++}: {v?.GetType().Name} \"{v?.Title}\" {v?.Frame}");
        return sb.Length == 0 ? "(no view under this point)" : sb.ToString().TrimEnd();
    }

    /// <summary>
    /// Returns the latest screen capture (plain text). The snapshot is refreshed by
    /// the pump on the UI thread, so this never blocks — at most ~250 ms stale.
    /// </summary>
    public static string ANSI_Tui_Capture()
    {
        if (_app == null) return "(puppet mode not initialized)";
        return _snapshot;
    }

    /// <summary>Queues a key-down for the keyboard pipeline, with the matching key-up
    /// ~200 ms later (executed on the UI thread).</summary>
    /// <remarks>
    /// A real key press holds for ~100–300 ms between down and up; controls that
    /// activate on the press→release gesture (buttons, list Accept) can miss an
    /// immediate Down+Up pair fired in the same pump tick. The KeyUp is scheduled
    /// from the UI thread (safe — no TimedEvents.Add from background threads).
    /// </remarks>
    public static void InjectKey(Key key)
    {
        if (_app == null) return;
        _injections.Enqueue(() =>
        {
            _app!.Keyboard.RaiseKeyDownEvent(key);
            _app.AddTimeout(TimeSpan.FromMilliseconds(200), () =>
            {
                _app.Keyboard.RaiseKeyUpEvent(key);
                return false;   // one-shot
            });
        });
    }

    /// <summary>Queues text injection, one character at a time (executed on the UI thread).</summary>
    public static void InjectText(string text)
    {
        if (_app == null || string.IsNullOrEmpty(text)) return;
        foreach (var ch in text)
            _injections.Enqueue(() =>
            {
                var key = (Key)ch;
                _app!.Keyboard.RaiseKeyDownEvent(key);
                _app.Keyboard.RaiseKeyUpEvent(key);
            });
    }

    /// <summary>Queues a mouse event at terminal-relative coordinates (executed on the UI thread).</summary>
    public static void InjectMouse(int x, int y, MouseFlags flags)
    {
        if (_app == null) return;
        _injections.Enqueue(() =>
        {
            // Only ScreenPosition is set: the mouse router resolves View and the
            // view-relative Position itself from the screen coordinates.
            _app!.Mouse.RaiseMouseEvent(new Mouse
            {
                ScreenPosition = new System.Drawing.Point(x, y),
                Flags = flags,
            });
        });
    }

    /// <summary>
    /// Hit-tests a screen coordinate and returns the views stacked under it (deepest
    /// last), so a tester can see exactly which control will receive a mouse event
    /// before sending it. Resolved by the pump on the UI thread (never blocks on the
    /// TimedEvents lock — see the pump design note above).
    /// </summary>
    public static string HitTest(int x, int y)
    {
        if (_app == null) return "(puppet mode not initialized)";
        var tcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
        _hitTests.Enqueue((new System.Drawing.Point(x, y), tcs));
        return tcs.Task.GetAwaiter().GetResult();
    }
}