agent_tui/tui/

attach.rs

//! `synaps --attach [ID] [--observe|--takeover] [--keep-warm]
//! [--no-confirm-answers]` — the TUI
//! over `SocketTransport` (PLAN-phase3 A4). Client diet: no `EngineHost`,
//! no `Runtime`, no `ExtensionManager`, no MCP, no skills index — config,
//! builtin commands, keybinds, the render thread and the event stream only.
//! Plugin commands / interactive plugin commands are not available over the
//! socket yet (`Query{Commands}` is phase 4).

use std::path::PathBuf;
use std::sync::Arc;

use agent_engine::session::socket_transport::SocketTransport;
use agent_engine::session::wire::{Attach, Hello};
use agent_engine::session::{
    AttachMode, ClientKind, ClientTransport, CompactionPolicyWire, EndReason, HistoryMode,
    SessionCommand, SessionConfig, SessionId, TransportError,
};
use synaps_cli::skills::registry::CommandRegistry;
use synaps_cli::skills::BUILTIN_COMMANDS;
use synaps_cli::Result;

use agent_core::core::memstat::ladder;

use super::app::ChatMessage;
use super::run_setup::{app_from_snapshot, finish_setup, LazyHttp, TransportMode};

/// What to attach to.
pub struct AttachOpts {
    pub profile: Option<String>,
    /// Session id (prefix ok); `None` = the only live session, else create.
    pub id: Option<String>,
    /// Create by continuing a saved session (name or id).
    /// `--continue [NAME_OR_ID]`: `Some(None)` = most recent journal (bare
    /// `--continue`), `Some(Some(x))` = that one. Must stay two-level: the
    /// attach path used to flatten it, which turned a bare `--continue`
    /// into a fresh session under adopt / `--new` (soak F21).
    pub continue_session: Option<Option<String>>,
    pub system: Option<String>,
    pub prompt_manifest: Option<PathBuf>,
    pub mode: AttachMode,
    /// `--no-confirm-answers`: never answer confirm prompts (tool-call and
    /// tool-activation approvals) from this TUI, whatever keys reach it;
    /// they are only listed as waiting for another client. Secret prompts
    /// are still typed here.
    pub no_confirm_answers: bool,
    pub keep_warm: bool,
    /// `--new`/`--create`: always create a fresh session even if one is
    /// live. Rejected together with an explicit `id`.
    pub new_session: bool,
    /// `--name`: name the created session (`synaps send --session <name>`
    /// resolves it at once).
    pub name: Option<String>,
    /// `--as`: what this client is called in the session; `None` =
    /// `SYNAPS_CLIENT_NAME`, else the daemon's default (`tui`, `tui-2`, …).
    pub client_name: Option<String>,
    /// A plain `synaps` adopted a running daemon (no explicit `--attach`):
    /// after attaching, show what else lives in this daemon so parked
    /// work stays discoverable (F1).
    pub adopted: bool,
}

/// Toast id for the routine attach notes ([`attach_notices`]).
const ATTACH_TOAST_ID: &str = "attach";

/// What [`attach_notices`] needs to know about the attach that just happened.
struct AttachNoticeInputs<'a> {
    session_id: &'a SessionId,
    client_id: u64,
    mode: AttachMode,
    /// `Some(notice)` when another client owns input, so this one is read-only.
    owned_elsewhere: Option<String>,
    /// `Some(continued)` when a plain `synaps` adopted the daemon.
    adopted: Option<bool>,
    /// The daemon's other sessions ([`adopt_banner`]), adopt only.
    others_banner: Option<String>,
    config_warnings: &'a [String],
    /// `Some(notice)` when this client's binary differs from the daemon's
    /// ([`version_skew_notice`](agent_engine::session::transport::version_skew_notice)).
    version_skew: Option<String>,
}

/// Attach notes, split by whether they need the user.
#[derive(Debug, Default, PartialEq, Eq)]
struct AttachNotices {
    /// Stays in the transcript: the other-sessions list, config warnings,
    /// and the attach line when input is owned elsewhere (this client is
    /// read-only until it takes over).
    transcript: Vec<String>,
    /// Routine notes ("adopted the running daemon", "attached to … as
    /// client #N") for a short toast. Kept out of the transcript so a fresh
    /// session starts empty and shows the boot logo, like in-process.
    toast: Vec<String>,
}

fn attach_notices(i: AttachNoticeInputs<'_>) -> AttachNotices {
    let mut out = AttachNotices::default();
    if let Some(continued) = i.adopted {
        let how = if continued { "continued session" } else { "fresh session" };
        out.toast.push(format!("adopted the running daemon ({how})"));
        out.toast.push("SYNAPS_DAEMON_ADOPT=0 for in-process".to_string());
        out.transcript.extend(i.others_banner);
    }
    for w in i.config_warnings {
        out.transcript.push(format!("⚠ config: {w}"));
    }
    if let Some(skew) = i.version_skew {
        out.transcript.push(format!("⚠ {skew}"));
    }
    let attached = format!("attached to {} as client #{} ({:?})", i.session_id, i.client_id, i.mode);
    match i.owned_elsewhere {
        // Read-only until it takes over: `/takeover` does it from here
        // (never offered to an observer, whose `/takeover` is refused).
        Some(owned) if i.mode != AttachMode::Observe => {
            out.transcript.push(format!("{attached} — {owned}, or /takeover here"))
        }
        Some(owned) => out.transcript.push(format!("{attached} — {owned}")),
        None => out.toast.insert(0, attached),
    }
    out
}

