agent_session/

lib.rs

mod activity;
mod cli;
pub mod completion;
mod provider_prompt;
mod serve;

use std::collections::{BTreeMap, BTreeSet, VecDeque};
use std::env;
use std::ffi::OsString;
use std::fs::{self, OpenOptions};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::process::Command as ProcessCommand;
use std::thread;
use std::time::{Duration, Instant, SystemTime};

use clap::Parser;
use clap::error::ErrorKind;
use jiff::{Timestamp, Zoned};
use nils_common::cli_contract::{
    Envelope, EnvelopeError, OutputFormat, emit_parse_error, exit, schema_version_for,
};
use nils_common::fs::{
    SECRET_FILE_MODE, display_path, expand_home, home_dir, normalize_path, write_atomic,
};
use nils_common::git::parse_git_remote_url;
// The provider session-resume resolver, session-history scanning primitives, and
// bounded-scan budgets live in `nils-provider-resume` so `codex-cli`,
// `claude-cli`, and this crate share one implementation. Items reused by the
// `provider_prompt` module via `crate::` are re-exported at crate scope.
use nils_provider_resume::{
    CODEX_RESUME_SCAN_MAX_DEPTH, ClaudeResumeScanBudget, CodexResumeScanBudget, ResumeIdError,
    ResumeProvider, ResumeResolveError, collect_claude_provider_resume_matches,
    collect_codex_provider_resume_matches, normalize_resume_id, resolve_resume_source,
};
pub(crate) use nils_provider_resume::{
    claude_projects_root, codex_sessions_root, read_claude_session_cwd, read_codex_session_meta,
};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

use cli::{AgentKind, Cli, Command, SpecialKey};

const SESSION_DOCUMENT_VERSION: &str = "agent-session.session.v1";
const SESSION_RESUME_DOCUMENT_VERSION: &str = "agent-session.resume.v1";
const SESSION_RESUME_FILE: &str = "resume.json";
const BINARY: &str = "agent-session";
const START_COMMAND: &str = "start";
const RUN_COMMAND: &str = "run";
const LIST_COMMAND: &str = "list";
const COMMAND_COMMAND: &str = "command";
const LOGS_COMMAND: &str = "logs";
const SEND_COMMAND: &str = "send";
const GLANCE_COMMAND: &str = "glance";
const RESUME_COMMAND: &str = "resume";
const ACTIVITY_EVENT_COMMAND: &str = "activity-event";
const ACTIVITY_STATUS_COMMAND: &str = "activity-status";
const ACTIVITY_DOCTOR_COMMAND: &str = "activity-doctor";
const ACTIVITY_SETUP_COMMAND: &str = "activity-setup";
const DELETE_COMMAND: &str = "delete";
const WORKDIR_USAGE_FILE: &str = "workdir-usage.json";
const CODEX_RESUME_CAPTURE_TIMEOUT_MS: u64 = 1500;
const CODEX_RESUME_CAPTURE_POLL_MS: u64 = 100;
const CODEX_RESUME_AMBIGUITY_WINDOW_MS: u64 = 500;
const CODEX_RESUME_BACKFILL_MAX_AGE_SECS: u64 = 10 * 60;

pub fn run() -> i32 {
    run_with_args(env::args_os())
}

pub fn run_with_args<I, T>(args: I) -> i32
where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,
{
    let raw_args: Vec<OsString> = args.into_iter().map(Into::into).collect();
    let cli = match Cli::try_parse_from(raw_args.clone()) {
        Ok(cli) => cli,
        Err(err) => {
            let kind = err.kind();
            if matches!(
                kind,
                ErrorKind::DisplayHelp
                    | ErrorKind::DisplayVersion
                    | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
            ) {
                let _ = err.print();
                return err.exit_code();
            }

            let format = detect_format_from_args(&raw_args);
            let code = match kind {
                ErrorKind::InvalidSubcommand => "unknown-subcommand",
                _ => "parse-error",
            };
            let message = render_clap_message(&err);
            return emit_parse_error(BINARY, format, code, &message);
        }
    };

    dispatch(cli)
}

fn dispatch(cli: Cli) -> i32 {
    if let Command::Completion(args) = cli.command {
        return completion::run(args.shell);
    }

    let format = command_format(&cli.command);
    let context = match CliContext::resolve(cli.state_dir, cli.host) {
        Ok(context) => context,
        Err(err) => {
            return render_error("error", format, err);
        }
    };

    match cli.command {
        Command::Start(args) => run_start(&context, args),
        Command::Run(args) => run_one_shot(&context, args),
        Command::List(args) => run_list(&context, args),
        Command::Show(args) => run_command(&context, args),
        Command::Attach(args) => run_attach(&context, args),
        Command::Logs(args) => run_logs(&context, args),
        Command::Send(args) => run_send(&context, args),
        Command::Glance(args) => run_glance(&context, args),
        Command::Resume(args) => run_resume(&context, args),
        Command::Activity(args) => run_activity(&context, args),
        Command::Serve(args) => serve::run_serve(&context, args),
        Command::Delete(args) => run_delete(&context, args),
        Command::Completion(_) => unreachable!("completion is handled before context resolution"),
    }
}

fn command_format(command: &Command) -> OutputFormat {
    match command {
        Command::Start(args) => args.format,
        Command::Run(args) => args.format,
        Command::List(args) => args.format,
        Command::Show(args) => args.format,
        Command::Logs(args) => args.format,
        Command::Send(args) => args.format,
        Command::Glance(args) => args.format,
        Command::Resume(args) => args.format,
        Command::Activity(args) => match &args.command {
            cli::ActivityCommand::Event(args) => args.format,
            cli::ActivityCommand::Status(args) => args.format,
            cli::ActivityCommand::Hook(_) => OutputFormat::Text,
            cli::ActivityCommand::Doctor(args) => args.format,
            cli::ActivityCommand::Setup(args) => args.format,
        },
        Command::Delete(args) => args.format,
        Command::Attach(_) | Command::Serve(_) | Command::Completion(_) => OutputFormat::Text,
    }
}

fn detect_format_from_args(args: &[OsString]) -> OutputFormat {
    let mut index = 1;
    while index < args.len() {
        let Some(arg) = args[index].to_str() else {
            index += 1;
            continue;
        };
        if arg == "--format" {
            if args
                .get(index + 1)
                .and_then(|value| value.to_str())
                .is_some_and(|value| value.eq_ignore_ascii_case("json"))
            {
                return OutputFormat::Json;
            }
            index += 2;
            continue;
        }
        if let Some(value) = arg.strip_prefix("--format=")
            && value.eq_ignore_ascii_case("json")
        {
            return OutputFormat::Json;
        }
        index += 1;
    }
    OutputFormat::Text
}

fn render_clap_message(err: &clap::Error) -> String {
    let rendered = err.to_string();
    rendered
        .lines()
        .find(|line| !line.trim().is_empty())
        .map(|line| {
            let line = line.trim();
            line.strip_prefix("error:")
                .map(str::trim)
                .unwrap_or(line)
                .to_string()
        })
        .unwrap_or_else(|| "command-line parse failed".to_string())
}

fn run_start(context: &CliContext, args: cli::StartArgs) -> i32 {
    let format = args.format;
    match start_session(context, args) {
        Ok(view) => render_single_success(
            START_COMMAND,
            view.format,
            &view.result,
            render_started_text,
        ),
        Err(err) => render_error(START_COMMAND, format, err),
    }
}

fn run_one_shot(context: &CliContext, args: cli::RunArgs) -> i32 {
    let format = args.format;
    match start_run_session(context, args) {
        Ok(view) => {
            render_single_success(RUN_COMMAND, view.format, &view.result, render_started_text)
        }
        Err(err) => render_error(RUN_COMMAND, format, err),
    }
}

fn run_list(context: &CliContext, args: cli::ListArgs) -> i32 {
    match list_sessions(context, None) {
        Ok(results) => render_list_success(args.format, &results),
        Err(err) => render_error(LIST_COMMAND, args.format, err),
    }
}

fn run_command(context: &CliContext, args: cli::SessionRefArgs) -> i32 {
    match load_session_view(context, &args.id, None) {
        Ok(view) => render_single_success(COMMAND_COMMAND, args.format, &view, render_command_text),
        Err(err) => render_error(COMMAND_COMMAND, args.format, err),
    }
}

fn run_attach(context: &CliContext, args: cli::AttachArgs) -> i32 {
    match load_session_record(context, &args.id) {
        Ok(record) => {
            let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
            let status = ProcessCommand::new(&tmux_bin)
                .arg("attach-session")
                .arg("-t")
                .arg(&record.tmux_session)
                .status();
            match status {
                Ok(status) if status.success() => exit::SUCCESS,
                Ok(status) => {
                    eprintln!("error: tmux attach failed with status {status}");
                    exit::RUNTIME
                }
                Err(err) => {
                    eprintln!("error: failed to run {}: {err}", tmux_bin.display());
                    exit::RUNTIME
                }
            }
        }
        Err(err) => render_error("attach", OutputFormat::Text, err),
    }
}

fn run_logs(context: &CliContext, args: cli::LogsArgs) -> i32 {
    match load_session_record(context, &args.id).and_then(|record| {
        session_logs(
            &record,
            args.tail,
            &resolve_tmux_bin(args.tmux_bin.as_deref()),
        )
    }) {
        Ok(result) => render_single_success(LOGS_COMMAND, args.format, &result, render_logs_text),
        Err(err) => render_error(LOGS_COMMAND, args.format, err),
    }
}

fn run_send(context: &CliContext, args: cli::SendArgs) -> i32 {
    let format = args.format;
    match send_to_session(context, args) {
        Ok(result) => render_single_success(SEND_COMMAND, format, &result, render_send_text),
        Err(err) => render_error(SEND_COMMAND, format, err),
    }
}

fn run_glance(context: &CliContext, args: cli::GlanceArgs) -> i32 {
    let format = args.format;
    match glance_session(context, args) {
        Ok(result) => render_single_success(GLANCE_COMMAND, format, &result, render_glance_text),
        Err(err) => render_error(GLANCE_COMMAND, format, err),
    }
}

fn run_resume(context: &CliContext, args: cli::ResumeArgs) -> i32 {
    let format = args.format;
    match resume_session(context, args) {
        Ok(result) => render_single_success(RESUME_COMMAND, format, &result, render_resumed_text),
        Err(err) => render_error(RESUME_COMMAND, format, err),
    }
}

fn run_activity(context: &CliContext, args: cli::ActivityArgs) -> i32 {
    match args.command {
        cli::ActivityCommand::Event(args) => {
            let format = args.format;
            let result = activity::read_event_from_stdin()
                .and_then(|event| activity::ingest_event(context, &args.id, event));
            match result {
                Ok(result) => render_single_success(
                    ACTIVITY_EVENT_COMMAND,
                    format,
                    &result,
                    render_activity_text,
                ),
                Err(err) => render_error(ACTIVITY_EVENT_COMMAND, format, err),
            }
        }
        cli::ActivityCommand::Status(args) => match activity::activity_status(context, &args.id) {
            Ok(result) => render_single_success(
                ACTIVITY_STATUS_COMMAND,
                args.format,
                &result,
                render_activity_text,
            ),
            Err(err) => render_error(ACTIVITY_STATUS_COMMAND, args.format, err),
        },
        cli::ActivityCommand::Hook(args) => {
            // Provider telemetry is deliberately fail-open: malformed or stale
            // hook input must never block a prompt, permission, or turn.
            activity::ingest_provider_hook_fail_open(context, args.agent, args.event.as_deref());
            exit::SUCCESS
        }
        cli::ActivityCommand::Doctor(args) => match activity::doctor(context, args.agent) {
            Ok(result) => render_single_success(
                ACTIVITY_DOCTOR_COMMAND,
                args.format,
                &result,
                render_doctor_text,
            ),
            Err(err) => render_error(ACTIVITY_DOCTOR_COMMAND, args.format, err),
        },
        cli::ActivityCommand::Setup(args) => {
            let action = if args.dry_run {
                activity::SetupAction::DryRun
            } else if args.apply {
                activity::SetupAction::Apply
            } else if args.remove {
                activity::SetupAction::Remove
            } else {
                activity::SetupAction::Repair
            };
            match activity::setup(args.agent, action) {
                Ok(result) => render_single_success(
                    ACTIVITY_SETUP_COMMAND,
                    args.format,
                    &result,
                    render_setup_text,
                ),
                Err(err) => render_error(ACTIVITY_SETUP_COMMAND, args.format, err),
            }
        }
    }
}

fn run_delete(context: &CliContext, args: cli::DeleteArgs) -> i32 {
    match delete_session(
        context,
        &args.id,
        resolve_tmux_bin(args.tmux_bin.as_deref()),
    ) {
        Ok(result) => {
            render_single_success(DELETE_COMMAND, args.format, &result, render_delete_text)
        }
        Err(err) => render_error(DELETE_COMMAND, args.format, err),
    }
}

#[derive(Debug, Clone)]
struct CliContext {
    state_dir: PathBuf,
    host: Option<String>,
}

impl CliContext {
    fn resolve(state_dir: Option<PathBuf>, host: Option<String>) -> Result<Self, CliError> {
        let state_dir = resolve_state_dir(state_dir)?;
        let host = resolve_host(
            host.or_else(|| non_empty_env("AGENT_SESSION_HOST"))
                .or_else(short_hostname),
        )?;
        Ok(Self { state_dir, host })
    }
}

#[derive(Debug, Clone, Deserialize, Serialize)]
struct SessionRecord {
    schema_version: String,
    id: String,
    agent: String,
    mode: String,
    title: Option<String>,
    cwd: String,
    tmux_session: String,
    prompt_file: Option<String>,
    log_file: Option<String>,
    created_at: String,
    updated_at: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    provider_resume: Option<ProviderResume>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    runtime: Option<RuntimeInfo>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    agent_args: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    agent_bin: Option<String>,
    #[serde(default, flatten, skip_serializing_if = "BTreeMap::is_empty")]
    extra: BTreeMap<String, Value>,
    #[serde(skip)]
    resume_sidecar_extra: BTreeMap<String, Value>,
}

#[derive(Debug, Clone, Deserialize, Serialize)]
struct ProviderResume {
    provider: String,
    session_id: String,
    captured_at: String,
    capture_method: String,
    resume_args: Vec<String>,
    #[serde(default, flatten, skip_serializing_if = "BTreeMap::is_empty")]
    extra: BTreeMap<String, Value>,
}

#[derive(Debug, Clone, Serialize)]
struct ProviderResumeView {
    provider: String,
    session_id: String,
    captured_at: String,
    capture_method: String,
    resume_args: Vec<String>,
}

impl From<&ProviderResume> for ProviderResumeView {
    fn from(provider_resume: &ProviderResume) -> Self {
        Self {
            provider: provider_resume.provider.clone(),
            session_id: provider_resume.session_id.clone(),
            captured_at: provider_resume.captured_at.clone(),
            capture_method: provider_resume.capture_method.clone(),
            resume_args: provider_resume.resume_args.clone(),
        }
    }
}

#[derive(Debug, Clone, Deserialize, Serialize)]
struct RuntimeInfo {
    kind: String,
    tmux_session: String,
    generation: u64,
    started_at: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    launch_id: String,
    #[serde(default, flatten, skip_serializing_if = "BTreeMap::is_empty")]
    extra: BTreeMap<String, Value>,
}

