a3s 0.7.7

//! Codex-style terminal UI for the A3S Code agent.
//!
//! Built on the `a3s-tui` TEA framework: it drives an [`AgentSession`] via
//! `session.stream()` and renders the resulting [`AgentEvent`] stream as a live
//! chat transcript, with an inline (y/n/a) approval prompt for tool calls.
//!
//! Streaming bridge: `session.stream()` yields a `tokio::mpsc` receiver. A
//! self-re-issuing "pump" command reads one event, turns it into a `Msg`, and
//! the update handler issues the next pump — feeding the async event stream into
//! the synchronous TEA update loop one event at a time.

use std::collections::{BinaryHeap, HashMap, HashSet, VecDeque};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};

use a3s_code_core::config::OsConfig;
use a3s_code_core::context::RecentWorkspaceFilesContextProvider;
use a3s_code_core::hitl::TimeoutAction;
use a3s_code_core::workspace::{
    LocalWorkspaceManifest, LocalWorkspaceManifestSnapshot, ManifestWorkspaceBackend,
    WorkspaceServices,
};
use a3s_code_core::{
    Agent, AgentEvent, AgentSession, SessionOptions, SystemPromptSlots, ToolCallResult,
};
use a3s_tui::cmd::{self, Cmd};
use a3s_tui::components::textarea::TextareaMsg;
use a3s_tui::components::viewport::ViewportMsg;
use a3s_tui::components::{
    Alert, AlertKind, ChoicePrompt, ChoicePromptMsg, InlineAction, Scrollbar, SessionStatusChip,
    Spinner, Textarea, Toast, ToastKind, ToolLogRecord as TuiToolLogRecord, ToolLogStatus,
    Viewport,
};
use a3s_tui::event::{KeyEvent, MouseEvent};
use a3s_tui::keymap::{KeyBinding, Keymap};
use a3s_tui::layout::{Constraint, Layout};
use a3s_tui::style::{Color, Style};
use a3s_tui::{
    AgentChrome, Event, KeyCode, KeyModifiers, Model, ProgramBuilder, Theme as TuiTheme,
};
use tokio::sync::{mpsc, Mutex};

use crate::top::{collect_processes, render_process_table, ProcessRow, ProcessTableView};

// Team digital assets.
#[path = "assets/clone.rs"]
mod asset_clone;
#[path = "assets/lifecycle.rs"]
mod asset_lifecycle;
#[path = "assets/naming.rs"]
mod asset_naming;
#[path = "code_cli.rs"]
mod code_cli;
pub(crate) use code_cli::{is_code_cli_command, run_code_cli};

// System integrations.
#[path = "system/skills.rs"]
pub(crate) mod skills;
#[path = "system/update.rs"]
mod update;

// Local workspace.
#[path = "workspace/gitutil.rs"]
mod gitutil;

// Local and shared knowledge.
#[path = "knowledge/kbutil.rs"]
pub(crate) mod kbutil;

// Context and memory.
#[path = "context/memutil.rs"]
mod memutil;

// OS Runtime bridge.
#[path = "os/progressive.rs"]
mod os_progressive;
#[path = "os/remote_ui.rs"]
mod remote_ui;
#[path = "os/runtime_policy.rs"]
mod runtime_policy;
mod runtime_projection;

// Terminal UI support.
#[path = "ui/design_markdown.rs"]
mod design_markdown;
#[path = "ui/image.rs"]
mod image;
#[path = "ui/render.rs"]
mod render;
#[path = "ui/syntax.rs"]
mod syntax;
#[path = "ui/util.rs"]
mod util;

mod panels;
use crate::budget::{
    auto_compact_threshold_for, budget_plan_for_effort_index, context_limit_for_model,
    context_percent_from_core_window, resolve_ctx_limit, BudgetPlan, BudgetWorkload,
    DEFAULT_TUI_EFFORT_INDEX, EFFORT_LEVELS, ULTRACODE_INDEX as ULTRACODE,
};
use crate::config::*;
use asset_naming::*;
use design_markdown::StreamingMarkdown;
use gitutil::*;
use image::*;
use memutil::*;
pub(crate) use panels::loop_engineering;
use render::*;
use runtime_policy::RuntimePolicy;
use runtime_projection::{RuntimeProjection, ToolCallRecord};
use skills::*;
use syntax::*;
use update::*;
use util::*;

const HITL_CONFIRM_TIMEOUT_MS: u64 = 60 * 60 * 1000;
const BACKGROUND_CONFIRM_TIMEOUT_MS: u64 = 500;
const TOOL_EXEC_TIMEOUT_MS: u64 = 30 * 60 * 1000;
const DEEP_RESEARCH_RUNTIME_PREFLIGHT_TIMEOUT_MS: u64 = 90 * 1000;
const DEEP_RESEARCH_RUNTIME_STEP_TIMEOUT_MS: u64 = 15 * 60 * 1000;
const DEEP_RESEARCH_SCRIPT_TIMEOUT_MS: u64 =
    DEEP_RESEARCH_RUNTIME_PREFLIGHT_TIMEOUT_MS + DEEP_RESEARCH_RUNTIME_STEP_TIMEOUT_MS + 60 * 1000;
const DEEP_RESEARCH_WORKFLOW_HOST_GRACE_MS: u64 = 30_000;
const DEEP_RESEARCH_SYNTHESIS_TIMEOUT_MS: u64 = 8 * 60 * 1000;
const DEEP_RESEARCH_REPAIR_TIMEOUT_MS: u64 = 3 * 60 * 1000;
const DEEP_RESEARCH_ABORT_GRACE_MS: u64 = 2_000;
const TUI_DUPLICATE_TOOL_CALL_THRESHOLD: u32 = 12;

/// Terminal-safe mapping of the DESIGN.md Geist/Vercel palette.
const ACCENT: Color = Color::Rgb(0, 112, 243); // link / active / success
const TN_GREEN: Color = ACCENT; // compatibility alias: success maps to blue
const TN_YELLOW: Color = Color::Rgb(245, 166, 35); // warning
const TN_RED: Color = Color::Rgb(238, 0, 0); // error / destructive
const TN_CYAN: Color = Color::Rgb(80, 227, 194); // sparse accent
const TN_ORANGE: Color = Color::Rgb(249, 203, 40); // ship gradient amber
const TN_PURPLE: Color = Color::Rgb(151, 71, 255); // lifted preview violet
const TN_FG: Color = Color::Rgb(237, 237, 237); // primary text on dark terminals
const TN_GRAY: Color = Color::Rgb(143, 143, 143); // muted text
const SURFACE_SOFT: Color = Color::Rgb(31, 31, 31);
const SURFACE_SELECTED: Color = Color::Rgb(7, 49, 108);
const GRADIENT_DEVELOP_START: Color = Color::Rgb(0, 124, 240);
const GRADIENT_DEVELOP_END: Color = Color::Rgb(0, 223, 216);
const GRADIENT_PREVIEW_START: Color = TN_PURPLE;
const GRADIENT_PREVIEW_END: Color = Color::Rgb(255, 0, 128);
const GRADIENT_SHIP_START: Color = Color::Rgb(255, 77, 77);
const GRADIENT_SHIP_END: Color = Color::Rgb(249, 203, 40);
const BRAND_GRADIENT: [Color; 6] = [
    GRADIENT_DEVELOP_START,
    GRADIENT_DEVELOP_END,
    GRADIENT_PREVIEW_START,
    GRADIENT_PREVIEW_END,
    GRADIENT_SHIP_START,
    GRADIENT_SHIP_END,
];

fn agent_chrome_theme() -> TuiTheme {
    TuiTheme {
        primary: ACCENT,
        secondary: TN_CYAN,
        bg: Color::Black,
        fg: TN_FG,
        muted: TN_GRAY,
        border: TN_GRAY,
        success: TN_GREEN,
        warning: TN_ORANGE,
        error: TN_RED,
        info: TN_CYAN,
        surface: SURFACE_SOFT,
        highlight: SURFACE_SELECTED,
    }
}

fn agent_chrome(theme: &TuiTheme) -> AgentChrome<'_> {
    AgentChrome::new(theme)
}

/// Self-contained system-prompt directive injected ONLY when signed in to the OS
/// platform. It disambiguates "OS" (the user means the signed-in OS open
/// platform, not this machine's operating system) AND inlines exactly how to call
/// the progressive API, so the model can act immediately — without first
/// discovering/loading the `a3s-os-capabilities` skill (that extra hop is why a
/// passive catalog entry rarely triggered: the model fell back to `whoami`).
/// `base_url` is the signed-in address so the endpoint is concrete.
fn os_platform_guide(base_url: &str) -> String {
    format!(
        "[OS platform] You are signed in to the OS open platform at {base_url} (via /login). \
DEFAULT RULE: while signed in, \"OS\" in the user's questions ALWAYS means THIS OS platform — \
never this machine's operating system. So \"what's my OS account\", \"what modules does OS have\", \
etc. are about the platform. Answer them via the platform's progressive API; do NOT answer from \
this machine (whoami / hostname / paths / working directory describe the local box, not the \
platform — they are the WRONG answer). The endpoint and auth token are ALREADY in your shell \
environment (exported at login) — use them directly; do NOT read ~/.a3s/os-auth.json or any config \
file on each call:\n\
  curl -s -X POST \"$A3S_OS_BASE_URL/api/v1/kernel/capabilities\" \
-H \"Authorization: Bearer $A3S_OS_TOKEN\" -H 'Content-Type: application/json' \
-d '{{\"action\":\"list\"}}'\n\
Body fields: `action` = list|search|describe|execute, plus `module` / `operation` / `params`. \
Go broad→narrow: `list` (modules) → `describe`/`search` for the one operation → `execute`. \
For `list`/`search`/`describe`, pipe through `jq` to extract only the fields you need so output \
stays a few lines (e.g. `| jq -r '.data.modules[].name'`). \
For `execute`, ALWAYS add `\"shaped\":true` to the request body — that is what makes the response \
carry the `.view` popup deep-link — and do NOT jq-narrow an execute response: pipe it whole (it is \
already compact), so `.view` survives. If you strip `.view` (or omit `\"shaped\":true`), the user \
loses the Open view button. \
Summarize the result for the user in a few lines; do NOT paste the whole raw JSON back. \
After your summary, ALWAYS output the trace on its own line, exactly \
`↳ requestId <requestId> · <timestamp>`. \
You do NOT print the view link yourself: whenever the execute output carries a `.view`, the host \
automatically shows a one-click `Open view` button that opens the authenticated progressive UI popup \
(the user's OS login is injected, no re-login). Never print the raw URL. The \
`a3s-os-capabilities` skill has full examples."
    )
}

/// Built-in slash commands shown in the `/` menu.
const SLASH_COMMANDS: &[(&str, &str)] = &[
    (
        "/model",
        "switch model (←/→ for Claude/GPT accounts if signed in)",
    ),
    ("/init", "analyze the project and generate AGENTS.md"),
    ("/config", "edit config.acl in the built-in editor"),
    ("/theme", "cycle the code-highlight theme (Geist Dark …)"),
    (
        "/flow",
        "select a workflow asset → OS Workflow as a Service designer (needs /login) · /flow <text> drafts one",
    ),
    (
        "/agent",
        "select an agent definition → local dev · Agent as a Service or Function as a Service by kind",
    ),
    (
        "/mcp",
        "select an MCP server asset → local dev · publish/run/test via OS Function as a Service",
    ),
    (
        "/skill",
        "select a skill asset → local dev · publish/deploy via OS Function as a Service",
    ),
    (
        "/okf",
        "select an OKF package → local dev · publish/deploy via OS Knowledge service",
    ),
    (
        "/output",
        "view every tool call this session (name · args · result)",
    ),
    ("/login", "sign in to the configured OS account"),
    ("/logout", "sign out from the configured OS account"),
    ("/plugin", "enable/disable Claude skills & plugins"),
    ("/reload", "re-scan skills/plugins (hot-reload the / menu)"),
    ("/update", "upgrade a3s to the latest release"),
    ("/btw", "ask a background side-question (/btw <prompt>)"),
    ("/top", "inspect local agent process activity"),
    ("/ide", "superfile-style file browser + editor"),
    (
        "/memory",
        "browse memory as an event/entity graph with tiers and forget candidates",
    ),
    (
        "/kb",
        "open the local personal knowledge base · add/import/search/vault",
    ),
    (
        "/ctx",
        "search past sessions (ctx) · /ctx <n> attach · /ctx save <n> keep as memory",
    ),
    ("/effort", "adjust model effort (low … max)"),
    ("/compact", "summarize + compact the conversation context"),
    ("/goal", "set a north-star goal the agent keeps in mind"),
    (
        "/loop",
        "engineered loop dashboard · agent-aware in /agent mode · /loop <task> quick loop",
    ),
    (
        "/sleep",
        "consolidate today's work into memory (experience · preferences · knowledge)",
    ),
    ("/help", "show commands and shortcuts"),
    (
        "/fork",
        "branch a new session from this point (original kept)",
    ),
    ("/clear", "reset the conversation"),
    ("/auto", "switch to auto-approve mode"),
    ("/exit", "quit a3s code"),
];

/// Slash commands that mutate the session / conversation and so must NOT run
/// mid-stream — hidden from the menu and rejected while a turn is in flight.
const IDLE_ONLY: &[&str] = &[
    "/clear", "/compact", "/model", "/effort", "/goal", "/loop", "/reload", "/update", "/init",
    "/fork", "/sleep", "/flow", "/agent", "/mcp", "/skill", "/okf", "/kb",
];

/// Slash commands whose name starts with `input` (input begins with `/`).
fn slash_candidates(input: &str) -> Vec<(&'static str, &'static str)> {
    SLASH_COMMANDS
        .iter()
        .filter(|(cmd, _)| cmd.starts_with(input))
        .copied()
        .collect()
}

fn slash_tail<'a>(input: &'a str, command: &str) -> Option<&'a str> {
    input
        .strip_prefix(command)
        .filter(|rest| rest.is_empty() || rest.starts_with(char::is_whitespace))
}

fn os_asset_category_query(category: &str, query: &str) -> String {
    let query = query.trim();
    if query.is_empty() {
        format!("category:{category}")
    } else {
        format!("category:{category} {query}")
    }
}

fn runtime_asset_query(category: &str, asset_hint: &str, query: &str) -> String {
    let category = category.trim();
    let asset_hint = asset_hint.trim();
    let query = query.trim();
    let mut parts = Vec::new();
    if !category.is_empty() {
        parts.push(format!("category:{category}"));
    }
    if !asset_hint.is_empty() {
        parts.push(asset_hint.to_string());
    }
    if !query.is_empty() {
        parts.push(query.to_string());
    }
    parts.join(" ")
}

fn cancel_pending_picker<Panel, Pending>(
    picker: &mut Option<Panel>,
    pending: &mut Option<Pending>,
) {
    *picker = None;
    *pending = None;
}

fn os_required_message(cmd: &str, os_configured: bool) -> String {
    if os_configured {
        format!("  {cmd} needs OS — sign in with /login first")
    } else {
        format!(
            "  {cmd} needs OS — configure `os = \"https://your-os-host\"` in config.acl, then /login"
        )
    }
}

fn os_required_alert(cmd: &str, os_configured: bool) -> String {
    let body = os_required_message(cmd, os_configured)
        .trim_start()
        .to_string();
    format!(
        "  {}",
        Alert::new(AlertKind::Warning, body).color(TN_YELLOW).view()
    )
}

fn ide_flash_line(kind: ToastKind, message: impl Into<String>) -> String {
    let color = match kind {
        ToastKind::Info => TN_CYAN,
        ToastKind::Success => TN_GREEN,
        ToastKind::Warning => TN_YELLOW,
        ToastKind::Error => TN_RED,
    };
    Toast::new(kind, message).color(color).view()
}

/// Glyph + colour for a plan task's status.
fn task_status_style(status: a3s_code_core::planning::TaskStatus) -> (char, Color) {
    use a3s_code_core::planning::TaskStatus;
    match status {
        TaskStatus::Completed => ('✔', TN_GRAY),
        TaskStatus::InProgress => ('▶', TN_YELLOW),
        TaskStatus::Failed => ('✗', TN_RED),
        TaskStatus::Skipped | TaskStatus::Cancelled => ('⊘', TN_GRAY),
        _ => ('□', TN_GRAY), // Pending
    }
}

/// A turn that delegated work (tools / subagents / planning) but stopped without
/// a final user-facing answer should auto-synthesize one. This applies in EVERY
/// mode, not just ultracode: parallel fan-out and planning run at all efforts, so
/// the "did work, produced no answer" gap can happen anywhere (e.g. a high-effort
/// plan that fans out to subagents which return artifacts-only). Fires at most
/// once per turn (`synthesis_used`).
fn needs_synthesis(
    synthesis_inflight: bool,
    synthesis_used: bool,
    had_agent_activity: bool,
    text_after_activity: bool,
) -> bool {
    !synthesis_inflight && !synthesis_used && had_agent_activity && !text_after_activity
}

/// Rough in-flight token estimate for text that's still streaming, before the
/// provider's exact `usage` arrives on End. ASCII text averages ~4 chars/token,
/// but wide scripts are closer to ~1 token/char — so a flat `chars / 4`
/// under-counts them by 3-4x and makes the live counter lurch
/// upward when it snaps to the real number. Count the two classes separately.
fn estimate_tokens(s: &str) -> usize {
    let (ascii, wide) = s.chars().fold((0usize, 0usize), |(a, w), c| {
        if c.is_ascii() {
            (a + 1, w)
        } else {
            (a, w + 1)
        }
    });
    ascii / 4 + wide
}

fn ctx_limit_for_model(model_ctx: &std::collections::HashMap<String, u32>, model: &str) -> u32 {
    context_limit_for_model(
        model,
        model_ctx.get(model).copied(),
        crate::codex::codex_model_context(model),
    )
}

fn os_gateway_llm_override(
    session: &crate::a3s_os::StoredOsSession,
    model: &str,
) -> Arc<dyn a3s_code_core::llm::LlmClient> {
    let origin = crate::a3s_os::os_origin(&session.address);
    // Route through the OS backend's authenticated LLM proxy (validates the OS
    // token, forwards to the internal gateway) rather than a bare `/v1`.
    Arc::new(
        a3s_code_core::llm::OpenAiClient::new(session.access_token.clone(), model.to_string())
            .with_base_url(origin)
            .with_chat_completions_path("/api/v1/llm/chat/completions")
            .with_provider_name("OS Gateway"),
    )
}

fn restore_model_selection(
    models: &[String],
    os_session: Option<&crate::a3s_os::StoredOsSession>,
    session_id: &str,
) -> Option<(String, Option<Arc<dyn a3s_code_core::llm::LlmClient>>)> {
    let preference = load_model_selection_preference()?;
    match preference.source {
        ModelSelectionSource::Config => models
            .iter()
            .any(|model| model == &preference.model)
            .then_some((preference.model, None)),
        ModelSelectionSource::Claude => {
            if !panels::login::has_local_login(panels::login::AuthProvider::Claude) {
                return None;
            }
            let model = crate::claude::canonical_model_name(&preference.model);
            let client = crate::claude::ClaudeClient::from_claude_login(&model).ok()?;
            Some((model, Some(Arc::new(client))))
        }
        ModelSelectionSource::Codex => {
            if !panels::login::has_local_login(panels::login::AuthProvider::Codex) {
                return None;
            }
            let client =
                crate::codex::CodexClient::from_codex_login(&preference.model, session_id).ok()?;
            Some((preference.model, Some(Arc::new(client))))
        }
        ModelSelectionSource::OsGateway => {
            let session = os_session?;
            let client = os_gateway_llm_override(session, &preference.model);
            Some((preference.model, Some(client)))
        }
    }
}

fn apply_launch_model_options(
    opts: SessionOptions,
    model: Option<&str>,
    llm_override: Option<&Arc<dyn a3s_code_core::llm::LlmClient>>,
) -> SessionOptions {
    let opts = match model {
        Some(model) => opts.with_model(model),
        None => opts,
    };
    match llm_override {
        Some(client) => opts.with_llm_client(client.clone()),
        None => opts,
    }
}

/// Context-fill warning latch: maps `pct` to its tier (0/70/85) and says
/// whether crossing INTO a higher tier than `warned` should warn now. The
/// returned tier becomes the new latch, so dropping back (compaction, /clear,
/// model switch) re-arms the warning. Pure for unit-testing.
fn ctx_warn_tier(pct: usize, warned: u8) -> (u8, Option<u8>) {
    let tier: u8 = if pct >= 85 {
        85
    } else if pct >= 70 {
        70
    } else {
        0
    };
    (tier, (tier > warned).then_some(tier))
}

fn workflow_doc_for_tool(name: &str, args: Option<&serde_json::Value>) -> Option<(String, String)> {
    match name {
        "dynamic_workflow" => {
            let src = args
                .and_then(|a| a.get("source"))
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())?;
            Some((
                format!("# Dynamic workflow script\n\n```javascript\n{src}\n```\n"),
                "dynamic workflow script captured".to_string(),
            ))
        }
        "program" => {
            let src = args
                .and_then(|a| a.get("source"))
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())?;
            Some((
                format!("# Dynamic workflow script\n\n```javascript\n{src}\n```\n"),
                "dynamic workflow script captured".to_string(),
            ))
        }
        "parallel_task" => {
            let tasks = args
                .and_then(|a| a.get("tasks"))
                .and_then(|t| t.as_array())?
                .iter()
                .collect::<Vec<_>>();
            workflow_doc_for_tasks(&tasks, true)
        }
        "task" => {
            let args = args?;
            if let Some(tasks) = args.get("tasks").and_then(|t| t.as_array()) {
                let tasks = tasks.iter().collect::<Vec<_>>();
                workflow_doc_for_tasks(&tasks, tasks.len() > 1)
            } else {
                workflow_doc_for_tasks(&[args], false)
            }
        }
        _ => None,
    }
}

fn workflow_doc_for_tasks(
    tasks: &[&serde_json::Value],
    parallel: bool,
) -> Option<(String, String)> {
    if tasks.is_empty() {
        return None;
    }

    let mut doc = if parallel {
        format!(
            "# Dynamic workflow\n\nFanned out {} parallel subagent task(s):\n\n",
            tasks.len()
        )
    } else {
        "# Dynamic workflow\n\nDelegated subagent task(s):\n\n".to_string()
    };

    for (i, task) in tasks.iter().enumerate() {
        let desc = task
            .get("description")
            .or_else(|| task.get("prompt"))
            .or_else(|| task.get("task"))
            .and_then(|v| v.as_str())
            .unwrap_or("(task)");
        let agent = task
            .get("agent")
            .and_then(|v| v.as_str())
            .unwrap_or("agent");
        let prompt = task
            .get("prompt")
            .or_else(|| task.get("task"))
            .and_then(|v| v.as_str())
            .unwrap_or("");
        doc.push_str(&format!(
            "## {}. {desc}\n\nAgent: `{agent}`\n\n{prompt}\n\n",
            i + 1
        ));
    }

    let label = if parallel {
        format!("dynamic workflow · {} parallel tasks captured", tasks.len())
    } else {
        format!(
            "dynamic workflow · {} delegated task{} captured",
            tasks.len(),
            if tasks.len() == 1 { "" } else { "s" }
        )
    };
    Some((doc, label))
}

/// Snapshot host processes for the `/top` panel via the shared `a3s top`
/// collector, so the panel and `a3s top` agree on rows, agent detection, risk,
/// CWD, and ordering (agents first, then CPU descending).
async fn fetch_top() -> Vec<ProcessRow> {
    collect_processes().await.unwrap_or_default()
}

const TOP_HISTORY_LIMIT: usize = 32;

#[derive(Debug, Default)]
struct TopProcessHistory {
    samples: HashMap<u32, TopMetricHistory>,
}

impl TopProcessHistory {
    fn observe(&mut self, rows: &[ProcessRow]) {
        let live = rows.iter().map(|row| row.pid).collect::<HashSet<_>>();
        for row in rows {
            self.samples
                .entry(row.pid)
                .or_default()
                .push(row.cpu_pct, row.mem_pct);
        }
        self.samples.retain(|pid, _| live.contains(pid));
    }

    fn values(&self, pid: u32) -> (Vec<f32>, Vec<f32>) {
        self.samples
            .get(&pid)
            .map(TopMetricHistory::values)
            .unwrap_or_default()
    }

    fn clear(&mut self) {
        self.samples.clear();
    }
}

#[derive(Debug, Default)]
struct TopMetricHistory {
    cpu: VecDeque<f32>,
    mem: VecDeque<f32>,
}

impl TopMetricHistory {
    fn push(&mut self, cpu: f32, mem: f32) {
        push_top_history_value(&mut self.cpu, cpu);
        push_top_history_value(&mut self.mem, mem);
    }

    fn values(&self) -> (Vec<f32>, Vec<f32>) {
        (
            self.cpu.iter().copied().collect(),
            self.mem.iter().copied().collect(),
        )
    }
}

fn push_top_history_value(values: &mut VecDeque<f32>, value: f32) {
    values.push_back(value);
    while values.len() > TOP_HISTORY_LIMIT {
        values.pop_front();
    }
}

/// One visible row of the `/ide` file tree (a flattened, expandable tree).
struct IdeEntry {
    path: std::path::PathBuf,
    name: String,
    depth: usize,
    is_dir: bool,
    expanded: bool,
}

#[derive(Clone, PartialEq, Eq, Debug)]
enum IdePrompt {
    Search { forward: bool, text: String },
    Command(String),
}

/// Editor input mode — vim-aligned: Normal navigates/operates, Insert types.
/// Freshly opened buffers start in Normal.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum EditMode {
    Normal,
    Insert,
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct PendingOp {
    op: char,
    count: usize,
}

#[derive(Clone, PartialEq, Eq, Debug)]
enum RepeatEdit {
    DeleteChar(usize),
    DeleteLine(usize),
    DeleteWord(usize),
    DeleteToEol,
    ChangeLine(usize),
    Replace(char),
    JoinLine(usize),
    ToggleCase(usize),
}

/// An open, editable file in the `/ide` panel.
struct IdeFile {
    path: std::path::PathBuf,
    lines: Vec<String>, // text rows, or pre-rendered half-block rows if `image`
    scroll: usize,      // top visible row (vertical scroll)
    hscroll: usize,     // leftmost visible column (horizontal scroll; display columns)
    row: usize,         // cursor line
    col: usize,         // cursor column (char index)
    dirty: bool,
    image: bool,    // read-only image preview
    readonly: bool, // view-only (e.g. a dynamic-workflow artifact) — edits blocked
    mode: EditMode, // vim Normal/Insert (see `ide_key`)
    /// A pending operator/prefix awaiting its second keystroke (`d`, `c`, `g`, `y`).
    pending: Option<PendingOp>,
    /// Normal-mode numeric prefix (`3j`, `5dd`, `2w`).
    count: Option<usize>,
    /// Undo snapshots (lines + cursor) for `u`; bounded — configs are small.
    undo: Vec<(Vec<String>, usize, usize)>,
    /// Redo snapshots for Ctrl+R.
    redo: Vec<(Vec<String>, usize, usize)>,
    /// Last repeatable Normal-mode change for `.`.
    last_change: Option<RepeatEdit>,
    /// Last search query and direction for `n` / `N`.
    search: Option<(String, bool)>,
    /// Visual Line anchor row (`V`).
    visual_line_anchor: Option<usize>,
    clip: String,        // yank/delete register for p / P
    clip_linewise: bool, // register holds whole lines (dd/yy) vs an inline span
}

impl IdeFile {
    /// A freshly opened buffer: cursor at the top, Normal mode, empty undo.
    fn new(path: std::path::PathBuf, lines: Vec<String>, image: bool, readonly: bool) -> Self {
        IdeFile {
            path,
            lines: if lines.is_empty() {
                vec![String::new()]
            } else {
                lines
            },
            scroll: 0,
            hscroll: 0,
            row: 0,
            col: 0,
            dirty: false,
            image,
            readonly,
            mode: EditMode::Normal,
            pending: None,
            count: None,
            undo: Vec::new(),
            redo: Vec::new(),
            last_change: None,
            search: None,
            visual_line_anchor: None,
            clip: String::new(),
            clip_linewise: false,
        }
    }
}

/// Render the `/output` viewer body. It mirrors the main transcript's tool
/// vocabulary while staying plain-text for the read-only editor.
fn format_tool_log_records(records: &[ToolCallRecord], width: usize) -> Option<String> {
    if records.is_empty() {
        return None;
    }
    const OUTPUT_TAIL: usize = 24;

    let records = records
        .iter()
        .map(|rec| {
            let arg = rec
                .args
                .as_ref()
                .and_then(|args| arg_summary_for_tool(&rec.name, args))
                .unwrap_or_default();
            let action = if arg.is_empty() {
                tool_verb(&rec.name).to_string()
            } else {
                format!("{} {}", tool_verb(&rec.name), arg)
            };
            let status = if rec.exit_code == 0 {
                ToolLogStatus::Ok
            } else {
                ToolLogStatus::Exit(rec.exit_code)
            };
            let args = rec
                .args
                .as_ref()
                .map(serde_json::to_string)
                .transpose()
                .unwrap_or_default();
            let mut record = TuiToolLogRecord::new(action, status).output(rec.output.clone());
            if let Some(args) = args {
                record = record.args(args);
            }
            record
        })
        .collect::<Vec<_>>();

    let theme = agent_chrome_theme();
    let chrome = agent_chrome(&theme);
    Some(
        chrome
            .tool_log()
            .records(records)
            .max_output_lines_per_record(OUTPUT_TAIL)
            .view(width as u16, usize::MAX),
    )
}

/// PTC source used by the `?` deep-research workflow. The workflow function is
/// deterministic and only schedules work; side effects live in Flow steps.
fn deep_research_workflow_source() -> &'static str {
    r#"
async function run(ctx, inputs) {
  const input = inputs.input || {};
  const query = input.query || "";
  const osRuntimeEnabled = false;
  const fallbackTracks = [
    { title: "Facts and timeline", focus: "establish the current facts, dates, and key actors" },
    { title: "Primary sources", focus: "find official or primary-source evidence" },
    { title: "Independent analysis", focus: "compare reputable independent analysis and disagreements" },
    { title: "Quantitative evidence", focus: "find concrete numbers, benchmarks, market data, or measurable claims when applicable" },
    { title: "Contradictions", focus: "look for reputable disagreement, minority views, and claims that conflict with the emerging answer" },
    { title: "Risks and caveats", focus: "identify uncertainty, recency caveats, and weak claims" },
  ];
  const complexityMarkers = [
    ["comprehensive", "deep dive", "research", "全面", "深入", "调研", "研究"],
    ["compare", "comparison", "versus", "benchmark", "对比", "比较", "竞品"],
    ["latest", "recent", "timeline", "2026", "2025", "最新", "趋势", "时间线"],
    ["market", "regulation", "policy", "paper", "papers", "市场", "法规", "政策", "论文"],
    ["multi-source", "multi source", "many sources", "多来源", "大量", "并行"]
  ];
  const queryComplexity = () => {
    const q = String(query || "").toLowerCase();
    let score = 0;
    for (const group of complexityMarkers) {
      if (group.some((marker) => q.includes(marker))) {
        score += 1;
      }
    }
    const wordCount = q.split(/\s+/).filter(Boolean).length;
    const charCount = Array.from(q).length;
    if (wordCount >= 14 || charCount >= 80) {
      score += 1;
    }
    if (wordCount >= 28 || charCount >= 140) {
      score += 1;
    }
    return score;
  };
  const complexityScore = queryComplexity();
  const requestedLocalParallelTasks = Number(input.local_max_parallel_tasks);
  const maxLocalParallelTasks = Number.isFinite(requestedLocalParallelTasks) && requestedLocalParallelTasks > 0
    ? Math.max(1, Math.min(64, Math.floor(requestedLocalParallelTasks)))
    : fallbackTracks.length;
  const requestedResearchRounds = Number(input.local_research_rounds);
  const derivedResearchRounds = complexityScore <= 1
    ? 1
    : (complexityScore <= 3 ? 2 : (complexityScore <= 5 ? 3 : 4));
  const maxResearchRounds = Number.isFinite(requestedResearchRounds) && requestedResearchRounds > 0
    ? Math.max(1, Math.min(4, Math.floor(requestedResearchRounds)))
    : derivedResearchRounds;
  const minResearchRounds = maxResearchRounds > 1 ? 2 : 1;
  const initialFallbackTrackCount = Math.min(
    fallbackTracks.length,
    maxLocalParallelTasks,
    complexityScore <= 1 ? 2 : (complexityScore <= 3 ? 3 : (complexityScore <= 5 ? 4 : 6))
  );
  const requestedLocalMaxSteps = Number(input.local_max_steps);
  const localMaxSteps = Number.isFinite(requestedLocalMaxSteps) && requestedLocalMaxSteps > 0
    ? Math.floor(requestedLocalMaxSteps)
    : 200;
  const continueWorkflowRetry = {
    max_attempts: 1,
    delay_ms: 0,
    on_exhausted: "continue_workflow",
  };
  const providedTracks = Array.isArray(input.tracks)
    ? input.tracks.filter((track) => {
        if (track === null || track === undefined) {
          return false;
        }
        if (track && typeof track === "object" && !Array.isArray(track) && track.parallelizable === false) {
          return false;
        }
        return true;
      })
    : [];
  const tracks = (providedTracks.length > 0 ? providedTracks : fallbackTracks)
    .slice(0, providedTracks.length > 0 ? maxLocalParallelTasks : initialFallbackTrackCount);
  const evidenceSchema = {
    type: "object",
    additionalProperties: false,
    properties: {
      summary: { type: "string" },
      sources: {
        type: "array",
        items: {
          type: "object",
          additionalProperties: false,
          properties: {
            title: { type: "string" },
            url_or_path: { type: "string" },
            date: { type: "string" },
            quote_or_fact: { type: "string" },
            reliability: { type: "string" }
          },
          required: ["title", "url_or_path", "quote_or_fact"]
        }
      },
      key_evidence: { type: "array", items: { type: "string" } },
      contradictions: { type: "array", items: { type: "string" } },
      confidence: { type: "string" },
      gaps: { type: "array", items: { type: "string" } }
    },
    required: ["summary", "sources", "key_evidence", "contradictions", "confidence", "gaps"]
  };
  const localTasks = (roundNumber, roundTracks, previousEvidence) => roundTracks.map((track, index) => {
    const title = track.title || `Track ${index + 1}`;
    const focus = track.focus || String(track);
    const roundContext = roundNumber > 1
      ? `\n\nRecursive round: ${roundNumber}/${maxResearchRounds}. Use the prior evidence summary below to resolve only the remaining gaps or contradictions. Do not repeat the same query, source, path, or fetch from earlier rounds unless you are checking a changed/stronger source.\n\nPrior evidence summary:\n${previousEvidence || "No prior evidence summary available."}`
      : "";
    return {
      agent: "explore",
      description: `Research round ${roundNumber}.${index + 1}: ${title}`,
      max_steps: localMaxSteps,
      output_schema: evidenceSchema,
      prompt: `Deep-research evidence track for: ${query}\n\nFocus: ${focus}${roundContext}\n\nEvidence only: do not write files, create report artifacts, run tests, or modify the workspace. You are an evidence collector, not a verification runner. Use dedicated read-only tools: web_search/web_fetch for current external evidence, read/grep/glob/ls for local workspace evidence. Do not use bash for research collection. Do not inspect .a3s-flow/dynamic-workflows logs unless the focus explicitly asks about DeepResearch/runtime diagnostics; workflow logs are host diagnostics, not research evidence. If the query is about public/current facts, use web_search first and fetch the strongest sources; do not fall back to local repository grep just because a web query is empty. If web tools are unavailable or return no useful results after several distinct queries, report that gap with the attempted queries and stop instead of looping. If the query explicitly asks for local workspace evidence only, inspect local files and do not use web tools. Use as many distinct high-signal tool calls as the evidence actually requires, avoid repeating the same query/pattern/path, and synthesize when evidence is sufficient. Return concise evidence, URLs or local paths, publication dates when available, key evidence, contradictions, and confidence notes. Your final child response should contain enough information to satisfy the provided output_schema: summary, sources, key_evidence, contradictions, confidence, and gaps.`
    };
  });
  const isNonEmptyString = (value) => typeof value === "string" && value.trim().length > 0;
  const isStringArray = (value, allowEmpty) =>
    Array.isArray(value) &&
    (allowEmpty || value.length > 0) &&
    value.every((item) => typeof item === "string");
  const isEvidenceSource = (value) =>
    value &&
    typeof value === "object" &&
    !Array.isArray(value) &&
    isNonEmptyString(value.title) &&
    isNonEmptyString(value.url_or_path) &&
    isNonEmptyString(value.quote_or_fact) &&
    (value.date === undefined || typeof value.date === "string") &&
    (value.reliability === undefined || typeof value.reliability === "string");
  const isEvidenceObject = (value) =>
    value &&
    typeof value === "object" &&
    !Array.isArray(value) &&
    isNonEmptyString(value.summary) &&
    Array.isArray(value.sources) &&
    value.sources.length > 0 &&
    value.sources.every(isEvidenceSource) &&
    isStringArray(value.key_evidence, false) &&
    isStringArray(value.contradictions, true) &&
    isNonEmptyString(value.confidence) &&
    isStringArray(value.gaps, true);
  const normalizeRuntimeOutput = (runtimeOutput) => {
    if (!runtimeOutput || !Array.isArray(runtimeOutput.results)) {
      return runtimeOutput;
    }
    const normalized = Object.assign({}, runtimeOutput);
    normalized.results = runtimeOutput.results.map((item) => {
      if (!item || typeof item !== "object") {
        return item;
      }
      const output = item.output;
      let structured = item.structured || null;
      if (!structured && typeof output === "string") {
        try {
          structured = JSON.parse(output);
        } catch (_err) {
          structured = null;
        }
      } else if (!structured && output && typeof output === "object") {
        structured = output;
      }
      if (!structured) {
        return item;
      }
      if (!isEvidenceObject(structured)) {
        const next = Object.assign({}, item);
        delete next.structured;
        next.structured_error = "runtime output did not match DeepResearch evidence schema";
        return next;
      }
      return Object.assign({}, item, { structured });
    });
    return normalized;
  };
  const compactText = (value, limit) => {
    let text = "";
    if (typeof value === "string") {
      text = value;
    } else if (value !== undefined && value !== null) {
      try {
        text = JSON.stringify(value);
      } catch (_err) {
        text = String(value);
      }
    }
    const compact = text.replace(/\s+/g, " ").trim();
    if (compact.length <= limit) {
      return compact;
    }
    return `${compact.slice(0, limit)} ... [truncated]`;
  };
  const failureSummary = (value) => {
    const compact = compactText(value, 600);
    const lower = compact.toLowerCase();
    if (lower.includes("permission denied: tool")) {
      return "Delegated task could not use a requested tool because the permission policy denied it.";
    }
    if (lower.includes("max tool rounds")) {
      return "Delegated task exhausted its tool-round budget before returning usable evidence.";
    }
    if (lower.includes("timed out") || lower.includes("[command timed out")) {
      return "Delegated task timed out before returning usable evidence.";
    }
    if (
      lower.includes("[tool output truncated") ||
      lower.includes("full output artifact:") ||
      lower.includes("a3s://tool-output")
    ) {
      return "Delegated task produced oversized tool output that was withheld from the report context.";
    }
    if (
      lower.includes(".a3s-flow/dynamic-workflows") ||
      lower.includes("● searched") ||
      lower.includes("● ran") ||
      lower.includes("● read") ||
      compact.includes("⎿")
    ) {
      return "Delegated task returned internal workflow/tool logs that were withheld from the report context.";
    }
    return "Delegated task failed before returning usable evidence.";
  };
  const copyIfPresent = (target, source, keys) => {
    for (const key of keys) {
      if (source[key] !== undefined) {
        target[key] = source[key];
      }
    }
  };
  const compactLocalResult = (item, success) => {
    const next = {};
    copyIfPresent(next, item, [
      "task_id",
      "session_id",
      "agent",
      "success",
      "artifact_id",
      "artifact_uri",
      "output_bytes",
      "truncated_for_context",
      "structured_error"
    ]);
    if (success) {
      if (item.structured) {
        next.structured = item.structured;
      } else if (item.output !== undefined) {
        next.output_summary = compactText(item.output, 1200);
      }
    } else {
      next.error_summary = failureSummary(item.output || item.error || "task failed");
    }
    return next;
  };
  const normalizeLocalResearch = (parallelOutput) => {
    if (!parallelOutput || typeof parallelOutput !== "object" || Array.isArray(parallelOutput)) {
      return parallelOutput;
    }
    const metadata = parallelOutput.metadata && typeof parallelOutput.metadata === "object"
      ? parallelOutput.metadata
      : null;
    const results = metadata && Array.isArray(metadata.results) ? metadata.results : null;
    if (!results) {
      return parallelOutput;
    }
    const successfulResults = results.filter((item) => item && item.success === true);
    const failedResults = results.filter((item) => item && item.success === false);
    const compactSuccesses = successfulResults.map((item) => compactLocalResult(item, true));
    const countFromMetadata = (key, fallback) => {
      const value = Number(metadata[key]);
      return Number.isFinite(value) ? value : fallback;
    };
    const successCount = countFromMetadata("success_count", successfulResults.length);
    const failedCount = countFromMetadata("failed_count", failedResults.length);
    const resultCount = countFromMetadata("result_count", results.length);
    const taskCount = countFromMetadata("task_count", resultCount);
    const partialFailure = failedCount > 0 && successCount > 0;
    const normalized = {
      tool: parallelOutput.tool || "parallel_task",
      exit_code: parallelOutput.exit_code ?? parallelOutput.exitCode ?? (successCount > 0 ? 0 : 1),
      status: failedCount > 0 ? (successCount > 0 ? "partial_success" : "failed") : "success",
      metadata: {
        task_count: taskCount,
        result_count: resultCount,
        success_count: successCount,
        failed_count: failedCount,
        all_success: failedCount === 0,
        partial_failure: partialFailure,
        allow_partial_failure: metadata.allow_partial_failure === true,
        results: compactSuccesses
      },
      results: compactSuccesses
    };
    copyIfPresent(normalized, parallelOutput, ["artifact_id", "artifact_uri"]);
    if (failedResults.length > 0) {
      normalized.warnings = {
        failed_tasks: failedResults.map((item) => compactLocalResult(item, false))
      };
    }
    return normalized;
  };
  const roundStepId = (prefix, roundNumber) =>
    roundNumber === 1 ? prefix : `${prefix}_round_${roundNumber}`;
  const collectRoundOutputs = (stepOutputs, prefix) => {
    const rounds = [];
    for (let roundNumber = 1; roundNumber <= maxResearchRounds; roundNumber += 1) {
      const output = stepOutputs[roundStepId(prefix, roundNumber)];
      if (!output) {
        break;
      }
      rounds.push({ round: roundNumber, research: normalizeLocalResearch(output) });
    }
    return rounds;
  };
  const collectRoundFailures = (stepFailures, prefix) => {
    const failures = [];
    for (let roundNumber = 1; roundNumber <= maxResearchRounds; roundNumber += 1) {
      const failure = stepFailures[roundStepId(prefix, roundNumber)];
      if (failure) {
        failures.push({
          round: roundNumber,
          error: failure.error || "research round failed",
          attempt: failure.attempt
        });
      }
    }
    return failures;
  };
  const uniqueStrings = (items) => {
    const seen = new Set();
    const unique = [];
    for (const item of items) {
      const text = typeof item === "string" ? item.trim() : "";
      if (!text) {
        continue;
      }
      const key = text.toLowerCase();
      if (seen.has(key)) {
        continue;
      }
      seen.add(key);
      unique.push(text);
    }
    return unique;
  };
  const structuredEvidence = (rounds) => {
    const structured = [];
    for (const round of rounds) {
      const results = round.research && Array.isArray(round.research.results)
        ? round.research.results
        : [];
      for (const result of results) {
        if (result && result.structured) {
          structured.push({ round: round.round, value: result.structured });
        }
      }
    }
    return structured;
  };
  const evidenceSummary = (rounds) => {
    const structured = structuredEvidence(rounds);
    const summaries = structured.map((item) => `round ${item.round}: ${item.value.summary}`);
    const sources = structured.flatMap((item) =>
      Array.isArray(item.value.sources)
        ? item.value.sources.map((source) => `${source.title || "source"} — ${source.url_or_path || ""}`)
        : []
    );
    const gaps = structured.flatMap((item) => Array.isArray(item.value.gaps) ? item.value.gaps : []);
    const contradictions = structured.flatMap((item) =>
      Array.isArray(item.value.contradictions) ? item.value.contradictions : []
    );
    return compactText(JSON.stringify({
      summaries: summaries.slice(-8),
      sources: uniqueStrings(sources).slice(-16),
      gaps: uniqueStrings(gaps).slice(-12),
      contradictions: uniqueStrings(contradictions).slice(-12)
    }), 4000);
  };
  const followUpTracks = (rounds, nextRound) => {
    const structured = structuredEvidence(rounds);
    const gaps = uniqueStrings(structured.flatMap((item) =>
      Array.isArray(item.value.gaps) ? item.value.gaps : []
    ));
    const contradictions = uniqueStrings(structured.flatMap((item) =>
      Array.isArray(item.value.contradictions) ? item.value.contradictions : []
    ));
    const tracks = [];
    for (const gap of gaps) {
      tracks.push({
        title: `Resolve gap: ${compactText(gap, 80)}`,
        focus: `Resolve this remaining evidence gap without repeating prior searches: ${gap}`
      });
    }
    for (const contradiction of contradictions) {
      tracks.push({
        title: `Check contradiction: ${compactText(contradiction, 80)}`,
        focus: `Investigate this contradiction or disagreement and decide which claim is best supported: ${contradiction}`
      });
    }
    if (tracks.length === 0 && nextRound <= minResearchRounds) {
      tracks.push({
        title: "Independent corroboration",
        focus: "Find independent corroboration for the strongest claims from prior rounds; avoid repeating the same sources."
      });
      tracks.push({
        title: "Adversarial caveat check",
        focus: "Look for missing caveats, outdated claims, weak sources, or counterexamples in the prior evidence."
      });
    }
    return tracks.slice(0, maxLocalParallelTasks);
  };
  const aggregateResearchRounds = (rounds, stopReason, workflowFailures) => {
    const aggregate = {
      algorithm: "bounded_recursive_parallel_retrieval_summary",
      tool: "parallel_task",
      status: "failed",
      max_rounds: maxResearchRounds,
      completed_rounds: rounds.length,
      stop_reason: stopReason,
      complexity: {
        score: complexityScore,
        min_rounds: minResearchRounds,
        max_rounds: maxResearchRounds,
        initial_track_count: tracks.length,
        max_parallel_tasks: maxLocalParallelTasks
      },
      metadata: {
        task_count: 0,
        result_count: 0,
        success_count: 0,
        failed_count: 0,
        all_success: true,
        partial_failure: false,
        allow_partial_failure: true,
        results: []
      },
      results: [],
      rounds: []
    };
    const failedTasks = [];
    for (const round of rounds) {
      const research = round.research || {};
      const metadata = research.metadata || {};
      const results = Array.isArray(research.results) ? research.results : [];
      const roundResults = results.map((item) => Object.assign({ round: round.round }, item));
      aggregate.metadata.task_count += Number(metadata.task_count) || 0;
      aggregate.metadata.result_count += Number(metadata.result_count) || 0;
      aggregate.metadata.success_count += Number(metadata.success_count) || 0;
      aggregate.metadata.failed_count += Number(metadata.failed_count) || 0;
      aggregate.results.push(...roundResults);
      aggregate.metadata.results.push(...roundResults);
      if (research.warnings && Array.isArray(research.warnings.failed_tasks)) {
        failedTasks.push(...research.warnings.failed_tasks.map((item) =>
          Object.assign({ round: round.round }, item)
        ));
      }
      aggregate.rounds.push({
        round: round.round,
        status: research.status || "unknown",
        metadata: {
          task_count: metadata.task_count || 0,
          result_count: metadata.result_count || 0,
          success_count: metadata.success_count || 0,
          failed_count: metadata.failed_count || 0
        },
        results: roundResults,
        warnings: research.warnings
      });
    }
    aggregate.metadata.all_success = aggregate.metadata.failed_count === 0;
    aggregate.metadata.partial_failure =
      aggregate.metadata.failed_count > 0 && aggregate.metadata.success_count > 0;
    aggregate.status = aggregate.metadata.failed_count > 0
      ? (aggregate.metadata.success_count > 0 ? "partial_success" : "failed")
      : "success";
    if (failedTasks.length > 0 || (workflowFailures && workflowFailures.length > 0)) {
      aggregate.warnings = {};
      if (failedTasks.length > 0) {
        aggregate.warnings.failed_tasks = failedTasks;
      }
      if (workflowFailures && workflowFailures.length > 0) {
        aggregate.warnings.failed_rounds = workflowFailures;
      }
    }
    return aggregate;
  };
  const shouldContinueRounds = (rounds, failures) => {
    if (rounds.length === 0 || failures.length > 0 || rounds.length >= maxResearchRounds) {
      return false;
    }
    const aggregate = aggregateResearchRounds(rounds, "checking_next_round", []);
    if (aggregate.metadata.success_count === 0) {
      return false;
    }
    return followUpTracks(rounds, rounds.length + 1).length > 0;
  };
  const hasStructuredEvidence = (runtimeOutput) =>
    runtimeOutput &&
    Array.isArray(runtimeOutput.results) &&
    runtimeOutput.results.some((item) => item && item.structured);
  const runtimeStepError = (stepName, message) =>
    stepName === "runtime_preflight"
      ? `runtime preflight failed: ${message}`
      : message;

  if (inputs.kind === "workflow") {
    const runtimePreflight = inputs.step_outputs.runtime_preflight;
    const runtimeResearch = inputs.step_outputs.runtime_research;
    const stepFailures = inputs.step_failures || {};
    const localRounds = collectRoundOutputs(inputs.step_outputs, "local_research");
    const localRoundFailures = collectRoundFailures(stepFailures, "local_research");
    const localFallbackRounds = collectRoundOutputs(inputs.step_outputs, "local_fallback");
    const localFallbackFailures = collectRoundFailures(stepFailures, "local_fallback");

    if (localFallbackRounds.length > 0) {
      if (shouldContinueRounds(localFallbackRounds, localFallbackFailures)) {
        const nextRound = localFallbackRounds.length + 1;
        return {
          type: "schedule_step",
          step_id: roundStepId("local_fallback", nextRound),
          step_name: "parallel_task",
          input: {
            allow_partial_failure: true,
            tasks: localTasks(nextRound, followUpTracks(localFallbackRounds, nextRound), evidenceSummary(localFallbackRounds))
          },
          retry: continueWorkflowRetry,
        };
      }
      return {
        type: "complete",
        output: {
          query,
          mode: "local_fallback",
          runtime_error: (runtimeResearch && runtimeResearch.runtime_error) || (runtimePreflight && runtimePreflight.runtime_error),
          research: aggregateResearchRounds(
            localFallbackRounds,
            localFallbackFailures.length > 0 ? "round_failed_after_partial_evidence" : "bounded_rounds_complete",
            localFallbackFailures
          )
        }
      };
    }

    if (localRounds.length > 0) {
      if (shouldContinueRounds(localRounds, localRoundFailures)) {
        const nextRound = localRounds.length + 1;
        return {
          type: "schedule_step",
          step_id: roundStepId("local_research", nextRound),
          step_name: "parallel_task",
          input: {
            allow_partial_failure: true,
            tasks: localTasks(nextRound, followUpTracks(localRounds, nextRound), evidenceSummary(localRounds))
          },
          retry: continueWorkflowRetry,
        };
      }
      return {
        type: "complete",
        output: {
          query,
          mode: "local_parallel_task",
          research: aggregateResearchRounds(
            localRounds,
            localRoundFailures.length > 0 ? "round_failed_after_partial_evidence" : "bounded_rounds_complete",
            localRoundFailures
          )
        }
      };
    }

    if (localRoundFailures.length > 0) {
      return {
        type: "complete",
        output: {
          query,
          mode: "local_parallel_task_failed",
          research: {
            status: "failed",
            algorithm: "bounded_recursive_parallel_retrieval_summary",
            max_rounds: maxResearchRounds,
            completed_rounds: 0,
            error: localRoundFailures[0].error || "local research step failed",
            note: "Local evidence fan-out failed before producing usable structured evidence; synthesis should create a transparent fallback report instead of retrying the workflow."
          }
        }
      };
    }

    if (localFallbackFailures.length > 0) {
      return {
        type: "complete",
        output: {
          query,
          mode: "local_fallback_failed",
          runtime_error: (runtimeResearch && runtimeResearch.runtime_error) || (runtimePreflight && runtimePreflight.runtime_error),
          research: {
            status: "failed",
            algorithm: "bounded_recursive_parallel_retrieval_summary",
            max_rounds: maxResearchRounds,
            completed_rounds: 0,
            error: localFallbackFailures[0].error || "local fallback research step failed",
            note: "Both OS-runtime research and local fallback fan-out failed; synthesis should report the failure and materialize a transparent fallback artifact."
          }
        }
      };
    }

    if (runtimeResearch && !runtimeResearch.runtime_error) {
      return { type: "complete", output: { query, mode: "os_runtime", research: runtimeResearch } };
    }

    if (runtimeResearch && runtimeResearch.runtime_error) {
      return {
        type: "schedule_step",
        step_id: roundStepId("local_fallback", 1),
        step_name: "parallel_task",
        input: { allow_partial_failure: true, tasks: localTasks(1, tracks, "") },
        retry: continueWorkflowRetry,
      };
    }

    if (runtimePreflight && runtimePreflight.runtime_error) {
      return {
        type: "schedule_step",
        step_id: roundStepId("local_fallback", 1),
        step_name: "parallel_task",
        input: { allow_partial_failure: true, tasks: localTasks(1, tracks, "") },
        retry: continueWorkflowRetry,
      };
    }

    if (runtimePreflight && !runtimePreflight.runtime_error) {
      return {
        type: "schedule_step",
        step_id: "runtime_research",
        step_name: "runtime_research",
        input: {
          query,
          worker: input.worker || "deep-research-worker",
          runtime_timeout_ms: input.runtime_timeout_ms,
          tracks,
        },
        retry: { max_attempts: 1, delay_ms: 0 },
      };
    }

    if (osRuntimeEnabled && input.os_runtime) {
      return {
        type: "schedule_step",
        step_id: "runtime_preflight",
        step_name: "runtime_preflight",
        input: {
          query,
          worker: input.worker || "deep-research-worker",
          runtime_preflight_timeout_ms: input.runtime_preflight_timeout_ms,
          tracks,
        },
        retry: { max_attempts: 1, delay_ms: 0 },
      };
    }

    return {
      type: "schedule_step",
      step_id: roundStepId("local_research", 1),
      step_name: "parallel_task",
      input: { allow_partial_failure: true, tasks: localTasks(1, tracks, "") },
      retry: continueWorkflowRetry,
    };
  }

  if (
    inputs.kind === "step" &&
    (inputs.step_name === "runtime_preflight" || inputs.step_name === "runtime_research")
  ) {
    const isPreflight = inputs.step_name === "runtime_preflight";
    const runtimeTracks = isPreflight
      ? [{
          title: "Runtime capability preflight",
          focus: `Verify the OS Runtime worker can use read-only research tools and return schema-shaped evidence for: ${inputs.input.query}`
        }]
      : inputs.input.tracks;
    const result = await ctx.tool("runtime", {
      worker: inputs.input.worker,
      timeout_ms: isPreflight
        ? (inputs.input.runtime_preflight_timeout_ms || 90000)
        : (inputs.input.runtime_timeout_ms || 240000),
      tasks: runtimeTracks.map((track, index) => ({
        query: inputs.input.query,
        title: track.title || `Track ${index + 1}`,
        focus: track.focus || String(track),
        capability_probe: isPreflight,
        required_tools: ["web_search", "web_fetch", "read", "grep", "glob", "ls"],
        output_schema: evidenceSchema,
        requirements: isPreflight
          ? "Capability preflight only. Use at least one harmless read-only research tool available to you: web_search/web_fetch for current external evidence, or read/grep/glob/ls for local workspace evidence. Return a JSON object matching output_schema with at least one traceable URL or local path. If the required tools are unavailable or permission-denied, do not fabricate evidence; surface the failure."
          : "Use web search and full-page reads. Return a JSON object matching output_schema with URLs, dates, key evidence, contradictions, confidence notes, and gaps. Do not write report artifacts in worker tasks."
      }))
    });
    if (!result || result.exitCode !== 0) {
      return {
        runtime_error: runtimeStepError(inputs.step_name, (result && result.output) || "runtime tool failed"),
        runtime_result: result || null
      };
    }
    let runtimeOutput = null;
    try {
      runtimeOutput = typeof result.output === "string" ? JSON.parse(result.output) : result.output;
    } catch (_err) {
      runtimeOutput = null;
    }
    runtimeOutput = normalizeRuntimeOutput(runtimeOutput);
    if (runtimeOutput && runtimeOutput.partial) {
      return {
        runtime_error: runtimeStepError(inputs.step_name, runtimeOutput.note || "runtime tool returned partial results before every subtask finished"),
        runtime_result: result,
        runtime_output: runtimeOutput,
      };
    }
    if (!hasStructuredEvidence(runtimeOutput)) {
      return {
        runtime_error: runtimeStepError(inputs.step_name, "runtime tool returned no valid structured DeepResearch evidence"),
        runtime_result: result,
        runtime_output: runtimeOutput,
      };
    }
    return {
      mode: isPreflight ? "runtime_preflight" : "os_runtime",
      runtime: result,
      runtime_output: runtimeOutput
    };
  }

  return { error: `unknown dynamic workflow invocation: ${inputs.kind}/${inputs.step_name || ""}` };
}
"#
}

fn deep_research_report_contract() -> &'static str {
    "Report artifact contract (mandatory final step unless the user explicitly forbids files):\n\
     - Create a Markdown report at `.a3s/research/<slug>/report.md` and an HTML page at \
       `.a3s/research/<slug>/index.html`.\n\
     - Use a clean standalone HTML layout without external build steps. Do not search the workspace \
       for design/style files, run shell/glob/read calls solely for styling, or narrate artifact \
       creation or verification checks in the final answer or report.\n\
     - The standalone HTML page must be polished, responsive, and source-backed: include the answer, \
       citations/sources, evidence notes, confidence/caveats, and next actions.\n\
     - Write only the required report artifacts unless a tool error requires a targeted correction; \
       the host validates file existence, source traceability, and HTML completeness.\n\
     - If a targeted self-check is necessary, only read or list the report files under \
       `.a3s/research/<slug>/`; never use shell commands for report verification.\n\
     - The final answer must contain the research answer and the required marker only. Do not list \
       directory creation, file write, shell, or verification steps.\n\
     - End the final answer with one plain line exactly like \
     `A3S_RESEARCH_VIEW: .a3s/research/<slug>/index.html`. Do not put this marker in a code fence. \
       The marker must point to `index.html`, not `report.md` or another HTML filename. \
       Print this marker only after the final report is complete and verified. Never print it for \
       a partial answer, timeout recovery, fallback draft, or error state. The host verifies the \
       sibling `report.md` and opens the HTML in RemoteUI automatically."
}

fn deep_research_report_target_note(query: &str) -> String {
    let slug = deep_research_report_slug(query);
    format!(
        "For this query, the host expects report slug `{slug}`. Write the report \
         files at `.a3s/research/{slug}/report.md` and \
         `.a3s/research/{slug}/index.html`, then end with exactly \
         `A3S_RESEARCH_VIEW: .a3s/research/{slug}/index.html`."
    )
}

fn deep_research_duplicate_tool_guard() -> &'static str {
    "Tool-loop guard:\n\
     - Do not repeat an identical grep/read/search/web_fetch/tool call with the same arguments. \
       If you already observed the result, reuse it; if it was insufficient, change the \
       pattern/path/query/source or move to synthesis.\n\
     - Verification layers are for targeted corrections, not restarting the same evidence search."
}

/// The directive sent to the agent for a `?` deep-research turn: decompose the
/// question, run the evidence fan-out through DynamicWorkflowRuntime, then
/// cross-check and synthesize a cited report. OS Runtime tool-call fan-out is
/// intentionally disabled; future OS Runtime integration should use its
/// Function-as-a-Service path instead.
#[cfg(test)]
fn deep_research_prompt(query: &str, _os_runtime: bool) -> String {
    let report_contract = deep_research_report_contract();
    let duplicate_guard = deep_research_duplicate_tool_guard();
    let tracks_directive = "OS Runtime tool-call fan-out is temporarily disabled. Set \
         `os_runtime: false`; the DynamicWorkflowRuntime script will run a bounded, \
         complexity-driven recursive parallel retrieval-summary loop through \
         host-side `parallel_task` steps because PTC itself cannot call \
         `parallel_task`. Future OS Runtime support should use Function-as-a-Service, \
         not remote tool-call fan-out. Still create the local Markdown + HTML \
         report artifacts and finish with the RemoteUI marker."
        .to_string();
    let source = deep_research_workflow_source();
    format!(
        "Conduct deep research to answer the query below. Be thorough.\n\n\
         Required execution path:\n\
         1. First call `dynamic_workflow` with the JavaScript source below. \
         The workflow must gather evidence through Flow before final synthesis.\n\
         2. Provide `input.query`, `input.local_research_rounds` when you have a \
         strong complexity judgment, and only the `input.tracks` that are genuinely independent \
         enough for round-1 parallel retrieval; choose the count yourself, from one focused track to the \
         local max. Each track should have `title` and `focus`. The workflow will \
         recursively derive follow-up tracks from unresolved gaps and contradictions, \
         then stop at the finite round cap or when no useful follow-up remains. \
         {tracks_directive}\n\
         3. After `dynamic_workflow` returns, read the evidence, cross-check \
         claims across independent sources, call out disagreements and recency \
         caveats, then synthesize a comprehensive answer with inline citations.\n\
         4. Produce a final \"Sources\" list of URLs used and complete the \
         local HTML report view step.\n\n\
         {report_contract}\n\n\
         {duplicate_guard}\n\n\
         Dynamic workflow source:\n\
         ```javascript\n{source}\n```\n\n\
         Query: {query}"
    )
}

pub(crate) fn deep_research_default_budget() -> BudgetPlan {
    budget_plan_for_effort_index(DEFAULT_TUI_EFFORT_INDEX, None, BudgetWorkload::DeepResearch)
}

fn deep_research_budget_for_effort_index(effort: usize, context_limit: u32) -> BudgetPlan {
    budget_plan_for_effort_index(effort, Some(context_limit), BudgetWorkload::DeepResearch)
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct DeepResearchWorkflowBudget {
    complexity_layers: usize,
    local_research_rounds: usize,
    local_max_parallel_tasks: usize,
    local_max_steps: usize,
    runtime_preflight_timeout_ms: u64,
    runtime_step_timeout_ms: u64,
    workflow_timeout_ms: u64,
    workflow_max_tool_calls: usize,
    workflow_max_output_bytes: usize,
}

fn deep_research_workflow_args(query: &str, os_runtime: bool) -> serde_json::Value {
    deep_research_workflow_args_for_budget(query, os_runtime, deep_research_default_budget())
}

fn deep_research_research_rounds(query: &str, os_runtime: bool, budget: BudgetPlan) -> usize {
    let complexity_rounds = deep_research_loop_layers(query, os_runtime).saturating_add(1);
    let effort_cap = match budget.effort_id {
        "low" => 2,
        "medium" => 3,
        _ => 4,
    };
    complexity_rounds.clamp(1, effort_cap)
}

fn deep_research_workflow_budget_for_query(
    query: &str,
    os_runtime: bool,
    budget: BudgetPlan,
) -> DeepResearchWorkflowBudget {
    let complexity_layers = deep_research_loop_layers(query, os_runtime);
    let local_research_rounds = deep_research_research_rounds(query, os_runtime, budget);
    let local_parallel_cap = match complexity_layers {
        0 => 4,
        1 => 6,
        2 => 12,
        _ => budget.max_parallel_tasks,
    };
    let local_step_cap = match complexity_layers {
        0 => 80,
        1 => 140,
        2 => 240,
        _ => budget.deep_research_child_steps,
    };
    let workflow_tool_call_cap = match complexity_layers {
        0 => 120,
        1 => 200,
        2 => 360,
        _ => budget.workflow_max_tool_calls,
    };
    let workflow_output_cap = match complexity_layers {
        0 => 1024 * 1024,
        1 => 2 * 1024 * 1024,
        2 => 4 * 1024 * 1024,
        _ => budget.workflow_max_output_bytes,
    };
    let (runtime_preflight_timeout_ms, runtime_step_timeout_ms) = match complexity_layers {
        0 => (30 * 1000, 4 * 60 * 1000),
        1 => (45 * 1000, 7 * 60 * 1000),
        2 => (60 * 1000, 11 * 60 * 1000),
        _ => (
            DEEP_RESEARCH_RUNTIME_PREFLIGHT_TIMEOUT_MS,
            DEEP_RESEARCH_RUNTIME_STEP_TIMEOUT_MS,
        ),
    };
    let workflow_timeout_ms = runtime_preflight_timeout_ms + runtime_step_timeout_ms + 60 * 1000;

    DeepResearchWorkflowBudget {
        complexity_layers,
        local_research_rounds,
        local_max_parallel_tasks: budget.max_parallel_tasks.min(local_parallel_cap).max(1),
        local_max_steps: budget.deep_research_child_steps.min(local_step_cap).max(1),
        runtime_preflight_timeout_ms,
        runtime_step_timeout_ms,
        workflow_timeout_ms,
        workflow_max_tool_calls: budget
            .workflow_max_tool_calls
            .min(workflow_tool_call_cap)
            .max(
                local_research_rounds
                    .saturating_mul(local_parallel_cap)
                    .max(1),
            ),
        workflow_max_output_bytes: budget
            .workflow_max_output_bytes
            .min(workflow_output_cap)
            .max(256 * 1024),
    }
}

pub(crate) fn deep_research_workflow_timeout_ms(args: &serde_json::Value) -> u64 {
    args.pointer("/limits/timeoutMs")
        .and_then(serde_json::Value::as_u64)
        .filter(|timeout_ms| *timeout_ms >= 1_000)
        .unwrap_or(DEEP_RESEARCH_SCRIPT_TIMEOUT_MS)
}

pub(crate) fn deep_research_workflow_host_timeout_ms(args: &serde_json::Value) -> u64 {
    deep_research_workflow_timeout_ms(args).saturating_add(DEEP_RESEARCH_WORKFLOW_HOST_GRACE_MS)
}

fn deep_research_workflow_args_for_budget(
    query: &str,
    _os_runtime: bool,
    budget: BudgetPlan,
) -> serde_json::Value {
    let os_runtime = false;
    let allowed_tools = serde_json::json!([]);
    let workflow_budget = deep_research_workflow_budget_for_query(query, os_runtime, budget);
    serde_json::json!({
        "source": deep_research_workflow_source(),
        "input": {
            "query": query,
            "os_runtime": os_runtime,
            "complexity_layers": workflow_budget.complexity_layers,
            "runtime_preflight_timeout_ms": workflow_budget.runtime_preflight_timeout_ms,
            "runtime_timeout_ms": workflow_budget.runtime_step_timeout_ms,
            "local_max_parallel_tasks": workflow_budget.local_max_parallel_tasks,
            "local_research_rounds": workflow_budget.local_research_rounds,
            "local_max_steps": workflow_budget.local_max_steps,
        },
        "allowed_tools": allowed_tools,
        "limits": {
            "timeoutMs": workflow_budget.workflow_timeout_ms,
            "maxToolCalls": workflow_budget.workflow_max_tool_calls,
            "maxOutputBytes": workflow_budget.workflow_max_output_bytes
        }
    })
}

fn should_use_os_runtime_for_deep_research(_query: &str, _os_available: bool) -> bool {
    false
}

const DEEP_RESEARCH_PROMPT_SUCCESS_OUTPUT_LIMIT: usize = 1200;
const DEEP_RESEARCH_PROMPT_TEXT_LIMIT: usize = 12_000;
const DEEP_RESEARCH_MAX_DIGEST_EVIDENCE: usize = 18;
const DEEP_RESEARCH_MAX_DIGEST_SOURCES: usize = 12;
const DEEP_RESEARCH_MAX_DIGEST_STRINGS: usize = 12;

fn deep_research_prompt_workflow_output(workflow_output: &str) -> String {
    let value = match serde_json::from_str::<serde_json::Value>(workflow_output) {
        Ok(value) => value,
        Err(_) => {
            if deep_research_output_has_internal_leak(workflow_output) {
                return "Research evidence was non-JSON and contained internal tool logs; raw text withheld from synthesis.".to_string();
            }
            return deep_research_truncate_chars(
                &workflow_output
                    .split_whitespace()
                    .collect::<Vec<_>>()
                    .join(" "),
                DEEP_RESEARCH_PROMPT_TEXT_LIMIT,
            );
        }
    };
    let digest = deep_research_workflow_output_digest(&value);
    serde_json::to_string_pretty(&digest).unwrap_or_else(|_| {
        deep_research_truncate_chars(workflow_output, DEEP_RESEARCH_PROMPT_TEXT_LIMIT)
    })
}

fn deep_research_tool_card_output(workflow_output: &str) -> String {
    workflow_evidence_summary(workflow_output)
        .unwrap_or_else(|| {
            if deep_research_output_has_internal_leak(workflow_output) {
                "Evidence collection returned internal diagnostic logs; raw output withheld from the tool card.".to_string()
            } else {
                deep_research_truncate_chars(workflow_output, 1200)
            }
        })
}

fn deep_research_prompt_metadata(workflow_metadata: Option<&serde_json::Value>) -> String {
    workflow_metadata
        .map(deep_research_workflow_metadata_digest)
        .and_then(|metadata| serde_json::to_string_pretty(&metadata).ok())
        .unwrap_or_else(|| "{}".to_string())
}

fn deep_research_sanitize_workflow_metadata(metadata: &serde_json::Value) -> serde_json::Value {
    let mut sanitized = metadata.clone();
    deep_research_sanitize_parallel_task_values(&mut sanitized);
    sanitized
}

fn deep_research_workflow_output_digest(value: &serde_json::Value) -> serde_json::Value {
    let mut digest = serde_json::Map::new();
    copy_json_field(&mut digest, value, "query");
    digest.insert(
        "collection_status".to_string(),
        serde_json::Value::String(deep_research_collection_status(value).to_string()),
    );
    if let Some(runtime_error) = value.get("runtime_error") {
        digest.insert(
            "collection_error".to_string(),
            serde_json::Value::String(deep_research_error_or_digest_text(runtime_error, 1000)),
        );
    }

    if let Some(research) = value.get("research") {
        if let Some(research) = research.as_object() {
            let mut compact = serde_json::Map::new();
            for key in [
                "algorithm",
                "status",
                "max_rounds",
                "completed_rounds",
                "stop_reason",
            ] {
                copy_json_field(
                    &mut compact,
                    &serde_json::Value::Object(research.clone()),
                    key,
                );
            }
            if let Some(complexity) = research.get("complexity") {
                compact.insert("complexity".to_string(), complexity.clone());
            }
            if let Some(metadata) = research.get("metadata") {
                compact.insert(
                    "counts".to_string(),
                    deep_research_compact_count_metadata(metadata),
                );
            }
            compact.insert(
                "rounds".to_string(),
                deep_research_compact_rounds(research.get("rounds")),
            );
            compact.insert(
                "evidence_items".to_string(),
                serde_json::Value::Array(deep_research_collect_structured_evidence(
                    research.get("runtime_output").unwrap_or(
                        research
                            .get("results")
                            .unwrap_or(research.get("rounds").unwrap_or(&serde_json::Value::Null)),
                    ),
                )),
            );
            if let Some(warnings) = research.get("warnings") {
                compact.insert(
                    "warnings".to_string(),
                    deep_research_compact_warnings(warnings),
                );
            }
            digest.insert("research".to_string(), serde_json::Value::Object(compact));
        } else {
            digest.insert(
                "research_summary".to_string(),
                serde_json::Value::String(deep_research_compact_json_text(
                    research,
                    DEEP_RESEARCH_PROMPT_SUCCESS_OUTPUT_LIMIT,
                )),
            );
        }
    }

    serde_json::Value::Object(digest)
}

fn deep_research_collection_status(value: &serde_json::Value) -> &'static str {
    let mode = value
        .get("mode")
        .and_then(serde_json::Value::as_str)
        .unwrap_or_default();
    if mode.contains("failed") || value.get("error").is_some() {
        "failed"
    } else if value.get("runtime_error").is_some() || mode.contains("fallback") {
        "degraded"
    } else {
        "completed"
    }
}

fn deep_research_workflow_metadata_digest(metadata: &serde_json::Value) -> serde_json::Value {
    let sanitized = deep_research_sanitize_workflow_metadata(metadata);
    let Some(workflow) = sanitized.get("dynamic_workflow") else {
        let evidence_items = deep_research_collect_structured_evidence(&sanitized);
        return if evidence_items.is_empty() {
            serde_json::json!({})
        } else {
            serde_json::json!({ "research_run": { "evidence_items": evidence_items } })
        };
    };
    let mut dynamic = serde_json::Map::new();
    copy_json_field(&mut dynamic, workflow, "status");
    copy_json_field(&mut dynamic, workflow, "last_sequence");

    if let Some(steps) = workflow
        .pointer("/snapshot/steps")
        .and_then(serde_json::Value::as_object)
    {
        let mut compact_steps = Vec::new();
        for (index, step) in steps.values().enumerate() {
            let mut compact = serde_json::Map::new();
            compact.insert(
                "step".to_string(),
                serde_json::Value::Number(serde_json::Number::from(index + 1)),
            );
            copy_json_field(&mut compact, step, "status");
            copy_json_field(&mut compact, step, "attempt");
            if let Some(output) = step.get("output") {
                if let Some(metadata) = output.get("metadata") {
                    compact.insert(
                        "counts".to_string(),
                        deep_research_compact_count_metadata(metadata),
                    );
                }
                if let Some(warnings) = output.get("warnings") {
                    compact.insert(
                        "warnings".to_string(),
                        deep_research_compact_warnings(warnings),
                    );
                }
            }
            compact_steps.push(serde_json::Value::Object(compact));
        }
        dynamic.insert("steps".to_string(), serde_json::Value::Array(compact_steps));
    }
    dynamic.insert(
        "evidence_items".to_string(),
        serde_json::Value::Array(deep_research_collect_structured_evidence(&sanitized)),
    );

    serde_json::json!({ "research_run": dynamic })
}

fn deep_research_sanitize_parallel_task_values(value: &mut serde_json::Value) {
    match value {
        serde_json::Value::Object(map) => {
            let is_parallel_task = map
                .get("tool")
                .or_else(|| map.get("name"))
                .or_else(|| map.get("tool_name"))
                .and_then(serde_json::Value::as_str)
                == Some("parallel_task");
            if is_parallel_task {
                deep_research_sanitize_parallel_task_object(map);
            }
            for value in map.values_mut() {
                deep_research_sanitize_parallel_task_values(value);
            }
        }
        serde_json::Value::Array(items) => {
            for item in items {
                deep_research_sanitize_parallel_task_values(item);
            }
        }
        _ => {}
    }
}

fn deep_research_sanitize_parallel_task_object(
    map: &mut serde_json::Map<String, serde_json::Value>,
) {
    let sanitized_results = map
        .get("metadata")
        .and_then(|metadata| metadata.get("results"))
        .and_then(serde_json::Value::as_array)
        .map(|results| {
            let mut successes = Vec::new();
            let mut failed_tasks = Vec::new();
            for result in results {
                let success = result
                    .get("success")
                    .and_then(serde_json::Value::as_bool)
                    .unwrap_or(false);
                if success {
                    successes.push(deep_research_sanitize_parallel_result(result, true));
                } else {
                    failed_tasks.push(deep_research_sanitize_parallel_result(result, false));
                }
            }
            (successes, failed_tasks)
        });

    if let Some((successes, failed_tasks)) = sanitized_results {
        if let Some(metadata) = map
            .get_mut("metadata")
            .and_then(serde_json::Value::as_object_mut)
        {
            metadata.insert(
                "results".to_string(),
                serde_json::Value::Array(successes.clone()),
            );
        }
        if !failed_tasks.is_empty() {
            let warnings = map
                .entry("warnings".to_string())
                .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()));
            if let Some(warnings) = warnings.as_object_mut() {
                warnings.insert(
                    "failed_tasks".to_string(),
                    serde_json::Value::Array(failed_tasks),
                );
            }
        }
        map.remove("output");
    } else if let Some(output) = map.remove("output") {
        map.insert(
            "output_summary".to_string(),
            serde_json::Value::String(deep_research_compact_json_text(
                &output,
                DEEP_RESEARCH_PROMPT_SUCCESS_OUTPUT_LIMIT,
            )),
        );
    }
}

fn deep_research_sanitize_parallel_result(
    result: &serde_json::Value,
    success: bool,
) -> serde_json::Value {
    let mut next = serde_json::Map::new();
    for key in [
        "task_id",
        "session_id",
        "agent",
        "success",
        "artifact_id",
        "artifact_uri",
        "output_bytes",
        "truncated_for_context",
        "structured_error",
    ] {
        if let Some(value) = result.get(key) {
            next.insert(key.to_string(), value.clone());
        }
    }

    if success {
        if let Some(structured) = result.get("structured") {
            next.insert("structured".to_string(), structured.clone());
        } else if let Some(output) = result.get("output") {
            next.insert(
                "output_summary".to_string(),
                serde_json::Value::String(deep_research_compact_json_text(
                    output,
                    DEEP_RESEARCH_PROMPT_SUCCESS_OUTPUT_LIMIT,
                )),
            );
        }
    } else {
        let summary = result
            .get("output")
            .or_else(|| result.get("error"))
            .map(deep_research_failure_summary)
            .unwrap_or_else(|| {
                "Delegated task failed before returning usable evidence.".to_string()
            });
        next.insert(
            "error_summary".to_string(),
            serde_json::Value::String(summary),
        );
    }

    serde_json::Value::Object(next)
}

fn copy_json_field(
    target: &mut serde_json::Map<String, serde_json::Value>,
    source: &serde_json::Value,
    key: &str,
) {
    if let Some(value) = source.get(key) {
        target.insert(key.to_string(), value.clone());
    }
}

fn deep_research_compact_count_metadata(metadata: &serde_json::Value) -> serde_json::Value {
    let mut counts = serde_json::Map::new();
    for key in [
        "task_count",
        "result_count",
        "success_count",
        "failed_count",
        "all_success",
        "partial_failure",
        "allow_partial_failure",
    ] {
        copy_json_field(&mut counts, metadata, key);
    }
    serde_json::Value::Object(counts)
}

fn deep_research_compact_rounds(rounds: Option<&serde_json::Value>) -> serde_json::Value {
    let items = rounds
        .and_then(serde_json::Value::as_array)
        .map(|rounds| {
            rounds
                .iter()
                .map(|round| {
                    let mut compact = serde_json::Map::new();
                    copy_json_field(&mut compact, round, "round");
                    copy_json_field(&mut compact, round, "status");
                    if let Some(metadata) = round.get("metadata") {
                        compact.insert(
                            "counts".to_string(),
                            deep_research_compact_count_metadata(metadata),
                        );
                    }
                    if let Some(warnings) = round.get("warnings") {
                        compact.insert(
                            "warnings".to_string(),
                            deep_research_compact_warnings(warnings),
                        );
                    }
                    serde_json::Value::Object(compact)
                })
                .collect::<Vec<_>>()
        })
        .unwrap_or_default();
    serde_json::Value::Array(items)
}

fn deep_research_compact_warnings(warnings: &serde_json::Value) -> serde_json::Value {
    let mut compact = serde_json::Map::new();
    if let Some(failed_tasks) = warnings
        .get("failed_tasks")
        .and_then(serde_json::Value::as_array)
    {
        compact.insert(
            "failed_tasks".to_string(),
            serde_json::Value::Array(
                failed_tasks
                    .iter()
                    .take(8)
                    .map(|item| {
                        let mut task = serde_json::Map::new();
                        copy_json_field(&mut task, item, "round");
                        copy_json_field(&mut task, item, "agent");
                        copy_json_field(&mut task, item, "task_id");
                        if let Some(summary) = item
                            .get("error_summary")
                            .or_else(|| item.get("error"))
                            .and_then(serde_json::Value::as_str)
                        {
                            task.insert(
                                "error_summary".to_string(),
                                serde_json::Value::String(deep_research_failure_summary(
                                    &serde_json::Value::String(summary.to_string()),
                                )),
                            );
                        }
                        serde_json::Value::Object(task)
                    })
                    .collect(),
            ),
        );
    }
    if let Some(failed_rounds) = warnings
        .get("failed_rounds")
        .and_then(serde_json::Value::as_array)
    {
        compact.insert(
            "failed_rounds".to_string(),
            serde_json::Value::Array(
                failed_rounds
                    .iter()
                    .take(4)
                    .map(|item| {
                        let mut round = serde_json::Map::new();
                        copy_json_field(&mut round, item, "round");
                        if let Some(error) = item.get("error").and_then(serde_json::Value::as_str) {
                            round.insert(
                                "error".to_string(),
                                serde_json::Value::String(deep_research_failure_summary(
                                    &serde_json::Value::String(error.to_string()),
                                )),
                            );
                        }
                        serde_json::Value::Object(round)
                    })
                    .collect(),
            ),
        );
    }
    serde_json::Value::Object(compact)
}

fn deep_research_collect_structured_evidence(root: &serde_json::Value) -> Vec<serde_json::Value> {
    fn walk(
        value: &serde_json::Value,
        round_hint: Option<u64>,
        out: &mut Vec<serde_json::Value>,
        seen: &mut HashSet<String>,
    ) {
        if out.len() >= DEEP_RESEARCH_MAX_DIGEST_EVIDENCE {
            return;
        }
        match value {
            serde_json::Value::Object(map) => {
                let round = map
                    .get("round")
                    .and_then(serde_json::Value::as_u64)
                    .or(round_hint);
                if let Some(structured) = map.get("structured") {
                    if let Some(compact) =
                        deep_research_compact_evidence_object(structured, round, seen)
                    {
                        out.push(compact);
                    }
                } else if is_deep_research_evidence_object(value) {
                    if let Some(compact) = deep_research_compact_evidence_object(value, round, seen)
                    {
                        out.push(compact);
                    }
                }
                for (key, child) in map {
                    if matches!(
                        key.as_str(),
                        "output_summary" | "error_summary" | "input" | "history"
                    ) || (key == "output" && !child.is_object() && !child.is_array())
                    {
                        continue;
                    }
                    walk(child, round, out, seen);
                    if out.len() >= DEEP_RESEARCH_MAX_DIGEST_EVIDENCE {
                        break;
                    }
                }
            }
            serde_json::Value::Array(items) => {
                for item in items {
                    walk(item, round_hint, out, seen);
                    if out.len() >= DEEP_RESEARCH_MAX_DIGEST_EVIDENCE {
                        break;
                    }
                }
            }
            _ => {}
        }
    }

    let mut out = Vec::new();
    let mut seen = HashSet::new();
    walk(root, None, &mut out, &mut seen);
    out
}

fn is_deep_research_evidence_object(value: &serde_json::Value) -> bool {
    value
        .get("summary")
        .and_then(serde_json::Value::as_str)
        .is_some()
        && value
            .get("sources")
            .and_then(serde_json::Value::as_array)
            .is_some()
        && value
            .get("confidence")
            .and_then(serde_json::Value::as_str)
            .is_some()
}

fn deep_research_compact_evidence_object(
    evidence: &serde_json::Value,
    round: Option<u64>,
    seen: &mut HashSet<String>,
) -> Option<serde_json::Value> {
    let summary = evidence.get("summary")?.as_str()?.trim();
    if summary.is_empty() {
        return None;
    }
    let dedupe_key = format!(
        "{}|{}",
        round.unwrap_or_default(),
        summary.to_ascii_lowercase()
    );
    if !seen.insert(dedupe_key) {
        return None;
    }

    let mut compact = serde_json::Map::new();
    if let Some(round) = round {
        compact.insert(
            "round".to_string(),
            serde_json::Value::Number(serde_json::Number::from(round)),
        );
    }
    compact.insert(
        "summary".to_string(),
        serde_json::Value::String(deep_research_digest_text(summary, 700)),
    );
    compact.insert(
        "sources".to_string(),
        serde_json::Value::Array(
            evidence
                .get("sources")
                .and_then(serde_json::Value::as_array)
                .map(|sources| {
                    sources
                        .iter()
                        .take(DEEP_RESEARCH_MAX_DIGEST_SOURCES)
                        .map(deep_research_compact_source)
                        .collect::<Vec<_>>()
                })
                .unwrap_or_default(),
        ),
    );
    for key in ["key_evidence", "contradictions", "gaps"] {
        compact.insert(
            key.to_string(),
            serde_json::Value::Array(deep_research_compact_string_array(
                evidence.get(key),
                DEEP_RESEARCH_MAX_DIGEST_STRINGS,
                350,
            )),
        );
    }
    if let Some(confidence) = evidence
        .get("confidence")
        .and_then(serde_json::Value::as_str)
    {
        compact.insert(
            "confidence".to_string(),
            serde_json::Value::String(deep_research_digest_text(confidence, 350)),
        );
    }
    Some(serde_json::Value::Object(compact))
}

fn deep_research_compact_source(source: &serde_json::Value) -> serde_json::Value {
    let mut compact = serde_json::Map::new();
    for (key, limit) in [
        ("title", 220usize),
        ("url_or_path", 500),
        ("date", 120),
        ("quote_or_fact", 450),
        ("reliability", 220),
    ] {
        if let Some(value) = source.get(key).and_then(serde_json::Value::as_str) {
            compact.insert(
                key.to_string(),
                serde_json::Value::String(deep_research_digest_text(value, limit)),
            );
        }
    }
    serde_json::Value::Object(compact)
}

fn deep_research_compact_string_array(
    value: Option<&serde_json::Value>,
    max_items: usize,
    max_chars: usize,
) -> Vec<serde_json::Value> {
    let mut seen = HashSet::new();
    value
        .and_then(serde_json::Value::as_array)
        .map(|items| {
            items
                .iter()
                .filter_map(serde_json::Value::as_str)
                .filter_map(|item| {
                    let item = item.trim();
                    if item.is_empty() {
                        return None;
                    }
                    let key = item.to_ascii_lowercase();
                    if !seen.insert(key) {
                        return None;
                    }
                    Some(serde_json::Value::String(deep_research_digest_text(
                        item, max_chars,
                    )))
                })
                .take(max_items)
                .collect::<Vec<_>>()
        })
        .unwrap_or_default()
}

fn deep_research_compact_json_text(value: &serde_json::Value, limit: usize) -> String {
    let text = value
        .as_str()
        .map(str::to_string)
        .unwrap_or_else(|| serde_json::to_string(value).unwrap_or_default());
    let compact = text.split_whitespace().collect::<Vec<_>>().join(" ");
    deep_research_digest_text(&compact, limit)
}

fn deep_research_digest_text(text: &str, limit: usize) -> String {
    let compact = text.split_whitespace().collect::<Vec<_>>().join(" ");
    if compact.is_empty() {
        return compact;
    }
    if deep_research_output_has_internal_leak(&compact) {
        return "Internal workflow/tool log text withheld from DeepResearch synthesis.".to_string();
    }
    deep_research_truncate_chars(&compact, limit)
}

fn deep_research_error_or_digest_text(value: &serde_json::Value, limit: usize) -> String {
    let text = value
        .as_str()
        .map(str::to_string)
        .unwrap_or_else(|| serde_json::to_string(value).unwrap_or_default());
    if deep_research_output_has_internal_leak(&text) {
        deep_research_failure_summary(&serde_json::Value::String(text))
    } else {
        deep_research_digest_text(&text, limit)
    }
}

fn deep_research_failure_summary(value: &serde_json::Value) -> String {
    let text = value
        .as_str()
        .map(str::to_string)
        .unwrap_or_else(|| serde_json::to_string(value).unwrap_or_default());
    let lower = text.to_ascii_lowercase();
    if lower.contains("permission denied: tool") || lower.contains("permission policy denied") {
        return "Delegated task could not use a requested tool because the permission policy denied it.".to_string();
    }
    if lower.contains("max tool rounds") || lower.contains("tool-round budget") {
        return "Delegated task exhausted its tool-round budget before returning usable evidence."
            .to_string();
    }
    if lower.contains("timed out") || lower.contains("[command timed out") {
        return "Delegated task timed out before returning usable evidence.".to_string();
    }
    if lower.contains("[tool output truncated")
        || lower.contains("full output artifact:")
        || lower.contains("a3s://tool-output")
    {
        return "Delegated task produced oversized tool output that was withheld from the report context.".to_string();
    }
    if lower.contains(".a3s-flow/dynamic-workflows")
        || lower.contains("● searched")
        || lower.contains("● ran")
        || lower.contains("● read")
        || text.contains('⎿')
    {
        return "Delegated task returned internal workflow/tool logs that were withheld from the report context.".to_string();
    }
    "Delegated task failed before returning usable evidence.".to_string()
}

fn deep_research_truncate_chars(text: &str, limit: usize) -> String {
    let mut output = String::new();
    let mut truncated = false;
    for (index, ch) in text.chars().enumerate() {
        if index >= limit {
            truncated = true;
            break;
        }
        output.push(ch);
    }
    if truncated {
        output.push_str(" ... [truncated]");
    }
    output
}

fn deep_research_loop_layers(query: &str, os_runtime: bool) -> usize {
    let q = query.trim().to_lowercase();
    if q.is_empty() {
        return 0;
    }
    let local_only_markers = [
        "local only",
        "local workspace",
        "local evidence",
        "local files",
        "local file",
        "workspace evidence",
        "workspace only",
        "repository only",
        "locally",
        "no os",
        "without os",
        "不要 os",
        "不用 os",
        "不使用 os",
        "本地",
        "不要远程",
        "不用远程",
    ];
    if local_only_markers.iter().any(|marker| q.contains(marker)) {
        return 0;
    }

    let mut score = 0usize;
    let groups: &[&[&str]] = &[
        &["comprehensive", "deep dive", "全面", "深入", "调研", "研究"],
        &["compare", "comparison", "benchmark", "对比", "比较", "竞品"],
        &["latest", "recent", "timeline", "最新", "趋势", "时间线"],
        &[
            "market",
            "regulation",
            "policy",
            "paper",
            "papers",
            "市场",
            "法规",
            "政策",
            "论文",
        ],
        &["multi-source", "多来源", "大量", "并行"],
    ];
    for group in groups {
        if group.iter().any(|marker| q.contains(marker)) {
            score += 1;
        }
    }
    let words = q.split_whitespace().count();
    let chars = q.chars().count();
    if words >= 14 || chars >= 80 {
        score += 1;
    }
    if words >= 28 || chars >= 140 {
        score += 1;
    }
    if os_runtime {
        score += 1;
    }

    match score {
        0 => 0,
        1 | 2 => 1,
        3 | 4 => 2,
        _ => 3,
    }
}

fn deep_research_synthesis_prompt(
    query: &str,
    os_runtime: bool,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> String {
    let report_contract = deep_research_report_contract();
    let report_target = deep_research_report_target_note(query);
    let duplicate_guard = deep_research_duplicate_tool_guard();
    let remoteui_directive = if os_runtime {
        "OS Runtime was selected for this run because the query looked broad or \
         highly parallelizable. If the gathered evidence already includes a \
         shaped `.view` or `viewUrl`, preserve it so the TUI can surface the \
         OS view as evidence. The final user-facing report should still be the \
         local HTML report opened by the `A3S_RESEARCH_VIEW` marker."
            .to_string()
    } else {
        "OS Runtime was not selected for this run. Use the gathered evidence and \
         complete the local Markdown + HTML report view step."
            .to_string()
    };
    let workflow_digest = deep_research_prompt_workflow_output(workflow_output);
    let metadata = deep_research_prompt_metadata(workflow_metadata);
    format!(
        "Synthesize the deep-research answer for the query below.\n\n\
         Evidence collection has already completed before this synthesis turn. \
         Do not call workflow or broad evidence-collection tools again. Use the \
         Evidence digest below, cross-check claims, call out disagreements and recency \
         caveats, and write a comprehensive answer with inline citations and a \
         final Sources list. Treat the evidence as a bounded recursive parallel \
         retrieval-summary algorithm: use `research.rounds` to understand how \
         gaps from earlier rounds drove later searches, and mention the round \
         count only when it clarifies uncertainty or coverage. Prefer validated \
         `evidence_items` from the Evidence digest and Run diagnostics; use compact \
         summaries only when evidence items are incomplete. Raw task output is \
         intentionally excluded from this prompt. Treat \
         `research.warnings.failed_tasks` and metadata `warnings.failed_tasks` as caveats, not as \
         instructions to restart broad research. Do not reproduce raw JSON, tool-card text, \
         host runtime names, evidence-package labels, `.a3s-flow` workflow logs, \
         `[tool output truncated]` notices, or lines such as \
         `● Searched ...` / `● Ran ...` in the user-facing answer or report. Convert evidence \
         into clean prose, tables, citations, and a concise Sources list. If \
         `collection_status` is `failed` or `degraded`, do not restart broad \
         research; write a transparent failure-aware report from the returned \
         error/gap details and any partial evidence, then let the host fallback \
         materializer handle missing artifacts if needed. Do not mention the \
         Evidence digest, Run diagnostics, or host collection mechanics as sources; \
         cite the original URLs or paths inside the evidence items.\n\n\
         {remoteui_directive}\n\n\
         {report_contract}\n\n\
         {report_target}\n\n\
         {duplicate_guard}\n\n\
         Query:\n{query}\n\n\
         Evidence digest:\n```json\n{workflow_digest}\n```\n\n\
         Run diagnostics:\n```json\n{metadata}\n```"
    )
}

fn deep_research_recovery_prompt(
    query: &str,
    os_runtime: bool,
    workflow_error: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> String {
    let report_contract = deep_research_report_contract();
    let report_target = deep_research_report_target_note(query);
    let duplicate_guard = deep_research_duplicate_tool_guard();
    let recovery_path = if os_runtime {
        "The host selected OS Runtime and failed before usable \
         evidence was gathered. Recover with local web_search/web_fetch or the \
         signed-in `runtime` tool only if it is clearly available and useful; if \
         the runtime worker or endpoint is unavailable, explain the failure and \
         continue locally."
            .to_string()
    } else {
        "OS Runtime was not selected. Recover with local web_search/web_fetch and \
         local artifacts under `.a3s/research/<slug>/`."
            .to_string()
    };
    let metadata = deep_research_prompt_metadata(workflow_metadata);
    let workflow_error = if deep_research_output_has_internal_leak(workflow_error) {
        deep_research_failure_summary(&serde_json::Value::String(workflow_error.to_string()))
    } else {
        deep_research_truncate_chars(workflow_error, 4000)
    };
    format!(
        "Recover and complete the deep-research task for the query below.\n\n\
         The host evidence preflight failed before usable synthesis evidence was \
         gathered. Do not call workflow or broad evidence-collection tools again \
         unless the recovery path explicitly says to use local research tools. {recovery_path}\n\n\
         Query:\n{query}\n\n\
         Evidence collection error:\n```text\n{workflow_error}\n```\n\n\
         Run diagnostics:\n```json\n{metadata}\n```\n\n\
         {report_contract}\n\n\
         {report_target}\n\n\
         {duplicate_guard}\n\n\
         Deliver a comprehensive answer with inline citations, a final Sources \
         list, local report artifacts, and the required RemoteUI marker."
    )
}

fn deep_research_repair_prompt(
    query: &str,
    os_runtime: bool,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
    prior_text: &str,
) -> String {
    let report_contract = deep_research_report_contract();
    let report_target = deep_research_report_target_note(query);
    let duplicate_guard = deep_research_duplicate_tool_guard();
    let runtime_note = if os_runtime {
        "OS Runtime was selected for the evidence-gathering phase. Preserve any \
         useful OS Runtime evidence, but the required user-facing deliverable is \
         still the local Markdown + HTML report artifact pair."
    } else {
        "OS Runtime was not selected. Use the local evidence already gathered by \
         the host."
    };
    let metadata = deep_research_prompt_metadata(workflow_metadata);
    let workflow_digest = deep_research_prompt_workflow_output(workflow_output);
    let prior = if deep_research_output_has_internal_leak(prior_text) {
        "The previous synthesis was discarded because it contained internal workflow/tool logs or raw JSON. Do not reuse its wording.".to_string()
    } else {
        nonempty_report_section(prior_text, "The previous synthesis returned no text.")
    };
    format!(
        "Repair the DeepResearch report artifact step for the query below.\n\n\
         The previous synthesis did not produce a valid completed report marker \
         and artifact pair. Do not call workflow or broad evidence-collection \
         tools again, do not restart broad research, and do not write ordinary \
         workspace files. Use only the gathered evidence and prior synthesis below \
         to create or correct the \
         required report artifacts under `.a3s/research/<slug>/`. Remove any raw JSON, \
         tool-card text, host runtime names, evidence-package labels, `.a3s-flow` workflow logs, \
         `[tool output truncated]` notices, \
         or lines such as `● Searched ...` / `● Ran ...`; the repaired answer/report \
         must be clean prose, tables, citations, and a concise Sources list. Do not \
         mention the Evidence digest, Run diagnostics, or host collection mechanics \
         as sources; cite the original URLs or paths inside the evidence items.\n\n\
         {runtime_note}\n\n\
         Query:\n{query}\n\n\
         Previous synthesis text:\n```text\n{prior}\n```\n\n\
         Evidence digest:\n```json\n{workflow_digest}\n```\n\n\
         Run diagnostics:\n```json\n{metadata}\n```\n\n\
         {report_contract}\n\n\
         {report_target}\n\n\
         {duplicate_guard}\n\n\
         Complete only the missing report work. End with the required \
         `A3S_RESEARCH_VIEW: .a3s/research/<slug>/index.html` marker only after \
         both files exist, are non-empty, and the HTML document is complete."
    )
}

fn json_contains_tool_evidence(value: &serde_json::Value, tool: &str) -> bool {
    match value {
        serde_json::Value::Object(map) => map.iter().any(|(key, value)| {
            ((key == "name" || key == "tool" || key == "tool_name") && value.as_str() == Some(tool))
                || json_contains_tool_evidence(value, tool)
        }),
        serde_json::Value::Array(items) => items
            .iter()
            .any(|item| json_contains_tool_evidence(item, tool)),
        _ => false,
    }
}

/// The persistent `/goal` north-star for a `?` deep-research task. Kept short
/// since it is prepended to every continuation turn of the long-horizon loop.
fn deep_research_goal(query: &str) -> String {
    format!("Deep research — deliver a comprehensive, well-cited report answering: {query}")
}

/// Append the shared one-column vertical scrollbar to the viewport's visible
/// rows. The viewport is sized to `inner_width` (= screen width - 1, see
/// `relayout`) so the bar never clips content, and the gutter stays blank when
/// nothing overflows the window.
fn append_scrollbar(view: &str, inner_width: usize, total: usize, scroll_percent: u8) -> String {
    let visible = view.split('\n').count();
    Scrollbar::from_scroll_percent(total, visible, scroll_percent)
        .track_color(TN_GRAY)
        .thumb_color(ACCENT)
        .hide_when_not_overflowing(true)
        .append_to_view(view, inner_width)
}

/// The OSC 52 escape that asks the terminal to set the system clipboard to
/// `text` (base64). Works over SSH on terminals that support OSC 52. Capped so a
/// long reply can't blow past a terminal's OSC 52 size limit.
fn osc52_copy(text: &str) -> String {
    use base64::Engine;
    let capped: String = text.chars().take(64_000).collect();
    let b64 = base64::engine::general_purpose::STANDARD.encode(capped.as_bytes());
    format!("\x1b]52;c;{b64}\x07")
}

/// Marker the agent puts inline in its reply to offer the RemoteUI popup. The
/// host recognises a mouse click on any reply line containing it and opens the
/// remembered view. The styled button is still transcript text, so ANSI stripping
/// keeps this marker clickable.
const VIEW_BUTTON_MARKER: &str = "Open view";
const VIEW_BUTTON_CLICK_DRIFT_COLS: u16 = 2;
const RESEARCH_VIEW_MARKER: &str = "A3S_RESEARCH_VIEW:";

#[derive(Clone, Debug, PartialEq, Eq)]
struct ResearchReportArtifacts {
    markdown: std::path::PathBuf,
    html: std::path::PathBuf,
}

fn remote_view_button(detail: &str) -> String {
    InlineAction::new(VIEW_BUTTON_MARKER)
        .icon("↗")
        .colors(Color::BrightWhite, ACCENT)
        .detail_color(TN_GRAY)
        .detail(detail)
        .view()
}

fn research_report_view_spec(output: &str, workspace: &Path) -> Option<remote_ui::ViewSpec> {
    let artifacts = research_report_artifacts_from_output(output, workspace)?;
    remote_ui::local_file_view(&artifacts.html).ok()
}

fn deep_research_report_view_spec_for_query(
    output: &str,
    workspace: &Path,
    query: &str,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> Option<remote_ui::ViewSpec> {
    let artifacts = deep_research_report_artifacts_from_output_for_query(
        output,
        workspace,
        query,
        workflow_output,
        workflow_metadata,
    )?;
    remote_ui::local_file_view(&artifacts.html).ok()
}

fn deep_research_report_is_missing(
    deep_research_active: bool,
    report_already_ready: bool,
    query: Option<&str>,
    review_text: &str,
    workspace: &Path,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> bool {
    if !deep_research_active || report_already_ready {
        return false;
    }
    match query {
        Some(query) => deep_research_report_view_spec_for_query(
            review_text,
            workspace,
            query,
            workflow_output,
            workflow_metadata,
        )
        .is_none(),
        None => research_report_view_spec(review_text, workspace).is_none(),
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum ResearchReportViewAction {
    OpenNow,
    DeferUntilDeepResearchComplete,
}

fn research_report_view_action(deep_research_active: bool) -> ResearchReportViewAction {
    if deep_research_active {
        ResearchReportViewAction::DeferUntilDeepResearchComplete
    } else {
        ResearchReportViewAction::OpenNow
    }
}

fn arm_deep_research_report_repair(loop_remaining: &mut usize, repair_used: &mut bool) -> bool {
    if *repair_used {
        return false;
    }
    *repair_used = true;
    *loop_remaining = (*loop_remaining).max(1);
    true
}

#[derive(Debug)]
enum DeepResearchReportRecovery {
    CompletedMaterialized { artifacts: ResearchReportArtifacts },
    RepairPassArmed,
    FallbackMaterialized { artifacts: ResearchReportArtifacts },
    Missing(String),
}

fn recover_missing_deep_research_report(
    workspace: &Path,
    query: Option<&str>,
    review_text: &str,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
    loop_remaining: &mut usize,
    repair_used: &mut bool,
) -> DeepResearchReportRecovery {
    let Some(query) = query else {
        return DeepResearchReportRecovery::Missing(
            "DeepResearch ended without a valid local HTML report marker".to_string(),
        );
    };

    if let Some(artifacts) = materialize_deep_research_completed_report_from_markdown(
        workspace,
        query,
        workflow_output,
        workflow_metadata,
    ) {
        *loop_remaining = 0;
        return DeepResearchReportRecovery::CompletedMaterialized { artifacts };
    }

    if arm_deep_research_report_repair(loop_remaining, repair_used) {
        return DeepResearchReportRecovery::RepairPassArmed;
    }

    match materialize_deep_research_fallback_draft(workspace, query, review_text, workflow_output) {
        Ok(artifacts) => {
            *loop_remaining = 0;
            DeepResearchReportRecovery::FallbackMaterialized { artifacts }
        }
        Err(error) => DeepResearchReportRecovery::Missing(format!(
            "DeepResearch ended without a valid local HTML report marker ({error})"
        )),
    }
}

fn research_report_artifacts_from_output(
    output: &str,
    workspace: &Path,
) -> Option<ResearchReportArtifacts> {
    research_report_artifacts_from_output_with_slug(output, workspace, None)
}

fn research_report_artifacts_from_output_for_query(
    output: &str,
    workspace: &Path,
    query: &str,
) -> Option<ResearchReportArtifacts> {
    let expected_slug = deep_research_report_slug(query);
    research_report_artifacts_from_output_with_slug(output, workspace, Some(&expected_slug))
}

fn deep_research_report_artifacts_from_output_for_query(
    output: &str,
    workspace: &Path,
    query: &str,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> Option<ResearchReportArtifacts> {
    let artifacts = research_report_artifacts_from_output_for_query(output, workspace, query)?;
    deep_research_report_sources_trace_workflow(&artifacts, workflow_output, workflow_metadata)
        .then_some(artifacts)
}

fn clean_deep_research_final_text_from_artifacts(
    artifacts: &ResearchReportArtifacts,
    workspace: &Path,
) -> Option<String> {
    let markdown = read_small_utf8_file(&artifacts.markdown)?;
    if deep_research_output_has_internal_leak(&markdown) {
        return None;
    }
    let root = workspace.canonicalize().ok()?;
    let rel_html = artifacts.html.strip_prefix(&root).ok()?.to_string_lossy();
    let rel_html = rel_html.replace('\\', "/");
    let body = markdown.trim();
    if body.is_empty() {
        return None;
    }
    Some(format!("{body}\n\n{RESEARCH_VIEW_MARKER} {rel_html}"))
}

fn materialize_deep_research_completed_report_from_markdown(
    workspace: &Path,
    query: &str,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> Option<ResearchReportArtifacts> {
    let root = workspace.canonicalize().ok()?;
    let slug = deep_research_report_slug(query);
    let report_dir = root.join(".a3s").join("research").join(&slug);
    let markdown_path = report_dir.join("report.md");
    let markdown = read_small_utf8_file(&markdown_path)?;
    if looks_like_deep_research_fallback_draft(&markdown)
        || is_deep_research_model_failure_text(&markdown)
        || deep_research_output_has_internal_leak(&markdown)
        || visible_char_count(markdown.trim()) < 120
    {
        return None;
    }

    std::fs::create_dir_all(&report_dir).ok()?;
    let html = deep_research_completed_report_html(query, &markdown);
    std::fs::write(report_dir.join("index.html"), html).ok()?;

    let rel_html = format!(".a3s/research/{slug}/index.html");
    let artifacts = trusted_research_report_artifact_paths(&rel_html, &root)?;
    deep_research_report_sources_trace_workflow(&artifacts, workflow_output, workflow_metadata)
        .then_some(artifacts)
}

fn deep_research_completed_report_html(query: &str, markdown: &str) -> String {
    let title = deep_research_markdown_report_title(markdown, query);
    let body = deep_research_markdown_to_html_fragment(markdown);
    format!(
        "<!doctype html>\n\
         <html lang=\"en\">\n\
         <head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\
         <title>{title}</title>\
         <style>\
         :root{{color-scheme:light dark}}\
         body{{margin:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;line-height:1.62;background:#f8fafc;color:#111827}}\
         main{{max-width:960px;margin:0 auto;padding:36px 22px 56px}}\
         article{{background:#fff;border:1px solid #d1d5db;border-radius:8px;padding:28px}}\
         h1{{font-size:2rem;line-height:1.15;margin:0 0 18px}}\
         h2{{font-size:1.25rem;margin:28px 0 10px;border-top:1px solid #e5e7eb;padding-top:18px}}\
         h3{{font-size:1.05rem;margin:22px 0 8px}}\
         p,li{{font-size:1rem}}\
         a{{color:#0f766e}}\
         code{{background:#f3f4f6;border-radius:4px;padding:0 4px}}\
         pre{{white-space:pre-wrap;word-break:break-word;background:#111827;color:#f9fafb;border-radius:6px;padding:14px;overflow:auto}}\
         ul{{padding-left:22px}}\
         @media (prefers-color-scheme:dark){{body{{background:#0b0f14;color:#e5e7eb}}article{{background:#111827;border-color:#374151}}h2{{border-color:#374151}}code{{background:#1f2937}}a{{color:#5eead4}}}}\
         </style></head>\n\
         <body><main><article>{body}</article></main></body></html>\n",
        title = html_escape(&title),
        body = body,
    )
}

fn deep_research_markdown_report_title(markdown: &str, query: &str) -> String {
    markdown
        .lines()
        .find_map(|line| line.trim().strip_prefix("# "))
        .map(str::trim)
        .filter(|title| !title.is_empty())
        .unwrap_or(query)
        .to_string()
}

fn deep_research_markdown_to_html_fragment(markdown: &str) -> String {
    let mut html = String::new();
    let mut in_code = false;
    let mut in_list = false;

    for line in markdown.lines() {
        let trimmed = line.trim();
        if trimmed.starts_with("```") {
            if in_list {
                html.push_str("</ul>");
                in_list = false;
            }
            if in_code {
                html.push_str("</code></pre>");
            } else {
                html.push_str("<pre><code>");
            }
            in_code = !in_code;
            continue;
        }

        if in_code {
            html.push_str(&html_escape(line));
            html.push('\n');
            continue;
        }

        if trimmed.is_empty() {
            if in_list {
                html.push_str("</ul>");
                in_list = false;
            }
            continue;
        }

        if let Some((level, text)) = markdown_heading(trimmed) {
            if in_list {
                html.push_str("</ul>");
                in_list = false;
            }
            html.push_str(&format!("<h{level}>{}</h{level}>", html_escape(text)));
            continue;
        }

        if let Some(item) = trimmed
            .strip_prefix("- ")
            .or_else(|| trimmed.strip_prefix("* "))
        {
            if !in_list {
                html.push_str("<ul>");
                in_list = true;
            }
            html.push_str(&format!("<li>{}</li>", html_escape(item.trim())));
            continue;
        }

        if in_list {
            html.push_str("</ul>");
            in_list = false;
        }
        html.push_str(&format!("<p>{}</p>", html_escape(trimmed)));
    }

    if in_code {
        html.push_str("</code></pre>");
    }
    if in_list {
        html.push_str("</ul>");
    }
    html
}

fn markdown_heading(line: &str) -> Option<(usize, &str)> {
    let hashes = line.chars().take_while(|ch| *ch == '#').count();
    if !(1..=3).contains(&hashes) {
        return None;
    }
    let text = line.get(hashes..)?.strip_prefix(' ')?.trim();
    (!text.is_empty()).then_some((hashes, text))
}

fn research_report_artifacts_from_output_with_slug(
    output: &str,
    workspace: &Path,
    expected_slug: Option<&str>,
) -> Option<ResearchReportArtifacts> {
    output.lines().rev().find_map(|line| {
        let marker_at = line.find(RESEARCH_VIEW_MARKER)?;
        let raw = &line[marker_at + RESEARCH_VIEW_MARKER.len()..];
        let candidate = clean_research_report_marker_value(raw)?;
        let artifacts = trusted_research_report_artifacts(&candidate, workspace)?;
        match expected_slug {
            Some(slug) if !research_report_artifact_slug_matches(&artifacts, slug) => None,
            _ => Some(artifacts),
        }
    })
}

fn research_report_artifact_slug_matches(
    artifacts: &ResearchReportArtifacts,
    expected_slug: &str,
) -> bool {
    artifacts
        .html
        .parent()
        .and_then(Path::file_name)
        .and_then(|value| value.to_str())
        == Some(expected_slug)
}

fn clean_research_report_marker_value(raw: &str) -> Option<String> {
    let mut value = raw.trim();
    value = value
        .trim_start_matches(|c| matches!(c, '`' | '"' | '\'' | '<'))
        .trim_end_matches(|c| matches!(c, '`' | '"' | '\'' | '>' | '.' | ',' | ';'));
    if value.is_empty() || value.starts_with("file://") {
        return None;
    }
    value
        .split_whitespace()
        .next()
        .filter(|s| !s.is_empty())
        .map(str::to_string)
}

fn trusted_research_report_artifacts(
    candidate: &str,
    workspace: &Path,
) -> Option<ResearchReportArtifacts> {
    let artifacts = trusted_research_report_artifact_paths(candidate, workspace)?;
    completed_research_report_artifacts(&artifacts).then_some(artifacts)
}

fn trusted_research_report_artifact_paths(
    candidate: &str,
    workspace: &Path,
) -> Option<ResearchReportArtifacts> {
    let root = workspace.canonicalize().ok()?;
    let candidate = Path::new(candidate);
    let path = if candidate.is_absolute() {
        candidate.to_path_buf()
    } else {
        workspace.join(candidate)
    }
    .canonicalize()
    .ok()?;
    if !is_nonempty_file(&path) || !path.starts_with(&root) || !is_html_path(&path) {
        return None;
    }
    let rel = path.strip_prefix(&root).ok()?;
    let mut components = rel.components();
    let first = components.next()?.as_os_str();
    let second = components.next()?.as_os_str();
    let slug = components.next()?.as_os_str();
    let file = components.next()?.as_os_str();
    if components.next().is_some() {
        return None;
    }
    if first != std::ffi::OsStr::new(".a3s") || second != std::ffi::OsStr::new("research") {
        return None;
    }
    if slug.is_empty() || file != std::ffi::OsStr::new("index.html") {
        return None;
    }
    let markdown = path.parent()?.join("report.md").canonicalize().ok()?;
    if !is_nonempty_file(&markdown) || !markdown.starts_with(&root) {
        return None;
    }
    Some(ResearchReportArtifacts {
        markdown,
        html: path,
    })
}

fn completed_research_report_artifacts(artifacts: &ResearchReportArtifacts) -> bool {
    let markdown = read_small_utf8_file(&artifacts.markdown);
    let html = read_small_utf8_file(&artifacts.html);
    let (Some(markdown), Some(html)) = (markdown, html) else {
        return false;
    };
    !looks_like_deep_research_fallback_draft(&markdown)
        && !looks_like_deep_research_fallback_draft(&html)
        && !is_deep_research_model_failure_text(&markdown)
        && !is_deep_research_model_failure_text(&html)
        && !deep_research_output_has_internal_leak(&markdown)
        && !deep_research_output_has_internal_leak(&html)
        && complete_html_document(&html)
        && has_research_report_substance(&markdown, &html)
}

fn deep_research_report_sources_trace_workflow(
    artifacts: &ResearchReportArtifacts,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> bool {
    let anchors = deep_research_workflow_source_anchors(workflow_output, workflow_metadata);
    if anchors.is_empty() {
        return true;
    }

    let markdown = read_small_utf8_file(&artifacts.markdown);
    let html = read_small_utf8_file(&artifacts.html);
    let (Some(markdown), Some(html)) = (markdown, html) else {
        return false;
    };
    let report_text =
        normalize_research_source_text(&format!("{}\n{}", markdown, strip_html_tags(&html)));
    anchors
        .iter()
        .any(|anchor| report_text_contains_source_anchor(&report_text, anchor))
}

fn deep_research_workflow_source_anchors(
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
) -> Vec<String> {
    let mut anchors = Vec::new();
    let mut seen = HashSet::new();
    if let Ok(value) = serde_json::from_str::<serde_json::Value>(workflow_output) {
        let digest = deep_research_workflow_output_digest(&value);
        collect_deep_research_source_anchors(&digest, &mut anchors, &mut seen);
    }
    if let Some(metadata) = workflow_metadata {
        let digest = deep_research_workflow_metadata_digest(metadata);
        collect_deep_research_source_anchors(&digest, &mut anchors, &mut seen);
    }
    anchors
}

fn collect_deep_research_source_anchors(
    value: &serde_json::Value,
    anchors: &mut Vec<String>,
    seen: &mut HashSet<String>,
) {
    match value {
        serde_json::Value::Object(map) => {
            for (key, value) in map {
                if key == "url_or_path" {
                    if let Some(anchor) = value
                        .as_str()
                        .and_then(normalize_research_source_anchor)
                        .filter(|anchor| seen.insert(anchor.clone()))
                    {
                        anchors.push(anchor);
                    }
                }
                collect_deep_research_source_anchors(value, anchors, seen);
            }
        }
        serde_json::Value::Array(items) => {
            for item in items {
                collect_deep_research_source_anchors(item, anchors, seen);
            }
        }
        _ => {}
    }
}

fn read_small_utf8_file(path: &Path) -> Option<String> {
    const MAX_REPORT_VALIDATION_BYTES: u64 = 2 * 1024 * 1024;
    let metadata = path.metadata().ok()?;
    if !metadata.is_file() || metadata.len() == 0 || metadata.len() > MAX_REPORT_VALIDATION_BYTES {
        return None;
    }
    std::fs::read_to_string(path).ok()
}

fn complete_html_document(html: &str) -> bool {
    let lower = html.to_ascii_lowercase();
    lower.contains("<html")
        && lower.contains("</html>")
        && lower.contains("<body")
        && lower.contains("</body>")
}

fn has_research_report_substance(markdown: &str, html: &str) -> bool {
    const MIN_MARKDOWN_TEXT_CHARS: usize = 120;
    const MIN_HTML_TEXT_CHARS: usize = 120;

    let markdown_text = markdown.trim();
    let html_text = strip_html_tags(html);
    if visible_char_count(markdown_text) < MIN_MARKDOWN_TEXT_CHARS
        || visible_char_count(&html_text) < MIN_HTML_TEXT_CHARS
    {
        return false;
    }

    let combined = format!("{markdown_text}\n{html_text}").to_lowercase();
    let placeholder_markers = [
        "placeholder",
        "lorem ipsum",
        "todo",
        "tbd",
        "coming soon",
        "under construction",
        "not yet available",
        "待补充",
        "占位",
    ];
    if placeholder_markers
        .iter()
        .any(|marker| combined.contains(marker))
    {
        return false;
    }

    let has_findings = contains_any(
        &combined,
        &[
            "finding",
            "findings",
            "conclusion",
            "conclusions",
            "analysis",
            "recommendation",
            "recommendations",
            "结论",
            "分析",
            "发现",
            "建议",
        ],
    );
    let has_sources = contains_any(
        &combined,
        &[
            "source",
            "sources",
            "evidence",
            "citation",
            "citations",
            "来源",
            "证据",
            "引用",
        ],
    );
    let has_confidence = contains_any(
        &combined,
        &[
            "confidence",
            "caveat",
            "caveats",
            "limitation",
            "limitations",
            "risk",
            "risks",
            "uncertain",
            "uncertainty",
            "置信",
            "限制",
            "风险",
            "不确定",
        ],
    );

    has_findings && has_sources && has_confidence && has_report_source_anchor(&combined)
}

fn deep_research_output_has_internal_leak(text: &str) -> bool {
    let lower = text.to_ascii_lowercase();
    let markers = [
        ".a3s-flow/dynamic-workflows",
        "a3s://tool-output",
        "[tool output truncated",
        "full output artifact:",
        "permission denied: tool",
        "max tool rounds",
        "dynamicworkflowruntime output:",
        "dynamicworkflowruntime metadata:",
        "dynamicworkflowruntime evidence package:",
        "dynamicworkflowruntime diagnostic package:",
        "dynamicworkflowruntime structured evidence",
        "provided dynamicworkflowruntime",
        "evidence digest:",
        "run diagnostics:",
        "provided evidence digest",
        "provided run diagnostics",
        "workflow runtime/evidence-package",
        "workflow evidence\n\n```text",
        "created the target report directory",
        "created the report directory",
        "created `.a3s/research",
        "created .a3s/research",
        "created the markdown report",
        "created the standalone",
        "markdown report written",
        "markdown report written to",
        "wrote the markdown report",
        "wrote the standalone",
        "wrote the html report",
        "wrote the standalone responsive html artifact",
        "verifying the two required report artifacts",
        "targeted verification passed",
        "report.md exists",
        "index.html exists",
        "written and verified successfully",
        "batch verification was unavailable",
        "file-read access is blocked",
        "file-read tooling is currently blocked",
        "unable to verify the two required files",
        "targeted verification could not be performed",
        "verification could not be performed",
        "remaining unverified contract items",
        "step 2 complete",
        "step 3 complete",
        "● searched",
        "● ran",
        "● read ",
        "⎿",
    ];
    if markers.iter().any(|marker| lower.contains(marker)) {
        return true;
    }

    let json_field_hits = [
        "\"summary\"",
        "\"sources\"",
        "\"key_evidence\"",
        "\"contradictions\"",
        "\"confidence\"",
        "\"gaps\"",
        "\"url_or_path\"",
        "\"quote_or_fact\"",
    ]
    .iter()
    .filter(|field| lower.contains(**field))
    .count();
    json_field_hits >= 3
}

fn contains_any(haystack: &str, needles: &[&str]) -> bool {
    needles.iter().any(|needle| haystack.contains(needle))
}

fn has_report_source_anchor(text: &str) -> bool {
    contains_any(
        text,
        &[
            "http://",
            "https://",
            "readme.md",
            "design.md",
            "cargo.toml",
            "package.json",
            "pyproject.toml",
            "src/",
            "crates/",
            "apps/",
            "docs/",
            ".a3s/",
            ".rs",
            ".ts",
            ".tsx",
            ".js",
            ".jsx",
            ".py",
            ".go",
            ".java",
            ".md",
            ".mdx",
            ".pdf",
        ],
    )
}

fn normalize_research_source_anchor(value: &str) -> Option<String> {
    let normalized = normalize_research_source_text(value)
        .trim_matches(|ch: char| {
            matches!(
                ch,
                '`' | '"' | '\'' | '<' | '>' | '(' | ')' | '[' | ']' | '{' | '}'
            )
        })
        .trim_end_matches(|ch: char| matches!(ch, '.' | ',' | ';' | ':' | ')' | ']'))
        .trim()
        .trim_end_matches('/')
        .to_string();
    if normalized.len() < 4
        || normalized.starts_with("a3s://")
        || normalized.contains(".a3s-flow/dynamic-workflows")
        || deep_research_output_has_internal_leak(&normalized)
    {
        None
    } else {
        Some(normalized)
    }
}

fn normalize_research_source_text(value: &str) -> String {
    value
        .to_ascii_lowercase()
        .replace("&amp;", "&")
        .split_whitespace()
        .collect::<Vec<_>>()
        .join(" ")
}

fn report_text_contains_source_anchor(report_text: &str, anchor: &str) -> bool {
    if report_text.contains(anchor) {
        return true;
    }
    anchor
        .strip_suffix('/')
        .filter(|value| value.len() >= 4)
        .is_some_and(|value| report_text.contains(value))
}

fn visible_char_count(text: &str) -> usize {
    text.chars()
        .filter(|ch| !ch.is_whitespace() && !ch.is_control())
        .count()
}

fn strip_html_tags(html: &str) -> String {
    let mut out = String::with_capacity(html.len());
    let mut in_tag = false;
    for ch in html.chars() {
        match ch {
            '<' => {
                in_tag = true;
                out.push(' ');
            }
            '>' => in_tag = false,
            _ if !in_tag => out.push(ch),
            _ => {}
        }
    }
    out
}

fn looks_like_deep_research_fallback_draft(text: &str) -> bool {
    let lower = text.to_ascii_lowercase();
    lower.contains("deepresearch fallback draft")
        || lower.contains("fallback draft")
        || lower.contains("not a completed deepresearch report")
        || lower.contains("not a final report")
}

fn is_html_path(path: &Path) -> bool {
    matches!(
        path.extension()
            .and_then(|ext| ext.to_str())
            .map(str::to_ascii_lowercase)
            .as_deref(),
        Some("html" | "htm")
    )
}

fn is_nonempty_file(path: &Path) -> bool {
    path.metadata()
        .map(|metadata| metadata.is_file() && metadata.len() > 0)
        .unwrap_or(false)
}

fn materialize_deep_research_fallback_draft(
    workspace: &Path,
    query: &str,
    answer_text: &str,
    workflow_output: &str,
) -> Result<ResearchReportArtifacts, String> {
    let slug = deep_research_report_slug(query);
    let rel_html = format!(".a3s/research/{slug}/index.html");
    let report_dir = workspace.join(".a3s").join("research").join(&slug);
    std::fs::create_dir_all(&report_dir)
        .map_err(|e| format!("could not create {}: {e}", report_dir.display()))?;

    let answer = deep_research_fallback_answer(answer_text, workflow_output);
    let evidence = deep_research_fallback_evidence(workflow_output);
    let artifact_note = deep_research_fallback_artifact_note(answer_text);
    let markdown = format!(
        "# DeepResearch Fallback Draft\n\n\
         > This is an incomplete fallback draft. It is not a completed DeepResearch report and \
         should not be opened automatically as a final RemoteUI view.\n\n\
         ## Query\n\n{query}\n\n\
         ## Draft Answer\n\n{answer}\n\n\
         ## Workflow Evidence Digest\n\n```json\n{evidence}\n```\n\n\
         ## Artifact Note\n\n\
         {artifact_note}\n"
    );
    let html = format!(
        "<!doctype html>\n\
         <html lang=\"en\">\n\
         <head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>DeepResearch Fallback Draft</title>\
         <style>body{{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;line-height:1.6;margin:0;background:#f7f7f7;color:#111}}main{{max-width:920px;margin:0 auto;padding:32px 20px}}.banner{{border-left:4px solid #b45309;background:#fff7ed;padding:14px 16px;margin:16px 0}}section{{background:#fff;border:1px solid #ddd;border-radius:8px;padding:20px;margin:16px 0}}pre{{white-space:pre-wrap;word-break:break-word;background:#111;color:#f5f5f5;border-radius:6px;padding:16px;overflow:auto}}</style></head>\n\
         <body><main><h1>DeepResearch Fallback Draft</h1>\
         <div class=\"banner\">This draft was generated after DeepResearch failed to complete. It is not a final report and RemoteUI should not open it automatically.</div>\
         <section><h2>Query</h2><p>{query_html}</p></section>\
         <section><h2>Draft Answer</h2><pre>{answer_html}</pre></section>\
         <section><h2>Workflow Evidence Digest</h2><pre>{evidence_html}</pre></section>\
         <section><h2>Artifact Note</h2><p>{artifact_note_html}</p></section>\
         </main></body></html>\n",
        query_html = html_escape(query),
        answer_html = html_escape(&answer),
        evidence_html = html_escape(&evidence),
        artifact_note_html = html_escape(&artifact_note),
    );

    std::fs::write(report_dir.join("report.md"), markdown)
        .map_err(|e| format!("could not write fallback report.md: {e}"))?;
    std::fs::write(report_dir.join("index.html"), html)
        .map_err(|e| format!("could not write fallback index.html: {e}"))?;

    let artifacts = trusted_research_report_artifact_paths(&rel_html, workspace)
        .ok_or_else(|| "fallback draft artifacts failed validation".to_string())?;
    Ok(artifacts)
}

fn deep_research_report_slug(query: &str) -> String {
    const MAX_READABLE_SLUG_BYTES: usize = 80;
    let base = asset_slug(query);
    if base != "asset" && base.len() <= MAX_READABLE_SLUG_BYTES && query.is_ascii() {
        return base;
    }
    if query.trim().is_empty() {
        return base;
    }

    let hash = deep_research_query_hash(query);
    let hash_text = format!("{hash:016x}");
    let hash_text = &hash_text[..12];
    if base == "asset" {
        return format!("research-{hash_text}");
    }

    let readable = base
        .chars()
        .take(MAX_READABLE_SLUG_BYTES)
        .collect::<String>()
        .trim_matches('-')
        .to_string();
    if readable.is_empty() {
        format!("research-{hash_text}")
    } else {
        format!("{readable}-{hash_text}")
    }
}

fn deep_research_query_hash(query: &str) -> u64 {
    let mut hash = 0xcbf29ce484222325u64;
    for byte in query.as_bytes() {
        hash ^= *byte as u64;
        hash = hash.wrapping_mul(0x100000001b3);
    }
    hash
}

fn nonempty_report_section(text: &str, fallback: &str) -> String {
    let trimmed = text.trim();
    if trimmed.is_empty() {
        fallback.to_string()
    } else {
        trimmed.to_string()
    }
}

fn deep_research_fallback_evidence(workflow_output: &str) -> String {
    let evidence = deep_research_prompt_workflow_output(workflow_output);
    if evidence.trim().is_empty() {
        "{}".to_string()
    } else if deep_research_output_has_internal_leak(&evidence) {
        serde_json::json!({
            "status": "internal_logs_withheld",
            "note": "A3S Code captured diagnostics, but raw tool logs are not written into DeepResearch fallback artifacts."
        })
        .to_string()
    } else {
        evidence
    }
}

fn deep_research_fallback_answer(answer_text: &str, workflow_output: &str) -> String {
    let answer = answer_text.trim();
    if !answer.is_empty()
        && !is_deep_research_model_failure_text(answer)
        && !deep_research_output_has_internal_leak(answer)
    {
        return answer.to_string();
    }
    workflow_evidence_summary(workflow_output).unwrap_or_else(|| {
        "The model did not return a final synthesis, but A3S Code preserved a sanitized workflow evidence digest below.".to_string()
    })
}

fn is_deep_research_model_failure_text(text: &str) -> bool {
    let lower = text.to_ascii_lowercase();
    lower.contains("deepresearch synthesis model call timed out")
        || lower.contains("deepresearch synthesis model call failed")
        || lower.contains("deepresearch repair model call timed out")
        || lower.contains("deepresearch repair model call failed")
}

fn deep_research_fallback_artifact_note(answer_text: &str) -> String {
    let answer = answer_text.trim();
    let mut note = "This fallback draft was materialized by A3S Code because the model response did not create the required completed report artifacts.".to_string();
    if !answer.is_empty() && is_deep_research_model_failure_text(answer) {
        note.push_str("\n\nModel synthesis status: ");
        note.push_str(answer);
    }
    note
}

fn workflow_evidence_summary(workflow_output: &str) -> Option<String> {
    let value: serde_json::Value = serde_json::from_str(workflow_output).ok()?;
    let status = deep_research_collection_status(&value);
    let metadata = value
        .pointer("/research/metadata")
        .or_else(|| value.pointer("/metadata"));
    let success_count = metadata
        .and_then(|v| v.get("success_count"))
        .and_then(serde_json::Value::as_u64);
    let task_count = metadata
        .and_then(|v| v.get("task_count"))
        .and_then(serde_json::Value::as_u64);
    let result_count = metadata
        .and_then(|v| v.get("result_count"))
        .and_then(serde_json::Value::as_u64);
    let count_text = match (success_count, task_count.or(result_count)) {
        (Some(success), Some(total)) => format!("{success}/{total} delegated research tasks"),
        (Some(success), None) => format!("{success} successful delegated research tasks"),
        (None, Some(total)) => format!("{total} delegated research results"),
        (None, None) => "delegated research evidence".to_string(),
    };
    let mut summary = format!(
        "The evidence collection phase ended with {status} status and captured {count_text}. A sanitized evidence digest is preserved below."
    );
    if workflow_output.contains("README.md") {
        summary.push_str(" The evidence includes `README.md` as a cited local source.");
    }
    Some(summary)
}

fn html_escape(text: &str) -> String {
    let mut escaped = String::with_capacity(text.len());
    for ch in text.chars() {
        match ch {
            '&' => escaped.push_str("&amp;"),
            '<' => escaped.push_str("&lt;"),
            '>' => escaped.push_str("&gt;"),
            '"' => escaped.push_str("&quot;"),
            '\'' => escaped.push_str("&#39;"),
            _ => escaped.push(ch),
        }
    }
    escaped
}

/// Put `text` on the system clipboard: OSC 52 (portable, survives SSH on
/// supporting terminals) plus the native tool where we have one (macOS pbcopy).
fn copy_to_clipboard(text: &str) {
    use std::io::Write;
    let mut out = std::io::stdout();
    let _ = out.write_all(osc52_copy(text).as_bytes());
    let _ = out.flush();
    #[cfg(target_os = "macos")]
    {
        if let Ok(mut child) = std::process::Command::new("pbcopy")
            .stdin(std::process::Stdio::piped())
            .spawn()
        {
            if let Some(mut stdin) = child.stdin.take() {
                let _ = stdin.write_all(text.as_bytes());
            }
            let _ = child.wait();
        }
    }
}

/// Background of an active text selection in the transcript.
const SELECTION_BG: Color = SURFACE_SELECTED;

/// An in-progress mouse text-selection in the transcript viewport, in screen
/// cells (visible row, column). `anchor` = drag start, `head` = current point.
#[derive(Clone, Copy)]
struct Selection {
    anchor: (u16, u16),
    head: (u16, u16),
}

impl Selection {
    fn is_empty(&self) -> bool {
        self.anchor == self.head
    }
    /// (top_row, top_col, bottom_row, bottom_col), as usize.
    fn ordered(&self) -> (usize, usize, usize, usize) {
        let (a, b) = if self.anchor <= self.head {
            (self.anchor, self.head)
        } else {
            (self.head, self.anchor)
        };
        (a.0 as usize, a.1 as usize, b.0 as usize, b.1 as usize)
    }
}

fn viewport_mouse_cell(
    row: u16,
    column: u16,
    viewport_rows: usize,
    max_col: u16,
) -> Option<(u16, u16)> {
    if viewport_rows == 0 || row as usize >= viewport_rows {
        None
    } else {
        Some((row, column.min(max_col)))
    }
}

fn viewport_mouse_cell_clamped(
    row: u16,
    column: u16,
    viewport_rows: usize,
    max_col: u16,
) -> Option<(u16, u16)> {
    if viewport_rows == 0 {
        None
    } else {
        Some((
            row.min(viewport_rows.saturating_sub(1) as u16),
            column.min(max_col),
        ))
    }
}

/// Substring of `s` spanning visible columns `[from, to)` (wide chars counted by
/// display width). A char straddling the start is dropped; one straddling the
/// end is kept.
fn slice_cols(s: &str, from: usize, to: usize) -> String {
    let mut col = 0usize;
    let mut out = String::new();
    for ch in s.chars() {
        if col >= to {
            break;
        }
        if col >= from {
            out.push(ch);
        }
        col += a3s_tui::style::visible_len(&ch.to_string());
    }
    out
}

/// Plain text of a selection over the rendered viewport `view`: screen rows
/// `r1..=r2`, columns `[c1, c2)` clipped on the first/last rows. Rows are
/// ANSI-stripped and trailing padding trimmed.
fn selection_to_text(view: &str, r1: usize, c1: usize, r2: usize, c2: usize) -> String {
    let rows: Vec<&str> = view.split('\n').collect();
    let mut out: Vec<String> = Vec::new();
    for r in r1..=r2 {
        let Some(row) = rows.get(r) else { break };
        let plain = a3s_tui::style::strip_ansi(row);
        let from = if r == r1 { c1 } else { 0 };
        let to = if r == r2 { c2 } else { usize::MAX };
        out.push(slice_cols(&plain, from, to).trim_end().to_string());
    }
    out.join("\n")
}

fn viewport_row_contains_view_button(view: &str, row: u16) -> bool {
    view.split('\n')
        .nth(row as usize)
        .map(a3s_tui::style::strip_ansi)
        .is_some_and(|line| line.to_ascii_lowercase().contains("open view"))
}

fn is_remote_view_click(view: &str, selection: Selection) -> bool {
    selection.anchor.0 == selection.head.0
        && selection.anchor.1.abs_diff(selection.head.1) <= VIEW_BUTTON_CLICK_DRIFT_COLS
        && viewport_row_contains_view_button(view, selection.anchor.0)
}

fn is_quit_key(key: &KeyEvent) -> bool {
    key.modifiers.contains(KeyModifiers::CONTROL)
        && matches!(key.code, KeyCode::Char(c) if c.eq_ignore_ascii_case(&'c'))
}

fn quit_is_confirmed(armed: Option<Instant>, now: Instant) -> bool {
    armed.is_some_and(|t| now.saturating_duration_since(t) < Duration::from_secs(2))
}

/// Re-render the viewport `view` with the selected span highlighted: selected
/// rows render in plain text (no syntax colour, transiently) with the selected
/// columns on `SELECTION_BG`; other rows keep their styling.
fn highlight_selection(view: &str, r1: usize, c1: usize, r2: usize, c2: usize) -> String {
    let bg = Style::new().bg(SELECTION_BG).fg(TN_FG);
    view.split('\n')
        .enumerate()
        .map(|(i, row)| {
            if i < r1 || i > r2 {
                return row.to_string();
            }
            let plain = a3s_tui::style::strip_ansi(row);
            let from = if i == r1 { c1 } else { 0 };
            let to = if i == r2 { c2 } else { usize::MAX };
            let before = slice_cols(&plain, 0, from);
            let sel = slice_cols(&plain, from, to);
            let after = slice_cols(&plain, to, usize::MAX);
            format!("{before}{}{after}", bg.render(&sel))
        })
        .collect::<Vec<_>>()
        .join("\n")
}

/// State of the `/ide` panel: the file tree, selection, and the open file.
/// Also backs `/config` (rooted at the config dir) and the `/kb` browser
/// (rooted at the vault, with delete enabled) — all superfile-styled.
struct Ide {
    entries: Vec<IdeEntry>,
    sel: usize,
    tree_scroll: usize,
    file: Option<IdeFile>,
    focus_editor: bool,
    /// Transient save status shown in the footer (set on Ctrl+S).
    flash: Option<String>,
    /// Left-panel title ("workspace" / "config" / "knowledge base").
    title: String,
    /// Superfile-style hover preview of the tree-selected file, keyed by path
    /// so it reloads only when the selection actually moves.
    preview: Option<(std::path::PathBuf, Vec<String>)>,
    /// Active command prompt inside the editor footer (`/`, `?`, `:`).
    prompt: Option<IdePrompt>,
    /// `/kb` browser: the vault root. Enables `x` delete, hard-bounded to
    /// paths inside this root. `None` for /ide and /config.
    kb_root: Option<std::path::PathBuf>,
    /// A path armed for deletion — the next `x` on the same selection deletes.
    armed_delete: Option<std::path::PathBuf>,
    /// Selected action in the `/kb` delete confirmation row (`true` = delete).
    delete_confirm_yes: bool,
}

impl Ide {
    /// A fresh panel over `entries` (no file open, tree focused).
    fn browse(entries: Vec<IdeEntry>, title: &str) -> Self {
        Ide {
            entries,
            sel: 0,
            tree_scroll: 0,
            file: None,
            focus_editor: false,
            flash: None,
            title: title.to_string(),
            preview: None,
            prompt: None,
            kb_root: None,
            armed_delete: None,
            delete_confirm_yes: true,
        }
    }
}

/// Directory children for the tree, dirs first then files, noise skipped.
fn ide_children(dir: &std::path::Path, depth: usize) -> Vec<IdeEntry> {
    let mut v: Vec<IdeEntry> = std::fs::read_dir(dir)
        .into_iter()
        .flatten()
        .flatten()
        .filter_map(|e| {
            let name = e.file_name().to_string_lossy().into_owned();
            if matches!(
                name.as_str(),
                ".git" | "node_modules" | "target" | ".DS_Store" | ".next" | "dist"
            ) {
                return None;
            }
            let is_dir = e.path().is_dir();
            Some(IdeEntry {
                path: e.path(),
                name,
                depth,
                is_dir,
                expanded: false,
            })
        })
        .collect();
    v.sort_by(|a, b| {
        b.is_dir
            .cmp(&a.is_dir)
            .then(a.name.to_lowercase().cmp(&b.name.to_lowercase()))
    });
    v
}

/// Project instructions for the agent's system prompt. a3s-code already
/// auto-loads `AGENTS.md`; this adds Claude Code's `CLAUDE.md` (preferred), so
/// existing projects work unchanged. Returns the content wrapped with a header.
fn project_instructions(workspace: &str) -> Option<String> {
    for name in ["CLAUDE.md", "AGENT.md"] {
        let p = std::path::Path::new(workspace).join(name);
        if let Ok(c) = std::fs::read_to_string(&p) {
            if !c.trim().is_empty() {
                return Some(format!("# Project Instructions ({name})\n\n{c}"));
            }
        }
    }
    None
}

/// Left margin for the whole UI (inner padding).
const PAD: usize = 2;

fn viewport_content_width_for(width: u16) -> usize {
    (width as usize).saturating_sub(1)
}

fn transcript_markdown_width_for(width: u16) -> usize {
    viewport_content_width_for(width).saturating_sub(PAD + 2)
}

/// Run mode, cycled with Shift+Tab.
#[derive(Clone, Copy, PartialEq)]
enum Mode {
    /// Approve every tool call.
    Default,
    /// Read-only tools auto-approved; writes still prompt (exploration/planning).
    Plan,
    /// Auto-approve every tool call.
    Auto,
}

impl Mode {
    fn next(self) -> Self {
        match self {
            Mode::Default => Mode::Plan,
            Mode::Plan => Mode::Auto,
            Mode::Auto => Mode::Default,
        }
    }

    fn glyph(self) -> &'static str {
        match self {
            Mode::Default => "⏵",
            Mode::Plan => "✎",
            Mode::Auto => "⏵⏵",
        }
    }

    /// Short one-word name for the status line ("auto mode on").
    fn name(self) -> &'static str {
        match self {
            Mode::Default => "default",
            Mode::Plan => "plan",
            Mode::Auto => "auto",
        }
    }

    fn color(self) -> Color {
        match self {
            Mode::Default => TN_FG,
            Mode::Plan => TN_CYAN,
            Mode::Auto => TN_GREEN,
        }
    }

    /// Whether a tool call is auto-approved in this mode.
    fn auto_approves(self, tool: &str) -> bool {
        match self {
            Mode::Auto => true,
            Mode::Plan => is_readonly_tool(tool),
            Mode::Default => false,
        }
    }
}

fn is_readonly_tool(name: &str) -> bool {
    matches!(
        name,
        "read" | "grep" | "ls" | "glob" | "find" | "search" | "web_search" | "web_fetch"
    )
}

/// A user message queued while the agent is busy. Priority queue: lower `prio`
/// runs first, FIFO within a priority.
struct Queued {
    prio: u8,
    seq: u64,
    text: String,
    display: String,
    runtime_expectation: Option<RuntimeExpectation>,
    deep_research: Option<(String, bool)>,
}

impl PartialEq for Queued {
    fn eq(&self, o: &Self) -> bool {
        self.prio == o.prio && self.seq == o.seq
    }
}
impl Eq for Queued {}
impl Ord for Queued {
    fn cmp(&self, o: &Self) -> std::cmp::Ordering {
        // BinaryHeap is a max-heap; invert so lowest prio, then lowest seq, pops first.
        o.prio.cmp(&self.prio).then(o.seq.cmp(&self.seq))
    }
}
impl PartialOrd for Queued {
    fn partial_cmp(&self, o: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(o))
    }
}

/// Shared, single-consumer receiver for the active agent run. Wrapped so the
/// pump command can own a clone; pumps run sequentially, so the mutex never
/// actually contends.
type SharedRx = Arc<Mutex<mpsc::Receiver<AgentEvent>>>;
type SharedManifestRx =
    Arc<Mutex<tokio::sync::broadcast::Receiver<LocalWorkspaceManifestSnapshot>>>;
type StreamJoin = tokio::task::JoinHandle<()>;
type HostToolAbort = tokio::task::AbortHandle;

#[derive(PartialEq)]
enum State {
    Idle,
    Streaming,
    Awaiting,
}

#[derive(Clone)]
#[allow(clippy::enum_variant_names)]
enum Action {
    ScrollUp,
    ScrollDown,
    ScrollTop,
    ScrollBottom,
}

/// Set by `/update` when an upgrade is available: after the TUI exits (terminal
/// restored), `run` performs the upgrade (Homebrew or standalone download) and
/// re-execs the freshly-installed binary.
static UPGRADE_ON_EXIT: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
/// The latest version tag, stashed by `/update` for the post-exit upgrade.
static LATEST: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None);

enum Msg {
    Term(Event),
    // Boxed: AgentEvent is large; keeps the Msg enum small.
    Agent(Box<AgentEvent>),
    Submit(String),
    StreamStarted(SharedRx, StreamJoin),
    StreamEnded,
    StreamError(String),
    WorkspaceManifest(Box<LocalWorkspaceManifestSnapshot>),
    WorkspaceManifestStopped,
    SpinnerTick,
    /// Advance the welcome-mascot animation frame.
    BannerTick,
    ModalConfirm(usize),
    Resume,
    Interrupted,
    /// Output of a `!`-prefixed shell command.
    ShellOutput(String),
    /// Host-controlled `?` deep-research workflow finished; next step is synthesis.
    DeepResearchWorkflowCompleted {
        query: String,
        os_runtime: bool,
        args: serde_json::Value,
        result: Result<ToolCallResult, String>,
    },
    /// A DeepResearch synthesis/repair stream exceeded its host-side model budget.
    DeepResearchSynthesisTimedOut {
        token: u64,
    },
    /// `/update` version check finished: the latest version tag, if reachable.
    UpdatePlan(Option<String>),
    /// `/update` found no binary upgrade was needed and repaired companion tools.
    UpdateRepair(Result<Vec<String>, String>),
    /// OS login completed.
    OsLogin(Result<String, String>),
    /// Post-login SSH-key sync finished (registers the local pubkey with OS).
    SshKeySynced(crate::a3s_os::SshKeyOutcome),
    /// OS access token was refreshed (or refresh failed) in the background.
    OsRefreshed(Result<crate::a3s_os::StoredOsSession, String>),
    /// OS unified-gateway model ids fetched for the `/model` picker.
    OsGatewayModels {
        login_at_ms: u64,
        result: Result<Vec<crate::a3s_os::GatewayModel>, String>,
    },
    /// Answer from a `/btw` background side-thread.
    SideNote(String),
    /// Refreshed process snapshot for the `/top` panel.
    TopData(Vec<ProcessRow>),
    /// Tick to re-fetch the `/top` snapshot.
    TopRefresh,
    /// `/fork` copied the session under a new id (Ok) — swap the active session to
    /// it — or failed (Err with a reason).
    Forked(Result<String, String>),
    /// `/memory` graph data loaded (timeline + details + derived graph).
    MemoryLoaded(MemPanelData),
    /// A `/memory` forget-candidate deletion finished, with fresh graph data.
    MemoryForgotten(Result<(String, MemPanelData), String>),
    /// Asset-scoped OS asset list loaded.
    AssetListLoaded(Result<panels::asset_resources::AssetListFetch, String>),
    /// Runtime activity rows loaded for an asset-scoped activity panel.
    RuntimeActivityLoaded(Result<panels::asset_resources::RuntimeActivityFetch, String>),
    /// `/kb import` finished; carries the one-line summary to show.
    KbAdded(String),
    /// `/ctx <query>` finished: raw `ctx search --json` stdout (or the error).
    CtxResults(Result<String, String>),
    /// `/ctx <n>` finished: (hit title, transcript window) to stage as context.
    CtxWindow(Result<(String, String), String>),
    /// `/ctx save <n>` finished: Ok(hit title) once written to the memory store.
    CtxSaved(Result<String, String>),
    /// `/sleep` finished persisting its consolidated memories (count on Ok).
    SleepSaved(Result<usize, String>),
    /// `/flow` published/opened/inspected an OS Workflow as a Service asset.
    FlowOsCompleted(Result<panels::flow::FlowOsResult, String>),
    /// `/agent` published/opened an OS agent asset through Agent as a Service or Function as a Service.
    AgentOsCompleted(Result<panels::agent::AgentOsResult, String>),
    /// `/mcp` published/ran/tested an OS Function as a Service MCP asset.
    McpOsCompleted(Result<panels::mcp::McpOsResult, String>),
    /// `/skill` published/deployed/inspected an OS Function as a Service skill asset.
    SkillOsCompleted(Result<panels::skill::SkillOsResult, String>),
    /// `/okf` published/deployed an OS Knowledge service package asset.
    OkfOsCompleted(Result<panels::okf::OkfOsResult, String>),
    /// Asset source was cloned into the local asset workspace.
    AssetCloned(Result<asset_clone::AssetCloneResult, String>),
    /// `/memory` → ctx back-jump finished: (ctx event id, transcript window).
    CtxMemorySource(Result<(String, String), String>),
    /// Inactivity auto-review summary text.
    AutoReview(String),
    /// `/compact` produced this conversation summary; reseed a fresh session.
    Compacted(String),
    /// Startup update check completed with the latest published version (if any).
    UpdateCheck(Option<String>),
}

impl From<Event> for Msg {
    fn from(event: Event) -> Self {
        // Ctrl+C is handled in the key loop as a global graceful quit key.
        Msg::Term(event)
    }
}

/// Read one event from the active run and turn it into a `Msg`.
fn pump(rx: SharedRx) -> Cmd<Msg> {
    cmd::cmd(move || async move {
        let mut guard = rx.lock().await;
        match guard.recv().await {
            Some(event) => Msg::Agent(Box::new(event)),
            None => Msg::StreamEnded,
        }
    })
}

fn pump_manifest(rx: SharedManifestRx) -> Cmd<Msg> {
    cmd::cmd(move || async move {
        let mut guard = rx.lock().await;
        loop {
            match guard.recv().await {
                Ok(snapshot) => return Msg::WorkspaceManifest(Box::new(snapshot)),
                Err(tokio::sync::broadcast::error::RecvError::Lagged(_)) => continue,
                Err(tokio::sync::broadcast::error::RecvError::Closed) => {
                    return Msg::WorkspaceManifestStopped;
                }
            }
        }
    })
}

fn spinner_tick() -> Cmd<Msg> {
    cmd::tick(Duration::from_millis(80), Msg::SpinnerTick)
}

fn resume_after_pending_confirmation_cmd(rx: Option<SharedRx>) -> Cmd<Msg> {
    let mut cmds = vec![spinner_tick()];
    if let Some(rx) = rx {
        cmds.push(pump(rx));
    }
    cmd::batch(cmds)
}

/// Drives the welcome-mascot animation while the banner is on screen.
fn banner_tick() -> Cmd<Msg> {
    cmd::tick(Duration::from_millis(280), Msg::BannerTick)
}

fn with_recent_workspace_context(
    opts: SessionOptions,
    manifest: &Arc<LocalWorkspaceManifest>,
) -> SessionOptions {
    opts.with_context_provider(Arc::new(RecentWorkspaceFilesContextProvider::new(
        manifest.clone(),
    )))
}

fn tui_session_options(confirmation: a3s_code_core::hitl::ConfirmationPolicy) -> SessionOptions {
    tui_session_options_with_gate(confirmation, DeepResearchReportToolGate::default())
}

fn tui_session_options_with_gate(
    confirmation: a3s_code_core::hitl::ConfirmationPolicy,
    deep_research_report_tool_gate: DeepResearchReportToolGate,
) -> SessionOptions {
    let permission_policy = tui_permission_policy();
    SessionOptions::new()
        .with_confirmation_policy(confirmation)
        .with_permission_policy(permission_policy.clone())
        .with_permission_checker(Arc::new(TuiHitlPermissionChecker::new(
            permission_policy,
            deep_research_report_tool_gate,
        )))
        .with_tool_timeout(TOOL_EXEC_TIMEOUT_MS)
        .with_duplicate_tool_call_threshold(TUI_DUPLICATE_TOOL_CALL_THRESHOLD)
}

/// Core serializable permission policy for the TUI.
///
/// The runtime checker below layers structured decisions for bash, git, and
/// batch on top of this policy. Keep this policy conservative and serializable
/// so persisted sessions still have a safe fallback.
fn tui_permission_policy() -> a3s_code_core::permissions::PermissionPolicy {
    a3s_code_core::permissions::PermissionPolicy::new()
        .allow_all(&[
            "Read(*)",
            "Grep(*)",
            "Glob(*)",
            "LS(*)",
            "web_search(*)",
            "web_fetch(*)",
            "Write(.a3s/research/**)",
            "Write(**/.a3s/research/**)",
            "Edit(.a3s/research/**)",
            "Edit(**/.a3s/research/**)",
        ])
        .ask_all(&[
            "Write(*)",
            "Edit(*)",
            "Patch(*)",
            "Bash(*)",
            "Git(*)",
            "batch(*)",
            "program(*)",
            "task(*)",
            "parallel_task(*)",
            "dynamic_workflow(*)",
            "Skill(*)",
        ])
}

#[derive(Clone, Default)]
struct DeepResearchReportToolGate {
    report_only: Arc<AtomicBool>,
}

impl DeepResearchReportToolGate {
    fn set_report_only(&self, enabled: bool) {
        self.report_only.store(enabled, Ordering::SeqCst);
    }

    fn report_only(&self) -> bool {
        self.report_only.load(Ordering::SeqCst)
    }
}

#[derive(Clone)]
struct TuiHitlPermissionChecker {
    base: a3s_code_core::permissions::PermissionPolicy,
    deep_research_report_tool_gate: DeepResearchReportToolGate,
}

impl TuiHitlPermissionChecker {
    fn new(
        base: a3s_code_core::permissions::PermissionPolicy,
        deep_research_report_tool_gate: DeepResearchReportToolGate,
    ) -> Self {
        Self {
            base,
            deep_research_report_tool_gate,
        }
    }

    fn check_batch(
        &self,
        args: &serde_json::Value,
    ) -> a3s_code_core::permissions::PermissionDecision {
        let Some(invocations) = args.get("invocations").and_then(|value| value.as_array()) else {
            return a3s_code_core::permissions::PermissionDecision::Ask;
        };
        if invocations.is_empty() {
            return a3s_code_core::permissions::PermissionDecision::Ask;
        }

        let mut saw_ask = false;
        for invocation in invocations {
            match self.check_batch_invocation(invocation) {
                a3s_code_core::permissions::PermissionDecision::Deny => {
                    return a3s_code_core::permissions::PermissionDecision::Deny;
                }
                a3s_code_core::permissions::PermissionDecision::Ask => saw_ask = true,
                a3s_code_core::permissions::PermissionDecision::Allow => {}
            }
        }

        if saw_ask {
            a3s_code_core::permissions::PermissionDecision::Ask
        } else {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
    }

    fn check_batch_invocation(
        &self,
        invocation: &serde_json::Value,
    ) -> a3s_code_core::permissions::PermissionDecision {
        let Some(tool) = invocation.get("tool").and_then(|value| value.as_str()) else {
            return a3s_code_core::permissions::PermissionDecision::Ask;
        };
        let empty_args = serde_json::Value::Object(serde_json::Map::new());
        let tool_args = invocation.get("args").unwrap_or(&empty_args);

        if tool.eq_ignore_ascii_case("batch") {
            return a3s_code_core::permissions::PermissionDecision::Ask;
        }

        self.check_tool(tool, tool_args)
    }

    fn check_tool(
        &self,
        tool_name: &str,
        args: &serde_json::Value,
    ) -> a3s_code_core::permissions::PermissionDecision {
        if self.deep_research_report_tool_gate.report_only() {
            return deep_research_report_phase_tool_permission(tool_name, args);
        }

        let base = self.base.check(tool_name, args);
        if matches!(base, a3s_code_core::permissions::PermissionDecision::Deny) {
            return base;
        }

        match tool_name.to_ascii_lowercase().as_str() {
            "bash" => tui_bash_permission(args),
            "git" => tui_git_permission(args),
            "batch" => self.check_batch(args),
            _ => base,
        }
    }
}

fn deep_research_report_phase_tool_permission(
    tool_name: &str,
    args: &serde_json::Value,
) -> a3s_code_core::permissions::PermissionDecision {
    match tool_name.to_ascii_lowercase().as_str() {
        "write" | "edit" if is_deep_research_report_artifact_write_tool_args(args) => {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
        "read" | "ls" | "glob" | "grep"
            if is_deep_research_report_artifact_read_tool_args(args) =>
        {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
        _ => a3s_code_core::permissions::PermissionDecision::Deny,
    }
}

fn is_deep_research_report_artifact_write_tool_args(args: &serde_json::Value) -> bool {
    ["file_path", "path"]
        .iter()
        .filter_map(|key| args.get(*key).and_then(serde_json::Value::as_str))
        .any(is_deep_research_report_artifact_path)
}

fn is_deep_research_report_artifact_read_tool_args(args: &serde_json::Value) -> bool {
    [
        "file_path",
        "path",
        "dir",
        "directory",
        "root",
        "pattern",
        "glob",
        "include",
    ]
    .iter()
    .filter_map(|key| args.get(*key).and_then(serde_json::Value::as_str))
    .any(is_deep_research_report_artifact_path)
}

fn is_deep_research_report_artifact_path(path: &str) -> bool {
    let normalized = path.replace('\\', "/");
    normalized.starts_with(".a3s/research/") || normalized.contains("/.a3s/research/")
}

impl a3s_code_core::permissions::PermissionChecker for TuiHitlPermissionChecker {
    fn check(
        &self,
        tool_name: &str,
        args: &serde_json::Value,
    ) -> a3s_code_core::permissions::PermissionDecision {
        self.check_tool(tool_name, args)
    }
}

fn tui_bash_permission(args: &serde_json::Value) -> a3s_code_core::permissions::PermissionDecision {
    let Some(command) = args.get("command").and_then(|value| value.as_str()) else {
        return a3s_code_core::permissions::PermissionDecision::Ask;
    };
    let command = command.trim();
    if command.is_empty() {
        return a3s_code_core::permissions::PermissionDecision::Ask;
    }

    if is_catastrophic_bash_command(command) {
        return a3s_code_core::permissions::PermissionDecision::Deny;
    }

    if is_readonly_bash_command(command) {
        return a3s_code_core::permissions::PermissionDecision::Allow;
    }

    a3s_code_core::permissions::PermissionDecision::Ask
}

fn tui_git_permission(args: &serde_json::Value) -> a3s_code_core::permissions::PermissionDecision {
    let Some(command) = args.get("command").and_then(|value| value.as_str()) else {
        return a3s_code_core::permissions::PermissionDecision::Ask;
    };

    match command {
        "status" | "log" | "diff" | "remote" => {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
        "branch" if args.get("name").and_then(|value| value.as_str()).is_none() => {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
        "stash"
            if args
                .get("message")
                .and_then(|value| value.as_str())
                .is_none()
                && !args
                    .get("include_untracked")
                    .and_then(|value| value.as_bool())
                    .unwrap_or(false) =>
        {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
        "worktree"
            if args
                .get("subcommand")
                .and_then(|value| value.as_str())
                .unwrap_or("list")
                == "list" =>
        {
            a3s_code_core::permissions::PermissionDecision::Allow
        }
        _ => a3s_code_core::permissions::PermissionDecision::Ask,
    }
}

fn normalized_shell(command: &str) -> String {
    command.split_whitespace().collect::<Vec<_>>().join(" ")
}

fn is_catastrophic_bash_command(command: &str) -> bool {
    let normalized = normalized_shell(command);
    let lower = normalized.to_ascii_lowercase();

    if lower == "sudo" || lower.starts_with("sudo ") || lower.starts_with("doas ") {
        return true;
    }
    if lower == "su" || lower.starts_with("su ") || lower.starts_with("su -") {
        return true;
    }
    if lower.contains("mkfs")
        || lower.contains("diskutil erase")
        || lower.contains(":(){")
        || lower.contains("kill -9 -1")
        || lower.starts_with("shutdown")
        || lower.starts_with("reboot")
    {
        return true;
    }
    if (lower.contains("curl ") || lower.contains("wget "))
        && (lower.contains("| sh")
            || lower.contains("|sh")
            || lower.contains("| bash")
            || lower.contains("|bash")
            || lower.contains("| zsh")
            || lower.contains("|zsh"))
    {
        return true;
    }
    if (lower.starts_with("dd ") || lower.contains(" dd "))
        && (lower.contains(" of=/dev/") || lower.contains("of=/dev/"))
    {
        return true;
    }
    if lower.contains("rm -rf /")
        || lower.contains("rm -fr /")
        || lower.contains("rm -rf ~")
        || lower.contains("rm -fr ~")
        || lower.contains("rm -rf $home")
        || lower.contains("rm -fr $home")
        || lower.contains("rm -rf *")
        || lower.contains("rm -fr *")
        || lower == "rm -rf ."
        || lower == "rm -fr ."
    {
        return true;
    }

    false
}

fn is_readonly_bash_command(command: &str) -> bool {
    if command.contains("&&")
        || command.contains("||")
        || command.contains(';')
        || command.contains('>')
        || command.contains('<')
        || command.contains('`')
        || command.contains("$(")
        || command.contains('&')
        || has_absolute_or_home_path_token(command)
    {
        return false;
    }

    command
        .split('|')
        .all(|segment| is_readonly_bash_segment(segment.trim()))
}

fn has_absolute_or_home_path_token(command: &str) -> bool {
    command.split_whitespace().any(|token| {
        let token = token.trim_matches(|c: char| {
            matches!(
                c,
                '\'' | '"' | '(' | ')' | '[' | ']' | '{' | '}' | ',' | ':'
            )
        });
        token.starts_with('/')
            || token == "~"
            || token.starts_with("~/")
            || token.starts_with("$HOME")
            || token.starts_with("${HOME}")
    })
}

fn is_readonly_bash_segment(segment: &str) -> bool {
    if segment.is_empty() {
        return false;
    }
    let Some(command) = segment.split_whitespace().next() else {
        return false;
    };
    let command = command.trim_matches(|c: char| c == '\'' || c == '"');

    match command {
        "pwd" | "ls" | "cat" | "head" | "tail" | "wc" | "rg" | "grep" | "stat" | "file" | "du"
        | "df" | "sort" | "uniq" | "cut" | "tr" | "printf" | "echo" | "date" | "uname"
        | "whoami" => true,
        "find" => {
            let lower = segment.to_ascii_lowercase();
            !lower.contains(" -delete")
                && !lower.contains(" -exec")
                && !lower.contains(" -execdir")
                && !lower.contains(" -ok")
        }
        "sed" => {
            let lower = segment.to_ascii_lowercase();
            !lower.contains(" -i") && !lower.contains(" --in-place")
        }
        "git" => is_readonly_git_bash_segment(segment),
        _ => false,
    }
}

fn is_readonly_git_bash_segment(segment: &str) -> bool {
    let tokens: Vec<&str> = segment.split_whitespace().collect();
    if tokens.first().copied() != Some("git") {
        return false;
    }

    let mut index = 1;
    while index < tokens.len() {
        match tokens[index] {
            "--no-pager" | "-P" => index += 1,
            "-C" => index += 2,
            _ => break,
        }
    }

    let Some(subcommand) = tokens.get(index).copied() else {
        return false;
    };
    match subcommand {
        "status" | "diff" | "log" | "show" | "blame" | "grep" | "ls-files" | "rev-parse" => true,
        "remote" => match tokens.get(index + 1) {
            Some(value) => matches!(*value, "-v" | "show"),
            None => true,
        },
        "branch" => tokens[index + 1..].iter().all(|value| {
            matches!(
                *value,
                "--all" | "-a" | "--list" | "--show-current" | "--verbose" | "-v" | "-vv"
            )
        }),
        _ => false,
    }
}

fn instant_from_epoch_ms(epoch_ms: u64) -> Instant {
    let now = Instant::now();
    if epoch_ms == 0 {
        return now;
    }
    let wall_now_ms = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|duration| duration.as_millis() as u64)
        .unwrap_or(epoch_ms);
    let age_ms = wall_now_ms.saturating_sub(epoch_ms);
    now.checked_sub(Duration::from_millis(age_ms))
        .unwrap_or(now)
}

fn touch_workspace_file_path_for_manifest(
    manifest: &LocalWorkspaceManifest,
    workspace: &str,
    path: &Path,
) {
    let root = Path::new(workspace);
    if let Ok(relative) = path.strip_prefix(root) {
        if let Some(path) = relative.to_str() {
            manifest.touch_file(path);
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum RuntimeEvidenceMode {
    Any,
    ParallelReportView,
}

#[derive(Clone, Debug, PartialEq, Eq)]
struct RuntimeExpectation {
    label: String,
    policy: RuntimePolicy,
    evidence_mode: RuntimeEvidenceMode,
    runtime_tool: bool,
    parallel_work: bool,
    remote_view: bool,
    warned_missing: bool,
}

impl RuntimeExpectation {
    fn required(label: impl Into<String>) -> Self {
        Self {
            label: label.into(),
            policy: RuntimePolicy::Required,
            evidence_mode: RuntimeEvidenceMode::Any,
            runtime_tool: false,
            parallel_work: false,
            remote_view: false,
            warned_missing: false,
        }
    }

    fn required_report_view(label: impl Into<String>) -> Self {
        Self {
            evidence_mode: RuntimeEvidenceMode::ParallelReportView,
            ..Self::required(label)
        }
    }

    fn record_tool(&mut self, name: &str) {
        match name {
            "runtime" => self.runtime_tool = true,
            "dynamic_workflow" | "parallel_task" | "task" => self.parallel_work = true,
            _ => {}
        }
    }

    fn record_parallel_work(&mut self) {
        self.parallel_work = true;
    }

    fn record_remote_view(&mut self) {
        self.remote_view = true;
    }

    fn has_parallel_evidence(&self) -> bool {
        self.runtime_tool || self.parallel_work
    }

    fn is_satisfied(&self) -> bool {
        match self.evidence_mode {
            RuntimeEvidenceMode::Any => self.has_parallel_evidence() || self.remote_view,
            RuntimeEvidenceMode::ParallelReportView => {
                self.has_parallel_evidence() && self.remote_view
            }
        }
    }

    fn missing_expectation(&self) -> String {
        match self.evidence_mode {
            RuntimeEvidenceMode::Any => {
                "expected `dynamic_workflow`, `runtime`, `parallel_task`, or an OS shaped `.view`/`viewUrl` response"
                    .to_string()
            }
            RuntimeEvidenceMode::ParallelReportView => match (self.has_parallel_evidence(), self.remote_view) {
                (false, false) => {
                    "expected `dynamic_workflow`/OS Runtime/`parallel_task` fan-out plus an OS shaped `.view`/`viewUrl` report response".to_string()
                }
                (false, true) => {
                    "expected `dynamic_workflow`/OS Runtime/`parallel_task` fan-out before the report view".to_string()
                }
                (true, false) => {
                    "expected an OS shaped `.view`/`viewUrl` response for the report".to_string()
                }
                (true, true) => unreachable!("satisfied expectations are filtered before warning"),
            },
        }
    }

    fn missing_warning(&mut self) -> Option<String> {
        if self.policy != RuntimePolicy::Required || self.is_satisfied() || self.warned_missing {
            return None;
        }
        self.warned_missing = true;
        Some(format!(
            "  Runtime evidence missing for {} - {} before the final answer",
            self.label,
            self.missing_expectation()
        ))
    }

    fn corrective_prompt(&self) -> Option<String> {
        if self.policy != RuntimePolicy::Required || self.is_satisfied() {
            return None;
        }
        Some(format!(
            "The previous turn ended without the required OS Runtime evidence for {}: {}. \
             Continue the same task, explicitly use `dynamic_workflow` first; inside it use \
             the signed-in `runtime` tool or a host-side `parallel_task` step as required, \
             create or surface the shaped OS `.view`/`viewUrl` report response when required, \
             and only then give the final answer. If the OS capability is unavailable, explain exactly \
             which OS endpoint or response field is missing and provide local report artifact paths.",
            self.label,
            self.missing_expectation()
        ))
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
struct DeepResearchLoop {
    query: String,
    total_layers: usize,
    os_runtime: bool,
}

impl DeepResearchLoop {
    fn verification_prompt(&self, next_layer: usize) -> String {
        format!(
            "DeepResearch verification layer {next_layer}/{} for:\n{}\n\n\
             Check the existing answer and `.a3s/research/<slug>/index.html` report. \
             Do not restart broad research or call `dynamic_workflow` again unless a \
             critical factual gap remains. If the answer, citations, source traceability, HTML report, \
             and `{RESEARCH_VIEW_MARKER}` \
             marker are already complete, reply exactly DONE. Otherwise make only the \
             missing correction, update the report files, and finish with \
             `{RESEARCH_VIEW_MARKER} .a3s/research/<slug>/index.html`.\n\n\
             {}",
            self.total_layers,
            self.query,
            deep_research_duplicate_tool_guard()
        )
    }
}

fn deep_research_report_repair_prompt_from_state(
    loop_state: Option<&DeepResearchLoop>,
    workflow_output: &str,
    workflow_metadata: Option<&serde_json::Value>,
    review_text: &str,
) -> Option<String> {
    let loop_state = loop_state?;
    Some(deep_research_repair_prompt(
        &loop_state.query,
        loop_state.os_runtime,
        workflow_output,
        workflow_metadata,
        review_text,
    ))
}

#[derive(Clone, Debug, PartialEq, Eq)]
struct WorkflowSubagentBackfill {
    task_id: String,
    agent: String,
    description: String,
    success: bool,
}

fn workflow_parallel_subagent_backfills(
    metadata: &serde_json::Value,
) -> Vec<WorkflowSubagentBackfill> {
    let Some(steps) = metadata
        .pointer("/dynamic_workflow/snapshot/steps")
        .and_then(serde_json::Value::as_object)
    else {
        return Vec::new();
    };

    let mut backfills = Vec::new();
    for step in steps.values() {
        if step.get("step_name").and_then(serde_json::Value::as_str) != Some("parallel_task") {
            continue;
        }
        let descriptions = step
            .pointer("/input/tasks")
            .and_then(serde_json::Value::as_array)
            .map(|tasks| {
                tasks
                    .iter()
                    .map(|task| {
                        task.get("description")
                            .and_then(serde_json::Value::as_str)
                            .unwrap_or("")
                            .to_string()
                    })
                    .collect::<Vec<_>>()
            })
            .unwrap_or_default();
        let Some(results) = step
            .pointer("/output/metadata/results")
            .and_then(serde_json::Value::as_array)
        else {
            continue;
        };
        for (index, result) in results.iter().enumerate() {
            let Some(task_id) = result.get("task_id").and_then(serde_json::Value::as_str) else {
                continue;
            };
            let agent = result
                .get("agent")
                .and_then(serde_json::Value::as_str)
                .unwrap_or("general")
                .to_string();
            let success = result
                .get("success")
                .and_then(serde_json::Value::as_bool)
                .unwrap_or(false);
            backfills.push(WorkflowSubagentBackfill {
                task_id: task_id.to_string(),
                agent,
                description: descriptions.get(index).cloned().unwrap_or_default(),
                success,
            });
        }
    }
    backfills
}

fn is_new_remote_view(last_view: Option<&remote_ui::ViewSpec>, spec: &remote_ui::ViewSpec) -> bool {
    last_view != Some(spec)
}

fn take_pending_tool_label(
    pending_tool: &mut Option<(String, String)>,
    tool_id: &str,
) -> Option<String> {
    if pending_tool
        .as_ref()
        .is_some_and(|(pending_id, _)| pending_id == tool_id)
    {
        pending_tool.take().map(|(_, label)| label)
    } else {
        None
    }
}

struct App {
    session: Arc<AgentSession>,
    /// Agent + session-rebuild bits, kept so `/model` can switch models by
    /// resuming the session under a new model (no in-place model setter exists).
    agent: Arc<Agent>,
    store: Arc<dyn a3s_code_core::store::SessionStore>,
    confirmation: a3s_code_core::hitl::ConfirmationPolicy,
    deep_research_report_tool_gate: DeepResearchReportToolGate,
    /// This session's id (for model-switch resume + the exit hint).
    session_id: String,
    /// "provider/model" ids from the config, for the /model picker.
    models: Vec<String>,
    /// Context-window size per model id, for the ctx% indicator.
    model_ctx: std::collections::HashMap<String, u32>,
    /// Context window of the active model (0 = unknown).
    context_limit: u32,
    /// Prompt tokens of the last turn = current context fill.
    last_prompt_tokens: usize,
    /// Highest context-fill tier already warned about (0 / 70 / 85), so each
    /// warning prints once per fill-up and re-arms when usage drops back.
    ctx_warned_tier: u8,
    /// Selected index in the /model panel; `Some` means the panel is open.
    model_menu: Option<usize>,
    /// Active tab in the /model panel (0 = config; account tabs when signed in).
    model_tab: usize,
    /// Custom LLM client to inject for signed-in account tabs; None uses config.acl.
    llm_override: Option<Arc<dyn a3s_code_core::llm::LlmClient>>,
    /// Optional OS endpoint from config.acl; enables /login and /logout.
    os_config: Option<OsConfig>,
    /// Restored OS login (from `~/.a3s/os-auth.json`, persisted across runs);
    /// `None` = signed out. Loaded on startup, set by /login, cleared by /logout.
    os_session: Option<crate::a3s_os::StoredOsSession>,
    /// True while an OS access-token refresh is in flight (guards the BannerTick
    /// trigger from spawning a second refresh before the first resolves).
    os_refreshing: bool,
    /// OS unified-gateway models for the `/model` picker, lazily fetched when
    /// the signed-in user opens the OS Gateway tab. `None` = not fetched yet or
    /// currently loading; `Some([])` = the gateway is unavailable/unconfigured.
    os_gateway_models: Option<Vec<String>>,
    /// True while the OS Gateway tab is fetching its model list. Guards against
    /// spawning duplicate slow requests while the user switches tabs repeatedly.
    os_gateway_models_loading: bool,
    /// The precise reason the last gateway-models fetch failed (e.g. `/v1` not
    /// proxied → HTML, auth error, unreachable), shown in the `/model` picker.
    os_gateway_error: Option<String>,
    /// Last OS view seen in a tool result. Generic tool views are opened by
    /// clicking the inline "Open view" button; owned workflows like `/flow` may
    /// also open their prepared designer view directly.
    last_view: Option<remote_ui::ViewSpec>,
    /// Completed DeepResearch report view captured before all verification
    /// layers have drained. It opens only when DeepResearch actually finishes.
    pending_deep_research_report_view: Option<remote_ui::ViewSpec>,
    /// Bounded DeepResearch verification state; turns generic loop continuation
    /// into report-focused gap checks instead of another broad planning round.
    deep_research_loop: Option<DeepResearchLoop>,
    /// One extra repair pass is allowed when synthesis misses the required local
    /// report marker/artifact, including "single synthesis pass" research.
    deep_research_report_repair_used: bool,
    /// Last host DynamicWorkflowRuntime output for the active DeepResearch run.
    /// Used only if report synthesis needs a host-materialized fallback.
    deep_research_workflow_output: Option<String>,
    /// Last DynamicWorkflowRuntime metadata for the active DeepResearch run.
    /// Kept so a missing-report repair prompt can be self-contained.
    deep_research_workflow_metadata: Option<serde_json::Value>,
    /// True after the active DeepResearch run has emitted a valid completed
    /// report marker and the host has verified its `index.html` + `report.md`.
    deep_research_report_ready: bool,
    /// One-shot prompt generated when the active DeepResearch synthesis missed
    /// its report artifacts. It has priority over generic verification loops.
    pending_deep_research_report_repair_prompt: Option<String>,
    /// Monotonic guard for DeepResearch stream watchdogs; stale timeout ticks
    /// must not affect later turns.
    deep_research_stream_timeout_token: u64,
    /// Required Runtime use for the current autonomous workflow, plus observed
    /// evidence from tool/subagent/view events.
    runtime_expectation: Option<RuntimeExpectation>,
    /// Current model effort (index into EFFORT_LEVELS).
    effort: usize,
    /// `/effort` slider panel: temp selection while open.
    effort_panel: Option<usize>,
    /// `/theme` picker: temp theme index while open.
    theme_panel: Option<usize>,
    /// First Ctrl+C arms quit; a second within the window exits.
    quit_armed: Option<Instant>,
    /// Last user activity; drives the inactivity auto-review.
    last_activity: Instant,
    /// True once the idle conversation has been auto-reviewed (until next input).
    auto_reviewed: bool,
    /// Shell mode: a leading `!` becomes the prompt, the rest is the command.
    shell_mode: bool,
    /// Deep-research mode: a leading `?` turns the input into a deep-research
    /// query — sent to the agent with a multi-source research directive. Box
    /// turns cyan.
    research_mode: bool,
    /// True from an asset-scoped review submit until its report is parsed (or
    /// the run is interrupted/fails). Gates capture_review so a turn that merely
    /// QUOTES an a3s-review block can't open a phantom checklist.
    review_pending: bool,
    /// True from a `/sleep` submit until its report is parsed (or the run is
    /// interrupted/fails). Gates capture_sleep the same way.
    sleep_pending: bool,
    /// Last parsed asset-review report (issues + checkbox state). Survives the
    /// panel closing so a follow-up asset review can reopen it.
    review: Option<panels::review::ReviewState>,
    /// `/flow` DAG picker (login-gated); open when `Some`.
    flow: Option<panels::flow::FlowPanel>,
    /// A `/flow <action>` submitted before a flow was selected; run after selection.
    pending_flow_subcommand: Option<panels::flow::FlowSubcommand>,
    /// `/agent` definition picker; open when `Some`.
    agent_picker: Option<panels::agent::AgentPanel>,
    /// A `/agent <action>` submitted before an agent was active; run after selection.
    pending_agent_subcommand: Option<panels::agent::AgentSubcommand>,
    /// The local agent currently being developed by ordinary user turns.
    agent_dev: Option<panels::agent::AgentDevSession>,
    /// `/mcp` asset selector; open when `Some`.
    mcp_picker: Option<panels::mcp::McpPanel>,
    /// A `/mcp <action>` submitted before an MCP was active; run after selection.
    pending_mcp_subcommand: Option<panels::mcp::McpSubcommand>,
    /// The local MCP asset currently being developed by ordinary user turns.
    mcp_dev: Option<panels::mcp::McpDevSession>,
    /// `/skill` picker; open when `Some`.
    skill_picker: Option<panels::skill::SkillPanel>,
    /// A `/skill <action>` submitted before a skill was active; run after selection.
    pending_skill_subcommand: Option<panels::skill::SkillSubcommand>,
    /// The local skill currently being developed by ordinary user turns.
    skill_dev: Option<panels::skill::SkillDevSession>,
    /// `/okf` OKF package picker; open when `Some`.
    okf_picker: Option<panels::okf::OkfPackagePanel>,
    /// A `/okf <action>` submitted before an OKF package was active; run after selection.
    pending_okf_subcommand: Option<panels::okf::OkfCommand>,
    /// The local OKF package currently being developed by ordinary user turns.
    okf_dev: Option<panels::okf::OkfDevSession>,
    /// Whether the review issue-checklist overlay is showing.
    review_open: bool,
    /// `ctx` CLI detected at startup (past-session history search).
    ctx_ready: bool,
    /// Last `/ctx` search hits, addressable as `/ctx <n>`.
    ctx_hits: Vec<panels::ctx::CtxHit>,
    /// A transcript window staged by `/ctx <n>`, attached (one-shot) to the
    /// next outgoing message.
    pending_ctx: Option<String>,
    /// True for the single `Msg::Submit` the `/loop` mechanism emits to
    /// auto-continue — so on_submit doesn't attach a staged `/ctx` window to
    /// this machine turn.
    loop_continuation: bool,
    /// ALL assistant text of the current turn (across mid-turn tool-call
    /// finalizes, which clear the live streaming buffer). capture_review scans
    /// this when a provider leaves `End.text` empty.
    turn_text: String,
    /// Active transcript text-selection (mouse drag → highlight → copy on
    /// release); `None` when there's no selection.
    selection: Option<Selection>,
    /// Latest dynamic-workflow artifact (ultracode dynamic workflow or task dispatch),
    /// retained for synthesis and shown collapsed in the transcript.
    last_workflow: Option<String>,
    /// Clipboard images pasted (Ctrl+V), sent with the next message.
    pending_images: Vec<a3s_code_core::llm::Attachment>,
    /// Persistent north-star goal (`/goal`), prepended to each prompt.
    goal: Option<String>,
    /// When the current `/goal` was set — drives the "Pursuing goal (1h 32m)"
    /// elapsed timer in the status bar. `None` whenever `goal` is `None`.
    goal_since: Option<Instant>,
    /// Remaining auto-continue turns for `/loop` (0 = off).
    loop_remaining: usize,
    /// ECS-style projection of live runtime entities (tools/subagents) plus
    /// completed tool-call records used by `/output`.
    runtime: RuntimeProjection,
    /// True once this turn used tools/planning/subagents that need a final
    /// user-facing synthesis if the model stops without text afterwards.
    turn_had_agent_activity: bool,
    /// True once assistant text arrived after the latest tool/planning/subagent
    /// activity in this turn.
    turn_text_after_activity: bool,
    /// Guard for the hidden ultracode continuation that turns raw workflow
    /// results into a final answer.
    ultracode_synthesis_inflight: bool,
    /// At most one hidden synthesis continuation per user turn.
    ultracode_synthesis_used: bool,
    /// Project instructions (CLAUDE.md/AGENT.md), injected into the system prompt.
    instructions: Option<String>,
    /// Summary of earlier conversation after a manual `/compact` (reseed).
    compact_summary: Option<String>,
    /// Shared in-memory workspace file manifest, refreshed by a background watcher.
    workspace_manifest: Arc<LocalWorkspaceManifest>,
    workspace_manifest_rx: SharedManifestRx,
    /// Manifest-backed workspace backend used by agent tools.
    workspace_services: Arc<WorkspaceServices>,
    /// Brief brand-gradient flourish on the input border when ultracode is picked.
    gradient_until: Option<Instant>,
    gradient_frame: usize,
    /// Ultracode confirm animation playing in the /effort panel before it closes.
    effort_anim: Option<Instant>,
    /// Active `/btw` side-chat shown as a panel: (question, answer-once-ready).
    btw: Option<(String, Option<String>)>,
    viewport: Viewport,
    textarea: Textarea,
    spinner: Spinner,
    streaming: StreamingMarkdown,
    deferred_tool_blocks: Vec<String>,
    defer_tool_blocks_until_stream_finalized: bool,
    /// Whether the current turn streamed any text deltas (vs. text only at End).
    got_delta: bool,
    /// Set while `/compact` is summarizing — drives the progress bar + blocks input.
    compacting: Option<Instant>,
    /// Set while `/update` is upgrading — drives a progress bar + blocks input;
    /// on success the app restarts into the new binary.
    updating: Option<Instant>,
    /// Last time the streaming viewport was rebuilt — throttles the O(n) rebuild
    /// to ~30fps so a flood of deltas doesn't starve animation on the 1 loop.
    last_paint: Option<Instant>,
    /// Live reasoning ("thinking") text for the current turn, shown dimmed above
    /// the answer and cleared when the answer is finalized.
    thinking: String,
    state: State,
    messages: Vec<String>,
    rx: Option<SharedRx>,
    stream_join: Option<StreamJoin>,
    /// Abort handle for host-direct tools such as the DeepResearch workflow.
    host_tool_abort: Option<HostToolAbort>,
    /// True while `rx` is carrying host-direct tool progress rather than an
    /// agent stream; channel close must not finish the turn.
    host_progress_inflight: bool,
    interrupting: bool,
    pending_tool: Option<(String, String)>,
    /// Selected row in the tool-approval options panel (0 yes · 1 always · 2 no).
    approval_sel: usize,
    /// Submitted prompts, oldest first, for ↑/↓ recall.
    history: Vec<String>,
    /// Cursor into `history` while browsing; `None` means "fresh input".
    history_pos: Option<usize>,
    /// Model name reported by the provider (captured from the first turn).
    model: Option<String>,
    /// Cumulative OUTPUT (generated) tokens this session — what `↓` reports.
    output_tokens: usize,
    /// When the current run started, for the live elapsed-time indicator.
    stream_started: Option<Instant>,
    /// Animation counter for the blinking running-tool dot (advances per tick).
    blink_tick: u8,
    /// Frame counter for the welcome-mascot animation.
    anim: u8,
    /// Run mode (Shift+Tab cycles default → plan → auto).
    mode: Mode,
    /// The mode to restore once an autonomous directive run finishes —
    /// `Some` while such a run auto-switched to `Mode::Auto`.
    autonomy_restore: Option<Mode>,
    /// User messages submitted while the agent is busy, run when it frees up.
    queue: BinaryHeap<Queued>,
    /// Monotonic counter for FIFO ordering within a queue priority.
    seq: u64,
    /// Text of the message currently being processed (the running task).
    running_task: Option<String>,
    /// Live plan/TODO from planning mode: (task text, status glyph, colour),
    /// pinned above the input. Updated from PlanningEnd/TaskUpdated events.
    plan: Vec<(String, String, char, Color)>, // (id, content, glyph, colour)
    /// `/top` process panel: `Some(rows)` when open; `top_scroll` is the scroll
    /// offset and `top_sel` the highlighted (absolute) row index.
    top: Option<Vec<ProcessRow>>,
    top_history: TopProcessHistory,
    top_scroll: usize,
    top_sel: usize,
    /// `/top` agent drill-down: `Some(pid)` focuses one coding agent's process
    /// subtree (the agent root + its descendants). `None` shows all processes.
    top_focus: Option<u32>,
    /// `/ide` file-tree + viewer panel (Some when open).
    ide: Option<Ide>,
    /// `/memory` full-screen timeline panel (Some when open).
    memory: Option<MemPanel>,
    /// Asset-scoped OS digital-asset browser.
    asset_list: Option<panels::asset_resources::AssetListPanel>,
    /// Asset-scoped OS Runtime activity panel.
    runtime_activity: Option<panels::asset_resources::RuntimeActivityPanel>,
    /// `/kb` full-screen local personal knowledge-base panel (Some when open).
    kb: Option<panels::kb::KbPanel>,
    /// `/loop` engineered loop dashboard (Some when open).
    loop_panel: Option<panels::loop_engineering::LoopPanel>,
    /// `/help` overlay panel is showing.
    help_open: bool,
    /// Scroll offset inside the `/help` overlay.
    help_scroll: usize,
    /// Turns completed this session, for the status-bar task counter.
    completed: usize,
    /// Working directory shown for context.
    cwd: String,
    /// Git branch of the workspace (if any), shown in the bottom status bar.
    branch: Option<String>,
    /// Selected index in the `/` command menu.
    slash_sel: usize,
    /// Workspace files (for the `@` file picker) + its selected index.
    files: Vec<String>,
    file_sel: usize,
    /// Expanded directories in the `@` picker tree (collapsed by default).
    at_expanded: std::collections::HashSet<String>,
    /// Count of discoverable Claude skills (incl. plugin-bundled) for the banner.
    skill_count: usize,
    /// Loaded skills (name, description) for the slash menu + `/plugin`.
    skills: Vec<(String, String)>,
    /// Skill names the user disabled via `/plugin` (persisted, hidden from `/`).
    disabled_skills: std::collections::HashSet<String>,
    /// `/plugin` panel: selected row while open.
    plugins_panel: Option<usize>,
    /// Newer release found at startup (latest version), if any.
    update_available: Option<String>,
    width: u16,
    height: u16,
    keymap: Keymap<Action>,
}

impl App {
    pub(crate) fn touch_workspace_file(&self, path: &str) {
        self.workspace_manifest.touch_file(path);
    }

    pub(crate) fn viewport_content_width(&self) -> usize {
        viewport_content_width_for(self.width)
    }

    fn transcript_markdown_width(&self) -> usize {
        transcript_markdown_width_for(self.width)
    }
}

impl Model for App {
    type Msg = Msg;

    fn init(&mut self) -> Option<Cmd<Msg>> {
        // Auto-check for a newer release on every launch (non-blocking).
        let mut cmds = vec![cmd::cmd(|| async {
            Msg::UpdateCheck(check_latest_version().await)
        })];
        cmds.push(pump_manifest(self.workspace_manifest_rx.clone()));
        // Heartbeat for EVERY session (fresh or resumed) — the BannerTick handler
        // self-gates the mascot animation, but it's also the sole driver of the
        // ultracode /effort confirm→apply and the idle auto-review. Resumed
        // sessions used to start no heartbeat, so neither ever fired.
        cmds.push(banner_tick());
        if self.messages.is_empty() {
            self.viewport.set_content(&self.banner());
        } else {
            // Resumed session — show the prior conversation, scrolled to the end.
            self.rebuild_viewport();
            self.viewport.update(ViewportMsg::Bottom);
        }
        Some(cmd::batch(cmds))
    }

    fn update(&mut self, msg: Msg) -> Option<Cmd<Msg>> {
        match msg {
            Msg::Term(Event::Resize { width, height }) => {
                self.selection = None; // screen-coord selection is stale after resize
                self.width = width;
                self.height = height;
                self.relayout();
                self.textarea
                    .set_width(width.saturating_sub((PAD + 2) as u16));
                // An open /ide image buffer is rasterized at open-time width —
                // re-render it for the new panel size or its rows overflow the
                // frame (styled rows can't be re-truncated).
                if let Some(f) = self
                    .ide
                    .as_mut()
                    .and_then(|i| i.file.as_mut())
                    .filter(|f| f.image)
                {
                    let inner = panels::spf::ide_split(width as usize).1.saturating_sub(2);
                    let body = (height as usize).saturating_sub(5);
                    f.lines = render_image_file(&f.path, inner, body)
                        .unwrap_or_else(|| vec!["<cannot decode image>".into()]);
                    f.scroll = 0;
                }
                // Re-wrap the live answer at the new width instead of discarding it
                // (the old reset lost any text streamed before the resize).
                let raw = self.streaming.raw_content().to_string();
                self.streaming = StreamingMarkdown::new(self.transcript_markdown_width());
                if !raw.is_empty() {
                    self.streaming.push(&raw);
                }
                self.rebuild_viewport();
            }

            // Bracketed paste: drop the whole pasted block into the input as
            // one edit (newlines become real line breaks) instead of N submitted
            // lines / a3s-lane queue spam — Claude-Code-style paste DX.
            Msg::Term(Event::Paste(text)) => {
                self.last_activity = Instant::now();
                if self.ide.is_some() {
                    self.ide_paste_text(&text);
                    return None;
                }
                self.textarea.insert_str(&text);
                self.relayout();
            }

            Msg::Term(Event::Key(key)) => {
                self.last_activity = Instant::now();
                self.auto_reviewed = false;
                // Any keypress dismisses the copy highlight.
                self.selection = None;
                // Ctrl+C is a global quit key. Keep it before panels, approval
                // prompts, and streaming handlers so terminal variants cannot
                // route it into hidden input instead of exiting.
                if is_quit_key(&key) {
                    let now = Instant::now();
                    if quit_is_confirmed(self.quit_armed, now) {
                        return Some(cmd::quit());
                    }
                    self.quit_armed = Some(now);
                    self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  press Ctrl+C again to exit"),
                    );
                    return None;
                }
                // Esc closes the /btw side-chat panel.
                if self.btw.is_some() && key.code == KeyCode::Esc {
                    self.btw = None;
                    return None;
                }
                // The /help overlay owns its own close + scroll keys.
                if self.help_open {
                    return self.handle_help_key(&key);
                }
                // /memory panel takes all keys while open.
                if self.memory.is_some() {
                    return self.memory_key(&key);
                }
                // Asset resource panels take all keys while open.
                if self.asset_list.is_some() {
                    return self.handle_asset_list_key(&key);
                }
                if self.runtime_activity.is_some() {
                    return self.handle_runtime_activity_key(&key);
                }
                // /kb panel takes all keys while open; an approval prompt
                // still overlays it and must get the keys first.
                if self.kb.is_some() {
                    if self.state == State::Awaiting {
                        return self.handle_approval_key(&key);
                    }
                    return self.handle_kb_key(&key);
                }
                // /ide panel takes all keys while open — except while a tool
                // approval is pending: the prompt is overlaid on the page and
                // must get the keys, or the turn stalls invisibly.
                if self.ide.is_some() {
                    if self.state == State::Awaiting {
                        return self.handle_approval_key(&key);
                    }
                    self.ide_key(&key);
                    return None;
                }
                // /top panel takes keys while open.
                if self.top.is_some() {
                    let rows = self.top_rows();
                    let last = rows.len().saturating_sub(1);
                    match key.code {
                        // Esc backs out of an agent focus first, then closes.
                        KeyCode::Esc => {
                            if self.top_focus.is_some() {
                                self.top_focus = None;
                                self.top_sel = 0;
                                self.top_scroll = 0;
                            } else {
                                self.top = None;
                                self.top_history.clear();
                            }
                        }
                        KeyCode::Up | KeyCode::Char('k') => {
                            self.top_sel = self.top_sel.saturating_sub(1)
                        }
                        KeyCode::Down | KeyCode::Char('j') => {
                            self.top_sel = (self.top_sel + 1).min(last)
                        }
                        KeyCode::PageUp => self.top_sel = self.top_sel.saturating_sub(10),
                        KeyCode::PageDown => self.top_sel = (self.top_sel + 10).min(last),
                        // Enter / → drills into the selected coding agent's
                        // process subtree (its child processes).
                        KeyCode::Enter | KeyCode::Right if self.top_focus.is_none() => {
                            if let Some(row) = rows.get(self.top_sel) {
                                if row.agent.is_some() {
                                    self.top_focus = Some(row.pid);
                                    self.top_sel = 0;
                                    self.top_scroll = 0;
                                }
                            }
                        }
                        _ => {}
                    }
                    // Keep the selection within the visible window.
                    let body = (self.height as usize).saturating_sub(3);
                    if self.top_sel < self.top_scroll {
                        self.top_scroll = self.top_sel;
                    } else if self.top_sel >= self.top_scroll + body {
                        self.top_scroll = self.top_sel + 1 - body;
                    }
                    return None;
                }
                // Shift+Tab cycles run mode in any state.
                if key.code == KeyCode::BackTab {
                    self.mode = self.mode.next();
                    return None;
                }
                if self.state == State::Awaiting {
                    return self.handle_approval_key(&key);
                }
                // /model picker takes keys while open — consume EVERY key so
                // nothing leaks to the hidden input box behind the overlay.
                if self.model_menu.is_some() {
                    return self.handle_model_key(&key).unwrap_or(None);
                }
                // /effort slider takes keys while open.
                if let Some(sel) = self.effort_panel {
                    match key.code {
                        KeyCode::Left => self.effort_panel = Some(sel.saturating_sub(1)),
                        KeyCode::Right => {
                            self.effort_panel = Some((sel + 1).min(EFFORT_LEVELS.len() - 1))
                        }
                        KeyCode::Enter => {
                            self.confirm_effort_selection(sel);
                        }
                        KeyCode::Esc => {
                            self.effort_panel = None;
                            self.effort_anim = None;
                        }
                        _ => {}
                    }
                    return None;
                }
                // /theme picker: ↑/↓ preview, Enter apply, Esc cancel.
                if let Some(sel) = self.theme_panel {
                    match key.code {
                        KeyCode::Up => self.theme_panel = Some(sel.saturating_sub(1)),
                        KeyCode::Down => self.theme_panel = Some((sel + 1).min(THEMES.len() - 1)),
                        KeyCode::Enter => self.apply_theme_selection(sel),
                        KeyCode::Esc => self.theme_panel = None,
                        _ => {}
                    }
                    return None;
                }
                // /plugin panel: ↑/↓ select, Space enable/disable, Esc close.
                if let Some(sel) = self.plugins_panel {
                    let last = self.skills.len().saturating_sub(1);
                    match key.code {
                        KeyCode::Up => self.plugins_panel = Some(sel.saturating_sub(1)),
                        KeyCode::Down => self.plugins_panel = Some((sel + 1).min(last)),
                        KeyCode::Char(' ') => {
                            self.toggle_plugin_skill(sel.min(last));
                        }
                        KeyCode::Esc => self.plugins_panel = None,
                        _ => {}
                    }
                    return None;
                }
                // Asset review issue checklist: consume EVERY key while open.
                if self.review_open {
                    return self.handle_review_key(&key);
                }
                // `/flow` DAG picker: same.
                if self.flow.is_some() {
                    return self.handle_flow_key(&key);
                }
                // `/agent` definition picker: same.
                if self.agent_picker.is_some() {
                    return self.handle_agent_key(&key);
                }
                // `/mcp` asset selector: same.
                if self.mcp_picker.is_some() {
                    return self.handle_mcp_key(&key);
                }
                if self.skill_picker.is_some() {
                    return self.handle_skill_key(&key);
                }
                if self.okf_picker.is_some() {
                    return self.handle_okf_package_key(&key);
                }
                // `/loop` engineered-loop dashboard: same.
                if self.loop_panel.is_some() {
                    return self.handle_loop_key(&key);
                }
                // Shift+End jumps to the latest output and resumes auto-follow.
                if key.code == KeyCode::End && key.modifiers.contains(KeyModifiers::SHIFT) {
                    self.viewport.update(ViewportMsg::Bottom);
                    self.viewport.set_auto_scroll(true);
                    return None;
                }
                if let Some(action) = self.keymap.resolve(&key) {
                    let m = match action {
                        Action::ScrollUp => ViewportMsg::PageUp,
                        Action::ScrollDown => ViewportMsg::PageDown,
                        Action::ScrollTop => ViewportMsg::Top,
                        Action::ScrollBottom => ViewportMsg::Bottom,
                    };
                    self.viewport.update(m);
                    // Pause auto-follow while scrolled up; resume once back at the
                    // bottom — so streaming output doesn't yank the view down.
                    self.viewport.set_auto_scroll(self.viewport.at_bottom());
                    return None;
                }
                // Esc leaves shell/research mode first (discarding the
                // partial input), taking priority over the streaming interrupt
                // below.
                if (self.shell_mode || self.research_mode) && key.code == KeyCode::Esc {
                    self.shell_mode = false;
                    self.research_mode = false;
                    self.textarea.clear();
                    return None;
                }
                // Esc interrupts the in-progress run (input stays usable otherwise).
                if self.state == State::Streaming && key.code == KeyCode::Esc {
                    if self.interrupting {
                        return None;
                    }
                    self.interrupting = true;
                    self.push_line(&Style::new().fg(TN_YELLOW).render("  ⎋ interrupting…"));
                    let session = self.session.clone();
                    let join = self.stream_join.take();
                    let host_abort = self.host_tool_abort.take();
                    return Some(cmd::cmd(move || async move {
                        if let Some(host_abort) = host_abort {
                            host_abort.abort();
                        }
                        session.cancel().await;
                        if let Some(join) = join {
                            let _ = join.await;
                        }
                        Msg::Interrupted
                    }));
                }
                if self.state == State::Idle && self.agent_dev.is_some() && key.code == KeyCode::Esc
                {
                    self.exit_agent_dev();
                    return None;
                }
                if self.state == State::Idle && self.mcp_dev.is_some() && key.code == KeyCode::Esc {
                    self.exit_mcp_dev();
                    return None;
                }
                if self.state == State::Idle && self.skill_dev.is_some() && key.code == KeyCode::Esc
                {
                    self.exit_skill_dev();
                    return None;
                }
                if self.state == State::Idle && self.okf_dev.is_some() && key.code == KeyCode::Esc {
                    self.exit_okf_dev();
                    return None;
                }
                // Slash-command menu: ↑/↓ select, Enter run, Tab complete, Esc
                // dismiss — takes priority over history recall while open.
                if self.slash_menu_open() {
                    if let Some(result) = self.handle_slash_key(&key) {
                        return result;
                    }
                }
                // `@` file picker takes nav keys while open.
                if self.file_menu_open() {
                    if let Some(result) = self.handle_file_key(&key) {
                        return result;
                    }
                }
                // ↑/↓ recall prompt history (single-line input only, so multi-line
                // editing keeps normal cursor movement).
                if matches!(key.code, KeyCode::Up | KeyCode::Down)
                    && !self.textarea.value().contains('\n')
                    && !self.history.is_empty()
                {
                    self.history_recall(key.code == KeyCode::Up);
                    return None;
                }
                // Ctrl+V pastes a clipboard image (macOS Cmd+V is swallowed by the
                // terminal, so the app can't see it) to attach to the next message.
                if key.code == KeyCode::Char('v') && key.modifiers.contains(KeyModifiers::CONTROL) {
                    self.paste_clipboard_image();
                    return None;
                }
                // Input is always live (you can keep typing while the agent works);
                // a submit while busy is queued and run when the current turn ends.
                if let Some(TextareaMsg::Submit(text)) = self.textarea.handle_key(&key) {
                    return Some(cmd::msg(Msg::Submit(text)));
                }
                // A leading `!` enters shell mode and a leading `?` enters
                // deep-research mode. Each stays on until Esc or submit.
                let val = self.textarea.value();
                if !self.shell_mode && !self.research_mode {
                    if let Some(rest) = val.strip_prefix('!') {
                        self.shell_mode = true;
                        self.textarea.set_value(rest);
                    } else if let Some(rest) = val.strip_prefix('?') {
                        self.research_mode = true;
                        self.textarea.set_value(rest);
                    }
                }
            }

            Msg::Term(Event::Mouse(m)) => {
                use a3s_tui::event::{MouseButton, MouseEventKind};
                if self.state == State::Awaiting {
                    return self.handle_approval_mouse(&m);
                }
                if self.model_menu.is_some() {
                    return self.handle_model_mouse(&m);
                }
                if self.effort_panel.is_some() {
                    self.handle_effort_mouse(&m);
                    return None;
                }
                if self.theme_panel.is_some() {
                    self.handle_theme_mouse(&m);
                    return None;
                }
                if self.file_menu_open() {
                    self.handle_file_mouse(&m);
                    return None;
                }
                if self.plugins_panel.is_some() {
                    self.handle_plugins_mouse(&m);
                    return None;
                }
                if self.slash_menu_open() {
                    return self.handle_slash_mouse(&m);
                }
                if self.flow.is_some() {
                    return self.handle_flow_mouse(&m);
                }
                if self.agent_picker.is_some() {
                    return self.handle_agent_mouse(&m);
                }
                if self.mcp_picker.is_some() {
                    return self.handle_mcp_mouse(&m);
                }
                if self.skill_picker.is_some() {
                    return self.handle_skill_mouse(&m);
                }
                if self.okf_picker.is_some() {
                    return self.handle_okf_package_mouse(&m);
                }
                if self.top.is_some() {
                    return self.handle_top_mouse(&m);
                }
                if self.help_open {
                    match m.kind {
                        MouseEventKind::ScrollUp => self.scroll_help_by(-3),
                        MouseEventKind::ScrollDown => self.scroll_help_by(3),
                        _ => {}
                    }
                    return None;
                }
                // Full-screen /ide //config //kb page: the transcript isn't
                // visible, so transcript scroll/select must not act on it
                // (a drag would silently copy hidden text).
                if self.ide.is_some()
                    || self.kb.is_some()
                    || self.asset_list.is_some()
                    || self.runtime_activity.is_some()
                {
                    return None;
                }
                let vp_rows = self.viewport_rows();
                // Content columns exclude the rightmost scrollbar column.
                let max_col = (self.width as usize).saturating_sub(2) as u16;
                match m.kind {
                    MouseEventKind::ScrollUp => {
                        self.selection = None;
                        self.viewport.update(ViewportMsg::ScrollUp(3));
                    }
                    MouseEventKind::ScrollDown => {
                        self.selection = None;
                        self.viewport.update(ViewportMsg::ScrollDown(3));
                    }
                    // Drag to select transcript text. Capture stays on so the wheel
                    // still scrolls; the app owns selection, so scroll + copy work
                    // together (no mode toggle). Release copies to the clipboard.
                    MouseEventKind::Down(MouseButton::Left) => {
                        self.selection = viewport_mouse_cell(m.row, m.column, vp_rows, max_col)
                            .map(|p| Selection { anchor: p, head: p });
                    }
                    MouseEventKind::Drag(MouseButton::Left) => {
                        if let Some(s) = self.selection.as_mut() {
                            if let Some(p) =
                                viewport_mouse_cell_clamped(m.row, m.column, vp_rows, max_col)
                            {
                                s.head = p;
                            }
                        }
                    }
                    MouseEventKind::Up(MouseButton::Left) => {
                        if let Some(mut s) = self.selection {
                            if let Some(p) =
                                viewport_mouse_cell_clamped(m.row, m.column, vp_rows, max_col)
                            {
                                s.head = p;
                            }
                            let view = self.viewport.view();
                            if is_remote_view_click(&view, s) {
                                self.selection = None;
                                if let Some(spec) = self.last_view.clone() {
                                    self.open_remote_view(&spec);
                                } else {
                                    self.push_line(&Style::new().fg(TN_GRAY).render(
                                        "  no OS view is available for this Open view marker yet",
                                    ));
                                }
                            } else if s.is_empty() {
                                self.selection = None;
                            } else {
                                let (r1, c1, r2, c2) = s.ordered();
                                let text = selection_to_text(&view, r1, c1, r2, c2);
                                if text.trim().is_empty() {
                                    self.selection = None;
                                } else {
                                    // Keep the highlight visible as "copied" feedback.
                                    copy_to_clipboard(&text);
                                }
                            }
                        }
                    }
                    _ => {}
                }
                // Pause auto-follow while scrolled up (so streaming output won't
                // yank the view down); resume once back at the bottom.
                self.viewport.set_auto_scroll(self.viewport.at_bottom());
            }

            Msg::Submit(text) => return self.on_submit(text),

            Msg::StreamStarted(rx, join) => {
                self.rx = Some(rx.clone());
                self.stream_join = Some(join);
                self.host_tool_abort = None;
                self.host_progress_inflight = false;
                self.interrupting = false;
                let mut commands = vec![pump(rx)];
                if self.deep_research_loop.is_some() {
                    self.deep_research_stream_timeout_token =
                        self.deep_research_stream_timeout_token.wrapping_add(1);
                    let token = self.deep_research_stream_timeout_token;
                    let timeout_ms = if self.deep_research_report_repair_used {
                        DEEP_RESEARCH_REPAIR_TIMEOUT_MS
                    } else {
                        DEEP_RESEARCH_SYNTHESIS_TIMEOUT_MS
                    };
                    commands.push(cmd::cmd(move || async move {
                        tokio::time::sleep(Duration::from_millis(timeout_ms)).await;
                        Msg::DeepResearchSynthesisTimedOut { token }
                    }));
                }
                return Some(cmd::batch(commands));
            }

            Msg::StreamError(e) => {
                self.push_line(&Style::new().fg(TN_RED).render(&format!("  error: {e}")));
                self.loop_remaining = 0; // a failed turn stops the /loop
                self.review_pending = false; // a turn that never started can't
                self.sleep_pending = false; // deliver a review/sleep report
                self.restore_autonomy();
                self.finish();
                // Don't strand messages queued while this turn was starting.
                return self.drain_queue();
            }

            Msg::WorkspaceManifest(snapshot) => {
                self.files = snapshot.file_paths();
                self.file_sel = self.file_sel.min(self.files.len().saturating_sub(1));
                return Some(pump_manifest(self.workspace_manifest_rx.clone()));
            }

            Msg::WorkspaceManifestStopped => {
                let snapshot = self.workspace_manifest.snapshot();
                self.files = snapshot.file_paths();
                self.file_sel = self.file_sel.min(self.files.len().saturating_sub(1));
            }

            Msg::Interrupted => {
                // Esc force-aborted the turn. The cancel command awaited the
                // stream join first, so core has committed the interrupted
                // history before any queued continuation starts.
                self.finalize_streaming();
                self.push_line(&Style::new().fg(TN_YELLOW).render("  ⎋ interrupted"));
                self.loop_remaining = 0; // Esc also stops a /loop
                self.review_pending = false; // and abandons an asset review
                self.sleep_pending = false; // and a `/sleep` consolidation
                self.restore_autonomy();
                self.finish();
                return self.drain_queue();
            }

            Msg::Agent(event) => return self.on_agent_event(*event),

            Msg::StreamEnded => {
                if self.host_progress_inflight {
                    self.rx = None;
                    return None;
                }
                if self.interrupting || self.state != State::Streaming {
                    return None;
                }
                // Channel closed without a normal End event (abnormal close).
                self.finalize_streaming();
                // An asset-review report fully streamed before the drop still
                // counts — same for a `/sleep` consolidation report.
                let turn_text = self.turn_text.clone();
                self.capture_review(&turn_text);
                let sleep_save = self.capture_sleep(&turn_text);
                self.disarm_sleep_if_over(sleep_save.is_some());
                return match (sleep_save, self.complete_turn()) {
                    (Some(save), Some(next)) => Some(cmd::batch(vec![save, next])),
                    (save, next) => save.or(next),
                };
            }

            Msg::SpinnerTick => {
                self.spinner.tick();
                self.blink_tick = self.blink_tick.wrapping_add(1);
                if self.state == State::Streaming {
                    self.update_viewport_with_stream();
                    return Some(spinner_tick());
                }
            }

            Msg::BannerTick => {
                // Re-render the animated mascot only while the banner is shown
                // (start screen / after /clear); the heartbeat keeps running so
                // the animation resumes whenever the banner reappears.
                if self.messages.is_empty()
                    && self.state == State::Idle
                    && self.top.is_none()
                    && self.ide.is_none()
                    && self.memory.is_none()
                    && !self.help_open
                {
                    self.anim = self.anim.wrapping_add(1);
                    self.viewport.set_content(&self.banner());
                }
                // Advance the ultracode brand-gradient flourish.
                if self.gradient_until.is_some() || self.effort_anim.is_some() {
                    self.gradient_frame = self.gradient_frame.wrapping_add(1);
                }
                // Ultracode confirm flourish: play in the /effort panel ~1.1s,
                // then close the panel and apply (which lights the input borders).
                if let Some(t) = self.effort_anim {
                    if t.elapsed() > Duration::from_millis(1100) {
                        self.effort_anim = None;
                        self.effort_panel = None;
                        self.apply_effort();
                    }
                }
                // Inactivity auto-review: after a quiet stretch with a real
                // conversation, summarise it once as a side note (Claude-style).
                if !self.auto_reviewed
                    && self.state == State::Idle
                    && !self.messages.is_empty()
                    && self.last_activity.elapsed() > Duration::from_secs(300)
                {
                    self.auto_reviewed = true;
                    let agent = self.agent.clone();
                    let workspace = self.cwd.clone();
                    let history = self.session.history();
                    let review = cmd::cmd(move || async move {
                        let conf = a3s_code_core::hitl::ConfirmationPolicy::enabled()
                            .with_timeout(BACKGROUND_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
                        let prompt = "Briefly review this conversation so far: summarise the \
                             key decisions and what's done, then list any open threads or next \
                             steps. Keep it to a few lines.";
                        let mut answer = String::new();
                        if let Ok(sess) = agent.session(workspace, Some(tui_session_options(conf)))
                        {
                            if let Ok((mut rx, _j)) = sess.stream(prompt, Some(&history)).await {
                                while let Some(ev) = rx.recv().await {
                                    match ev {
                                        AgentEvent::TextDelta { text } => answer.push_str(&text),
                                        AgentEvent::End { text, .. } => {
                                            if answer.trim().is_empty() {
                                                answer = text;
                                            }
                                            break;
                                        }
                                        _ => {}
                                    }
                                }
                            }
                        }
                        Msg::AutoReview(answer)
                    });
                    return Some(cmd::batch(vec![banner_tick(), review]));
                }
                // Keep the OS access token fresh: refresh proactively before it
                // expires so the agent's $A3S_OS_TOKEN never goes stale mid-session.
                if !self.os_refreshing {
                    if let Some(s) = &self.os_session {
                        if crate::a3s_os::needs_refresh(s) {
                            self.os_refreshing = true;
                            let session = s.clone();
                            let refresh = cmd::cmd(move || async move {
                                Msg::OsRefreshed(
                                    crate::a3s_os::refresh_session(&session)
                                        .await
                                        .map_err(|e| e.to_string()),
                                )
                            });
                            return Some(cmd::batch(vec![banner_tick(), refresh]));
                        }
                    }
                }
                return Some(banner_tick());
            }

            Msg::AutoReview(text) => {
                if !text.trim().is_empty() {
                    // Dim + unobtrusive — it's a passive side note, not output.
                    let dim =
                        |s: &str| format!("  {}", Style::new().fg(TN_GRAY).italic().render(s));
                    let mut lines = vec![dim("⟳ inactivity review")];
                    lines.extend(text.trim().lines().map(dim));
                    self.push_line(&lines.join("\n"));
                }
            }

            Msg::Compacted(summary) => {
                self.compacting = None;
                if summary.trim().is_empty() {
                    self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render("  compaction failed (empty summary)"),
                    );
                    return None;
                }
                // Reseed a FRESH session (new id, no history) carrying just the
                // summary in its system prompt — that's the actual compaction.
                self.compact_summary = Some(summary.trim().to_string());
                self.session_id = new_session_id();
                let model = self.model.clone();
                match self.rebuild_session(model.as_deref()) {
                    Ok((s, _)) => {
                        self.replace_session(s);
                        self.messages.clear();
                        self.output_tokens = 0;
                        self.last_prompt_tokens = 0;
                        self.ctx_warned_tier = 0; // fresh window: re-arm fill warnings
                        self.push_line(
                            &Style::new()
                                .fg(TN_GREEN)
                                .bold()
                                .render("  ✦ context compacted — continuing from this summary:"),
                        );
                        self.push_line(&gutter(
                            TN_CYAN,
                            self.compact_summary.as_deref().unwrap_or(""),
                        ));
                        self.rebuild_viewport();
                    }
                    Err(e) => self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  compaction failed: {e}")),
                    ),
                }
            }

            Msg::UpdateCheck(latest) => {
                let current = crate::update::current_version();
                let newer = latest
                    .as_deref()
                    .is_some_and(|l| !crate::update::version_ge(&current, l));
                if newer {
                    self.update_available = latest;
                    // Refresh the start screen so the notice shows in the banner
                    // without clobbering it with a transcript line.
                    if self.messages.is_empty() {
                        self.viewport.set_content(&self.banner());
                    }
                }
            }

            Msg::ModalConfirm(idx) => {
                let approved = idx == 0;
                self.state = State::Streaming;
                if let Some((tool_id, label)) = self.pending_tool.take() {
                    // Approved → silent (the tool runs, ToolEnd shows the result);
                    // denied → a brief note since no result will follow.
                    if !approved {
                        self.push_line(
                            &Style::new()
                                .fg(TN_RED)
                                .render(&format!("  ⎿ denied {label}")),
                        );
                    }
                    let session = self.session.clone();
                    return Some(cmd::batch(vec![
                        cmd::cmd(move || async move {
                            let _ = session.confirm_tool_use(&tool_id, approved, None).await;
                            Msg::Resume
                        }),
                        spinner_tick(),
                    ]));
                }
            }

            Msg::Resume => {
                if let Some(rx) = self.rx.clone() {
                    return Some(pump(rx));
                }
            }

            Msg::ShellOutput(text) => {
                let body = text.lines().take(40).collect::<Vec<_>>().join("\n");
                self.push_line(&gutter(TN_GRAY, body.trim_end()));
            }

            Msg::DeepResearchWorkflowCompleted {
                query,
                os_runtime,
                args,
                result,
            } => return self.on_deep_research_workflow_completed(query, os_runtime, args, result),

            Msg::DeepResearchSynthesisTimedOut { token } => {
                return self.on_deep_research_synthesis_timed_out(token);
            }

            Msg::UpdatePlan(latest) => {
                self.updating = None;
                self.relayout();
                let current = crate::update::current_version();
                match latest {
                    None => self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  couldn't reach the release server — try again later"),
                    ),
                    Some(l) if crate::update::version_ge(&current, &l) => {
                        self.push_line(
                            &Style::new()
                                .fg(TN_GREEN)
                                .render(&format!("  ✓ already up to date (a3s {current})")),
                        );
                        self.push_line(
                            &Style::new()
                                .fg(TN_GRAY)
                                .render("  checking companion tools…"),
                        );
                        self.updating = Some(Instant::now());
                        self.relayout();
                        return Some(cmd::cmd(|| async {
                            let result =
                                tokio::task::spawn_blocking(crate::update::repair_installation)
                                    .await
                                    .map_err(|e| format!("repair task failed: {e}"))
                                    .and_then(|r| r);
                            Msg::UpdateRepair(result)
                        }));
                    }
                    Some(l) => {
                        // macOS/Linux self-update in place (Homebrew or a direct
                        // download); unsupported platforms get the download link.
                        if crate::update::can_self_update() {
                            if let Ok(mut g) = LATEST.lock() {
                                *g = Some(l.clone());
                            }
                            UPGRADE_ON_EXIT.store(true, std::sync::atomic::Ordering::Relaxed);
                            self.push_line(&Style::new().fg(TN_GREEN).render(&format!(
                                "  → a3s {l} available — closing to upgrade, then restarting…"
                            )));
                            return Some(cmd::quit());
                        }
                        self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                            "  → a3s {l} available — download: https://github.com/A3S-Lab/Cli/releases/latest"
                        )));
                    }
                }
            }

            Msg::UpdateRepair(result) => {
                self.updating = None;
                self.relayout();
                match result {
                    Ok(items) if items.is_empty() => self.push_line(
                        &Style::new()
                            .fg(TN_GREEN)
                            .render("  ✓ installation looks healthy"),
                    ),
                    Ok(items) => {
                        for item in items {
                            self.push_line(
                                &Style::new().fg(TN_GREEN).render(&format!("  ✓ {item}")),
                            );
                        }
                    }
                    Err(error) => self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  install repair failed: {error}")),
                    ),
                }
            }

            Msg::OsLogin(result) => match result {
                Ok(label) => {
                    // The browser flow already saved to disk; load it into memory
                    // and rebuild so the login-gated skill activates this run.
                    self.os_session = self
                        .os_config
                        .as_ref()
                        .and_then(crate::a3s_os::current_session);
                    if let Some(s) = &self.os_session {
                        crate::a3s_os::export_os_env(s);
                    }
                    self.refresh_after_auth();
                    self.push_line(&Style::new().fg(TN_GREEN).render(&format!(
                        "  ✓ signed in to OS as {label} · capabilities skill active"
                    )));
                    // Auto-register this machine's SSH public key with OS so
                    // git-over-SSH works without manual key setup (idempotent,
                    // best-effort — never blocks the completed login).
                    if let Some(s) = self.os_session.clone() {
                        return Some(cmd::cmd(move || async move {
                            Msg::SshKeySynced(crate::a3s_os::sync_ssh_key(s).await)
                        }));
                    }
                }
                Err(error) => self.push_line(
                    &Style::new()
                        .fg(TN_RED)
                        .render(&format!("  login failed: {error}")),
                ),
            },

            Msg::SshKeySynced(outcome) => {
                use crate::a3s_os::SshKeyOutcome;
                match outcome {
                    SshKeyOutcome::Registered(fp) => self.push_line(&Style::new().fg(TN_GREEN).render(
                        &format!("  ✓ local SSH public key registered with OS ({fp}) · git clone(ssh) ready"),
                    )),
                    SshKeyOutcome::AlreadyRegistered => self.push_line(
                        &Style::new()
                            .fg(TN_GRAY)
                            .render("  · SSH public key already registered with OS; skipping"),
                    ),
                    SshKeyOutcome::NoLocalKey => self.push_line(&Style::new().fg(TN_YELLOW).render(
                        "  · no local SSH public key found; create one and run /login again to register it automatically: ssh-keygen -t ed25519",
                    )),
                    SshKeyOutcome::Failed(e) => self.push_line(
                        &Style::new()
                            .fg(TN_GRAY)
                            .render(&format!("  · SSH key sync skipped: {e}")),
                    ),
                }
            }

            Msg::OsRefreshed(result) => {
                self.os_refreshing = false;
                match result {
                    Ok(session) => {
                        // Re-export the fresh token so the agent's $A3S_OS_TOKEN
                        // stays valid; no session rebuild needed. Re-sync the
                        // runtime tool too because it owns a token snapshot.
                        crate::a3s_os::export_os_env(&session);
                        self.os_session = Some(session);
                        self.sync_runtime_tool();
                    }
                    Err(_) => {
                        // Leave the existing session; the next BannerTick retries
                        // while it's still within the refresh window, and /login
                        // remains the fallback once it truly expires.
                    }
                }
            }

            Msg::OsGatewayModels {
                login_at_ms,
                result,
            } => {
                if !self
                    .os_session
                    .as_ref()
                    .is_some_and(|session| session.login_at_ms == login_at_ms)
                {
                    return None;
                }
                self.os_gateway_models_loading = false;
                match result {
                    // Record each model's real context window (when the gateway
                    // reports one) so switching to it sizes auto-compact + the
                    // status bar correctly, then cache the ids.
                    Ok(models) => {
                        for m in &models {
                            if let Some(ctx) = m.context {
                                self.model_ctx.insert(m.id.clone(), ctx);
                            }
                        }
                        self.os_gateway_models = Some(models.into_iter().map(|m| m.id).collect());
                        self.os_gateway_error = None;
                    }
                    // Keep the precise reason so the picker + switch attempt can
                    // explain WHY the gateway is unavailable.
                    Err(e) => {
                        self.os_gateway_models = Some(Vec::new());
                        self.os_gateway_error = Some(e);
                    }
                }
                self.clamp_open_model_menu_selection();
            }

            Msg::SideNote(text) => {
                if let Some((q, _)) = self.btw.take() {
                    self.btw = Some((q, Some(text.trim().to_string())));
                }
            }

            Msg::TopData(rows) => {
                if self.top.is_some() {
                    self.top_history.observe(&rows);
                    self.top = Some(rows);
                    return Some(cmd::tick(Duration::from_millis(1500), Msg::TopRefresh));
                }
            }
            Msg::TopRefresh => {
                if self.top.is_some() {
                    return Some(cmd::cmd(|| async { Msg::TopData(fetch_top().await) }));
                }
            }
            Msg::Forked(result) => {
                match result {
                    Ok(new_id) => {
                        // Swap the active session to the fork (which carries the copied
                        // history). Set the id first — rebuild_session keys off it — and
                        // revert on failure so id and session never desync. The
                        // transcript stays on screen: the fork continues from here.
                        let prev = std::mem::replace(&mut self.session_id, new_id);
                        let model = self.model.clone();
                        match self.rebuild_session(model.as_deref()) {
                            Ok((s, _)) => {
                                self.replace_session(s);
                                let short: String = self.session_id.chars().take(8).collect();
                                self.push_line(&gutter(
                                TN_CYAN,
                                &format!("⑂ forked into a new session ({short}) — the original is kept"),
                            ));
                            }
                            Err(e) => {
                                self.session_id = prev;
                                self.push_line(
                                    &Style::new()
                                        .fg(TN_RED)
                                        .render(&format!("  fork failed: {e}")),
                                );
                            }
                        }
                    }
                    Err(e) => {
                        self.push_line(&Style::new().fg(TN_YELLOW).render(&format!("  /fork: {e}")))
                    }
                }
            }
            Msg::MemoryLoaded(data) => {
                if let Some(m) = &mut self.memory {
                    let source = if data.loaded_from_session {
                        "session fallback · "
                    } else {
                        ""
                    };
                    m.note = format!(
                        "{source}{} memories · {} entities · {} relations",
                        data.entries.len(),
                        data.graph.stats.entities,
                        data.graph.stats.relations
                    );
                    m.sel = 0;
                    m.apply_data(data);
                }
            }
            Msg::MemoryForgotten(result) => {
                if let Some(m) = &mut self.memory {
                    match result {
                        Ok((id, data)) => {
                            m.note = format!(
                                "forgot {id} · {} memories · {} candidates",
                                data.entries.len(),
                                data.graph.stats.forget_candidates
                            );
                            m.apply_data(data);
                        }
                        Err(error) => {
                            m.note = format!("forget failed: {error}");
                        }
                    }
                }
            }
            Msg::AssetListLoaded(result) => self.on_asset_list(result),
            Msg::RuntimeActivityLoaded(result) => self.on_runtime_activity(result),
            Msg::KbAdded(summary) => {
                let color = if summary.starts_with('✗') {
                    TN_RED
                } else {
                    TN_GRAY
                };
                self.push_line(&Style::new().fg(color).render(&format!("  {summary}")));
                if self.kb.is_some() {
                    self.open_kb_home(Some(summary));
                }
            }
            Msg::CtxResults(res) => self.on_ctx_results(res),
            Msg::CtxWindow(res) => self.on_ctx_window(res),
            Msg::CtxSaved(res) => self.on_ctx_saved(res),

            Msg::SleepSaved(res) => self.on_sleep_saved(res),

            Msg::FlowOsCompleted(res) => self.on_flow_os_completed(res),
            Msg::AgentOsCompleted(res) => self.on_agent_os_completed(res),
            Msg::McpOsCompleted(res) => self.on_mcp_os_completed(res),
            Msg::SkillOsCompleted(res) => self.on_skill_os_completed(res),
            Msg::OkfOsCompleted(res) => self.on_okf_os_completed(res),
            Msg::AssetCloned(res) => match res {
                Ok(result) => self.on_asset_cloned(result),
                Err(error) => self.push_line(
                    &Style::new()
                        .fg(TN_RED)
                        .render(&format!("  clone failed: {error}")),
                ),
            },
            Msg::CtxMemorySource(res) => match res {
                Ok((event_id, window)) => {
                    self.memory = None; // leave the panel to show the source
                    self.open_readonly_in_ide(&format!("ctx-source-{event_id}.txt"), &window);
                }
                Err(e) => {
                    if let Some(m) = self.memory.as_mut() {
                        m.note = format!("ctx source unavailable: {e}");
                    }
                }
            },

            _ => {}
        }
        None
    }

    fn view(&self) -> String {
        if self.help_open {
            return self.render_help();
        }
        if let Some(m) = &self.memory {
            return self.render_memory(m);
        }
        if let Some(panel) = &self.asset_list {
            return self.render_asset_list(panel);
        }
        if let Some(panel) = &self.runtime_activity {
            return self.render_runtime_activity(panel);
        }
        if let Some(kb) = &self.kb {
            let page = self.render_kb(kb);
            return self.overlay_approval(page);
        }
        if let Some(panel) = &self.loop_panel {
            return self.render_loop_panel(panel);
        }
        if let Some(ide) = &self.ide {
            // A pending tool approval overlays the full-screen page so it is
            // never invisible (its keys take priority in the key dispatch).
            let page = self.render_ide(ide);
            return self.overlay_approval(page);
        }
        if self.top.is_some() {
            return self.render_top_panel();
        }
        let width = self.width as usize;
        let raw_view = self.viewport.view();
        // Paint an active text-selection over the visible rows, then add the bar.
        let shown = match &self.selection {
            Some(s) if !s.is_empty() => {
                let (r1, c1, r2, c2) = s.ordered();
                highlight_selection(&raw_view, r1, c1, r2, c2)
            }
            _ => raw_view,
        };
        let viewport_view = append_scrollbar(
            &shown,
            width.saturating_sub(1),
            self.viewport.total_lines(),
            self.viewport.scroll_percent(),
        );
        // Input mode hint: `!` = shell command (pink), `?` = deep research
        // (cyan), `/agent` dev = local agent development (green), `/mcp` dev =
        // local MCP development (cyan), `/btw` = side-channel (yellow),
        // otherwise the normal prompt (accent blue).
        let inp = self.textarea.value();
        let (sym, icolor, border): (&str, Color, Color) = if self.shell_mode {
            ("!", GRADIENT_PREVIEW_END, GRADIENT_PREVIEW_END)
        } else if self.research_mode {
            ("?", TN_CYAN, TN_CYAN)
        } else if self.agent_dev.is_some() {
            ("◇", TN_GREEN, TN_GREEN)
        } else if self.mcp_dev.is_some() {
            ("◆", TN_CYAN, TN_CYAN)
        } else if self.skill_dev.is_some() {
            ("✦", TN_CYAN, TN_CYAN)
        } else if self.okf_dev.is_some() {
            ("⌁", TN_CYAN, TN_CYAN)
        } else if inp.starts_with("/btw") {
            ("❯", TN_YELLOW, TN_YELLOW)
        } else {
            ("❯", ACCENT, TN_GRAY)
        };
        // Brief brand-gradient ribbon on both input borders after picking
        // ultracode; otherwise plain bottom + effort-chip top.
        let gradient = self
            .gradient_until
            .is_some_and(|t| t.elapsed() < Duration::from_millis(1600));
        let separator = if gradient {
            input_gradient_rule(width, &BRAND_GRADIENT, self.gradient_frame + 3)
        } else {
            input_rule(width, border)
        };
        let top_separator = if gradient {
            input_gradient_rule(width, &BRAND_GRADIENT, self.gradient_frame)
        } else {
            let elabel = format!("◇ {}", EFFORT_LEVELS[self.effort].label);
            // Context-window usage at the top-right of the input (Claude-style).
            let ctxlabel = if self.context_limit > 0 {
                let pct = (self.last_prompt_tokens * 100 / self.context_limit as usize).min(100);
                format!("{pct}% context used  ")
            } else {
                String::new()
            };
            input_status_rule(width, border, &ctxlabel, &elabel)
        };

        // Activity line directly above the input: spinner while the agent works,
        // an inline approval prompt while awaiting, empty when idle.
        let activity = if self.updating.is_some() {
            // The upgrade itself runs in the shell after exit (real brew
            // progress); in-TUI this is just the quick version check.
            Style::new()
                .fg(TN_GREEN)
                .render("  ⬇ checking for updates…")
        } else if let Some(t0) = self.compacting {
            compact_progress_line(t0.elapsed(), width)
        } else {
            match self.state {
                State::Streaming => {
                    // Pulsing sparkle + "Thinking…" with live elapsed + token count.
                    let g = ['✶', '✸', '✹', '✺', '✹', '✷'][(self.blink_tick as usize / 2) % 6];
                    let spark = Style::new().fg(ACCENT).render(&g.to_string());
                    let working = shimmer("Working…", self.blink_tick as usize);
                    let mut tail = String::new();
                    if let Some(t0) = self.stream_started {
                        // Live output estimate: finalized output tokens + a
                        // CJK-aware estimate of the in-flight reasoning + answer
                        // (snaps to exact completion usage on End).
                        let est = self.output_tokens
                            + estimate_tokens(self.streaming.raw_content())
                            + estimate_tokens(&self.thinking);
                        tail.push_str(&format!(" ({}", fmt_elapsed(t0.elapsed())));
                        if est > 0 {
                            tail.push_str(&format!(" · ↓ {} tokens", humanize(est)));
                        }
                        tail.push(')');
                    }
                    let tail = Style::new().fg(ACCENT).render(&tail);
                    format!("  {spark} {working}{tail}")
                }
                // The approval options panel (overlay_approval) is the UI now.
                State::Awaiting => String::new(),
                State::Idle => String::new(),
            }
        };

        let typed = self.textarea.view();
        let tint_input = sym == "!"
            || sym == "?"
            || sym == "◇"
            || sym == "◆"
            || sym == "⌁"
            || inp.starts_with("/btw");
        let input_view = input_prompt_line(sym, icolor, &typed, tint_input, width);

        // Bottom status bar (Claude-style, two lines):
        //   dir git:(branch) <model> (<window> context) ctx:N%   [+ live chips]
        //   ⏵⏵ <mode> mode on (shift+tab to cycle) · …
        let status1 = self.session_status_line(width);
        let status2 = render_mode_status_line(self.mode, width);

        // Gap line between transcript and loading — or a floating "jump to
        // latest" hint when the user has scrolled up away from the bottom.
        let spacer = if self.viewport.at_bottom() {
            String::new()
        } else {
            jump_to_latest_hint(width)
        };
        let tasks = self.task_lines();
        let task_block = tasks.join("\n");
        // Plan/TODO panel stays pinned above the input.
        let plan = self.plan_lines();
        let plan_block = plan.join("\n");
        // Parallel-subagent tracker is pinned at the very bottom, below the
        // status bar (not above the input) so it doesn't push the prompt around.
        let subs = self.subagent_lines();
        let sub_block = subs.join("\n");
        let composed = Layout::vertical()
            .item(&viewport_view, Constraint::Fill)
            .item(&spacer, Constraint::Fixed(1))
            .item(&activity, Constraint::Fixed(1))
            .item(&plan_block, Constraint::Fixed(plan.len() as u16))
            .item(&top_separator, Constraint::Fixed(1))
            .item(&input_view, Constraint::Fixed(self.input_height()))
            .item(&separator, Constraint::Fixed(1))
            .item(&status1, Constraint::Fixed(1))
            .item(&status2, Constraint::Fixed(1))
            .item(&sub_block, Constraint::Fixed(subs.len() as u16))
            .item(&task_block, Constraint::Fixed(tasks.len() as u16))
            .render(self.height);

        let composed = self.overlay_slash_menu(composed);
        let composed = self.overlay_file_menu(composed);
        let composed = self.overlay_model_menu(composed);
        let composed = self.overlay_review_menu(composed);
        let composed = self.overlay_flow_menu(composed);
        let composed = self.overlay_agent_menu(composed);
        let composed = self.overlay_mcp_menu(composed);
        let composed = self.overlay_skill_menu(composed);
        let composed = self.overlay_okf_package_menu(composed);
        let composed = self.overlay_effort(composed);
        let composed = self.overlay_theme(composed);
        let composed = self.overlay_plugins(composed);
        let composed = self.overlay_approval(composed);
        self.overlay_btw(composed)
    }

    fn cursor(&self) -> Option<(u16, u16)> {
        // In the /ide editor, place the cursor at the edit position — inside
        // the right panel: tree width + its left border + the `%4d ` gutter.
        if let Some(ide) = &self.ide {
            if ide.focus_editor {
                if let Some(f) = &ide.file {
                    let width = self.width as usize;
                    let (tw, _) = panels::spf::ide_split(width);
                    let gutter = if panels::spf::ide_gutter_on(width) {
                        5
                    } else {
                        0
                    };
                    let x = tw + 1 + gutter + f.display_col().saturating_sub(f.hscroll);
                    let col = x.min(width.saturating_sub(2)) as u16;
                    let row = (1 + f.row.saturating_sub(f.scroll)) as u16;
                    return Some((col, row));
                }
            }
            return None;
        }
        // Real cursor at the input insertion point whenever the input is live —
        // idle OR streaming (you can keep typing while the agent works). Hidden
        // only during an approval prompt.
        if self.state == State::Awaiting
            || self.top.is_some()
            || self.memory.is_some()
            || self.asset_list.is_some()
            || self.runtime_activity.is_some()
            || self.kb.is_some()
            || self.loop_panel.is_some()
            || self.flow.is_some()
            || self.agent_picker.is_some()
            || self.mcp_picker.is_some()
            || self.skill_picker.is_some()
            || self.help_open
        {
            return None;
        }
        // Below the input: separator + 2 status lines + the subagent panel +
        // the task panel. The input spans `input_height` rows; cursor on its row.
        let below = 3 + self.subagent_lines().len() as u16 + self.task_lines().len() as u16;
        let row = self.height.saturating_sub(below + self.input_height())
            + self.textarea.cursor_row() as u16;
        let col = (PAD + 2) as u16 + self.textarea.cursor_display_col() as u16; // PAD + "❯ "
        Some((col, row))
    }
}

#[allow(clippy::too_many_arguments)]
fn render_session_status_line(
    cwd: &str,
    branch: Option<&str>,
    model: Option<&str>,
    context_limit: u32,
    last_prompt_tokens: usize,
    output_tokens: usize,
    chips: impl IntoIterator<Item = SessionStatusChip>,
    width: usize,
) -> String {
    if width == 0 {
        return String::new();
    }

    let theme = agent_chrome_theme();
    let chrome = agent_chrome(&theme);
    let mut status = chrome
        .session_status(cwd)
        .branch_color(TN_YELLOW)
        .threshold_colors(TN_YELLOW, TN_RED)
        .margin(2);

    if let Some(branch) = branch {
        status = status.branch(branch);
    }
    if let Some(model) = model {
        status = status.model(model);
    }
    if context_limit > 0 {
        status = status.context(last_prompt_tokens, context_limit as usize);
    } else if output_tokens > 0 {
        status = status.output_tokens(output_tokens);
    }
    for chip in chips {
        status = status.status_chip(chip);
    }

    status.view(width.min(u16::MAX as usize) as u16)
}

fn render_mode_status_line(mode: Mode, width: usize) -> String {
    if width == 0 {
        return String::new();
    }

    let theme = agent_chrome_theme();
    let chrome = agent_chrome(&theme);
    chrome
        .mode_line(mode.name())
        .glyph(mode.glyph())
        .hints("(shift+tab to cycle) · /help · ↑↓ history · esc")
        .mode_color(mode.color())
        .view(width.min(u16::MAX as usize) as u16)
}

fn jump_to_latest_hint(width: usize) -> String {
    if width == 0 {
        return String::new();
    }

    let label = InlineAction::new("more below · Shift+End to jump to latest")
        .icon("↓")
        .colors(Color::BrightWhite, ACCENT)
        .view();
    let label_width = a3s_tui::style::visible_len(&label);
    if label_width >= width {
        return a3s_tui::style::fit_visible(&label, width);
    }

    let pad = width.saturating_sub(label_width) / 2;
    a3s_tui::style::fit_visible(&format!("{}{}", " ".repeat(pad), label), width)
}

fn markdown_fragment_has_open_inline(text: &str) -> bool {
    let text = text.trim_end();
    if text.is_empty() {
        return false;
    }

    has_odd_unescaped_char(text, '`')
        || has_odd_unescaped_token(text, "**")
        || has_odd_unescaped_token(text, "__")
}

fn has_odd_unescaped_char(text: &str, needle: char) -> bool {
    let mut count = 0usize;
    let mut escaped = false;
    for ch in text.chars() {
        if escaped {
            escaped = false;
            continue;
        }
        if ch == '\\' {
            escaped = true;
            continue;
        }
        if ch == needle {
            count += 1;
        }
    }
    count % 2 == 1
}

fn has_odd_unescaped_token(text: &str, token: &str) -> bool {
    let mut count = 0usize;
    let mut index = 0usize;
    while let Some(offset) = text[index..].find(token) {
        let start = index + offset;
        if !is_escaped_at(text, start) {
            count += 1;
        }
        index = start + token.len();
    }
    count % 2 == 1
}

fn is_escaped_at(text: &str, byte_index: usize) -> bool {
    let mut slash_count = 0usize;
    for ch in text[..byte_index].chars().rev() {
        if ch == '\\' {
            slash_count += 1;
        } else {
            break;
        }
    }
    slash_count % 2 == 1
}

impl App {
    fn session_status_line(&self, width: usize) -> String {
        render_session_status_line(
            &self.cwd,
            self.branch.as_deref(),
            self.model.as_deref(),
            self.context_limit,
            self.last_prompt_tokens,
            self.output_tokens,
            self.session_status_chips(),
            width,
        )
    }

    fn session_status_chips(&self) -> Vec<SessionStatusChip> {
        let mut chips = Vec::new();

        if self.goal.is_some() {
            let elapsed = self
                .goal_since
                .map(|t| format!(" ({})", fmt_elapsed(t.elapsed())))
                .unwrap_or_default();
            chips.push(
                SessionStatusChip::new("🎯", format!("Pursuing goal{elapsed}")).color(TN_CYAN),
            );
        }
        if let Some(dev) = &self.agent_dev {
            chips.push(
                SessionStatusChip::new(
                    "◇",
                    format!("agent:{} · Esc /agent off", truncate(&dev.name, 24)),
                )
                .color(TN_GREEN),
            );
        }
        if let Some(dev) = &self.mcp_dev {
            chips.push(
                SessionStatusChip::new(
                    "◆",
                    format!("mcp:{} · Esc /mcp off", truncate(&dev.name, 24)),
                )
                .color(TN_CYAN),
            );
        }
        if let Some(dev) = &self.skill_dev {
            chips.push(
                SessionStatusChip::new(
                    "✦",
                    format!("skill:{} · Esc /skill off", truncate(&dev.name, 24)),
                )
                .color(TN_CYAN),
            );
        }
        if let Some(dev) = &self.okf_dev {
            chips.push(
                SessionStatusChip::new(
                    "⌁",
                    format!("okf:{} · Esc /okf off", truncate(&dev.name, 24)),
                )
                .color(TN_CYAN),
            );
        }
        if self.loop_remaining > 0 {
            chips.push(SessionStatusChip::new("↻", self.loop_remaining.to_string()).color(TN_GRAY));
        }
        let active_subagents = self.runtime.active_subagent_count();
        if active_subagents > 0 {
            chips.push(
                SessionStatusChip::new("⇉", format!("{active_subagents} agents")).color(TN_GRAY),
            );
        }
        let active_tools = self.runtime.active_tool_count();
        if active_tools > 0 {
            chips.push(
                SessionStatusChip::new("⚙", format!("{active_tools} running")).color(TN_GRAY),
            );
        }
        if let Some(version) = self.update_available.as_deref() {
            chips.push(SessionStatusChip::new("⬆", version).color(TN_YELLOW));
        }

        chips
    }

    fn clone_asset_command(
        &mut self,
        family: &'static str,
        url: String,
        root: std::path::PathBuf,
    ) -> Option<Cmd<Msg>> {
        self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
            "  cloning {family} asset from {url} → {}",
            root.display()
        )));
        Some(cmd::cmd(move || async move {
            Msg::AssetCloned(asset_clone::clone_asset_source(family, url, root).await)
        }))
    }

    fn on_asset_cloned(&mut self, result: asset_clone::AssetCloneResult) {
        self.push_line(&Style::new().fg(TN_GREEN).render(&format!(
            "  cloned {} asset → {}",
            result.family,
            result.path.display()
        )));
        match result.family {
            "agent" => self.open_agent_panel_focused(&result.path),
            "mcp" => self.open_mcp_panel_focused(&result.path),
            "skill" => self.open_skill_panel_focused(&result.path),
            "okf" | "knowledge" => self.open_okf_package_panel_focused(&result.path),
            "workflow" => self.open_flow_panel_focused(&result.path),
            _ => self.push_line(
                &Style::new()
                    .fg(TN_GRAY)
                    .render("  run the asset command again to select or operate on it"),
            ),
        }
    }

    fn path_is_within(path: &std::path::Path, root: &std::path::Path) -> bool {
        path == root || path.starts_with(root)
    }

    fn open_agent_panel_focused(&mut self, cloned_path: &std::path::Path) {
        let root = agent_dir();
        let agents = panels::agent::list_agents(&root);
        let Some(sel) = agents
            .iter()
            .position(|agent| Self::path_is_within(&agent.path, cloned_path))
        else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  cloned source does not contain a recognized agent definition yet"),
            );
            return;
        };
        self.agent_picker = Some(panels::agent::AgentPanel { root, agents, sel });
        self.push_line(
            &Style::new()
                .fg(TN_GRAY)
                .render("  selected cloned agent asset · Enter develops locally"),
        );
    }

    fn open_mcp_panel_focused(&mut self, cloned_path: &std::path::Path) {
        let root = mcp_dir();
        let projects = panels::mcp::list_mcp_projects(&root);
        let Some(sel) = projects
            .iter()
            .position(|project| Self::path_is_within(&project.path, cloned_path))
        else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  cloned source does not contain a recognized MCP asset yet"),
            );
            return;
        };
        self.mcp_picker = Some(panels::mcp::McpPanel {
            root,
            projects,
            sel,
        });
        self.push_line(
            &Style::new()
                .fg(TN_GRAY)
                .render("  selected cloned MCP asset · Enter develops locally"),
        );
    }

    fn open_skill_panel_focused(&mut self, cloned_path: &std::path::Path) {
        let root = skill_dir();
        let skills = panels::skill::list_skill_assets(&root);
        let Some(sel) = skills
            .iter()
            .position(|skill| Self::path_is_within(&skill.path, cloned_path))
        else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  cloned source does not contain a recognized skill asset yet"),
            );
            return;
        };
        self.skill_picker = Some(panels::skill::SkillPanel { root, skills, sel });
        self.push_line(
            &Style::new()
                .fg(TN_GRAY)
                .render("  selected cloned skill asset · Enter develops locally"),
        );
    }

    fn open_okf_package_panel_focused(&mut self, cloned_path: &std::path::Path) {
        let root = panels::okf::okf_package_dir(&self.cwd);
        let packages = panels::okf::list_okf_packages(&root);
        let Some(sel) = packages
            .iter()
            .position(|package| Self::path_is_within(&package.path, cloned_path))
        else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  cloned source does not contain a recognized OKF package yet"),
            );
            return;
        };
        self.okf_picker = Some(panels::okf::OkfPackagePanel {
            root,
            packages,
            sel,
        });
        self.push_line(
            &Style::new()
                .fg(TN_GRAY)
                .render("  selected cloned OKF package · Enter develops locally"),
        );
    }

    fn open_flow_panel_focused(&mut self, cloned_path: &std::path::Path) {
        let root = flow_dir();
        let flows = panels::flow::list_flows(&root);
        let Some(sel) = flows
            .iter()
            .position(|flow| Self::path_is_within(&root.join(flow), cloned_path))
        else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  cloned source does not contain a recognized workflow design yet"),
            );
            return;
        };
        self.flow = Some(panels::flow::FlowPanel { root, flows, sel });
        self.push_line(
            &Style::new()
                .fg(TN_GRAY)
                .render("  selected cloned workflow asset · Enter opens the OS designer"),
        );
    }

    fn execute_agent_subcommand(
        &mut self,
        subcommand: panels::agent::AgentSubcommand,
    ) -> Option<Cmd<Msg>> {
        match subcommand {
            panels::agent::AgentSubcommand::Exit => {
                self.exit_agent_dev();
                None
            }
            panels::agent::AgentSubcommand::Clone(url) => {
                self.clone_asset_command("agent", url, agent_dir())
            }
            panels::agent::AgentSubcommand::List(query) => {
                self.open_asset_list_panel(os_asset_category_query("agent", &query))
            }
            panels::agent::AgentSubcommand::Activity(query) => {
                let Some(agent_dev) = self.agent_dev.clone() else {
                    self.pending_agent_subcommand =
                        Some(panels::agent::AgentSubcommand::Activity(query));
                    self.open_agent_panel();
                    return None;
                };
                self.open_runtime_activity_panel(runtime_asset_query(
                    "agent",
                    &agent_dev.name,
                    &query,
                ))
            }
            panels::agent::AgentSubcommand::Review => {
                let Some(agent_dev) = self.agent_dev.clone() else {
                    self.pending_agent_subcommand = Some(panels::agent::AgentSubcommand::Review);
                    self.open_agent_panel();
                    return None;
                };
                self.messages
                    .push(user_bubble("/agent review", self.viewport_content_width()));
                self.engage_autonomy(4);
                self.review_pending = true;
                let prompt = panels::agent::agent_review_prompt(&agent_dev);
                let display = format!("◇ {} review", agent_dev.name);
                self.start_stream_inner(prompt, display, true, true, false)
            }
            other => {
                let Some(agent_dev) = self.agent_dev.clone() else {
                    self.pending_agent_subcommand = Some(other);
                    self.open_agent_panel();
                    return None;
                };
                let Some(session) = self.os_session.clone() else {
                    self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  /agent OS actions need /login first"),
                    );
                    return None;
                };
                let action = match other {
                    panels::agent::AgentSubcommand::Publish(kind) => {
                        panels::agent::AgentOsAction::Publish(kind)
                    }
                    panels::agent::AgentSubcommand::Run => {
                        panels::agent::AgentOsAction::Run(panels::agent::AgentOsKind::Agentic)
                    }
                    panels::agent::AgentSubcommand::Deploy => panels::agent::AgentOsAction::Deploy,
                    panels::agent::AgentSubcommand::Open(kind) => {
                        panels::agent::AgentOsAction::Open(kind)
                    }
                    panels::agent::AgentSubcommand::Logs(kind) => {
                        panels::agent::AgentOsAction::Logs(kind)
                    }
                    panels::agent::AgentSubcommand::Status(kind) => {
                        panels::agent::AgentOsAction::Status(kind)
                    }
                    panels::agent::AgentSubcommand::Exit
                    | panels::agent::AgentSubcommand::Clone(_)
                    | panels::agent::AgentSubcommand::List(_)
                    | panels::agent::AgentSubcommand::Activity(_)
                    | panels::agent::AgentSubcommand::Review => unreachable!(),
                };
                let kind = action.target_kind();
                self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                    "  ◇ {} → OS {} {}…",
                    agent_dev.name,
                    kind.label(),
                    kind.service_label()
                )));
                Some(cmd::cmd(move || async move {
                    let result =
                        panels::agent::publish_agent_to_os(session, agent_dev, action).await;
                    Msg::AgentOsCompleted(result)
                }))
            }
        }
    }

    fn execute_mcp_subcommand(
        &mut self,
        subcommand: panels::mcp::McpSubcommand,
    ) -> Option<Cmd<Msg>> {
        match subcommand {
            panels::mcp::McpSubcommand::Exit => {
                self.exit_mcp_dev();
                None
            }
            panels::mcp::McpSubcommand::Clone(url) => {
                self.clone_asset_command("mcp", url, mcp_dir())
            }
            panels::mcp::McpSubcommand::List(query) => {
                self.open_asset_list_panel(os_asset_category_query("mcp", &query))
            }
            panels::mcp::McpSubcommand::Activity(query) => {
                let Some(mcp_dev) = self.mcp_dev.clone() else {
                    self.pending_mcp_subcommand = Some(panels::mcp::McpSubcommand::Activity(query));
                    self.open_mcp_panel();
                    return None;
                };
                self.open_runtime_activity_panel(runtime_asset_query("mcp", &mcp_dev.name, &query))
            }
            panels::mcp::McpSubcommand::Review => {
                let Some(mcp_dev) = self.mcp_dev.clone() else {
                    self.pending_mcp_subcommand = Some(panels::mcp::McpSubcommand::Review);
                    self.open_mcp_panel();
                    return None;
                };
                self.messages
                    .push(user_bubble("/mcp review", self.viewport_content_width()));
                self.engage_autonomy(4);
                self.review_pending = true;
                let prompt = panels::mcp::mcp_review_prompt(&mcp_dev);
                let display = format!("◆ {} review", mcp_dev.name);
                self.start_stream_inner(prompt, display, true, true, false)
            }
            other => {
                let Some(action) = other.os_action() else {
                    unreachable!("local MCP actions handled above")
                };
                let Some(mcp_dev) = self.mcp_dev.clone() else {
                    self.pending_mcp_subcommand = Some(other);
                    self.open_mcp_panel();
                    return None;
                };
                let Some(session) = self.os_session.clone() else {
                    self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  /mcp OS actions need /login first"),
                    );
                    return None;
                };
                self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                    "  ◆ {} → OS MCP Function as a Service {}…",
                    mcp_dev.name,
                    action.label()
                )));
                Some(cmd::cmd(move || async move {
                    let result = panels::mcp::publish_mcp_to_os(session, mcp_dev, action).await;
                    Msg::McpOsCompleted(result)
                }))
            }
        }
    }

    fn execute_skill_subcommand(
        &mut self,
        subcommand: panels::skill::SkillSubcommand,
    ) -> Option<Cmd<Msg>> {
        match subcommand {
            panels::skill::SkillSubcommand::Exit => {
                self.exit_skill_dev();
                None
            }
            panels::skill::SkillSubcommand::Clone(url) => {
                self.clone_asset_command("skill", url, skill_dir())
            }
            panels::skill::SkillSubcommand::List(query) => {
                self.open_asset_list_panel(os_asset_category_query("skill", &query))
            }
            panels::skill::SkillSubcommand::Activity(query) => {
                let Some(skill_dev) = self.skill_dev.clone() else {
                    self.pending_skill_subcommand =
                        Some(panels::skill::SkillSubcommand::Activity(query));
                    self.open_skill_panel();
                    return None;
                };
                self.open_runtime_activity_panel(runtime_asset_query(
                    "skill",
                    &skill_dev.name,
                    &query,
                ))
            }
            panels::skill::SkillSubcommand::Review => {
                if self.skill_dev.is_none() {
                    self.pending_skill_subcommand = Some(panels::skill::SkillSubcommand::Review);
                    self.open_skill_panel();
                    return None;
                }
                let skill = self.skill_dev.clone().expect("checked above");
                let body = match std::fs::read_to_string(&skill.path) {
                    Ok(body) => body,
                    Err(error) => {
                        self.push_line(&Style::new().fg(TN_RED).render(&format!(
                            "  could not read {}: {error}",
                            skill.path.display()
                        )));
                        return None;
                    }
                };
                self.messages
                    .push(user_bubble("/skill review", self.viewport_content_width()));
                self.engage_autonomy(4);
                self.review_pending = true;
                let prompt = panels::skill::skill_review_prompt(&skill.path, &body);
                let display = format!("✦ {} review", skill.name);
                self.start_stream_inner(prompt, display, true, true, false)
            }
            panels::skill::SkillSubcommand::Publish => {
                self.execute_skill_os_action(panels::skill::SkillOsAction::Publish)
            }
            panels::skill::SkillSubcommand::Deploy => {
                if self.skill_dev.is_none() {
                    self.pending_skill_subcommand = Some(panels::skill::SkillSubcommand::Deploy);
                    self.open_skill_panel();
                    return None;
                }
                self.execute_skill_os_action(panels::skill::SkillOsAction::Deploy)
            }
            panels::skill::SkillSubcommand::Open => {
                self.execute_skill_os_action(panels::skill::SkillOsAction::Open)
            }
            panels::skill::SkillSubcommand::Status => {
                self.execute_skill_os_action(panels::skill::SkillOsAction::Status)
            }
        }
    }

    fn execute_skill_os_action(
        &mut self,
        action: panels::skill::SkillOsAction,
    ) -> Option<Cmd<Msg>> {
        let Some(skill_dev) = self.skill_dev.clone() else {
            self.pending_skill_subcommand = Some(match action {
                panels::skill::SkillOsAction::Publish => panels::skill::SkillSubcommand::Publish,
                panels::skill::SkillOsAction::Deploy => panels::skill::SkillSubcommand::Deploy,
                panels::skill::SkillOsAction::Open => panels::skill::SkillSubcommand::Open,
                panels::skill::SkillOsAction::Status => panels::skill::SkillSubcommand::Status,
            });
            self.open_skill_panel();
            return None;
        };
        let Some(session) = self.os_session.clone() else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  /skill OS actions need /login first"),
            );
            return None;
        };
        self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
            "  ✦ {} → OS skill Function as a Service {}…",
            skill_dev.name,
            action.label()
        )));
        Some(cmd::cmd(move || async move {
            let result = panels::skill::publish_skill_to_os(session, skill_dev, action).await;
            Msg::SkillOsCompleted(result)
        }))
    }

    fn on_submit(&mut self, text: String) -> Option<Cmd<Msg>> {
        let trimmed = text.trim();
        if trimmed.is_empty() {
            return None;
        }
        // No input while compacting or upgrading.
        if self.compacting.is_some() || self.updating.is_some() {
            self.textarea.clear();
            return None;
        }
        // Shell mode (`!`) runs a shell command directly (not through the agent).
        if self.shell_mode {
            self.shell_mode = false;
            let cmd = trimmed.trim_start_matches('!').trim().to_string();
            if cmd.is_empty() {
                return None;
            }
            self.messages.push(gutter(
                GRADIENT_PREVIEW_END,
                &Style::new().bold().render(&format!("! {cmd}")),
            ));
            self.textarea.clear();
            self.rebuild_viewport();
            return Some(cmd::cmd(move || async move {
                let out = tokio::process::Command::new("sh")
                    .arg("-c")
                    .arg(&cmd)
                    .output()
                    .await;
                let text = match out {
                    Ok(o) => {
                        let mut s = String::from_utf8_lossy(&o.stdout).into_owned();
                        s.push_str(&String::from_utf8_lossy(&o.stderr));
                        if s.trim().is_empty() {
                            format!("(exit {})", o.status.code().unwrap_or(-1))
                        } else {
                            s
                        }
                    }
                    Err(e) => format!("failed to run: {e}"),
                };
                Msg::ShellOutput(text)
            }));
        }
        // Deep-research mode (`?`) is host-orchestrated for stability: the TUI
        // first executes a finite, complexity-driven recursive retrieval-summary
        // workflow through local parallel_task fan-out, then starts one synthesis
        // turn over the gathered evidence.
        if self.research_mode {
            self.research_mode = false;
            let query = trimmed.trim_start_matches('?').trim().to_string();
            if query.is_empty() {
                self.textarea.clear();
                return None;
            }
            self.history.push(trimmed.to_string());
            self.history_pos = None;
            self.textarea.clear();
            self.goal = Some(deep_research_goal(&query));
            self.goal_since = Some(Instant::now());
            self.messages.push(gutter(
                TN_CYAN,
                &Style::new()
                    .bold()
                    .render(&format!("🔬 deep research: {query}")),
            ));
            let os_runtime =
                should_use_os_runtime_for_deep_research(&query, self.os_session.is_some());
            let loop_layers = deep_research_loop_layers(&query, os_runtime);
            let budget = deep_research_budget_for_effort_index(self.effort, self.context_limit);
            let research_rounds = deep_research_research_rounds(&query, os_runtime, budget);
            let layer_hint = match loop_layers {
                0 => "single synthesis pass".to_string(),
                1 => "1 verification layer".to_string(),
                n => format!("{n} verification layers"),
            };
            let round_hint = if research_rounds == 1 {
                "1 retrieval round".to_string()
            } else {
                format!("up to {research_rounds} retrieval rounds")
            };
            let runtime_hint = if os_runtime {
                format!(
                    "  🎯 goal set · adaptive deep research · local workflow selected · OS Runtime FaaS pending · {round_hint} · local HTML opens in RemoteUI · {layer_hint} (Esc stops)"
                )
            } else if self.os_session.is_some() {
                format!(
                    "  🎯 goal set · adaptive deep research · local workflow selected · {round_hint} · local HTML opens in RemoteUI · {layer_hint} (Esc stops)"
                )
            } else {
                format!(
                    "  🎯 goal set · local deep research · {round_hint} · report + HTML opens in RemoteUI · {layer_hint} (Esc stops)"
                )
            };
            self.push_line(&Style::new().fg(TN_GRAY).render(&runtime_hint));
            let display = format!("🔬 {query}");
            // DeepResearch is bounded in two places: the host workflow runs a
            // finite recursive retrieval-summary loop, then the synthesis turn
            // may get a small scored number of report verification layers.
            if loop_layers == 0 {
                self.engage_single_turn_autonomy();
            } else {
                self.engage_autonomy(loop_layers);
            }
            let runtime_expectation = Some(RuntimeExpectation::required("deep research"));
            if self.state == State::Idle {
                return self.start_deep_research_workflow(query, os_runtime, runtime_expectation);
            }
            self.seq += 1;
            self.queue.push(Queued {
                prio: 1,
                seq: self.seq,
                text: String::new(),
                display,
                runtime_expectation,
                deep_research: Some((query, os_runtime)),
            });
            self.push_line(&Style::new().fg(TN_GRAY).render("    ⋯ queued"));
            self.relayout();
            return None;
        }
        // Block session-mutating commands while a turn is streaming.
        if self.state != State::Idle {
            let cmd0 = trimmed.split_whitespace().next().unwrap_or("");
            if IDLE_ONLY.contains(&cmd0) {
                self.textarea.clear();
                self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
                    "  {cmd0} is unavailable while a turn is running — press Esc to stop first"
                )));
                return None;
            }
        }
        if let Some(rest) = slash_tail(trimmed, "/login") {
            self.textarea.clear();
            let Some(os_config) = self.os_config.clone() else {
                self.push_line(&format!(
                    "{}\n{}\n{}\n{}",
                    Style::new()
                        .fg(TN_YELLOW)
                        .render("  /login needs an OS endpoint, but none is configured."),
                    Style::new().fg(TN_GRAY).render(
                        "  Add it to ~/.a3s/config.acl (or your project's .a3s/config.acl):"
                    ),
                    Style::new()
                        .fg(TN_CYAN)
                        .render("      os = \"https://your-os-host.example.com\""),
                    Style::new()
                        .fg(TN_GRAY)
                        .render("  then restart a3s code and run /login again."),
                ));
                return None;
            };
            let token = rest.trim();
            if !token.is_empty() {
                match crate::a3s_os::login_with_token(&os_config, token) {
                    Ok(session) => {
                        let label = session.display_label();
                        crate::a3s_os::export_os_env(&session);
                        self.os_session = Some(session);
                        self.refresh_after_auth();
                        self.push_line(&Style::new().fg(TN_GREEN).render(&format!(
                            "  ✓ signed in to OS as {label} · capabilities skill active"
                        )));
                    }
                    Err(error) => self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  login failed: {error}")),
                    ),
                }
                return None;
            }

            // Already signed in (restored from a previous run) → no need to
            // re-authenticate; tell the user how to switch instead.
            if let Some(s) = &self.os_session {
                self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                    "  already signed in to OS as {} · /logout to switch accounts",
                    s.display_label()
                )));
                return None;
            }

            self.push_line(
                &Style::new()
                    .fg(TN_GRAY)
                    .render("  opening OS login in your browser…"),
            );
            return Some(cmd::cmd(move || async move {
                let result = crate::a3s_os::login_via_browser(os_config)
                    .await
                    .map(|session| session.display_label())
                    .map_err(|error| error.to_string());
                Msg::OsLogin(result)
            }));
        }
        if trimmed == "/logout" {
            self.textarea.clear();
            let Some(os_config) = self.os_config.clone() else {
                self.push_line(&Style::new().fg(TN_YELLOW).render(
                    "  configure `os = \"https://...\"` in .a3s/config.acl to enable /logout",
                ));
                return None;
            };
            match crate::a3s_os::logout(&os_config) {
                Ok(true) => {
                    self.os_session = None;
                    self.asset_list = None;
                    self.runtime_activity = None;
                    crate::a3s_os::remove_capability_skill_dir();
                    crate::a3s_os::clear_os_env();
                    self.refresh_after_auth();
                    self.push_line(
                        &Style::new()
                            .fg(TN_GREEN)
                            .render("  ✓ signed out from OS · capabilities skill removed"),
                    );
                }
                Ok(false) => {
                    self.os_session = None;
                    self.asset_list = None;
                    self.runtime_activity = None;
                    crate::a3s_os::remove_capability_skill_dir();
                    crate::a3s_os::clear_os_env();
                    self.refresh_after_auth();
                    self.push_line(&Style::new().fg(TN_GRAY).render("  no OS login was stored"));
                }
                Err(error) => self.push_line(
                    &Style::new()
                        .fg(TN_RED)
                        .render(&format!("  logout failed: {error}")),
                ),
            }
            return None;
        }
        // `/kb` opens the local personal knowledge-base panel. Notes/imports/search are
        // explicit subcommands so a mistyped path no longer becomes a note.
        // `/ctx <query>` searches past agent sessions; `/ctx <n>` stages hit n
        // as context for the next message (ctx CLI, local SQLite index).
        if let Some(rest) = slash_tail(trimmed, "/ctx") {
            return self.handle_ctx_command(rest);
        }
        if let Some(rest) = slash_tail(trimmed, "/okf") {
            return self.handle_okf_command(rest);
        }
        if let Some(rest) = slash_tail(trimmed, "/kb") {
            return self.handle_kb_command(rest);
        }
        // `/btw <prompt>` runs a background side-thread (separate ephemeral
        // session, the main conversation as context) without disturbing the
        // current turn; its answer arrives as a side note.
        if let Some(rest) = slash_tail(trimmed, "/btw") {
            let q = rest.trim().to_string();
            self.textarea.clear();
            if q.is_empty() {
                self.push_line(&Style::new().fg(TN_GRAY).render("  usage: /btw <question>"));
                return None;
            }
            self.btw = Some((q.clone(), None));
            let agent = self.agent.clone();
            let workspace = self.cwd.clone();
            let history = self.session.history();
            return Some(cmd::cmd(move || async move {
                // Side-thread is a quick Q&A; auto-reject tool prompts (no UI).
                let conf = a3s_code_core::hitl::ConfirmationPolicy::enabled()
                    .with_timeout(BACKGROUND_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
                let sess = match agent.session(workspace, Some(tui_session_options(conf))) {
                    Ok(s) => s,
                    Err(e) => return Msg::SideNote(format!("(/btw failed: {e})")),
                };
                let mut answer = String::new();
                if let Ok((mut rx, _join)) = sess.stream(&q, Some(&history)).await {
                    while let Some(ev) = rx.recv().await {
                        match ev {
                            AgentEvent::TextDelta { text } => answer.push_str(&text),
                            AgentEvent::End { text, .. } => {
                                if answer.trim().is_empty() {
                                    answer = text;
                                }
                                break;
                            }
                            _ => {}
                        }
                    }
                }
                Msg::SideNote(answer)
            }));
        }
        // `/goal [text|clear]` — a persistent goal prepended to every prompt.
        if let Some(rest) = slash_tail(trimmed, "/goal") {
            let g = rest.trim();
            self.textarea.clear();
            if g.is_empty() {
                match &self.goal {
                    Some(cur) => self.push_line(&gutter(
                        TN_CYAN,
                        &format!("🎯 goal: {cur}   (/goal clear to remove)"),
                    )),
                    None => self.push_line(
                        &Style::new()
                            .fg(TN_GRAY)
                            .render("  usage: /goal <what you're working toward>"),
                    ),
                }
            } else if g == "clear" {
                self.goal = None;
                self.goal_since = None;
                self.push_line(&Style::new().fg(TN_GRAY).render("  goal cleared"));
                return None;
            } else {
                if let Some(dev) = self.agent_dev.clone() {
                    let scoped = panels::agent::agent_goal_label(&dev, g);
                    self.goal = Some(scoped.clone());
                    self.goal_since = Some(Instant::now());
                    self.push_line(&gutter(
                        TN_CYAN,
                        &format!("🎯 agent goal set: {} · {g}", dev.name),
                    ));
                    let prompt = panels::agent::agent_dev_prompt(&dev, g);
                    let display = format!("◇ {} goal: {}", dev.name, truncate(g, 54));
                    return self.start_stream_inner(prompt, display, true, true, false);
                }
                // Set the persistent goal AND start working toward it now (the
                // goal is prepended to this and every later prompt).
                self.goal = Some(g.to_string());
                self.goal_since = Some(Instant::now());
                self.push_line(&gutter(TN_CYAN, &format!("🎯 goal set: {g}")));
                return Some(cmd::msg(Msg::Submit(g.to_string())));
            }
            return None;
        }
        // `/loop` — engineered loop dashboard + subcommands; unknown tails keep
        // the quick-loop contract (`/loop <task>`).
        if let Some(rest) = slash_tail(trimmed, "/loop") {
            return self.handle_loop_command(rest);
        }
        // `/sleep [focus]` — end-of-day consolidation: the `/loop` mechanism
        // drives the agent through reviewing today's work (cross-session via
        // `ctx` when installed) until a turn ends with the machine-readable
        // ```a3s-sleep report, which capture_sleep persists into long-term
        // memory (experience · preferences · knowledge). Idle-only.
        if let Some(rest) = slash_tail(trimmed, "/sleep") {
            let focus = rest.trim().to_string();
            self.textarea.clear();
            self.sleep_pending = true;
            self.engage_autonomy(8);
            self.push_line(
                &Style::new()
                    .fg(TN_GRAY)
                    .render("  ☾ sleep — consolidating today's work into memory… (Esc stops)"),
            );
            let directive = panels::sleep::sleep_directive(
                &focus,
                self.ctx_ready,
                &panels::sleep::sleep_today(),
            );
            // Like asset reviews: send the directive but show a short display
            // line (echoing the boilerplate as a user message is just noise).
            let display = if focus.is_empty() {
                "☾ sleep".to_string()
            } else {
                format!("☾ sleep · {focus}")
            };
            return self.start_stream_inner(directive, display, true, true, false);
        }
        // `/flow` — select a local DAG JSON and open it in the OS workflow
        // designer (login-gated); `/flow <description>` orchestrates a basic DAG into
        // the flows folder (local, no login needed). Token-boundary filtered
        // so "/flowx" stays a normal message and can't bypass the idle gate.
        if let Some(rest) = slash_tail(trimmed, "/flow") {
            let description = rest.trim().to_string();
            self.textarea.clear();
            if let Some(parsed) = panels::flow::parse_flow_subcommand(&description) {
                match parsed {
                    Ok(panels::flow::FlowSubcommand::Clone(url)) => {
                        return self.clone_asset_command("workflow", url, flow_dir());
                    }
                    Ok(panels::flow::FlowSubcommand::List(query)) => {
                        return self
                            .open_asset_list_panel(os_asset_category_query("workflow", &query));
                    }
                    Ok(panels::flow::FlowSubcommand::Activity(query)) => {
                        if self.os_session.is_none() {
                            self.push_line(&os_required_alert(
                                "workflow runtime activity",
                                self.os_config.is_some(),
                            ));
                        } else {
                            self.pending_flow_subcommand =
                                Some(panels::flow::FlowSubcommand::Activity(query));
                            self.open_flow_panel();
                        }
                        return None;
                    }
                    Ok(panels::flow::FlowSubcommand::Review(target)) => {
                        let root = flow_dir();
                        let flows = panels::flow::list_flows(&root);
                        let picked = match target {
                            Some(target) => flows
                                .into_iter()
                                .find(|flow| flow == &target || flow.ends_with(&target)),
                            None if flows.len() == 1 => flows.into_iter().next(),
                            None => None,
                        };
                        let Some(file) = picked else {
                            self.pending_flow_subcommand =
                                Some(panels::flow::FlowSubcommand::Review(None));
                            self.open_flow_panel();
                            return None;
                        };
                        let path = root.join(&file);
                        let design = match std::fs::read_to_string(&path) {
                            Ok(value) => value,
                            Err(error) => {
                                self.push_line(&Style::new().fg(TN_RED).render(&format!(
                                    "  could not read {}: {error}",
                                    path.display()
                                )));
                                return None;
                            }
                        };
                        if serde_json::from_str::<serde_json::Value>(&design).is_err() {
                            self.push_line(
                                &Style::new()
                                    .fg(TN_RED)
                                    .render(&format!("  {} is not valid JSON", file)),
                            );
                            return None;
                        }
                        self.messages.push(user_bubble(
                            &format!("/flow review {file}"),
                            self.viewport_content_width(),
                        ));
                        self.engage_autonomy(4);
                        self.review_pending = true;
                        let prompt = panels::flow::flow_review_prompt(&path, &design);
                        let display = format!("⧉ flow review: {}", truncate(&file, 48));
                        return self.start_stream_inner(prompt, display, true, true, false);
                    }
                    Ok(action @ panels::flow::FlowSubcommand::Publish)
                    | Ok(action @ panels::flow::FlowSubcommand::Run)
                    | Ok(action @ panels::flow::FlowSubcommand::Deploy)
                    | Ok(action @ panels::flow::FlowSubcommand::Open)
                    | Ok(action @ panels::flow::FlowSubcommand::Logs)
                    | Ok(action @ panels::flow::FlowSubcommand::Status) => {
                        if self.os_session.is_none() {
                            self.push_line(
                                &Style::new().fg(TN_YELLOW).render(
                                    "  /flow publish/run/deploy/open/logs/status needs OS — sign in with /login first",
                                ),
                            );
                        } else {
                            self.pending_flow_subcommand = Some(action);
                            self.open_flow_panel();
                        }
                        return None;
                    }
                    Err(e) => {
                        self.push_line(&Style::new().fg(TN_RED).render(&format!("  {e}")));
                        return None;
                    }
                }
            }
            if description.is_empty() {
                if self.os_session.is_none() {
                    self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  /flow needs OS — sign in with /login first"),
                    );
                } else {
                    self.open_flow_panel();
                }
                return None;
            }
            let dir = flow_dir();
            match panels::flow::scaffold_flow_asset(&description, &dir) {
                Ok(path) => {
                    self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                        "  ⧉ scaffolded workflow asset → {}",
                        path.parent()
                            .unwrap_or_else(|| std::path::Path::new("."))
                            .display()
                    )));
                    self.open_flow_panel_focused(&path);
                    return None;
                }
                Err(e) => {
                    self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  /flow scaffold failed: {e}")),
                    );
                    return None;
                }
            }
        }
        // `/agent` — select a local a3s-code agent package and enter local
        // multi-turn development mode; `/agent <description>` scaffolds a complete
        // local A3S Code agent package; OS subcommands publish/run/deploy the
        // active local definition through Agent as a Service or Function as a
        // Service according to the kind.
        if let Some(rest) = slash_tail(trimmed, "/agent") {
            let description = rest.trim().to_string();
            self.textarea.clear();
            if let Some(parsed) = panels::agent::parse_agent_subcommand(&description) {
                return match parsed {
                    Ok(subcommand) => self.execute_agent_subcommand(subcommand),
                    Err(e) => {
                        self.push_line(&Style::new().fg(TN_RED).render(&format!("  {e}")));
                        None
                    }
                };
            }
            if description.is_empty() {
                self.open_agent_panel();
                return None;
            }
            let dir = agent_dir();
            match panels::agent::scaffold_agent_package(&description, &dir) {
                Ok(dev) => {
                    self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                        "  ◇ scaffolded complete agent package → {}",
                        dev.package_path.display()
                    )));
                    return self.activate_agent_package_path(&dev.package_path);
                }
                Err(e) => {
                    self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  /agent scaffold failed: {e}")),
                    );
                    return None;
                }
            }
        }
        // `/mcp` — select a local MCP server asset and enter local multi-turn
        // development mode; `/mcp <description>` drafts a local MCP asset.
        // OS publish/run/test will map MCP tool calls to Function as a Service.
        if let Some(rest) = slash_tail(trimmed, "/mcp") {
            let description = rest.trim().to_string();
            self.textarea.clear();
            if let Some(parsed) = panels::mcp::parse_mcp_subcommand(&description) {
                return match parsed {
                    Ok(subcommand) => self.execute_mcp_subcommand(subcommand),
                    Err(e) => {
                        self.push_line(&Style::new().fg(TN_RED).render(&format!("  {e}")));
                        None
                    }
                };
            }
            if description.is_empty() {
                self.open_mcp_panel();
                return None;
            }
            let dir = mcp_dir();
            match panels::mcp::scaffold_mcp_project(&description, &dir) {
                Ok(dev) => {
                    self.agent_dev = None;
                    self.skill_dev = None;
                    self.okf_dev = None;
                    self.mcp_dev = Some(dev.clone());
                    self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                        "  ◆ scaffolded MCP asset → {}",
                        dev.path.display()
                    )));
                    self.push_line(&gutter(
                        TN_CYAN,
                        &format!(
                            "◆ mcp dev: {} ({}) · Esc or /mcp off returns to normal mode",
                            dev.name, dev.rel
                        ),
                    ));
                    self.relayout();
                    return None;
                }
                Err(e) => {
                    self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  /mcp scaffold failed: {e}")),
                    );
                    return None;
                }
            }
        }
        // `/skill` — select a local skill asset and enter local multi-turn
        // development mode; `/skill <description>` drafts a local skill asset.
        if let Some(rest) = slash_tail(trimmed, "/skill") {
            let description = rest.trim().to_string();
            self.textarea.clear();
            if let Some(parsed) = panels::skill::parse_skill_subcommand(&description) {
                return match parsed {
                    Ok(subcommand) => self.execute_skill_subcommand(subcommand),
                    Err(e) => {
                        self.push_line(&Style::new().fg(TN_RED).render(&format!("  {e}")));
                        None
                    }
                };
            }
            if description.is_empty() {
                self.open_skill_panel();
                return None;
            }
            let dir = skill_dir();
            match panels::skill::scaffold_skill_asset(&description, &dir) {
                Ok(dev) => {
                    self.agent_dev = None;
                    self.mcp_dev = None;
                    self.okf_dev = None;
                    self.skill_dev = Some(dev.clone());
                    self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                        "  ✦ scaffolded skill asset → {}",
                        dev.path
                            .parent()
                            .unwrap_or_else(|| std::path::Path::new("."))
                            .display()
                    )));
                    self.push_line(&gutter(
                        TN_CYAN,
                        &format!(
                            "✦ skill dev: {} ({}) · Esc or /skill off returns to normal mode",
                            dev.name, dev.rel
                        ),
                    ));
                    self.relayout();
                    return None;
                }
                Err(e) => {
                    self.push_line(
                        &Style::new()
                            .fg(TN_RED)
                            .render(&format!("  /skill scaffold failed: {e}")),
                    );
                    return None;
                }
            }
        }
        // Slash commands run inline in any state.
        match trimmed {
            "/exit" => return Some(cmd::quit()),
            "/fork" => {
                // Branch a new session from the current one: copy the persisted
                // SessionData under a fresh id, then swap the active session to it
                // (Msg::Forked). The original id keeps its state, so it stays
                // resumable — the two diverge from here. Idle-only (guarded above),
                // so the last turn is already flushed to the store.
                self.textarea.clear();
                let store = self.store.clone();
                let src = self.session_id.clone();
                let dst = new_session_id();
                return Some(cmd::cmd(move || async move {
                    match store.load(&src).await {
                        Ok(Some(mut data)) => {
                            data.id = dst.clone();
                            match store.save(&data).await {
                                Ok(()) => Msg::Forked(Ok(dst)),
                                Err(e) => Msg::Forked(Err(format!("could not save the fork: {e}"))),
                            }
                        }
                        Ok(None) => Msg::Forked(Err(
                            "nothing to fork yet — start a conversation first".into(),
                        )),
                        Err(e) => Msg::Forked(Err(format!("could not read the session: {e}"))),
                    }
                }));
            }
            "/clear" => {
                self.messages.clear();
                self.plan.clear();
                self.runtime.clear_turn_entities();
                self.queue.clear();
                self.completed = 0;
                self.textarea.clear();
                // A fresh conversation can't deliver the old review's report
                // or sleep consolidation, and must not inherit a staged `/ctx`
                // window or stale hits.
                self.review_pending = false;
                self.sleep_pending = false;
                self.restore_autonomy();
                self.pending_ctx = None;
                self.ctx_hits.clear();
                self.agent_dev = None;
                self.pending_flow_subcommand = None;
                self.pending_agent_subcommand = None;
                self.mcp_dev = None;
                self.pending_mcp_subcommand = None;
                self.skill_dev = None;
                self.pending_skill_subcommand = None;
                self.okf_picker = None;
                self.pending_okf_subcommand = None;
                self.okf_dev = None;
                self.asset_list = None;
                self.runtime_activity = None;
                self.kb = None;
                // Actually reset the conversation, not just the screen: swap in a
                // fresh session (new id, no history, no carried compact summary)
                // and zero the token/ctx counters. /clear is idle-only (guarded
                // above), so replacing the session is safe. Set the id first
                // (rebuild_session keys off it) and revert it if the rebuild fails
                // so id and session never desync.
                let prev_id = std::mem::replace(&mut self.session_id, new_session_id());
                let model = self.model.clone();
                match self.rebuild_session(model.as_deref()) {
                    Ok((s, _)) => {
                        self.replace_session(s);
                        self.compact_summary = None;
                        self.output_tokens = 0;
                        self.last_prompt_tokens = 0;
                        self.ctx_warned_tier = 0; // fresh window: re-arm fill warnings
                    }
                    Err(_) => self.session_id = prev_id,
                }
                self.relayout();
                self.rebuild_viewport();
                return None;
            }
            "/init" => {
                // Agent-driven: analyze the workspace and write AGENTS.md (auto-loaded
                // by the core, like CLAUDE.md). Guarded idle by IDLE_ONLY above.
                self.textarea.clear();
                self.messages.push(user_bubble(
                    "/init — generate AGENTS.md",
                    self.viewport_content_width(),
                ));
                self.rebuild_viewport();
                return self.start_stream(
                    "Analyze this codebase and create (or update) an AGENTS.md file at the \
                     project root. Include: a concise project overview, the exact build / test / \
                     lint / run commands, the high-level architecture and key directories, and \
                     the conventions an AI coding agent should follow. Base everything on what's \
                     actually in the workspace, and write the file with your file-writing tool."
                        .to_string(),
                );
            }
            "/compact" => {
                self.textarea.clear();
                if self.state != State::Idle {
                    self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  finish the current turn before compacting"),
                    );
                    return None;
                }
                let history = self.session.history();
                if history.is_empty() {
                    self.push_line(&Style::new().fg(TN_GRAY).render("  nothing to compact yet"));
                    return None;
                }
                self.compacting = Some(Instant::now()); // progress bar + input lock
                let agent = self.agent.clone();
                let workspace = self.cwd.clone();
                // Re-compacting must subsume the PRIOR summary — it lives in the
                // system prompt, not in `history`, so without this everything
                // before the last /compact would be dropped from the new summary.
                let prompt = match &self.compact_summary {
                    Some(prev) => format!(
                        "An earlier part of this conversation was already condensed into this \
                         summary:\n\n{prev}\n\nProduce a SINGLE updated summary that fully \
                         incorporates the summary above AND the conversation history below, so a \
                         fresh session can continue seamlessly: the goal, key decisions, \
                         files/commands touched, current state, and the immediate next steps. Be \
                         thorough but compact."
                    ),
                    None => "Summarize this conversation so a fresh session can continue \
                         seamlessly: the goal, key decisions, files/commands touched, current \
                         state, and the immediate next steps. Be thorough but compact."
                        .to_string(),
                };
                return Some(cmd::cmd(move || async move {
                    let conf = a3s_code_core::hitl::ConfirmationPolicy::enabled()
                        .with_timeout(BACKGROUND_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
                    let mut summary = String::new();
                    if let Ok(sess) = agent.session(workspace, Some(tui_session_options(conf))) {
                        if let Ok((mut rx, _j)) = sess.stream(&prompt, Some(&history)).await {
                            while let Some(ev) = rx.recv().await {
                                match ev {
                                    AgentEvent::TextDelta { text } => summary.push_str(&text),
                                    AgentEvent::End { text, .. } => {
                                        if summary.trim().is_empty() {
                                            summary = text;
                                        }
                                        break;
                                    }
                                    _ => {}
                                }
                            }
                        }
                    }
                    Msg::Compacted(summary)
                }));
            }
            "/help" => {
                self.textarea.clear();
                self.help_open = true;
                self.help_scroll = 0;
                return None;
            }
            "/auto" => {
                self.mode = Mode::Auto;
                self.textarea.clear();
                self.rebuild_viewport();
                return None;
            }
            "/config" => {
                self.textarea.clear();
                // Resolve the config; if there's none, generate a starter so the
                // user always lands in the editor with something to edit.
                let path = find_config().map(std::path::PathBuf::from).or_else(|| {
                    let p = default_config_path()?;
                    let _ = write_template_config(&p);
                    Some(p)
                });
                match path {
                    Some(p) => self.open_config_in_ide(&p),
                    None => self.push_line(
                        &Style::new()
                            .fg(TN_YELLOW)
                            .render("  could not locate a home directory for ~/.a3s/config.acl"),
                    ),
                }
                return None;
            }
            "/model" => {
                self.textarea.clear();
                self.open_model_menu();
                return None;
            }
            "/effort" => {
                self.textarea.clear();
                self.effort_panel = Some(self.effort);
                return None;
            }
            "/top" => {
                self.textarea.clear();
                self.top = Some(Vec::new());
                self.top_history.clear();
                self.top_scroll = 0;
                self.top_sel = 0;
                self.top_focus = None;
                return Some(cmd::cmd(|| async { Msg::TopData(fetch_top().await) }));
            }
            "/ide" => {
                self.textarea.clear();
                let entries = ide_children(std::path::Path::new(&self.cwd), 0);
                self.ide = Some(Ide::browse(entries, "workspace"));
                return None;
            }
            "/plugin" => {
                self.textarea.clear();
                if self.skills.is_empty() {
                    self.push_line(&Style::new().fg(TN_GRAY).render(
                        "  no skills/plugins found (~/.claude/skills, ~/.codex/skills, ~/.claude/plugins)",
                    ));
                } else {
                    self.plugins_panel = Some(0);
                }
                return None;
            }
            "/theme" => {
                self.textarea.clear();
                let cur = SYNTAX_THEME.load(std::sync::atomic::Ordering::Relaxed);
                self.theme_panel = Some(cur.min(THEMES.len() - 1));
                return None;
            }
            "/output" => {
                self.textarea.clear();
                match self.format_tool_log() {
                    Some(content) => self.open_readonly_in_ide("tool-calls.txt", &content),
                    None => self.push_line(
                        &Style::new()
                            .fg(TN_GRAY)
                            .render("  no tool calls yet this session"),
                    ),
                }
                return None;
            }
            "/reload" => {
                self.textarea.clear();
                // Hot-reload: re-discover skill dirs, refresh the UI catalog,
                // and rebuild the session so the core skill registry and
                // next Claude/system prompt see the same skills.
                let dirs = agent_skill_dirs(&self.cwd);
                self.skills = load_skills(&dirs);
                self.skill_count = count_skill_files(&dirs);
                let model = self.model.clone();
                match self.rebuild_session(model.as_deref()) {
                    Ok((session, _)) => {
                        self.replace_session(session);
                        self.push_line(&Style::new().fg(TN_GREEN).render(&format!(
                            "  ↻ reloaded — {} skills available",
                            self.skills.len()
                        )));
                    }
                    Err(error) => {
                        self.push_line(
                            &Style::new()
                                .fg(TN_RED)
                                .render(&format!("  reload failed: {error}")),
                        );
                    }
                }
                return None;
            }
            "/update" => {
                self.textarea.clear();
                self.updating = Some(Instant::now()); // "checking…" + input lock
                self.relayout();
                return Some(cmd::cmd(|| async {
                    // Quick version check only; the actual upgrade runs in the
                    // shell after the TUI exits (run()), so brew's/curl's own
                    // progress shows and the restart picks up the new binary.
                    let latest = tokio::task::spawn_blocking(crate::update::fetch_latest)
                        .await
                        .ok()
                        .flatten();
                    Msg::UpdatePlan(latest)
                }));
            }
            "/memory" => {
                self.textarea.clear();
                // Open immediately ("loading…"); load the file snapshot off the
                // UI thread, with live session memory as a fallback.
                let dir = memory_dir();
                self.memory = Some(MemPanel {
                    entries: Vec::new(),
                    sel: 0,
                    details: std::collections::BTreeMap::new(),
                    graph: MemoryGraph::default(),
                    loaded_from_session: false,
                    detail: memutil::MemDetail::default(),
                    detail_scroll: 0,
                    dir: dir.clone(),
                    note: "loading…".into(),
                });
                return Some(self.load_memory_panel(dir));
            }
            _ => {}
        }

        self.history.push(trimmed.to_string());
        self.history_pos = None;
        // Show the user message in a background bubble, then run now (if idle)
        // or queue it (if the agent is busy).
        self.messages
            .push(user_bubble(trimmed, self.viewport_content_width()));
        self.textarea.clear();
        // One-shot `/ctx <n>` context: attach the staged transcript to THIS
        // genuine typed message only (never a `/loop` "Continue." re-entry),
        // invisibly — the display bubble above stays clean. Travels with the
        // message whether it runs now or is queued.
        let loop_cont = std::mem::take(&mut self.loop_continuation);
        let prompt = match (loop_cont, self.pending_ctx.take()) {
            (false, Some(c)) => format!("{c}\n\n{trimmed}"),
            _ => trimmed.to_string(),
        };
        let (prompt, display) = match &self.agent_dev {
            Some(dev) => (
                panels::agent::agent_dev_prompt(dev, &prompt),
                format!("◇ {}: {}", dev.name, truncate(trimmed, 60)),
            ),
            None => match &self.mcp_dev {
                Some(dev) => (
                    panels::mcp::mcp_dev_prompt(dev, &prompt),
                    format!("◆ {}: {}", dev.name, truncate(trimmed, 60)),
                ),
                None => match &self.skill_dev {
                    Some(dev) => (
                        panels::skill::skill_dev_prompt(dev, &prompt),
                        format!("✦ {}: {}", dev.name, truncate(trimmed, 60)),
                    ),
                    None => match &self.okf_dev {
                        Some(dev) => (
                            panels::okf::okf_dev_prompt(dev, &prompt),
                            format!("⌁ {}: {}", dev.name, truncate(trimmed, 60)),
                        ),
                        None => (prompt, trimmed.to_string()),
                    },
                },
            },
        };
        if self.state == State::Idle {
            self.start_stream_inner(prompt, display, true, true, false)
        } else {
            self.seq += 1;
            self.queue.push(Queued {
                prio: 1,
                seq: self.seq,
                text: prompt,
                display,
                runtime_expectation: None,
                deep_research: None,
            });
            self.push_line(&Style::new().fg(TN_GRAY).render("    ⋯ queued"));
            self.relayout();
            None
        }
    }

    /// Begin streaming a prompt (the user message must already be on screen).
    /// Grab a clipboard image, preview it inline, and queue it for the next send.
    fn paste_clipboard_image(&mut self) {
        let dest =
            std::env::temp_dir().join(format!("a3s-paste-{}.png", self.pending_images.len()));
        if !clipboard_image_to(&dest) {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  no image in clipboard (Ctrl+V pastes a copied/screenshot image)"),
            );
            return;
        }
        let Ok(bytes) = std::fs::read(&dest) else {
            return;
        };
        self.messages.push(gutter(
            ACCENT,
            "📎 pasted image (sends with your next message):",
        ));
        // Render narrower than the viewport so half-block rows never wrap (a
        // wrapped row splits the picture and garbles it). Indent to align.
        let cols = self.transcript_markdown_width().min(72);
        if let Some(lines) = render_image_file(&dest, cols, 16) {
            for l in lines {
                self.messages.push(format!("{}{l}", " ".repeat(PAD)));
            }
        }
        self.rebuild_viewport();
        self.pending_images
            .push(a3s_code_core::llm::Attachment::png(bytes));
    }

    fn start_stream(&mut self, prompt: String) -> Option<Cmd<Msg>> {
        self.start_stream_inner(prompt.clone(), prompt, true, true, false)
    }

    fn start_ultracode_synthesis(
        &mut self,
        prompt: String,
        display_task: String,
    ) -> Option<Cmd<Msg>> {
        self.ultracode_synthesis_used = true;
        self.push_line(&Style::new().fg(TN_GRAY).render("  ⇉ synthesizing results…"));
        self.start_stream_inner(prompt, display_task, false, false, true)
    }

    fn start_deep_research_workflow(
        &mut self,
        query: String,
        _os_runtime: bool,
        runtime_expectation: Option<RuntimeExpectation>,
    ) -> Option<Cmd<Msg>> {
        let os_runtime = false;
        self.streaming.clear();
        self.deferred_tool_blocks.clear();
        self.defer_tool_blocks_until_stream_finalized = false;
        self.got_delta = false;
        self.turn_text.clear();
        self.turn_had_agent_activity = false;
        self.turn_text_after_activity = false;
        let loop_layers = deep_research_loop_layers(&query, os_runtime);
        self.deep_research_loop = Some(DeepResearchLoop {
            query: query.clone(),
            total_layers: loop_layers.max(1),
            os_runtime,
        });
        self.deep_research_report_repair_used = false;
        self.deep_research_workflow_output = None;
        self.deep_research_workflow_metadata = None;
        self.deep_research_report_ready = false;
        self.pending_deep_research_report_repair_prompt = None;
        self.pending_deep_research_report_view = None;
        self.deep_research_report_tool_gate.set_report_only(false);
        if let Some(expectation) = runtime_expectation {
            self.runtime_expectation = Some(expectation);
        }
        self.ultracode_synthesis_inflight = false;
        self.ultracode_synthesis_used = false;
        self.last_paint = None;
        self.viewport.set_auto_scroll(true);
        self.plan.clear();
        self.runtime.clear_turn_entities();
        let display_task = format!("🔬 {query}");
        self.runtime.set_subagent_task(display_task.clone());
        self.running_task = Some(display_task);
        self.state = State::Streaming;
        self.relayout();
        self.stream_started = Some(Instant::now());
        self.spinner.start();
        self.push_line(
            &Style::new()
                .fg(TN_GRAY)
                .render("  ⇉ gathering evidence with bounded recursive DynamicWorkflowRuntime…"),
        );
        self.rebuild_viewport();

        let budget = deep_research_budget_for_effort_index(self.effort, self.context_limit);
        let args = deep_research_workflow_args_for_budget(&query, os_runtime, budget);
        let (progress_rx, workflow_join) = self
            .session
            .tool_with_events("dynamic_workflow", args.clone());
        let progress_rx = Arc::new(Mutex::new(progress_rx));
        self.rx = Some(progress_rx.clone());
        self.stream_join = None;
        self.host_tool_abort = Some(workflow_join.abort_handle());
        self.host_progress_inflight = true;
        self.interrupting = false;
        let workflow_abort = workflow_join.abort_handle();
        let timeout_ms = deep_research_workflow_host_timeout_ms(&args);
        Some(cmd::batch(vec![
            cmd::cmd(move || async move {
                let result = match tokio::time::timeout(
                    std::time::Duration::from_millis(timeout_ms),
                    workflow_join,
                )
                .await
                {
                    Ok(Ok(result)) => result.map_err(|err| err.to_string()),
                    Ok(Err(err)) => Err(err.to_string()),
                    Err(_) => {
                        workflow_abort.abort();
                        Err(format!(
                            "dynamic_workflow timed out after {timeout_ms} ms while gathering DeepResearch evidence"
                        ))
                    }
                };
                Msg::DeepResearchWorkflowCompleted {
                    query,
                    os_runtime,
                    args,
                    result,
                }
            }),
            pump(progress_rx),
            spinner_tick(),
        ]))
    }

    fn on_deep_research_workflow_completed(
        &mut self,
        query: String,
        os_runtime: bool,
        args: serde_json::Value,
        result: Result<ToolCallResult, String>,
    ) -> Option<Cmd<Msg>> {
        self.host_tool_abort = None;
        if self.state != State::Streaming {
            return None;
        }
        self.host_progress_inflight = false;
        self.rx = None;

        let (output, exit_code, metadata) = match result {
            Ok(result) => (result.output, result.exit_code, result.metadata),
            Err(error) => (error, 1, None),
        };
        self.deep_research_workflow_output = Some(output.clone());
        self.deep_research_workflow_metadata = metadata.clone();
        let tool_id = "dynamic_workflow".to_string();
        self.runtime
            .start_tool(tool_id.clone(), "dynamic_workflow".to_string());
        self.runtime
            .push_tool_input(&serde_json::to_string(&args).unwrap_or_default());
        let display_output = deep_research_tool_card_output(&output);
        let completed = self.runtime.end_tool(
            &tool_id,
            "dynamic_workflow".to_string(),
            display_output.clone(),
            exit_code,
        );
        self.push_line(&render_tool_end(
            "dynamic_workflow",
            exit_code,
            &display_output,
            metadata.as_ref(),
            completed.args.as_ref(),
            self.viewport_content_width(),
        ));
        self.record_runtime_tool_evidence("dynamic_workflow");
        if metadata
            .as_ref()
            .is_some_and(|value| json_contains_tool_evidence(value, "runtime"))
        {
            self.record_runtime_tool_evidence("runtime");
        }
        if metadata
            .as_ref()
            .is_some_and(|value| json_contains_tool_evidence(value, "parallel_task"))
        {
            self.record_runtime_parallel_evidence();
        }
        self.backfill_parallel_subagents_from_workflow_metadata(metadata.as_ref());
        self.capture_workflow("dynamic_workflow", completed.args.as_ref());
        if let Some(spec) = self.find_remote_view_spec(&output) {
            self.remember_remote_view(spec);
        }

        let prompt = if exit_code == 0 {
            deep_research_synthesis_prompt(&query, os_runtime, &output, metadata.as_ref())
        } else {
            self.push_line(
                &Style::new()
                    .fg(TN_YELLOW)
                    .render("  ⚠ dynamic workflow failed; starting recovery synthesis…"),
            );
            deep_research_recovery_prompt(&query, os_runtime, &output, metadata.as_ref())
        };
        self.deep_research_report_tool_gate.set_report_only(true);
        self.start_stream_inner_with_runtime(
            prompt,
            format!("🔬 synthesize {query}"),
            false,
            false,
            false,
            None,
        )
    }

    fn on_deep_research_synthesis_timed_out(&mut self, token: u64) -> Option<Cmd<Msg>> {
        if token != self.deep_research_stream_timeout_token
            || self.state != State::Streaming
            || self.host_progress_inflight
            || self.deep_research_loop.is_none()
        {
            return None;
        }

        let repair_phase = self.deep_research_report_repair_used;
        let timeout_ms = if repair_phase {
            DEEP_RESEARCH_REPAIR_TIMEOUT_MS
        } else {
            DEEP_RESEARCH_SYNTHESIS_TIMEOUT_MS
        };
        let phase = if repair_phase { "repair" } else { "synthesis" };
        let status = format!("DeepResearch {phase} model call timed out after {timeout_ms} ms.");

        if let Some(join) = self.stream_join.take() {
            join.abort();
        }
        self.rx = None;
        let streamed_text = self.turn_text.clone();
        self.finalize_streaming();
        self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
            "  ⚠ {status} Writing a fallback draft from gathered workflow evidence; RemoteUI will not open automatically."
        )));

        let workspace = PathBuf::from(&self.cwd);
        if research_report_view_spec(&streamed_text, &workspace).is_some() {
            self.push_line(&Style::new().fg(TN_YELLOW).render(
                "  ⚠ A report marker was present, but DeepResearch timed out before completion; not opening RemoteUI automatically.",
            ));
        } else {
            let query = self
                .deep_research_loop
                .as_ref()
                .map(|state| state.query.clone());
            let workflow_output = self
                .deep_research_workflow_output
                .clone()
                .unwrap_or_default();
            match query {
                Some(query) => match materialize_deep_research_fallback_draft(
                    &workspace,
                    &query,
                    &status,
                    &workflow_output,
                ) {
                    Ok(artifacts) => {
                        self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
                            "  ⚠ DeepResearch fallback draft written at {}",
                            artifacts.html.display()
                        )));
                    }
                    Err(error) => self.push_line(&Style::new().fg(TN_RED).render(&format!(
                        "  error: DeepResearch fallback draft failed: {error}"
                    ))),
                },
                None => self.push_line(&Style::new().fg(TN_RED).render(
                    "  error: DeepResearch timed out but the original query is unavailable",
                )),
            }
        }

        self.loop_remaining = 0;
        self.deep_research_report_repair_used = true;
        self.complete_turn()
    }

    fn backfill_parallel_subagents_from_workflow_metadata(
        &mut self,
        metadata: Option<&serde_json::Value>,
    ) {
        let backfills = metadata
            .map(workflow_parallel_subagent_backfills)
            .unwrap_or_default();
        if backfills.is_empty() {
            return;
        }
        let now = Instant::now();
        for backfill in backfills {
            self.runtime.start_subagent(
                backfill.task_id.clone(),
                backfill.agent.clone(),
                backfill.description,
                now,
            );
            self.runtime
                .end_subagent(backfill.task_id, backfill.agent, backfill.success, now);
        }
        self.relayout();
    }

    fn start_stream_inner(
        &mut self,
        prompt: String,
        display_task: String,
        clear_turn_artifacts: bool,
        include_attachments: bool,
        synthesis: bool,
    ) -> Option<Cmd<Msg>> {
        self.start_stream_inner_with_runtime(
            prompt,
            display_task,
            clear_turn_artifacts,
            include_attachments,
            synthesis,
            None,
        )
    }

    fn start_stream_inner_with_runtime(
        &mut self,
        prompt: String,
        display_task: String,
        clear_turn_artifacts: bool,
        include_attachments: bool,
        synthesis: bool,
        runtime_expectation: Option<RuntimeExpectation>,
    ) -> Option<Cmd<Msg>> {
        self.streaming.clear();
        self.deferred_tool_blocks.clear();
        self.defer_tool_blocks_until_stream_finalized = false;
        self.got_delta = false; // track if this turn streamed any text deltas
        self.turn_text.clear();
        self.turn_had_agent_activity = false;
        self.turn_text_after_activity = false;
        if let Some(expectation) = runtime_expectation {
            self.runtime_expectation = Some(expectation);
        }
        self.ultracode_synthesis_inflight = synthesis;
        if !synthesis {
            self.ultracode_synthesis_used = false;
        }
        self.last_paint = None; // first delta of the turn paints immediately
        self.viewport.set_auto_scroll(true); // sending a message jumps to latest
        if clear_turn_artifacts {
            self.plan.clear(); // fresh plan per user turn; planning events refill it
                               // Keep completed agents visible until the next user turn; a fresh
                               // user turn starts a fresh runtime-entity projection.
            self.runtime.clear_turn_entities();
            self.runtime.set_subagent_task(display_task.clone());
        } else {
            self.runtime.clear_live_tools();
        }
        self.running_task = Some(display_task);
        self.state = State::Streaming;
        self.relayout();
        self.stream_started = Some(Instant::now());
        self.spinner.start();
        self.rebuild_viewport();
        let session = self.session.clone();
        let atts = if include_attachments {
            std::mem::take(&mut self.pending_images)
        } else {
            Vec::new()
        };
        // Keep the agent aligned with the standing goal (display stays clean).
        let prompt = match &self.goal {
            Some(g) => format!("[Ongoing goal: {g}]\n\n{prompt}"),
            None => prompt,
        };
        // (A `/ctx <n>` staged transcript window is attached upstream, only to a
        // genuine typed user message — see on_submit — never to a `/loop`,
        // asset review, `?`, or synthesis continuation.)
        // ultracode no longer rewrites the user turn. Whether a turn plans and
        // fans out is decided by the core's message-gated planning
        // (PlanningMode::Auto) plus the `parallel_task` tool description — not an
        // unconditional per-turn imperative, which made even "hi" trigger a plan
        // and workspace exploration.
        Some(cmd::batch(vec![
            cmd::cmd(move || async move {
                let res = if atts.is_empty() {
                    session.stream(prompt.as_str(), None).await
                } else {
                    session
                        .stream_with_attachments(prompt.as_str(), &atts, None)
                        .await
                };
                match res {
                    Ok((rx, join)) => Msg::StreamStarted(Arc::new(Mutex::new(rx)), join),
                    Err(e) => Msg::StreamError(e.to_string()),
                }
            }),
            spinner_tick(),
        ]))
    }

    /// Pop the next queued message and start streaming it, if any.
    fn drain_queue(&mut self) -> Option<Cmd<Msg>> {
        let next = self.queue.pop()?;
        if let Some((query, os_runtime)) = next.deep_research {
            return self.start_deep_research_workflow(query, os_runtime, next.runtime_expectation);
        }
        self.start_stream_inner_with_runtime(
            next.text,
            next.display,
            true,
            true,
            false,
            next.runtime_expectation,
        )
    }

    /// Shared turn-completion: count the turn, run any ultracode synthesis, go
    /// idle, then either continue a `/loop` or drain the next queued message.
    /// Called from BOTH the normal `AgentEvent::End` arm (the happy path, which
    /// returns without re-pumping so `StreamEnded` never fires) and the
    /// `StreamEnded` channel-closed arm — previously this lived only in
    /// `StreamEnded`, so on success the queue never drained and `/loop` ran once.
    fn complete_turn(&mut self) -> Option<Cmd<Msg>> {
        if self.state == State::Streaming {
            self.completed += 1;
        }
        self.warn_missing_runtime_evidence();
        let synthesis = self.prepare_ultracode_synthesis();
        self.finish();
        if let Some((prompt, display_task)) = synthesis {
            return self.start_ultracode_synthesis(prompt, display_task);
        }
        if self.loop_remaining > 0 && self.queue.is_empty() {
            if let Some(prompt) = self.pending_deep_research_report_repair_prompt.take() {
                self.loop_remaining -= 1;
                let n = self.loop_remaining;
                self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                    "  ↻ deep research report repair ({n} left · Esc to stop)"
                )));
                self.loop_continuation = true;
                return Some(cmd::msg(Msg::Submit(prompt)));
            }
        }
        // Required runtime evidence is a deliverable, not just a warning. In
        // autonomous runs, spend the next loop turn on a targeted correction
        // before falling back to the generic "Continue" prompt.
        if self.loop_remaining > 0 && self.queue.is_empty() {
            if let Some(prompt) = self
                .runtime_expectation
                .as_ref()
                .and_then(RuntimeExpectation::corrective_prompt)
            {
                self.loop_remaining -= 1;
                let n = self.loop_remaining;
                self.push_line(&Style::new().fg(TN_GRAY).render(&format!(
                    "  ↻ runtime evidence retry ({n} left · Esc to stop)"
                )));
                self.loop_continuation = true;
                return Some(cmd::msg(Msg::Submit(prompt)));
            }
        }
        // /loop: auto-continue until the agent says DONE, the cap is hit, or Esc.
        // Queued user messages take priority.
        if self.loop_remaining > 0 && self.queue.is_empty() {
            self.loop_remaining -= 1;
            let n = self.loop_remaining;
            let (label, prompt) = if let Some(deep_research) = &self.deep_research_loop {
                let layer = deep_research.total_layers.saturating_sub(n);
                (
                    "deep research verification",
                    deep_research.verification_prompt(layer.max(1)),
                )
            } else {
                (
                    "loop",
                    "Continue. If the task is fully complete, reply DONE and stop.".to_string(),
                )
            };
            self.push_line(
                &Style::new()
                    .fg(TN_GRAY)
                    .render(&format!("  ↻ {label} ({n} left · Esc to stop)")),
            );
            // Mark the continuation as machine-driven so on_submit doesn't
            // attach a staged `/ctx` window to it.
            self.loop_continuation = true;
            return Some(cmd::msg(Msg::Submit(prompt)));
        }
        // The loop is drained (or was never armed): an autonomous run that
        // auto-switched to auto mode is over — restore the user's mode.
        if self.loop_remaining == 0 {
            self.open_pending_deep_research_report_view();
            self.restore_autonomy();
        }
        // Run the next queued message (submitted while busy), if any.
        self.drain_queue()
    }

    fn resume_after_pending_confirmation(&self) -> Cmd<Msg> {
        resume_after_pending_confirmation_cmd(self.rx.clone())
    }

    /// An autonomous directive run is starting (/sleep, asset reviews,
    /// asset run/deploy, /flow drafts, /loop): switch to auto-approve so tool
    /// prompts can't stall it, and arm the loop budget that re-prompts until
    /// the deliverable lands. The prior mode is restored when the run ends
    /// (loop drained, interrupt, error, or /clear). A user already in auto
    /// mode keeps it — nothing is remembered or restored.
    fn engage_autonomy(&mut self, budget: usize) {
        self.loop_remaining = self.loop_remaining.max(budget);
        if self.mode != Mode::Auto {
            self.autonomy_restore = Some(self.mode);
            self.mode = Mode::Auto;
            self.push_line(&Style::new().fg(TN_GRAY).render(
                "  ⏵⏵ auto mode engaged for this task — restores when it completes (Esc stops)",
            ));
        }
    }

    fn engage_single_turn_autonomy(&mut self) {
        if self.mode != Mode::Auto {
            self.autonomy_restore = Some(self.mode);
            self.mode = Mode::Auto;
            self.push_line(&Style::new().fg(TN_GRAY).render(
                "  ⏵⏵ auto mode engaged for this task — restores when it completes (Esc stops)",
            ));
        }
    }

    fn record_runtime_tool_evidence(&mut self, name: &str) {
        if let Some(expectation) = &mut self.runtime_expectation {
            expectation.record_tool(name);
        }
    }

    fn record_runtime_parallel_evidence(&mut self) {
        if let Some(expectation) = &mut self.runtime_expectation {
            expectation.record_parallel_work();
        }
    }

    fn record_runtime_view_evidence(&mut self) {
        if let Some(expectation) = &mut self.runtime_expectation {
            expectation.record_remote_view();
        }
    }

    fn warn_missing_runtime_evidence(&mut self) {
        let warning = self
            .runtime_expectation
            .as_mut()
            .and_then(RuntimeExpectation::missing_warning);
        if let Some(warning) = warning {
            self.push_line(&Style::new().fg(TN_YELLOW).render(&warning));
        }
    }

    /// Restore the pre-autonomy mode (no-op when nothing was auto-switched).
    fn restore_autonomy(&mut self) {
        self.runtime_expectation = None;
        self.deep_research_loop = None;
        self.deep_research_report_repair_used = false;
        self.deep_research_workflow_output = None;
        self.deep_research_workflow_metadata = None;
        self.deep_research_report_ready = false;
        self.pending_deep_research_report_repair_prompt = None;
        self.pending_deep_research_report_view = None;
        self.deep_research_report_tool_gate.set_report_only(false);
        if let Some(prev) = self.autonomy_restore.take() {
            self.mode = prev;
            self.push_line(
                &Style::new()
                    .fg(TN_GRAY)
                    .render("  ⏵ autonomous task ended — auto mode restored to your previous mode"),
            );
        }
    }

    fn on_agent_event(&mut self, event: AgentEvent) -> Option<Cmd<Msg>> {
        // After an interrupt, rx is cleared — ignore any late buffered events.
        self.rx.as_ref()?;
        match event {
            AgentEvent::TextDelta { text } => {
                self.mark_assistant_text(&text);
                self.got_delta = true;
                self.turn_text.push_str(&text);
                if self.deep_research_loop.is_some()
                    && self.deep_research_report_tool_gate.report_only()
                {
                    return None;
                }
                self.streaming.push(&text);
                self.update_viewport_with_stream();
            }
            AgentEvent::ReasoningDelta { text } => {
                self.thinking.push_str(&text);
                self.update_viewport_with_stream();
            }
            AgentEvent::ToolStart { id, name } => {
                // Usually finalize assistant text before a tool. If the stream
                // is in the middle of an inline Markdown construct, keep it live
                // and defer completed tool blocks until that text finalizes; this
                // prevents chunks like "`query" / tool / "rest`" becoming three
                // separate gutter messages.
                self.mark_agent_activity();
                if self.should_defer_tool_for_streaming_markdown() {
                    self.defer_tool_blocks_until_stream_finalized = true;
                } else {
                    self.finalize_streaming();
                }
                self.runtime.start_tool(id, name);
                self.update_viewport_with_stream();
            }
            AgentEvent::ToolInputDelta { delta } => {
                self.runtime.push_tool_input(&delta);
            }
            AgentEvent::ToolOutputDelta { id, name, delta } => {
                self.runtime.push_tool_output(id, name, &delta);
                if let Some(output) = self
                    .runtime
                    .live_tool()
                    .map(|tool| tool.output().to_string())
                {
                    if let Some(spec) = self.find_remote_view_spec(&output) {
                        self.remember_remote_view(spec);
                    }
                }
                self.update_viewport_with_stream();
            }
            AgentEvent::ToolEnd {
                id,
                name,
                output,
                exit_code,
                metadata,
                ..
            } => {
                self.mark_agent_activity();
                let completed = self
                    .runtime
                    .end_tool(&id, name.clone(), output.clone(), exit_code);
                let rendered_tool = render_tool_end(
                    &name,
                    exit_code,
                    &output,
                    metadata.as_ref(),
                    completed.args.as_ref(),
                    self.viewport_content_width(),
                );
                if self.defer_tool_blocks_until_stream_finalized {
                    self.deferred_tool_blocks.push(rendered_tool);
                    self.update_viewport_with_stream();
                } else {
                    self.push_line(&rendered_tool);
                }
                self.record_runtime_tool_evidence(&name);
                self.capture_workflow(&name, completed.args.as_ref());
                if let Some(spec) = self.find_remote_view_spec(&output) {
                    self.remember_remote_view(spec);
                }
            }
            // Parallel/child task lifecycle (parallel_task, task) — show each
            // sub-task starting, its progress, and how it finished.
            AgentEvent::SubagentStart {
                task_id,
                agent,
                description,
                started_ms,
                ..
            } => {
                self.mark_agent_activity();
                self.finalize_streaming();
                self.record_runtime_parallel_evidence();
                // Track it in the live bottom panel instead of a transcript line.
                self.runtime.start_subagent(
                    task_id,
                    agent,
                    description,
                    instant_from_epoch_ms(started_ms),
                );
                self.relayout();
            }
            AgentEvent::SubagentProgress {
                task_id, metadata, ..
            } => {
                self.mark_agent_activity();
                // Per-child OUTPUT tokens for the panel's `↓`. Each child turn-end
                // reports that turn's completion_tokens once, so SUM them across
                // turns (tool-event progress carries no usage, so it won't add).
                // The old code took max(total_tokens), i.e. the largest single
                // turn's prompt+completion ≈ the child's context size, not output.
                let toks = metadata
                    .get("completion_tokens")
                    .or_else(|| metadata.pointer("/usage/completion_tokens"))
                    .and_then(|v| v.as_u64());
                if let Some(t) = toks {
                    self.runtime.add_subagent_tokens(&task_id, t);
                }
            }
            AgentEvent::SubagentEnd {
                task_id,
                agent,
                output,
                success,
                finished_ms,
                ..
            } => {
                self.mark_agent_activity();
                self.runtime.end_subagent(
                    task_id,
                    agent.clone(),
                    success,
                    instant_from_epoch_ms(finished_ms),
                );
                self.relayout();
                let (mark, color) = if success {
                    ("✓", TN_GREEN)
                } else {
                    ("✗", TN_RED)
                };
                let snippet = output.lines().next().unwrap_or("").trim();
                let snippet = truncate(snippet, self.width.saturating_sub(20) as usize);
                self.push_line(&Style::new().fg(color).render(&format!(
                    "  ⇉ {mark} {agent}{}",
                    if snippet.is_empty() {
                        String::new()
                    } else {
                        format!(" · {snippet}")
                    }
                )));
            }
            AgentEvent::ContextCompacted {
                before_messages,
                after_messages,
                percent_before,
                ..
            } => {
                // The core auto-compacted mid-turn (pruned tool outputs + summarized
                // old messages). The next turn's prompt reflects the smaller context,
                // so ctx% self-corrects on the following End — just surface a note.
                // The core emits this whenever the threshold is crossed, even
                // when nothing could shrink (short histories can't summarize);
                // a note per round would spam "auto-compacted" while nothing
                // happened. Only surface real reductions — prune-only rounds
                // (equal count, smaller content) show up via ctx% instead.
                if after_messages < before_messages {
                    // `percent_before` is relative to the core's fixed 200k
                    // window; rescale to the model's REAL window to match ctx%.
                    let pct = context_percent_from_core_window(percent_before, self.context_limit);
                    self.push_line(&Style::new().fg(TN_GRAY).italic().render(&format!(
                        "  ✦ context auto-compacted at {pct}% · {before_messages} → {after_messages} messages"
                    )));
                }
            }
            AgentEvent::ConfirmationRequired {
                tool_id,
                tool_name,
                args,
                ..
            } => {
                if self.mode.auto_approves(&tool_name) {
                    // Silent: the mode indicator already shows auto-approve is on;
                    // a line per tool is just noise. Do NOT start another
                    // spinner_tick here — the turn's tick loop is already running
                    // (state stays Streaming through auto-approval). Stacking one
                    // per auto-approved tool made the spinner advance several
                    // frames per 80ms = the speed-up / slow-down cadence.
                    let session = self.session.clone();
                    return Some(cmd::cmd(move || async move {
                        let _ = session.confirm_tool_use(&tool_id, true, None).await;
                        Msg::Resume
                    }));
                }
                // Claude-style: no "requests:" transcript line — the prompt on
                // the activity line shows the tool; after approval the tool just
                // runs and its result lands via ToolEnd.
                self.state = State::Awaiting;
                self.runtime.remove_tool(&tool_id);
                self.approval_sel = 0;
                let label = tool_label(&tool_name, Some(&args));
                self.pending_tool = Some((tool_id, label));
                // Keep one pump parked on the event stream while awaiting input:
                // the confirmation can also resolve by timeout or an external
                // provider, and those events must clear the overlay.
                return self.rx.clone().map(pump);
            }
            AgentEvent::ConfirmationReceived {
                tool_id,
                approved,
                reason,
            } => {
                if let Some(label) = take_pending_tool_label(&mut self.pending_tool, &tool_id) {
                    self.state = State::Streaming;
                    if !approved {
                        let suffix = reason
                            .filter(|value| !value.trim().is_empty())
                            .map(|value| format!(" · {value}"))
                            .unwrap_or_default();
                        self.push_line(
                            &Style::new()
                                .fg(TN_RED)
                                .render(&format!("  ⎿ denied {label}{suffix}")),
                        );
                    }
                    return Some(self.resume_after_pending_confirmation());
                }
            }
            AgentEvent::ConfirmationTimeout {
                tool_id,
                action_taken,
            } => {
                if let Some(label) = take_pending_tool_label(&mut self.pending_tool, &tool_id) {
                    self.state = State::Streaming;
                    let (color, note) = if action_taken == "auto_approved" {
                        (
                            TN_YELLOW,
                            format!("  ⎿ confirmation timed out · auto-approved {label}"),
                        )
                    } else {
                        (
                            TN_RED,
                            format!("  ⎿ confirmation timed out · denied {label}"),
                        )
                    };
                    self.push_line(&Style::new().fg(color).render(&note));
                    return Some(self.resume_after_pending_confirmation());
                }
            }
            AgentEvent::PermissionDenied { tool_id, .. } => {
                self.runtime.remove_tool(&tool_id);
            }
            // Live context fill: every LLM round-trip reports its prompt size,
            // so ctx% (and the fill warnings) track DURING long multi-tool
            // turns instead of freezing until End.
            AgentEvent::TurnEnd { usage, .. } => {
                if usage.prompt_tokens > 0 {
                    self.last_prompt_tokens = usage.prompt_tokens;
                    self.maybe_warn_ctx();
                }
            }
            AgentEvent::End {
                text, usage, meta, ..
            } => {
                let mut review_text = if text.is_empty() {
                    self.turn_text.clone()
                } else {
                    text.clone()
                };
                let deep_research_query = self
                    .deep_research_loop
                    .as_ref()
                    .map(|state| state.query.clone());
                let deep_research_buffered_output = self.deep_research_loop.is_some()
                    && self.deep_research_report_tool_gate.report_only();
                let workflow_output_for_validation = self
                    .deep_research_workflow_output
                    .clone()
                    .unwrap_or_default();
                let workflow_metadata_for_validation = self.deep_research_workflow_metadata.clone();
                let deep_research_artifacts = deep_research_query.as_deref().and_then(|query| {
                    deep_research_report_artifacts_from_output_for_query(
                        &review_text,
                        Path::new(&self.cwd),
                        query,
                        &workflow_output_for_validation,
                        workflow_metadata_for_validation.as_ref(),
                    )
                });
                if self.deep_research_loop.is_some()
                    && deep_research_output_has_internal_leak(&review_text)
                {
                    if let Some(clean_text) =
                        deep_research_artifacts.as_ref().and_then(|artifacts| {
                            clean_deep_research_final_text_from_artifacts(
                                artifacts,
                                Path::new(&self.cwd),
                            )
                        })
                    {
                        review_text = clean_text;
                        self.streaming.clear();
                        self.turn_text.clear();
                        self.streaming.push(&review_text);
                        self.turn_text.push_str(&review_text);
                        self.mark_assistant_text(&review_text);
                    }
                }
                let deep_research_dirty_output = self.deep_research_loop.is_some()
                    && deep_research_output_has_internal_leak(&review_text);
                if deep_research_buffered_output
                    && !deep_research_dirty_output
                    && !review_text.trim().is_empty()
                {
                    self.streaming.clear();
                    self.turn_text.clear();
                    self.streaming.push(&review_text);
                    self.turn_text.push_str(&review_text);
                    self.mark_assistant_text(&review_text);
                }
                let deep_research_missing_report = deep_research_report_is_missing(
                    self.deep_research_loop.is_some(),
                    self.deep_research_report_ready,
                    deep_research_query.as_deref(),
                    &review_text,
                    Path::new(&self.cwd),
                    &workflow_output_for_validation,
                    workflow_metadata_for_validation.as_ref(),
                ) || deep_research_dirty_output;
                // /loop: stop once the agent signals completion (the word DONE).
                // Not during /sleep: its completion signal is the a3s-sleep
                // report itself, and consolidation narration ("what was done
                // today") would false-trigger this and end the run early.
                if self.loop_remaining > 0 && !self.sleep_pending && !deep_research_missing_report {
                    let r = review_text.clone();
                    if r.split(|c: char| !c.is_alphabetic())
                        .any(|w| w.eq_ignore_ascii_case("done"))
                    {
                        self.loop_remaining = 0;
                    }
                }
                // Asset review scans the WHOLE turn's text: with a delta-only
                // provider a tool call after the report would have cleared the
                // live buffer, losing a fully delivered report.
                // Only fall back to End.text when the provider never streamed
                // deltas this turn. Using the live buffer's emptiness here dups
                // text: a mid-turn finalize (e.g. a tool call) empties the buffer,
                // so End.text (the full message) would be appended a second time.
                if !self.got_delta && !text.is_empty() {
                    self.mark_assistant_text(&text);
                    self.streaming.push(&text);
                }
                if deep_research_dirty_output {
                    self.streaming.clear();
                    self.turn_text.clear();
                    self.push_line(&Style::new().fg(TN_YELLOW).render(
                        "  ⚠ DeepResearch synthesis contained internal workflow/tool logs; discarding that draft and running a clean repair pass…",
                    ));
                }
                self.finalize_streaming();
                // Asset code review: a ```a3s-review report in the final message
                // ends the review loop and opens the issue checklist.
                self.capture_review(&review_text);
                // `/sleep`: an ```a3s-sleep report ends the consolidation loop
                // and persists the distilled memories (async, batched below).
                let sleep_save = self.capture_sleep(&review_text);
                if !deep_research_dirty_output {
                    self.capture_research_report_view(&review_text);
                }
                if deep_research_missing_report {
                    let fallback_query = self
                        .deep_research_loop
                        .as_ref()
                        .map(|state| state.query.clone());
                    let workflow_output = self
                        .deep_research_workflow_output
                        .as_deref()
                        .unwrap_or_default()
                        .to_string();
                    let workflow_metadata = self.deep_research_workflow_metadata.clone();
                    match recover_missing_deep_research_report(
                        Path::new(&self.cwd),
                        fallback_query.as_deref(),
                        &review_text,
                        &workflow_output,
                        workflow_metadata.as_ref(),
                        &mut self.loop_remaining,
                        &mut self.deep_research_report_repair_used,
                    ) {
                        DeepResearchReportRecovery::CompletedMaterialized { artifacts } => {
                            if let Ok(spec) = remote_ui::local_file_view(&artifacts.html) {
                                self.deep_research_report_ready = true;
                                self.pending_deep_research_report_view = Some(spec);
                            }
                            self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
                                "  ⚠ DeepResearch HTML report was missing; rebuilt validated view at {}",
                                artifacts.html.display()
                            )));
                        }
                        DeepResearchReportRecovery::RepairPassArmed => {
                            self.pending_deep_research_report_repair_prompt =
                                deep_research_report_repair_prompt_from_state(
                                    self.deep_research_loop.as_ref(),
                                    &workflow_output,
                                    workflow_metadata.as_ref(),
                                    &review_text,
                                );
                            self.push_line(&Style::new().fg(TN_YELLOW).render(
                            "  ⚠ DeepResearch report is missing; running one focused repair pass…",
                        ));
                        }
                        DeepResearchReportRecovery::FallbackMaterialized { artifacts } => {
                            self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
                                        "  ⚠ DeepResearch report was missing; fallback draft written at {} (not opened automatically)",
                                        artifacts.html.display()
                                    )));
                        }
                        DeepResearchReportRecovery::Missing(message) => self.push_line(
                            &Style::new().fg(TN_YELLOW).render(&format!("  ⚠ {message}")),
                        ),
                    }
                }
                self.disarm_sleep_if_over(sleep_save.is_some());
                // `↓` counts OUTPUT (generated) tokens. Summing total_tokens per
                // turn re-counts the whole context every turn (the prompt is
                // re-sent each round) and balloons far past what was generated.
                // completion_tokens is the output; fall back to total-prompt if a
                // provider omits it.
                self.output_tokens += if usage.completion_tokens > 0 {
                    usage.completion_tokens
                } else {
                    usage.total_tokens.saturating_sub(usage.prompt_tokens)
                };
                // ctx% is NOT updated here: End.usage.prompt_tokens is the
                // per-turn SUM of every round's prompt (the context is re-sent
                // each round, same ballooning as above), not the current
                // context size — a multi-round turn would read rounds× too
                // high and fire false fill warnings. The TurnEnd arm already
                // recorded the real per-round size, final round included.
                if self.model.is_none() {
                    self.model = meta.and_then(|m| m.response_model.or(m.request_model));
                }
                // Count the turn, idle, then continue /loop or drain the queue.
                // A captured sleep report's save runs alongside.
                return match (sleep_save, self.complete_turn()) {
                    (Some(save), Some(next)) => Some(cmd::batch(vec![save, next])),
                    (save, next) => save.or(next),
                };
            }
            AgentEvent::Error { message } => {
                self.push_line(
                    &Style::new()
                        .fg(TN_RED)
                        .render(&format!("  error: {message}")),
                );
                self.loop_remaining = 0; // a failed turn stops the /loop
                self.review_pending = false; // and abandons an asset review
                self.sleep_pending = false; // and a `/sleep` consolidation
                self.restore_autonomy();
                self.finish();
                // Don't strand messages queued while this turn was running.
                return self.drain_queue();
            }
            // Planning mode: capture the plan and live task-status updates for
            // the pinned TODO panel above the input.
            AgentEvent::PlanningEnd { plan, .. } => {
                self.mark_agent_activity();
                self.set_plan(&plan.steps);
            }
            AgentEvent::TaskUpdated { tasks, .. } => {
                self.mark_agent_activity();
                self.set_plan(&tasks);
            }
            // Per-step lifecycle also drives the panel, in case TaskUpdated is
            // sparse: a step turns ▶ on start and ✔/✗/⊘ on completion.
            AgentEvent::StepStart { step_id, .. } => {
                self.mark_agent_activity();
                self.set_task_status(&step_id, '▶', TN_YELLOW);
            }
            AgentEvent::StepEnd {
                step_id, status, ..
            } => {
                self.mark_agent_activity();
                let (g, c) = task_status_style(status);
                self.set_task_status(&step_id, g, c);
            }
            // TurnStart, ToolInputDelta, memory, confirmation echoes,
            // etc. — not surfaced in this MVP.
            _ => {}
        }
        // Keep draining the stream.
        self.rx.clone().map(pump)
    }

    /// One-shot transcript warning as the context fills: a heads-up at 70%
    /// and a red alert at 85% (the auto-compact point). Called wherever
    /// `last_prompt_tokens` updates; the latch re-arms when usage drops.
    fn maybe_warn_ctx(&mut self) {
        if self.context_limit == 0 {
            return;
        }
        let pct = (self.last_prompt_tokens * 100 / self.context_limit as usize).min(100);
        let (latch, warn) = ctx_warn_tier(pct, self.ctx_warned_tier);
        self.ctx_warned_tier = latch;
        if warn.is_some() {
            // push_line rebuilds the viewport from `messages` only, which
            // would hide a still-streaming round's text (invisible through a
            // whole approval wait if this round ends in a gated tool call).
            // Finalize it into the transcript first — same as ToolStart does.
            self.finalize_streaming();
        }
        match warn {
            Some(85) => self.push_line(&Style::new().fg(TN_RED).render(&format!(
                "  ✦ context {pct}% full — auto-compacting soon; /compact to summarize now"
            ))),
            Some(_) => self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
                "  ✦ context {pct}% full — auto-compacts near 85%; /compact to summarize early"
            ))),
            None => {}
        }
    }

    fn mark_agent_activity(&mut self) {
        self.turn_had_agent_activity = true;
        self.turn_text_after_activity = false;
    }

    fn mark_assistant_text(&mut self, text: &str) {
        if !text.trim().is_empty() {
            self.turn_text_after_activity = true;
        }
    }

    fn prepare_ultracode_synthesis(&self) -> Option<(String, String)> {
        if !needs_synthesis(
            self.ultracode_synthesis_inflight,
            self.ultracode_synthesis_used,
            self.turn_had_agent_activity,
            self.turn_text_after_activity,
        ) {
            return None;
        }

        let user_task = self
            .running_task
            .as_deref()
            .filter(|task| !task.trim().is_empty())
            .unwrap_or("the previous task");
        let mut prompt = format!(
            "[synthesis]\n\
             The previous turn completed planning/tool/subagent work \
             but stopped without a final user-facing answer.\n\n\
             Original user task:\n{user_task}\n\n\
             Write the final answer now in the user's language. Synthesize the \
             completed work into a useful response. Do not call tools or start \
             more subagents unless it is strictly necessary to avoid an incorrect \
             answer. If a child run produced no text output, summarize the \
             available plan/status instead of exposing raw task metadata.\n"
        );

        if !self.plan.is_empty() {
            prompt.push_str("\nPlan/status:\n");
            for (_, text, glyph, _) in &self.plan {
                let status = match glyph {
                    '✔' => "done",
                    '▶' => "in progress",
                    '✗' => "failed",
                    _ => "pending",
                };
                prompt.push_str(&format!("- [{status}] {text}\n"));
            }
        }

        let subagents = self.runtime.subagents();
        if !subagents.is_empty() {
            prompt.push_str("\nSubagents:\n");
            for agent in subagents {
                let status = match agent.success {
                    Some(true) => "done",
                    Some(false) => "failed",
                    None if agent.done => "done",
                    None => "unknown",
                };
                prompt.push_str(&format!(
                    "- [{status}] {}: {}\n",
                    agent.agent, agent.description
                ));
            }
        }

        if let Some(workflow) = &self.last_workflow {
            prompt.push_str("\nLatest workflow artifact excerpt:\n");
            prompt.push_str(&truncate(workflow, 4000));
            prompt.push('\n');
        }

        Some((prompt, user_task.to_string()))
    }

    fn finalize_streaming(&mut self) {
        let rendered = self.streaming.view();
        if !rendered.trim().is_empty() {
            let block = gutter(TN_GREEN, &rendered);
            // Safety net against duplicate output: skip if this exact block
            // already appeared in the last few messages (a re-finalize, or an
            // agent that re-emits earlier text — e.g. its preamble after a tool).
            let recent_dup = self.messages.iter().rev().take(4).any(|m| m == &block);
            if !recent_dup {
                self.messages.push(block);
            }
        }
        if !self.deferred_tool_blocks.is_empty() {
            self.messages
                .extend(std::mem::take(&mut self.deferred_tool_blocks));
        }
        self.defer_tool_blocks_until_stream_finalized = false;
        self.streaming.clear();
        self.thinking.clear();
        self.rebuild_viewport();
    }

    fn should_defer_tool_for_streaming_markdown(&self) -> bool {
        if self.defer_tool_blocks_until_stream_finalized {
            return true;
        }
        markdown_fragment_has_open_inline(self.streaming.raw_content())
    }

    fn finish(&mut self) {
        self.state = State::Idle;
        self.running_task = None;
        // Keep completed subagent rows visible after the turn so DeepResearch
        // fan-out has a durable bottom summary; the next user turn clears them.
        self.runtime.finish_turn_entities(Instant::now());
        self.ultracode_synthesis_inflight = false;
        self.relayout();
        self.stream_started = None;
        self.spinner.stop();
        self.rx = None;
        self.stream_join = None;
        self.host_tool_abort = None;
        self.host_progress_inflight = false;
        self.interrupting = false;
        self.rebuild_viewport();
    }

    fn push_line(&mut self, line: &str) {
        self.messages.push(line.to_string());
        self.rebuild_viewport();
    }

    fn capture_research_report_view(&mut self, output: &str) -> bool {
        let workspace = Path::new(&self.cwd);
        let spec = self
            .deep_research_loop
            .as_ref()
            .and_then(|state| {
                deep_research_report_view_spec_for_query(
                    output,
                    workspace,
                    &state.query,
                    self.deep_research_workflow_output
                        .as_deref()
                        .unwrap_or_default(),
                    self.deep_research_workflow_metadata.as_ref(),
                )
            })
            .or_else(|| {
                self.deep_research_loop
                    .is_none()
                    .then(|| research_report_view_spec(output, workspace))
                    .flatten()
            });
        if let Some(spec) = spec {
            match research_report_view_action(self.deep_research_loop.is_some()) {
                ResearchReportViewAction::DeferUntilDeepResearchComplete => {
                    self.deep_research_report_ready = true;
                    self.pending_deep_research_report_view = Some(spec);
                }
                ResearchReportViewAction::OpenNow => {
                    let is_new = self.remember_remote_view(spec.clone());
                    if is_new {
                        self.open_remote_view(&spec);
                    }
                }
            }
            return true;
        }
        false
    }

    fn open_pending_deep_research_report_view(&mut self) {
        let Some(spec) = self.pending_deep_research_report_view.take() else {
            return;
        };
        let is_new = self.remember_remote_view(spec.clone());
        if is_new {
            self.open_remote_view(&spec);
        }
    }

    /// Open an OS viewUrl in the native `a3s-webview` window. If the helper is
    /// not installed, fall back to the system browser and leave a transcript
    /// hint so the click never feels like a no-op.
    fn open_remote_view(&mut self, spec: &remote_ui::ViewSpec) {
        match remote_ui::open_window(spec) {
            Ok(remote_ui::OpenedWith::Webview) => {}
            Ok(remote_ui::OpenedWith::Browser) => {
                let helper = remote_ui::webview_helper_path()
                    .map(|path| path.display().to_string())
                    .unwrap_or_else(|| {
                        "missing; install a3s-webview or set A3S_WEBVIEW_BIN".to_string()
                    });
                self.push_line(&Style::new().fg(TN_YELLOW).render(&format!(
                    "  ↗ opened URL in browser: {} · authenticated RemoteUI popup helper: {helper}",
                    spec.url
                )));
            }
            Err(err) => {
                self.push_line(
                    &Style::new()
                        .fg(TN_GRAY)
                        .render(&format!("  🔗 open in your browser: {} ({err})", spec.url)),
                );
            }
        }
    }

    fn find_remote_view_spec(&self, output: &str) -> Option<remote_ui::ViewSpec> {
        // The progressive API returns a RELATIVE view url; complete it against
        // the signed-in OS origin (the TUI is "the edge").
        let os_origin = self
            .os_session
            .as_ref()
            .map(|s| crate::a3s_os::os_origin(&s.address));
        remote_ui::find_view_url(output, os_origin.as_deref())
    }

    fn remember_remote_view(&mut self, spec: remote_ui::ViewSpec) -> bool {
        // Remember the view and surface a clickable "Open view" line ourselves
        // (deterministic) rather than trusting the model to print the marker —
        // weaker models often forget it or jq the `.view` object away.
        let is_new = is_new_remote_view(self.last_view.as_ref(), &spec);
        self.last_view = Some(spec.clone());
        self.record_runtime_view_evidence();
        if is_new {
            self.push_line(&gutter(ACCENT, &remote_view_button("click to open")));
        }
        is_new
    }

    /// Skill dirs for the session: the discovered Claude/Codex dirs plus the
    /// login-gated built-in OS `a3s-os-capabilities` skill when signed in.
    pub(crate) fn skill_dirs(&self) -> Vec<std::path::PathBuf> {
        let mut dirs = agent_skill_dirs(&self.cwd);
        // Always-available built-in skills (the `okf` LLM-wiki / knowledge compiler).
        if let Some(d) = ensure_builtin_skills_dir() {
            dirs.push(d);
        }
        if self.os_session.is_some() {
            if let Some(cfg) = &self.os_config {
                if let Some(d) = crate::a3s_os::ensure_capability_skill_dir(cfg) {
                    dirs.push(d);
                }
            }
        }
        dirs
    }

    /// After an OS login/logout, rebuild the session so the login-gated
    /// skill loads/unloads immediately, and refresh the start-screen skill list.
    fn refresh_after_auth(&mut self) {
        self.os_gateway_models = None;
        self.os_gateway_models_loading = false;
        self.os_gateway_error = None;
        if self.state == State::Idle {
            if let Ok((s, _)) = self.rebuild_session(self.model.as_deref()) {
                self.replace_session(s);
            }
        }
        // Login/logout flips whether the A3S Runtime `runtime` tool is available.
        self.sync_runtime_tool();
        let dirs = self.skill_dirs();
        self.skill_count = count_skill_files(&dirs);
        self.skills = load_skills(&dirs);
    }

    /// Register the A3S Runtime `runtime` offload tool while signed in to OS,
    /// unregister it while signed out — so it only appears in the model's toolset
    /// after login. Called after every auth change (login/logout), once the
    /// session has been (re)built.
    fn replace_session(&mut self, session: AgentSession) {
        self.session = Arc::new(session);
        self.session.register_dynamic_workflow_runtime();
        self.sync_runtime_tool();
    }

    fn sync_runtime_tool(&self) {
        match self.os_session.as_ref() {
            Some(s) => self.session.register_dynamic_tool(std::sync::Arc::new(
                crate::runtime_tool::RuntimeTool::new(s),
            )),
            None => self.session.unregister_dynamic_tool("runtime"),
        }
    }

    /// Open `path` directly in the built-in IDE editor (tree rooted at its
    /// directory, file loaded, editor focused). Used by `/config` + first launch.
    fn open_config_in_ide(&mut self, path: &std::path::Path) {
        let dir = path.parent().unwrap_or(std::path::Path::new("."));
        let lines: Vec<String> = std::fs::read_to_string(path)
            .unwrap_or_default()
            .replace('\t', "    ")
            .lines()
            .map(String::from)
            .collect();
        let mut ide = Ide::browse(ide_children(dir, 0), "config");
        ide.file = Some(IdeFile::new(path.to_path_buf(), lines, false, false));
        ide.focus_editor = true;
        self.ide = Some(ide);
    }

    /// Capture a dynamic workflow or `parallel_task`/`task` dispatch as a
    /// readable artifact for synthesis and a collapsed transcript marker.
    fn capture_workflow(&mut self, name: &str, args: Option<&serde_json::Value>) {
        let Some((doc, label)) = workflow_doc_for_tool(name, args) else {
            return;
        };
        self.last_workflow = Some(doc);
        self.push_line(&Style::new().fg(ACCENT).render(&format!("  ⊞ {label}")));
    }

    /// Open read-only text content in the built-in IDE. Editor-focused for
    /// scroll/nav, but `readonly` blocks edits and Ctrl+S.
    fn open_readonly_in_ide(&mut self, title: &str, content: &str) {
        let lines: Vec<String> = content.lines().map(String::from).collect();
        let mut ide = Ide::browse(
            ide_children(std::path::Path::new(&self.cwd), 0),
            "workspace",
        );
        ide.file = Some(IdeFile::new(
            std::path::PathBuf::from(title),
            lines,
            false,
            true,
        ));
        ide.focus_editor = true;
        ide.flash = Some(ide_flash_line(ToastKind::Warning, "read-only"));
        self.ide = Some(ide);
    }

    /// Format every retained tool call for the `/output` viewer.
    fn format_tool_log(&self) -> Option<String> {
        format_tool_log_records(self.runtime.tool_log(), self.viewport_content_width())
    }

    /// Move through prompt history and load the entry into the input. Going
    /// forward past the newest entry returns to a fresh, empty input.
    fn history_recall(&mut self, up: bool) {
        let pos = match (self.history_pos, up) {
            (None, true) => self.history.len().saturating_sub(1),
            (None, false) => return,
            (Some(i), true) => i.saturating_sub(1),
            (Some(i), false) => i + 1,
        };
        if pos >= self.history.len() {
            self.history_pos = None;
            self.textarea.clear();
        } else {
            self.history_pos = Some(pos);
            self.textarea.set_value(&self.history[pos]);
        }
    }

    fn update_viewport_with_stream(&mut self) {
        // Throttle this O(n) rebuild to ~30fps. A fast stream emits deltas far
        // faster than that; rebuilding the whole transcript each time starves
        // the animation ticks on the single-threaded loop (uneven cadence jitter).
        if let Some(t) = self.last_paint {
            if t.elapsed() < Duration::from_millis(33) {
                return;
            }
        }
        self.last_paint = Some(Instant::now());
        let mut blocks: Vec<String> = self.messages.clone();
        let body = thinking_block(&self.thinking, self.viewport_content_width());
        if !body.is_empty() {
            blocks.push(body);
        }
        let rendered = self.streaming.view();
        if !rendered.is_empty() {
            blocks.push(gutter(TN_GREEN, &rendered));
        }
        blocks.extend(self.deferred_tool_blocks.iter().cloned());
        // Currently-executing tool: "• Running <cmd>…" with a blinking bullet.
        if let Some(tool) = self.runtime.live_tool() {
            let on = self.blink_tick % 8 < 4; // ~320ms on / 320ms off
            blocks.push(render_live_tool_activity(
                &tool.name,
                tool.args().as_ref(),
                tool.output(),
                self.viewport_content_width(),
                on,
            ));
        }
        // Same "\n…\n" framing as rebuild_viewport so the transcript doesn't
        // jump a line when streaming starts/ends.
        self.viewport
            .set_content(&format!("\n{}\n", blocks.join("\n\n")));
    }

    fn rebuild_viewport(&mut self) {
        self.selection = None; // content changed → screen-coord selection is stale
        let full = self.messages.join("\n\n");
        self.viewport.set_content(&format!("\n{full}\n")); // top padding
    }

    /// Rows the input box needs — the textarea auto-grows its own height with
    /// embedded newlines (Shift+Enter), so the layout just mirrors it.
    pub(crate) fn input_height(&self) -> u16 {
        self.textarea.height()
    }

    /// Inline tool-approval keys (Codex-style): y/Enter allow, n/Esc deny,
    /// a = allow + enable auto-approve for the rest of the session.
    fn handle_approval_key(&mut self, key: &KeyEvent) -> Option<Cmd<Msg>> {
        match key.code {
            KeyCode::Up => {
                self.approval_sel = self.approval_sel.saturating_sub(1);
                None
            }
            KeyCode::Down => {
                self.approval_sel = (self.approval_sel + 1).min(2);
                None
            }
            // Enter selects the highlighted option (0 yes · 1 always · 2 no).
            KeyCode::Enter => Some(cmd::msg(self.apply_approval(self.approval_sel))),
            KeyCode::Char('y' | 'Y') => Some(cmd::msg(self.apply_approval(0))),
            KeyCode::Char('a' | 'A') => Some(cmd::msg(self.apply_approval(1))),
            KeyCode::Char('n' | 'N') | KeyCode::Esc => Some(cmd::msg(self.apply_approval(2))),
            // Digit keys pick the numbered option directly (1 Yes · 2 Always · 3 No).
            KeyCode::Char(c @ '1'..='3') => {
                Some(cmd::msg(self.apply_approval(c as usize - '1' as usize)))
            }
            _ => None,
        }
    }

    fn handle_approval_mouse(&mut self, mouse: &MouseEvent) -> Option<Cmd<Msg>> {
        if self.state != State::Awaiting {
            return None;
        }
        let Some((_, label)) = &self.pending_tool else {
            return None;
        };
        let width = (self.width as usize).min(u16::MAX as usize);
        if width == 0 {
            return None;
        }
        let mut prompt = approval_prompt(label, self.approval_sel);
        let row_count = prompt.lines(width as u16, APPROVAL_PANEL_HEIGHT).len();
        if row_count == 0 {
            return None;
        }
        let y_offset = approval_overlay_y_offset(self.height as usize, row_count);
        let row = mouse.row as usize;
        let start = y_offset as usize;
        if row < start || row >= start.saturating_add(row_count) {
            return None;
        }
        prompt.set_y_offset(y_offset);
        let before = prompt.selected_index();

        match prompt.handle_mouse(mouse) {
            Some(ChoicePromptMsg::Selected(index)) => Some(cmd::msg(self.apply_approval(index))),
            Some(ChoicePromptMsg::Cancelled) => Some(cmd::msg(self.apply_approval(2))),
            None => {
                let after = prompt.selected_index().min(2);
                if after != before {
                    self.approval_sel = after;
                }
                None
            }
        }
    }

    fn apply_approval(&mut self, choice: usize) -> Msg {
        match choice {
            0 => Msg::ModalConfirm(0), // yes, once
            1 => {
                self.mode = Mode::Auto; // yes, and stop asking
                Msg::ModalConfirm(0)
            }
            _ => Msg::ModalConfirm(1), // no
        }
    }

    /// Tool-approval options panel (Claude-style numbered choices).
    fn overlay_approval(&self, composed: String) -> String {
        if self.state != State::Awaiting {
            return composed;
        }
        let Some((_, label)) = &self.pending_tool else {
            return composed;
        };
        let menu = approval_menu_lines(label, self.approval_sel, self.width as usize);
        self.overlay_list(composed, &menu)
    }
}

fn approval_menu_lines(label: &str, selected: usize, width: usize) -> Vec<String> {
    approval_prompt(label, selected).lines(width as u16, APPROVAL_PANEL_HEIGHT)
}

const APPROVAL_OVERLAY_ROWS_BELOW: usize = 5;
const APPROVAL_PANEL_HEIGHT: usize = 5;

fn approval_prompt(label: &str, selected: usize) -> ChoicePrompt {
    ChoicePrompt::approval(format!("⏵ Allow {label}?"))
        .selected(selected)
        .indent(2)
        .marker("❯")
        .title_color(TN_YELLOW)
        .text_color(TN_FG)
        .muted_color(TN_GRAY)
        .danger_color(TN_RED)
        .selected_colors(Color::BrightWhite, ACCENT)
        .hint("Enter select · ↑/↓ · 1–3 · Esc")
}

fn approval_overlay_y_offset(screen_height: usize, row_count: usize) -> u16 {
    screen_height
        .saturating_sub(APPROVAL_OVERLAY_ROWS_BELOW)
        .saturating_sub(row_count)
        .min(u16::MAX as usize) as u16
}

/// Headless probe of the same `session.stream()` / `AgentEvent` path the TUI
/// uses, auto-approving tool calls. Drives the integration without a TTY.
async fn run_smoke(
    session: Arc<AgentSession>,
    os_available: bool,
    deep_research_report_tool_gate: DeepResearchReportToolGate,
) -> anyhow::Result<()> {
    let prompt = std::env::var("A3S_CODE_TUI_PROMPT")
        .unwrap_or_else(|_| "Reply with exactly one short sentence: what is 2 + 2?".to_string());
    if let Some(query) = prompt.trim().strip_prefix('?') {
        let query = query.trim().to_string();
        if query.is_empty() {
            anyhow::bail!("A3S_CODE_TUI_PROMPT starts with `?` but has no DeepResearch query");
        }
        return run_smoke_deep_research(
            session,
            query,
            os_available,
            deep_research_report_tool_gate,
        )
        .await;
    }
    eprintln!("[smoke] prompt: {prompt}");
    let _ = stream_smoke_prompt(session.as_ref(), prompt.as_str()).await?;
    Ok(())
}

async fn stream_smoke_prompt(session: &AgentSession, prompt: &str) -> anyhow::Result<String> {
    stream_smoke_prompt_inner(session, prompt, None, None).await
}

async fn stream_smoke_prompt_until_report(
    session: &AgentSession,
    prompt: &str,
    workspace: &Path,
    query: &str,
    timeout_ms: u64,
    phase: &'static str,
) -> anyhow::Result<String> {
    stream_smoke_prompt_inner(
        session,
        prompt,
        Some((workspace, query)),
        Some((timeout_ms, phase)),
    )
    .await
}

async fn stream_smoke_prompt_inner(
    session: &AgentSession,
    prompt: &str,
    stop_on_report: Option<(&Path, &str)>,
    timeout: Option<(u64, &'static str)>,
) -> anyhow::Result<String> {
    let (mut rx, join) = session.stream(prompt, None).await?;
    let abort = join.abort_handle();
    let mut streamed = String::new();
    let mut end_text = String::new();
    let mut stopped_after_report = false;
    let mut deadline = timeout
        .map(|(timeout_ms, _)| Box::pin(tokio::time::sleep(Duration::from_millis(timeout_ms))));
    loop {
        let event = if let Some(deadline) = deadline.as_mut() {
            tokio::select! {
                event = rx.recv() => event,
                _ = deadline.as_mut() => {
                    let (timeout_ms, phase) = timeout.expect("deadline implies timeout");
                    abort.abort();
                    let _ = tokio::time::timeout(
                        Duration::from_millis(DEEP_RESEARCH_ABORT_GRACE_MS),
                        join,
                    )
                    .await;
                    let message = format!(
                        "DeepResearch {phase} model call timed out after {timeout_ms} ms."
                    );
                    eprintln!("\n[smoke] {message}");
                    return Ok(message);
                }
            }
        } else {
            rx.recv().await
        };
        let Some(event) = event else {
            break;
        };
        match event {
            AgentEvent::TextDelta { text } => {
                streamed.push_str(&text);
                if stop_on_report.is_none() {
                    print!("{text}");
                }
                if stop_on_report.is_some_and(|(workspace, query)| {
                    research_report_artifacts_from_output_for_query(&streamed, workspace, query)
                        .is_some()
                }) {
                    stopped_after_report = true;
                    eprintln!("\n[smoke] report marker observed; stopping stream");
                    abort.abort();
                    break;
                }
            }
            AgentEvent::ToolStart { name, .. } => eprintln!("\n[tool start] {name}"),
            AgentEvent::ToolEnd {
                name,
                exit_code,
                output,
                ..
            } => eprintln!(
                "[tool end] {name} (exit {exit_code}): {}",
                output.lines().take(2).collect::<Vec<_>>().join(" | ")
            ),
            AgentEvent::ConfirmationRequired {
                tool_id, tool_name, ..
            } => {
                eprintln!("[confirm] auto-allowing {tool_name}");
                let _ = session.confirm_tool_use(&tool_id, true, None).await;
            }
            AgentEvent::End { text, .. } => {
                if stop_on_report.is_none() && streamed.trim().is_empty() && !text.trim().is_empty()
                {
                    print!("{text}");
                }
                end_text = text;
                if stop_on_report.is_some_and(|(workspace, query)| {
                    research_report_artifacts_from_output_for_query(&end_text, workspace, query)
                        .is_some()
                }) {
                    stopped_after_report = true;
                }
                eprintln!("\n[end]");
                break;
            }
            AgentEvent::Error { message } => eprintln!("\n[error] {message}"),
            _ => {}
        }
    }
    // Let the stream task finish (incl. auto-save/persist) before we exit.
    if stopped_after_report {
        let _ =
            tokio::time::timeout(Duration::from_millis(DEEP_RESEARCH_ABORT_GRACE_MS), join).await;
    } else {
        tokio::time::timeout(std::time::Duration::from_secs(30), join)
            .await
            .map_err(|_| {
                anyhow::anyhow!("smoke stream worker did not finish after AgentEvent::End")
            })??;
    }
    if end_text.trim().is_empty() {
        Ok(streamed)
    } else {
        Ok(end_text)
    }
}

async fn run_smoke_deep_research(
    session: Arc<AgentSession>,
    query: String,
    os_available: bool,
    deep_research_report_tool_gate: DeepResearchReportToolGate,
) -> anyhow::Result<()> {
    let workspace = std::env::current_dir()?;
    let os_runtime = should_use_os_runtime_for_deep_research(&query, os_available);
    eprintln!(
        "[smoke] deepresearch workflow: {}",
        if os_runtime { "os-runtime" } else { "local" }
    );
    let workflow_args = deep_research_workflow_args(&query, os_runtime);
    let (mut progress_rx, workflow_join) =
        session.tool_with_events("dynamic_workflow", workflow_args.clone());
    let workflow_abort = workflow_join.abort_handle();
    let progress_drain = tokio::spawn(async move { while progress_rx.recv().await.is_some() {} });
    let timeout_ms = deep_research_workflow_host_timeout_ms(&workflow_args);
    let workflow = match tokio::time::timeout(
        std::time::Duration::from_millis(timeout_ms),
        workflow_join,
    )
    .await
    {
        Ok(Ok(result)) => result.map_err(|err| err.to_string()),
        Ok(Err(err)) => Err(err.to_string()),
        Err(_) => {
            workflow_abort.abort();
            Err(format!(
                "dynamic_workflow timed out after {timeout_ms} ms while gathering DeepResearch evidence"
            ))
        }
    };
    progress_drain.abort();

    let (workflow_output, exit_code, metadata) = match workflow {
        Ok(result) => (result.output, result.exit_code, result.metadata),
        Err(error) => (error, 1, None),
    };
    eprintln!("[smoke] deepresearch workflow exit: {exit_code}");
    let prompt = if exit_code == 0 {
        deep_research_synthesis_prompt(&query, os_runtime, &workflow_output, metadata.as_ref())
    } else {
        deep_research_recovery_prompt(&query, os_runtime, &workflow_output, metadata.as_ref())
    };
    eprintln!("[smoke] deepresearch synthesis");
    deep_research_report_tool_gate.set_report_only(true);
    let mut final_text = stream_smoke_prompt_until_report(
        session.as_ref(),
        prompt.as_str(),
        &workspace,
        &query,
        DEEP_RESEARCH_SYNTHESIS_TIMEOUT_MS,
        "synthesis",
    )
    .await?;
    let mut artifacts = deep_research_report_artifacts_from_output_for_query(
        &final_text,
        &workspace,
        &query,
        &workflow_output,
        metadata.as_ref(),
    );

    if deep_research_output_has_internal_leak(&final_text) {
        if let Some(clean_text) = artifacts.as_ref().and_then(|artifacts| {
            clean_deep_research_final_text_from_artifacts(artifacts, &workspace)
        }) {
            final_text = clean_text;
        }
    }
    if artifacts.is_none() {
        artifacts = materialize_deep_research_completed_report_from_markdown(
            &workspace,
            &query,
            &workflow_output,
            metadata.as_ref(),
        );
        if let Some(clean_text) = artifacts.as_ref().and_then(|artifacts| {
            clean_deep_research_final_text_from_artifacts(artifacts, &workspace)
        }) {
            final_text = clean_text;
        }
    }

    if artifacts.is_none() || deep_research_output_has_internal_leak(&final_text) {
        if deep_research_output_has_internal_leak(&final_text) {
            eprintln!("[smoke] deepresearch report contained internal/tool-status text; running repair pass");
        } else {
            eprintln!("[smoke] deepresearch report missing; running repair pass");
        }
        let repair = deep_research_repair_prompt(
            &query,
            os_runtime,
            &workflow_output,
            metadata.as_ref(),
            &final_text,
        );
        final_text = stream_smoke_prompt_until_report(
            session.as_ref(),
            repair.as_str(),
            &workspace,
            &query,
            DEEP_RESEARCH_REPAIR_TIMEOUT_MS,
            "repair",
        )
        .await?;
        artifacts = deep_research_report_artifacts_from_output_for_query(
            &final_text,
            &workspace,
            &query,
            &workflow_output,
            metadata.as_ref(),
        );
        if deep_research_output_has_internal_leak(&final_text) {
            if let Some(clean_text) = artifacts.as_ref().and_then(|artifacts| {
                clean_deep_research_final_text_from_artifacts(artifacts, &workspace)
            }) {
                final_text = clean_text;
            }
        }
        if artifacts.is_none() {
            artifacts = materialize_deep_research_completed_report_from_markdown(
                &workspace,
                &query,
                &workflow_output,
                metadata.as_ref(),
            );
            if let Some(clean_text) = artifacts.as_ref().and_then(|artifacts| {
                clean_deep_research_final_text_from_artifacts(artifacts, &workspace)
            }) {
                final_text = clean_text;
            }
        }
    }

    if artifacts.is_none() {
        eprintln!("[smoke] deepresearch report missing; materializing host fallback draft");
        deep_research_report_tool_gate.set_report_only(false);
        let fallback_artifacts = materialize_deep_research_fallback_draft(
            &workspace,
            &query,
            &final_text,
            &workflow_output,
        )
        .map_err(anyhow::Error::msg)?;
        artifacts = Some(fallback_artifacts);
    }

    let artifacts = artifacts.ok_or_else(|| {
        anyhow::anyhow!(
            "DeepResearch smoke did not produce the required report artifacts: expected `A3S_RESEARCH_VIEW: .a3s/research/<slug>/index.html`"
        )
    })?;
    deep_research_report_tool_gate.set_report_only(false);
    if !final_text.trim().is_empty() && !deep_research_output_has_internal_leak(&final_text) {
        println!("{final_text}");
    }
    eprintln!("[smoke] report.md: {}", artifacts.markdown.display());
    eprintln!("[smoke] index.html: {}", artifacts.html.display());
    Ok(())
}

pub async fn run(args: Vec<String>) -> anyhow::Result<()> {
    // `a3s code resume [id]` continues a saved session (newest if no id given);
    // otherwise a fresh id. Existence is verified against the store below.
    let resuming = args.first().map(String::as_str) == Some("resume");
    let explicit_id = if resuming { args.get(1).cloned() } else { None };
    let mut session_id = explicit_id.clone().unwrap_or_else(new_session_id);
    // First launch: if there's no config, generate a starter template at
    // ~/.a3s/config.acl and open it in the built-in IDE (see `created_config`).
    let (config_path, created_config) = match find_config() {
        Some(p) => (p, false),
        None => {
            let p = default_config_path()
                .ok_or_else(|| anyhow::anyhow!("no HOME directory found for ~/.a3s/config.acl"))?;
            write_template_config(&p)
                .map_err(|e| anyhow::anyhow!("failed to write starter config {p:?}: {e}"))?;
            (p.to_string_lossy().into_owned(), true)
        }
    };
    let agent = Arc::new(
        Agent::new(config_path.clone())
            .await
            .map_err(|e| anyhow::anyhow!("failed to load agent from {config_path}: {e}"))?,
    );
    let workspace = std::env::current_dir()?.to_string_lossy().to_string();

    // Configured "provider/model" ids (+ context windows) + the default model.
    let mut models: Vec<String> = Vec::new();
    let mut model_ctx: std::collections::HashMap<String, u32> = std::collections::HashMap::new();
    let mut default_model: Option<String> = None;
    let mut os_config: Option<OsConfig> = None;
    if let Ok(cfg) =
        a3s_code_core::config::CodeConfig::from_file(std::path::Path::new(&config_path))
    {
        for (p, m) in cfg.list_models() {
            let id = format!("{}/{}", p.name, m.id);
            model_ctx.insert(id.clone(), m.limit.context);
            models.push(id);
        }
        default_model = cfg.default_model.clone();
        os_config = cfg.os.clone();
    }

    // Persistent, resumable session: stored under <cwd>/.a3s/tui-sessions and
    // keyed by a fixed id, so relaunching in the same directory continues the
    // conversation. Falls back to a fresh session when none exists yet.
    let store_dir = std::path::Path::new(&workspace).join(".a3s/tui-sessions");

    // Resolve `resume`: verify the id exists (else show what's available), or
    // pick the most recent session when no id was given.
    if resuming {
        let mut saved: Vec<(String, std::time::SystemTime)> = std::fs::read_dir(&store_dir)
            .into_iter()
            .flatten()
            .flatten()
            .filter_map(|e| {
                let p = e.path();
                if p.extension().and_then(|x| x.to_str()) != Some("json") {
                    return None;
                }
                let id = p.file_stem()?.to_str()?.to_string();
                let mtime = e.metadata().ok()?.modified().ok()?;
                Some((id, mtime))
            })
            .collect();
        saved.sort_by_key(|e| std::cmp::Reverse(e.1)); // newest first
        match &explicit_id {
            Some(id) if !saved.iter().any(|(s, _)| s == id) => {
                eprintln!("a3s: session '{id}' not found in {}", store_dir.display());
                if saved.is_empty() {
                    eprintln!("  (no saved sessions in this directory)");
                } else {
                    eprintln!("  available sessions (newest first):");
                    for (s, _) in saved.iter().take(10) {
                        eprintln!("    a3s code resume {s}");
                    }
                }
                return Ok(());
            }
            None => match saved.first() {
                Some((s, _)) => session_id = s.clone(),
                None => {
                    eprintln!(
                        "a3s: no saved sessions to resume in {}",
                        store_dir.display()
                    );
                    return Ok(());
                }
            },
            _ => {}
        }
    }

    let store: Arc<dyn a3s_code_core::store::SessionStore> = Arc::new(
        a3s_code_core::store::FileSessionStore::new(&store_dir)
            .await
            .map_err(|e| anyhow::anyhow!("failed to open session store {store_dir:?}: {e}"))?,
    );
    // Enable HITL confirmation so file-modifying tools (write/edit/patch) can
    // run — they require a confirmation manager, otherwise they fail with
    // "requires confirmation but no HITL confirmation manager is configured".
    // The TUI is that manager (approve/deny modal, or /auto). Keep the human
    // confirmation wait separate from the tool execution timeout: reading and
    // deciding must not consume the tool's runtime budget.
    let confirmation = a3s_code_core::hitl::ConfirmationPolicy::enabled()
        .with_timeout(HITL_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
    // Claude Code compatibility: load Claude/plugin SKILL.md skills alongside
    // a3s's own (they share the markdown + YAML-frontmatter format).
    let mut claude_dirs = agent_skill_dirs(&workspace);
    // Restore the persisted OS login *before* building the session, so its
    // login-gated built-in `a3s-os-capabilities` skill is materialized and
    // loaded from the first turn (only when signed in).
    let os_session = os_config.as_ref().and_then(crate::a3s_os::current_session);
    if let Some(s) = &os_session {
        // Export endpoint + token so the agent's shell uses $A3S_OS_* directly
        // instead of re-reading ~/.a3s/os-auth.json every call.
        crate::a3s_os::export_os_env(s);
        if let Some(dir) = os_config
            .as_ref()
            .and_then(crate::a3s_os::ensure_capability_skill_dir)
        {
            claude_dirs.push(dir);
        }
    }
    let restored_model_selection =
        restore_model_selection(&models, os_session.as_ref(), session_id.as_str());
    let launch_model = restored_model_selection
        .as_ref()
        .map(|(model, _)| model.clone())
        .or_else(|| default_model.clone());
    let launch_llm_override = restored_model_selection
        .as_ref()
        .and_then(|(_, client)| client.clone());
    let context_limit = launch_model
        .as_ref()
        .map(|m| ctx_limit_for_model(&model_ctx, m))
        .unwrap_or_else(|| resolve_ctx_limit(None));
    let initial_budget = budget_plan_for_effort_index(
        DEFAULT_TUI_EFFORT_INDEX,
        Some(context_limit),
        BudgetWorkload::Interactive,
    );
    let deep_research_report_tool_gate = DeepResearchReportToolGate::default();
    // Claude Code compatibility: inject CLAUDE.md (AGENTS.md is auto-loaded by
    // the core) into the system prompt via prompt slots.
    let instructions = project_instructions(&workspace);
    // When a persisted login is restored on launch, inject the OS-platform
    // directive too (mirrors effort_session_opts) so the very first turn already
    // routes OS questions through the progressive-API skill.
    let os_address = os_session.as_ref().map(|s| s.address.clone());
    // Past-session recall: when the ctx CLI is installed, teach the agent to
    // search local agent history before re-deriving prior work.
    let ctx_ready = panels::ctx::ctx_available();
    let with_instr = |o: SessionOptions| {
        let mut parts: Vec<String> = Vec::new();
        if let Some(i) = &instructions {
            parts.push(i.clone());
        }
        if let Some(addr) = &os_address {
            parts.push(os_platform_guide(addr));
        }
        if ctx_ready {
            parts.push(panels::ctx::ctx_history_guide());
        }
        if parts.is_empty() {
            o
        } else {
            o.with_prompt_slots(SystemPromptSlots::default().with_extra(parts.join("\n\n")))
        }
    };
    let manifest_backend = ManifestWorkspaceBackend::new(std::path::PathBuf::from(&workspace));
    let workspace_manifest = manifest_backend.manifest();
    let initial_manifest = workspace_manifest.snapshot();
    let initial_files = initial_manifest.file_paths();
    let workspace_manifest_rx = Arc::new(Mutex::new(workspace_manifest.subscribe()));
    let workspace_services = WorkspaceServices::local_with_manifest_backend(manifest_backend);
    let session = match agent.resume_session(
        session_id.as_str(),
        apply_launch_model_options(
            with_instr(with_recent_workspace_context(
                tui_session_options_with_gate(
                    confirmation.clone(),
                    deep_research_report_tool_gate.clone(),
                )
                .with_session_store(store.clone())
                .with_workspace_backend(workspace_services.clone())
                .with_skill_dirs(claude_dirs.clone())
                .with_auto_save(true)
                .with_auto_compact(true)
                // Scaled to the model's real window — the core triggers off a
                // fixed 200k, so a flat 0.85 would put the trigger past a
                // smaller window and auto-compact would never fire (see
                // `auto_compact_threshold_for`).
                .with_auto_compact_threshold(auto_compact_threshold_for(context_limit))
                .with_file_memory(memory_dir())
                .with_max_parallel_tasks(initial_budget.max_parallel_tasks)
                .with_max_tool_rounds(initial_budget.max_tool_rounds)
                .with_max_continuation_turns(initial_budget.max_continuation_turns)
                .with_auto_delegation_enabled(true)
                .with_auto_parallel_delegation(true)
                .with_manual_delegation_enabled(true),
                &workspace_manifest,
            )),
            launch_model.as_deref(),
            launch_llm_override.as_ref(),
        ),
    ) {
        Ok(s) => s,
        Err(_) => agent.session(
            workspace.clone(),
            Some(apply_launch_model_options(
                with_instr(with_recent_workspace_context(
                    tui_session_options_with_gate(
                        confirmation.clone(),
                        deep_research_report_tool_gate.clone(),
                    )
                    .with_session_store(store.clone())
                    .with_session_id(session_id.as_str())
                    .with_workspace_backend(workspace_services.clone())
                    .with_skill_dirs(claude_dirs.clone())
                    .with_auto_save(true)
                    .with_auto_compact(true)
                    .with_auto_compact_threshold(auto_compact_threshold_for(context_limit))
                    .with_file_memory(memory_dir())
                    .with_max_parallel_tasks(initial_budget.max_parallel_tasks)
                    .with_max_tool_rounds(initial_budget.max_tool_rounds)
                    .with_max_continuation_turns(initial_budget.max_continuation_turns)
                    .with_auto_delegation_enabled(true)
                    .with_auto_parallel_delegation(true)
                    .with_manual_delegation_enabled(true),
                    &workspace_manifest,
                )),
                launch_model.as_deref(),
                launch_llm_override.as_ref(),
            )),
        )?,
    };

    // DynamicWorkflowRuntime is always available in the TUI because built-in
    // `?` deep research and ultracode dynamic workflows both route through it.
    session.register_dynamic_workflow_runtime();

    // A3S Runtime offload tool: registered only when signed in to OS, so the
    // model sees `runtime` after login and not before. Auth changes re-sync it via
    // `refresh_after_auth` → `sync_runtime_tool`.
    if let Some(os) = os_session.as_ref() {
        session.register_dynamic_tool(std::sync::Arc::new(crate::runtime_tool::RuntimeTool::new(
            os,
        )));
    }

    let (width, height) = a3s_tui::terminal::Terminal::size().unwrap_or((80, 24));

    // Seed the transcript with any resumed conversation (user + assistant text).
    let resumed = session.history();
    let mut initial_messages: Vec<String> = resumed
        .iter()
        .filter_map(|m| {
            let text = m.text();
            if text.trim().is_empty() {
                return None;
            }
            match m.role.as_str() {
                // Same gutter (● dot + indent) as live messages.
                "user" => Some(gutter(ACCENT, text.trim())),
                "assistant" => {
                    let mut md = StreamingMarkdown::new(transcript_markdown_width_for(width));
                    md.push(&text);
                    Some(gutter(TN_GREEN, &md.view()))
                }
                _ => None,
            }
        })
        .collect();
    // Seed ↑/↓ input recall with the user's prior prompts so resuming a session
    // keeps its command history (tool-result `user` messages carry no text block,
    // so the non-empty filter excludes them).
    let history_seed: Vec<String> = resumed
        .iter()
        .filter(|m| m.role == "user")
        .map(|m| m.text().trim().to_string())
        .filter(|t| !t.is_empty())
        .collect();

    // Quiet confirmation that the persisted login was restored. Only when
    // RESUMING an existing conversation — on a fresh start, leaving the transcript
    // empty lets the welcome banner show (it notes the signed-in account itself);
    // inserting this line here is what was suppressing the banner after OS login.
    if let Some(s) = &os_session {
        if !initial_messages.is_empty() {
            initial_messages.insert(
                0,
                Style::new().fg(TN_GRAY).render(&format!(
                    "  ✓ signed in to OS as {} · capabilities skill active · /logout to sign out",
                    s.display_label()
                )),
            );
        }
    }

    let session = Arc::new(session);

    // Headless smoke mode: exercise the agent-stream integration (the hard part
    // the TUI depends on) without taking over the terminal. Useful for CI/probes
    // and for validating a model/config end-to-end.
    if std::env::var_os("A3S_CODE_TUI_SMOKE").is_some() {
        return run_smoke(
            session,
            os_session.is_some(),
            deep_research_report_tool_gate,
        )
        .await;
    }

    let keymap = Keymap::new()
        .bind(
            KeyBinding::new(KeyCode::PageUp),
            Action::ScrollUp,
            "Scroll up",
        )
        .bind(
            KeyBinding::new(KeyCode::PageDown),
            Action::ScrollDown,
            "Scroll down",
        )
        // NB: Ctrl+U / Ctrl+D are intentionally NOT bound to scroll — they shadow
        // readline line-editing (Ctrl+U = delete-to-start) in the input. PageUp/Down
        // and Ctrl+Home/End cover scrolling.
        .bind(
            KeyBinding::ctrl(KeyCode::Home),
            Action::ScrollTop,
            "Scroll to top",
        )
        .bind(
            KeyBinding::ctrl(KeyCode::End),
            Action::ScrollBottom,
            "Scroll to bottom",
        );

    remote_ui::prime_webview_lookup();

    let mut app = App {
        session,
        agent: agent.clone(),
        store: store.clone(),
        confirmation,
        deep_research_report_tool_gate,
        session_id: session_id.clone(),
        models,
        model_ctx,
        context_limit,
        last_prompt_tokens: 0,
        ctx_warned_tier: 0,
        model_menu: None,
        model_tab: 0,
        llm_override: launch_llm_override,
        os_config,
        os_session,
        os_refreshing: false,
        os_gateway_models: None,
        os_gateway_models_loading: false,
        os_gateway_error: None,
        last_view: None,
        pending_deep_research_report_view: None,
        deep_research_loop: None,
        deep_research_report_repair_used: false,
        deep_research_workflow_output: None,
        deep_research_workflow_metadata: None,
        deep_research_report_ready: false,
        pending_deep_research_report_repair_prompt: None,
        deep_research_stream_timeout_token: 0,
        runtime_expectation: None,
        effort: DEFAULT_TUI_EFFORT_INDEX, // high
        effort_panel: None,
        theme_panel: None,
        quit_armed: None,
        last_activity: Instant::now(),
        auto_reviewed: false,
        shell_mode: false,
        research_mode: false,
        review_pending: false,
        sleep_pending: false,
        review: None,
        review_open: false,
        flow: None,
        pending_flow_subcommand: None,
        agent_picker: None,
        pending_agent_subcommand: None,
        agent_dev: None,
        mcp_picker: None,
        pending_mcp_subcommand: None,
        mcp_dev: None,
        skill_picker: None,
        pending_skill_subcommand: None,
        skill_dev: None,
        okf_picker: None,
        pending_okf_subcommand: None,
        okf_dev: None,
        autonomy_restore: None,
        ctx_ready,
        ctx_hits: Vec::new(),
        pending_ctx: None,
        loop_continuation: false,
        turn_text: String::new(),
        selection: None,
        last_workflow: None,
        pending_images: Vec::new(),
        goal: None,
        goal_since: None,
        loop_remaining: 0,
        runtime: RuntimeProjection::default(),
        turn_had_agent_activity: false,
        turn_text_after_activity: false,
        ultracode_synthesis_inflight: false,
        ultracode_synthesis_used: false,
        instructions,
        workspace_manifest,
        workspace_manifest_rx,
        workspace_services,
        gradient_until: None,
        gradient_frame: 0,
        effort_anim: None,
        compact_summary: None,
        btw: None,
        viewport: Viewport::new(width.saturating_sub(1), height.saturating_sub(7)),
        textarea: Textarea::new()
            .with_height(1)
            .with_auto_grow(8) // box grows with Shift+Enter newlines (no scroll)
            .with_width(width.saturating_sub((PAD + 2) as u16)) // PAD margin + "❯ "
            .with_submit_on_enter(true),
        spinner: Spinner::new().with_title(""),
        streaming: StreamingMarkdown::new(transcript_markdown_width_for(width)),
        deferred_tool_blocks: Vec::new(),
        defer_tool_blocks_until_stream_finalized: false,
        got_delta: false,
        compacting: None,
        updating: None,
        last_paint: None,
        thinking: String::new(),
        state: State::Idle,
        messages: initial_messages,
        rx: None,
        stream_join: None,
        host_tool_abort: None,
        host_progress_inflight: false,
        interrupting: false,
        pending_tool: None,
        approval_sel: 0,
        history: history_seed,
        history_pos: None,
        model: launch_model,
        output_tokens: 0,
        stream_started: None,
        blink_tick: 0,
        anim: 0,
        mode: Mode::Default,
        queue: BinaryHeap::new(),
        seq: 0,
        running_task: None,
        plan: Vec::new(),
        top: None,
        top_history: TopProcessHistory::default(),
        top_scroll: 0,
        top_sel: 0,
        top_focus: None,
        ide: None,
        memory: None,
        asset_list: None,
        runtime_activity: None,
        kb: None,
        loop_panel: None,
        help_open: false,
        help_scroll: 0,
        completed: 0,
        branch: git_branch(&workspace),
        slash_sel: 0,
        files: initial_files,
        at_expanded: std::collections::HashSet::new(),
        file_sel: 0,
        skill_count: count_skill_files(&claude_dirs),
        skills: load_skills(&claude_dirs),
        disabled_skills: load_disabled_skills(),
        plugins_panel: None,
        update_available: None,
        cwd: workspace.clone(),
        width,
        height,
        keymap,
    };

    // First launch: drop the user straight into the editor on the new config.
    if created_config {
        app.messages.push(gutter(
            ACCENT,
            "Welcome to a3s code! Generated a starter ~/.a3s/config.acl — fill in your \
             provider apiKey/baseUrl + model, Ctrl+S to save, Esc to close, then restart \
             `a3s code` to load it.",
        ));
        app.open_config_in_ide(std::path::Path::new(&config_path));
        app.rebuild_viewport();
    }

    // Apply the current effort (default `high`) to the launch session so the
    // FIRST turn already runs at the chosen depth. The session built above is
    // effort-naive — the scaled tool-round budget and the depth guideline live
    // only in effort_session_opts (reached via rebuild_session, as every
    // /effort switch does). Best-effort: keep the launch session if it can't
    // rebuild. (Resumes the same id, so transcript history is preserved.)
    let launch_model = app.model.clone();
    if let Ok((s, _)) = app.rebuild_session(launch_model.as_deref()) {
        app.replace_session(s);
    }

    ProgramBuilder::new(app)
        .with_alt_screen()
        // Capture mouse input so wheel/trackpad scrolling works in the alternate
        // screen. Drag-copy is app-owned: on release we write the selected text to
        // the clipboard, so scroll and copy can coexist.
        .with_mouse_support()
        .with_fps(30)
        .run()
        .await?;

    // `/update` found a newer version → upgrade via Homebrew in the (now
    // restored) shell so brew's own download progress shows, then re-exec the
    // freshly-installed binary. Use PATH `a3s` (brew repointed its symlink to
    // the new version); current_exe() is the OLD version's path.
    if UPGRADE_ON_EXIT.load(std::sync::atomic::Ordering::Relaxed) {
        let latest = LATEST
            .lock()
            .ok()
            .and_then(|g| g.clone())
            .unwrap_or_default();
        match crate::update::perform_upgrade(&latest) {
            Ok(bin) => {
                let restart_args = ["code", "resume", session_id.as_str()];
                #[cfg(unix)]
                {
                    use std::os::unix::process::CommandExt;
                    // exec replaces this process; only returns on failure → fall back.
                    let err = std::process::Command::new(&bin).args(restart_args).exec();
                    eprintln!(
                        "\n⚠  updated, but restart via {} failed: {err}",
                        bin.display()
                    );
                    if let Ok(exe) = std::env::current_exe() {
                        let err = std::process::Command::new(&exe).args(restart_args).exec();
                        eprintln!("⚠  fallback restart via {} failed: {err}", exe.display());
                    }
                    eprintln!(
                        "✓ updated to a3s {latest}; resume manually with: a3s code resume {session_id}\n"
                    );
                }
                #[cfg(not(unix))]
                {
                    match std::process::Command::new(&bin).args(restart_args).status() {
                        Ok(status) if status.success() => {}
                        Ok(status) => eprintln!(
                            "\n⚠  updated, but restart exited with status {status}; resume manually with: a3s code resume {session_id}\n"
                        ),
                        Err(err) => eprintln!(
                            "\n⚠  updated, but restart failed: {err}; resume manually with: a3s code resume {session_id}\n"
                        ),
                    }
                }
            }
            Err(error) => {
                eprintln!("\n✗ upgrade failed: {error}");
                eprintln!("get the latest from https://github.com/A3S-Lab/Cli/releases/latest\n");
            }
        }
        return Ok(());
    }

    // Session is auto-saved under this directory; show how to come back.
    println!("\n  session saved · resume it with:  a3s code resume {session_id}\n");
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn rgb(color: Color) -> (u8, u8, u8) {
        match color {
            Color::Rgb(r, g, b) => (r, g, b),
            other => panic!("expected RGB color, got {other:?}"),
        }
    }

    fn contains_cjk(s: &str) -> bool {
        s.chars().any(|ch| {
            ('\u{3400}'..='\u{4dbf}').contains(&ch)
                || ('\u{4e00}'..='\u{9fff}').contains(&ch)
                || ('\u{f900}'..='\u{faff}').contains(&ch)
        })
    }

    #[test]
    fn tui_palette_tracks_design_tokens() {
        assert_eq!(rgb(ACCENT), (0, 112, 243));
        assert_eq!(TN_GREEN, ACCENT);
        assert_eq!(rgb(TN_YELLOW), (245, 166, 35));
        assert_eq!(rgb(TN_RED), (238, 0, 0));
        assert_eq!(rgb(TN_CYAN), (80, 227, 194));
        assert_eq!(rgb(TN_FG), (237, 237, 237));
        assert_eq!(rgb(TN_GRAY), (143, 143, 143));
        assert_eq!(
            BRAND_GRADIENT,
            [
                Color::Rgb(0, 124, 240),
                Color::Rgb(0, 223, 216),
                TN_PURPLE,
                Color::Rgb(255, 0, 128),
                Color::Rgb(255, 77, 77),
                Color::Rgb(249, 203, 40),
            ]
        );
    }

    #[test]
    fn agent_chrome_theme_maps_tui_roles_to_code_palette() {
        let theme = agent_chrome_theme();
        assert_eq!(theme.primary, ACCENT);
        assert_eq!(theme.fg, TN_FG);
        assert_eq!(theme.muted, TN_GRAY);
        assert_eq!(theme.border, TN_GRAY);
        assert_eq!(theme.success, TN_GREEN);
        assert_eq!(theme.warning, TN_ORANGE);
        assert_eq!(theme.error, TN_RED);
        assert_eq!(theme.surface, SURFACE_SOFT);
        assert_eq!(theme.highlight, SURFACE_SELECTED);

        let chrome = agent_chrome(&theme);
        let rendered = chrome.tool_status("Running").view(24);
        assert!(
            rendered.contains(&ACCENT.fg_ansi()),
            "agent chrome should render code primary color: {rendered:?}"
        );
    }

    #[test]
    fn remote_view_button_is_styled_but_clickable_by_marker() {
        let rendered = remote_view_button("click to open");
        let plain = a3s_tui::style::strip_ansi(&rendered);
        assert!(plain.contains(VIEW_BUTTON_MARKER), "{plain}");
        assert!(plain.contains("click to open"), "{plain}");
        assert!(
            rendered.contains("\x1b["),
            "button should carry ANSI styling"
        );
    }

    #[test]
    fn remote_view_click_tolerates_small_terminal_mouse_drift() {
        let rendered = remote_view_button("click to open");
        let view = format!("plain transcript\n{rendered}\nnext line");

        assert!(is_remote_view_click(
            &view,
            Selection {
                anchor: (1, 4),
                head: (1, 6),
            }
        ));
        assert!(!is_remote_view_click(
            &view,
            Selection {
                anchor: (1, 4),
                head: (1, 12),
            }
        ));
        assert!(!is_remote_view_click(
            &view,
            Selection {
                anchor: (1, 4),
                head: (2, 4),
            }
        ));
        assert!(!is_remote_view_click(
            &view,
            Selection {
                anchor: (0, 4),
                head: (0, 4),
            }
        ));
    }

    #[test]
    fn remote_view_click_marker_is_case_insensitive_after_ansi_strip() {
        let view = format!(
            "  {}\n",
            Style::new()
                .fg(Color::BrightWhite)
                .bg(ACCENT)
                .render(" ↗ Open View ")
        );

        assert!(is_remote_view_click(
            &view,
            Selection {
                anchor: (0, 3),
                head: (0, 3),
            }
        ));
    }

    #[test]
    fn quit_key_accepts_control_c_terminal_variants() {
        let key = |code, modifiers| KeyEvent { code, modifiers };

        assert!(is_quit_key(&key(KeyCode::Char('c'), KeyModifiers::CONTROL)));
        assert!(is_quit_key(&key(
            KeyCode::Char('C'),
            KeyModifiers::CONTROL | KeyModifiers::SHIFT
        )));
        assert!(!is_quit_key(&key(KeyCode::Char('c'), KeyModifiers::NONE)));
        assert!(!is_quit_key(&key(
            KeyCode::Char('v'),
            KeyModifiers::CONTROL
        )));
    }

    #[test]
    fn quit_confirmation_requires_second_press_inside_window() {
        let now = Instant::now();

        assert!(!quit_is_confirmed(None, now));
        if let Some(recent) = now.checked_sub(Duration::from_millis(500)) {
            assert!(quit_is_confirmed(Some(recent), now));
        }
        if let Some(stale) = now.checked_sub(Duration::from_secs(3)) {
            assert!(!quit_is_confirmed(Some(stale), now));
        }
    }

    #[test]
    fn footer_uses_shared_status_components() {
        let status = render_session_status_line(
            "/Users/roylin/code/a3s",
            Some("main"),
            Some("openai/gpt-5"),
            128_000,
            90_000,
            0,
            [SessionStatusChip::new("⚙", "1 running").color(TN_GRAY)],
            72,
        );
        let status_plain = a3s_tui::style::strip_ansi(&status);

        assert_eq!(a3s_tui::style::visible_len(&status), 72);
        assert!(status_plain.contains("a3s git:(main)"), "{status_plain}");
        assert!(
            status_plain.contains("gpt-5 (128k context)"),
            "{status_plain}"
        );
        assert!(status_plain.contains("ctx:70%"), "{status_plain}");
        assert!(status_plain.contains("⚙ 1 running"), "{status_plain}");
        assert!(status.contains("\x1b["), "status should be styled");

        let mode = render_mode_status_line(Mode::Auto, 48);
        let mode_plain = a3s_tui::style::strip_ansi(&mode);
        assert_eq!(a3s_tui::style::visible_len(&mode), 48);
        assert!(mode_plain.starts_with("  ⏵⏵ auto mode on"), "{mode_plain}");
        assert!(mode_plain.contains("/help"), "{mode_plain}");
        assert!(mode.contains("\x1b["), "mode line should be styled");
    }

    #[test]
    fn jump_to_latest_hint_uses_shared_inline_action() {
        let hint = jump_to_latest_hint(48);
        let plain = a3s_tui::style::strip_ansi(&hint);

        assert_eq!(a3s_tui::style::visible_len(&hint), 48);
        assert!(plain.contains("↓ more below"), "{plain}");
        assert!(plain.contains("Shift+End"), "{plain}");
        let left_pad = plain.chars().take_while(|ch| *ch == ' ').count();
        let right_pad = plain.chars().rev().take_while(|ch| *ch == ' ').count();
        assert!(left_pad > 0, "{plain:?}");
        assert!(right_pad > 0, "{plain:?}");
        assert!(left_pad.abs_diff(right_pad) <= 1, "{plain:?}");
        assert!(hint.contains("\x1b["), "hint should be styled");
        assert_eq!(jump_to_latest_hint(0), "");
    }

    #[test]
    fn markdown_fragment_open_inline_detection_defers_split_tool_blocks() {
        assert!(markdown_fragment_has_open_inline("`今日"));
        assert!(markdown_fragment_has_open_inline(
            "FIFA World Cup，当前处于**淘汰赛"
        ));
        assert!(markdown_fragment_has_open_inline("```text\npartial"));

        assert!(!markdown_fragment_has_open_inline(
            "`今日 世界杯 战况 7月7日`"
        ));
        assert!(!markdown_fragment_has_open_inline(
            "**FIFA World Cup，当前处于淘汰赛阶段。**"
        ));
        assert!(!markdown_fragment_has_open_inline(
            "escaped \\` backtick is plain text"
        ));
    }

    #[test]
    fn tui_session_options_sets_separate_tool_timeout() {
        let confirmation = a3s_code_core::hitl::ConfirmationPolicy::enabled()
            .with_timeout(HITL_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
        let opts = tui_session_options(confirmation);
        let dbg = format!("{opts:?}");

        assert_ne!(HITL_CONFIRM_TIMEOUT_MS, TOOL_EXEC_TIMEOUT_MS);
        assert!(
            dbg.contains(&format!("tool_timeout_ms: Some({TOOL_EXEC_TIMEOUT_MS})")),
            "{dbg}"
        );
        assert!(
            dbg.contains(&format!(
                "duplicate_tool_call_threshold: Some({TUI_DUPLICATE_TOOL_CALL_THRESHOLD})"
            )),
            "{dbg}"
        );
    }

    #[test]
    fn approval_menu_uses_shared_choice_prompt() {
        let lines = approval_menu_lines(
            "Bash(cargo test very-long-filter-name-that-should-not-overflow)",
            1,
            42,
        );
        let plain = lines
            .iter()
            .map(|line| a3s_tui::style::strip_ansi(line))
            .collect::<Vec<_>>();

        assert_eq!(plain.len(), 5);
        assert!(plain[0].contains("Allow"), "{plain:?}");
        assert!(plain[1].contains("1. Yes"), "{plain:?}");
        assert!(plain[2].contains("2. Yes, and"), "{plain:?}");
        assert!(plain[3].contains("3. No"), "{plain:?}");
        assert!(plain[4].contains("Enter select"), "{plain:?}");
        assert!(
            lines
                .iter()
                .all(|line| a3s_tui::style::visible_len(line) <= 42),
            "{plain:?}"
        );
        assert!(lines[2].contains("\x1b["), "selected row is styled");
    }

    #[test]
    fn approval_prompt_mouse_wheel_moves_selection_at_overlay_offset() {
        use a3s_tui::event::{MouseEvent, MouseEventKind};

        let width = 42;
        let lines = approval_menu_lines("Bash(cargo test)", 0, width);
        let y_offset = approval_overlay_y_offset(18, lines.len());
        let mut prompt = approval_prompt("Bash(cargo test)", 0);
        prompt.set_y_offset(y_offset);

        let msg = prompt.handle_mouse(&MouseEvent {
            kind: MouseEventKind::ScrollDown,
            column: 0,
            row: y_offset + 1,
            modifiers: KeyModifiers::NONE,
        });

        assert_eq!(msg, None);
        assert_eq!(prompt.selected_index(), 1);
    }

    #[test]
    fn approval_prompt_click_selects_choice_at_overlay_offset() {
        use a3s_tui::event::{MouseButton, MouseEvent, MouseEventKind};

        let width = 42;
        let lines = approval_menu_lines("Bash(cargo test)", 0, width);
        let y_offset = approval_overlay_y_offset(18, lines.len());
        let mut prompt = approval_prompt("Bash(cargo test)", 0);
        prompt.set_y_offset(y_offset);

        let msg = prompt.handle_mouse(&MouseEvent {
            kind: MouseEventKind::Down(MouseButton::Left),
            column: 2,
            row: y_offset + 2,
            modifiers: KeyModifiers::NONE,
        });

        assert_eq!(msg, Some(ChoicePromptMsg::Selected(1)));
    }

    #[test]
    fn effort_ladder_is_monotonic_and_well_formed() {
        // ULTRACODE indexes the last level, which is the ultracode profile.
        assert_eq!(ULTRACODE, EFFORT_LEVELS.len() - 1);
        assert_eq!(EFFORT_LEVELS[ULTRACODE].label, "ultracode");
        // Depth rises with effort: thinking budget and tool-round budget both
        // non-decreasing across low → max (so higher effort is never shallower).
        for w in EFFORT_LEVELS[..=ULTRACODE].windows(2) {
            assert!(
                w[1].thinking_budget >= w[0].thinking_budget,
                "thinking budget regressed"
            );
            assert!(
                w[1].max_tool_rounds >= w[0].max_tool_rounds,
                "tool-round budget regressed"
            );
            assert!(
                w[1].max_continuation_turns >= w[0].max_continuation_turns,
                "continuation budget regressed"
            );
        }
        // medium is the unsteered baseline; every other level carries a guideline
        // so effort is meaningful even on models with no thinking budget.
        assert!(
            EFFORT_LEVELS[1].guideline.is_none(),
            "medium should be the baseline"
        );
        for (i, p) in EFFORT_LEVELS.iter().enumerate() {
            if i != 1 {
                assert!(
                    p.guideline.is_some(),
                    "level {} has no depth steer",
                    p.label
                );
            }
        }
    }

    use a3s_code_core::llm::{
        ContentBlock, LlmClient, LlmResponse, Message, StreamEvent, TokenUsage, ToolDefinition,
    };
    use async_trait::async_trait;
    use std::collections::VecDeque;
    use std::sync::{Arc, Mutex};
    use tokio::sync::mpsc;
    use tokio_util::sync::CancellationToken;

    #[derive(Clone, Default)]
    struct CapturedLlmTurn {
        system: Option<String>,
        tools: Vec<String>,
    }

    struct CaptureLlmClient {
        turns: Mutex<Vec<CapturedLlmTurn>>,
        responses: Mutex<VecDeque<LlmResponse>>,
    }

    #[async_trait]
    impl LlmClient for CaptureLlmClient {
        async fn complete(
            &self,
            _messages: &[Message],
            system: Option<&str>,
            tools: &[ToolDefinition],
        ) -> anyhow::Result<LlmResponse> {
            self.record(system, tools);
            Ok(self.next_response())
        }

        async fn complete_streaming(
            &self,
            _messages: &[Message],
            system: Option<&str>,
            tools: &[ToolDefinition],
            _cancel_token: CancellationToken,
        ) -> anyhow::Result<mpsc::Receiver<StreamEvent>> {
            self.record(system, tools);
            let response = self.next_response();
            let (tx, rx) = mpsc::channel(2);
            tokio::spawn(async move {
                let _ = tx.send(StreamEvent::Done(response)).await;
            });
            Ok(rx)
        }
    }

    impl CaptureLlmClient {
        fn new(responses: Vec<LlmResponse>) -> Self {
            Self {
                turns: Mutex::new(Vec::new()),
                responses: Mutex::new(responses.into()),
            }
        }

        fn record(&self, system: Option<&str>, tools: &[ToolDefinition]) {
            self.turns.lock().unwrap().push(CapturedLlmTurn {
                system: system.map(str::to_string),
                tools: tools.iter().map(|tool| tool.name.clone()).collect(),
            });
        }

        fn next_response(&self) -> LlmResponse {
            self.responses
                .lock()
                .unwrap()
                .pop_front()
                .unwrap_or_else(done_response)
        }

        fn turns(&self) -> Vec<CapturedLlmTurn> {
            self.turns.lock().unwrap().clone()
        }
    }

    fn tool_call_response(name: &str, input: serde_json::Value) -> LlmResponse {
        LlmResponse {
            message: Message {
                role: "assistant".into(),
                content: vec![ContentBlock::ToolUse {
                    id: "toolu_test".into(),
                    name: name.into(),
                    input,
                }],
                reasoning_content: None,
            },
            usage: TokenUsage::default(),
            stop_reason: Some("tool_use".into()),
            token_logprobs: Vec::new(),
            meta: None,
        }
    }

    fn done_response() -> LlmResponse {
        LlmResponse {
            message: Message {
                role: "assistant".into(),
                content: vec![ContentBlock::Text {
                    text: "DONE".into(),
                }],
                reasoning_content: None,
            },
            usage: TokenUsage::default(),
            stop_reason: Some("stop".into()),
            token_logprobs: Vec::new(),
            meta: None,
        }
    }

    fn test_config(path: &std::path::Path) {
        std::fs::write(
            path,
            "default_model = \"openai/x\"\n\
             providers \"openai\" {\n  apiKey = \"x\"\n  baseUrl = \"http://127.0.0.1:1\"\n  \
             models \"x\" { name = \"x\" }\n}\n",
        )
        .unwrap();
    }

    /// Guard: ultracode registers A3S Flow plus `task`/`parallel_task` in the
    /// session tool surface (so dynamic workflows and fan-out have tools to call).
    #[tokio::test]
    async fn parallel_opts_register_parallel_task() {
        let dir = std::env::temp_dir().join(format!("a3s-ptask-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&dir);
        let cfg = dir.join("config.acl");
        test_config(&cfg);
        let agent = a3s_code_core::Agent::new(cfg.to_string_lossy().to_string())
            .await
            .unwrap();
        let budget = budget_plan_for_effort_index(ULTRACODE, None, BudgetWorkload::Interactive);
        // The FULL ultracode config (planning + goal + parallel fan-out).
        let opts = SessionOptions::new()
            .with_max_parallel_tasks(budget.max_parallel_tasks)
            .with_auto_delegation_enabled(true)
            .with_auto_parallel_delegation(true)
            .with_manual_delegation_enabled(true)
            .with_planning_mode(a3s_code_core::PlanningMode::Enabled)
            .with_goal_tracking(true)
            .with_max_tool_rounds(budget.max_tool_rounds);
        let session = agent
            .session(dir.to_string_lossy().to_string(), Some(opts))
            .unwrap();
        session.register_dynamic_workflow_runtime();
        let names = session.tool_names();
        let _ = std::fs::remove_dir_all(&dir);
        assert!(
            names.contains(&"dynamic_workflow".to_string()),
            "dynamic_workflow registered; got {names:?}"
        );
        assert!(
            names.contains(&"parallel_task".to_string()),
            "parallel_task registered; got {names:?}"
        );
        assert!(
            names.contains(&"task".to_string()),
            "task registered; got {names:?}"
        );
    }

    // ── `/output` formatting ───────────────────────────────────────────────
    #[test]
    fn format_tool_log_empty_is_none() {
        assert!(format_tool_log_records(&[], 80).is_none());
    }

    #[test]
    fn format_tool_log_renders_bounded_headers_args_and_output() {
        let recs = vec![
            ToolCallRecord {
                name: "read".into(),
                args: Some(serde_json::json!({"file_path": "/x"})),
                output: "hello\n".into(),
                exit_code: 0,
            },
            ToolCallRecord {
                name: "bash".into(),
                args: None,
                output: String::new(),
                exit_code: 2,
            },
        ];
        let out = format_tool_log_records(&recs, 48).unwrap();
        let plain = a3s_tui::style::strip_ansi(&out);
        assert!(plain.contains("#1 · Read /x · ok"), "{plain}");
        assert!(plain.contains("args: {\"file_path\":\"/x\"}"), "{plain}");
        assert!(
            plain.contains("    hello"),
            "output should be indented: {plain}"
        );
        assert!(plain.contains("#2 · Ran · exit 2"), "{plain}");
        for line in out.lines() {
            assert!(
                a3s_tui::style::visible_len(line) <= 48,
                "log line should be bounded: {line:?}"
            );
        }
    }

    #[test]
    fn format_tool_log_tails_long_output() {
        let recs = vec![ToolCallRecord {
            name: "bash".into(),
            args: Some(serde_json::json!({
                "command": "cargo test a-very-long-filter-that-must-not-overflow -- --nocapture"
            })),
            output: (0..30)
                .map(|i| format!("line-{i}-with-a-long-payload-that-must-stay-inside-the-editor"))
                .collect::<Vec<_>>()
                .join("\n"),
            exit_code: 0,
        }];
        let out = format_tool_log_records(&recs, 52).unwrap();
        let plain = a3s_tui::style::strip_ansi(&out);

        assert!(plain.contains("... +6 earlier lines"), "{plain}");
        assert!(!plain.contains("line-0-with"), "{plain}");
        assert!(plain.contains("line-6-with"), "{plain}");
        for line in out.lines() {
            assert!(
                a3s_tui::style::visible_len(line) <= 52,
                "log line should be bounded: {line:?}"
            );
        }
    }

    #[test]
    fn format_tool_log_respects_narrow_editor_width() {
        let recs = vec![ToolCallRecord {
            name: "bash".into(),
            args: Some(serde_json::json!({
                "command": "printf a-very-long-line-that-used-to-force-a-minimum-width"
            })),
            output: "a-very-long-output-line-that-must-be-clipped\n".into(),
            exit_code: 0,
        }];
        let out = format_tool_log_records(&recs, 16).unwrap();

        for line in out.lines() {
            assert!(
                a3s_tui::style::visible_len(line) <= 16,
                "log line should respect narrow width: {line:?}"
            );
        }
    }

    #[test]
    fn pending_tool_label_is_taken_only_for_matching_tool_id() {
        let mut pending = Some(("tool-a".to_string(), "edit file".to_string()));

        assert!(take_pending_tool_label(&mut pending, "tool-b").is_none());
        assert_eq!(
            pending,
            Some(("tool-a".to_string(), "edit file".to_string()))
        );

        assert_eq!(
            take_pending_tool_label(&mut pending, "tool-a"),
            Some("edit file".to_string())
        );
        assert!(pending.is_none());
    }

    #[tokio::test]
    async fn confirmation_resume_rearms_spinner_and_stream_pump() {
        let cmd = resume_after_pending_confirmation_cmd(None);
        match cmd.await {
            a3s_tui::cmd::CmdResult::Batch(cmds) => {
                assert_eq!(cmds.len(), 1, "spinner should resume without an rx");
            }
            _ => panic!("expected batched resume command"),
        }

        let (_tx, rx) = mpsc::channel::<AgentEvent>(1);
        let cmd = resume_after_pending_confirmation_cmd(Some(std::sync::Arc::new(
            tokio::sync::Mutex::new(rx),
        )));
        match cmd.await {
            a3s_tui::cmd::CmdResult::Batch(cmds) => {
                assert_eq!(cmds.len(), 2, "spinner and stream pump should resume");
            }
            _ => panic!("expected batched resume command"),
        }
    }

    // ── `?` deep-research mode ─────────────────────────────────────────────
    #[test]
    fn deep_research_prompt_directs_research_and_keeps_query() {
        let p = deep_research_prompt("rust async runtimes", false);
        assert!(p.contains("rust async runtimes"), "{p}");
        let lo = p.to_lowercase();
        assert!(lo.contains("deep research"), "{p}");
        assert!(p.contains("dynamic_workflow"), "{p}");
        assert!(
            p.contains("genuinely independent")
                && p.contains("choose the count yourself")
                && p.contains("local max"),
            "{p}"
        );
        assert!(lo.contains("web search") && lo.contains("web_fetch"), "{p}");
        assert!(lo.contains("source"), "should ask to cite sources: {p}");
        assert!(
            p.contains("step_name: \"parallel_task\"") || p.contains("parallel_task"),
            "{p}"
        );
        assert!(p.contains(".a3s/research/<slug>/"), "{p}");
        assert!(p.contains("standalone HTML"), "{p}");
        assert!(p.contains("source traceability"), "{p}");
        assert!(p.contains("Do not search the workspace"), "{p}");
        assert!(p.contains("creation or verification checks"), "{p}");
        assert!(p.contains("Do not list"), "{p}");
        assert!(p.contains(RESEARCH_VIEW_MARKER), "{p}");
        assert!(p.contains("RemoteUI automatically"), "{p}");
        assert!(p.contains("Never print it for"), "{p}");
        assert!(p.contains("fallback draft"), "{p}");
        assert!(p.contains("host validates file existence"), "{p}");
        assert!(p.contains("sibling `report.md`"), "{p}");
        assert!(p.contains("Do not repeat an identical grep"), "{p}");
    }

    #[test]
    fn deep_research_prompt_disables_os_runtime_tool_fanout() {
        let p = deep_research_prompt("comprehensive rust async runtimes comparison", true);
        assert!(p.contains("rust async runtimes"), "{p}");
        assert!(p.contains("dynamic_workflow"), "{p}");
        assert!(
            p.contains("OS Runtime tool-call fan-out is temporarily disabled"),
            "{p}"
        );
        assert!(p.contains("os_runtime: false"), "{p}");
        assert!(!p.contains("allowed_tools: [\"runtime\"]"), "{p}");
        assert!(p.contains("Function-as-a-Service"), "{p}");
        assert!(
            p.contains("Markdown report") && p.contains("HTML page"),
            "{p}"
        );
        assert!(p.contains(RESEARCH_VIEW_MARKER), "{p}");
        assert!(p.contains("Do not repeat an identical grep"), "{p}");
    }

    #[test]
    fn deep_research_os_runtime_selection_is_disabled() {
        assert!(!should_use_os_runtime_for_deep_research(
            "rust async runtimes",
            true
        ));
        assert!(!should_use_os_runtime_for_deep_research(
            "全面调研 2026 年多智能体运行时市场、最新论文、竞品和趋势",
            true
        ));
        assert!(!should_use_os_runtime_for_deep_research(
            "全面调研 2026 年多智能体运行时市场",
            false
        ));
        assert!(!should_use_os_runtime_for_deep_research(
            "本地分析一下这个 README",
            true
        ));
        assert!(!should_use_os_runtime_for_deep_research(
            "Use local workspace evidence only. Read README.md and report what it says.",
            true
        ));
    }

    #[test]
    fn deep_research_loop_layers_scale_with_task_complexity() {
        assert_eq!(deep_research_loop_layers("rust async runtimes", false), 0);
        assert_eq!(
            deep_research_loop_layers("本地分析一下这个 README，不要远程", true),
            0
        );
        assert_eq!(
            deep_research_loop_layers("Use local workspace evidence only. Read README.md.", true),
            0
        );
        assert_eq!(
            deep_research_loop_layers("比较 tokio 和 async-std 的设计取舍", false),
            1
        );
        assert_eq!(
            deep_research_loop_layers(
                "全面调研 2026 年多智能体运行时市场、最新论文、竞品和趋势",
                true
            ),
            3
        );
    }

    #[test]
    fn deep_research_verification_prompt_is_bounded_and_report_focused() {
        let loop_state = DeepResearchLoop {
            query: "全面调研 runtime 市场".to_string(),
            total_layers: 3,
            os_runtime: true,
        };
        let prompt = loop_state.verification_prompt(2);
        assert!(prompt.contains("verification layer 2/3"), "{prompt}");
        assert!(prompt.contains("Do not restart broad research"), "{prompt}");
        assert!(prompt.contains("reply exactly DONE"), "{prompt}");
        assert!(prompt.contains(RESEARCH_VIEW_MARKER), "{prompt}");
        assert!(prompt.contains("source traceability"), "{prompt}");
        assert!(
            prompt.contains("Do not repeat an identical grep"),
            "{prompt}"
        );
    }

    #[test]
    fn dynamic_workflow_metadata_backfills_parallel_subagent_results() {
        let metadata = serde_json::json!({
            "dynamic_workflow": {
                "snapshot": {
                    "steps": {
                        "local_research": {
                            "step_name": "parallel_task",
                            "input": {
                                "tasks": [
                                    { "description": "Track A" },
                                    { "description": "Track B" }
                                ]
                            },
                            "output": {
                                "metadata": {
                                    "results": [
                                        {
                                            "task_id": "task-a",
                                            "agent": "general",
                                            "success": true
                                        },
                                        {
                                            "task_id": "task-b",
                                            "agent": "general",
                                            "success": false
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        });

        let backfills = workflow_parallel_subagent_backfills(&metadata);

        assert_eq!(
            backfills,
            vec![
                WorkflowSubagentBackfill {
                    task_id: "task-a".to_string(),
                    agent: "general".to_string(),
                    description: "Track A".to_string(),
                    success: true,
                },
                WorkflowSubagentBackfill {
                    task_id: "task-b".to_string(),
                    agent: "general".to_string(),
                    description: "Track B".to_string(),
                    success: false,
                },
            ]
        );
    }

    #[test]
    fn research_report_marker_requires_workspace_index_html_and_markdown_pair() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-view-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let report_dir = root.join(".a3s/research/rust-async");
        std::fs::create_dir_all(&report_dir).unwrap();
        let html = report_dir.join("index.html");
        let md = report_dir.join("report.md");
        std::fs::write(
            &html,
            "<!doctype html><html><body><h1>Rust Async</h1><section><h2>Findings</h2><p>The report compares async runtime tradeoffs using source-backed evidence and highlights scheduler, ecosystem, and operational caveats.</p></section><section><h2>Sources</h2><p>Evidence: https://example.com/runtime-notes with confidence notes and limitations.</p></section></body></html>",
        )
        .unwrap();
        std::fs::write(
            &md,
            "# Rust Async\n\n## Findings\n\nThis source-backed report compares async runtime tradeoffs across scheduler behavior, ecosystem maturity, operational caveats, and confidence levels.\n\n## Sources\n\n- https://example.com/runtime-notes\n\n## Confidence\n\nConfidence is medium because evidence is concise but independently reviewable.\n",
        )
        .unwrap();

        let spec = research_report_view_spec(
            "done\nA3S_RESEARCH_VIEW: .a3s/research/rust-async/index.html",
            &root,
        )
        .expect("trusted report marker should become a view");
        assert!(spec.url.starts_with("http://127.0.0.1:"), "{spec:?}");
        assert!(spec.url.contains("/a3s-local-view/"), "{spec:?}");
        assert!(spec.url.ends_with("/index.html"));
        assert!(spec.embeddable);
        let artifacts = research_report_artifacts_from_output(
            "done\nA3S_RESEARCH_VIEW: .a3s/research/rust-async/index.html",
            &root,
        )
        .expect("trusted report marker should resolve artifacts");
        assert_eq!(artifacts.html, html.canonicalize().unwrap());
        assert_eq!(artifacts.markdown, md.canonicalize().unwrap());
        assert!(
            research_report_artifacts_from_output_for_query(
                "done\nA3S_RESEARCH_VIEW: .a3s/research/rust-async/index.html",
                &root,
                "rust async",
            )
            .is_some(),
            "DeepResearch markers should resolve when the slug matches the query"
        );
        assert!(
            research_report_artifacts_from_output_for_query(
                "done\nA3S_RESEARCH_VIEW: .a3s/research/rust-async/index.html",
                &root,
                "old unrelated query",
            )
            .is_none(),
            "DeepResearch markers must not reuse a report slug from another query"
        );

        let incomplete_dir = root.join(".a3s/research/incomplete");
        std::fs::create_dir_all(&incomplete_dir).unwrap();
        std::fs::write(incomplete_dir.join("index.html"), "<!doctype html>").unwrap();
        std::fs::write(incomplete_dir.join("report.md"), "# Incomplete").unwrap();
        assert!(
            research_report_view_spec(
                "A3S_RESEARCH_VIEW: .a3s/research/incomplete/index.html",
                &root,
            )
            .is_none(),
            "formal report markers require a complete standalone HTML document"
        );

        let draft_dir = root.join(".a3s/research/draft");
        std::fs::create_dir_all(&draft_dir).unwrap();
        std::fs::write(
            draft_dir.join("index.html"),
            "<!doctype html><html><body><h1>DeepResearch Fallback Draft</h1></body></html>",
        )
        .unwrap();
        std::fs::write(
            draft_dir.join("report.md"),
            "# DeepResearch Fallback Draft\n\nNot a completed DeepResearch report.",
        )
        .unwrap();
        assert!(
            research_report_view_spec("A3S_RESEARCH_VIEW: .a3s/research/draft/index.html", &root,)
                .is_none(),
            "fallback draft artifacts must not be accepted as completed report markers"
        );

        let dirty_dir = root.join(".a3s/research/dirty");
        std::fs::create_dir_all(&dirty_dir).unwrap();
        std::fs::write(
            dirty_dir.join("index.html"),
            "<!doctype html><html><body><h1>Dirty Report</h1><section><h2>Findings</h2><p>The analysis has enough apparent substance but contains leaked transcript output.</p><pre>● Searched web fifa results\n⎿ [tool output truncated: showing first bytes]</pre></section><section><h2>Sources</h2><p>Evidence source: https://example.com/dirty. Confidence is low because leaked logs were detected.</p></section></body></html>",
        )
        .unwrap();
        std::fs::write(
            dirty_dir.join("report.md"),
            "# Dirty Report\n\n## Findings\n\nThe analysis has enough apparent substance but contains leaked transcript output.\n\n● Searched web fifa results\n⎿ [tool output truncated: showing first bytes]\n\n## Sources\n\n- https://example.com/dirty\n\n## Confidence\n\nConfidence is low because leaked logs were detected.\n",
        )
        .unwrap();
        assert!(
            research_report_view_spec("A3S_RESEARCH_VIEW: .a3s/research/dirty/index.html", &root,)
                .is_none(),
            "DeepResearch report markers must reject artifacts that contain internal tool logs"
        );
        assert!(deep_research_output_has_internal_leak(
            "Report generated from provided DynamicWorkflowRuntime structured evidence."
        ));
        assert!(deep_research_output_has_internal_leak(
            "Targeted verification passed: report.md exists and index.html exists."
        ));
        assert!(deep_research_output_has_internal_leak(
            "Step 2 complete: Markdown report written to .a3s/research/example/report.md."
        ));
        assert!(deep_research_output_has_internal_leak(
            "Targeted verification could not be performed because file-read tooling is currently blocked; remaining unverified contract items are listed below."
        ));

        assert!(research_report_view_spec(
            "A3S_RESEARCH_VIEW: .a3s/research/rust-async/report.md",
            &root,
        )
        .is_none());
        let non_index = report_dir.join("summary.html");
        std::fs::write(&non_index, "<!doctype html>").unwrap();
        assert!(research_report_view_spec(
            "A3S_RESEARCH_VIEW: .a3s/research/rust-async/summary.html",
            &root,
        )
        .is_none());
        let nested_dir = report_dir.join("nested");
        std::fs::create_dir_all(&nested_dir).unwrap();
        std::fs::write(nested_dir.join("index.html"), "<!doctype html>").unwrap();
        assert!(research_report_view_spec(
            "A3S_RESEARCH_VIEW: .a3s/research/rust-async/nested/index.html",
            &root,
        )
        .is_none());
        let empty_dir = root.join(".a3s/research/empty");
        std::fs::create_dir_all(&empty_dir).unwrap();
        std::fs::write(empty_dir.join("index.html"), "").unwrap();
        std::fs::write(empty_dir.join("report.md"), "# Report").unwrap();
        assert!(research_report_view_spec(
            "A3S_RESEARCH_VIEW: .a3s/research/empty/index.html",
            &root,
        )
        .is_none());
        let shallow_dir = root.join(".a3s/research/shallow");
        std::fs::create_dir_all(&shallow_dir).unwrap();
        std::fs::write(
            shallow_dir.join("index.html"),
            "<!doctype html><html><body><h1>Report</h1><p>Completed.</p></body></html>",
        )
        .unwrap();
        std::fs::write(shallow_dir.join("report.md"), "# Report\n\nCompleted.").unwrap();
        assert!(
            research_report_view_spec(
                "A3S_RESEARCH_VIEW: .a3s/research/shallow/index.html",
                &root,
            )
            .is_none(),
            "completed report markers require more than placeholder-level content"
        );
        let keyword_only_dir = root.join(".a3s/research/keyword-only");
        std::fs::create_dir_all(&keyword_only_dir).unwrap();
        std::fs::write(
            keyword_only_dir.join("index.html"),
            "<!doctype html><html><body><h1>Report</h1><section><h2>Findings</h2><p>This report has fluent analysis and claims that evidence exists, but it deliberately avoids any traceable source anchor.</p></section><section><h2>Sources</h2><p>The source material is described only in prose without a URL or local path.</p></section><section><h2>Confidence</h2><p>Confidence is medium because limitations and risks are discussed in general terms.</p></section></body></html>",
        )
        .unwrap();
        std::fs::write(
            keyword_only_dir.join("report.md"),
            "# Report\n\n## Findings\n\nThis report has fluent analysis and claims that evidence exists, but it deliberately avoids any traceable source anchor.\n\n## Sources\n\nThe source material is described only in prose without a URL or local path.\n\n## Confidence\n\nConfidence is medium because limitations and risks are discussed in general terms.\n",
        )
        .unwrap();
        assert!(
            research_report_view_spec(
                "A3S_RESEARCH_VIEW: .a3s/research/keyword-only/index.html",
                &root,
            )
            .is_none(),
            "completed report markers require at least one traceable source URL or local path"
        );
        std::fs::remove_file(&md).unwrap();
        assert!(research_report_view_spec(
            "A3S_RESEARCH_VIEW: .a3s/research/rust-async/index.html",
            &root,
        )
        .is_none());
        assert!(research_report_view_spec("A3S_RESEARCH_VIEW: /etc/passwd", &root).is_none());
        assert!(
            research_report_view_spec("A3S_RESEARCH_VIEW: file:///etc/passwd", &root,).is_none()
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_completed_report_sources_must_trace_workflow_evidence() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-source-trace-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let report_dir = root.join(".a3s/research/source-trace");
        std::fs::create_dir_all(&report_dir).unwrap();
        let marker = "done\nA3S_RESEARCH_VIEW: .a3s/research/source-trace/index.html";
        let workflow_output = serde_json::json!({
            "mode": "local_parallel_task",
            "research": {
                "results": [{
                    "structured": {
                        "summary": "Workflow evidence names the traceable source.",
                        "sources": [{
                            "title": "Workflow Source",
                            "url_or_path": "https://example.com/workflow-source",
                            "quote_or_fact": "The evidence source that the report must cite."
                        }],
                        "key_evidence": ["traceable source"],
                        "contradictions": [],
                        "confidence": "high",
                        "gaps": []
                    }
                }]
            }
        })
        .to_string();

        std::fs::write(
            report_dir.join("report.md"),
            "# Source Trace\n\n## Findings\n\nThis report has polished analysis, conclusions, and confidence notes, but it cites an unrelated source instead of the gathered evidence.\n\n## Sources\n\n- https://example.com/fabricated-source\n\n## Confidence\n\nConfidence is low because source traceability should fail.\n",
        )
        .unwrap();
        std::fs::write(
            report_dir.join("index.html"),
            "<!doctype html><html><body><h1>Source Trace</h1><section><h2>Findings</h2><p>This report has polished analysis, conclusions, caveats, and confidence notes, but it cites an unrelated source.</p></section><section><h2>Sources</h2><p>Evidence source: https://example.com/fabricated-source. Confidence is low.</p></section></body></html>",
        )
        .unwrap();
        assert!(
            deep_research_report_artifacts_from_output_for_query(
                marker,
                &root,
                "source trace",
                &workflow_output,
                None,
            )
            .is_none(),
            "DeepResearch reports must cite at least one source from workflow evidence when evidence sources exist"
        );

        std::fs::write(
            report_dir.join("report.md"),
            "# Source Trace\n\n## Findings\n\nThis report has polished analysis, conclusions, caveats, and confidence notes anchored to the gathered workflow source.\n\n## Sources\n\n- https://example.com/workflow-source\n\n## Confidence\n\nConfidence is medium because the source traceability check can match the workflow evidence source.\n",
        )
        .unwrap();
        std::fs::write(
            report_dir.join("index.html"),
            "<!doctype html><html><body><h1>Source Trace</h1><section><h2>Findings</h2><p>This report has polished analysis, conclusions, caveats, and confidence notes anchored to gathered workflow evidence.</p></section><section><h2>Sources</h2><p>Evidence source: https://example.com/workflow-source. Confidence is medium.</p></section></body></html>",
        )
        .unwrap();
        assert!(
            deep_research_report_artifacts_from_output_for_query(
                marker,
                &root,
                "source trace",
                &workflow_output,
                None,
            )
            .is_some(),
            "DeepResearch reports should pass when at least one report source traces workflow evidence"
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_clean_final_text_can_reuse_valid_report_artifacts() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-clean-final-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let report_dir = root.join(".a3s/research/clean-final");
        std::fs::create_dir_all(&report_dir).unwrap();
        std::fs::write(
            report_dir.join("report.md"),
            "# Clean Final\n\n## Findings\n\nThis source-backed report gives the final answer, cites the gathered source, and avoids narrating artifact operations.\n\n## Sources\n\n- https://example.com/source\n\n## Confidence\n\nConfidence is high because source traceability is explicit.\n",
        )
        .unwrap();
        std::fs::write(
            report_dir.join("index.html"),
            "<!doctype html><html><body><h1>Clean Final</h1><section><h2>Findings</h2><p>This source-backed report gives the final answer, cites the gathered source, and avoids artifact-operation narration.</p></section><section><h2>Sources</h2><p>Evidence source: https://example.com/source. Confidence is high.</p></section></body></html>",
        )
        .unwrap();
        let workflow_output = serde_json::json!({
            "research": {
                "results": [{
                    "structured": {
                        "summary": "source-backed",
                        "sources": [{
                            "url_or_path": "https://example.com/source",
                            "quote_or_fact": "source trace"
                        }],
                        "confidence": "high"
                    }
                }]
            }
        })
        .to_string();
        let dirty_output = "Step 2 complete: Markdown report written.\nTargeted verification could not be performed because file-read tooling is currently blocked.\nA3S_RESEARCH_VIEW: .a3s/research/clean-final/index.html";
        assert!(deep_research_output_has_internal_leak(dirty_output));
        let artifacts = deep_research_report_artifacts_from_output_for_query(
            dirty_output,
            &root,
            "clean final",
            &workflow_output,
            None,
        )
        .expect("valid report files should still be discoverable from a dirty final marker");
        let clean = clean_deep_research_final_text_from_artifacts(&artifacts, &root)
            .expect("host should be able to rebuild clean final text from report.md");
        assert!(!deep_research_output_has_internal_leak(&clean), "{clean}");
        assert!(clean.contains("A3S_RESEARCH_VIEW: .a3s/research/clean-final/index.html"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_report_view_open_is_deferred_until_workflow_finishes() {
        assert_eq!(
            research_report_view_action(true),
            ResearchReportViewAction::DeferUntilDeepResearchComplete,
            "DeepResearch should not auto-open a report before verification layers drain"
        );
        assert_eq!(
            research_report_view_action(false),
            ResearchReportViewAction::OpenNow,
            "ordinary report markers can still open immediately"
        );
    }

    #[test]
    fn deep_research_tui_missing_report_arms_one_repair_pass() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-repair-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&root).unwrap();

        assert!(deep_research_report_is_missing(
            true,
            false,
            Some("complete"),
            "DONE without report artifacts",
            &root,
            "",
            None
        ));
        assert!(
            !deep_research_report_is_missing(
                false,
                false,
                None,
                "DONE without report artifacts",
                &root,
                "",
                None
            ),
            "non-DeepResearch turns must not arm report repair"
        );
        assert!(
            !deep_research_report_is_missing(
                true,
                true,
                Some("complete"),
                "DONE without report artifacts",
                &root,
                "",
                None
            ),
            "a later verification DONE must not re-arm repair after a report was captured"
        );

        let mut loop_remaining = 0;
        let mut repair_used = false;
        assert!(arm_deep_research_report_repair(
            &mut loop_remaining,
            &mut repair_used
        ));
        assert_eq!(loop_remaining, 1);
        assert!(repair_used);
        assert!(
            !arm_deep_research_report_repair(&mut loop_remaining, &mut repair_used),
            "only one focused repair pass is allowed"
        );
        assert_eq!(loop_remaining, 1);

        let report_dir = root.join(".a3s/research/complete");
        std::fs::create_dir_all(&report_dir).unwrap();
        std::fs::write(
            report_dir.join("report.md"),
            "# Complete Report\n\n## Findings\n\nThis completed report summarizes the gathered evidence, identifies the main conclusion, and records caveats so the user can evaluate the result.\n\n## Sources\n\n- https://example.com/evidence\n\n## Confidence\n\nConfidence is medium because the sample evidence is intentionally compact but source-backed.\n",
        )
        .unwrap();
        std::fs::write(
            report_dir.join("index.html"),
            "<!doctype html><html><body><h1>Complete Report</h1><section><h2>Findings</h2><p>This completed report summarizes gathered evidence, caveats, and confidence so the user can inspect the result.</p></section><section><h2>Sources</h2><p>Evidence source: https://example.com/evidence. Confidence is medium.</p></section></body></html>",
        )
        .unwrap();
        assert!(
            !deep_research_report_is_missing(
                true,
                false,
                Some("complete"),
                "A3S_RESEARCH_VIEW: .a3s/research/complete/index.html",
                &root,
                "",
                None,
            ),
            "valid markdown/html artifact pair should let TUI finish"
        );
        assert!(
            deep_research_report_is_missing(
                true,
                false,
                Some("different query"),
                "A3S_RESEARCH_VIEW: .a3s/research/complete/index.html",
                &root,
                "",
                None,
            ),
            "DeepResearch must not finish by pointing at a report slug from another query"
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_tui_missing_html_can_complete_from_valid_markdown_report() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-tui-markdown-complete-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let report_dir = root.join(".a3s/research/completed-markdown-only");
        std::fs::create_dir_all(&report_dir).unwrap();
        std::fs::write(
            report_dir.join("report.md"),
            "# Completed Markdown Only\n\n## Findings\n\nThis report has enough source-backed analysis to answer the query and should be completed into an HTML RemoteUI artifact by the host when the model stalls before writing HTML.\n\n## Sources\n\n- https://example.com/source\n\n## Confidence\n\nConfidence is high because the cited source traces directly to gathered evidence.\n",
        )
        .unwrap();
        let workflow_output = serde_json::json!({
            "research": {
                "results": [{
                    "structured": {
                        "summary": "source-backed",
                        "sources": [{
                            "url_or_path": "https://example.com/source",
                            "quote_or_fact": "source trace"
                        }],
                        "confidence": "high"
                    }
                }]
            }
        })
        .to_string();
        let mut loop_remaining = 0;
        let mut repair_used = false;
        let recovery = recover_missing_deep_research_report(
            &root,
            Some("completed markdown only"),
            "Synthesis timed out before writing HTML.",
            &workflow_output,
            None,
            &mut loop_remaining,
            &mut repair_used,
        );
        let artifacts = match recovery {
            DeepResearchReportRecovery::CompletedMaterialized { artifacts } => artifacts,
            other => panic!("expected completed report materialization, got {other:?}"),
        };

        assert_eq!(loop_remaining, 0);
        assert!(
            !repair_used,
            "valid markdown should avoid an unnecessary repair pass"
        );
        assert!(artifacts.markdown.is_file());
        assert!(artifacts.html.is_file());
        let html = std::fs::read_to_string(&artifacts.html).unwrap();
        assert!(html.contains("<html"), "{html}");
        assert!(html.contains("https://example.com/source"), "{html}");
        assert!(
            deep_research_report_artifacts_from_output_for_query(
                "A3S_RESEARCH_VIEW: .a3s/research/completed-markdown-only/index.html",
                &root,
                "completed markdown only",
                &workflow_output,
                None,
            )
            .is_some(),
            "host-completed report must pass normal report validation"
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_tui_second_missing_report_materializes_fallback() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-tui-fallback-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&root).unwrap();

        let mut loop_remaining = 0;
        let mut repair_used = false;
        let first = recover_missing_deep_research_report(
            &root,
            Some("TUI fallback report"),
            "Synthesis without marker",
            r#"{"mode":"local_parallel_task","research":"evidence"}"#,
            None,
            &mut loop_remaining,
            &mut repair_used,
        );
        assert!(matches!(first, DeepResearchReportRecovery::RepairPassArmed));
        assert_eq!(loop_remaining, 1);
        assert!(repair_used);

        let second = recover_missing_deep_research_report(
            &root,
            Some("TUI fallback report"),
            "Repair still forgot the marker",
            r#"{"mode":"local_parallel_task","research":"evidence"}"#,
            None,
            &mut loop_remaining,
            &mut repair_used,
        );
        let artifacts = match second {
            DeepResearchReportRecovery::FallbackMaterialized { artifacts } => artifacts,
            other => panic!("expected fallback materialization, got {other:?}"),
        };

        assert_eq!(loop_remaining, 0);
        assert!(artifacts.markdown.is_file());
        assert!(artifacts.html.is_file());
        let markdown = std::fs::read_to_string(&artifacts.markdown).unwrap();
        assert!(markdown.contains("Repair still forgot the marker"));
        assert!(markdown.contains("collection_status"));
        assert!(!markdown.contains("local_parallel_task"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_fallback_draft_materializes_valid_artifacts_without_marker() {
        let root = std::env::temp_dir().join(format!(
            "a3s-research-fallback-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&root).unwrap();

        let artifacts = materialize_deep_research_fallback_draft(
            &root,
            "Rust async runtimes: Tokio & async-std",
            "Final answer with <unsafe> characters & citations.",
            r#"{"mode":"local_parallel_task","research":"evidence"}"#,
        )
        .expect("fallback draft should be written");

        assert!(artifacts.markdown.is_file());
        assert!(artifacts.html.is_file());
        assert!(artifacts
            .html
            .ends_with(".a3s/research/rust-async-runtimes-tokio-async-std/index.html"));
        let markdown = std::fs::read_to_string(&artifacts.markdown).unwrap();
        assert!(markdown.contains("# DeepResearch Fallback Draft"));
        assert!(markdown.contains("not a completed DeepResearch report"));
        assert!(markdown.contains("collection_status"));
        assert!(!markdown.contains("local_parallel_task"));
        assert!(!markdown.contains(RESEARCH_VIEW_MARKER));
        let html = std::fs::read_to_string(&artifacts.html).unwrap();
        assert!(html.contains("DeepResearch Fallback Draft"));
        assert!(html.contains("&lt;unsafe&gt;"));
        assert!(!html.contains(RESEARCH_VIEW_MARKER));

        let timeout_artifacts = materialize_deep_research_fallback_draft(
            &root,
            "Timeout fallback report",
            "DeepResearch synthesis model call timed out after 480000 ms.",
            r#"{"mode":"local_parallel_task","research":{"metadata":{"success_count":4,"task_count":4},"output":"README.md evidence"}}"#,
        )
        .expect("timeout fallback draft should be written");
        let timeout_markdown = std::fs::read_to_string(&timeout_artifacts.markdown).unwrap();
        let answer_section = timeout_markdown
            .split("## Workflow Evidence")
            .next()
            .unwrap_or_default();
        assert!(answer_section.contains("captured 4/4 delegated research tasks"));
        assert!(answer_section.contains("README.md"));
        assert!(
            !answer_section.contains("timed out after 480000 ms"),
            "{answer_section}"
        );
        assert!(timeout_markdown.contains(
            "Model synthesis status: DeepResearch synthesis model call timed out after 480000 ms."
        ));

        let dirty_artifacts = materialize_deep_research_fallback_draft(
            &root,
            "Dirty fallback report",
            "● Searched web fifa results\n⎿ [tool output truncated: showing first bytes]",
            r#"{"mode":"local_parallel_task","research":{"metadata":{"success_count":1,"task_count":1},"output":"● Searched web\n⎿ [tool output truncated]"}}"#,
        )
        .expect("dirty fallback draft should be written with sanitized content");
        let dirty_markdown = std::fs::read_to_string(&dirty_artifacts.markdown).unwrap();
        let dirty_html = std::fs::read_to_string(&dirty_artifacts.html).unwrap();
        assert!(
            dirty_markdown.contains("sanitized evidence digest"),
            "{dirty_markdown}"
        );
        assert!(
            !deep_research_output_has_internal_leak(&dirty_markdown),
            "{dirty_markdown}"
        );
        assert!(
            !deep_research_output_has_internal_leak(&dirty_html),
            "{dirty_html}"
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_fallback_slug_handles_long_and_non_ascii_queries() {
        assert_eq!(
            deep_research_report_slug("Rust async runtimes"),
            "rust-async-runtimes"
        );

        let chinese = deep_research_report_slug("帮我深入研究书小安本地 API 和 Web 版本");
        assert!(chinese.starts_with("api-web-"), "{chinese}");
        assert!(chinese.len() <= 93, "{chinese}");

        let long_query = "compare ".repeat(80);
        let long_slug = deep_research_report_slug(&long_query);
        assert!(long_slug.len() <= 93, "{long_slug}");
        assert!(long_slug.starts_with("compare-compare"), "{long_slug}");

        let root = std::env::temp_dir().join(format!(
            "a3s-research-fallback-slug-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&root).unwrap();
        let artifacts =
            materialize_deep_research_fallback_draft(&root, &long_query, "answer", "evidence")
                .expect("long query fallback draft should be written");
        assert!(artifacts.html.is_file());
        assert!(
            artifacts
                .html
                .parent()
                .and_then(|path| path.file_name())
                .and_then(|name| name.to_str())
                .is_some_and(|slug| slug.len() <= 93),
            "{}",
            artifacts.html.display()
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn deep_research_workflow_args_force_local_even_when_runtime_requested() {
        let args = deep_research_workflow_args("rust async runtimes", true);
        let source = args["source"].as_str().unwrap();
        let budget = deep_research_default_budget();
        let workflow_budget =
            deep_research_workflow_budget_for_query("rust async runtimes", false, budget);

        assert_eq!(args["input"]["query"], "rust async runtimes");
        assert_eq!(args["input"]["os_runtime"], false);
        assert_eq!(
            args["input"]["complexity_layers"],
            workflow_budget.complexity_layers
        );
        assert_eq!(
            args["input"]["local_max_parallel_tasks"],
            workflow_budget.local_max_parallel_tasks
        );
        assert_eq!(
            args["input"]["local_max_steps"],
            workflow_budget.local_max_steps
        );
        assert_eq!(args["input"]["local_research_rounds"], 1);
        assert_eq!(
            args["input"]["runtime_preflight_timeout_ms"],
            workflow_budget.runtime_preflight_timeout_ms
        );
        assert_eq!(
            args["input"]["runtime_timeout_ms"],
            workflow_budget.runtime_step_timeout_ms
        );
        assert_eq!(
            args["limits"]["timeoutMs"],
            workflow_budget.workflow_timeout_ms
        );
        assert_eq!(
            deep_research_workflow_host_timeout_ms(&args),
            workflow_budget.workflow_timeout_ms + DEEP_RESEARCH_WORKFLOW_HOST_GRACE_MS
        );
        assert_eq!(
            args["limits"]["maxToolCalls"],
            workflow_budget.workflow_max_tool_calls
        );
        assert_eq!(
            args["limits"]["maxOutputBytes"],
            workflow_budget.workflow_max_output_bytes
        );
        assert_eq!(args["allowed_tools"], serde_json::json!([]));
        assert!(source.contains("local_research"), "{source}");
        assert!(
            source.contains("bounded_recursive_parallel_retrieval_summary"),
            "{source}"
        );
        assert!(source.contains("maxResearchRounds"), "{source}");
        assert!(source.contains("minResearchRounds"), "{source}");
        assert!(source.contains("followUpTracks"), "{source}");
        assert!(source.contains("evidenceSummary"), "{source}");
        assert!(
            source.contains("${prefix}_round_${roundNumber}"),
            "{source}"
        );
        assert!(source.contains("maxLocalParallelTasks"), "{source}");
        assert!(
            source.contains("const osRuntimeEnabled = false"),
            "{source}"
        );
        assert!(
            source.contains("if (osRuntimeEnabled && input.os_runtime)"),
            "{source}"
        );
        assert!(
            source.contains("providedTracks.length > 0 ? providedTracks : fallbackTracks"),
            "{source}"
        );
        assert!(source.contains("parallelizable === false"), "{source}");
        assert!(source.contains("step_name: \"parallel_task\""), "{source}");
        assert!(source.contains("allow_partial_failure: true"), "{source}");
        assert!(source.contains("output_schema: evidenceSchema"), "{source}");
        assert!(
            source.contains("Return a JSON object matching output_schema"),
            "{source}"
        );
        assert!(source.contains("summary: { type: \"string\" }"), "{source}");
        assert!(source.contains("key_evidence"), "{source}");
        assert!(source.contains("contradictions"), "{source}");
        assert!(source.contains("confidence"), "{source}");
        assert!(source.contains("gaps"), "{source}");
        assert!(source.contains("agent: \"explore\""), "{source}");
        assert!(!source.contains("agent: \"verification\""), "{source}");
        assert!(
            source.contains("Number(input.local_max_parallel_tasks)"),
            "{source}"
        );
        assert!(
            !source.contains("local_max_parallel_tasks || 8"),
            "{source}"
        );
        assert!(source.contains("max_steps: localMaxSteps"), "{source}");
        assert!(source.contains("Recursive round:"), "{source}");
        assert!(
            source.contains("on_exhausted: \"continue_workflow\""),
            "{source}"
        );
        assert!(source.contains("step_failures"), "{source}");
        assert!(source.contains("normalizeLocalResearch"), "{source}");
        assert!(source.contains("aggregateResearchRounds"), "{source}");
        assert!(source.contains("partial_success"), "{source}");
        assert!(source.contains("failed_tasks"), "{source}");
        assert!(source.contains("error_summary"), "{source}");
        assert!(source.contains("output_summary"), "{source}");
        assert!(
            source.contains("local_parallel_task_failed")
                && source.contains("local_fallback_failed"),
            "{source}"
        );
        assert!(
            source.contains("Evidence only: do not write files"),
            "{source}"
        );
        assert!(source.contains("You are an evidence collector"), "{source}");
        assert!(
            source.contains("Do not inspect .a3s-flow/dynamic-workflows logs"),
            "{source}"
        );
        assert!(
            source.contains("Use dedicated read-only tools:"),
            "{source}"
        );
        assert!(
            source.contains("web_search/web_fetch")
                && source.contains("read/grep/glob/ls")
                && source.contains("Do not use bash for research collection"),
            "{source}"
        );
        assert!(source.contains("Math.min(64"), "{source}");
        assert!(!source.contains("Math.min(8"), "{source}");
        assert!(source.contains(": 200"), "{source}");
        assert!(!source.contains("agent: \"general\""), "{source}");
    }

    #[test]
    fn deep_research_workflow_budget_scales_with_query_complexity() {
        let budget = deep_research_default_budget();
        let narrow = deep_research_workflow_budget_for_query(
            "Rust stable version from official Rust source; concise cited report.",
            false,
            budget,
        );
        assert_eq!(narrow.complexity_layers, 0);
        assert_eq!(narrow.local_research_rounds, 1);
        assert_eq!(narrow.local_max_parallel_tasks, 4);
        assert_eq!(narrow.local_max_steps, 80);
        assert_eq!(narrow.runtime_preflight_timeout_ms, 30_000);
        assert_eq!(narrow.runtime_step_timeout_ms, 4 * 60 * 1000);
        assert_eq!(narrow.workflow_timeout_ms, 330_000);
        assert_eq!(narrow.workflow_max_tool_calls, 120);
        assert_eq!(narrow.workflow_max_output_bytes, 1024 * 1024);
        assert!(narrow.local_max_steps < budget.deep_research_child_steps);
        assert!(narrow.workflow_timeout_ms < DEEP_RESEARCH_SCRIPT_TIMEOUT_MS);

        let broad =
            "全面调研 2026 年多智能体运行时市场、最新论文、竞品、趋势、多来源、大量并行证据";
        let complex = deep_research_workflow_budget_for_query(broad, false, budget);
        assert_eq!(complex.complexity_layers, 3);
        assert_eq!(complex.local_max_parallel_tasks, budget.max_parallel_tasks);
        assert_eq!(complex.local_max_steps, budget.deep_research_child_steps);
        assert_eq!(
            complex.runtime_preflight_timeout_ms,
            DEEP_RESEARCH_RUNTIME_PREFLIGHT_TIMEOUT_MS
        );
        assert_eq!(
            complex.runtime_step_timeout_ms,
            DEEP_RESEARCH_RUNTIME_STEP_TIMEOUT_MS
        );
        assert_eq!(complex.workflow_timeout_ms, DEEP_RESEARCH_SCRIPT_TIMEOUT_MS);
        assert_eq!(
            complex.workflow_max_tool_calls,
            budget.workflow_max_tool_calls
        );
        assert_eq!(
            complex.workflow_max_output_bytes,
            budget.workflow_max_output_bytes
        );
    }

    #[test]
    fn deep_research_research_rounds_scale_with_complexity_and_effort() {
        let low = crate::budget::budget_plan_for_effort_id(
            "low",
            Some(128_000),
            BudgetWorkload::DeepResearch,
        );
        let medium = crate::budget::budget_plan_for_effort_id(
            "medium",
            Some(128_000),
            BudgetWorkload::DeepResearch,
        );
        let high = crate::budget::budget_plan_for_effort_id(
            "high",
            Some(128_000),
            BudgetWorkload::DeepResearch,
        );

        assert_eq!(
            deep_research_research_rounds("rust async runtimes", false, high),
            1
        );
        assert_eq!(
            deep_research_research_rounds("比较 tokio 和 async-std 的设计取舍", false, high),
            2
        );
        let broad =
            "全面调研 2026 年多智能体运行时市场、最新论文、竞品、趋势、多来源、大量并行证据";
        assert_eq!(deep_research_research_rounds(broad, false, low), 2);
        assert_eq!(deep_research_research_rounds(broad, false, medium), 3);
        assert_eq!(deep_research_research_rounds(broad, false, high), 4);
    }

    #[test]
    fn deep_research_synthesis_prompt_uses_host_workflow_evidence() {
        let prompt = deep_research_synthesis_prompt(
            "rust async runtimes",
            true,
            r#"{"mode":"os_runtime"}"#,
            Some(&serde_json::json!({
                "dynamic_workflow": {
                    "snapshot": {
                        "steps": {
                            "runtime_research": {
                                "output": { "name": "runtime" }
                            }
                        }
                    }
                }
            })),
        );

        assert!(
            prompt.contains("Do not call workflow or broad evidence-collection tools again"),
            "{prompt}"
        );
        assert!(prompt.contains("rust async runtimes"), "{prompt}");
        assert!(prompt.contains("Evidence digest"), "{prompt}");
        assert!(prompt.contains("Run diagnostics"), "{prompt}");
        assert!(!prompt.contains("DynamicWorkflowRuntime"), "{prompt}");
        assert!(!prompt.contains("dynamic_workflow"), "{prompt}");
        assert!(
            prompt.contains("\"collection_status\": \"completed\""),
            "{prompt}"
        );
        assert!(prompt.contains("OS Runtime was selected"), "{prompt}");
        assert!(prompt.contains("evidence_items"), "{prompt}");
        assert!(prompt.contains("bounded recursive parallel"), "{prompt}");
        assert!(prompt.contains("research.rounds"), "{prompt}");
        assert!(prompt.contains("warnings.failed_tasks"), "{prompt}");
        assert!(
            prompt.contains("Raw task output is intentionally excluded"),
            "{prompt}"
        );
        assert!(prompt.contains("Do not reproduce raw JSON"), "{prompt}");
        assert!(
            prompt.contains("host expects report slug `rust-async-runtimes`"),
            "{prompt}"
        );
        assert!(
            prompt.contains("A3S_RESEARCH_VIEW: .a3s/research/rust-async-runtimes/index.html"),
            "{prompt}"
        );
        assert!(prompt.contains("source traceability"), "{prompt}");
        assert!(prompt.contains(RESEARCH_VIEW_MARKER), "{prompt}");
        assert!(prompt.contains("host validates file existence"), "{prompt}");
        assert!(
            prompt.contains("opens the HTML in RemoteUI automatically"),
            "{prompt}"
        );
        assert!(
            prompt.contains("Do not repeat an identical grep"),
            "{prompt}"
        );
    }

    #[test]
    fn deep_research_synthesis_prompt_sanitizes_parallel_task_metadata() {
        let verbose_failure = format!(
            "Task failed: Max tool rounds (30) exceeded {}",
            format!(
                "{}RAW_FAILURE_DETAIL_SHOULD_NOT_SURVIVE",
                "padding ".repeat(120)
            )
        );
        let prompt = deep_research_synthesis_prompt(
            "unstable research",
            false,
            r#"{"mode":"local_parallel_task"}"#,
            Some(&serde_json::json!({
                "dynamic_workflow": {
                    "snapshot": {
                        "steps": {
                            "local_research": {
                                "output": {
                                    "tool": "parallel_task",
                                    "output": format!("Executed 2 tasks in parallel:\n\n{verbose_failure}"),
                                    "metadata": {
                                        "task_count": 2,
                                        "result_count": 2,
                                        "success_count": 1,
                                        "failed_count": 1,
                                        "partial_failure": true,
                                        "allow_partial_failure": true,
                                        "results": [
                                            {
                                                "task_id": "ok",
                                                "agent": "explore",
                                                "success": true,
                                                "output": "successful raw output should be redundant",
                                                "structured": {
                                                    "summary": "source-backed evidence",
                                                    "sources": [{
                                                        "title": "Source",
                                                        "url_or_path": "https://example.com",
                                                        "quote_or_fact": "evidence"
                                                    }],
                                                    "key_evidence": ["evidence"],
                                                    "contradictions": [],
                                                    "confidence": "high",
                                                    "gaps": []
                                                }
                                            },
                                            {
                                                "task_id": "bad",
                                                "agent": "explore",
                                                "success": false,
                                                "output": verbose_failure
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            })),
        );

        assert!(prompt.contains("source-backed evidence"), "{prompt}");
        assert!(prompt.contains("failed_tasks"), "{prompt}");
        assert!(
            prompt.contains("Delegated task exhausted its tool-round budget"),
            "{prompt}"
        );
        assert!(!prompt.contains("Task failed: Max tool rounds"), "{prompt}");
        assert!(!prompt.contains("Executed 2 tasks in parallel"), "{prompt}");
        assert!(
            !prompt.contains("RAW_FAILURE_DETAIL_SHOULD_NOT_SURVIVE"),
            "{prompt}"
        );
        assert!(
            !prompt.contains("successful raw output should be redundant"),
            "{prompt}"
        );
        assert!(!prompt.contains("parallel_task"), "{prompt}");
        assert!(!prompt.contains("dynamic_workflow"), "{prompt}");
    }

    #[test]
    fn deep_research_repair_prompt_is_self_contained_and_artifact_focused() {
        let metadata = serde_json::json!({
            "dynamic_workflow": {
                "snapshot": {
                    "steps": {
                        "local_research": {
                            "status": "completed"
                        }
                    }
                }
            }
        });
        let prompt = deep_research_repair_prompt(
            "compare async runtimes",
            false,
            r#"{"mode":"local_parallel_task","research":{"results":[{"structured":{"summary":"source-backed","sources":[{"url_or_path":"https://example.com/async","quote_or_fact":"evidence"}],"confidence":"high"}}]}}"#,
            Some(&metadata),
            "Previous answer without a report marker.",
        );

        assert!(prompt.contains("compare async runtimes"), "{prompt}");
        assert!(
            prompt.contains("Previous answer without a report marker"),
            "{prompt}"
        );
        assert!(prompt.contains("source-backed"), "{prompt}");
        assert!(prompt.contains("https://example.com/async"), "{prompt}");
        assert!(
            prompt.contains("Do not call workflow or broad evidence-collection"),
            "{prompt}"
        );
        assert!(!prompt.contains("local_parallel_task"), "{prompt}");
        assert!(!prompt.contains("local_research"), "{prompt}");
        assert!(!prompt.contains("dynamic_workflow"), "{prompt}");
        assert!(
            prompt.contains("host expects report slug `compare-async-runtimes`"),
            "{prompt}"
        );
        assert!(
            prompt.contains("A3S_RESEARCH_VIEW: .a3s/research/compare-async-runtimes/index.html"),
            "{prompt}"
        );
        assert!(
            prompt.contains("Do not repeat an identical grep"),
            "{prompt}"
        );
        assert!(
            prompt.contains("do not write ordinary workspace files"),
            "{prompt}"
        );
        assert!(
            prompt.contains(".a3s/research/<slug>/report.md"),
            "{prompt}"
        );
        assert!(prompt.contains(RESEARCH_VIEW_MARKER), "{prompt}");
    }

    #[test]
    fn deep_research_tui_missing_report_repair_prompt_uses_workflow_state() {
        let loop_state = DeepResearchLoop {
            query: "runtime market scan".to_string(),
            total_layers: 2,
            os_runtime: true,
        };
        let metadata = serde_json::json!({
            "dynamic_workflow": {
                "snapshot": {
                    "steps": {
                        "runtime_research": {
                            "status": "completed"
                        }
                    }
                }
            }
        });

        let prompt = deep_research_report_repair_prompt_from_state(
            Some(&loop_state),
            r#"{"mode":"os_runtime","research":{"results":[{"structured":{"summary":"runtime-backed","sources":[{"url_or_path":"https://example.com/runtime","quote_or_fact":"evidence"}],"confidence":"medium"}}]}}"#,
            Some(&metadata),
            "Prior synthesis forgot report artifacts.",
        )
        .expect("active DeepResearch loop should produce a report repair prompt");

        assert!(prompt.contains("runtime market scan"), "{prompt}");
        assert!(prompt.contains("OS Runtime was selected"), "{prompt}");
        assert!(prompt.contains("runtime-backed"), "{prompt}");
        assert!(prompt.contains("https://example.com/runtime"), "{prompt}");
        assert!(!prompt.contains("runtime_research"), "{prompt}");
        assert!(!prompt.contains("dynamic_workflow"), "{prompt}");
        assert!(
            prompt.contains("Prior synthesis forgot report artifacts"),
            "{prompt}"
        );
        assert!(
            prompt.contains("host expects report slug `runtime-market-scan`"),
            "{prompt}"
        );
        assert!(
            prompt.contains("A3S_RESEARCH_VIEW: .a3s/research/runtime-market-scan/index.html"),
            "{prompt}"
        );
        assert!(
            deep_research_report_repair_prompt_from_state(None, "{}", None, "missing").is_none()
        );
    }

    #[test]
    fn deep_research_metadata_detects_runtime_and_local_parallel_evidence() {
        let metadata = serde_json::json!({
            "dynamic_workflow": {
                "snapshot": {
                    "steps": {
                        "runtime_research": {
                            "output": { "name": "runtime" }
                        },
                        "local_fallback": {
                            "output": { "tool": "parallel_task" }
                        }
                    }
                }
            }
        });

        assert!(json_contains_tool_evidence(&metadata, "runtime"));
        assert!(json_contains_tool_evidence(&metadata, "parallel_task"));
        assert!(!json_contains_tool_evidence(&metadata, "program"));
    }

    #[test]
    fn deep_research_goal_is_a_research_north_star_with_query() {
        let g = deep_research_goal("rust async runtimes");
        assert!(g.contains("rust async runtimes"), "{g}");
        assert!(g.to_lowercase().contains("research"), "{g}");
    }

    // ── scroll + copy ──────────────────────────────────────────────────────
    #[test]
    fn scrollbar_blank_when_content_fits() {
        let out = append_scrollbar("a\nb\nc", 5, 3, 100);
        assert_eq!(out.lines().count(), 3);
        for line in out.lines() {
            assert!(line.ends_with(' '), "no-overflow gutter blank: {line:?}");
            assert!(!line.contains('█') && !line.contains('│'));
        }
    }

    #[test]
    fn scrollbar_thumb_tracks_position() {
        let view = "r0\nr1\nr2\nr3"; // 4 visible rows, far more total
        let top = append_scrollbar(view, 4, 40, 0);
        assert!(top.lines().next().unwrap().contains('█'), "thumb at top");
        let bottom = append_scrollbar(view, 4, 40, 100);
        assert!(
            bottom.lines().last().unwrap().contains('█'),
            "thumb at bottom"
        );
        // every row carries the bar (thumb or track) once content overflows
        assert!(top.lines().all(|l| l.contains('█') || l.contains('│')));
    }

    #[test]
    fn osc52_wraps_base64_in_envelope() {
        let s = osc52_copy("hi");
        assert!(s.starts_with("\u{1b}]52;c;") && s.ends_with('\u{7}'));
        assert!(s.contains("aGk=")); // base64("hi")
    }

    #[test]
    fn slice_cols_handles_ascii_and_wide() {
        assert_eq!(slice_cols("hello", 1, 4), "ell");
        assert_eq!(slice_cols("hello", 0, 100), "hello");
        // Wide glyphs are width-2: "あい" spans columns 0..4.
        assert_eq!(slice_cols("あい", 0, 2), "あ");
        assert_eq!(slice_cols("あい", 2, 4), "い");
    }

    #[test]
    fn selection_to_text_extracts_span_across_rows() {
        let view = "  hello world\n  second line\n  third";
        // row0 col2..end, through row1 col0..8 — trailing padding trimmed.
        let t = selection_to_text(view, 0, 2, 1, 8);
        assert_eq!(t, "hello world\n  second");
    }

    #[test]
    fn mouse_selection_uses_release_position_clamped_to_viewport() {
        assert_eq!(viewport_mouse_cell(2, 40, 4, 20), Some((2, 20)));
        assert_eq!(viewport_mouse_cell(4, 2, 4, 20), None);
        assert_eq!(viewport_mouse_cell_clamped(9, 40, 4, 20), Some((3, 20)));
        assert_eq!(viewport_mouse_cell_clamped(0, 1, 0, 20), None);
    }

    #[test]
    fn highlight_selection_touches_only_selected_rows() {
        let view = "row zero\nrow one\nrow two";
        let out = highlight_selection(view, 1, 0, 1, 7);
        let lines: Vec<&str> = out.split('\n').collect();
        assert_eq!(lines[0], "row zero"); // untouched
        assert_eq!(lines[2], "row two"); // untouched
        assert!(lines[1].contains("row one")); // selected text preserved
        assert!(lines[1].contains('\u{1b}')); // wrapped in a style escape
    }

    /// `?` deep research is only meaningful if the agent actually has the web
    /// tools to call — guard that they're registered in the session surface.
    #[tokio::test]
    async fn web_tools_registered_for_q_research_mode() {
        let dir = std::env::temp_dir().join(format!(
            "a3s-research-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let cfg = dir.join("config.acl");
        test_config(&cfg);
        let agent = a3s_code_core::Agent::new(cfg.to_string_lossy().to_string())
            .await
            .unwrap();
        let session = agent
            .session(dir.to_string_lossy().to_string(), None)
            .unwrap();
        let names = session.tool_names();
        let _ = std::fs::remove_dir_all(&dir);
        assert!(
            names.contains(&"web_search".to_string()) && names.contains(&"web_fetch".to_string()),
            "the `?` deep-research mode relies on web_search + web_fetch; got {names:?}"
        );
    }

    #[test]
    fn tui_default_policy_allows_readonly_research_tools() {
        use a3s_code_core::permissions::PermissionDecision;

        let policy = tui_permission_policy();

        assert_eq!(
            policy.check(
                "web_fetch",
                &serde_json::json!({"url": "https://example.com"})
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            policy.check("web_search", &serde_json::json!({"query": "a3s"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            policy.check("read", &serde_json::json!({"file_path": "README.md"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            policy.check(
                "write",
                &serde_json::json!({
                    "file_path": ".a3s/research/rust-async/report.md",
                    "content": "# Report"
                })
            ),
            PermissionDecision::Allow,
            "DeepResearch report artifacts should not require an interactive confirmation"
        );
        assert_eq!(
            policy.check(
                "Write",
                &serde_json::json!({
                    "file_path": "/tmp/workspace/.a3s/research/rust-async/index.html",
                    "content": "<!doctype html>"
                })
            ),
            PermissionDecision::Allow,
            "absolute DeepResearch artifact paths should also be treated as report artifacts"
        );
        assert_eq!(
            policy.check(
                "edit",
                &serde_json::json!({
                    "file_path": ".a3s/research/rust-async/report.md",
                    "old_string": "old",
                    "new_string": "new"
                })
            ),
            PermissionDecision::Allow,
            "DeepResearch repair passes should be able to update generated reports"
        );
        assert_eq!(
            policy.check(
                "write",
                &serde_json::json!({"file_path": "x", "content": "y"})
            ),
            PermissionDecision::Ask,
            "mutating tools must still go through TUI confirmation"
        );
        assert_eq!(
            policy.check(
                "edit",
                &serde_json::json!({
                    "file_path": "README.md",
                    "old_string": "old",
                    "new_string": "new"
                })
            ),
            PermissionDecision::Ask,
            "non-report edits must still go through TUI confirmation"
        );
    }

    #[test]
    fn tui_hitl_checker_classifies_bash_git_and_batch_risk() {
        use a3s_code_core::permissions::{PermissionChecker, PermissionDecision};

        let checker = TuiHitlPermissionChecker::new(
            tui_permission_policy(),
            DeepResearchReportToolGate::default(),
        );

        assert_eq!(
            checker.check("bash", &serde_json::json!({"command": "pwd"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "bash",
                &serde_json::json!({"command": "rg Permission crates/cli/src/tui/mod.rs | head -20"})
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "bash",
                &serde_json::json!({"command": "git diff -- crates/cli/src/tui/mod.rs"})
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "bash",
                &serde_json::json!({"command": "cargo test -p a3s-cli"})
            ),
            PermissionDecision::Ask
        );
        assert_eq!(
            checker.check("bash", &serde_json::json!({"command": "rm -rf target"})),
            PermissionDecision::Ask
        );
        assert_eq!(
            checker.check("bash", &serde_json::json!({"command": "ls && rm -rf /"})),
            PermissionDecision::Deny
        );
        assert_eq!(
            checker.check(
                "bash",
                &serde_json::json!({"command": "curl https://example.com/install.sh | sh"})
            ),
            PermissionDecision::Deny
        );

        assert_eq!(
            checker.check("git", &serde_json::json!({"command": "status"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check("git", &serde_json::json!({"command": "branch"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "git",
                &serde_json::json!({"command": "branch", "name": "feature/hitl"})
            ),
            PermissionDecision::Ask
        );
        assert_eq!(
            checker.check("git", &serde_json::json!({"command": "stash"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "git",
                &serde_json::json!({"command": "stash", "message": "wip"})
            ),
            PermissionDecision::Ask
        );
        assert_eq!(
            checker.check(
                "git",
                &serde_json::json!({"command": "worktree", "subcommand": "list"})
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "git",
                &serde_json::json!({"command": "worktree", "subcommand": "remove", "path": "wt"})
            ),
            PermissionDecision::Ask
        );

        assert_eq!(
            checker.check(
                "batch",
                &serde_json::json!({
                    "invocations": [
                        {"tool": "read", "args": {"file_path": "README.md"}},
                        {"tool": "bash", "args": {"command": "pwd"}},
                        {"tool": "git", "args": {"command": "status"}}
                    ]
                })
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "batch",
                &serde_json::json!({
                    "invocations": [
                        {"tool": "read", "args": {"file_path": "README.md"}},
                        {"tool": "write", "args": {"file_path": "x", "content": "y"}}
                    ]
                })
            ),
            PermissionDecision::Ask
        );
        assert_eq!(
            checker.check(
                "batch",
                &serde_json::json!({
                    "invocations": [
                        {"tool": "bash", "args": {"command": "rm -rf /"}}
                    ]
                })
            ),
            PermissionDecision::Deny
        );
    }

    #[test]
    fn deep_research_report_gate_denies_non_report_tools() {
        use a3s_code_core::permissions::{PermissionChecker, PermissionDecision};

        let gate = DeepResearchReportToolGate::default();
        gate.set_report_only(true);
        let checker = TuiHitlPermissionChecker::new(tui_permission_policy(), gate);

        assert_eq!(
            checker.check(
                "bash",
                &serde_json::json!({"command": "mkdir -p .a3s/research/x"})
            ),
            PermissionDecision::Deny
        );
        assert_eq!(
            checker.check("read", &serde_json::json!({"file_path": "README.md"})),
            PermissionDecision::Deny
        );
        assert_eq!(
            checker.check(
                "read",
                &serde_json::json!({"file_path": ".a3s/research/rust-stable/report.md"})
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "ls",
                &serde_json::json!({"path": ".a3s/research/rust-stable"})
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check("web_search", &serde_json::json!({"query": "rust stable"})),
            PermissionDecision::Deny
        );
        assert_eq!(
            checker.check(
                "write",
                &serde_json::json!({
                    "file_path": ".a3s/research/rust-stable/report.md",
                    "content": "# Report"
                })
            ),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "write",
                &serde_json::json!({
                    "file_path": "README.md",
                    "include": ".a3s/research/**",
                    "content": "# Report"
                })
            ),
            PermissionDecision::Deny
        );
        assert_eq!(
            checker.check(
                "edit",
                &serde_json::json!({
                    "file_path": "/tmp/workspace/.a3s/research/rust-stable/index.html",
                    "old_string": "old",
                    "new_string": "new"
                })
            ),
            PermissionDecision::Allow
        );
    }

    #[test]
    fn tui_session_options_installs_smart_hitl_checker_and_persistable_policy() {
        use a3s_code_core::permissions::PermissionDecision;

        let confirmation = a3s_code_core::hitl::ConfirmationPolicy::enabled()
            .with_timeout(HITL_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
        let opts = tui_session_options(confirmation);

        assert!(
            opts.permission_policy.is_some(),
            "the serializable fallback policy should still be persisted"
        );
        let checker = opts
            .permission_checker
            .as_ref()
            .expect("TUI sessions should install the smart HITL checker");
        assert_eq!(
            checker.check("bash", &serde_json::json!({"command": "pwd"})),
            PermissionDecision::Allow
        );
        assert_eq!(
            checker.check(
                "write",
                &serde_json::json!({"file_path": "README.md", "content": "new"})
            ),
            PermissionDecision::Ask
        );
    }

    #[tokio::test]
    async fn tui_session_policy_does_not_block_web_fetch() {
        let dir = std::env::temp_dir().join(format!(
            "a3s-web-fetch-policy-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let cfg = dir.join("config.acl");
        test_config(&cfg);

        let agent = a3s_code_core::Agent::new(cfg.to_string_lossy().to_string())
            .await
            .unwrap();
        let llm = Arc::new(CaptureLlmClient::new(vec![
            tool_call_response("web_fetch", serde_json::json!({"url": "not-a-url"})),
            done_response(),
        ]));
        let confirmation = a3s_code_core::hitl::ConfirmationPolicy::enabled()
            .with_timeout(300, TimeoutAction::Reject);
        let opts = tui_session_options(confirmation)
            .with_llm_client(llm)
            .with_planning_mode(a3s_code_core::PlanningMode::Disabled);
        let session = agent
            .session(dir.to_string_lossy().to_string(), Some(opts))
            .unwrap();

        let (mut rx, join) = session
            .stream("Fetch a URL for research.", None)
            .await
            .unwrap();
        let mut saw_fetch_end = None;
        while let Some(event) = rx.recv().await {
            match event {
                a3s_code_core::AgentEvent::ToolEnd {
                    name,
                    output,
                    exit_code,
                    ..
                } if name == "web_fetch" => {
                    saw_fetch_end = Some((output, exit_code));
                }
                a3s_code_core::AgentEvent::PermissionDenied {
                    tool_name, reason, ..
                } => panic!("{tool_name} was denied: {reason}"),
                a3s_code_core::AgentEvent::End { .. } => break,
                a3s_code_core::AgentEvent::Error { message } => panic!("{message}"),
                _ => {}
            }
        }
        join.await.unwrap();
        let _ = std::fs::remove_dir_all(&dir);

        let (output, exit_code) = saw_fetch_end.expect("web_fetch should run");
        assert_ne!(exit_code, 0, "invalid URL should fail validation");
        assert!(
            !output.contains("Permission denied"),
            "web_fetch should not be blocked by permission policy: {output}"
        );
    }

    #[tokio::test]
    async fn hitl_wait_does_not_consume_tool_timeout_budget() {
        let dir = std::env::temp_dir().join(format!(
            "a3s-hitl-timeout-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let cfg = dir.join("config.acl");
        test_config(&cfg);
        std::fs::write(dir.join("sample.txt"), "timeout sentinel").unwrap();

        let agent = a3s_code_core::Agent::new(cfg.to_string_lossy().to_string())
            .await
            .unwrap();
        let llm = Arc::new(CaptureLlmClient::new(vec![
            tool_call_response("read", serde_json::json!({"file_path": "sample.txt"})),
            done_response(),
        ]));
        let confirmation = a3s_code_core::hitl::ConfirmationPolicy::enabled()
            .with_timeout(5_000, TimeoutAction::Reject);
        let opts = tui_session_options(confirmation)
            .with_tool_timeout(300)
            .with_llm_client(llm)
            .with_permission_policy(a3s_code_core::permissions::PermissionPolicy::new())
            .with_planning_mode(a3s_code_core::PlanningMode::Disabled);
        let session = agent
            .session(dir.to_string_lossy().to_string(), Some(opts))
            .unwrap();

        let (mut rx, join) = session.stream("Read sample.txt.", None).await.unwrap();
        let mut saw_confirmation = false;
        let mut tool_output = None;
        while let Some(event) = rx.recv().await {
            match event {
                a3s_code_core::AgentEvent::ConfirmationRequired { tool_id, .. } => {
                    saw_confirmation = true;
                    tokio::time::sleep(Duration::from_millis(500)).await;
                    assert!(session
                        .confirm_tool_use(&tool_id, true, None)
                        .await
                        .unwrap());
                }
                a3s_code_core::AgentEvent::ToolEnd {
                    output, exit_code, ..
                } => {
                    assert_eq!(exit_code, 0, "{output}");
                    assert!(!output.contains("timed out"), "{output}");
                    tool_output = Some(output);
                }
                a3s_code_core::AgentEvent::End { .. } => break,
                a3s_code_core::AgentEvent::Error { message } => panic!("{message}"),
                _ => {}
            }
        }
        join.await.unwrap();
        let _ = std::fs::remove_dir_all(&dir);

        assert!(saw_confirmation, "the tool call should require HITL");
        assert!(
            tool_output
                .as_deref()
                .is_some_and(|output| output.contains("timeout sentinel")),
            "tool output should come from read, got {tool_output:?}"
        );
    }

    /// Manual e2e guard for the TUI's natural-language asset creation prompts.
    ///
    /// Runs against the real configured LLM and auto-approves the tool calls the
    /// TUI would ask the user about. It is ignored by default because it spends
    /// network/model time and writes a temporary asset workspace.
    ///
    /// Run with:
    /// `cargo test -q real_llm_natural_language_asset_creation -- --ignored --nocapture`
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    #[ignore = "hits the real configured LLM and writes temporary asset files"]
    async fn real_llm_natural_language_asset_creation() {
        let home = std::env::var("HOME").expect("HOME");
        let config = format!("{home}/.a3s/config.acl");
        assert!(
            std::path::Path::new(&config).exists(),
            "no ~/.a3s/config.acl - configure a real model first"
        );

        let tmp = std::env::temp_dir().join(format!(
            "a3s-asset-realllm-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let workspace = tmp.join("workspace");
        let roots = tmp.join("assets");
        let agent_root = roots.join("agents");
        let mcp_root = roots.join("mcps");
        let skill_root = roots.join("skills");
        let flow_root = roots.join("flows");
        for dir in [&workspace, &agent_root, &mcp_root, &skill_root, &flow_root] {
            std::fs::create_dir_all(dir).unwrap();
        }

        let agent = a3s_code_core::Agent::new(config)
            .await
            .expect("build agent from config.acl");
        let workspace_str = workspace.to_string_lossy().to_string();
        let only = std::env::var("A3S_REAL_LLM_ASSET_ONLY").ok().map(|value| {
            value
                .split(',')
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .map(str::to_string)
                .collect::<std::collections::BTreeSet<_>>()
        });

        if only.as_ref().map_or(true, |only| only.contains("agent")) {
            eprintln!("\n[asset-e2e] creating agent");
            let dev = panels::agent::scaffold_agent_package(
                "Name it exactly a3s-e2e-review-agent. It reviews pull-request diffs for risky Rust changes and reports concise findings.",
                &agent_root,
            )
            .expect("scaffold agent asset package");
            let saved_path = verify_real_llm_agent_asset(&agent_root).expect("verify agent asset");
            eprintln!(
                "[asset-e2e] agent verified at {} scaffolded: {}",
                saved_path.display(),
                dev.package_path.display()
            );
        }

        let cases = vec![
            (
                "mcp",
                panels::mcp::mcp_gen_prompt(
                    "Name it exactly a3s-e2e-sql-checker. It exposes one stdio MCP tool that checks SQL text for obvious destructive statements.",
                    &mcp_root.to_string_lossy(),
                ),
            ),
            (
                "skill",
                panels::skill::skill_gen_prompt(
                    "Name it exactly a3s-e2e-incident-brief. It helps summarize incident notes into a customer-safe brief.",
                    &skill_root.to_string_lossy(),
                ),
            ),
            (
                "flow",
                panels::flow::flow_gen_prompt(
                    "Name it exactly a3s-e2e-triage-flow. It classifies an incoming support ticket, drafts a short answer, and ends.",
                    &flow_root.to_string_lossy(),
                ),
            ),
            (
                "okf",
                panels::okf::okf_package_gen_prompt(
                    "Name it exactly a3s-e2e-runbook-kb. It stores a small on-call runbook knowledge package for API outage triage.",
                    &workspace_str,
                ),
            ),
        ];

        for (label, prompt) in cases {
            if only.as_ref().is_some_and(|only| !only.contains(label)) {
                continue;
            }
            eprintln!("\n[asset-e2e] creating {label}");
            let session = real_llm_asset_session(&agent, &workspace, label);
            let (answer, saved_path) =
                real_llm_asset_turn(&session, label, &prompt, || match label {
                    "agent" => verify_real_llm_agent_asset(&agent_root),
                    "mcp" => verify_real_llm_mcp_asset(&mcp_root),
                    "skill" => verify_real_llm_skill_asset(&skill_root),
                    "flow" => verify_real_llm_flow_asset(&flow_root),
                    "okf" => verify_real_llm_okf_asset(&workspace),
                    _ => Err(format!("unknown asset e2e label {label}")),
                })
                .await;
            eprintln!(
                "[asset-e2e] {label} verified at {} final: {}",
                saved_path.display(),
                truncate(&answer, 500)
            );
        }

        if std::env::var_os("A3S_REAL_LLM_ASSET_KEEP").is_some() {
            eprintln!("[asset-e2e] kept {}", tmp.display());
        } else {
            let _ = std::fs::remove_dir_all(&tmp);
        }
    }

    fn real_llm_asset_session(
        agent: &a3s_code_core::Agent,
        workspace: &std::path::Path,
        label: &str,
    ) -> a3s_code_core::AgentSession {
        let confirmation = a3s_code_core::hitl::ConfirmationPolicy::enabled()
            .with_timeout(HITL_CONFIRM_TIMEOUT_MS, TimeoutAction::Reject);
        let opts = tui_session_options(confirmation)
            .with_session_id(format!("asset-e2e-{label}-{}", std::process::id()))
            .with_auto_save(false)
            .with_tool_timeout(90_000)
            .with_planning_mode(a3s_code_core::PlanningMode::Disabled);
        agent
            .session(workspace.to_string_lossy().to_string(), Some(opts))
            .expect("real LLM asset session")
    }

    async fn real_llm_asset_turn<F>(
        session: &a3s_code_core::AgentSession,
        label: &str,
        prompt: &str,
        mut verify: F,
    ) -> (String, std::path::PathBuf)
    where
        F: FnMut() -> Result<std::path::PathBuf, String>,
    {
        let timeout_secs = std::env::var("A3S_REAL_LLM_ASSET_TIMEOUT_SECS")
            .ok()
            .and_then(|value| value.parse::<u64>().ok())
            .unwrap_or(240);
        let label_contract = if label == "agent" {
            "For the agent package, completeness means package files, prompts, examples, evals, \
             tests/checklists, and A3S metadata on disk; do not scaffold or run an application, \
             do not install dependencies, and do not execute the generated agent."
        } else {
            ""
        };
        let prompt = format!(
            "{prompt}\n\n\
             {label_contract}\n\
             E2E completion contract: create exactly one asset package. Use at most four tool \
             calls; if the asset root is outside the workspace, create every required file with \
             bash heredocs in the first tool call when possible. Once the files and JSON \
             validation are complete, stop using tools immediately and answer with \
             `ASSET_E2E_DONE: <saved package path>`."
        );
        let fut = async {
            let (mut rx, join) = session.stream(&prompt, None).await.expect("stream start");
            let mut final_text = String::new();
            let mut streamed = String::new();
            let mut tool_count = 0usize;
            let mut verified_path = None;
            let mut last_verify_error = "asset files were not checked yet".to_string();
            while let Some(event) = rx.recv().await {
                match event {
                    a3s_code_core::AgentEvent::TextDelta { text } => streamed.push_str(&text),
                    a3s_code_core::AgentEvent::ToolStart { name, .. } => {
                        tool_count += 1;
                        eprintln!("[asset-e2e:{label}] tool start: {name}");
                    }
                    a3s_code_core::AgentEvent::ToolEnd {
                        name,
                        output,
                        exit_code,
                        ..
                    } => {
                        eprintln!(
                            "[asset-e2e:{label}] tool end: {name} exit {exit_code}: {}",
                            output.lines().take(2).collect::<Vec<_>>().join(" | ")
                        );
                        match verify() {
                            Ok(path) => {
                                eprintln!(
                                    "[asset-e2e:{label}] verifier passed after {tool_count} tool(s)"
                                );
                                verified_path = Some(path);
                                let _ = session.cancel().await;
                                break;
                            }
                            Err(error) => {
                                last_verify_error = error;
                            }
                        }
                    }
                    a3s_code_core::AgentEvent::ConfirmationRequired {
                        tool_id, tool_name, ..
                    } => {
                        eprintln!("[asset-e2e:{label}] auto-approving {tool_name}");
                        session
                            .confirm_tool_use(
                                &tool_id,
                                true,
                                Some("real LLM asset e2e auto-approval".to_string()),
                            )
                            .await
                            .expect("confirm tool use");
                    }
                    a3s_code_core::AgentEvent::PermissionDenied {
                        tool_name, reason, ..
                    } => {
                        panic!("{label}: tool {tool_name} denied: {reason}");
                    }
                    a3s_code_core::AgentEvent::End { text, .. } => {
                        final_text = if text.trim().is_empty() {
                            streamed.clone()
                        } else {
                            text
                        };
                        match verify() {
                            Ok(path) => verified_path = Some(path),
                            Err(error) => last_verify_error = error,
                        }
                        break;
                    }
                    a3s_code_core::AgentEvent::Error { message } => {
                        panic!("{label}: real LLM turn errored: {message}");
                    }
                    _ => {}
                }
            }
            assert!(
                tool_count > 0,
                "{label}: expected the real LLM to use tools"
            );
            let verified_path = verified_path
                .unwrap_or_else(|| panic!("{label}: verifier never passed: {last_verify_error}"));
            tokio::time::timeout(Duration::from_secs(30), join)
                .await
                .unwrap_or_else(|_| {
                    panic!("{label}: stream worker did not stop after verifier pass")
                })
                .expect("stream task join");
            (final_text, verified_path)
        };
        tokio::time::timeout(Duration::from_secs(timeout_secs), fut)
            .await
            .unwrap_or_else(|_| panic!("{label}: real LLM turn timed out after {timeout_secs}s"))
    }

    fn verify_real_llm_agent_asset(root: &std::path::Path) -> Result<std::path::PathBuf, String> {
        let agent_md = find_required_file(root, "agent.md")?;
        let body = std::fs::read_to_string(&agent_md)
            .map_err(|e| format!("could not read {}: {e}", agent_md.display()))?;
        let def = a3s_code_core::subagent::parse_agent_md(&body)
            .map_err(|e| format!("{} is not a valid agent.md: {e}", agent_md.display()))?;
        if def.name.trim().is_empty() || def.description.trim().is_empty() {
            return Err("agent definition should carry name and description".to_string());
        }
        let package = agent_md.parent().unwrap();
        for rel in [
            "README.md",
            "prompts/system.md",
            "workflows/operating-procedure.md",
            "examples/example-input.md",
            "examples/example-output.md",
            "eval/smoke.md",
            "tests/smoke.md",
        ] {
            if !package.join(rel).is_file() {
                return Err(format!("agent package missing required file {rel}"));
            }
        }
        assert_asset_acl_only_metadata(package)?;
        assert_forbidden_asset_files(
            package,
            &[
                "agent.asset.json",
                "agent.config.json",
                "agent.runtime-binding.json",
                "runtime-binding.json",
                "package.json",
            ],
        )?;
        Ok(package.to_path_buf())
    }

    fn verify_real_llm_mcp_asset(root: &std::path::Path) -> Result<std::path::PathBuf, String> {
        let entrypoint = find_required_file(root, "server.js")
            .or_else(|_| find_required_file(root, "server.py"))
            .or_else(|_| find_required_file(root, "mcp.py"))?;
        let package = entrypoint.parent().unwrap();
        if !package.join("README.md").is_file() {
            return Err("missing MCP README.md".to_string());
        }
        assert_asset_acl_only_metadata(package)?;
        assert_forbidden_asset_files(
            package,
            &[
                "package.json",
                "mcp.asset.json",
                "mcp.server.json",
                "mcp.runtime-binding.json",
                "runtime-binding.json",
            ],
        )?;
        Ok(package.to_path_buf())
    }

    fn verify_real_llm_skill_asset(root: &std::path::Path) -> Result<std::path::PathBuf, String> {
        let skill_md = find_required_file(root, "SKILL.md")?;
        let skill = a3s_code_core::skills::Skill::from_file(&skill_md)
            .map_err(|e| format!("{} is not a valid SKILL.md: {e}", skill_md.display()))?;
        if skill.name.trim().is_empty() || skill.description.trim().is_empty() {
            return Err("skill should carry name and description".to_string());
        }
        let package = skill_md.parent().unwrap();
        if !package.join("README.md").is_file() {
            return Err("missing skill README.md".to_string());
        }
        assert_asset_acl_only_metadata(package)?;
        assert_forbidden_asset_files(
            package,
            &[
                "skill.asset.json",
                "skill.runtime-binding.json",
                "runtime-binding.json",
            ],
        )?;
        Ok(package.to_path_buf())
    }

    fn verify_real_llm_flow_asset(root: &std::path::Path) -> Result<std::path::PathBuf, String> {
        let flow_json = find_required_file(root, "flow.json")?;
        let flow = assert_json_file(&flow_json)?;
        let nodes = flow["nodes"]
            .as_array()
            .ok_or_else(|| "flow nodes must be an array".to_string())?;
        if !(nodes.iter().any(|node| node["kind"] == "start")
            && nodes.iter().any(|node| node["kind"] == "end"))
        {
            return Err("flow should have start and end nodes".to_string());
        }
        let package = flow_json.parent().unwrap();
        assert_asset_acl_only_metadata(package)?;
        assert_forbidden_asset_files(
            package,
            &[
                "workflow.design.json",
                "workflow.asset.json",
                "workflow.runtime-binding.json",
                "runtime-binding.json",
            ],
        )?;
        Ok(package.to_path_buf())
    }

    fn verify_real_llm_okf_asset(
        workspace: &std::path::Path,
    ) -> Result<std::path::PathBuf, String> {
        let root = workspace.join("okf");
        let readme = find_required_file(&root, "README.md")?;
        let package = readme.parent().unwrap().to_path_buf();
        if !package.join("README.md").is_file() {
            return Err("missing OKF README.md".to_string());
        }
        if !package.join("sources").is_dir() {
            return Err("missing OKF sources/".to_string());
        }
        if !package.join("wiki/index.md").is_file() {
            return Err("missing OKF wiki/index.md".to_string());
        }
        assert_asset_acl_only_metadata(&package)?;
        assert_forbidden_asset_files(
            &package,
            &[
                "package.okf.json",
                "knowledge.asset.json",
                "knowledge.runtime-binding.json",
                "runtime-binding.json",
            ],
        )?;
        Ok(package)
    }

    fn assert_asset_acl_only_metadata(package: &std::path::Path) -> Result<(), String> {
        let acl = package.join(".a3s/asset.acl");
        if !acl.is_file() {
            return Err(format!("missing {}", acl.display()));
        }
        let metadata_dir = package.join(".a3s");
        let entries = std::fs::read_dir(&metadata_dir)
            .map_err(|e| format!("could not read {}: {e}", metadata_dir.display()))?;
        for entry in entries.flatten() {
            let path = entry.path();
            let rel = path
                .strip_prefix(package)
                .unwrap_or(&path)
                .components()
                .map(|part| part.as_os_str().to_string_lossy())
                .collect::<Vec<_>>()
                .join("/");
            if rel != ".a3s/asset.acl" {
                return Err(format!(".a3s should contain only asset.acl, found {rel}"));
            }
        }
        Ok(())
    }

    fn assert_forbidden_asset_files(
        package: &std::path::Path,
        names: &[&str],
    ) -> Result<(), String> {
        let mut files = Vec::new();
        collect_all_files(package, &mut files);
        for file in files {
            let rel = file
                .strip_prefix(package)
                .unwrap_or(&file)
                .components()
                .map(|part| part.as_os_str().to_string_lossy())
                .collect::<Vec<_>>()
                .join("/");
            let basename = file
                .file_name()
                .and_then(|name| name.to_str())
                .unwrap_or("");
            if names.iter().any(|name| *name == rel || *name == basename) {
                return Err(format!("asset package should not contain {rel}"));
            }
        }
        Ok(())
    }

    fn collect_all_files(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_dir() {
                collect_all_files(&path, out);
            } else if path.is_file() {
                out.push(path);
            }
        }
    }

    fn find_required_file(
        root: &std::path::Path,
        name: &str,
    ) -> Result<std::path::PathBuf, String> {
        let mut matches = Vec::new();
        collect_files_named(root, name, &mut matches);
        matches.sort();
        matches
            .into_iter()
            .next()
            .ok_or_else(|| format!("expected {name} under {}", root.display()))
    }

    fn collect_files_named(root: &std::path::Path, name: &str, out: &mut Vec<std::path::PathBuf>) {
        let Ok(entries) = std::fs::read_dir(root) else {
            return;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_dir() {
                collect_files_named(&path, name, out);
            } else if path.file_name().and_then(|n| n.to_str()) == Some(name) {
                out.push(path);
            }
        }
    }

    fn assert_json_file(path: impl AsRef<std::path::Path>) -> Result<serde_json::Value, String> {
        let path = path.as_ref();
        let text = std::fs::read_to_string(path)
            .map_err(|e| format!("could not read JSON {}: {e}", path.display()))?;
        serde_json::from_str(&text)
            .map_err(|e| format!("{} is not valid JSON: {e}", path.display()))
    }

    #[test]
    fn asset_scaffolds_create_parseable_visible_file_formats() {
        let root = std::env::temp_dir().join(format!(
            "a3s-asset-format-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        let _ = std::fs::remove_dir_all(&root);
        std::fs::create_dir_all(&root).unwrap();

        let agent_root = root.join("agents");
        std::fs::create_dir_all(&agent_root).unwrap();
        let agent = panels::agent::scaffold_agent_package(
            "Name it exactly format-reviewer. It reviews asset file formats.",
            &agent_root,
        )
        .unwrap();
        assert_asset_acl_only_metadata(&agent.package_path).unwrap();
        assert_forbidden_asset_files(
            &agent.package_path,
            &[
                "agent.asset.json",
                "agent.config.json",
                "agent.runtime-binding.json",
                "runtime-binding.json",
                "package.json",
            ],
        )
        .unwrap();
        let agent_md = std::fs::read_to_string(agent.package_path.join("agent.md")).unwrap();
        let agent_def = a3s_code_core::subagent::parse_agent_md(&agent_md).unwrap();
        assert_eq!(agent_def.name, "format-reviewer");
        assert_eq!(agent_def.max_steps, Some(30));
        assert!(agent_def.description.contains("reviews asset file formats"));
        assert!(agent_def
            .prompt
            .as_deref()
            .is_some_and(|prompt| prompt.contains("# format-reviewer")));
        let agent_acl =
            std::fs::read_to_string(agent.package_path.join(asset_lifecycle::ASSET_ACL_PATH))
                .unwrap();
        assert_asset_acl_format(
            &agent_acl,
            "agent",
            &[
                "definition_path = \"agent.md\"",
                "package_path = \".\"",
                "runtime_kind = \"a3s-agent-service\"",
            ],
        );

        let mcp_root = root.join("mcps");
        std::fs::create_dir_all(&mcp_root).unwrap();
        let mcp = panels::mcp::scaffold_mcp_project(
            "Name it exactly format-tools. It exposes file format checks.",
            &mcp_root,
        )
        .unwrap();
        assert_asset_acl_only_metadata(&mcp.path).unwrap();
        assert_forbidden_asset_files(
            &mcp.path,
            &[
                "package.json",
                "mcp.asset.json",
                "mcp.server.json",
                "mcp.runtime-binding.json",
                "runtime-binding.json",
            ],
        )
        .unwrap();
        let server_js = std::fs::read_to_string(mcp.path.join("server.js")).unwrap();
        assert!(server_js.starts_with("const description = "));
        assert!(server_js.contains("process.stdin.on('data'"));
        assert!(server_js.contains("JSON.stringify(response)"));
        let mcp_acl =
            std::fs::read_to_string(mcp.path.join(asset_lifecycle::ASSET_ACL_PATH)).unwrap();
        assert_asset_acl_format(
            &mcp_acl,
            "mcp",
            &[
                "entrypoint = \"server.js\"",
                "package_root = \".\"",
                "runtime_kind = \"a3s-function-service\"",
                "protocol = \"mcp\"",
            ],
        );

        let skill_root = root.join("skills");
        std::fs::create_dir_all(&skill_root).unwrap();
        let skill = panels::skill::scaffold_skill_asset(
            "Name it exactly format-skill. It checks generated asset formats.",
            &skill_root,
        )
        .unwrap();
        let skill_package = skill.path.parent().unwrap();
        assert_asset_acl_only_metadata(skill_package).unwrap();
        assert_forbidden_asset_files(
            skill_package,
            &[
                "skill.asset.json",
                "skill.runtime-binding.json",
                "runtime-binding.json",
                "package.json",
            ],
        )
        .unwrap();
        let parsed_skill = a3s_code_core::skills::Skill::from_file(&skill.path).unwrap();
        assert_eq!(parsed_skill.name, "format-skill");
        assert!(matches!(
            parsed_skill.kind,
            a3s_code_core::skills::SkillKind::Instruction
        ));
        assert!(parsed_skill
            .allowed_tools
            .as_deref()
            .is_some_and(|tools| tools.contains("Read(*)")));
        let skill_acl =
            std::fs::read_to_string(skill_package.join(asset_lifecycle::ASSET_ACL_PATH)).unwrap();
        assert_asset_acl_format(
            &skill_acl,
            "skill",
            &[
                "definition_path = \"SKILL.md\"",
                "runtime_kind = \"a3s-function-service\"",
            ],
        );

        let flow_root = root.join("flows");
        std::fs::create_dir_all(&flow_root).unwrap();
        let flow_json = panels::flow::scaffold_flow_asset(
            "Name it exactly format-flow. It validates generated files.",
            &flow_root,
        )
        .unwrap();
        let flow_package = flow_json.parent().unwrap();
        assert_asset_acl_only_metadata(flow_package).unwrap();
        assert_forbidden_asset_files(
            flow_package,
            &[
                "workflow.design.json",
                "workflow.asset.json",
                "workflow.runtime-binding.json",
                "runtime-binding.json",
            ],
        )
        .unwrap();
        assert_eq!(
            flow_json.file_name().and_then(|name| name.to_str()),
            Some("flow.json")
        );
        let flow = assert_json_file(&flow_json).unwrap();
        assert_eq!(flow["version"], "a3s.workflow.design.v1");
        assert_eq!(flow["name"], "format-flow");
        let nodes = flow["nodes"].as_array().unwrap();
        assert_eq!(
            nodes.iter().filter(|node| node["kind"] == "start").count(),
            1
        );
        assert_eq!(nodes.iter().filter(|node| node["kind"] == "end").count(), 1);
        assert!(flow["edges"]
            .as_array()
            .unwrap()
            .iter()
            .all(|edge| edge.get("sourceNodeID").is_some() && edge.get("targetNodeID").is_some()));
        let flow_acl =
            std::fs::read_to_string(flow_package.join(asset_lifecycle::ASSET_ACL_PATH)).unwrap();
        assert_asset_acl_format(
            &flow_acl,
            "workflow",
            &[
                "design_document_path = \"flow.json\"",
                "runtime_kind = \"a3s-workflow-service\"",
                "protocol = \"workflow\"",
            ],
        );

        let okf_root = root.join("okf");
        std::fs::create_dir_all(&okf_root).unwrap();
        let okf = panels::okf::scaffold_okf_package(
            "Name it exactly format-knowledge. It documents asset formats.",
            &okf_root,
        )
        .unwrap();
        assert_asset_acl_only_metadata(&okf.path).unwrap();
        assert_forbidden_asset_files(
            &okf.path,
            &[
                "package.okf.json",
                "knowledge.asset.json",
                "knowledge.runtime-binding.json",
                "runtime-binding.json",
                "package.json",
            ],
        )
        .unwrap();
        assert!(std::fs::read_to_string(okf.path.join("README.md"))
            .unwrap()
            .starts_with("# format-knowledge\n\n"));
        assert!(okf.path.join("sources/overview.md").is_file());
        assert!(okf.path.join("wiki/index.md").is_file());
        assert!(okf.path.join("wiki/concepts/example.md").is_file());
        assert!(okf.path.join("eval/smoke.md").is_file());
        let okf_acl =
            std::fs::read_to_string(okf.path.join(asset_lifecycle::ASSET_ACL_PATH)).unwrap();
        assert_asset_acl_format(
            &okf_acl,
            "knowledge",
            &[
                "readme_path = \"README.md\"",
                "sources_path = \"sources\"",
                "wiki_path = \"wiki\"",
                "eval_path = \"eval\"",
                "runtime_kind = \"a3s-knowledge-service\"",
                "protocol = \"okf\"",
            ],
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    fn assert_asset_acl_format(acl: &str, category: &str, required: &[&str]) {
        assert!(acl.starts_with("version = \"a3s.asset.v1\"\n"), "{acl}");
        assert!(acl.contains(&format!("category = \"{category}\"")), "{acl}");
        assert!(acl.contains("created_by = \"a3s-code-tui\""), "{acl}");
        assert!(acl.contains("source {\n"), "{acl}");
        assert!(acl.contains("metadata {\n"), "{acl}");
        assert!(acl.contains("asset_acl_path = \".a3s/asset.acl\""), "{acl}");
        assert!(acl.contains("runtime {\n"), "{acl}");
        for field in required {
            assert!(acl.contains(field), "missing {field} in:\n{acl}");
        }
    }

    #[tokio::test]
    async fn claude_session_surface_passes_system_tools_and_skills_to_llm() {
        let dir = std::env::temp_dir().join(format!(
            "a3s-claude-surface-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let cfg = dir.join("config.acl");
        test_config(&cfg);
        std::fs::write(
            dir.join("CLAUDE.md"),
            "Project rule: claude-session-surface-marker",
        )
        .unwrap();
        let skill_dir = dir.join(".claude/skills/inspect-surface");
        std::fs::create_dir_all(&skill_dir).unwrap();
        std::fs::write(
            skill_dir.join("SKILL.md"),
            "---\nname: inspect-surface\n\
             description: Inspect the Claude session surface\n\
             kind: instruction\n\
             allowed-tools:\n  - Read\n---\n\
             Use this skill marker: inspect-surface-skill-marker\n",
        )
        .unwrap();

        let agent = a3s_code_core::Agent::new(cfg.to_string_lossy().to_string())
            .await
            .unwrap();
        let llm = Arc::new(CaptureLlmClient::new(vec![done_response()]));
        let opts = SessionOptions::new()
            .with_llm_client(llm.clone())
            .with_prompt_slots(
                SystemPromptSlots::default()
                    .with_extra(project_instructions(dir.to_str().unwrap()).unwrap()),
            )
            .with_skill_dirs(agent_skill_dirs(dir.to_str().unwrap()))
            .with_manual_delegation_enabled(true)
            .with_auto_delegation_enabled(false)
            .with_planning_mode(a3s_code_core::PlanningMode::Disabled);
        let session = agent
            .session(dir.to_string_lossy().to_string(), Some(opts))
            .unwrap();

        let (mut rx, join) = session
            .stream("Use available skills to inspect this project.", None)
            .await
            .unwrap();
        while let Some(event) = rx.recv().await {
            if matches!(event, a3s_code_core::AgentEvent::End { .. }) {
                break;
            }
        }
        join.await.unwrap();
        let turns = llm.turns();
        let captured = turns.first().unwrap();
        let system = captured.system.as_deref().unwrap();
        let _ = std::fs::remove_dir_all(&dir);

        assert!(
            system.contains("You are A3S Code"),
            "core system prompt should reach the LLM"
        );
        assert!(
            system.contains("claude-session-surface-marker"),
            "CLAUDE.md project instructions should reach the LLM"
        );
        assert!(
            system.contains("# Skills"),
            "skill catalog guidance should reach the LLM system prompt"
        );
        assert!(
            captured.tools.iter().any(|name| name == "read")
                && captured.tools.iter().any(|name| name == "Skill")
                && captured.tools.iter().any(|name| name == "search_skills")
                && captured.tools.iter().any(|name| name == "parallel_task"),
            "a3s tools and skill tools should be model-visible; got {:?}",
            captured.tools
        );
    }

    #[tokio::test]
    async fn claude_can_invoke_skill_and_child_run_receives_skill_prompt() {
        let dir = std::env::temp_dir().join(format!(
            "a3s-claude-skill-invoke-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        let cfg = dir.join("config.acl");
        test_config(&cfg);
        let skill_dir = dir.join(".claude/skills/inspect-surface");
        std::fs::create_dir_all(&skill_dir).unwrap();
        std::fs::write(
            skill_dir.join("SKILL.md"),
            "---\nname: inspect-surface\n\
             description: Inspect the Claude session surface\n\
             kind: instruction\n\
             allowed-tools:\n  - Read\n---\n\
             Use this skill marker: inspect-surface-skill-marker\n",
        )
        .unwrap();

        let agent = a3s_code_core::Agent::new(cfg.to_string_lossy().to_string())
            .await
            .unwrap();
        let llm = Arc::new(CaptureLlmClient::new(vec![
            tool_call_response(
                "Skill",
                serde_json::json!({
                    "skill_name": "inspect-surface",
                    "prompt": "Apply the inspect-surface skill."
                }),
            ),
            done_response(),
            done_response(),
        ]));
        let opts = SessionOptions::new()
            .with_llm_client(llm.clone())
            .with_skill_dirs(agent_skill_dirs(dir.to_str().unwrap()))
            .with_manual_delegation_enabled(true)
            .with_auto_delegation_enabled(false)
            .with_permission_policy(
                a3s_code_core::permissions::PermissionPolicy::new().allow("Skill(*)"),
            )
            .with_planning_mode(a3s_code_core::PlanningMode::Disabled)
            .with_max_tool_rounds(5);
        let session = agent
            .session(dir.to_string_lossy().to_string(), Some(opts))
            .unwrap();

        let result = session
            .send("Use the inspect-surface skill.", None)
            .await
            .unwrap();
        let turns = llm.turns();
        let _ = std::fs::remove_dir_all(&dir);

        assert_eq!(result.text.trim(), "DONE");
        let system_snippets = turns
            .iter()
            .enumerate()
            .map(|(index, turn)| {
                format!(
                    "#{index}: {}",
                    turn.system
                        .as_deref()
                        .unwrap_or("<none>")
                        .chars()
                        .take(220)
                        .collect::<String>()
                )
            })
            .collect::<Vec<_>>()
            .join("\n");
        assert!(
            turns
                .iter()
                .any(|turn| turn.system.as_deref().is_some_and(|system| {
                    system.contains("You are executing the 'inspect-surface' skill")
                        && system.contains("inspect-surface-skill-marker")
                })),
            "Skill tool should start a child LLM run with the skill prompt; turns: {}",
            system_snippets
        );
    }

    #[test]
    fn workflow_doc_captures_single_task_dispatch() {
        let args = serde_json::json!({
            "agent": "plan",
            "description": "Design the rendering architecture",
            "prompt": "Plan a layered renderer."
        });
        let (doc, label) = workflow_doc_for_tool("task", Some(&args)).unwrap();

        assert!(label.contains("delegated task"), "{label}");
        assert!(doc.contains("Design the rendering architecture"));
        assert!(doc.contains("Agent: `plan`"));
        assert!(doc.contains("Plan a layered renderer."));
    }

    #[test]
    fn workflow_doc_captures_dynamic_workflow_tool_without_flow_command() {
        let args = serde_json::json!({
            "source": "async function run(ctx, inputs) { return { type: 'complete', output: inputs }; }"
        });
        let (doc, label) = workflow_doc_for_tool("dynamic_workflow", Some(&args)).unwrap();

        assert!(
            label.contains("dynamic workflow script captured"),
            "{label}"
        );
        assert!(!label.contains("/flow"), "{label}");
        assert!(doc.contains("async function run"));
    }

    #[test]
    fn synthesis_requires_activity_without_followup_text() {
        // Fires when a turn had agent activity but produced no final text — in
        // ANY mode (no effort gate), so a high-effort fan-out that ends silently
        // still gets a synthesized answer.
        assert!(needs_synthesis(false, false, true, false));
        // No final answer needed if the turn already produced text after activity.
        assert!(!needs_synthesis(false, false, true, true));
        // At most once per turn.
        assert!(!needs_synthesis(false, true, true, false));
        // Nothing to synthesize if no work happened (e.g. a bare greeting).
        assert!(!needs_synthesis(false, false, false, false));
        // Never while a synthesis turn is itself in flight.
        assert!(!needs_synthesis(true, false, true, false));
    }

    #[test]
    fn estimate_tokens_counts_wide_unicode_heavier_than_ascii() {
        assert_eq!(estimate_tokens("abcd"), 1); // ASCII ~4 chars/token
        assert_eq!(estimate_tokens("かなテストあ"), 6); // wide text ~1 token/char
        assert_eq!(estimate_tokens("hi かな"), 2); // mixed: 3 ASCII -> 0, 2 wide -> 2
        assert_eq!(estimate_tokens(""), 0);
    }

    #[test]
    fn ctx_limit_falls_back_when_undeclared() {
        let default_context_limit = resolve_ctx_limit(None);
        assert_eq!(resolve_ctx_limit(Some(200_000)), 200_000); // declared wins
        assert_eq!(resolve_ctx_limit(Some(0)), default_context_limit); // zero -> default
        assert_eq!(resolve_ctx_limit(None), default_context_limit); // missing -> default
    }

    #[test]
    fn ctx_limit_prefers_declared_then_infers_account_models() {
        let mut ctx = std::collections::HashMap::new();
        ctx.insert("openai/gpt-5".to_string(), 256_000);

        assert_eq!(ctx_limit_for_model(&ctx, "openai/gpt-5"), 256_000);
        assert_eq!(
            crate::budget::inferred_context_limit_for_model("claude-sonnet-4-6"),
            Some(200_000)
        );
        assert_eq!(
            crate::budget::inferred_context_limit_for_model("claude-opus-4-8[1m]"),
            Some(1_000_000)
        );
        assert_eq!(
            crate::budget::inferred_context_limit_for_model("gpt-4.1"),
            Some(1_000_000)
        );
        assert_eq!(
            crate::budget::inferred_context_limit_for_model("glm-5.1"),
            Some(resolve_ctx_limit(None))
        );
        assert_eq!(
            ctx_limit_for_model(&ctx, "unknown-model"),
            resolve_ctx_limit(None)
        );
    }

    #[test]
    fn auto_compact_threshold_scales_to_real_window() {
        // 128k model: fire at 85% of 128k, i.e. 0.85*128/200 of the core's fixed 200k.
        assert!((auto_compact_threshold_for(128_000) - 0.544).abs() < 0.001);
        // 200k model == the core's own denominator: plain 0.85.
        assert!((auto_compact_threshold_for(200_000) - 0.85).abs() < 0.001);
        // Windows past ~235k clamp to 1.0 (trigger at the fixed 200k, never overflow).
        assert_eq!(auto_compact_threshold_for(1_000_000), 1.0);
        // Unknown window (0) falls back to the core default of 0.85.
        assert!((auto_compact_threshold_for(0) - 0.85).abs() < 0.001);
        // Small window: NOT floored past the window itself — 8k triggers at
        // 0.034 * 200k = 6.8k = 85% of 8k (the old 0.05 floor meant 10k > 8k,
        // i.e. compaction could never fire before overflow).
        assert!((auto_compact_threshold_for(8_000) - 0.034).abs() < 0.001);
    }

    #[test]
    fn ctx_warn_tier_latches_once_and_rearms_on_drop() {
        // Climb: 0 → warn at 70 tier → no re-warn inside the tier → warn at 85.
        assert_eq!(ctx_warn_tier(40, 0), (0, None));
        assert_eq!(ctx_warn_tier(72, 0), (70, Some(70)));
        assert_eq!(ctx_warn_tier(79, 70), (70, None)); // same tier: silent
        assert_eq!(ctx_warn_tier(91, 70), (85, Some(85)));
        assert_eq!(ctx_warn_tier(100, 85), (85, None));
        // Drop (compaction, /clear, wider model): latch re-arms.
        assert_eq!(ctx_warn_tier(30, 85), (0, None));
        assert_eq!(ctx_warn_tier(72, 0), (70, Some(70)));
        // Jump straight past both tiers warns the top one only.
        assert_eq!(ctx_warn_tier(90, 0), (85, Some(85)));
    }

    #[test]
    fn task_tool_empty_child_output_renders_useful_summary() {
        let args = serde_json::json!({
            "agent": "plan",
            "description": "Plan subsystem boundaries",
            "prompt": "Create the plan."
        });
        let meta = serde_json::json!({
            "task_id": "task-abc123",
            "session_id": "task-run-task-abc123",
            "agent": "plan",
            "success": true,
            "output_bytes": 0,
            "artifact_uri": "a3s://tasks/task-run-task-abc123/runs/task-abc123/output"
        });
        let output = "Task completed: task-abc123\n\
                      Agent: plan\n\
                      Session: task-run-task-abc123\n\
                      Task ID: task-abc123\n\
                      Artifact ID: task-output:task-abc123\n\
                      Artifact URI: a3s://tasks/task-run-task-abc123/runs/task-abc123/output\n\
                      Output:\n";
        let out = render_tool_end("task", 0, output, Some(&meta), Some(&args), 100);
        let plain = strip_ansi(&out);

        assert!(plain.contains("Explored"));
        assert!(plain.contains("Task completed · plan · task-abc123"));
        assert!(plain.contains("no child text output"));
        assert!(plain.contains("artifact: a3s://tasks/task-run-task-abc123"));
    }

    #[test]
    fn edit_metadata_renders_colored_diff() {
        let meta = serde_json::json!({
            "file_path": "src/x.rs",
            "before": "let a = 1;\nkeep;\n",
            "after": "let a = 2;\nkeep;\n",
        });
        let out = render_tool_end("edit", 0, "ok", Some(&meta), None, 80);
        // The diff code is syntax-highlighted (ANSI between tokens), so compare
        // against the ANSI-stripped text.
        let plain = strip_ansi(&out);
        assert!(plain.contains("src/x.rs"), "header has path");
        assert!(
            plain.contains("+1") && plain.contains("-1"),
            "add/del counts"
        );
        assert!(plain.contains("let a = 2;"), "shows inserted line");
        assert!(plain.contains("let a = 1;"), "shows deleted line");
        assert!(
            plain.contains("keep;"),
            "context lines are shown (unified diff)"
        );
        assert!(plain.contains("Edited src/x.rs"), "edit header with path");
    }

    /// Strip ANSI SGR sequences so tests can match the underlying text.
    fn strip_ansi(s: &str) -> String {
        let mut out = String::new();
        let mut chars = s.chars();
        while let Some(c) = chars.next() {
            if c == '\x1b' {
                for c2 in chars.by_ref() {
                    if c2 == 'm' {
                        break;
                    }
                }
            } else {
                out.push(c);
            }
        }
        out
    }

    #[test]
    fn non_edit_tool_renders_status_line() {
        let out = render_tool_end("bash", 0, "hello\nworld", None, None, 80);
        // Action-verb header ("Ran") + the output; no diff marker.
        assert!(out.contains("Ran") && out.contains("hello"));
        assert!(!out.contains('✎'), "no diff marker for non-edit tools");
    }

    #[test]
    fn tool_end_shows_primary_arg_summary() {
        let args = serde_json::json!({ "command": "npm test", "timeout": 60 });
        let out = render_tool_end("bash", 0, "ok\n", None, Some(&args), 80);
        // Bash args are token-colored (program/flags/args), so check visible text.
        let plain = a3s_tui::style::strip_ansi(&out);
        assert!(plain.contains("Ran"), "action verb for bash");
        assert!(plain.contains("npm test"), "shows the command argument");
    }

    #[test]
    fn arg_summary_extracts_known_keys() {
        assert_eq!(
            arg_summary(&serde_json::json!({ "command": "ls -la" })),
            Some("ls -la".to_string())
        );
        assert_eq!(
            arg_summary(&serde_json::json!({ "pattern": "TODO" })),
            Some("TODO".to_string())
        );
        assert_eq!(arg_summary(&serde_json::json!({ "unknown": "x" })), None);
    }

    #[test]
    fn slash_tail_requires_a_token_boundary() {
        let parameterized = [
            "/login", "/ctx", "/kb", "/okf", "/btw", "/goal", "/loop", "/sleep", "/flow", "/agent",
            "/mcp", "/skill",
        ];

        for cmd in parameterized {
            assert_eq!(slash_tail(cmd, cmd), Some(""), "{cmd} accepts bare form");
            assert_eq!(
                slash_tail(&format!("{cmd} argument"), cmd),
                Some(" argument"),
                "{cmd} accepts whitespace-delimited arguments"
            );
            assert_eq!(
                slash_tail(&format!("{cmd}x"), cmd),
                None,
                "{cmd}x must remain a normal message, not {cmd}"
            );
            assert_eq!(
                slash_tail(&format!("{cmd}-token"), cmd),
                None,
                "{cmd}-token must remain a normal message, not {cmd}"
            );
        }
    }

    #[test]
    fn cloned_asset_focus_matches_only_paths_inside_the_clone_root() {
        let clone_root = std::path::Path::new("/tmp/a3s-assets/weather-agent");
        assert!(App::path_is_within(clone_root, clone_root));
        assert!(App::path_is_within(
            std::path::Path::new("/tmp/a3s-assets/weather-agent/agent.md"),
            clone_root
        ));
        assert!(App::path_is_within(
            std::path::Path::new("/tmp/a3s-assets/weather-agent/nested/asset.json"),
            clone_root
        ));
        assert!(!App::path_is_within(
            std::path::Path::new("/tmp/a3s-assets/weather-agent-2/agent.md"),
            clone_root
        ));
    }

    #[test]
    fn runtime_asset_query_carries_asset_category_and_terms() {
        assert_eq!(
            runtime_asset_query("mcp", "Calc Tools", "failed calls"),
            "category:mcp Calc Tools failed calls"
        );
        assert_eq!(
            runtime_asset_query("workflow", "daily-flow", ""),
            "category:workflow daily-flow"
        );
        assert_eq!(runtime_asset_query("", "", "stale"), "stale");
    }

    #[test]
    fn slash_command_registry_is_unique_english_and_idle_safe() {
        let mut seen = HashSet::new();
        for (cmd, desc) in SLASH_COMMANDS {
            assert!(cmd.starts_with('/'), "{cmd} should be a slash command");
            assert!(
                !cmd.contains(char::is_whitespace),
                "{cmd} should be the bare command token"
            );
            assert!(seen.insert(*cmd), "{cmd} should not be registered twice");
            assert!(
                !desc.trim().is_empty(),
                "{cmd} should have a menu description"
            );
            assert!(
                !contains_cjk(desc),
                "{cmd} description should stay English-only: {desc}"
            );
            assert!(
                !desc.to_ascii_lowercase().contains("repo"),
                "{cmd} slash-menu copy should not expose asset-workspace management: {desc}"
            );
        }

        for cmd in IDLE_ONLY {
            assert!(
                SLASH_COMMANDS
                    .iter()
                    .any(|(registered, _)| registered == cmd),
                "{cmd} is idle-only but missing from the slash registry"
            );
        }

        let removed_commands = [
            "im", "run", "deploy", "review", "list", "ps", "workflow", "repo", "git", "relay",
        ]
        .into_iter()
        .map(|name| format!("/{name}"))
        .chain([
            format!("/{}{}", "evo", "lve"),
            format!("/{}{}", "evo", "love"),
        ]);
        for removed in removed_commands {
            assert!(
                !SLASH_COMMANDS
                    .iter()
                    .any(|(cmd, _)| *cmd == removed.as_str()),
                "{removed} should stay removed from the slash registry"
            );
        }
    }

    #[test]
    fn asset_root_commands_are_backed_by_lifecycle_services() {
        let asset_commands: HashSet<&str> = asset_lifecycle::ASSET_LIFECYCLES
            .iter()
            .map(|lifecycle| lifecycle.command)
            .collect();
        assert_eq!(
            asset_commands,
            HashSet::from(["/agent", "/mcp", "/skill", "/okf", "/flow"])
        );

        for command in asset_commands {
            let menu_desc = SLASH_COMMANDS
                .iter()
                .find_map(|(cmd, desc)| (*cmd == command).then_some(*desc))
                .unwrap_or_else(|| panic!("{command} should be registered in the slash menu"));
            let services: HashSet<&str> = asset_lifecycle::ASSET_LIFECYCLES
                .iter()
                .filter(|lifecycle| lifecycle.command == command)
                .map(|lifecycle| asset_lifecycle::service_label(lifecycle.service))
                .collect();

            for service in services {
                assert!(
                    menu_desc.contains(service),
                    "{command} slash-menu copy should name {service}: {menu_desc}"
                );
            }
            assert!(
                !menu_desc.contains("lifecycle"),
                "{command} slash-menu copy should name concrete OS services, not generic lifecycle wording: {menu_desc}"
            );
        }
    }

    #[test]
    fn cancel_pending_picker_clears_panel_and_deferred_asset_command() {
        let mut picker = Some("agent selector");
        let mut pending = Some("review");

        cancel_pending_picker(&mut picker, &mut pending);

        assert!(picker.is_none());
        assert!(pending.is_none());
    }

    #[test]
    fn registered_slash_commands_have_declared_handler_paths() {
        let parameterized = HashSet::from([
            "/login", "/ctx", "/kb", "/okf", "/btw", "/goal", "/loop", "/sleep", "/flow", "/agent",
            "/mcp", "/skill",
        ]);
        let exact = HashSet::from([
            "/logout", "/exit", "/fork", "/clear", "/init", "/compact", "/help", "/auto",
            "/config", "/model", "/effort", "/top", "/ide", "/plugin", "/theme", "/output",
            "/reload", "/update", "/memory",
        ]);

        for (cmd, _) in SLASH_COMMANDS {
            assert!(
                parameterized.contains(cmd) || exact.contains(cmd),
                "{cmd} is registered but not mapped to a handler category"
            );
        }
    }

    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    enum SlashHandlerKind {
        Exact,
        Parameterized,
    }

    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
    enum SlashRuntimeScope {
        Local,
        OsAccount,
        RuntimeConditional,
    }

    #[derive(Clone, Copy, Debug)]
    struct SlashAuditRow {
        command: &'static str,
        handler: SlashHandlerKind,
        idle_only: bool,
        scope: SlashRuntimeScope,
    }

    fn slash_audit_rows() -> Vec<SlashAuditRow> {
        use SlashHandlerKind::{Exact, Parameterized};
        use SlashRuntimeScope::{Local, OsAccount, RuntimeConditional};

        vec![
            SlashAuditRow {
                command: "/model",
                handler: Exact,
                idle_only: true,
                scope: OsAccount,
            },
            SlashAuditRow {
                command: "/init",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/config",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/theme",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/flow",
                handler: Parameterized,
                idle_only: true,
                scope: OsAccount,
            },
            SlashAuditRow {
                command: "/agent",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/mcp",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/skill",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/okf",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/output",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/login",
                handler: Parameterized,
                idle_only: false,
                scope: OsAccount,
            },
            SlashAuditRow {
                command: "/logout",
                handler: Exact,
                idle_only: false,
                scope: OsAccount,
            },
            SlashAuditRow {
                command: "/plugin",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/reload",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/update",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/btw",
                handler: Parameterized,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/top",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/ide",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/memory",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/kb",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/ctx",
                handler: Parameterized,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/effort",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/compact",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/goal",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/loop",
                handler: Parameterized,
                idle_only: true,
                scope: RuntimeConditional,
            },
            SlashAuditRow {
                command: "/sleep",
                handler: Parameterized,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/help",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/fork",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/clear",
                handler: Exact,
                idle_only: true,
                scope: Local,
            },
            SlashAuditRow {
                command: "/auto",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
            SlashAuditRow {
                command: "/exit",
                handler: Exact,
                idle_only: false,
                scope: Local,
            },
        ]
    }

    #[test]
    fn slash_command_audit_matrix_matches_registry_and_policies() {
        let rows = slash_audit_rows();
        let registered = SLASH_COMMANDS
            .iter()
            .map(|(cmd, _)| *cmd)
            .collect::<HashSet<_>>();
        let audited = rows.iter().map(|row| row.command).collect::<HashSet<_>>();

        assert_eq!(
            registered, audited,
            "every registered command must have explicit audit metadata"
        );

        let idle_from_rows = rows
            .iter()
            .filter(|row| row.idle_only)
            .map(|row| row.command)
            .collect::<HashSet<_>>();
        let idle_from_const = IDLE_ONLY.iter().copied().collect::<HashSet<_>>();
        assert_eq!(
            idle_from_rows, idle_from_const,
            "idle-only policy should stay in sync with the audit matrix"
        );

        let parameterized_names = HashSet::from([
            "/login", "/ctx", "/kb", "/okf", "/btw", "/goal", "/loop", "/sleep", "/flow", "/agent",
            "/mcp", "/skill",
        ]);
        for row in &rows {
            match row.handler {
                SlashHandlerKind::Parameterized => {
                    assert!(
                        parameterized_names.contains(row.command),
                        "{} should be in the token-boundary handler set",
                        row.command
                    );
                    assert!(
                        slash_tail(row.command, row.command).is_some(),
                        "{} should be token-boundary parsed",
                        row.command
                    );
                }
                SlashHandlerKind::Exact => {
                    assert!(
                        !parameterized_names.contains(row.command),
                        "{} exact command should not be in the token-boundary handler set",
                        row.command
                    );
                }
            }
        }

        let loop_row = rows.iter().find(|row| row.command == "/loop").unwrap();
        assert_eq!(loop_row.scope, SlashRuntimeScope::RuntimeConditional);
        for cmd in ["/agent", "/mcp", "/skill", "/okf", "/kb", "/ctx"] {
            let row = rows.iter().find(|row| row.command == cmd).unwrap();
            assert_eq!(row.scope, SlashRuntimeScope::Local);
        }
    }

    #[test]
    fn removed_top_level_aliases_stay_unregistered() {
        let removed = [
            "/view".to_string(),
            "/mouse".to_string(),
            "/plugins".to_string(),
            "/quit".to_string(),
            format!("/{}{}", "re", "po"),
            format!("/{}{}", "re", "lay"),
        ];
        for alias in removed {
            assert!(
                !SLASH_COMMANDS.iter().any(|(cmd, _)| *cmd == alias.as_str()),
                "{alias} should stay removed from the slash registry"
            );
        }
    }

    #[test]
    fn ampersand_clone_review_syntax_stays_removed() {
        assert!(
            slash_candidates("&").is_empty(),
            "asset clone shortcuts must not return to the slash menu"
        );
        assert!(
            !SLASH_COMMANDS.iter().any(|(cmd, _)| cmd.starts_with('&')),
            "asset clone/review flows must stay under typed asset subcommands"
        );
    }

    #[test]
    fn reload_is_idle_only_because_it_rebuilds_the_session() {
        assert!(IDLE_ONLY.contains(&"/reload"));
    }

    #[test]
    fn fork_is_idle_only_and_listed() {
        // /fork swaps the active session, so it must not run mid-stream…
        assert!(IDLE_ONLY.contains(&"/fork"));
        // …and it's offered in the slash menu.
        assert!(SLASH_COMMANDS.iter().any(|(name, _)| *name == "/fork"));
    }

    #[test]
    fn asset_workflow_commands_are_idle_only_and_listed() {
        for cmd in ["/flow", "/agent", "/mcp", "/skill", "/okf"] {
            assert!(
                IDLE_ONLY.contains(&cmd),
                "{cmd} must not arm asset workflows while another turn is running"
            );
            assert!(
                SLASH_COMMANDS.iter().any(|(name, _)| *name == cmd),
                "{cmd} should be visible in the slash menu while idle"
            );
        }
    }

    #[test]
    fn runtime_activity_are_asset_scoped_not_top_level() {
        let top_level_ps = format!("/{}", "ps");
        assert!(
            !SLASH_COMMANDS
                .iter()
                .any(|(name, _)| *name == top_level_ps.as_str()),
            "runtime activity browsing should stay asset-scoped"
        );
        assert!(matches!(
            panels::agent::parse_agent_subcommand("activity")
                .unwrap()
                .unwrap(),
            panels::agent::AgentSubcommand::Activity(_)
        ));
        assert!(panels::agent::parse_agent_subcommand("ps")
            .unwrap()
            .is_err());
        assert!(matches!(
            panels::mcp::parse_mcp_subcommand("activity")
                .unwrap()
                .unwrap(),
            panels::mcp::McpSubcommand::Activity(_)
        ));
        assert!(panels::mcp::parse_mcp_subcommand("ps").unwrap().is_err());
        assert!(matches!(
            panels::flow::parse_flow_subcommand("activity")
                .unwrap()
                .unwrap(),
            panels::flow::FlowSubcommand::Activity(_)
        ));
        assert!(panels::flow::parse_flow_subcommand("ps").unwrap().is_err());
        assert!(matches!(
            panels::skill::parse_skill_subcommand("activity")
                .unwrap()
                .unwrap(),
            panels::skill::SkillSubcommand::Activity(_)
        ));
        assert!(panels::skill::parse_skill_subcommand("ps")
            .unwrap()
            .is_err());
        assert!(matches!(
            panels::okf::parse_okf_command("activity"),
            panels::okf::OkfCommand::Activity(_)
        ));
        assert!(matches!(
            panels::okf::parse_okf_command("ps"),
            panels::okf::OkfCommand::Usage(_)
        ));
    }

    #[test]
    fn runtime_expectation_warns_once_until_evidence_arrives() {
        let mut missing = RuntimeExpectation::required("deep research");
        let warning = missing.missing_warning().unwrap();
        assert!(warning.contains("Runtime evidence missing"), "{warning}");
        assert!(missing.missing_warning().is_none());

        let mut via_runtime = RuntimeExpectation::required("run");
        via_runtime.record_tool("runtime");
        assert!(via_runtime.is_satisfied());
        assert!(via_runtime.missing_warning().is_none());

        let mut via_parallel = RuntimeExpectation::required("review");
        via_parallel.record_tool("parallel_task");
        assert!(via_parallel.is_satisfied());

        let mut via_dynamic_workflow = RuntimeExpectation::required("research");
        via_dynamic_workflow.record_tool("dynamic_workflow");
        assert!(via_dynamic_workflow.is_satisfied());

        let mut via_view = RuntimeExpectation::required("deploy");
        via_view.record_remote_view();
        assert!(via_view.is_satisfied());

        let mut report_only_runtime = RuntimeExpectation::required_report_view("deep research");
        report_only_runtime.record_tool("runtime");
        assert!(!report_only_runtime.is_satisfied());
        let warning = report_only_runtime.missing_warning().unwrap();
        assert!(warning.contains("report"), "{warning}");
        assert!(warning.contains(".view"), "{warning}");
        let correction = report_only_runtime.corrective_prompt().unwrap();
        assert!(correction.contains("deep research"), "{correction}");
        assert!(correction.contains("dynamic_workflow"), "{correction}");
        assert!(correction.contains("OS Runtime"), "{correction}");
        assert!(correction.contains(".view"), "{correction}");
        assert!(correction.contains("viewUrl"), "{correction}");

        let mut report_only_view = RuntimeExpectation::required_report_view("loop daily-triage");
        report_only_view.record_remote_view();
        assert!(!report_only_view.is_satisfied());
        let warning = report_only_view.missing_warning().unwrap();
        assert!(warning.contains("fan-out"), "{warning}");
        let correction = report_only_view.corrective_prompt().unwrap();
        assert!(correction.contains("fan-out"), "{correction}");

        let mut full_report = RuntimeExpectation::required_report_view("deep research");
        full_report.record_tool("dynamic_workflow");
        full_report.record_remote_view();
        assert!(full_report.is_satisfied());
        assert!(full_report.missing_warning().is_none());
        assert!(full_report.corrective_prompt().is_none());
    }

    #[test]
    fn remote_view_detection_only_marks_new_specs() {
        let spec = remote_ui::ViewSpec {
            url: "https://os.example.com/admin/runtime/jobs/1?embed=1".into(),
            width: Some(1200),
            height: Some(800),
            embeddable: true,
        };

        assert!(is_new_remote_view(None, &spec));
        assert!(!is_new_remote_view(Some(&spec), &spec));
    }

    #[test]
    fn os_required_message_distinguishes_missing_config_from_missing_login() {
        let configured = os_required_message("/agent run", true);
        assert!(configured.contains("/login"));
        assert!(!configured.contains("configure `os"));

        let missing = os_required_message("/agent deploy", false);
        assert!(missing.contains("configure `os"));
        assert!(missing.contains("/login"));
    }

    #[test]
    fn os_required_alert_uses_shared_warning_line() {
        let rendered = os_required_alert("/agent run", true);

        assert_eq!(
            a3s_tui::style::strip_ansi(&rendered),
            "  ⚠ /agent run needs OS — sign in with /login first"
        );
        assert!(rendered.contains("\x1b[38;2;245;166;35m"));
    }

    #[test]
    fn ide_flash_line_uses_shared_toast_component() {
        let rendered = ide_flash_line(ToastKind::Warning, "read-only");

        assert_eq!(a3s_tui::style::strip_ansi(&rendered), "⚠ read-only");
        assert!(rendered.contains("\x1b[38;2;245;166;35m"));
    }

    // ---- image preview (/ide + paste) ----

    #[test]
    fn image_path_detection() {
        assert!(is_image_path(std::path::Path::new("a.PNG")));
        assert!(is_image_path(std::path::Path::new("x/y.jpeg")));
        assert!(!is_image_path(std::path::Path::new("main.rs")));
        assert!(!is_image_path(std::path::Path::new("noext")));
    }

    #[test]
    fn half_block_render_packs_two_rows_and_colors() {
        // 6px tall image -> 3 half-block rows; each row is colored ▀ cells.
        let img = ::image::DynamicImage::ImageRgba8(::image::RgbaImage::from_pixel(
            4,
            6,
            ::image::Rgba([10, 20, 30, 255]),
        ));
        let lines = render_image_blocks(&img, 80, 40);
        assert_eq!(lines.len(), 3, "6px / 2 = 3 rows");
        assert!(lines[0].contains('▀'), "uses upper half-block");
        assert!(lines[0].contains("\x1b["), "carries ANSI color");
    }

    #[test]
    fn half_block_render_fits_within_bounds() {
        let img = ::image::DynamicImage::ImageRgba8(::image::RgbaImage::new(400, 400));
        let lines = render_image_blocks(&img, 20, 10);
        assert!(lines.len() <= 10, "never exceeds max_rows");
    }

    #[test]
    fn clipboard_helper_cleans_up_on_no_image() {
        // No way to guarantee an empty clipboard, but the helper must never
        // leave a stray empty file behind when it fails.
        let dest = std::env::temp_dir().join("a3s-test-noimg.png");
        let _ = std::fs::remove_file(&dest);
        let ok = clipboard_image_to(&dest);
        if !ok {
            assert!(!dest.exists(), "failed paste leaves no file");
        } else {
            let _ = std::fs::remove_file(&dest);
        }
    }

    // ---- /ide editor cursor math (multi-byte safe) ----

    #[test]
    fn char_byte_handles_ascii_and_wide_unicode() {
        assert_eq!(char_byte("hello", 0), 0);
        assert_eq!(char_byte("hello", 3), 3);
        assert_eq!(char_byte("hello", 5), 5); // past end clamps to len
                                              // These wide chars are 3 bytes each in UTF-8; cursor index 1 -> byte 3.
        assert_eq!(char_byte("あい", 1), 3);
        assert_eq!(char_byte("あい", 2), 6);
    }

    #[test]
    fn char_byte_supports_inplace_edits() {
        // Mirrors the /ide insert path: insert a wide char mid-string by char idx.
        let mut s = String::from("ab");
        let b = char_byte(&s, 1);
        s.insert(b, 'あ');
        assert_eq!(s, "aあb");
    }

    // ---- config + skills ----

    #[test]
    fn starter_config_template_parses() {
        // First-launch generates this — it must be valid ACL with a usable model.
        let p = std::env::temp_dir().join("a3s-template-test.acl");
        std::fs::write(&p, config_template()).unwrap();
        let cfg = a3s_code_core::config::CodeConfig::from_file(&p)
            .expect("starter template must parse as valid ACL");
        let models: Vec<_> = cfg.list_models().into_iter().collect();
        assert!(!models.is_empty(), "template defines at least one model");
        let _ = std::fs::remove_file(&p);
    }

    #[test]
    fn counts_skill_dirs_and_flat_md() {
        let base = std::env::temp_dir().join("a3s-skillcount-test");
        let _ = std::fs::remove_dir_all(&base);
        std::fs::create_dir_all(base.join("myskill")).unwrap();
        std::fs::write(base.join("myskill/SKILL.md"), "# skill").unwrap();
        std::fs::write(base.join("flat.md"), "# flat skill").unwrap();
        std::fs::write(base.join("notes.txt"), "ignored").unwrap();
        assert_eq!(count_skill_files(std::slice::from_ref(&base)), 2);
        let _ = std::fs::remove_dir_all(&base);
    }
}