/// One-line inventory of the daemon's other sessions, shown when a plain
/// `synaps` adopts the daemon (F1): the lid-close user must be able to
/// *see* their parked task, without being surprise-attached to it.
/// `None` when nothing else is there. Rows read like `/sessions` rows (same
/// label, same state clock — `state_since`, not `created_at` — and `~`
/// paths), and the line points there.
pub fn adopt_banner(
    sessions: &[agent_engine::session::SessionMeta],
    ours: &SessionId,
    now: chrono::DateTime<chrono::Utc>,
) -> Option<String> {
    let home = std::env::var_os("HOME").map(std::path::PathBuf::from);
    adopt_banner_with_home(sessions, ours, now, home.as_deref())
}

/// [`adopt_banner`] with the home directory given: `~` paths without
/// reading the environment (Windows does not set `HOME`).
fn adopt_banner_with_home(
    sessions: &[agent_engine::session::SessionMeta],
    ours: &SessionId,
    now: chrono::DateTime<chrono::Utc>,
    home: Option<&std::path::Path>,
) -> Option<String> {
    use agent_engine::session::SessionLifecycle as L;
    let mut others: Vec<&agent_engine::session::SessionMeta> =
        sessions.iter().filter(|m| &m.id != ours).collect();
    if others.is_empty() {
        return None;
    }
    others.sort_by_key(|m| std::cmp::Reverse(m.created_at));
    let n = others.len();
    let parked = others.iter().filter(|m| matches!(m.lifecycle, L::Parked)).count();
    let live = n - parked;
    let counts: Vec<String> = [(live, "live"), (parked, "parked")]
        .into_iter()
        .filter(|(k, _)| *k > 0)
        .map(|(k, what)| format!("{k} {what}"))
        .collect();
    let mut line = format!(
        "{n} other session{} in this daemon ({}) \u{2014} /sessions to switch:",
        if n == 1 { "" } else { "s" },
        counts.join(", ")
    );
    for m in others.iter().take(5) {
        let attached = if m.clients > 0 { " \u{00b7} attached" } else { "" };
        let cwd = super::sessions::short_cwd(m.cwd.as_deref(), home);
        line.push_str(&format!(
            "\n  {}  {}{attached}  {cwd}",
            super::sessions::label(m),
            super::sessions::state_text(m, now)
        ));
    }
    if n > 5 {
        line.push_str(&format!("\n  \u{2026} and {} more", n - 5));
    }
    Some(line)
}

/// The slice of `Welcome.sessions` the attach decision needs.
pub struct LiveSession {
    pub id: SessionId,
    /// `--name` / `/name`, when set: `--attach <NAME>` resolves it too.
    pub name: Option<String>,
    pub model: String,
    pub clients: usize,
}

/// `--attach <ARG>`: an exact id, then a session name (`--name`), then an id
/// prefix. Unknown values pass through as ids so the daemon can still find
/// sessions the welcome list didn't carry (and answer "unknown session").
fn resolve_attach_target(
    sessions: &[LiveSession],
    arg: &str,
) -> std::result::Result<SessionId, String> {
    if let Some(m) = sessions.iter().find(|m| m.id.as_str() == arg) {
        return Ok(m.id.clone());
    }
    let named: Vec<&LiveSession> = sessions
        .iter()
        .filter(|m| m.name.as_deref() == Some(arg))
        .collect();
    match named.as_slice() {
        [one] => return Ok(one.id.clone()),
        [] => {}
        many => {
            let mut lines = vec![format!(
                "several live sessions are named \"{arg}\"; pick one by id:"
            )];
            lines.extend(many.iter().map(|m| format!("  {}  model={}", m.id, m.model)));
            return Err(lines.join("\n"));
        }
    }
    Ok(sessions
        .iter()
        .find(|m| m.id.as_str().starts_with(arg))
        .map(|m| m.id.clone())
        .unwrap_or_else(|| SessionId::from(arg)))
}