#[derive(Debug, Clone, Deserialize, Serialize)]
struct DurableResumeRecord {
    schema_version: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    provider_resume: Option<ProviderResume>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    runtime: Option<RuntimeInfo>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    agent_args: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    agent_bin: Option<String>,
    #[serde(default, flatten, skip_serializing_if = "BTreeMap::is_empty")]
    extra: BTreeMap<String, Value>,
}

#[derive(Debug, Serialize)]
struct SessionView {
    id: String,
    agent: String,
    mode: String,
    title: Option<String>,
    cwd: String,
    tmux_session: String,
    status: String,
    resumable: bool,
    repo_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    provider_resume: Option<ProviderResumeView>,
    attach_command: String,
    ssh_attach_command: Option<String>,
    prompt_file: Option<String>,
    log_file: Option<String>,
    created_at: String,
    updated_at: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    last_terminal_activity_at: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    runtime_started_at: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    turn_state: Option<activity::TurnState>,
}

#[derive(Debug)]
struct StartView {
    format: OutputFormat,
    result: SessionView,
}

pub(crate) struct ProviderResumeImportArgs {
    pub(crate) agent: AgentKind,
    pub(crate) provider_resume_id: String,
    pub(crate) title: Option<String>,
    pub(crate) id: Option<String>,
    pub(crate) tmux_bin: Option<PathBuf>,
    pub(crate) agent_bin: Option<PathBuf>,
    pub(crate) agent_args: Vec<String>,
    pub(crate) format: OutputFormat,
}

#[derive(Debug, Serialize)]
struct DeleteResult {
    id: String,
    tmux_session: String,
    killed: bool,
    deleted: bool,
    session_dir: String,
}

#[derive(Debug, Serialize)]
struct LogsResult {
    id: String,
    source: String,
    text: String,
}

#[derive(Debug, Serialize)]
struct SendResult {
    id: String,
    tmux_session: String,
    sent_text: bool,
    keys: Vec<String>,
}

#[derive(Debug, Serialize)]
struct GlanceResult {
    id: String,
    agent: String,
    title: Option<String>,
    tmux_session: String,
    status: String,
    resumable: bool,
    repo_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    provider_resume: Option<ProviderResumeView>,
    tail: String,
    created_at: String,
    updated_at: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    last_terminal_activity_at: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    runtime_started_at: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    turn_state: Option<activity::TurnState>,
}

#[derive(Debug, Serialize)]
struct AttachmentResult {
    id: String,
    filename: String,
    path: String,
    bytes: usize,
    content_type: Option<String>,
}

#[derive(Debug, Serialize)]
struct WorkdirResult {
    path: String,
    name: String,
    root: String,
    is_git_repo: bool,
    last_used: Option<String>,
}

#[derive(Debug, Default, Clone, Copy)]
struct WorkdirSearchOptions {
    git_only: bool,
    exclude_worktrees: bool,
}

#[derive(Debug, Default, Deserialize, Serialize)]
struct WorkdirUsage {
    entries: BTreeMap<String, String>,
}

#[derive(Debug, Clone)]
struct CliError(Box<CliErrorData>);

#[derive(Debug, Clone)]
struct CliErrorData {
    code: String,
    message: String,
    details: Option<Value>,
    exit_code: i32,
}

impl CliError {
    fn code(&self) -> &str {
        &self.0.code
    }

    fn usage(code: impl Into<String>, message: impl Into<String>, details: Option<Value>) -> Self {
        Self(Box::new(CliErrorData {
            code: code.into(),
            message: message.into(),
            details,
            exit_code: exit::USAGE,
        }))
    }

    fn runtime(
        code: impl Into<String>,
        message: impl Into<String>,
        details: Option<Value>,
    ) -> Self {
        Self(Box::new(CliErrorData {
            code: code.into(),
            message: message.into(),
            details,
            exit_code: exit::RUNTIME,
        }))
    }

    fn data(code: impl Into<String>, message: impl Into<String>, details: Option<Value>) -> Self {
        Self(Box::new(CliErrorData {
            code: code.into(),
            message: message.into(),
            details,
            exit_code: exit::DATA,
        }))
    }

    fn into_inner(self) -> CliErrorData {
        *self.0
    }
}

fn start_session(context: &CliContext, args: cli::StartArgs) -> Result<StartView, CliError> {
    validate_agent_args(args.agent, &args.agent_args)?;
    let cwd = resolve_cwd(args.cwd.as_deref())?;
    let prompt = read_prompt(&args.prompt, args.prompt_file.as_deref(), args.prompt_stdin)?;
    let provider_plan = initial_provider_resume_plan(args.agent, &cwd);
    let launch_started_at = SystemTime::now();
    let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
    let agent_bin = resolve_agent_bin(args.agent, args.agent_bin.as_deref());
    let mut created = create_record(RecordRequest {
        context,
        agent: args.agent,
        mode: "interactive",
        title: args.title.as_deref(),
        explicit_id: args.id.as_deref(),
        cwd: &cwd,
        prompt: prompt.as_deref(),
        log_file_name: None,
        provider_resume: provider_plan.provider_resume.clone(),
        agent_args: args.agent_args.clone(),
        agent_bin: Some(display_path(&agent_bin)),
    })?;

    if let Err(err) = start_interactive_tmux(
        &tmux_bin,
        &agent_bin,
        args.agent,
        &context.state_dir,
        &created.record,
        &provider_plan.launch_args,
        &args.agent_args,
    ) {
        cleanup_created_record(&created);
        return Err(err);
    }
    if created.prompt_file.is_some() {
        if args.paste_delay_ms > 0 {
            thread::sleep(Duration::from_millis(args.paste_delay_ms));
        }
        if let Err(err) = paste_prompt(&tmux_bin, &created.record) {
            let _ = kill_tmux_session(&tmux_bin, &created.record.tmux_session);
            cleanup_created_record(&created);
            return Err(err);
        }
    }
    if created.record.provider_resume.is_none()
        && let Some(provider_resume) =
            capture_provider_resume_after_launch(args.agent, &created.record, launch_started_at)
    {
        created.record.provider_resume = Some(provider_resume);
        created.record = persist_or_reload_session_record(context, &created.record);
    }

    let result = session_view(
        context,
        &created.record,
        Some("running".to_string()),
        Some(&tmux_bin),
    );
    record_workdir_usage(context, &cwd);
    Ok(StartView {
        format: args.format,
        result,
    })
}

fn start_run_session(context: &CliContext, args: cli::RunArgs) -> Result<StartView, CliError> {
    validate_agent_args(args.agent, &args.agent_args)?;
    let cwd = resolve_cwd(args.cwd.as_deref())?;
    let prompt = read_prompt(&args.prompt, args.prompt_file.as_deref(), args.prompt_stdin)?;
    let prompt = prompt
        .filter(|value| !value.trim().is_empty())
        .ok_or_else(|| {
            CliError::usage(
                "missing-prompt",
                "run requires --prompt, --prompt-file, or --prompt-stdin",
                None,
            )
        })?;
    let log_file = Some("output.log");
    let created = create_record(RecordRequest {
        context,
        agent: args.agent,
        mode: "run",
        title: args.title.as_deref(),
        explicit_id: args.id.as_deref(),
        cwd: &cwd,
        prompt: Some(&prompt),
        log_file_name: log_file,
        provider_resume: None,
        agent_args: args.agent_args.clone(),
        agent_bin: None,
    })?;

    let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
    let agent_bin = resolve_agent_bin(args.agent, args.agent_bin.as_deref());
    if let Err(err) = start_run_tmux(
        &tmux_bin,
        &agent_bin,
        args.agent,
        &context.state_dir,
        &created.record,
        &args.agent_args,
    ) {
        cleanup_created_record(&created);
        return Err(err);
    }

    let result = session_view(
        context,
        &created.record,
        Some("running".to_string()),
        Some(&tmux_bin),
    );
    record_workdir_usage(context, &cwd);
    Ok(StartView {
        format: args.format,
        result,
    })
}

pub(crate) fn start_provider_resume_session(
    context: &CliContext,
    args: ProviderResumeImportArgs,
) -> Result<StartView, CliError> {
    validate_provider_resume_import_agent_args(args.agent, &args.agent_args)?;
    validate_agent_args(args.agent, &args.agent_args)?;
    let provider_resume_id = normalize_provider_resume_id(&args.provider_resume_id)?;
    let source = resolve_provider_resume_source(args.agent, &provider_resume_id)?;
    let cwd = resolve_cwd(Some(&source.cwd))?;
    let cwd_string = display_path(&cwd);
    let resume_args = canonical_provider_resume_args(args.agent, &cwd_string, &provider_resume_id)
        .ok_or_else(|| {
            CliError::usage(
                "unsupported-provider-resume-agent",
                format!(
                    "{} sessions cannot be imported by provider resume id",
                    args.agent.as_str()
                ),
                Some(json!({ "agent": args.agent.as_str() })),
            )
        })?;
    let provider_resume = ProviderResume {
        provider: args.agent.as_str().to_string(),
        session_id: provider_resume_id,
        captured_at: Zoned::now().timestamp().to_string(),
        capture_method: source.capture_method,
        resume_args,
        extra: BTreeMap::new(),
    };
    let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
    let agent_bin = resolve_agent_bin(args.agent, args.agent_bin.as_deref());
    let created = create_record(RecordRequest {
        context,
        agent: args.agent,
        mode: "interactive",
        title: args.title.as_deref(),
        explicit_id: args.id.as_deref(),
        cwd: &cwd,
        prompt: None,
        log_file_name: None,
        provider_resume: Some(provider_resume.clone()),
        agent_args: args.agent_args,
        agent_bin: Some(display_path(&agent_bin)),
    })?;

    if let Err(err) = start_resume_tmux(
        &tmux_bin,
        &agent_bin,
        &context.state_dir,
        &created.record,
        &provider_resume.resume_args,
    ) {
        cleanup_created_record(&created);
        return Err(err);
    }

    let result = session_view(
        context,
        &created.record,
        Some("running".to_string()),
        Some(&tmux_bin),
    );
    record_workdir_usage(context, &cwd);
    Ok(StartView {
        format: args.format,
        result,
    })
}

struct CreatedRecord {
    record: SessionRecord,
    prompt_file: Option<PathBuf>,
    session_dir: PathBuf,
}

struct RecordRequest<'a> {
    context: &'a CliContext,
    agent: AgentKind,
    mode: &'a str,
    title: Option<&'a str>,
    explicit_id: Option<&'a str>,
    cwd: &'a Path,
    prompt: Option<&'a str>,
    log_file_name: Option<&'a str>,
    provider_resume: Option<ProviderResume>,
    agent_args: Vec<String>,
    agent_bin: Option<String>,
}

fn create_record(request: RecordRequest<'_>) -> Result<CreatedRecord, CliError> {
    let now = Zoned::now();
    let timestamp = now.strftime("%Y%m%d-%H%M%S").to_string();
    let iso = now.timestamp().to_string();
    let title_slug = request.title.map(slugify);
    let id = resolve_session_id(
        request.context,
        request.explicit_id,
        request.agent,
        &timestamp,
        title_slug.as_deref(),
    )?;
    let tmux_session = format!("hs-{}-{id}", request.agent.as_str());
    let session_dir = session_dir(request.context, &id);
    private_dir(&session_dir)?;

    let prompt_file = match request.prompt {
        Some(prompt) => {
            let path = session_dir.join("prompt.md");
            write_private_file(&path, prompt.as_bytes())?;
            Some(path)
        }
        None => None,
    };
    let log_file = request.log_file_name.map(|name| session_dir.join(name));
    let record = SessionRecord {
        schema_version: SESSION_DOCUMENT_VERSION.to_string(),
        id,
        agent: request.agent.as_str().to_string(),
        mode: request.mode.to_string(),
        title: request.title.map(str::to_string),
        cwd: display_path(request.cwd),
        tmux_session: tmux_session.clone(),
        prompt_file: prompt_file.as_ref().map(|path| display_path(path)),
        log_file: log_file.as_ref().map(|path| display_path(path)),
        created_at: iso.clone(),
        updated_at: iso,
        provider_resume: request.provider_resume,
        runtime: Some(RuntimeInfo {
            kind: "tmux".to_string(),
            tmux_session: tmux_session.clone(),
            generation: 1,
            started_at: now.timestamp().to_string(),
            launch_id: uuid::Uuid::new_v4().to_string(),
            extra: BTreeMap::new(),
        }),
        agent_args: request.agent_args,
        agent_bin: request.agent_bin,
        extra: BTreeMap::new(),
        resume_sidecar_extra: BTreeMap::new(),
    };

    write_session_record(request.context, &record)?;
    if let Err(err) = activity::activate_runtime(request.context, &record) {
        let _ = fs::remove_dir_all(&session_dir);
        return Err(err);
    }
    Ok(CreatedRecord {
        record,
        prompt_file,
        session_dir,
    })
}

fn cleanup_created_record(created: &CreatedRecord) {
    let _ = fs::remove_dir_all(&created.session_dir);
}

#[derive(Debug, Default)]
struct InitialProviderPlan {
    provider_resume: Option<ProviderResume>,
    launch_args: Vec<String>,
}

fn initial_provider_resume_plan(agent: AgentKind, _cwd: &Path) -> InitialProviderPlan {
    match agent {
        AgentKind::Claude => {
            let session_id = uuid::Uuid::new_v4().to_string();
            InitialProviderPlan {
                provider_resume: Some(ProviderResume {
                    provider: agent.as_str().to_string(),
                    session_id: session_id.clone(),
                    captured_at: Zoned::now().timestamp().to_string(),
                    capture_method: "claude-explicit-session-id".to_string(),
                    resume_args: vec!["--resume".to_string(), session_id.clone()],
                    extra: BTreeMap::new(),
                }),
                launch_args: vec!["--session-id".to_string(), session_id],
            }
        }
        AgentKind::Codex => InitialProviderPlan::default(),
        AgentKind::Hermes => InitialProviderPlan::default(),
    }
}

fn validate_agent_args(agent: AgentKind, args: &[String]) -> Result<(), CliError> {
    if agent != AgentKind::Claude {
        return Ok(());
    }
    for arg in args {
        if let Some(flag) = reserved_claude_resume_arg(arg) {
            return Err(CliError::usage(
                "reserved-agent-arg",
                format!(
                    "{flag} is managed by agent-session for durable Claude resume; do not pass it via --agent-arg"
                ),
                Some(json!({ "agent": agent.as_str(), "flag": flag })),
            ));
        }
    }
    Ok(())
}

fn validate_provider_resume_import_agent_args(
    agent: AgentKind,
    args: &[String],
) -> Result<(), CliError> {
    if args.is_empty() {
        return Ok(());
    }
    Err(CliError::usage(
        "provider-resume-agent-args-conflict",
        "provider_resume_id mode owns the resume command; omit agent_args",
        Some(json!({ "agent": agent.as_str() })),
    ))
}

fn reserved_claude_resume_arg(arg: &str) -> Option<&'static str> {
    [
        ("--session-id", false),
        ("--resume", false),
        ("-r", true),
        ("--continue", false),
        ("-c", false),
        ("--fork-session", false),
        ("--from-pr", false),
    ]
    .into_iter()
    .find_map(|(flag, allow_attached_short_value)| {
        reserved_agent_arg_matches(arg, flag, allow_attached_short_value).then_some(flag)
    })
}

