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 AIOrchestrator.API;
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;
// The agent reporting tool (malfunction reports / feature requests as GitHub issues) —
// short alias so the Help-menu toggle reads cleanly.
using MalfunctionReporterTool = AIOrchestrator.API.MalfunctionReporterTool;

// ═══════════════════════════════════════════════════════════════════════
//  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 ChatRoleColorizer? _chatColorizer;
        private int _inputLines = 1;
        private Scheme _baseScheme = new();
        // One color for the user's own words: the chat log repaints user messages with it
        // and the prompt text uses it too, so changing it changes both places.
        private readonly Color _userTextColor;
        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 = "";
        // Next-prompt suggestion: shown as ghost text in the empty prompt, Tab accepts it.
        // Requested from /v1/suggest after a successful reply only when the feature is on;
        // the server enforces the same setting, and clients that never ask pay nothing.
        private string _suggestion = "";
        private int _suggestionGeneration;
        private bool _entryPointShown;
        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;

        // ── Live activity while a chat request is in flight (issue #106) ──
        // The reply text only arrives once the WHOLE agent run is over, so a long task (a
        // presentation is many slow LLM round-trips) looked exactly like a frozen console: an
        // empty "agent" block and no clue about what, if anything, was still happening. The
        // engine reports every tool call on AgentHarness.GlobalProgress, so while a chat runs the
        // current method is mirrored on the status line together with the elapsed seconds —
        // "still working on create_presentation" instead of a bare, unreadable "generating…".
        // Written from the agent thread and read on the UI thread, hence volatile.
        private volatile string _currentActivity = "";
        // The in-flight run's clock (null when idle), driving the elapsed counter. Assigned when
        // the run starts and cleared in its finally, both before/after the UI-thread updates.
        private volatile Stopwatch? _chatStartedAt;
        // No byte at all on the chat stream for this long means the stream is DEAD, not merely
        // slow: the server emits an SSE comment keepalive every 15 s while the agent works, so the
        // default (90 s = six keepalives of complete silence) can never cut short a legitimately
        // slow tool. Before this there was no cap whatsoever on the wait (Timeout.InfiniteTimeSpan
        // on purpose, so a long job was never interrupted) — and that meant a wedged run held the
        // console hostage: _chatRunning stayed 1, every later prompt was refused, and only
        // restarting the program helped.
        // Settable through the environment so the wait can be tuned — and tested — without a
        // rebuild; 0/false/off/no disables the watchdog and restores the old wait-forever behaviour.
        internal const string ChatStallEnvVar = "AGENTBRIDGE_CHAT_STALL_SECONDS";
        private static readonly TimeSpan ChatStreamStallTimeout = ResolveChatStreamStallTimeout();

        private static TimeSpan ResolveChatStreamStallTimeout()
        {
            var raw = Environment.GetEnvironmentVariable(ChatStallEnvVar)?.Trim();
            if (string.IsNullOrEmpty(raw)) return TimeSpan.FromSeconds(90);
            if (raw.Equals("0", StringComparison.Ordinal)
                || raw.Equals("false", StringComparison.OrdinalIgnoreCase)
                || raw.Equals("off", StringComparison.OrdinalIgnoreCase)
                || raw.Equals("no", StringComparison.OrdinalIgnoreCase))
                return System.Threading.Timeout.InfiniteTimeSpan;
            return double.TryParse(raw, System.Globalization.CultureInfo.InvariantCulture, out var seconds) && seconds > 0
                ? TimeSpan.FromSeconds(seconds)
                : TimeSpan.FromSeconds(90);
        }

        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.
        // A pending next-prompt suggestion is shown as the prompt's ghost text (see the
        // /v1/suggest request after a reply); Tab accepts it.
        // A pending next-prompt suggestion replaces the generic hint while the prompt is
        // empty: it reads as a watermark and Tab turns it into real text.
        private string PlaceholderText => _suggestion.Length > 0 ? _suggestion : 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),
            // Deterministic scheduler console: never reaches the agent. Lists the tasks and
            // lets the user suspend/reactivate/remove/delete/update/replan them in place.
            new("taskscheduler", "list|suspend <id|name>|reactivate <id|name>|remove <id|name>|delete <id|name>|update <id|name> <instruction>|changeplanning <id|name> [time=HH:mm] [days=Mon,Tue] [interval=hours] [repeat=true|false] [start=yyyy-MM-dd] [end=yyyy-MM-dd] [dayofmonth=N] [dayofyear=N]",
                Dictionary.CmdTaskscheduler, (t, a) => t.TaskSchedulerAsync(a), new[] { "/tasks", "/scheduler" },
                MenuGroup: "settings", MenuTitle: Dictionary.MenuTaskscheduler),
            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()),
            // No menu voice: dedicated state toggle in the Help menu (malfunctionReportItem).
            new("malfunctionreport", "", Dictionary.CmdMalfunctionReport, (t, _) => t.MalfunctionReportAsync()),
        };

        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);

            // Live per-tool activity for the status line while the console waits on a run
            // (issue #106). The process-wide mirror is used on purpose: the TUI is a client of
            // the server in the same process and does not hold the AgentHarness instance itself,
            // so per-instance AgentProgress is not reachable from here.
            AgentHarness.GlobalProgress += OnAgentGlobalProgress;

            // 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);
            // The user's words are celeste in the chat (ChatRoleColorizer) and in the prompt
            // (this scheme): one color variable drives both.
            _userTextColor = MenuBarBackground();
            SchemeManager.AddScheme("Prompt", new Scheme
            {
                Normal = new TuiAttribute(_userTextColor, Color.Black),
                Focus = new TuiAttribute(_userTextColor, Color.Black),
            });
            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,
            });
            if (!string.IsNullOrEmpty(_hostError))
                _history.Add(new Entry { Role = "system", Text = string.Format(Dictionary.HostErrorNote, _hostError) });

            // Warn in the chat when the persisted documents area is no longer usable (the
            // folder was deleted, the drive went offline): the DocumentsPath getter returns
            // the stale value as-is, so probe it here. Non-blocking — the app keeps running
            // and only the document tools are affected until the path is fixed in Settings.
            if (!AIOrchestrator.Setup.IsDocumentsPathUsable(AIOrchestrator.Setup.DocumentsPath, out var docsPathError))
                _history.Add(new Entry { Role = "system", Text = string.Format(Dictionary.DocsPathStartupWarning, docsPathError) });

            // 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;
            // Static event: not detaching would root this instance (and everything it holds)
            // for the lifetime of the process.
            AgentHarness.GlobalProgress -= OnAgentGlobalProgress;
            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);
            });

            // Agent reporting toggle: whether the agent can open malfunction reports and feature
            // requests as GitHub issues (see AIOrchestrator/API/MalfunctionReporterTool.cs).
            // Own persisted gate, independent from the crash-report one above.
            MenuItem malfunctionReportItem = null!;
            malfunctionReportItem = new MenuItem(string.Format(Dictionary.MenuMalfunctionReport, MalfunctionReporterTool.Enabled ? Dictionary.On : Dictionary.Off), Key.Empty, () =>
            {
                MalfunctionReporterTool.Toggle();
                Log.LogStep($"TUI MalfunctionReport toggled: {MalfunctionReporterTool.Enabled}", monitor: true);
                AddNote(MalfunctionReporterTool.Enabled ? Dictionary.NoteMalfunctionReportEnabled : Dictionary.NoteMalfunctionReportDisabled);
                malfunctionReportItem.Title = string.Format(Dictionary.MenuMalfunctionReport, MalfunctionReporterTool.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("taskscheduler"),
                    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,
                    malfunctionReportItem,
                    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() - 2,
                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).
            _chatColorizer = new ChatRoleColorizer(_userTextColor);
            _chatView.LineTransformers.Add(_chatColorizer);
            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,
                SchemeName = "Prompt",
            };
            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 = "Prompt";
            _suggestion = "";
        }

        private void OnInputFocusChanged(object? sender, HasFocusEventArgs e)
        {
            if (e.NewValue)
            {
                // Ghost text (hint or next-prompt suggestion) stays visible in the empty
                // prompt; the caret goes to the start so it reads as a watermark.
                if (_inputPlaceholderActive && _inputField != null)
                    _inputField.CaretOffset = 0;
            }
            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)
        {
            // Tab accepts the suggested next prompt while it is shown as ghost text; every
            // other key dismisses the suggestion (the first keystroke clears the hint below).
            if (key == Key.Tab && _inputPlaceholderActive && _suggestion.Length > 0)
            {
                key.Handled = true;
                _inputField!.Text = _suggestion;
                _inputPlaceholderActive = false;
                _inputField.SchemeName = "Prompt";
                _inputField.CaretOffset = _suggestion.Length;
                _suggestion = "";
                UpdateInputLayout();
                return;
            }

            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;
            var width = ed.Viewport.Width;
            if (width <= 0) return;   // not laid out yet
            var rows = Math.Clamp(EstimateWrapRows(ed.Text ?? "", width, ed.CaretOffset), 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();
        }

        // Visual rows the prompt needs: a faithful port of the Editor's wrap rule (break at
        // the last whitespace before the wrap column, hard-break when there is none) plus
        // the caret's own row. Counting characters alone under-estimated the height — the
        // editor scrolled to the caret and the first wrapped row (the beginning of the text)
        // disappeared, and a full row's caret landed on an empty continuation row.
        private static int EstimateWrapRows(string text, int width, int caret)
        {
            if (text.Length == 0) return 1;
            text = text.Replace("\r\n", "\n");
            caret = Math.Clamp(caret, 0, text.Length);
            var rows = 0;
            var caretRow = 0;
            var lineStart = 0;
            while (true)
            {
                var end = text.IndexOf('\n', lineStart);
                if (end < 0) end = text.Length;
                var line = text[lineStart..end];
                var segments = WrapSegments(line, width);
                var lineRows = Math.Max(1, segments.Count);
                if (caret >= lineStart && caret <= end)
                {
                    var column = caret - lineStart;
                    var index = segments.FindLastIndex(s => s.Start <= column);
                    if (index < 0) index = 0;
                    // A caret at the end of a line that exactly fills the last segment sits
                    // on the empty continuation row the editor draws (and scrolls to).
                    var last = segments[^1];
                    if (column >= line.Length && last.Length > 0 && SegmentWidth(line, last.Start, last.Length) == width)
                        index++;
                    caretRow = rows + index + 1;
                }
                rows += lineRows;
                if (end == text.Length) break;
                lineStart = end + 1;
            }
            return Math.Max(rows, caretRow);
        }

        // Wrap segments of ONE document line, matching Terminal.Gui.Editor's
        // WordWrapStrategy.ComputeSegments (tabs use the default 4-cell indent).
        private static List<(int Start, int Length)> WrapSegments(string line, int wrapColumn)
        {
            var segments = new List<(int, int)>();
            if (wrapColumn <= 0) { segments.Add((0, line.Length)); return segments; }
            var segmentStart = 0;
            while (segmentStart < line.Length)
            {
                var visual = 0;
                var lastWhitespace = -1;
                var current = segmentStart;
                var reachedEnd = false;
                while (current < line.Length)
                {
                    var cellWidth = line[current] == '\t' ? 4 - visual % 4 : 1;
                    if (visual + cellWidth > wrapColumn && current > segmentStart)
                    {
                        if (lastWhitespace >= 0)
                        {
                            segments.Add((segmentStart, lastWhitespace - segmentStart));
                            segmentStart = lastWhitespace;
                            while (segmentStart < line.Length && char.IsWhiteSpace(line[segmentStart])) segmentStart++;
                        }
                        else
                        {
                            segments.Add((segmentStart, current - segmentStart));
                            segmentStart = current;
                        }
                        break;
                    }
                    if (char.IsWhiteSpace(line[current]) && current > segmentStart) lastWhitespace = current + 1;
                    visual += cellWidth;
                    current++;
                    reachedEnd = true;
                }
                if (reachedEnd) { segments.Add((segmentStart, line.Length - segmentStart)); break; }
                if (segmentStart >= line.Length) break;
            }
            if (segments.Count == 0) segments.Add((0, line.Length));
            return segments;
        }

        private static int SegmentWidth(string line, int start, int length)
        {
            var width = 0;
            for (int i = start; i < start + length && i < line.Length; i++)
                width += line[i] == '\t' ? 4 - width % 4 : 1;
            return width;
        }

        // ── 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];
            // The elapsed counter on the status line has to tick while the agent works
            // (issue #106): a run's reply text only arrives at the very end, so without this the
            // line looks frozen even though work is progressing. This timer already runs on the
            // UI loop, so UpdateStatus can be called directly (no Ui() re-marshalling).
            if (Volatile.Read(ref _chatRunning) != 0) UpdateStatus();
        }

        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;
                _inputPlaceholderActive = false;
                _inputField.SchemeName = "Prompt";
                UpdateInputLayout();   // the recalled prompt may wrap: grow before drawing
            }
        }

        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;
            UpdateInputLayout();
        }

        private void Submit()
        {
            var text = (_inputField?.Text ?? "").Trim();
            if (_inputPlaceholderActive || text.Length == 0) return;

            if (text[0] == '/')
            {
                _inputField!.Text = "";
                _inputPlaceholderActive = false;
                _inputField.SchemeName = "Prompt";
                _suggestion = "";
                _followBottom = true;
                Log.LogStep($"TUI submit: {text}");
                RunCommandLine(text);
                return;
            }

            // A chat is already running: the gate at the top of SendChatAsync would drop this
            // prompt, so clearing the field first would silently DESTROY what the user typed —
            // they see nothing happen and lose the message (issue #106: after a long task such as
            // a presentation the console looked stuck on the previous task AND swallowed whatever
            // was typed in the meantime). Keep the text verbatim so it can be sent as soon as
            // the agent is idle, and show why nothing went out.
            if (Volatile.Read(ref _chatRunning) != 0)
            {
                Log.LogStep($"TUI submit ignored, a chat is already running (input kept): {(text.Length > 100 ? text[..100] + "…" : text)}");
                _statusNote = Dictionary.StatusGenerating;
                UpdateStatusUi();
                return;
            }

            _inputField!.Text = "";
            _inputPlaceholderActive = false;
            _inputField.SchemeName = "Prompt";
            _suggestion = "";
            _followBottom = true;
            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();
            // Publish the run's clock and reset the activity shown on the status line (issue #106):
            // the wait now reads "generating… 12s · #2 PresentationTool.create_presentation" as the
            // engine reports each tool call, instead of a static "generating…" with no indication of
            // what is happening or how long it has been going on.
            _currentActivity = "";
            _chatStartedAt = sw;
            // 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`. Reporting
                // tools are normalized to their own gate (see AgentTools.WithReporting).
                var custom = _customTools is { Count: > 0 } ? AgentTools.WithReporting(_customTools.ToArray()) : 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();
                    // Stall watchdog (issue #106). This used to await ReadLineAsync with NO timeout
                    // whatsoever, so if the agent run ever wedged the wait never ended: _chatRunning
                    // stayed 1, every following prompt was refused with "generating…" and the console
                    // could only be freed by closing the program and starting it again — which is
                    // exactly what was reported. The server emits an SSE comment line every 15 s while
                    // the agent works (and any real chunk resets the timer too), so complete silence
                    // for far longer than that means the stream is dead, not merely slow: the answer
                    // can never arrive, and holding the console hostage buys nothing.
                    // ReadLineAsync returns a ValueTask, which can be awaited only once and has
                    // neither WaitAsync nor ContinueWith — AsTask() converts it into a Task that the
                    // timeout race and the later observation (below) can both safely use.
                    var readLine = reader.ReadLineAsync(_chatCts.Token).AsTask();
                    string? line;
                    try
                    {
                        line = await readLine.WaitAsync(ChatStreamStallTimeout, _chatCts.Token);
                    }
                    catch (TimeoutException)
                    {
                        // Observe the abandoned read so its eventual cancellation cannot surface
                        // later as an unobserved task exception.
                        _ = readLine.ContinueWith(t => _ = t.Exception, TaskScheduler.Default);
                        Log.LogStep($"TUI chat: no data on the stream for {(int)ChatStreamStallTimeout.TotalSeconds}s — "
                            + "ending the wait so the console stays usable", monitor: true);
                        _lastFailed = true;
                        FinishChat(new Entry { Role = "agent", Text = Dictionary.StatusStalledEntry, Error = true });
                        _statusNote = Dictionary.StatusStalled;
                        lock (_stateLock) _chatCts?.Cancel();
                        return;
                    }
                    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);
                _ = Task.Run(RequestSuggestionAsync);
            }
            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);
                // The run is over: drop the per-tool activity and the elapsed clock so the next
                // run starts with a clean status line (issue #106).
                _currentActivity = "";
                _chatStartedAt = null;
                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();
            });
        }

        // Asks the server for the prompt the user is most likely to type next (the same
        // feature Qwen Code popularized: ghost text in the prompt, Tab to accept). Runs in
        // the background after a successful reply, and only when the setting is on — the
        // server enforces it too, and clients that never ask (SIP, Telegram) pay nothing.
        private async Task RequestSuggestionAsync()
        {
            if (!AIOrchestrator.Setup.PromptSuggestion) return;
            var generation = Interlocked.Increment(ref _suggestionGeneration);
            try
            {
                var outgoing = new TaskCompletionSource<List<object>>(TaskCreationOptions.RunContinuationsAsynchronously);
                Ui(() => outgoing.TrySetResult(BuildTranscript()));
                var body = JsonSerializer.Serialize(new { messages = await outgoing.Task }, JsonOpts);
                using var resp = await _http.PostAsync("/v1/suggest",
                    new StringContent(body, Encoding.UTF8, "application/json")).WaitAsync(TimeSpan.FromSeconds(30));
                if (!resp.IsSuccessStatusCode) return;
                using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
                var suggestion = GetStr(doc.RootElement, "suggestion") ?? "";
                if (generation != _suggestionGeneration) return;
                Ui(() =>
                {
                    if (suggestion.Length == 0 || _chatRunning != 0) return;
                    _suggestion = suggestion;
                    // Show it only while the prompt is empty: otherwise keep it for later,
                    // but never overwrite what the user is typing.
                    if (_inputField is { } ed && (_inputPlaceholderActive || ed.Text.Length == 0))
                    {
                        SetPlaceholder();
                        ed.CaretOffset = 0;
                    }
                });
            }
            catch { }
        }

        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());
            }
            _chatColorizer?.SetText(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();
            });
        }

        // Startup banner and feedback after a provider/tool change: the chain the product is
        // named after, in two lines — [entry point] <-> AgentBridge <-> [provider] and the
        // tools the agent actually has. This is the one place that shows the endpoint: the
        // startup note and the status bar no longer repeat it.
        private void AddEntryPointNote()
        {
            ProviderConfigs.TryGet(_provider, out var cfg);
            var providerUrl = cfg?.BaseAddress?.ToString().TrimEnd('/') ?? "";
            var provider = providerUrl.Length > 0 ? providerUrl
                : _provider.Length > 0 ? _provider : Dictionary.None;
            var tools = EffectiveLoadedTools().Select(ToolShortName).ToArray();
            var toolsText = tools.Length > 0 ? string.Join(", ", tools) : Dictionary.None;
            var label = Dictionary.StatusTools;
            if (label.Length > 0) label = char.ToUpperInvariant(label[0]) + label[1..];
            // ⟷ is drawn two cells wide by the terminal font (the layout grid counts one),
            // so the cell right after it is swallowed: the second space keeps one visible.
            AddNote($"{_serverUrl} ⟷  AgentBridge ⟷  {provider}\n{label}: {toolsText}");
        }

        // 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 ? "●" : "○" };
            if (_provider.Length > 0) parts.Add(_provider);
            if (_modelName.Length > 0 && !string.Equals(_modelName, _provider)) parts.Add(_modelName);
            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)
            {
                // While the console waits on a run, show what the agent is actually doing and for
                // how long (issue #106) instead of a bare "generating…" that leaves the user
                // guessing whether anything is still happening at all.
                var startedAt = _chatStartedAt;
                var elapsed = startedAt != null ? $" {startedAt.Elapsed.TotalSeconds:0}s" : "";
                var activity = _currentActivity;
                parts.Add(activity.Length > 0
                    ? $"{Dictionary.StatusGeneratingShort}{elapsed} · {activity}"
                    : $"{Dictionary.StatusGeneratingShort}{elapsed}");
            }
            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. Reporting tools are normalized to
        // their own gate in both paths (see AgentTools.WithReporting).
        private string[] EffectiveTools() => _customTools is { Count: > 0 }
            ? AgentTools.WithReporting(_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 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);

        // Live per-tool activity for the status line while the console waits on a run (issue #106).
        // Fires on the agent's own thread, so only the volatile field is touched here — the UI-thread
        // spinner tick (100 ms) is what repaints the status line from it, exactly like the spinner
        // glyph itself. Only the tool-call events carry a name worth showing; Running/Completed/Failed
        // add nothing the waiting user can act on.
        private void OnAgentGlobalProgress(object? sender, AgentHarness.AgentProgressEventArgs e)
        {
            if (Volatile.Read(ref _chatRunning) == 0) return;
            if (e.State != AgentHarness.AgentState.Iteration || string.IsNullOrWhiteSpace(e.MethodName)) return;
            _currentActivity = $"#{e.Iteration} {e.MethodName}";
        }

        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(Color userColor) : IVisualLineTransformer
        {
            private const string UserRole = "user";
            private const string AttachmentRole = "attachment";
            private TuiAttribute? _userAttribute;
            private TuiAttribute? _attachmentAttribute;
            private string[] _roles = [];

            /// <summary>Roles for the document just written to the chat log. Called once per
            /// rebuild: deriving them inside <see cref="Transform"/> re-read the WHOLE document
            /// for every visible line on every redraw, which made typing lag on long chats.</summary>
            public void SetText(string text) => _roles = ComputeRoles(text);

            public void Transform(CellVisualLine line)
            {
                int index = line.DocumentLine.LineNumber - 1;
                if (index < 0 || index >= _roles.Length) return;
                if (_roles[index] == UserRole)
                {
                    _userAttribute ??= new TuiAttribute(userColor, Color.Black);
                    foreach (CellVisualLineElement element in line.Elements)
                        element.Attribute = _userAttribute.Value;
                }
                else if (_roles[index] == AttachmentRole)
                {
                    _attachmentAttribute ??= new TuiAttribute(Color.BrightYellow, Color.Black);
                    foreach (CellVisualLineElement element in line.Elements)
                        element.Attribute = _attachmentAttribute.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)
            {
                // Attachment lines are matched from the same localized resources AppendEntry
                // writes, so detection stays correct in every language: the marker is
                // "<prefix>{0}", the hint is a fixed line.
                var marker = Dictionary.ChatAttachmentMarker ?? "";
                int placeholder = marker.IndexOf("{0}", StringComparison.Ordinal);
                var markerPrefix = placeholder >= 0 ? marker[..placeholder] : marker;
                var hint = Dictionary.ChatAttachmentHint ?? "";

                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;
                    if ((markerPrefix.Length > 0 && line.StartsWith(markerPrefix, StringComparison.Ordinal))
                        || (hint.Length > 0 && line.SequenceEqual(hint)))
                        roles.Add(AttachmentRole);
                    else
                        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 MalfunctionReportAsync()
        {
            MalfunctionReporterTool.Toggle();
            AddNote(MalfunctionReporterTool.Enabled ? Dictionary.NoteMalfunctionReportEnabled : Dictionary.NoteMalfunctionReportDisabled);
            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.Accepting += async (_, e) =>
            {
                // By design, Terminal.Gui forwards unhandled Accept actions to the dialog,
                // which can close it and raise its own events. Handle the action here so
                // this handler controls validation, saving, and when the dialog closes.
                e.Handled = true;
                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 };
            OnButtonClicked(reload, 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 };
            OnButtonClicked(answerBtn, 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 };
            OnButtonClicked(callBtn, 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 };
            OnButtonClicked(hangupBtn, 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();
            }
            OnButtonClicked(sendBtn, () => 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 };

            OnButtonClicked(allowBtn, 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
            });
            OnButtonClicked(disallowBtn, 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
            });
            OnButtonClicked(configBtn, () => { Log.LogStep("TUI /telegram: Mostra configurazione"); RunCommandByName("telegram", "config"); });
            OnButtonClicked(reloadBtn, () => { Log.LogStep("TUI /telegram: Ricarica configurazione", monitor: true); RunCommandByName("telegram", "config reload"); });
            OnButtonClicked(toggleBtn, 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 };
            OnButtonClicked(ok, () => { result = (field.Text ?? "").Trim(); _app.RequestStop(dlg); });
            var cancel = new Button { Text = Dictionary.Cancel };
            OnButtonClicked(cancel, () => _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<bool> 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 false; }
                    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 false;
                }
                if (providers.Count == 0) { AddNote(Dictionary.NoteNoProviders); return false; }
                var pick = await PickProviderOnUiThreadAsync(Dictionary.PickSwitchProvider, providers);
                if (pick == null) return false;   // Esc → cancel
                name = pick.Trim();
            }

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

            AddNote(string.Format(Dictionary.NoteSwitchingProvider, name));
            var body = JsonSerializer.Serialize(new { session_id = _sessionId, llm_provider = name }, JsonOpts);
            try
            {
                using var resp2 = await _http.PostAsync("/v1/control", new StringContent(body, Encoding.UTF8, "application/json"));
                if (!resp2.IsSuccessStatusCode)
                {
                    AddNote(string.Format(Dictionary.NoteSwitchRefused, (int)resp2.StatusCode, await ReadErrorAsync(resp2)));
                    return false;
                }
            }
            catch (Exception ex)
            {
                // A switch is a server mutation: without the server the session keeps the
                // previous provider, so a failure must never be reported as success.
                AddNote(string.Format(Dictionary.NoteServerUnreachable, ex.Message));
                return false;
            }
            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();
            return true;
        }

        // 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). Returns false (and says why)
        // when the server did not accept it, so the caller never reports a save that the
        // running process refused.
        private async Task<bool> 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) return true;
                AddNote(string.Format(Dictionary.NoteSetDefaultFailedHttp, (int)resp.StatusCode, await ReadErrorAsync(resp)));
                return false;
            }
            catch (HttpRequestException ex)
            {
                // providers.json is already written; the running process simply cannot be told.
                AddNote(string.Format(Dictionary.NoteSetDefaultUnreachable, ex.Message));
                return false;
            }
            catch (Exception ex)
            {
                AddNote(string.Format(Dictionary.NoteSetDefaultFailed, ex.Message));
                return false;
            }
        }

        // Applies the provider panel's selection to the running server: the session switch and
        // the process default are two mutations of the same endpoint, so they run in order and
        // the success note appears only after both were accepted.
        private async Task ApplyProviderSelectionAsync(string chosen)
        {
            if (!string.Equals(chosen, _provider, StringComparison.OrdinalIgnoreCase)
                && !await SwitchModelAsync(chosen))
                return;   // SwitchModelAsync already reported the reason
            if (await SetDefaultProviderAsync(chosen))
                AddNote(string.Format(Dictionary.SetupActiveProviderSaved, chosen));
        }

        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();
            AddEntryPointNote();
        }

        // ── /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();
            // Reporting tools are not checklist rows: they have their own dedicated toggle
            // (Help → Malfunction reports) and are force-included in the combination when
            // active — like the core tools above, the checklist cannot contradict that gate.
            var toggleable = catalog.Where(c => !AgentTools.CoreTools.Contains(c.Name) && !AgentTools.ReportingTools.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);
            // Reporting tools follow their own gate, not the checklist (see AgentTools.WithReporting).
            marked = AgentTools.WithReporting(marked.ToArray()).ToList();
            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();
            AddEntryPointNote();    // feedback: which tools the agent now actually has

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

        // ── /taskscheduler: deterministic scheduler console ──
        // Slash commands never reach the agent: this one reads and changes the TaskSchedulerTool
        // state in-process and prints a table, so the user has direct control over the planned work.
        private Task TaskSchedulerAsync(string args)
        {
            var tool = new AIOrchestrator.API.TaskSchedulerTool();
            var rest = args.Trim();
            var sub = TakeToken(ref rest).ToLowerInvariant();
            if (sub.Length == 0 || sub is "list" or "ls")
            {
                ShowTasksTable(tool);
                return Task.CompletedTask;
            }
            if (sub is "help" or "?" or "h")
            {
                AddNote(Dictionary.TaskschedulerUsage);
                return Task.CompletedTask;
            }

            var token = TakeToken(ref rest);
            var name = ResolveTask(tool, token, out var notFound);
            if (name == null) { AddNote(notFound); return Task.CompletedTask; }

            string result;
            switch (sub)
            {
                case "suspend":
                    result = tool.SuspendTask(name);
                    AddNote(IsError(result) ? result : string.Format(Dictionary.TaskschedulerSuspendedNote, name));
                    break;
                case "reactivate" or "reactive" or "reactiva" or "resume" or "enable":
                    result = tool.ResumeTask(name);
                    AddNote(IsError(result) ? result : string.Format(Dictionary.TaskschedulerResumedNote, name));
                    break;
                case "remove":
                    result = tool.RemoveTask(name);
                    AddNote(IsError(result) ? result : string.Format(Dictionary.TaskschedulerRemovedNote, name));
                    break;
                case "delete":
                    result = tool.DeleteTask(name);
                    AddNote(IsError(result) ? result : string.Format(Dictionary.TaskschedulerDeletedNote, name));
                    break;
                case "update":
                    if (rest.Length == 0) { AddNote(Dictionary.TaskschedulerUsage); return Task.CompletedTask; }
                    result = tool.UpdateTask(name, rest);
                    AddNote(IsError(result) ? result : string.Format(Dictionary.TaskschedulerUpdatedNote, name));
                    break;
                case "changeplanning":
                    AddNote(ChangePlanning(tool, name, rest));
                    break;
                default:
                    AddNote(Dictionary.TaskschedulerUsage);
                    return Task.CompletedTask;
            }
            ShowTasksTable(tool);
            return Task.CompletedTask;
        }

        private void ShowTasksTable(AIOrchestrator.API.TaskSchedulerTool tool)
        {
            using var doc = JsonDocument.Parse(tool.GetTasksJson());
            var rows = doc.RootElement.EnumerateArray().ToList();
            if (rows.Count == 0) { AddNote(Dictionary.TaskschedulerEmpty); return; }

            // Widths come from the chat viewport: the instruction column takes what is left,
            // so no row wraps and the columns stay aligned at any window size.
            var width = Math.Max(64, (_chatView?.Viewport.Width ?? 100) - 1);
            var nameWidth = Math.Clamp(width / 5, 12, 22);
            var recurrenceWidth = Math.Clamp(width / 5, 12, 24);
            var fixedWidth = 3 + 16 + 9 + 5;   // ID, next run, state and the five separators
            var instructionWidth = width - fixedWidth - nameWidth - recurrenceWidth;
            if (instructionWidth < 14)
            {
                recurrenceWidth = Math.Max(10, recurrenceWidth - (14 - instructionWidth));
                instructionWidth = width - fixedWidth - nameWidth - recurrenceWidth;
            }

            var sb = new StringBuilder();
            sb.Append(Cell(Dictionary.TaskschedulerColId, 3, right: true)).Append(' ')
              .Append(Cell(Dictionary.TaskschedulerColTask, nameWidth)).Append(' ')
              .Append(Cell(Dictionary.TaskschedulerColNext, 16)).Append(' ')
              .Append(Cell(Dictionary.TaskschedulerColRecurrence, recurrenceWidth)).Append(' ')
              .Append(Cell(Dictionary.TaskschedulerColState, 9)).Append(' ')
              .Append(Cell(Dictionary.TaskschedulerColInstruction, instructionWidth)).Append('\n');

            var id = 0;
            foreach (var row in rows)
            {
                id++;
                sb.Append(Cell(id.ToString(), 3, right: true)).Append(' ')
                  .Append(Cell(GetStr(row, "name") ?? "", nameWidth)).Append(' ')
                  .Append(Cell(GetStr(row, "nextRunAt") ?? Dictionary.None, 16)).Append(' ')
                  .Append(Cell(DescribeRecurrence(row), recurrenceWidth)).Append(' ')
                  .Append(Cell(GetBool(row, "suspended") ? Dictionary.TaskschedulerSuspended : Dictionary.TaskschedulerActive, 9)).Append(' ')
                  .Append(Cell((GetStr(row, "instruction") ?? "").Replace('\n', ' ').Trim(), instructionWidth))
                  .Append('\n');
            }
            sb.Append('\n').Append(Dictionary.TaskschedulerHint);
            AddNote(sb.ToString());
        }

        private static string DescribeRecurrence(JsonElement row)
        {
            var time = GetStr(row, "executionTime") ?? "00:00";
            string text;
            if (row.TryGetProperty("intervalHours", out var interval) && interval.ValueKind == JsonValueKind.Number)
                text = string.Format(Dictionary.TaskschedulerEveryHours, interval.GetDouble().ToString("0.##"));
            else if (row.TryGetProperty("dayOfYear", out var doy) && doy.ValueKind == JsonValueKind.Number)
                text = string.Format(Dictionary.TaskschedulerDayOfYear, doy.GetInt32(), time);
            else if (row.TryGetProperty("dayOfMonth", out var dom) && dom.ValueKind == JsonValueKind.Number)
                text = string.Format(Dictionary.TaskschedulerDayOfMonth, dom.GetInt32(), time);
            else if (row.TryGetProperty("daysOfWeek", out var days) && days.ValueKind == JsonValueKind.Array && days.GetArrayLength() > 0)
                text = string.Format(Dictionary.TaskschedulerOnDays,
                    string.Join(",", days.EnumerateArray().Select(d => ShortDay(d.GetString() ?? ""))), time);
            else if (GetBool(row, "repeat"))
                text = string.Format(Dictionary.TaskschedulerDaily, time);
            else
                text = Dictionary.TaskschedulerOnce;
            var start = GetStr(row, "startDate");
            var end = GetStr(row, "endDate");
            if (start != null || end != null)
                text += " " + string.Format(Dictionary.TaskschedulerRange, start ?? "…", end ?? "…");
            return text;
        }

        private static string ShortDay(string day) => day.Length >= 3 ? day[..3] : day;

        private static string? ResolveTask(AIOrchestrator.API.TaskSchedulerTool tool, string token, out string message)
        {
            message = token.Length == 0 ? Dictionary.TaskschedulerUsage : string.Format(Dictionary.TaskschedulerNotFound, token);
            if (token.Length == 0) return null;
            using var doc = JsonDocument.Parse(tool.GetTasksJson());
            var names = doc.RootElement.EnumerateArray()
                .Select(e => GetStr(e, "name") ?? "").Where(n => n.Length > 0).ToList();
            // A numeric token is the ID shown in the table (1-based, sorted by name).
            if (int.TryParse(token, out var id) && id >= 1 && id <= names.Count) return names[id - 1];
            return names.FirstOrDefault(n => string.Equals(n, token, StringComparison.Ordinal))
                ?? names.FirstOrDefault(n => string.Equals(n, token, StringComparison.OrdinalIgnoreCase));
        }

        // changeplanning merges key=value options into the current schedule: only the keys
        // given change. dayofmonth/dayofyear/days are mutually exclusive, like schedule_task.
        private static string ChangePlanning(AIOrchestrator.API.TaskSchedulerTool tool, string name, string options)
        {
            if (string.IsNullOrWhiteSpace(options)) return Dictionary.TaskschedulerUsage;
            using var doc = JsonDocument.Parse(tool.GetTaskDefinitionJson(name));
            var def = doc.RootElement;
            if (def.TryGetProperty("error", out _)) return string.Format(Dictionary.TaskschedulerNotFound, name);

            TimeOnly? time = TimeOnly.TryParse(GetStr(def, "executionTime") ?? "", out var t) ? t : null;
            var days = DaysOfWeek.None;
            if (def.TryGetProperty("daysOfWeek", out var daysEl) && daysEl.ValueKind == JsonValueKind.Array)
                foreach (var day in daysEl.EnumerateArray())
                    if (Enum.TryParse<DaysOfWeek>(day.GetString(), true, out var flag)) days |= flag;
            int? dayOfMonth = IntOrNull(def, "dayOfMonth");
            int? dayOfYear = IntOrNull(def, "dayOfYear");
            TimeSpan? interval = def.TryGetProperty("intervalHours", out var iv) && iv.ValueKind == JsonValueKind.Number
                ? TimeSpan.FromHours(iv.GetDouble()) : null;
            var repeat = GetBool(def, "repeat");
            DateTime? start = DateTime.TryParse(GetStr(def, "startDate"), out var s) ? s : null;
            DateTime? end = DateTime.TryParse(GetStr(def, "endDate"), out var e) ? e : null;

            foreach (var option in options.Split(' ', StringSplitOptions.RemoveEmptyEntries))
            {
                var eq = option.IndexOf('=');
                if (eq <= 0) return Dictionary.TaskschedulerUsage;
                var key = option[..eq].ToLowerInvariant();
                var value = option[(eq + 1)..];
                switch (key)
                {
                    case "time":
                        if (!TimeOnly.TryParse(value, out var newTime)) return Dictionary.TaskschedulerUsage;
                        time = newTime;
                        break;
                    case "days":
                        if (!TryParseDays(value, out days)) return Dictionary.TaskschedulerUsage;
                        if (days != DaysOfWeek.None)
                        { dayOfMonth = null; dayOfYear = null; interval = null; }
                        break;
                    case "dayofmonth":
                        if (value is "none" or "off") { dayOfMonth = null; break; }
                        if (!int.TryParse(value, out var dom)) return Dictionary.TaskschedulerUsage;
                        dayOfMonth = dom;
                        dayOfYear = null;
                        days = DaysOfWeek.None;
                        interval = null;
                        break;
                    case "dayofyear":
                        if (value is "none" or "off") { dayOfYear = null; break; }
                        if (!int.TryParse(value, out var doy)) return Dictionary.TaskschedulerUsage;
                        dayOfYear = doy;
                        dayOfMonth = null;
                        days = DaysOfWeek.None;
                        interval = null;
                        break;
                    case "interval":
                        // interval=none returns to a date-based schedule (intervalHours has
                        // the highest precedence, so it must be removable).
                        if (value is "none" or "off") { interval = null; break; }
                        if (!double.TryParse(value, System.Globalization.NumberStyles.Float,
                                System.Globalization.CultureInfo.InvariantCulture, out var hours) || hours <= 0)
                            return Dictionary.TaskschedulerUsage;
                        interval = TimeSpan.FromHours(hours);
                        dayOfMonth = null;
                        dayOfYear = null;
                        days = DaysOfWeek.None;
                        break;
                    case "repeat":
                        repeat = value is "true" or "1" or "on" or "yes";
                        break;
                    case "start":
                        if (!DateTime.TryParse(value, out var newStart)) return Dictionary.TaskschedulerUsage;
                        start = newStart;
                        break;
                    case "end":
                        if (!DateTime.TryParse(value, out var newEnd)) return Dictionary.TaskschedulerUsage;
                        end = newEnd;
                        break;
                    default:
                        return Dictionary.TaskschedulerUsage;
                }
            }
            var result = tool.ChangePlanning(name, time, days, dayOfMonth, dayOfYear, interval, repeat, start, end);
            return IsError(result) ? result : string.Format(Dictionary.TaskschedulerPlanningNote, name);
        }

        private static bool TryParseDays(string value, out DaysOfWeek days)
        {
            days = DaysOfWeek.None;
            foreach (var raw in value.Split(',', StringSplitOptions.RemoveEmptyEntries))
            {
                var part = raw.Trim();
                if (part.Equals("weekdays", StringComparison.OrdinalIgnoreCase)) { days |= DaysOfWeek.Weekdays; continue; }
                if (part.Equals("weekend", StringComparison.OrdinalIgnoreCase)) { days |= DaysOfWeek.Weekend; continue; }
                if (part.Equals("all", StringComparison.OrdinalIgnoreCase) || part.Equals("daily", StringComparison.OrdinalIgnoreCase))
                { days = DaysOfWeek.All; continue; }
                if (part.Equals("none", StringComparison.OrdinalIgnoreCase)) { days = DaysOfWeek.None; continue; }
                var flag = Enum.GetValues<DaysOfWeek>()
                    .FirstOrDefault(d => d != DaysOfWeek.None && d.ToString().StartsWith(part, StringComparison.OrdinalIgnoreCase));
                if (flag == DaysOfWeek.None) return false;
                days |= flag;
            }
            return true;
        }

        private static int? IntOrNull(JsonElement element, string name) =>
            element.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number ? value.GetInt32() : null;

        private static bool IsError(string result) => result.StartsWith("Error", StringComparison.Ordinal);

        // First whitespace-delimited token; a leading "..." groups a name containing spaces.
        private static string TakeToken(ref string rest)
        {
            rest = rest.TrimStart();
            if (rest.Length == 0) return "";
            if (rest[0] == '"')
            {
                var close = rest.IndexOf('"', 1);
                if (close > 0)
                {
                    var quoted = rest[1..close];
                    rest = rest[(close + 1)..].TrimStart();
                    return quoted;
                }
            }
            var space = rest.IndexOf(' ');
            if (space < 0) { var whole = rest; rest = ""; return whole; }
            var token = rest[..space];
            rest = rest[(space + 1)..].TrimStart();
            return token;
        }

        // One fixed-width table cell: pad to the column, or cut with an ellipsis so a long
        // value never pushes the following columns out of line.
        private static string Cell(string text, int width, bool right = false) =>
            text.Length > width
                ? (right ? "…" + text[^(width - 1)..] : text[..(width - 1)] + "…")
                : (right ? text.PadLeft(width) : text.PadRight(width));

        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 = "Prompt";
                        _inputField.CaretOffset = _inputField.Document?.TextLength ?? 0;
                        UpdateInputLayout();
                    });
                    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 };
            OnButtonClicked(setBtn, () =>
            {
                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 };
            OnButtonClicked(resetBtn, () =>
            {
                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 };
            OnButtonClicked(addBtn, 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 };
            OnButtonClicked(toggleBtn, () =>
            {
                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 };
            OnButtonClicked(removeBtn, 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.

        // Wires an action to a Button that lives INSIDE a dialog body (not in the footer
        // button row). Terminal.Gui v2 raises Accepting first and, when nothing handles it,
        // bubbles the Accept up to the Dialog — which closes itself — so a handler attached
        // only to Accepted never runs and the panel just disappears on click (issue #94:
        // "Add", "Edit" and "Remove" did nothing). Marking Accepting handled stops the
        // bubble and runs the action, for both mouse clicks and Enter. Footer buttons added
        // with Dialog.AddButton take the default-button path and are unaffected.
        private static void OnButtonClicked(Button btn, Action action)
        {
            btn.Accepting += (_, e) =>
            {
                e.Handled = true;
                action();
            };
        }

        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.
        // LLM / Provider panel — simplified to a single DropDownList for provider selection.
        // The dropdown is the ONLY way to pick the active provider; the previously redundant
        // "Configured providers" ListView has been removed. The selected provider in the
        // dropdown is what Save activates (persisted as default + adopted by the running chat).
        // The API key field always corresponds to the provider shown in the dropdown.
        private void ShowProvidersPanel()
        {
            Log.LogStep("TUI Providers panel opened", monitor: true);
            var dlg = new Dialog
            {
                Title = Dictionary.SetupLlmTab,
                Width = Dim.Percent(80),
                // Compact layout: provider dropdown, active model, API key, validation,
                // Add/Edit/Remove buttons, and the Save/Close footer.
                Height = 14,
                SchemeName = "Dark",
            };

            var providerDropdown = new DropDownList { ReadOnly = true };

            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 selected in the dropdown, editable right here.
            // Save writes the edited value back for the dropdown-selected provider
            // through the single key-mutation path (ProviderConfigs.SetApiKey).
            // Local providers simply leave it empty.
            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 };
            dlg.Add(apiKeyField);

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

            // Add/Edit/Remove buttons for managing the provider list.
            int y = 5;
            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);

            // The dropdown's ValueChanged updates the model label and the API key field.
            providerDropdown.ValueChanged += (_, _) =>
            {
                UpdateActiveModelLabel();
                LoadApiKeyForSelection();
            };

            void UpdateActiveModelLabel()
            {
                var sel = ProviderConfigs.All.FirstOrDefault(p =>
                    string.Equals(p.ProviderName, providerDropdown.Text, StringComparison.OrdinalIgnoreCase));
                // The configuration wins over the session's cached model name: the server
                // reloads the provider config before every chat, so the file is what the
                // next run executes (a just-edited model must show up immediately).
                if (sel != null && !string.IsNullOrWhiteSpace(sel.ModelName))
                    activeModelLabel.Text = string.Format(Dictionary.SetupActiveModel, sel.ModelName);
                else if (sel != null && string.Equals(sel.ProviderName, _provider, StringComparison.OrdinalIgnoreCase)
                    && !string.IsNullOrWhiteSpace(_modelName))
                    activeModelLabel.Text = string.Format(Dictionary.SetupActiveModel, _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;
                UpdateActiveModelLabel();
                LoadApiKeyForSelection();
            }

            // Loads the current API key for the dropdown-selected provider into the key field.
            void LoadApiKeyForSelection()
            {
                var name = providerDropdown.Text;
                apiKeyField.Text = !string.IsNullOrWhiteSpace(name)
                    && ProviderConfigs.TryGet(name, out var cfg) && cfg != null
                    ? cfg.ApiKey ?? ""
                    : "";
            }

            RefreshProviders();

            // Open the shared provider form (Add when name is null) on the NEXT loop
            // iteration. Running a modal dialog from inside this button's click handler let
            // the same click reach the new dialog's default button, so Edit looked like it
            // did nothing and Add closed the panel: the deferred call has no click in flight.
            void OpenProviderEditor(string? name)
            {
                _app.AddTimeout(TimeSpan.Zero, () =>
                {
                    ProviderConfig? existing = null;
                    if (name != null)
                    {
                        if (!ProviderConfigs.TryGet(name, out existing)) { AddNote(Dictionary.SetupSelectToEdit); return false; }
                    }
                    var cfg = ShowProviderDialog(existing);
                    if (cfg == null) return false;
                    if (existing == null)
                    {
                        if (ProviderConfigs.Add(cfg, persist: true))
                            AddNote(string.Format(Dictionary.SetupProviderAdded, cfg.ProviderName));
                        else
                            AddNote(string.Format(Dictionary.SetupProviderExists, cfg.ProviderName));
                    }
                    else
                    {
                        ProviderConfigs.Upsert(cfg, persist: true);
                        AddNote(string.Format(Dictionary.SetupProviderUpdated, cfg.ProviderName));
                    }
                    RefreshProviders();
                    providerDropdown.Text = cfg.ProviderName;
                    UpdateActiveModelLabel();
                    LoadApiKeyForSelection();
                    return false;
                });
            }

            OnButtonClicked(addBtn, () =>
            {
                Log.LogStep("TUI Providers: Add provider button", monitor: true);
                OpenProviderEditor(null);
            });
            OnButtonClicked(editBtn, () =>
            {
                // Edit the provider currently shown in the dropdown.
                var name = providerDropdown.Text;
                if (string.IsNullOrWhiteSpace(name)) { AddNote(Dictionary.SetupSelectToEdit); return; }
                Log.LogStep($"TUI Providers: Edit provider '{name}'", monitor: true);
                OpenProviderEditor(name);
            });
            OnButtonClicked(removeBtn, () =>
            {
                var name = providerDropdown.Text;
                if (string.IsNullOrWhiteSpace(name)) { 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 (string.Equals(providerDropdown.Text, name, StringComparison.OrdinalIgnoreCase))
                {
                    providerDropdown.Text = ProviderConfigs.Default.ProviderName;
                    _ = SwitchModelAsync(ProviderConfigs.Default.ProviderName);
                }
                RefreshProviders();
            });

            var save = new Button { Text = Dictionary.SetupSave, IsDefault = true };
            save.Accepting += (_, e) =>
            {
                // By design, Terminal.Gui forwards unhandled Accept actions to the dialog,
                // which can close it and raise its own events. Handle the action here so
                // this handler controls validation, saving, and when the dialog closes.
                e.Handled = true;
                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 dropdown-selected provider.
                if (ProviderConfigs.TryGet(chosen, out var chosenCfg) && chosenCfg != null)
                {
                    var newKey = (apiKeyField.Text ?? "").Trim();
                    if (!string.Equals(newKey, chosenCfg.ApiKey ?? "", StringComparison.Ordinal))
                        ProviderConfigs.SetApiKey(chosen, 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);
                Log.LogStep($"TUI Providers saved (active: {chosen})", monitor: true);
                _app.RequestStop(dlg);
                _ = ApplyProviderSelectionAsync(chosen);
            };
            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.Accepting += (sender, e) =>
            {
                // By design, Terminal.Gui forwards unhandled Accept actions to the dialog,
                // which can close it and raise its own events. Handle the action here so
                // this handler controls validation, saving, and when the dialog closes.
                e.Handled = true;
                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,
            };
            // Next-prompt suggestion: the server only computes it when a client asks
            // (/v1/suggest) and this flag is on, so SIP/Telegram chats never pay for it.
            var suggestion = new CheckBox
            {
                Text = Dictionary.SetupPromptSuggestion,
                Value = AIOrchestrator.Setup.PromptSuggestion ? CheckState.Checked : CheckState.UnChecked,
                X = 1, Y = 2,
            };
            var docsPath = AddField(dlg, Dictionary.SetupDocumentsPath, AIOrchestrator.Setup.DocumentsPath, 4);
            var pathErr = new Label { Text = "", X = 1, Y = 5, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            dlg.Add(logEnabled, autoStart, suggestion, pathErr);

            var save = new Button { Text = Dictionary.SetupSave, IsDefault = true };
            save.Accepting += (_, e) =>
            {
                // By design, Terminal.Gui forwards unhandled Accept actions to the dialog,
                // which can close it and raise its own events. Handle the action here so
                // this handler controls validation, saving, and when the dialog closes.
                e.Handled = true;
                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);
                AIOrchestrator.Setup.PromptSuggestion = suggestion.Value == CheckState.Checked;
                AIOrchestrator.Setup.Save();
                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();
        }

        // ONE form for Add and Edit (dual mode): Add shows an editable name at the top,
        // Edit shows the provider being edited there instead. Every configurable field of
        // ProviderConfig is exposed, each with a one-line description, so the panel can set
        // whatever the provider needs (context window, endpoint, cache, extra body...).
        private ProviderConfig? ShowProviderDialog(ProviderConfig? existing)
        {
            var adding = existing == null;
            var dlg = new Dialog
            {
                Title = adding ? Dictionary.ProviderAddTitle : string.Format(Dictionary.ProviderEditTitle, existing!.ProviderName),
                Width = Dim.Percent(94),
                Height = 21,
                SchemeName = "Dark",
            };
            int y = 0;
            TextField? nameField = null;
            if (adding)
            {
                nameField = AddFormField(dlg, Dictionary.ProviderName, null, Dictionary.ProviderDescrName, ref y);
            }
            else
            {
                dlg.Add(new Label
                {
                    Text = string.Format(Dictionary.ProviderEditing, existing!.ProviderName),
                    X = 1, Y = y++, Width = Dim.Fill() - 2, SchemeName = "Hint",
                });
            }
            var protocol = new DropDownList
            {
                ReadOnly = true,
                X = FormFieldX, Y = y, Width = FormFieldWidth,
                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,
                new Label { Text = Dictionary.ProviderDescrProtocol, X = FormNoteX, Y = y, Width = Dim.Fill() - FormNoteX, SchemeName = "Hint" });
            y++;
            var modelField = AddFormField(dlg, Dictionary.ProviderModel, existing?.ModelName, Dictionary.ProviderDescrModel, ref y);
            var baseField = AddFormField(dlg, Dictionary.ProviderBaseAddress, existing?.BaseAddress.ToString(), Dictionary.ProviderDescrBaseAddress, ref y);
            var endPointField = AddFormField(dlg, Dictionary.ProviderEndpoint, existing?.EndPoint, Dictionary.ProviderDescrEndpoint, ref 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 = AddFormField(dlg, Dictionary.ProviderApiKey, existing?.ApiKey, Dictionary.ProviderDescrApiKey, ref y, secret: true);
            var ctxField = AddFormField(dlg, Dictionary.ProviderContextWindow, (existing?.ContextWindow ?? 32768).ToString(), Dictionary.ProviderDescrContextWindow, ref y);
            var timeoutField = AddFormField(dlg, Dictionary.ProviderTimeout, ((int)(existing?.Timeout.TotalSeconds ?? 30)).ToString(), Dictionary.ProviderDescrTimeout, ref y);
            var pauseField = AddFormField(dlg, Dictionary.ProviderPause, ((int)(existing?.PauseBetweenRequests.TotalSeconds ?? 0)).ToString(), Dictionary.ProviderDescrPause, ref y);
            var cacheType = new DropDownList
            {
                ReadOnly = true,
                X = FormFieldX, Y = y, Width = FormFieldWidth,
                Source = new ListWrapper<string>(new ObservableCollection<string>(Enum.GetNames<ProviderCacheType>())),
                Text = (existing?.CacheType ?? ProviderCacheType.PrefixCache).ToString(),
            };
            dlg.Add(new Label { Text = Dictionary.ProviderCacheType, X = 1, Y = y, Width = 18 }, cacheType,
                new Label { Text = Dictionary.ProviderDescrCacheType, X = FormNoteX, Y = y, Width = Dim.Fill() - FormNoteX, SchemeName = "Hint" });
            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 = FormFieldX, Y = y, Width = FormFieldWidth,
                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,
                new Label { Text = Dictionary.ProviderDescrInteractionMode, X = FormNoteX, Y = y, Width = Dim.Fill() - FormNoteX, SchemeName = "Hint" });
            y++;
            var forceTextTools = AddFormCheckBox(dlg, Dictionary.ProviderForceTextTools, existing?.ForceTextToolDefinitions ?? false,
                Dictionary.ProviderDescrForceTextTools, ref y);
            var noJsonFormat = AddFormCheckBox(dlg, Dictionary.ProviderNoJsonResponseFormat, existing?.NoJsonResponseFormat ?? false,
                Dictionary.ProviderDescrNoJsonResponseFormat, ref 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 = AddFormCheckBox(dlg, Dictionary.ProviderSupportsVision, existing?.SupportsVision ?? false,
                Dictionary.ProviderDescrVision, ref y);
            var visionMaxField = AddFormField(dlg, Dictionary.ProviderVisionMaxPixels, (existing?.VisionMaxPixels ?? 0).ToString(), Dictionary.ProviderDescrVisionMaxPixels, ref y);
            var extraBodyField = AddFormField(dlg, Dictionary.ProviderExtraBody,
                existing?.ExtraBody is { Count: > 0 } eb ? JsonSerializer.Serialize(eb) : "",
                Dictionary.ProviderDescrExtraBody, ref y);
            var formErr = new Label { Text = "", X = 1, Y = y, Width = Dim.Fill() - 2, SchemeName = "Hint" };
            dlg.Add(formErr);

            ProviderConfig? result = null;
            var ok = new Button { Text = Dictionary.Ok, IsDefault = true };
            OnButtonClicked(ok, () =>
            {
                var providerName = adding ? (nameField!.Text ?? "").Trim() : existing!.ProviderName;
                if (providerName.Length == 0)
                {
                    formErr.Text = Dictionary.ProviderNameRequired;
                    return;
                }
                if (!Uri.TryCreate((baseField.Text ?? "").Trim(), UriKind.Absolute, out var uri))
                {
                    formErr.Text = Dictionary.ProviderBaseAddressInvalid;
                    return;
                }
                if (!int.TryParse((ctxField.Text ?? "").Trim(), out var ctx) || ctx <= 0)
                {
                    formErr.Text = Dictionary.ProviderContextInvalid;
                    return;
                }
                if (!int.TryParse((timeoutField.Text ?? "").Trim(), out var secs) || secs <= 0) secs = 30;
                if (!int.TryParse((pauseField.Text ?? "").Trim(), out var pause) || pause < 0) pause = 0;
                if (!Enum.TryParse<ProviderProtocol>((protocol.Text ?? "").Trim(), out var proto)) proto = ProviderProtocol.OpenAI;
                if (!Enum.TryParse<ProviderCacheType>((cacheType.Text ?? "").Trim(), out var cache)) cache = ProviderCacheType.PrefixCache;
                // 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;
                Dictionary<string, object>? extra = null;
                var extraText = (extraBodyField.Text ?? "").Trim();
                if (extraText.Length > 0)
                {
                    try
                    {
                        using var extraDoc = JsonDocument.Parse(extraText);
                        if (extraDoc.RootElement.ValueKind != JsonValueKind.Object) throw new JsonException();
                        extra = JsonSerializer.Deserialize<Dictionary<string, object>>(extraText);
                    }
                    catch
                    {
                        formErr.Text = Dictionary.ProviderInvalidExtraBody;
                        return;
                    }
                }
                result = new ProviderConfig
                {
                    ProviderName = providerName,
                    Protocol = proto,
                    CacheType = cache,
                    AgentInteractionMode = mode,
                    // Editing a provider must never silently drop its default marker.
                    IsDefault = existing?.IsDefault ?? false,
                    ForceTextToolDefinitions = forceTextTools.Value == CheckState.Checked,
                    NoJsonResponseFormat = noJsonFormat.Value == CheckState.Checked,
                    PauseBetweenRequests = TimeSpan.FromSeconds(pause),
                    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,
                    ExtraBody = extra,
                };
                formErr.Text = "";
                Log.LogStep($"TUI Provider dialog OK: {providerName} ({proto})", monitor: true);
                _app.RequestStop(dlg);
            });
            var cancel = new Button { Text = Dictionary.Cancel };
            OnButtonClicked(cancel, () => { 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 ?? baseField).SetFocus();
            _app.Run(dlg);
            dlg.Dispose();
            return result;
        }

        // Form rows: label, value, and a one-line description on the right of the field
        // (the description is what makes every provider parameter self-explanatory).
        private const int FormLabelWidth = 18;
        private const int FormFieldX = 20;
        private const int FormFieldWidth = 42;
        private const int FormNoteX = FormFieldX + FormFieldWidth + 1;

        private static TextField AddFormField(View parent, string label, string? value, string description, ref int y, bool secret = false)
        {
            parent.Add(new Label { Text = label, X = 1, Y = y, Width = FormLabelWidth });
            var field = new TextField { Text = value ?? "", X = FormFieldX, Y = y, Width = FormFieldWidth, Secret = secret };
            parent.Add(field);
            parent.Add(new Label { Text = description, X = FormNoteX, Y = y, Width = Dim.Fill() - FormNoteX, SchemeName = "Hint" });
            y++;
            return field;
        }

        private static CheckBox AddFormCheckBox(View parent, string label, bool value, string description, ref int y)
        {
            var box = new CheckBox
            {
                Text = label,
                Value = value ? CheckState.Checked : CheckState.UnChecked,
                X = FormFieldX, Y = y, Width = FormFieldWidth,
            };
            parent.Add(box);
            parent.Add(new Label { Text = description, X = FormNoteX, Y = y, Width = Dim.Fill() - FormNoteX, SchemeName = "Hint" });
            y++;
            return box;
        }

        // 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();
                // Startup greeting: endpoint, active provider and the real tool set. It is a
                // chat entry (not a fixture under the prompt), so it scrolls away with the text.
                if (!_entryPointShown)
                {
                    _entryPointShown = true;
                    AddEntryPointNote();
                }
            }
            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();
    }
}