/// What to send: `Existing` for an explicit or sole live session, `Create`
/// for `--new`, `--continue`, or no live sessions. Errors are user-facing.
/// `notice` is a one-line stderr message when a live session was picked
/// implicitly (no id given).
pub fn choose_attach(
    opts: &AttachOpts,
    sessions: &[LiveSession],
    cwd: Option<PathBuf>,
    await_extensions: bool,
) -> std::result::Result<(Attach, Option<String>), String> {
    let create = |continue_session: Option<Option<String>>| Attach::Create {
        config: SessionConfig {
            continue_session,
            system: opts.system.clone(),
            prompt_manifest: opts.prompt_manifest.clone(),
            cwd: cwd.clone(),
            env: None,
            compaction_policy: CompactionPolicyWire::LinkedSuccessor,
            await_extensions,
            keep_warm: opts.keep_warm,
            name: opts.name.clone(),
            ..Default::default()
        },
        mode: opts.mode,
        owned: None,
    };
    if opts.new_session && opts.id.is_some() {
        return Err("cannot combine --attach <ID> with --new: pick one".to_string());
    }
    if let Some(c) = &opts.continue_session {
        return Ok((create(Some(c.clone())), None));
    }
    if opts.new_session {
        return Ok((create(None), None));
    }
    if let Some(id) = &opts.id {
        let sid = resolve_attach_target(sessions, id)?;
        return Ok((
            Attach::Existing {
                session_id: sid,
                mode: opts.mode,
            },
            None,
        ));
    }
    match sessions {
        [] => Ok((create(None), None)),
        [only] => Ok((
            Attach::Existing {
                session_id: only.id.clone(),
                mode: opts.mode,
            },
            Some(format!(
                "attaching to live session {} (--new for a fresh one; `synaps daemon sessions` lists all)",
                only.id
            )),
        )),
        many => {
            let mut lines =
                vec!["several sessions; pick one with --attach <ID or NAME> (or --new for a fresh one):".to_string()];
            for m in many {
                let name = m.name.as_deref().map(|n| format!("\"{n}\"  ")).unwrap_or_default();
                lines.push(format!("  {}  {name}model={}  clients={}", m.id, m.model, m.clients));
            }
            Err(lines.join("\n"))
        }
    }
}

/// `SYNAPS_ATTACH_MODE=mirror|observe|takeover` default, overridden by flags.
pub fn attach_mode(observe: bool, takeover: bool) -> AttachMode {
    if takeover {
        return AttachMode::Takeover;
    }
    if observe {
        return AttachMode::Observe;
    }
    match std::env::var("SYNAPS_ATTACH_MODE").ok().as_deref() {
        Some("observe") => AttachMode::Observe,
        Some("takeover") => AttachMode::Takeover,
        _ => AttachMode::Mirror,
    }
}

/// The version-skew notice for this daemon, once per daemon build: a
/// reconnect to the same daemon binary (a crash restart, a `daemon reload`
/// onto the same build) does not post it again (04-tui M8).
pub(super) fn skew_notice_once(
    app: &mut super::app::App,
    daemon: agent_engine::session::transport::BinaryId,
    session: &str,
) -> Option<String> {
    use agent_engine::session::transport::{version_skew_notice, BinaryId};
    if app.skew_noticed.as_ref() == Some(&daemon) {
        return None;
    }
    let notice = version_skew_notice(&BinaryId::this(), &daemon, session)?;
    app.skew_noticed = Some(daemon);
    Some(notice)
}

/// What a daemon-session TUI prints on stderr after it exits because the
/// session ended under it (`Ended`): `/close` here or on another client,
/// `daemon stop`, an eviction. The alternate screen is gone by then, so this
/// is the only place the user can still read which session it was and how
/// to bring it back. A session with no history (`has_history` false) has
/// no journal, so there is nothing to continue; `None` for one the daemon
/// ended for exactly that reason (`Idle`).
pub(super) fn session_ended_line(reason: EndReason, session: &str, has_history: bool) -> Option<String> {
    let what = match reason {
        EndReason::ClientQuit => "was closed",
        EndReason::OwnerGone => "ended: the client that owned it disconnected",
        EndReason::HostShutdown => "ended: the daemon shut down",
        EndReason::Evicted => "was evicted from the daemon",
        EndReason::Error => "ended after an error",
        EndReason::Idle => return None,
    };
    Some(if has_history {
        format!("synaps: session {session} {what}; resume it with: synaps --attach --continue {session}")
    } else {
        format!("synaps: session {session} {what} (it never ran a turn, so there is nothing to resume)")
    })
}

fn cfg_err(e: impl std::fmt::Display) -> synaps_cli::RuntimeError {
    synaps_cli::RuntimeError::Config(e.to_string())
}

/// What `--attach` prints when there is no daemon to attach to: says so,
/// and how to start one (profile-aware). The `SYNAPS_DAEMON_AUTOSPAWN` hint
/// only appears when autospawn really is off; otherwise the daemon was there
/// a moment ago (idle shutdown, crash) and re-running starts a new one.
pub fn daemon_not_running_message(profile: Option<&str>, detail: Option<&str>) -> String {
    not_running_message(profile, detail, agent_engine::daemon::autospawn_enabled())
}

fn not_running_message(profile: Option<&str>, detail: Option<&str>, autospawn: bool) -> String {
    let start = match profile {
        Some(p) => format!("synaps --profile {p} daemon --detach"),
        None => "synaps daemon --detach".to_string(),
    };
    let why = detail.map(|d| format!(" ({d})")).unwrap_or_default();
    if autospawn {
        return format!(
            "no daemon is running{why}; it may have just stopped.\n\
             re-run `synaps --attach` to start a new one, or start it yourself with:  {start}"
        );
    }
    format!(
        "no daemon is running{why} — nothing to attach to.\n\
         start one with:  {start}\n\
         or run in the foreground:  {}\n\
         then re-run `synaps --attach` (or unset SYNAPS_DAEMON_AUTOSPAWN=0 to auto-start).",
        start.replace("--detach", "--foreground")
    )
}