fn reserved_codex_resume_arg(arg: &str) -> Option<&'static str> {
    [
        ("--cd", false),
        ("-C", true),
        ("--last", false),
        ("--all", false),
        ("--include-non-interactive", false),
    ]
    .into_iter()
    .find_map(|(flag, allow_attached_short_value)| {
        reserved_agent_arg_matches(arg, flag, allow_attached_short_value).then_some(flag)
    })
}

fn reserved_agent_arg_matches(
    arg: &str,
    flag: &'static str,
    allow_attached_short_value: bool,
) -> bool {
    if arg == flag {
        return true;
    }
    arg.strip_prefix(flag).is_some_and(|rest| {
        rest.starts_with('=')
            || (allow_attached_short_value
                && flag.starts_with('-')
                && !flag.starts_with("--")
                && !rest.is_empty())
    })
}

struct ProviderResumeSource {
    cwd: PathBuf,
    capture_method: String,
}

fn normalize_provider_resume_id(session_id: &str) -> Result<String, CliError> {
    normalize_resume_id(session_id).map_err(|err| {
        let message = match err {
            ResumeIdError::Empty => "provider resume id must not be empty",
            ResumeIdError::ControlChar => "provider resume id must not contain control characters",
        };
        CliError::usage("invalid-provider-resume-id", message, None)
    })
}

fn resolve_provider_resume_source(
    agent: AgentKind,
    session_id: &str,
) -> Result<ProviderResumeSource, CliError> {
    let provider = match agent {
        AgentKind::Codex => ResumeProvider::Codex,
        AgentKind::Claude => ResumeProvider::Claude,
        AgentKind::Hermes => {
            return Err(CliError::usage(
                "unsupported-provider-resume-agent",
                "hermes sessions cannot be imported by provider resume id",
                Some(json!({ "agent": agent.as_str() })),
            ));
        }
    };
    // The shared resolver owns the bounded history scan and returns a structured
    // outcome; the user-facing error text and exit-code mapping stay here.
    match resolve_resume_source(provider, session_id) {
        Ok(resolved) => Ok(ProviderResumeSource {
            cwd: resolved.cwd,
            capture_method: resolved.capture_method.to_string(),
        }),
        Err(ResumeResolveError::NotFound) => Err(provider_resume_not_found(agent, session_id)),
        Err(ResumeResolveError::Ambiguous { cwd_count }) => {
            Err(provider_resume_ambiguous(agent, session_id, cwd_count))
        }
        Err(ResumeResolveError::Truncated) => {
            Err(provider_resume_scan_truncated(agent, session_id))
        }
    }
}

fn provider_resume_not_found(agent: AgentKind, session_id: &str) -> CliError {
    CliError::data(
        "provider-resume-not-found",
        format!(
            "no {} provider history contains resume id: {session_id}",
            agent.as_str()
        ),
        Some(json!({ "agent": agent.as_str(), "provider_resume_id": session_id })),
    )
}

fn provider_resume_ambiguous(agent: AgentKind, session_id: &str, cwd_count: usize) -> CliError {
    CliError::data(
        "provider-resume-ambiguous",
        format!(
            "{} provider history has multiple cwd matches for resume id: {session_id}",
            agent.as_str()
        ),
        Some(json!({
            "agent": agent.as_str(),
            "provider_resume_id": session_id,
            "cwd_count": cwd_count,
        })),
    )
}

fn provider_resume_scan_truncated(agent: AgentKind, session_id: &str) -> CliError {
    CliError::runtime(
        "provider-resume-scan-truncated",
        format!(
            "{} provider history scan was truncated before resume id could be resolved: {session_id}",
            agent.as_str()
        ),
        Some(json!({ "agent": agent.as_str(), "provider_resume_id": session_id })),
    )
}

pub(crate) fn resolve_provider_transcript_path_from_roots(
    agent: AgentKind,
    session_id: &str,
    codex_root: Option<&Path>,
    claude_root: Option<&Path>,
) -> Option<PathBuf> {
    let mut matches = BTreeSet::new();
    let truncated = match agent {
        AgentKind::Codex => {
            let mut budget = CodexResumeScanBudget::from_env();
            collect_codex_provider_resume_matches(
                codex_root?,
                0,
                session_id,
                &mut matches,
                &mut budget,
            );
            budget.truncated
        }
        AgentKind::Claude => {
            let mut budget = ClaudeResumeScanBudget::from_env();
            collect_claude_provider_resume_matches(
                claude_root?,
                session_id,
                &mut matches,
                &mut budget,
            );
            budget.truncated
        }
        AgentKind::Hermes => return None,
    };
    if truncated || matches.len() != 1 {
        return None;
    }
    matches.into_iter().next().map(|candidate| candidate.path)
}

/// Resolve the `systemd-run` binary used to launch the tmux server inside a
/// transient systemd `--user` scope, or `None` to launch tmux directly.
///
/// `agent-session serve` starts each session as a child `tmux new-session -d`,
/// so the tmux server it spawns lands in the caller's cgroup. Under the
/// agent-console serve systemd service that means the server shares the unit
/// cgroup, and a service stop/restart can kill every live session
/// (`sympoies/agent-console#122`). Wrapping the server start in
/// `systemd-run --user --scope` moves it into its own transient scope cgroup, a
/// sibling of the service, so the sessions survive even an explicit
/// cgroup-wide kill of the serve unit.
///
/// This is opt-in via `AGENT_SESSION_TMUX_SCOPE` (the serve launcher sets it) and
/// only engages when a systemd `--user` manager is actually reachable, so an
/// opt-in on an unsupported host (no user manager, missing `systemd-run`,
/// non-Linux) degrades to a direct launch instead of failing session creation.
fn tmux_scope_runner() -> Option<PathBuf> {
    if !env_truthy("AGENT_SESSION_TMUX_SCOPE") {
        return None;
    }
    if !cfg!(target_os = "linux") {
        return None;
    }
    // A running systemd --user manager exposes this socket; without it
    // `systemd-run --user` cannot register the scope.
    let runtime_dir = env::var_os("XDG_RUNTIME_DIR")?;
    if !Path::new(&runtime_dir)
        .join("systemd")
        .join("private")
        .exists()
    {
        return None;
    }
    binary_on_path("systemd-run")
}

/// Build the base command for a `tmux new-session` that may start the tmux
/// server. With `scope_runner` set the server is launched inside a transient
/// systemd user scope (see [`tmux_scope_runner`]); otherwise tmux runs directly.
/// Callers append the `new-session ...` arguments to the returned command; both
/// forms accept the same trailing arguments because `systemd-run`'s `--`
/// hands everything after the tmux binary straight to tmux.
fn new_session_command(tmux_bin: &Path, scope_runner: Option<&Path>) -> ProcessCommand {
    match scope_runner {
        Some(runner) => {
            let mut command = ProcessCommand::new(runner);
            command
                .arg("--user")
                .arg("--scope")
                .arg("--quiet")
                .arg("--collect")
                .arg("--")
                .arg(tmux_bin);
            command
        }
        None => ProcessCommand::new(tmux_bin),
    }
}

fn start_interactive_tmux(
    tmux_bin: &Path,
    agent_bin: &Path,
    agent: AgentKind,
    state_dir: &Path,
    record: &SessionRecord,
    provider_launch_args: &[String],
    agent_args: &[String],
) -> Result<(), CliError> {
    let mut command = new_session_command(tmux_bin, tmux_scope_runner().as_deref());
    command
        .arg("new-session")
        .arg("-d")
        .arg("-s")
        .arg(&record.tmux_session)
        .arg("-c")
        .arg(&record.cwd);
    add_runtime_tmux_environment(&mut command, state_dir, record)?;
    command.arg("--").arg(agent_bin);

    match agent {
        AgentKind::Codex => {
            command.arg("--cd").arg(&record.cwd).arg("--no-alt-screen");
        }
        AgentKind::Claude => {
            command.args(provider_launch_args);
            if let Some(title) = record
                .title
                .as_deref()
                .filter(|value| !value.trim().is_empty())
            {
                command.arg("--name").arg(title);
            }
        }
        AgentKind::Hermes => {
            command.arg("chat");
        }
    }
    command.args(agent_args);
    run_status(command, "tmux new-session")
}

fn start_run_tmux(
    tmux_bin: &Path,
    agent_bin: &Path,
    agent: AgentKind,
    state_dir: &Path,
    record: &SessionRecord,
    agent_args: &[String],
) -> Result<(), CliError> {
    let prompt_file = record.prompt_file.as_ref().ok_or_else(|| {
        CliError::runtime(
            "missing-prompt-file",
            "session prompt file is missing",
            None,
        )
    })?;
    let log_file = record.log_file.as_ref().ok_or_else(|| {
        CliError::runtime("missing-log-file", "session log file is missing", None)
    })?;
    let mut parts = Vec::new();
    parts.push(shell_words::quote(&display_path(agent_bin)).into_owned());
    match agent {
        AgentKind::Codex => {
            parts.push("exec".to_string());
            parts.push("--cd".to_string());
            parts.push(shell_words::quote(&record.cwd).into_owned());
        }
        AgentKind::Claude => {
            parts.push("-p".to_string());
        }
        AgentKind::Hermes => {
            return Err(CliError::usage(
                "unsupported-run-agent",
                "hermes does not support one-shot run mode; use start --agent hermes",
                None,
            ));
        }
    }
    parts.extend(
        agent_args
            .iter()
            .map(|arg| shell_words::quote(arg).into_owned()),
    );
    parts.push(format!("\"$(cat {})\"", shell_words::quote(prompt_file)));
    let script = format!(
        "set -u\n{} > {} 2>&1\n",
        parts.join(" "),
        shell_words::quote(log_file)
    );

    let mut command = new_session_command(tmux_bin, tmux_scope_runner().as_deref());
    command
        .arg("new-session")
        .arg("-d")
        .arg("-s")
        .arg(&record.tmux_session)
        .arg("-c")
        .arg(&record.cwd);
    add_runtime_tmux_environment(&mut command, state_dir, record)?;
    command.arg("--").arg("sh").arg("-lc").arg(script);
    run_status(command, "tmux new-session")
}

fn capture_provider_resume_after_launch(
    agent: AgentKind,
    record: &SessionRecord,
    launch_started_at: SystemTime,
) -> Option<ProviderResume> {
    match agent {
        AgentKind::Codex => capture_codex_resume(record, launch_started_at),
        AgentKind::Claude | AgentKind::Hermes => None,
    }
}

#[derive(Debug)]
struct CodexResumeCandidate {
    session_id: String,
    created_at: SystemTime,
}

fn capture_codex_resume(
    record: &SessionRecord,
    launch_started_at: SystemTime,
) -> Option<ProviderResume> {
    let root = codex_sessions_root()?;
    let timeout = Duration::from_millis(env_u64(
        "AGENT_SESSION_CODEX_CAPTURE_TIMEOUT_MS",
        CODEX_RESUME_CAPTURE_TIMEOUT_MS,
    ));
    let poll = Duration::from_millis(
        env_u64(
            "AGENT_SESSION_CODEX_CAPTURE_POLL_MS",
            CODEX_RESUME_CAPTURE_POLL_MS,
        )
        .max(1),
    );
    let ambiguity_window = Duration::from_millis(env_u64(
        "AGENT_SESSION_CODEX_AMBIGUITY_WINDOW_MS",
        CODEX_RESUME_AMBIGUITY_WINDOW_MS,
    ));
    let started = Instant::now();
    let mut observed_singleton: Option<(String, Instant)> = None;

    loop {
        let mut candidates = Vec::new();
        let mut budget = CodexResumeScanBudget::from_env();
        collect_codex_resume_candidates(
            &root,
            0,
            launch_started_at,
            &record.cwd,
            &mut candidates,
            &mut budget,
        );
        if budget.truncated {
            return None;
        }

        let candidate_ids: BTreeSet<String> = candidates
            .into_iter()
            .map(|candidate| candidate.session_id)
            .collect();
        match candidate_ids.len() {
            1 => {
                let candidate_id = candidate_ids.iter().next().expect("singleton candidate");
                match &observed_singleton {
                    Some((observed, first_seen_at)) if observed == candidate_id => {
                        if codex_candidate_satisfied_ambiguity_window(
                            *first_seen_at,
                            ambiguity_window,
                        ) {
                            return Some(codex_provider_resume(record, candidate_id));
                        }
                    }
                    Some(_) => return None,
                    None => observed_singleton = Some((candidate_id.clone(), Instant::now())),
                }
            }
            0 => {
                if observed_singleton.is_some() {
                    return None;
                }
            }
            _ => return None,
        }
        if timeout.is_zero() || started.elapsed() >= timeout {
            return observed_singleton
                .as_ref()
                .filter(|(_, first_seen_at)| {
                    codex_candidate_satisfied_ambiguity_window(*first_seen_at, ambiguity_window)
                })
                .map(|(session_id, _)| codex_provider_resume(record, session_id));
        }
        let remaining = timeout.saturating_sub(started.elapsed());
        thread::sleep(poll.min(remaining));
    }
}

fn capture_codex_resume_from_history(record: &SessionRecord) -> Option<ProviderResume> {
    let root = codex_sessions_root()?;
    let earliest = record
        .created_at
        .parse::<Timestamp>()
        .ok()
        .map(SystemTime::from)?;
    let latest = earliest.checked_add(Duration::from_secs(CODEX_RESUME_BACKFILL_MAX_AGE_SECS))?;
    let mut candidates = Vec::new();
    let mut budget = CodexResumeScanBudget::from_env();
    collect_codex_resume_candidates(
        &root,
        0,
        earliest,
        &record.cwd,
        &mut candidates,
        &mut budget,
    );
    if budget.truncated {
        return None;
    }

    let candidate_ids: BTreeSet<String> = candidates
        .into_iter()
        .filter(|candidate| candidate.created_at <= latest)
        .map(|candidate| candidate.session_id)
        .collect();
    if candidate_ids.len() == 1 {
        let candidate_id = candidate_ids.iter().next().expect("singleton candidate");
        return Some(codex_provider_resume(record, candidate_id));
    }
    None
}

fn codex_candidate_satisfied_ambiguity_window(
    first_seen_at: Instant,
    ambiguity_window: Duration,
) -> bool {
    ambiguity_window.is_zero() || first_seen_at.elapsed() >= ambiguity_window
}

fn codex_provider_resume(record: &SessionRecord, session_id: &str) -> ProviderResume {
    ProviderResume {
        provider: "codex".to_string(),
        session_id: session_id.to_string(),
        captured_at: Zoned::now().timestamp().to_string(),
        capture_method: "codex-session-meta".to_string(),
        resume_args: canonical_provider_resume_args(AgentKind::Codex, &record.cwd, session_id)
            .expect("codex resume args"),
        extra: BTreeMap::new(),
    }
}

fn collect_codex_resume_candidates(
    dir: &Path,
    depth: usize,
    earliest: SystemTime,
    cwd: &str,
    candidates: &mut Vec<CodexResumeCandidate>,
    budget: &mut CodexResumeScanBudget,
) {
    if depth > CODEX_RESUME_SCAN_MAX_DEPTH {
        return;
    }
    let Ok(entries) = fs::read_dir(dir) else {
        return;
    };
    for entry in entries.flatten() {
        if !budget.visit_entry() {
            return;
        }
        let path = entry.path();
        let Ok(file_type) = entry.file_type() else {
            continue;
        };
        if file_type.is_dir() {
            collect_codex_resume_candidates(&path, depth + 1, earliest, cwd, candidates, budget);
            if budget.truncated {
                return;
            }
            continue;
        }
        if path.extension().and_then(|value| value.to_str()) != Some("jsonl") {
            continue;
        }
        let modified_at = entry
            .metadata()
            .and_then(|metadata| metadata.modified())
            .unwrap_or(SystemTime::UNIX_EPOCH);
        if modified_at < earliest {
            continue;
        }
        if let Some(meta) = read_codex_session_meta(&path) {
            if meta.cwd != cwd {
                continue;
            }
            if meta.created_at < earliest {
                continue;
            }
            candidates.push(CodexResumeCandidate {
                session_id: meta.session_id,
                created_at: meta.created_at,
            });
        }
    }
}

fn paste_prompt(tmux_bin: &Path, record: &SessionRecord) -> Result<(), CliError> {
    let prompt_file = record.prompt_file.as_ref().ok_or_else(|| {
        CliError::runtime(
            "missing-prompt-file",
            "session prompt file is missing",
            None,
        )
    })?;
    let buffer_name = format!("{}-prompt", record.id);
    let target = format!("{}:0.0", record.tmux_session);

    load_and_paste_buffer(tmux_bin, &buffer_name, &target, Path::new(prompt_file))?;

    // The initial prompt is submitted; `send` deliberately leaves this to
    // an explicit `--key enter`.
    let mut enter = ProcessCommand::new(tmux_bin);
    enter.arg("send-keys").arg("-t").arg(&target).arg("Enter");
    run_status(enter, "tmux send-keys")
}

/// Load `file` into a named tmux buffer and paste it into `target`, deleting the
/// buffer after paste (`-d`) or on failure. Shared by `paste_prompt` (initial
/// prompt) and `send` (steering text) so the buffer lifecycle lives in one place.
fn load_and_paste_buffer(
    tmux_bin: &Path,
    buffer_name: &str,
    target: &str,
    file: &Path,
) -> Result<(), CliError> {
    let mut load = ProcessCommand::new(tmux_bin);
    load.arg("load-buffer").arg("-b").arg(buffer_name).arg(file);
    run_status(load, "tmux load-buffer")?;

    let mut paste = ProcessCommand::new(tmux_bin);
    paste
        .arg("paste-buffer")
        .arg("-b")
        .arg(buffer_name)
        .arg("-d")
        .arg("-t")
        .arg(target);
    if let Err(err) = run_status(paste, "tmux paste-buffer") {
        delete_tmux_buffer(tmux_bin, buffer_name);
        return Err(err);
    }
    Ok(())
}

fn delete_tmux_buffer(tmux_bin: &Path, buffer_name: &str) {
    let _ = ProcessCommand::new(tmux_bin)
        .arg("delete-buffer")
        .arg("-b")
        .arg(buffer_name)
        .status();
}

fn send_to_session(context: &CliContext, args: cli::SendArgs) -> Result<SendResult, CliError> {
    let text = read_send_text(&args.text, args.text_stdin)?;
    if text.is_none() && args.keys.is_empty() {
        return Err(CliError::usage(
            "empty-send",
            "send requires --text, --text-stdin, or at least one --key",
            None,
        ));
    }
    let mut record = load_session_record(context, &args.id)?;
    let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
    if live_status(&tmux_bin, &record.tmux_session) != "running" {
        return Err(CliError::runtime(
            "session-not-running",
            format!("session is not running: {}", record.id),
            Some(json!({ "id": record.id })),
        ));
    }
    send_input(context, &record, text.as_deref(), &args.keys, &tmux_bin)?;
    touch_updated_at(context, &mut record)?;
    Ok(SendResult {
        id: record.id.clone(),
        tmux_session: record.tmux_session.clone(),
        sent_text: text.is_some(),
        keys: args
            .keys
            .iter()
            .map(|key| key.as_str().to_string())
            .collect(),
    })
}

/// Push literal text (via a private buffer file, never argv/stdout) and then
/// each special key into the live pane. `send-keys` interprets the tmux key
/// names, so approvals like Enter/Esc/Ctrl-C/arrows work from mobile.
fn send_input(
    context: &CliContext,
    record: &SessionRecord,
    text: Option<&str>,
    keys: &[SpecialKey],
    tmux_bin: &Path,
) -> Result<(), CliError> {
    let target = format!("{}:0.0", record.tmux_session);
    if let Some(text) = text {
        let buffer_name = format!("{}-send", record.id);
        let temp = session_dir(context, &record.id).join("send-input");
        write_private_file(&temp, text.as_bytes())?;
        let result = load_and_paste_buffer(tmux_bin, &buffer_name, &target, &temp);
        let _ = fs::remove_file(&temp);
        result?;
    }
    for key in keys {
        let mut command = ProcessCommand::new(tmux_bin);
        command
            .arg("send-keys")
            .arg("-t")
            .arg(&target)
            .arg(key.tmux_key());
        run_status(command, "tmux send-keys")?;
    }
    Ok(())
}

fn read_send_text(text: &Option<String>, text_stdin: bool) -> Result<Option<String>, CliError> {
    // Empty text (an empty `--text ""` or an empty stdin pipe) collapses to
    // `None` so the caller's empty-send guard treats it as "no text" rather than
    // pasting an empty buffer and reporting `sent_text: true` for a no-op. A
    // whitespace-only value is preserved: a space can be a meaningful keystroke.
    match (text, text_stdin) {
        (Some(_), true) => Err(CliError::usage(
            "multiple-text-sources",
            "use only one of --text or --text-stdin",
            None,
        )),
        (Some(value), false) => Ok(Some(value.clone()).filter(|value| !value.is_empty())),
        (None, true) => {
            let mut input = String::new();
            io::stdin().read_to_string(&mut input).map_err(|err| {
                CliError::runtime(
                    "stdin-read-failed",
                    format!("failed to read stdin: {err}"),
                    None,
                )
            })?;
            Ok(Some(input).filter(|value| !value.is_empty()))
        }
        (None, false) => Ok(None),
    }
}

fn glance_session(context: &CliContext, args: cli::GlanceArgs) -> Result<GlanceResult, CliError> {
    let record = load_session_record_with_provider_resume_backfill(context, &args.id)?;
    let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
    let status = session_status(&tmux_bin, &record);
    let tail = if status == "running" {
        capture_pane_tail(&record, args.tail, &tmux_bin)?
    } else {
        String::new()
    };
    let last_terminal_activity_at = last_terminal_activity_at(&tmux_bin, &record, &status);
    Ok(GlanceResult {
        id: record.id.clone(),
        agent: record.agent.clone(),
        title: record.title.clone(),
        tmux_session: record.tmux_session.clone(),
        status,
        resumable: is_resumable(&record),
        repo_name: repo_name_from_cwd(&record.cwd),
        provider_resume: record
            .provider_resume
            .as_ref()
            .map(ProviderResumeView::from),
        tail,
        created_at: record.created_at.clone(),
        updated_at: record.updated_at.clone(),
        last_terminal_activity_at,
        runtime_started_at: record
            .runtime
            .as_ref()
            .map(|runtime| runtime.started_at.clone()),
        turn_state: activity::state_for_view(context, &record),
    })
}

/// Run `tmux capture-pane -p -S -<tail>` for a session. Returns `Ok(Some(text))`
/// on success, `Ok(None)` when tmux ran but capture failed (a non-running or
/// gone pane), and `Err` only when the tmux binary could not be spawned. Shared
/// by `glance` and `logs` so the capture invocation lives in one place.
fn run_capture_pane(
    record: &SessionRecord,
    tail: usize,
    tmux_bin: &Path,
) -> Result<Option<String>, CliError> {
    let start = format!("-{}", tail.max(1));
    let output = ProcessCommand::new(tmux_bin)
        .arg("capture-pane")
        .arg("-p")
        .arg("-t")
        .arg(&record.tmux_session)
        .arg("-S")
        .arg(start)
        .output()
        .map_err(|err| {
            CliError::runtime(
                "tmux-capture-failed",
                format!("failed to run {}: {err}", tmux_bin.display()),
                Some(json!({ "tmux_session": record.tmux_session })),
            )
        })?;
    if !output.status.success() {
        return Ok(None);
    }
    Ok(Some(String::from_utf8_lossy(&output.stdout).to_string()))
}

/// Read the tmux paste buffer for a session's server (`tmux show-buffer`). tmux
/// buffers are server-global, so this returns the most recently set buffer on the
/// socket — which, for an agent pane whose TUI copies mouse selections into the
/// buffer (e.g. Claude Code's "copied N chars to tmux buffer"), is the user's last
/// on-screen selection. The `id` only validates the session (and picks the
/// daemon's socket); the buffer itself is not session-scoped. A fresh server with
/// no buffer yet exits non-zero ("no buffers") — treated as an empty selection,
/// not an error, so "nothing selected yet" is a normal empty result.
fn session_clipboard_buffer(
    context: &CliContext,
    id: &str,
    tmux_bin: &Path,
) -> Result<String, CliError> {
    // Validate the session exists first (clean not-found) before touching tmux.
    let _record = load_session_record(context, id)?;
    let output = ProcessCommand::new(tmux_bin)
        .arg("show-buffer")
        .output()
        .map_err(|err| {
            CliError::runtime(
                "tmux-show-buffer-failed",
                format!("failed to run {}: {err}", tmux_bin.display()),
                None,
            )
        })?;
    if !output.status.success() {
        return Ok(String::new());
    }
    Ok(String::from_utf8_lossy(&output.stdout).to_string())
}

fn capture_pane_tail(
    record: &SessionRecord,
    tail: usize,
    tmux_bin: &Path,
) -> Result<String, CliError> {
    match run_capture_pane(record, tail, tmux_bin)? {
        Some(text) => Ok(tail_lines(&strip_trailing_blank_lines(&text), tail)),
        None => Err(CliError::runtime(
            "tmux-capture-failed",
            "tmux capture-pane failed",
            Some(json!({ "tmux_session": record.tmux_session })),
        )),
    }
}

/// `capture-pane` pads its output to the full pane height with blank lines, so a
/// short, top-anchored pane ends with many empties. Drop the trailing blank
/// lines before taking the tail, or `glance` would show the empty bottom of the
/// pane instead of the actual recent content.
fn strip_trailing_blank_lines(text: &str) -> String {
    let mut lines: Vec<&str> = text.lines().collect();
    while lines.last().is_some_and(|line| line.trim().is_empty()) {
        lines.pop();
    }
    lines.join("\n")
}

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

    #[test]
    fn codex_resume_scan_truncates_large_stale_tree_by_entry_budget() {
        let tmp = tempfile::TempDir::new().unwrap();
        let root = tmp.path().join("sessions");
        fs::create_dir_all(&root).unwrap();
        for index in 0..32 {
            fs::write(
                root.join(format!("stale-{index}.jsonl")),
                r#"{"timestamp":"2000-01-01T00:00:00Z","type":"session_meta","payload":{"id":"old","cwd":"/repo","source":"cli","timestamp":"2000-01-01T00:00:00Z"}}"#,
            )
            .unwrap();
        }

        let mut candidates = Vec::new();
        let mut budget = CodexResumeScanBudget {
            visited: 0,
            max_entries: 5,
            deadline: Instant::now() + Duration::from_secs(60),
            truncated: false,
        };
        collect_codex_resume_candidates(
            &root,
            0,
            SystemTime::now(),
            "/repo",
            &mut candidates,
            &mut budget,
        );

        assert_eq!(budget.visited, 5);
        assert!(budget.truncated);
        assert!(candidates.is_empty());
    }
}

/// Bump `updated_at` to now so `list` can order by real control-plane activity.
/// Applied on `send` (a steering action); intentionally not on `glance`, which
/// is a high-frequency dashboard poll that would otherwise make `updated_at`
/// track polling rather than activity.
fn touch_updated_at(context: &CliContext, record: &mut SessionRecord) -> Result<(), CliError> {
    record.updated_at = Zoned::now().timestamp().to_string();
    write_session_record(context, record)
}

fn update_session_title(
    context: &CliContext,
    id: &str,
    title: Option<String>,
    tmux_bin: &Path,
) -> Result<SessionView, CliError> {
    let mut record = load_session_record(context, id)?;
    let previous_title = record.title.clone();
    record.title = normalize_title(title)?;
    touch_updated_at(context, &mut record)?;
    let status = session_status(tmux_bin, &record);
    // The persisted record above is the source of truth. Claude also carries its
    // own prompt-bar display name, which we set once via `--name` at launch
    // (`start_interactive_tmux`) and which never changes afterwards, so a renamed
    // session would show a stale name in the terminal while the console shows the
    // new one. Claude exposes `/rename <name>` as a runtime rename, so push the
    // new title into the live pane to keep the two in sync. Best-effort: a tmux
    // hiccup must not fail the title update, and Codex/Hermes have no such display
    // name so this is Claude-only and only when the title actually changed.
    if status == "running"
        && AgentKind::from_name(&record.agent) == Some(AgentKind::Claude)
        && record.title != previous_title
        && let Some(new_title) = record.title.as_deref()
    {
        let _ = rename_live_claude_session(context, &record, new_title, tmux_bin);
    }
    Ok(session_view(context, &record, Some(status), Some(tmux_bin)))
}

/// Push Claude's `/rename <name>` slash command into the live pane so the
/// prompt-bar display name follows a title change. Reuses the same buffered
/// paste + Enter injection as steering `send`, and collapses any embedded
/// newlines so the rename stays a single submitted line.
fn rename_live_claude_session(
    context: &CliContext,
    record: &SessionRecord,
    title: &str,
    tmux_bin: &Path,
) -> Result<(), CliError> {
    let single_line = title.replace(['\n', '\r'], " ");
    let command = format!("/rename {single_line}");
    send_input(
        context,
        record,
        Some(&command),
        &[SpecialKey::Enter],
        tmux_bin,
    )
}

fn resume_session(context: &CliContext, args: cli::ResumeArgs) -> Result<SessionView, CliError> {
    let tmux_bin = resolve_tmux_bin(args.tmux_bin.as_deref());
    resume_session_by_id(context, &args.id, &tmux_bin)
}