pub async fn run_attached(mut opts: AttachOpts) -> Result<()> {
    ladder("attach:enter", &"");
    let paths = agent_engine::daemon::registry::daemon_paths(opts.profile.as_deref());
    if !agent_engine::daemon::registry::is_alive(&paths) {
        return Err(cfg_err(daemon_not_running_message(
            opts.profile.as_deref(),
            None,
        )));
    }
    let client_name = opts.client_name.clone().or_else(agent_engine::session::client_name_from_env);
    if let Some(name) = client_name.as_deref() {
        agent_engine::session::validate_client_name(name).map_err(cfg_err)?;
    }
    let hello = Hello::new(ClientKind::Tui)
        .with_name(client_name)
        .with_history(HistoryMode::from_env_or(HistoryMode::attach_client_default()));
    let conn = match SocketTransport::connect(&paths.sock, hello).await {
        Ok(c) => c,
        Err(TransportError::Version { client, daemon }) => {
            return Err(cfg_err(format!(
                "protocol version mismatch (client {client}, daemon {daemon}); restart or reload the daemon with this binary"
            )))
        }
        Err(TransportError::Io(e)) => {
            // Lock held but the socket is gone/refusing: the daemon is dead
            // or still booting — same advice, with the cause.
            return Err(cfg_err(daemon_not_running_message(
                opts.profile.as_deref(),
                Some(&format!("{}: {e}", paths.sock.display())),
            )));
        }
        Err(e) => return Err(cfg_err(format!("connect: {e}"))),
    };
    if let Some(msg) =
        agent_engine::daemon::profile_mismatch(conn.welcome.profile.as_deref(), opts.profile.as_deref())
    {
        return Err(cfg_err(msg));
    }
    ladder(
        "connect",
        &format_args!("sessions={}", conn.welcome.sessions.len()),
    );

    let cwd = std::env::current_dir().ok();

    // T4: resolve path-like args (--system, --prompt-manifest) against the
    // client's cwd before shipping them to the daemon.
    if let Some(ref cwd_path) = cwd {
        let mut probe_cfg = SessionConfig {
            system: opts.system.clone(),
            prompt_manifest: opts.prompt_manifest.clone(),
            ..Default::default()
        };
        if let Err(e) = agent_engine::session::client_args::resolve_client_session_args(
            &mut probe_cfg,
            cwd_path,
        ) {
            // Print to stderr before entering raw mode so it survives.
            eprintln!("synaps: {e}");
            return Err(cfg_err(e));
        }
        opts.system = probe_cfg.system;
        opts.prompt_manifest = probe_cfg.prompt_manifest;
    }

    let live: Vec<LiveSession> = conn
        .welcome
        .sessions
        .iter()
        .map(|m| LiveSession {
            id: m.id.clone(),
            name: m.name.clone(),
            model: m.model.clone(),
            clients: m.clients,
        })
        .collect();
    let welcome_sessions = conn.welcome.sessions.clone();
    // Quick Start (default on) => await_extensions=false: the daemon TUI
    // stops blocking on extension discovery before turn 1 (fast cold start),
    // matching the in-process TUI. Off => block like the historic daemon path.
    let await_extensions = !synaps_cli::load_config().startup.quick_start;
    let (attach, notice) =
        choose_attach(&opts, &live, cwd, await_extensions).map_err(cfg_err)?;
    if let Some(n) = notice {
        // Before the TUI takes the terminal, so it survives on the scrollback.
        eprintln!("{n}");
    }

    let (transport, snapshot) = SocketTransport::attach(conn, attach)
        .await
        .map_err(|e| cfg_err(format!("attach: {e}")))?;
    // `frame_bytes` is filled once the transport records its last frame
    // length (B4 `last_frame_bytes()`); until then the wire size is not known here.
    ladder(
        "attached",
        &format_args!(
            "frame_bytes=n/a messages_len={} api_messages={} replay={} tail_items={}",
            snapshot.conversation.messages_len,
            snapshot.conversation.api_messages.len(),
            snapshot.replay.len(),
            agent_engine::session::DEFAULT_TAIL_ITEMS
        ),
    );
    // The decode transient of `Attached` is garbage now — give it back (§4.4).
    super::client_diet::purge_arenas("purge:attached");

    // ── Client diet: config + builtin commands + keybinds, nothing else ──
    let config = synaps_cli::load_config();
    let registry = Arc::new(CommandRegistry::new(BUILTIN_COMMANDS, Vec::new()));
    let mut keybinds = synaps_cli::skills::keybinds::KeybindRegistry::new();
    if !config.keybinds.is_empty() {
        keybinds.register_user(&config.keybinds);
    }
    let keybind_registry = Arc::new(std::sync::RwLock::new(keybinds));
    let system_prompt_path = synaps_cli::config::resolve_read_path("system.md");
    ladder("config", &"");
    let http = LazyHttp::new();
    if std::env::var("SYNAPS_CLIENT_HTTP").is_ok_and(|v| v == "eager") {
        http.get()?;
    }

    let mut app = app_from_snapshot(&snapshot);
    app.observing = transport.mode() == AttachMode::Observe;
    app.attached_clients = transport.roster().clients().len();
    let (msgs, bytes) = super::app::scrollback_from_env(&TransportMode::Socket);
    app.transcript.set_scrollback(msgs, bytes);
    ladder("app", &"");
    // Notices queued before boot go first.
    for n in super::run_setup::take_boot_notices() {
        app.push_msg(ChatMessage::System(n));
    }
    let notices = attach_notices(AttachNoticeInputs {
        session_id: &snapshot.meta.id,
        client_id: transport.client_id().0,
        mode: transport.mode(),
        owned_elsewhere: snapshot.input_owned_elsewhere(transport.client_id()),
        adopted: opts.adopted.then_some(opts.continue_session.is_some()),
        others_banner: if opts.adopted {
            adopt_banner(&welcome_sessions, &snapshot.meta.id, chrono::Utc::now())
        } else {
            None
        },
        config_warnings: &config.warnings,
        version_skew: skew_notice_once(
            &mut app,
            agent_engine::session::transport::BinaryId::of(&transport.welcome),
            snapshot.meta.id.as_str(),
        ),
    });
    for n in notices.transcript {
        app.push_msg(ChatMessage::System(n));
    }
    // Same first-run guidance as the in-process boot: a new user's first
    // `synaps` lands here (daemon mode is the default), and without it the
    // first message fails with a token-refresh error.
    if let Some(n) = super::run_setup::no_credentials_notice() {
        app.push_msg(ChatMessage::System(n));
    }
    if !notices.toast.is_empty() {
        app.toasts.upsert(
            super::toast::Toast::new(ATTACH_TOAST_ID, String::new())
                .titled("daemon")
                .lines(notices.toast),
        );
    }
    // Mid-turn attach: rebuild the partial turn from the replay ring, then
    // the actor's pending prompts.
    let replay = snapshot.replay.clone();
    let pending = snapshot.pending_prompts.clone();
    let owns_input = super::session_link::may_drive(&transport);
    app.streaming = snapshot.streaming;

    let mut ctx = finish_setup(
        app,
        Box::new(transport),
        http,
        TransportMode::Socket,
        config,
        registry,
        keybind_registry,
        system_prompt_path,
        None,
    )
    .await?;
    // No extension host in this process: the loader arm never runs.
    ctx.app.extension_loader_running = false;
    // Before any prompt is fed: the replay and the pending prompts below.
    // An observer's confirm answers are refused by the session (#148 C2),
    // so it never opens the approval pane either.
    ctx.prompt_bridge.set_owns_input(owns_input);
    if opts.no_confirm_answers || opts.mode == AttachMode::Observe {
        ctx.prompt_bridge
            .set_confirm_policy(super::session_link::ConfirmPolicy::ViewOnly);
    }
    for env in replay {
        // Presentation only; a render handle is not needed for correctness.
        let _ = super::stream_handler::handle_session_event_arm(
            env,
            &mut ctx.app,
            &mut ctx.link,
            &ctx.registry,
            &ctx.render_handle,
            &mut ctx.prompt_bridge,
            None,
        )
        .await;
    }
    // The replayed partial turn is history: shown whole, not paced in.
    ctx.app.flush_reveal();
    for pr in pending {
        ctx.prompt_bridge.on_prompt(pr);
    }
    super::stream_handler::sync_waiting_confirms(&mut ctx.app, &ctx.prompt_bridge);
    ladder("replay", &"");
    if opts.keep_warm {
        let _ = ctx.link.send(SessionCommand::KeepWarm { on: true }).await;
    }
    super::run_loop(ctx).await
}

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

    /// The line a TUI leaves on stderr when its daemon session ended under
    /// it names the session and how to continue it; a session that never
    /// ran a turn has nothing to continue.
    #[test]
    fn an_ended_session_says_how_to_continue_it() {
        let line = session_ended_line(EndReason::ClientQuit, "20261014-183459-3f61", true).unwrap();
        assert_eq!(
            line,
            "synaps: session 20261014-183459-3f61 was closed; resume it with: \
             synaps --attach --continue 20261014-183459-3f61"
        );
        let stop = session_ended_line(EndReason::HostShutdown, "s1", true).unwrap();
        assert!(stop.contains("the daemon shut down") && stop.ends_with("--continue s1"), "{stop}");
        assert!(session_ended_line(EndReason::Evicted, "s1", true).unwrap().contains("evicted"));
        assert!(session_ended_line(EndReason::Error, "s1", true).unwrap().contains("error"));
        let empty = session_ended_line(EndReason::ClientQuit, "s1", false).unwrap();
        assert_eq!(empty, "synaps: session s1 was closed (it never ran a turn, so there is nothing to resume)");
        assert_eq!(session_ended_line(EndReason::Idle, "s1", true), None);
    }

    fn notice_inputs<'a>(id: &'a SessionId, warnings: &'a [String]) -> AttachNoticeInputs<'a> {
        AttachNoticeInputs {
            session_id: id,
            client_id: 1,
            mode: AttachMode::Mirror,
            owned_elsewhere: None,
            adopted: None,
            others_banner: None,
            config_warnings: warnings,
            version_skew: None,
        }
    }

    #[test]
    fn routine_attach_notes_go_to_the_toast_so_the_logo_shows() {
        let id = SessionId::from("20261001-000000-ours".to_string());
        // plain `synaps` adopting the daemon, nothing else going on
        let n = attach_notices(AttachNoticeInputs { adopted: Some(false), ..notice_inputs(&id, &[]) });
        assert!(n.transcript.is_empty(), "a fresh session's transcript stays empty: {n:?}");
        assert_eq!(n.toast[0], "attached to 20261001-000000-ours as client #1 (Mirror)");
        assert_eq!(n.toast[1], "adopted the running daemon (fresh session)");
        assert!(n.toast[2].contains("SYNAPS_DAEMON_ADOPT=0"), "{n:?}");
        // `--continue` says so
        let n = attach_notices(AttachNoticeInputs { adopted: Some(true), ..notice_inputs(&id, &[]) });
        assert_eq!(n.toast[1], "adopted the running daemon (continued session)");
        // explicit `--attach`: only the attach line
        let n = attach_notices(notice_inputs(&id, &[]));
        assert_eq!(n, AttachNotices { transcript: vec![], toast: vec![
            "attached to 20261001-000000-ours as client #1 (Mirror)".to_string(),
        ] });
    }

    #[test]
    fn notes_that_need_the_user_stay_in_the_transcript() {
        let id = SessionId::from("20261001-000000-ours".to_string());
        let warnings = vec!["unknown key `fooo`".to_string()];
        let n = attach_notices(AttachNoticeInputs {
            adopted: Some(false),
            others_banner: Some("2 other sessions in this daemon".to_string()),
            owned_elsewhere: Some("input is owned by client #3 (tui)".to_string()),
            ..notice_inputs(&id, &warnings)
        });
        assert_eq!(n.transcript, vec![
            "2 other sessions in this daemon".to_string(),
            "⚠ config: unknown key `fooo`".to_string(),
            "attached to 20261001-000000-ours as client #1 (Mirror) — input is owned by client #3 (tui), or /takeover here"
                .to_string(),
        ]);
        // read-only attach: the attach line is in the transcript, not the toast
        assert!(n.toast.iter().all(|l| !l.starts_with("attached to")), "{n:?}");
        assert_eq!(n.toast[0], "adopted the running daemon (fresh session)");
    }

    /// An observer is read-only on purpose: its attach line never offers
    /// `/takeover` (the session refuses it from an observer).
    #[test]
    fn an_observer_is_not_offered_takeover() {
        let id = SessionId::from("20261001-000000-ours".to_string());
        let n = attach_notices(AttachNoticeInputs {
            mode: AttachMode::Observe,
            owned_elsewhere: Some("input is owned by client #3 (tui)".to_string()),
            ..notice_inputs(&id, &[])
        });
        assert_eq!(n.transcript, vec![
            "attached to 20261001-000000-ours as client #1 (Observe) — input is owned by client #3 (tui)"
                .to_string(),
        ]);
    }

    #[test]
    fn a_client_older_than_the_daemon_says_so_in_the_transcript() {
        let id = SessionId::from("20261001-000000-ours".to_string());
        use agent_engine::session::transport::{version_skew_notice, BinaryId};
        let bin = |version: &str| BinaryId { version: version.into(), build: String::new() };
        let skew = version_skew_notice(&bin("0.10.1"), &bin("0.10.2"), id.as_str());
        let n = attach_notices(AttachNoticeInputs { version_skew: skew, ..notice_inputs(&id, &[]) });
        assert_eq!(n.transcript.len(), 1, "{n:?}");
        assert!(n.transcript[0].starts_with("⚠ this client is synaps 0.10.1 but the daemon is 0.10.2"), "{n:?}");
        assert!(n.transcript[0].contains("synaps --attach 20261001-000000-ours"), "{n:?}");
        // same binary: nothing extra
        let same = version_skew_notice(&bin("0.10.2"), &bin("0.10.2"), id.as_str());
        let n = attach_notices(AttachNoticeInputs { version_skew: same, ..notice_inputs(&id, &[]) });
        assert!(n.transcript.is_empty(), "{n:?}");
    }

    /// 04-tui M8: the skew line was posted again on every reconnect, crash
    /// reconnects included. It shows once per daemon build.
    #[test]
    fn the_skew_notice_shows_once_per_daemon_build() {
        use agent_engine::session::transport::BinaryId;
        let mut app = crate::tui::app::App::new(synaps_cli::Session::new("test-model", "low", None));
        let daemon = |build: &str| BinaryId { version: "0.0.1".into(), build: build.into() };
        assert!(skew_notice_once(&mut app, daemon("aaaa1111"), "s").is_some());
        assert!(
            skew_notice_once(&mut app, daemon("aaaa1111"), "s").is_none(),
            "a reconnect to the same daemon build says nothing again"
        );
        assert!(
            skew_notice_once(&mut app, daemon("bbbb2222"), "s").is_some(),
            "a reload onto another daemon build warns again"
        );
    }

    #[test]
    fn not_running_message_says_so_and_how_to_start() {
        let m = not_running_message(None, None, false);
        assert!(m.starts_with("no daemon is running"), "{m}");
        assert!(m.contains("synaps daemon --detach"), "{m}");
        assert!(m.contains("synaps daemon --foreground"), "{m}");
        assert!(m.contains("SYNAPS_DAEMON_AUTOSPAWN=0"), "{m}");
        let m = not_running_message(Some("work"), Some("connection refused"), false);
        assert!(m.contains("(connection refused)"), "{m}");
        assert!(m.contains("synaps --profile work daemon --detach"), "{m}");
    }

    #[test]
    fn not_running_message_skips_the_autospawn_hint_when_autospawn_is_on() {
        let m = not_running_message(Some("demo"), Some("connection refused"), true);
        assert!(m.starts_with("no daemon is running (connection refused)"), "{m}");
        assert!(m.contains("re-run `synaps --attach`"), "{m}");
        assert!(m.contains("synaps --profile demo daemon --detach"), "{m}");
        assert!(!m.contains("SYNAPS_DAEMON_AUTOSPAWN"), "{m}");
    }

    fn opts(id: Option<&str>, new_session: bool) -> AttachOpts {
        AttachOpts {
            profile: None,
            id: id.map(str::to_string),
            continue_session: None,
            system: None,
            prompt_manifest: None,
            mode: AttachMode::Mirror,
            no_confirm_answers: false,
            keep_warm: false,
            new_session,
            name: None,
            client_name: None,
            adopted: false,
        }
    }

    fn meta(id: &str, lifecycle: agent_engine::session::SessionLifecycle, clients: usize, mins_ago: i64) -> agent_engine::session::SessionMeta {
        agent_engine::session::SessionMeta {
            id: SessionId::from(id.to_string()),
            name: None,
            model: "m".into(),
            cwd: Some(std::path::PathBuf::from("/w")),
            created_at: chrono::Utc::now() - chrono::Duration::minutes(mins_ago),
            continued: false,
            continue_info: None,
            host_pid: 1,
            lifecycle,
            clients,
            input_owner: None,
            awaiting_input: 0,
            roster: Vec::new(),
            client_input: None,
            journal_id: String::new(),
            locked_by: None,
            pinned: false,
            busy: false,
            state_since: None,
            park_due: None,
            evict_due: None,
            title: None,
            cost_usd: 0.0,
            messages: 0,
        }
    }

    #[test]
    fn await_extensions_flows_from_quick_start() {
        // quick_start=false => caller passes await_extensions=true => the
        // created SessionConfig blocks on extensions (historic daemon path).
        let (a, _) = choose_attach(&opts(None, true), &[], None, true).unwrap();
        match a {
            Attach::Create { config, .. } => assert!(config.await_extensions),
            other => panic!("expected Create, got {other:?}"),
        }
        // quick_start=true (default) => await_extensions=false => fast start.
        let (a, _) = choose_attach(&opts(None, true), &[], None, false).unwrap();
        match a {
            Attach::Create { config, .. } => assert!(!config.await_extensions),
            other => panic!("expected Create, got {other:?}"),
        }
    }

    #[test]
    fn bare_continue_means_most_recent_not_fresh() {
        // F21: `synaps --continue` (no id) over the attach path must reach the
        // daemon as `continue_session: Some(None)` (= most recent journal),
        // even when --new is also set (adopt sets it).
        let mut o = opts(None, true);
        o.continue_session = Some(None);
        let (a, _) = choose_attach(&o, &[live("abc")], None, true).unwrap();
        match a {
            Attach::Create { config, .. } => assert_eq!(config.continue_session, Some(None)),
            other => panic!("expected Create, got {other:?}"),
        }
        let mut o = opts(None, false);
        o.continue_session = Some(Some("xyz".into()));
        let (a, _) = choose_attach(&o, &[], None, true).unwrap();
        match a {
            Attach::Create { config, .. } => assert_eq!(config.continue_session, Some(Some("xyz".into()))),
            other => panic!("expected Create, got {other:?}"),
        }
    }

    #[test]
    fn adopt_banner_lists_other_sessions_only() {
        use agent_engine::session::SessionLifecycle as L;
        let ours = SessionId::from("20260919-000000-ours".to_string());
        let now = chrono::Utc::now();
        // alone in the daemon → nothing to say
        assert!(adopt_banner(&[meta("20260919-000000-ours", L::Live, 1, 0)], &ours, now).is_none());
        let sessions = vec![
            meta("20260919-000000-ours", L::Live, 1, 0),
            meta("20260919-010000-aaaa", L::Parked, 0, 125),
            meta("20260919-020000-bbbb", L::Live, 1, 3),
        ];
        let b = adopt_banner(&sessions, &ours, now).unwrap();
        assert!(b.starts_with("2 other sessions in this daemon (1 live, 1 parked)"), "{b}");
        assert!(!b.contains("ours"), "{b}");
        // newest first, label + state + cwd per row
        let rows: Vec<&str> = b.lines().skip(1).collect();
        assert!(rows[0].contains("\u{2026}bbbb") && rows[0].contains("attached") && rows[0].contains("/w"), "{b}");
        assert!(rows[1].contains("\u{2026}aaaa") && rows[1].contains("parked"), "{b}");
        // capped at 5 rows + overflow line
        let many: Vec<_> = (0..8).map(|i| meta(&format!("20260919-00000{i}-xxxx"), L::Parked, 0, i)).collect();
        let b = adopt_banner(&many, &ours, now).unwrap();
        assert_eq!(b.lines().count(), 1 + 5 + 1, "{b}");
        assert!(b.contains("and 3 more"), "{b}");
    }

    /// C5: the banner dated rows by `created_at` ("parked 4m ago") while
    /// /sessions dates them by `state_since` ("parked 2m"); it also carried
    /// backticked CLI how-tos and absolute paths.
    #[test]
    fn adopt_banner_matches_the_sessions_modal() {
        use agent_engine::session::SessionLifecycle as L;
        let ours = SessionId::from("20260919-000000-ours".to_string());
        let now = chrono::Utc::now();
        // A fixed home, not `HOME`: Windows does not set it.
        let home = std::env::temp_dir();
        let mut m = meta("20260919-010000-793d", L::Parked, 0, 4);
        m.name = Some("gallery2".into());
        m.state_since = Some(now - chrono::Duration::minutes(2));
        m.evict_due = Some(now + chrono::Duration::minutes(57) + chrono::Duration::seconds(30));
        m.cwd = Some(home.join("Projects/synaps"));
        let b = adopt_banner_with_home(
            &[meta("20260919-000000-ours", L::Live, 1, 0), m.clone()],
            &ours,
            now,
            Some(&home),
        )
        .unwrap();
        assert_eq!(
            b,
            format!(
                "1 other session in this daemon (1 parked) \u{2014} /sessions to switch:\n  gallery2  {}  ~/Projects/synaps",
                crate::tui::sessions::state_text(&m, now)
            )
        );
        assert!(b.contains("parked 2m"), "{b}");
        assert!(!b.contains('`') && !b.contains("ago"), "{b}");
    }

    fn live(id: &str) -> LiveSession {
        LiveSession {
            id: SessionId::from(id),
            name: None,
            model: "m".into(),
            clients: 1,
        }
    }

    #[test]
    fn new_creates_even_with_live_sessions() {
        let (a, notice) = choose_attach(&opts(None, true), &[live("abc")], None, true).unwrap();
        assert!(matches!(a, Attach::Create { .. }), "{a:?}");
        assert!(notice.is_none());
        let (a, _) = choose_attach(&opts(None, true), &[live("a"), live("b")], None, true).unwrap();
        assert!(matches!(a, Attach::Create { .. }), "{a:?}");
    }

    fn named(id: &str, name: &str) -> LiveSession {
        LiveSession { name: Some(name.into()), ..live(id) }
    }

    #[test]
    fn attach_resolves_a_session_name() {
        let sessions = [live("20261026-081319-a97a"), named("20261026-081500-793d", "pair")];
        let (a, _) = choose_attach(&opts(Some("pair"), false), &sessions, None, true).unwrap();
        assert!(
            matches!(&a, Attach::Existing { session_id, .. } if session_id.as_str() == "20261026-081500-793d"),
            "{a:?}"
        );
        // An exact id still wins over a name, and id prefixes still work.
        let sessions = [named("abc", "x"), named("def", "abc")];
        let (a, _) = choose_attach(&opts(Some("abc"), false), &sessions, None, true).unwrap();
        assert!(matches!(&a, Attach::Existing { session_id, .. } if session_id.as_str() == "abc"), "{a:?}");
        let (a, _) = choose_attach(&opts(Some("de"), false), &sessions, None, true).unwrap();
        assert!(matches!(&a, Attach::Existing { session_id, .. } if session_id.as_str() == "def"), "{a:?}");
    }

    #[test]
    fn attach_by_ambiguous_name_lists_the_ids() {
        let sessions = [named("aaa", "pair"), named("bbb", "pair")];
        let e = choose_attach(&opts(Some("pair"), false), &sessions, None, true).unwrap_err();
        assert!(e.contains("aaa") && e.contains("bbb") && e.contains("by id"), "{e}");
    }

    #[test]
    fn new_with_explicit_id_is_rejected() {
        let e = choose_attach(&opts(Some("abc"), true), &[live("abc")], None, true).unwrap_err();
        assert!(e.contains("cannot combine"), "{e}");
    }

    #[test]
    fn sole_live_session_is_picked_with_notice() {
        let (a, notice) = choose_attach(&opts(None, false), &[live("abc")], None, true).unwrap();
        assert!(
            matches!(&a, Attach::Existing { session_id, .. } if session_id.as_str() == "abc"),
            "{a:?}"
        );
        let n = notice.unwrap();
        assert!(n.contains("abc") && n.contains("--new") && n.contains("daemon sessions"), "{n}");
    }

    #[test]
    fn no_live_sessions_creates_and_many_errors_with_hint() {
        let (a, _) = choose_attach(&opts(None, false), &[], None, true).unwrap();
        assert!(matches!(a, Attach::Create { .. }), "{a:?}");
        let e = choose_attach(&opts(None, false), &[live("a"), live("b")], None, true).unwrap_err();
        assert!(e.contains("--new") && e.contains("  a  ") && e.contains("  b  "), "{e}");
    }

    #[test]
    fn attach_mode_flags_override_env() {
        assert_eq!(attach_mode(false, true), AttachMode::Takeover);
        assert_eq!(attach_mode(true, false), AttachMode::Observe);
    }
}