fn resume_session_by_id(
    context: &CliContext,
    id: &str,
    tmux_bin: &Path,
) -> Result<SessionView, CliError> {
    let mut record = load_session_record_with_provider_resume_backfill(context, id)?;
    match session_status(tmux_bin, &record).as_str() {
        "running" => {
            return Ok(session_view(
                context,
                &record,
                Some("running".to_string()),
                Some(tmux_bin),
            ));
        }
        "unknown" => {
            return Err(CliError::runtime(
                "session-status-unknown",
                format!("session status could not be checked: {}", record.id),
                Some(json!({ "id": record.id })),
            ));
        }
        _ => {}
    }
    let (provider_resume, agent) = validate_resume_metadata(&record)?;
    let previous_record = record.clone();
    let previous_activity = activity::capture_snapshot(context, &record.id)?;
    let resume_args = provider_resume.resume_args.clone();
    let agent_bin = record
        .agent_bin
        .as_deref()
        .map(PathBuf::from)
        .unwrap_or_else(|| resolve_agent_bin(agent, None));
    let now = Zoned::now();
    let next_generation = record
        .runtime
        .as_ref()
        .map(|runtime| runtime.generation.saturating_add(1))
        .unwrap_or(1);
    record.runtime = Some(RuntimeInfo {
        kind: "tmux".to_string(),
        tmux_session: record.tmux_session.clone(),
        generation: next_generation,
        started_at: now.timestamp().to_string(),
        launch_id: uuid::Uuid::new_v4().to_string(),
        extra: record
            .runtime
            .as_ref()
            .map(|runtime| runtime.extra.clone())
            .unwrap_or_default(),
    });
    record.updated_at = now.timestamp().to_string();
    write_session_record(context, &record)?;
    activity::activate_runtime(context, &record)?;
    if let Err(launch_err) = start_resume_tmux(
        tmux_bin,
        &agent_bin,
        &context.state_dir,
        &record,
        &resume_args,
    ) {
        let record_restore = write_session_record(context, &previous_record);
        let activity_restore = activity::restore_snapshot(context, &record.id, &previous_activity);
        if record_restore.is_err() || activity_restore.is_err() {
            return Err(CliError::runtime(
                "resume-launch-rollback-failed",
                "provider resume launch failed and the prior durable runtime could not be fully restored",
                Some(json!({
                    "id": record.id,
                    "launch_error": launch_err.code(),
                    "record_restored": record_restore.is_ok(),
                    "activity_restored": activity_restore.is_ok()
                })),
            ));
        }
        return Err(launch_err);
    }
    Ok(session_view(
        context,
        &record,
        Some("running".to_string()),
        Some(tmux_bin),
    ))
}

fn start_resume_tmux(
    tmux_bin: &Path,
    agent_bin: &Path,
    state_dir: &Path,
    record: &SessionRecord,
    resume_args: &[String],
) -> Result<(), CliError> {
    let mut command = new_session_command(tmux_bin, tmux_scope_runner().as_deref());
    command
        .arg("new-session")
        .arg("-d")
        .arg("-s")
        .arg(&record.tmux_session)
        .arg("-c")
        .arg(&record.cwd);
    add_runtime_tmux_environment(&mut command, state_dir, record)?;
    command
        .arg("--")
        .arg(agent_bin)
        .args(resume_args)
        .args(&record.agent_args);
    run_status(command, "tmux new-session")
}

fn add_runtime_tmux_environment(
    command: &mut ProcessCommand,
    state_dir: &Path,
    record: &SessionRecord,
) -> Result<(), CliError> {
    let runtime_id = record
        .runtime
        .as_ref()
        .map(|runtime| runtime.launch_id.as_str())
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            CliError::data(
                "runtime-id-missing",
                "session runtime is missing its launch id",
                Some(json!({ "id": record.id })),
            )
        })?;
    for value in [
        format!("AGENT_SESSION_ID={}", record.id),
        format!("AGENT_SESSION_STATE_DIR={}", display_path(state_dir)),
        format!("AGENT_SESSION_RUNTIME_ID={runtime_id}"),
    ] {
        command.arg("-e").arg(value);
    }
    Ok(())
}

fn normalize_title(title: Option<String>) -> Result<Option<String>, CliError> {
    let Some(title) = title else {
        return Ok(None);
    };
    let title = title.trim().to_string();
    if title.is_empty() {
        return Ok(None);
    }
    if title.chars().count() > 120 {
        return Err(CliError::usage(
            "title-too-long",
            "session title must be 120 characters or fewer",
            Some(json!({ "max_chars": 120 })),
        ));
    }
    Ok(Some(title))
}

fn write_session_attachment(
    context: &CliContext,
    id: &str,
    filename: Option<&str>,
    content_type: Option<String>,
    bytes: &[u8],
) -> Result<AttachmentResult, CliError> {
    let record = load_session_record(context, id)?;
    let filename = sanitize_attachment_filename(filename.unwrap_or("attachment.bin"));
    let dir = session_dir(context, &record.id).join("attachments");
    ensure_private_dir(&dir)?;
    let path = write_unique_attachment_file(&dir, &filename, bytes)?;
    Ok(AttachmentResult {
        id: record.id,
        filename,
        path: display_path(&path),
        bytes: bytes.len(),
        content_type,
    })
}

fn sanitize_attachment_filename(raw: &str) -> String {
    let leaf = Path::new(raw)
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or("attachment.bin");
    let mut safe = leaf
        .chars()
        .map(|ch| {
            if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_') {
                ch
            } else {
                '_'
            }
        })
        .collect::<String>();
    safe = safe
        .trim_matches(|ch| matches!(ch, '.' | '-' | '_'))
        .to_string();
    if safe.is_empty() {
        safe = "attachment.bin".to_string();
    }
    if safe.len() > 120 {
        safe.truncate(120);
    }
    safe
}

fn attachment_candidate_path(dir: &Path, filename: &str, attempt: usize) -> PathBuf {
    let stamp = Zoned::now().strftime("%Y%m%d-%H%M%S").to_string();
    if attempt == 0 {
        dir.join(format!("{stamp}-{filename}"))
    } else {
        dir.join(format!("{stamp}-{attempt}-{filename}"))
    }
}

fn write_unique_attachment_file(
    dir: &Path,
    filename: &str,
    bytes: &[u8],
) -> Result<PathBuf, CliError> {
    for attempt in 0..1000 {
        let path = attachment_candidate_path(dir, filename, attempt);
        let mut options = OpenOptions::new();
        options.write(true).create_new(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            options.mode(SECRET_FILE_MODE);
        }
        let mut file = match options.open(&path) {
            Ok(file) => file,
            Err(err) if err.kind() == io::ErrorKind::AlreadyExists => continue,
            Err(err) => {
                return Err(CliError::runtime(
                    "file-write-failed",
                    format!("failed to write {}: {err}", path.display()),
                    Some(json!({ "path": display_path(&path) })),
                ));
            }
        };
        if let Err(err) = file.write_all(bytes).and_then(|_| file.sync_all()) {
            let _ = fs::remove_file(&path);
            return Err(CliError::runtime(
                "file-write-failed",
                format!("failed to write {}: {err}", path.display()),
                Some(json!({ "path": display_path(&path) })),
            ));
        }
        return Ok(path);
    }
    Err(CliError::runtime(
        "attachment-name-exhausted",
        "failed to allocate a unique attachment filename",
        Some(json!({ "filename": filename })),
    ))
}

const WORKDIR_SEARCH_MAX_DEPTH: usize = 4;
const WORKDIR_SEARCH_MAX_VISITED: usize = 5000;
const WORKDIR_SEARCH_TIMEOUT: Duration = Duration::from_millis(250);

fn search_workdirs(
    context: &CliContext,
    query: Option<&str>,
    limit: Option<usize>,
    options: WorkdirSearchOptions,
) -> Result<Vec<WorkdirResult>, CliError> {
    let Some(home) = home_dir() else {
        return Ok(Vec::new());
    };
    let roots = [home.join("Project"), home.join(".config")];
    let usage = load_workdir_usage(context);
    search_workdirs_in_roots(
        &roots,
        query.unwrap_or_default(),
        limit.unwrap_or(30).clamp(1, 100),
        options,
        &usage,
    )
}

fn search_workdirs_in_roots(
    roots: &[PathBuf],
    query: &str,
    limit: usize,
    options: WorkdirSearchOptions,
    usage: &BTreeMap<String, String>,
) -> Result<Vec<WorkdirResult>, CliError> {
    #[derive(Debug)]
    struct Candidate {
        result: WorkdirResult,
        depth: usize,
    }

    let query = query.trim().to_ascii_lowercase();
    let started = Instant::now();
    let mut visited = 0usize;
    let mut matches = Vec::new();

    for root in roots {
        if started.elapsed() >= WORKDIR_SEARCH_TIMEOUT || visited >= WORKDIR_SEARCH_MAX_VISITED {
            break;
        }
        let Ok(root_meta) = fs::symlink_metadata(root) else {
            continue;
        };
        if root_meta.file_type().is_symlink() || !root_meta.is_dir() {
            continue;
        }
        let Ok(canonical_root) = fs::canonicalize(root) else {
            continue;
        };
        let root_display = display_path(root);
        let mut queue = VecDeque::from([(root.clone(), 0usize)]);
        while let Some((path, depth)) = queue.pop_front() {
            if started.elapsed() >= WORKDIR_SEARCH_TIMEOUT || visited >= WORKDIR_SEARCH_MAX_VISITED
            {
                break;
            }
            let Ok(canonical_path) = fs::canonicalize(&path) else {
                continue;
            };
            if !canonical_path.starts_with(&canonical_root) {
                continue;
            }
            visited += 1;
            let name = path
                .file_name()
                .and_then(|value| value.to_str())
                .unwrap_or_default()
                .to_string();
            let is_git_repo = is_git_repo(&path);
            let is_linked_worktree = is_linked_worktree(&path);
            let include = depth > 0
                && workdir_matches(&path, &name, &query)
                && (!options.git_only || is_git_repo)
                && (!options.exclude_worktrees || !is_linked_worktree);
            if include {
                let path_display = display_path(&path);
                matches.push(Candidate {
                    depth,
                    result: WorkdirResult {
                        last_used: usage.get(&path_display).cloned(),
                        path: path_display,
                        name,
                        root: root_display.clone(),
                        is_git_repo,
                    },
                });
            }
            if depth >= WORKDIR_SEARCH_MAX_DEPTH {
                continue;
            }
            if options.git_only && is_git_repo {
                continue;
            }
            let Ok(entries) = fs::read_dir(&path) else {
                continue;
            };
            for entry in entries.flatten() {
                let Ok(file_type) = entry.file_type() else {
                    continue;
                };
                if options.git_only
                    && entry
                        .file_name()
                        .to_str()
                        .is_some_and(|name| name == ".git")
                {
                    continue;
                }
                if file_type.is_dir() {
                    queue.push_back((entry.path(), depth + 1));
                }
            }
        }
    }

    matches.sort_by(|a, b| {
        let base = if options.git_only || options.exclude_worktrees {
            b.result
                .last_used
                .cmp(&a.result.last_used)
                .then_with(|| a.result.name.cmp(&b.result.name))
        } else {
            b.result.is_git_repo.cmp(&a.result.is_git_repo)
        };
        base.then_with(|| a.depth.cmp(&b.depth))
            .then_with(|| a.result.path.cmp(&b.result.path))
    });
    matches.truncate(limit);
    Ok(matches
        .into_iter()
        .map(|candidate| candidate.result)
        .collect())
}

fn workdir_matches(path: &Path, name: &str, query: &str) -> bool {
    if query.is_empty() {
        return true;
    }
    name.to_ascii_lowercase().contains(query)
        || path.to_string_lossy().to_ascii_lowercase().contains(query)
}

fn is_git_repo(path: &Path) -> bool {
    path.join(".git").exists()
}

fn is_linked_worktree(path: &Path) -> bool {
    fs::symlink_metadata(path.join(".git"))
        .map(|meta| meta.is_file())
        .unwrap_or(false)
}

fn workdir_usage_path(context: &CliContext) -> PathBuf {
    context.state_dir.join(WORKDIR_USAGE_FILE)
}

fn load_workdir_usage(context: &CliContext) -> BTreeMap<String, String> {
    let path = workdir_usage_path(context);
    let Ok(contents) = fs::read_to_string(path) else {
        return BTreeMap::new();
    };
    serde_json::from_str::<WorkdirUsage>(&contents)
        .map(|usage| usage.entries)
        .unwrap_or_default()
}

fn record_workdir_usage(context: &CliContext, cwd: &Path) {
    let path = workdir_usage_path(context);
    let mut usage = WorkdirUsage {
        entries: load_workdir_usage(context),
    };
    usage
        .entries
        .insert(display_path(cwd), Zoned::now().timestamp().to_string());
    if let Ok(bytes) = serde_json::to_vec_pretty(&usage) {
        let _ = write_atomic(&path, &bytes, SECRET_FILE_MODE);
    }
}

fn list_sessions(
    context: &CliContext,
    tmux_bin: Option<&Path>,
) -> Result<Vec<SessionView>, CliError> {
    let sessions_root = context.state_dir.join("sessions");
    if !sessions_root.exists() {
        return Ok(Vec::new());
    }
    let tmux_bin = tmux_bin
        .map(Path::to_path_buf)
        .unwrap_or_else(|| resolve_tmux_bin(None));
    let tmux_snapshots = tmux_session_snapshots(&tmux_bin);
    let mut records = Vec::new();
    for entry in fs::read_dir(&sessions_root).map_err(|err| {
        CliError::runtime(
            "session-list-failed",
            format!("failed to read {}: {err}", sessions_root.display()),
            Some(json!({ "path": display_path(&sessions_root) })),
        )
    })? {
        let entry = entry.map_err(|err| {
            CliError::runtime(
                "session-list-failed",
                format!("failed to read session entry: {err}"),
                None,
            )
        })?;
        if entry.path().is_dir() {
            let entry_name = entry.file_name().to_string_lossy().to_string();
            let record_path = entry.path().join("session.json");
            if record_path.is_file() {
                let resolved = ensure_record_in_session_dir(
                    context,
                    &record_path,
                    &entry.path(),
                    &entry_name,
                )?;
                let record = read_session_record(&resolved.record_path)?;
                validate_record_id(&record, &resolved.expected_id, &resolved.record_path)?;
                let record = backfill_provider_resume(context, record);
                let (status, last_terminal_activity_at) =
                    session_list_runtime_snapshot(&tmux_bin, tmux_snapshots.as_ref(), &record);
                records.push(session_view_from_parts(
                    context,
                    &record,
                    status,
                    last_terminal_activity_at,
                ));
            }
        }
    }
    records.sort_by(|a, b| {
        b.updated_at
            .cmp(&a.updated_at)
            .then_with(|| b.created_at.cmp(&a.created_at))
            .then_with(|| a.id.cmp(&b.id))
    });
    Ok(records)
}

fn load_session_view(
    context: &CliContext,
    id: &str,
    tmux_bin: Option<&Path>,
) -> Result<SessionView, CliError> {
    let record = load_session_record_with_provider_resume_backfill(context, id)?;
    let tmux_bin = tmux_bin
        .map(Path::to_path_buf)
        .unwrap_or_else(|| resolve_tmux_bin(None));
    let status = session_status(&tmux_bin, &record);
    Ok(session_view(
        context,
        &record,
        Some(status),
        Some(&tmux_bin),
    ))
}

fn load_session_record(context: &CliContext, id: &str) -> Result<SessionRecord, CliError> {
    let resolved = resolve_session_record_path(context, id)?;
    let record = read_session_record(&resolved.record_path)?;
    validate_record_id(&record, &resolved.expected_id, &resolved.record_path)?;
    Ok(record)
}

fn load_session_record_with_provider_resume_backfill(
    context: &CliContext,
    id: &str,
) -> Result<SessionRecord, CliError> {
    load_session_record(context, id).map(|record| backfill_provider_resume(context, record))
}

fn backfill_provider_resume(context: &CliContext, record: SessionRecord) -> SessionRecord {
    if record.provider_resume.is_some()
        || AgentKind::from_name(&record.agent) != Some(AgentKind::Codex)
    {
        return record;
    }
    let Some(provider_resume) = capture_codex_resume_from_history(&record) else {
        return record;
    };
    let mut record = record;
    record.provider_resume = Some(provider_resume);
    persist_or_reload_session_record(context, &record)
}

#[derive(Debug)]
struct ResolvedRecordPath {
    record_path: PathBuf,
    session_dir: PathBuf,
    expected_id: String,
}

fn resolve_session_record_path(
    context: &CliContext,
    id: &str,
) -> Result<ResolvedRecordPath, CliError> {
    validate_id(id)?;
    let exact_dir = session_dir(context, id);
    let exact = exact_dir.join("session.json");
    if exact.is_file() {
        return ensure_record_in_session_dir(context, &exact, &exact_dir, id);
    }
    let sessions_root = context.state_dir.join("sessions");
    let mut matches = Vec::new();
    if sessions_root.exists() {
        for entry in fs::read_dir(&sessions_root).map_err(|err| {
            CliError::runtime(
                "session-list-failed",
                format!("failed to read {}: {err}", sessions_root.display()),
                Some(json!({ "path": display_path(&sessions_root) })),
            )
        })? {
            let entry = entry.map_err(|err| {
                CliError::runtime(
                    "session-list-failed",
                    format!("failed to read session entry: {err}"),
                    None,
                )
            })?;
            let name = entry.file_name().to_string_lossy().to_string();
            let record_path = entry.path().join("session.json");
            if name.starts_with(id) && record_path.is_file() {
                matches.push(ensure_record_in_session_dir(
                    context,
                    &record_path,
                    &entry.path(),
                    &name,
                )?);
            }
        }
    }
    match matches.len() {
        1 => Ok(matches.remove(0)),
        0 => Err(CliError::runtime(
            "session-not-found",
            format!("session not found: {id}"),
            Some(json!({ "id": id })),
        )),
        _ => Err(CliError::usage(
            "ambiguous-session-id",
            format!("session id prefix is ambiguous: {id}"),
            Some(json!({ "id": id, "matches": matches.len() })),
        )),
    }
}

fn ensure_record_in_session_dir(
    context: &CliContext,
    path: &Path,
    expected_session_dir: &Path,
    expected_id: &str,
) -> Result<ResolvedRecordPath, CliError> {
    let sessions_root = context.state_dir.join("sessions");
    let canonical_root = fs::canonicalize(&sessions_root).map_err(|err| {
        CliError::runtime(
            "session-root-unavailable",
            format!("failed to canonicalize {}: {err}", sessions_root.display()),
            Some(json!({ "path": display_path(&sessions_root) })),
        )
    })?;
    let canonical_session_dir = fs::canonicalize(expected_session_dir).map_err(|err| {
        CliError::runtime(
            "session-read-failed",
            format!(
                "failed to canonicalize {}: {err}",
                expected_session_dir.display()
            ),
            Some(json!({ "path": display_path(expected_session_dir) })),
        )
    })?;
    if !canonical_session_dir.starts_with(&canonical_root) {
        return Err(CliError::usage(
            "session-path-escaped",
            "session directory escapes the managed state directory",
            Some(json!({ "session_dir": display_path(expected_session_dir) })),
        ));
    }
    let canonical_path = fs::canonicalize(path).map_err(|err| {
        CliError::runtime(
            "session-read-failed",
            format!("failed to canonicalize {}: {err}", path.display()),
            Some(json!({ "path": display_path(path) })),
        )
    })?;
    let expected_record_path = canonical_session_dir.join("session.json");
    if canonical_path != expected_record_path {
        return Err(CliError::usage(
            "session-path-escaped",
            "session record path escapes the requested session directory",
            Some(json!({
                "path": display_path(path),
                "expected_session_dir": display_path(expected_session_dir),
            })),
        ));
    }
    Ok(ResolvedRecordPath {
        record_path: canonical_path,
        session_dir: canonical_session_dir,
        expected_id: expected_id.to_string(),
    })
}

fn read_session_record(path: &Path) -> Result<SessionRecord, CliError> {
    let contents = fs::read_to_string(path).map_err(|err| {
        CliError::runtime(
            "session-read-failed",
            format!("failed to read {}: {err}", path.display()),
            Some(json!({ "path": display_path(path) })),
        )
    })?;
    let mut record: SessionRecord = serde_json::from_str(&contents).map_err(|err| {
        CliError::data(
            "session-json-invalid",
            format!("failed to parse {}: {err}", path.display()),
            Some(json!({ "path": display_path(path) })),
        )
    })?;
    if record.schema_version != SESSION_DOCUMENT_VERSION {
        return Err(CliError::data(
            "unsupported-session-version",
            format!(
                "unsupported session schema_version {}; expected {}",
                record.schema_version, SESSION_DOCUMENT_VERSION
            ),
            Some(json!({ "path": display_path(path), "schema_version": record.schema_version })),
        ));
    }
    merge_resume_sidecar(path, &mut record)?;
    Ok(record)
}

fn validate_record_id(
    record: &SessionRecord,
    expected_id: &str,
    path: &Path,
) -> Result<(), CliError> {
    if record.id != expected_id {
        return Err(CliError::data(
            "session-record-mismatch",
            format!(
                "session record id {} does not match directory {}",
                record.id, expected_id
            ),
            Some(json!({
                "path": display_path(path),
                "record_id": record.id,
                "expected_id": expected_id,
            })),
        ));
    }
    Ok(())
}

fn write_session_record(context: &CliContext, record: &SessionRecord) -> Result<(), CliError> {
    let bytes = serde_json::to_vec_pretty(record).map_err(|err| {
        CliError::runtime(
            "session-render-failed",
            format!("failed to render session json: {err}"),
            None,
        )
    })?;
    let path = session_dir(context, &record.id).join("session.json");
    write_resume_sidecar(context, record)?;
    write_private_file(&path, &bytes)
}

fn persist_or_reload_session_record(context: &CliContext, record: &SessionRecord) -> SessionRecord {
    match write_session_record(context, record) {
        Ok(()) => record.clone(),
        Err(_) => load_session_record(context, &record.id).unwrap_or_else(|_| record.clone()),
    }
}

fn merge_resume_sidecar(path: &Path, record: &mut SessionRecord) -> Result<(), CliError> {
    let sidecar_path = path.with_file_name(SESSION_RESUME_FILE);
    if !sidecar_path.is_file() {
        return Ok(());
    }
    let Ok(contents) = fs::read_to_string(&sidecar_path) else {
        return Ok(());
    };
    let Ok(sidecar) = serde_json::from_str::<DurableResumeRecord>(&contents) else {
        return Ok(());
    };
    if sidecar.schema_version != SESSION_RESUME_DOCUMENT_VERSION {
        return Ok(());
    }
    if let Some(provider_resume) = sidecar.provider_resume.clone() {
        if let Some(existing) = record.provider_resume.as_mut() {
            merge_extra_fields(&mut existing.extra, provider_resume.extra);
        } else {
            record.provider_resume = Some(provider_resume);
        }
    }
    if let Some(runtime) = sidecar.runtime.clone() {
        if let Some(existing) = record.runtime.as_mut() {
            merge_extra_fields(&mut existing.extra, runtime.extra);
        } else {
            record.runtime = Some(runtime);
        }
    }
    if record.agent_args.is_empty() {
        record.agent_args = sidecar.agent_args.clone();
    }
    if record.agent_bin.is_none() {
        record.agent_bin = sidecar.agent_bin.clone();
    }
    record.resume_sidecar_extra = sidecar.extra;
    Ok(())
}

fn merge_extra_fields(target: &mut BTreeMap<String, Value>, source: BTreeMap<String, Value>) {
    for (key, value) in source {
        target.entry(key).or_insert(value);
    }
}

fn write_resume_sidecar(context: &CliContext, record: &SessionRecord) -> Result<(), CliError> {
    let path = session_dir(context, &record.id).join(SESSION_RESUME_FILE);
    let Some(sidecar) = durable_resume_record(record) else {
        return remove_current_resume_sidecar_if_present(&path);
    };
    if should_preserve_existing_unsupported_resume_sidecar(&path) {
        return Ok(());
    }
    let bytes = serde_json::to_vec_pretty(&sidecar).map_err(|err| {
        CliError::runtime(
            "session-render-failed",
            format!("failed to render resume json: {err}"),
            None,
        )
    })?;
    write_private_file(&path, &bytes)
}

fn should_preserve_existing_unsupported_resume_sidecar(path: &Path) -> bool {
    match fs::read_to_string(path) {
        Ok(contents) => serde_json::from_str::<DurableResumeRecord>(&contents)
            .map(|sidecar| sidecar.schema_version != SESSION_RESUME_DOCUMENT_VERSION)
            .unwrap_or(true),
        Err(_) => false,
    }
}

fn remove_current_resume_sidecar_if_present(path: &Path) -> Result<(), CliError> {
    let Ok(contents) = fs::read_to_string(path) else {
        return Ok(());
    };
    let Ok(sidecar) = serde_json::from_str::<DurableResumeRecord>(&contents) else {
        return Ok(());
    };
    if sidecar.schema_version != SESSION_RESUME_DOCUMENT_VERSION {
        return Ok(());
    }
    fs::remove_file(path).map_err(|err| {
        CliError::runtime(
            "file-delete-failed",
            format!("failed to delete {}: {err}", path.display()),
            Some(json!({ "path": display_path(path) })),
        )
    })
}

fn durable_resume_record(record: &SessionRecord) -> Option<DurableResumeRecord> {
    record
        .provider_resume
        .as_ref()
        .map(|provider_resume| DurableResumeRecord {
            schema_version: SESSION_RESUME_DOCUMENT_VERSION.to_string(),
            provider_resume: Some(provider_resume.clone()),
            runtime: record.runtime.clone(),
            agent_args: record.agent_args.clone(),
            agent_bin: record.agent_bin.clone(),
            extra: record.resume_sidecar_extra.clone(),
        })
}

fn session_view(
    context: &CliContext,
    record: &SessionRecord,
    forced_status: Option<String>,
    tmux_bin: Option<&Path>,
) -> SessionView {
    let fallback_tmux;
    let tmux_bin = match tmux_bin {
        Some(tmux_bin) => tmux_bin,
        None => {
            fallback_tmux = resolve_tmux_bin(None);
            &fallback_tmux
        }
    };
    let status = forced_status.unwrap_or_else(|| session_status(tmux_bin, record));
    let last_terminal_activity_at = last_terminal_activity_at(tmux_bin, record, &status);
    session_view_from_parts(context, record, status, last_terminal_activity_at)
}

fn session_view_from_parts(
    context: &CliContext,
    record: &SessionRecord,
    status: String,
    last_terminal_activity_at: Option<String>,
) -> SessionView {
    SessionView {
        id: record.id.clone(),
        agent: record.agent.clone(),
        mode: record.mode.clone(),
        title: record.title.clone(),
        cwd: record.cwd.clone(),
        tmux_session: record.tmux_session.clone(),
        status,
        resumable: is_resumable(record),
        repo_name: repo_name_from_cwd(&record.cwd),
        provider_resume: record
            .provider_resume
            .as_ref()
            .map(ProviderResumeView::from),
        attach_command: local_attach_command(&record.tmux_session),
        ssh_attach_command: context
            .host
            .as_deref()
            .filter(|host| !host.trim().is_empty())
            .map(|host| ssh_attach_command(host, &record.tmux_session)),
        prompt_file: record.prompt_file.clone(),
        log_file: record.log_file.clone(),
        created_at: record.created_at.clone(),
        updated_at: record.updated_at.clone(),
        last_terminal_activity_at,
        runtime_started_at: record
            .runtime
            .as_ref()
            .map(|runtime| runtime.started_at.clone()),
        turn_state: activity::state_for_view(context, record),
    }
}

fn last_terminal_activity_at(
    tmux_bin: &Path,
    record: &SessionRecord,
    status: &str,
) -> Option<String> {
    if status != "running" {
        return None;
    }
    tmux_window_activity_at(tmux_bin, &record.tmux_session)
}

#[derive(Debug, Clone)]
struct TmuxSessionSnapshot {
    last_terminal_activity_at: Option<String>,
}

fn session_list_runtime_snapshot(
    tmux_bin: &Path,
    tmux_snapshots: Option<&BTreeMap<String, TmuxSessionSnapshot>>,
    record: &SessionRecord,
) -> (String, Option<String>) {
    match tmux_snapshots {
        Some(snapshots) => match snapshots.get(&record.tmux_session) {
            Some(snapshot) => (
                "running".to_string(),
                snapshot.last_terminal_activity_at.clone(),
            ),
            None => ("stopped".to_string(), None),
        },
        None => (session_status(tmux_bin, record), None),
    }
}

fn tmux_session_snapshots(tmux_bin: &Path) -> Option<BTreeMap<String, TmuxSessionSnapshot>> {
    let output = ProcessCommand::new(tmux_bin)
        .arg("list-windows")
        .arg("-a")
        .arg("-F")
        .arg("#{session_name}\t#{window_activity}")
        .output()
        .ok()?;
    if !output.status.success() {
        return None;
    }
    let raw = String::from_utf8_lossy(&output.stdout);
    let mut activity_by_session: BTreeMap<String, Option<i64>> = BTreeMap::new();
    for line in raw.lines() {
        let Some((session, activity)) = line.split_once('\t') else {
            continue;
        };
        if session.is_empty() {
            continue;
        }
        let Some(epoch_seconds) = parse_tmux_window_activity_seconds(activity) else {
            activity_by_session
                .entry(session.to_string())
                .or_insert(None);
            continue;
        };
        activity_by_session
            .entry(session.to_string())
            .and_modify(|current| {
                *current = Some(current.map_or(epoch_seconds, |value| value.max(epoch_seconds)));
            })
            .or_insert(Some(epoch_seconds));
    }
    Some(
        activity_by_session
            .into_iter()
            .map(|(session, maybe_epoch_seconds)| {
                (
                    session,
                    TmuxSessionSnapshot {
                        last_terminal_activity_at: maybe_epoch_seconds
                            .and_then(format_tmux_window_activity),
                    },
                )
            })
            .collect(),
    )
}

fn tmux_window_activity_at(tmux_bin: &Path, tmux_session: &str) -> Option<String> {
    let output = ProcessCommand::new(tmux_bin)
        .arg("display-message")
        .arg("-p")
        .arg("-t")
        .arg(tmux_session)
        .arg("#{window_activity}")
        .output()
        .ok()?;
    if !output.status.success() {
        return None;
    }
    let raw = String::from_utf8_lossy(&output.stdout);
    let epoch_seconds = parse_tmux_window_activity_seconds(raw.trim())?;
    format_tmux_window_activity(epoch_seconds)
}

fn parse_tmux_window_activity_seconds(raw: &str) -> Option<i64> {
    let epoch_seconds = raw.trim().parse::<i64>().ok()?;
    (epoch_seconds > 0).then_some(epoch_seconds)
}

fn format_tmux_window_activity(epoch_seconds: i64) -> Option<String> {
    Timestamp::from_second(epoch_seconds)
        .ok()
        .map(|timestamp| timestamp.to_string())
}

fn session_logs(
    record: &SessionRecord,
    tail: usize,
    tmux_bin: &Path,
) -> Result<LogsResult, CliError> {
    if let Some(result) = read_session_log_file(record, tail)? {
        return Ok(result);
    }

    if live_status(tmux_bin, &record.tmux_session) == "running"
        && let Some(text) = run_capture_pane(record, tail, tmux_bin)?
    {
        return Ok(LogsResult {
            id: record.id.clone(),
            source: "tmux".to_string(),
            text,
        });
    }

    Err(CliError::runtime(
        "logs-unavailable",
        "no tmux pane output or log file is available",
        Some(json!({ "id": record.id })),
    ))
}

fn read_session_log_file(
    record: &SessionRecord,
    tail: usize,
) -> Result<Option<LogsResult>, CliError> {
    if let Some(log_file) = &record.log_file {
        match fs::read_to_string(log_file) {
            Ok(text) => {
                return Ok(Some(LogsResult {
                    id: record.id.clone(),
                    source: "file".to_string(),
                    text: tail_lines(&text, tail),
                }));
            }
            Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(None),
            Err(err) => {
                return Err(CliError::runtime(
                    "log-read-failed",
                    format!("failed to read {log_file}: {err}"),
                    Some(json!({ "log_file": log_file })),
                ));
            }
        }
    }
    Ok(None)
}

fn delete_session(
    context: &CliContext,
    id: &str,
    tmux_bin: PathBuf,
) -> Result<DeleteResult, CliError> {
    let resolved = resolve_session_record_path(context, id)?;
    let record = read_session_record(&resolved.record_path)?;
    validate_record_id(&record, &resolved.expected_id, &resolved.record_path)?;
    let session_dir = resolved.session_dir;
    let killed = kill_tmux_session(&tmux_bin, &record.tmux_session);
    fs::remove_dir_all(&session_dir).map_err(|err| {
        CliError::runtime(
            "session-delete-failed",
            format!("failed to delete {}: {err}", session_dir.display()),
            Some(json!({ "path": display_path(&session_dir) })),
        )
    })?;
    Ok(DeleteResult {
        id: record.id,
        tmux_session: record.tmux_session,
        killed,
        deleted: true,
        session_dir: display_path(&session_dir),
    })
}

fn kill_tmux_session(tmux_bin: &Path, tmux_session: &str) -> bool {
    ProcessCommand::new(tmux_bin)
        .arg("kill-session")
        .arg("-t")
        .arg(tmux_session)
        .status()
        .map(|status| status.success())
        .unwrap_or(false)
}

fn session_status(tmux_bin: &Path, record: &SessionRecord) -> String {
    live_status(tmux_bin, &record.tmux_session)
}

fn is_resumable(record: &SessionRecord) -> bool {
    validate_resume_metadata(record).is_ok()
}

fn validate_resume_metadata(
    record: &SessionRecord,
) -> Result<(&ProviderResume, AgentKind), CliError> {
    if record.mode != "interactive" {
        return Err(CliError::data(
            "session-not-resumable",
            format!("session mode is not resumable: {}", record.id),
            Some(json!({ "id": record.id.clone(), "mode": record.mode.clone() })),
        ));
    }
    let provider_resume = record.provider_resume.as_ref().ok_or_else(|| {
        CliError::data(
            "session-not-resumable",
            format!(
                "session has no exact provider resume identity: {}",
                record.id
            ),
            Some(json!({ "id": record.id.clone() })),
        )
    })?;
    if provider_resume.resume_args.is_empty() {
        return Err(CliError::data(
            "session-not-resumable",
            format!("session has no provider resume command: {}", record.id),
            Some(json!({ "id": record.id.clone() })),
        ));
    }
    let agent = AgentKind::from_name(&record.agent).ok_or_else(|| {
        CliError::data(
            "invalid-agent",
            format!("unknown agent in session record: {}", record.agent),
            Some(json!({ "id": record.id.clone(), "agent": record.agent.clone() })),
        )
    })?;
    if provider_resume.provider != agent.as_str() {
        return Err(CliError::data(
            "session-provider-mismatch",
            "session provider resume metadata does not match the agent",
            Some(json!({
                "id": record.id.clone(),
                "agent": record.agent.clone(),
                "provider": provider_resume.provider.clone(),
            })),
        ));
    }
    validate_stored_agent_args(record, agent)?;
    let expected_args =
        canonical_provider_resume_args(agent, &record.cwd, &provider_resume.session_id)
            .ok_or_else(|| {
                CliError::data(
                    "session-not-resumable",
                    format!("session provider is not resumable: {}", record.id),
                    Some(json!({
                        "id": record.id.clone(),
                        "agent": record.agent.clone(),
                        "provider": provider_resume.provider.clone(),
                    })),
                )
            })?;
    if provider_resume.session_id.trim().is_empty() || provider_resume.resume_args != expected_args
    {
        return Err(CliError::data(
            "session-not-resumable",
            "session provider resume command does not match the stored identity",
            Some(json!({
                "id": record.id.clone(),
                "agent": record.agent.clone(),
                "provider": provider_resume.provider.clone(),
            })),
        ));
    }
    Ok((provider_resume, agent))
}

fn canonical_provider_resume_args(
    agent: AgentKind,
    cwd: &str,
    session_id: &str,
) -> Option<Vec<String>> {
    match agent {
        AgentKind::Codex => Some(vec![
            "resume".to_string(),
            session_id.to_string(),
            "--cd".to_string(),
            cwd.to_string(),
            "--no-alt-screen".to_string(),
        ]),
        AgentKind::Claude => Some(vec!["--resume".to_string(), session_id.to_string()]),
        AgentKind::Hermes => None,
    }
}

fn validate_stored_agent_args(record: &SessionRecord, agent: AgentKind) -> Result<(), CliError> {
    let flag = match agent {
        AgentKind::Codex => record
            .agent_args
            .iter()
            .find_map(|arg| reserved_codex_resume_arg(arg)),
        AgentKind::Claude => record
            .agent_args
            .iter()
            .find_map(|arg| reserved_claude_resume_arg(arg)),
        AgentKind::Hermes => None,
    };
    if let Some(flag) = flag {
        return Err(CliError::data(
            "session-not-resumable",
            "session provider arguments conflict with durable resume identity",
            Some(json!({
                "id": record.id.clone(),
                "agent": record.agent.clone(),
                "flag": flag,
            })),
        ));
    }
    Ok(())
}

fn repo_name_from_cwd(cwd: &str) -> Option<String> {
    let trimmed = cwd.trim_end_matches(['/', '\\']);
    if trimmed.is_empty() {
        return None;
    }
    Path::new(trimmed)
        .file_name()
        .and_then(|value| value.to_str())
        .filter(|value| !value.trim().is_empty())
        .map(str::to_string)
}

fn repo_remote_url_from_cwd(cwd: &str) -> Option<String> {
    let trimmed = cwd.trim();
    if trimmed.is_empty() {
        return None;
    }
    let root_output = ProcessCommand::new("git")
        .arg("-C")
        .arg(trimmed)
        .args(["rev-parse", "--show-toplevel"])
        .output()
        .ok()?;
    if !root_output.status.success() {
        return None;
    }
    let root = String::from_utf8(root_output.stdout).ok()?;
    let root = root.trim();
    if root.is_empty() {
        return None;
    }

    let remote_output = ProcessCommand::new("git")
        .arg("-C")
        .arg(root)
        .args(["remote", "get-url", "origin"])
        .output()
        .ok()?;
    if !remote_output.status.success() {
        return None;
    }
    let remote = String::from_utf8(remote_output.stdout).ok()?;
    git_remote_web_url(&remote)
}

fn git_remote_web_url(remote: &str) -> Option<String> {
    let parsed = parse_git_remote_url(remote)?;
    if parsed.host.trim().is_empty() || parsed.path.trim().is_empty() {
        return None;
    }
    Some(format!("https://{}/{}", parsed.host, parsed.path))
}

fn live_status(tmux_bin: &Path, tmux_session: &str) -> String {
    match ProcessCommand::new(tmux_bin)
        .arg("has-session")
        .arg("-t")
        .arg(tmux_session)
        .status()
    {
        Ok(status) if status.success() => "running".to_string(),
        Ok(status) if status.code() == Some(1) => "stopped".to_string(),
        Ok(_) => "unknown".to_string(),
        Err(_) => "unknown".to_string(),
    }
}

fn run_status(mut command: ProcessCommand, label: &str) -> Result<(), CliError> {
    let output = command.output().map_err(|err| {
        CliError::runtime(
            "command-spawn-failed",
            format!("failed to run {label}: {err}"),
            None,
        )
    })?;
    if output.status.success() {
        return Ok(());
    }
    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
    Err(CliError::runtime(
        "command-failed",
        if stderr.is_empty() {
            format!("{label} failed with status {}", output.status)
        } else {
            format!("{label} failed: {stderr}")
        },
        None,
    ))
}

fn read_prompt(
    prompt: &Option<String>,
    prompt_file: Option<&Path>,
    prompt_stdin: bool,
) -> Result<Option<String>, CliError> {
    let source_count = usize::from(prompt.is_some())
        + usize::from(prompt_file.is_some())
        + usize::from(prompt_stdin);
    if source_count > 1 {
        return Err(CliError::usage(
            "multiple-prompt-sources",
            "use only one of --prompt, --prompt-file, or --prompt-stdin",
            None,
        ));
    }
    if let Some(prompt) = prompt {
        return Ok(Some(prompt.clone()));
    }
    if prompt_stdin || prompt_file == Some(Path::new("-")) {
        let mut input = String::new();
        io::stdin().read_to_string(&mut input).map_err(|err| {
            CliError::runtime(
                "stdin-read-failed",
                format!("failed to read stdin: {err}"),
                None,
            )
        })?;
        return Ok(Some(input));
    }
    if let Some(path) = prompt_file {
        let path = absolute_path(path)?;
        let input = fs::read_to_string(&path).map_err(|err| {
            CliError::runtime(
                "prompt-file-read-failed",
                format!("failed to read {}: {err}", path.display()),
                Some(json!({ "path": display_path(&path) })),
            )
        })?;
        return Ok(Some(input));
    }
    Ok(None)
}

fn resolve_state_dir(explicit: Option<PathBuf>) -> Result<PathBuf, CliError> {
    if let Some(path) = explicit {
        return absolute_path(&path);
    }
    if let Some(path) = non_empty_env("AGENT_SESSION_STATE_DIR") {
        return absolute_path(Path::new(&path));
    }
    if let Some(path) = non_empty_env("XDG_STATE_HOME") {
        return Ok(normalize_path(&PathBuf::from(path).join("agent-session")));
    }
    let home = home_dir().ok_or_else(|| {
        CliError::runtime(
            "home-unavailable",
            "HOME is unset; pass --state-dir",
            Some(json!({ "flag": "--state-dir" })),
        )
    })?;
    Ok(normalize_path(&home.join(".local/state/agent-session")))
}

fn resolve_cwd(explicit: Option<&Path>) -> Result<PathBuf, CliError> {
    let cwd = match explicit {
        Some(path) => absolute_path(path)?,
        None => env::current_dir().map_err(|err| {
            CliError::runtime(
                "cwd-unavailable",
                format!("failed to read current directory: {err}"),
                None,
            )
        })?,
    };
    let metadata = fs::metadata(&cwd).map_err(|err| {
        CliError::usage(
            "cwd-unavailable",
            format!("working directory does not exist: {}: {err}", cwd.display()),
            Some(json!({ "cwd": display_path(&cwd) })),
        )
    })?;
    if !metadata.is_dir() {
        return Err(CliError::usage(
            "cwd-not-directory",
            format!("working directory is not a directory: {}", cwd.display()),
            Some(json!({ "cwd": display_path(&cwd) })),
        ));
    }
    Ok(cwd)
}

fn absolute_path(path: &Path) -> Result<PathBuf, CliError> {
    let expanded = expand_home(path);
    if expanded.is_absolute() {
        return Ok(normalize_path(&expanded));
    }
    let cwd = env::current_dir().map_err(|err| {
        CliError::runtime(
            "cwd-unavailable",
            format!("failed to read current directory: {err}"),
            None,
        )
    })?;
    Ok(normalize_path(&cwd.join(expanded)))
}

fn resolve_tmux_bin(explicit: Option<&Path>) -> PathBuf {
    explicit
        .map(Path::to_path_buf)
        .or_else(|| non_empty_env("AGENT_SESSION_TMUX_BIN").map(PathBuf::from))
        .unwrap_or_else(|| PathBuf::from("tmux"))
}

fn resolve_host(host: Option<String>) -> Result<Option<String>, CliError> {
    let Some(host) = host else {
        return Ok(None);
    };
    let host = host.trim();
    if host.is_empty() {
        return Ok(None);
    }
    validate_host(host)?;
    Ok(Some(host.to_string()))
}

fn validate_host(host: &str) -> Result<(), CliError> {
    if host.starts_with('-') {
        return Err(CliError::usage(
            "invalid-host",
            "host must not start with '-' because ssh would parse it as an option",
            Some(json!({ "host": host })),
        ));
    }
    if host.chars().any(char::is_control) || host.chars().any(char::is_whitespace) {
        return Err(CliError::usage(
            "invalid-host",
            "host must not contain whitespace or control characters",
            Some(json!({ "host": host })),
        ));
    }
    Ok(())
}

fn resolve_agent_bin(agent: AgentKind, explicit: Option<&Path>) -> PathBuf {
    if let Some(path) = explicit {
        return path.to_path_buf();
    }
    let env_key = match agent {
        AgentKind::Codex => "AGENT_SESSION_CODEX_BIN",
        AgentKind::Claude => "AGENT_SESSION_CLAUDE_BIN",
        AgentKind::Hermes => "AGENT_SESSION_HERMES_BIN",
    };
    non_empty_env(env_key)
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from(agent.as_str()))
}

fn resolve_session_id(
    context: &CliContext,
    explicit_id: Option<&str>,
    agent: AgentKind,
    timestamp: &str,
    title_slug: Option<&str>,
) -> Result<String, CliError> {
    if let Some(id) = explicit_id {
        validate_id(id)?;
        if session_dir(context, id).exists() {
            return Err(CliError::runtime(
                "session-exists",
                format!("session already exists: {id}"),
                Some(json!({ "id": id })),
            ));
        }
        return Ok(id.to_string());
    }
    let base = default_session_id_base(timestamp, agent, title_slug);
    for index in 0..100 {
        let id = if index == 0 {
            base.clone()
        } else {
            format!("{base}-{index}")
        };
        if !session_dir(context, &id).exists() {
            return Ok(id);
        }
    }
    Err(CliError::runtime(
        "session-id-exhausted",
        "failed to allocate a unique session id",
        Some(json!({ "base": base })),
    ))
}

fn default_session_id_base(timestamp: &str, agent: AgentKind, title_slug: Option<&str>) -> String {
    match title_slug {
        Some(slug) => format!("{timestamp}-{}-{slug}", agent.as_str()),
        None => format!("{timestamp}-{}", agent.as_str()),
    }
}

fn validate_id(id: &str) -> Result<(), CliError> {
    if id.is_empty()
        || !id
            .chars()
            .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
    {
        return Err(CliError::usage(
            "invalid-session-id",
            "session id may contain only ASCII letters, digits, '-' and '_'",
            Some(json!({ "id": id })),
        ));
    }
    Ok(())
}

fn session_dir(context: &CliContext, id: &str) -> PathBuf {
    context.state_dir.join("sessions").join(id)
}

fn private_dir(path: &Path) -> Result<(), CliError> {
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).map_err(|err| {
            CliError::runtime(
                "directory-create-failed",
                format!("failed to create {}: {err}", parent.display()),
                Some(json!({ "path": display_path(parent) })),
            )
        })?;
    }
    // Create the session dir as an ATOMIC ownership claim (fail if it already
    // exists) rather than create_dir_all. This closes a create/create race:
    // without it, two concurrent creates of the same id both pass the earlier
    // exists() check, both proceed, and the one whose tmux new-session loses the
    // duplicate-name race runs cleanup_created_record -> remove_dir_all on the
    // shared dir, deleting the winner's session.json and orphaning a live agent.
    match fs::create_dir(path) {
        Ok(()) => {}
        Err(err) if err.kind() == io::ErrorKind::AlreadyExists => {
            return Err(CliError::runtime(
                "session-exists",
                format!("session already exists: {}", path.display()),
                Some(json!({ "path": display_path(path) })),
            ));
        }
        Err(err) => {
            return Err(CliError::runtime(
                "directory-create-failed",
                format!("failed to create {}: {err}", path.display()),
                Some(json!({ "path": display_path(path) })),
            ));
        }
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let permissions = fs::Permissions::from_mode(0o700);
        fs::set_permissions(path, permissions).map_err(|err| {
            CliError::runtime(
                "directory-permissions-failed",
                format!("failed to set permissions on {}: {err}", path.display()),
                Some(json!({ "path": display_path(path) })),
            )
        })?;
    }
    Ok(())
}

fn ensure_private_dir(path: &Path) -> Result<(), CliError> {
    fs::create_dir_all(path).map_err(|err| {
        CliError::runtime(
            "directory-create-failed",
            format!("failed to create {}: {err}", path.display()),
            Some(json!({ "path": display_path(path) })),
        )
    })?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let permissions = fs::Permissions::from_mode(0o700);
        fs::set_permissions(path, permissions).map_err(|err| {
            CliError::runtime(
                "directory-permissions-failed",
                format!("failed to set permissions on {}: {err}", path.display()),
                Some(json!({ "path": display_path(path) })),
            )
        })?;
    }
    Ok(())
}

fn write_private_file(path: &Path, bytes: &[u8]) -> Result<(), CliError> {
    write_atomic(path, bytes, SECRET_FILE_MODE).map_err(|err| {
        CliError::runtime(
            "file-write-failed",
            format!("failed to write {}: {err}", path.display()),
            Some(json!({ "path": display_path(path) })),
        )
    })
}

fn render_single_success<T: Serialize>(
    command: &'static str,
    format: OutputFormat,
    result: &T,
    render_text: fn(&T) -> String,
) -> i32 {
    match format {
        OutputFormat::Json => {
            let envelope = Envelope::success(schema_version_for(BINARY, command, 1), result);
            print_json(&envelope)
        }
        OutputFormat::Text => {
            print!("{}", render_text(result));
            exit::SUCCESS
        }
    }
}

fn render_list_success(format: OutputFormat, results: &[SessionView]) -> i32 {
    match format {
        OutputFormat::Json => {
            let envelope = Envelope::success(schema_version_for(BINARY, LIST_COMMAND, 1), results);
            print_json(&envelope)
        }
        OutputFormat::Text => {
            if results.is_empty() {
                println!("no agent sessions");
            } else {
                for result in results {
                    println!(
                        "{}  {}  {}  {}",
                        result.id, result.agent, result.status, result.cwd
                    );
                }
            }
            exit::SUCCESS
        }
    }
}

fn render_error(command: &'static str, format: OutputFormat, err: CliError) -> i32 {
    let err = err.into_inner();
    match format {
        OutputFormat::Json => {
            let mut envelope_error = EnvelopeError::new(err.code, err.message);
            if let Some(details) = err.details {
                envelope_error = envelope_error.with_details(details);
            }
            let envelope: Envelope<()> =
                Envelope::failure(schema_version_for(BINARY, command, 1), envelope_error);
            print_json(&envelope);
        }
        OutputFormat::Text => {
            let _ = writeln!(io::stderr(), "error: {}", err.message);
        }
    }
    err.exit_code
}

fn print_json<T: Serialize>(value: &T) -> i32 {
    match serde_json::to_string(value) {
        Ok(serialized) => {
            println!("{serialized}");
            exit::SUCCESS
        }
        Err(err) => {
            eprintln!("error: failed to serialize json: {err}");
            exit::SOFTWARE
        }
    }
}

fn render_started_text(result: &SessionView) -> String {
    let mut text = format!(
        "started {} session {}\ntmux: {}\nattach: {}\n",
        result.agent, result.id, result.tmux_session, result.attach_command
    );
    if let Some(command) = &result.ssh_attach_command {
        text.push_str(&format!("ssh: {command}\n"));
    }
    text.push_str(&format!("delete: agent-session delete {}\n", result.id));
    text
}

fn render_command_text(result: &SessionView) -> String {
    match &result.ssh_attach_command {
        Some(command) => format!("{command}\nlocal: {}\n", result.attach_command),
        None => format!("{}\n", result.attach_command),
    }
}

fn render_logs_text(result: &LogsResult) -> String {
    result.text.clone()
}

fn render_send_text(result: &SendResult) -> String {
    let mut parts = Vec::new();
    if result.sent_text {
        parts.push("text".to_string());
    }
    if !result.keys.is_empty() {
        parts.push(format!("keys [{}]", result.keys.join(" ")));
    }
    let detail = if parts.is_empty() {
        "nothing".to_string()
    } else {
        parts.join(" + ")
    };
    format!("sent {detail} to {}\n", result.id)
}

fn render_glance_text(result: &GlanceResult) -> String {
    let mut text = format!("{} {} [{}]\n", result.id, result.agent, result.status);
    text.push_str(&result.tail);
    if !result.tail.is_empty() && !result.tail.ends_with('\n') {
        text.push('\n');
    }
    text
}

fn render_resumed_text(result: &SessionView) -> String {
    format!(
        "resumed {} session {}\ntmux: {}\nattach: {}\n",
        result.agent, result.id, result.tmux_session, result.attach_command
    )
}

fn render_activity_text(result: &activity::ActivityResult) -> String {
    format!(
        "{}: {:?} (revision {})\n",
        result.id, result.turn_state.phase, result.turn_state.revision
    )
}

fn render_doctor_text(result: &activity::DoctorResult) -> String {
    let mut text = String::new();
    for provider in &result.providers {
        text.push_str(&format!(
            "{}: {} (configured: {})\n",
            provider.provider,
            provider.classification,
            if provider.configured { "yes" } else { "no" }
        ));
        text.push_str(&format!("  completion: {}\n", provider.completion));
        text.push_str(&format!(
            "  attention: {}\n",
            provider.attention_correlation
        ));
        text.push_str(&format!("  next: {}\n", provider.guidance));
    }
    text
}

fn render_setup_text(result: &activity::SetupResult) -> String {
    if result.action == "dry-run" {
        return format!(
            "{} activity setup preview: {} (configured now: {}; would configure: {})\n",
            result.provider,
            if result.would_change {
                "changes required"
            } else {
                "no change"
            },
            if result.configured { "yes" } else { "no" },
            if result.would_configure { "yes" } else { "no" }
        );
    }
    format!(
        "{} activity setup {}: {} (configured: {})\n",
        result.provider,
        result.action,
        if result.changed {
            "updated"
        } else {
            "no change"
        },
        if result.configured { "yes" } else { "no" }
    )
}

fn render_delete_text(result: &DeleteResult) -> String {
    format!(
        "deleted {} (tmux killed: {})\n",
        result.id,
        if result.killed { "yes" } else { "no" }
    )
}

fn local_attach_command(tmux_session: &str) -> String {
    format!("tmux attach -t {}", shell_words::quote(tmux_session))
}

fn ssh_attach_command(host: &str, tmux_session: &str) -> String {
    let remote = local_attach_command(tmux_session);
    format!(
        "ssh -t {} {}",
        shell_words::quote(host),
        shell_words::quote(&remote)
    )
}

fn slugify(value: &str) -> String {
    let mut slug = String::new();
    let mut last_dash = false;
    for ch in value.chars() {
        if ch.is_ascii_alphanumeric() {
            slug.push(ch.to_ascii_lowercase());
            last_dash = false;
        } else if !last_dash {
            slug.push('-');
            last_dash = true;
        }
        if slug.len() >= 32 {
            break;
        }
    }
    let slug = slug.trim_matches('-').to_string();
    if slug.is_empty() {
        "session".to_string()
    } else {
        slug
    }
}

fn non_empty_env(key: &str) -> Option<String> {
    env::var(key).ok().filter(|value| !value.trim().is_empty())
}

fn is_truthy_flag(value: &str) -> bool {
    matches!(
        value.trim().to_ascii_lowercase().as_str(),
        "1" | "true" | "yes" | "on"
    )
}

fn env_truthy(key: &str) -> bool {
    non_empty_env(key).is_some_and(|value| is_truthy_flag(&value))
}

/// First `name` found on `PATH` as a regular file, or `None`.
fn binary_on_path(name: &str) -> Option<PathBuf> {
    let path = env::var_os("PATH")?;
    env::split_paths(&path)
        .map(|dir| dir.join(name))
        .find(|candidate| candidate.is_file())
}

fn env_u64(key: &str, default: u64) -> u64 {
    non_empty_env(key)
        .and_then(|value| value.parse::<u64>().ok())
        .unwrap_or(default)
}

fn short_hostname() -> Option<String> {
    let output = ProcessCommand::new("hostname").arg("-s").output().ok()?;
    if !output.status.success() {
        return None;
    }
    let value = String::from_utf8_lossy(&output.stdout).trim().to_string();
    if value.is_empty() { None } else { Some(value) }
}

fn tail_lines(text: &str, tail: usize) -> String {
    if tail == 0 {
        return String::new();
    }
    let lines: Vec<&str> = text.lines().collect();
    let start = lines.len().saturating_sub(tail);
    let mut output = lines[start..].join("\n");
    if !output.is_empty() {
        output.push('\n');
    }
    output
}

#[cfg(test)]
mod tests {
    use super::{
        AgentKind, CliContext, RecordRequest, create_record, resolve_session_id,
        strip_trailing_blank_lines,
    };
    use pretty_assertions::assert_eq;
    use std::fs;
    use std::path::Path;

    fn test_context(state_dir: &Path) -> CliContext {
        CliContext {
            state_dir: state_dir.to_path_buf(),
            host: None,
        }
    }

    fn create_test_record_id(
        context: &CliContext,
        agent: AgentKind,
        title: Option<&str>,
        explicit_id: Option<&str>,
    ) -> String {
        create_record(RecordRequest {
            context,
            agent,
            mode: "interactive",
            title,
            explicit_id,
            cwd: Path::new("/repo"),
            prompt: None,
            log_file_name: None,
            provider_resume: None,
            agent_args: Vec::new(),
            agent_bin: None,
        })
        .unwrap()
        .record
        .id
    }

    #[test]
    fn create_record_untitled_default_ids_do_not_repeat_agent_slug() {
        let tmp = tempfile::TempDir::new().unwrap();

        for (agent, slug) in [
            (AgentKind::Codex, "codex"),
            (AgentKind::Claude, "claude"),
            (AgentKind::Hermes, "hermes"),
        ] {
            let context = test_context(&tmp.path().join(slug));
            let id = create_test_record_id(&context, agent, None, None);

            assert!(
                !id.contains(&format!("{slug}-{slug}")),
                "untitled {slug} id should not repeat the agent slug: {id}"
            );
            assert_eq!(
                id.matches(slug).count(),
                1,
                "untitled {slug} id should include the agent slug once: {id}"
            );
        }
    }

    #[test]
    fn resolve_session_id_appends_collision_suffix_to_untitled_agent_base() {
        let tmp = tempfile::TempDir::new().unwrap();
        let context = test_context(tmp.path());
        let timestamp = "20260709-121932";
        let existing_id = format!("{timestamp}-codex");
        fs::create_dir_all(super::session_dir(&context, &existing_id)).unwrap();

        let id = resolve_session_id(&context, None, AgentKind::Codex, timestamp, None).unwrap();

        assert_eq!(id, format!("{existing_id}-1"));
    }

    #[test]
    fn create_record_title_derived_default_ids_keep_title_slug() {
        let tmp = tempfile::TempDir::new().unwrap();
        let context = test_context(tmp.path());

        let id = create_test_record_id(&context, AgentKind::Codex, Some("New Codex session"), None);

        assert!(
            id.ends_with("-codex-new-codex-session"),
            "title-derived id should preserve the title slug: {id}"
        );
    }

    #[test]
    fn create_record_explicit_ids_are_unchanged() {
        let tmp = tempfile::TempDir::new().unwrap();
        let context = test_context(tmp.path());

        let id = create_test_record_id(&context, AgentKind::Codex, None, Some("custom-id"));

        assert_eq!(id, "custom-id");
    }

    #[test]
    fn strip_trailing_blank_lines_preserves_content_and_internal_blanks() {
        // Trailing blank/whitespace-only lines are dropped...
        assert_eq!(
            strip_trailing_blank_lines("top-line\nsecond-line\n\n\n\n"),
            "top-line\nsecond-line"
        );
        assert_eq!(strip_trailing_blank_lines("a\nb\n   \n\t\n"), "a\nb");
        // ...but internal blank lines are preserved (only the tail is trimmed).
        assert_eq!(strip_trailing_blank_lines("a\n\nb\n\n\n"), "a\n\nb");
        // An all-blank pane collapses to empty.
        assert_eq!(strip_trailing_blank_lines("\n\n\n"), "");
        assert_eq!(strip_trailing_blank_lines(""), "");
        // Content with no trailing blanks is unchanged.
        assert_eq!(strip_trailing_blank_lines("only"), "only");
    }

    #[test]
    fn new_session_command_runs_tmux_directly_without_scope() {
        use super::new_session_command;
        use std::ffi::OsStr;
        use std::path::Path;

        let command = new_session_command(Path::new("/opt/tmux"), None);
        assert_eq!(command.get_program(), OsStr::new("/opt/tmux"));
        // The caller appends `new-session ...`, so the base command has no args.
        assert_eq!(command.get_args().count(), 0);
    }

    #[test]
    fn new_session_command_wraps_tmux_in_systemd_scope() {
        use super::new_session_command;
        use std::ffi::OsStr;
        use std::path::Path;

        let command = new_session_command(
            Path::new("/usr/bin/tmux"),
            Some(Path::new("/usr/bin/systemd-run")),
        );
        assert_eq!(command.get_program(), OsStr::new("/usr/bin/systemd-run"));
        let args: Vec<_> = command.get_args().collect();
        assert_eq!(
            args,
            vec![
                OsStr::new("--user"),
                OsStr::new("--scope"),
                OsStr::new("--quiet"),
                OsStr::new("--collect"),
                OsStr::new("--"),
                OsStr::new("/usr/bin/tmux"),
            ]
        );
    }

    #[test]
    fn is_truthy_flag_accepts_common_true_values_case_insensitively() {
        use super::is_truthy_flag;

        for value in ["1", "true", "TRUE", " Yes ", "on", "On"] {
            assert!(is_truthy_flag(value), "expected truthy: {value:?}");
        }
        for value in ["0", "false", "no", "off", "", "  ", "2", "enabled"] {
            assert!(!is_truthy_flag(value), "expected falsey: {value:?}");
        }
    }
}