mj_controller/controller/

move_session.rs

//! One recoverable stop/restore operation, independent of its initiating viewer.

#[cfg(test)]
mod tests;

use anyhow::{Context, Result, bail, ensure};
use mj_core::hex::lower_hex;
use sha2::{Digest, Sha256};

use super::lifecycle::SourceTargetDisposition;
use super::{Controller, SessionResumeOptions, now};

fn mutation_holds() -> &'static std::sync::Mutex<std::collections::BTreeSet<String>> {
    static HOLDS: std::sync::OnceLock<std::sync::Mutex<std::collections::BTreeSet<String>>> =
        std::sync::OnceLock::new();
    HOLDS.get_or_init(Default::default)
}

pub fn move_owns_session(session_id: &str) -> bool {
    move_has_pending_queue(session_id)
        || mutation_holds()
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .contains(session_id)
}

fn queue_holds() -> &'static std::sync::Mutex<std::collections::BTreeSet<String>> {
    static HOLDS: std::sync::OnceLock<std::sync::Mutex<std::collections::BTreeSet<String>>> =
        std::sync::OnceLock::new();
    HOLDS.get_or_init(Default::default)
}

pub fn move_has_pending_queue(session_id: &str) -> bool {
    queue_holds()
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .contains(session_id)
}

pub fn release_move_queue_hold(session_id: &str) {
    queue_holds()
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .remove(session_id);
}

pub fn restore_move_queue_hold(operation: &MoveOperation) {
    let mut holds = queue_holds()
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    if operation.queue_admission_started && !operation.queue_admission_finished {
        holds.insert(operation.selection.session_id.clone());
    } else {
        holds.remove(&operation.selection.session_id);
    }
}

/// What a recovered, interrupted source stop tells the person.
///
/// An in-place move promised to keep the environment; a recovery that tears it
/// down has broken that promise, so the message says so instead of leaving the
/// person to infer it from an unchanged "retry" line.
fn interrupted_source_stop_message(recovered: &str, in_place: bool) -> String {
    if in_place {
        format!("{recovered}; the in-place swap was interrupted; the environment was released")
    } else {
        recovered.to_owned()
    }
}

/// Whether the persisted record shows a source that has finished stopping with
/// a verified checkpoint to restore.
///
/// Only `Stopped` proves the source stop finished. Resume also admits recovery
/// states, but those do not establish that the source is already stopped.
fn source_stopped_with_verified_checkpoint(record: &mj_core::state::SessionRecord) -> bool {
    record.state == SessionState::Stopped && record.checkpoint.is_some()
}

/// The recovery guidance for a failed Move whose source is already stopped with
/// a verified checkpoint.
///
/// Resume restores the retained checkpoint on the destination profile and
/// target the Move selected.
fn stopped_source_recovery(
    session_id: &str,
    destination_profile: Option<&str>,
    destination_target: Option<&str>,
) -> String {
    let flag = |name: &str, value: Option<&str>| {
        value
            .filter(|value| !value.is_empty())
            .map(|value| format!(" --{name} {value}"))
            .unwrap_or_default()
    };
    format!(
        "Source is stopped with a verified checkpoint. Bring it back with \
         `mj resume --session {session_id}{}{} --queue start`.",
        flag("profile", destination_profile),
        flag("target", destination_target),
    )
}

/// The recovery guidance a failed or cancelled Move shows, from its persisted
/// state.
fn failed_move_recovery(
    operation: &MoveOperation,
    record: Option<&mj_core::state::SessionRecord>,
) -> String {
    if operation.queue_admission_started {
        return "Destination is live; retry queue admission on this same destination. Already accepted work may have effects.".to_owned();
    }
    match record {
        Some(record) if source_stopped_with_verified_checkpoint(record) => {
            stopped_source_recovery(
                &operation.selection.session_id,
                operation.selection.profile_id.as_deref(),
                operation.selection.target_template_id.as_deref(),
            )
        }
        _ => "Source or partial destination is retained. Retry move after resolving the reported error.".to_owned(),
    }
}

pub struct MoveMutationGuard(String);

impl MoveMutationGuard {
    pub fn reserve(session_id: &str) -> Result<Self> {
        ensure!(
            mutation_holds()
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner)
                .insert(session_id.to_owned()),
            "session already has a move owner"
        );
        Ok(Self(session_id.to_owned()))
    }
}

impl Drop for MoveMutationGuard {
    fn drop(&mut self) {
        mutation_holds()
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .remove(&self.0);
    }
}

pub(crate) fn move_refuses_command(session_id: &str, command: &RelayCommand) -> bool {
    move_owns_session(session_id)
        && matches!(
            command,
            RelayCommand::Prompt { .. }
                | RelayCommand::SetConfig { .. }
                | RelayCommand::SetSessionMode { .. }
                | RelayCommand::RunUserShell { .. }
                | RelayCommand::CancelUserShell { .. }
                | RelayCommand::Cancel
                | RelayCommand::RemoveQueuedPrompt { .. }
                | RelayCommand::ClearQueuedPrompts
        )
}
use crate::session_manager::{SessionManagerControl, StandaloneSession, new_command_id};
use mj_checkpoint::archive::{CanonicalQueuedCommandKind, verify_archive_streaming};
use mj_core::state::{MoveOperation, MovePhase, ResumeQueueDisposition, SessionState};

pub use mj_core::state::{MoveOutcome, MovePreparation, MoveSelection, MoveSessionRequest};

use crate::targets::{CommandExecutor, ProvisionStage, ProvisionStageGuard};
use mj_core::relay::RelayCommand;

/// Refresh source state without turning a dead source harness into a Move prerequisite.
/// Leasing preserves typed transport failures, unlike the UI's string-valued sync reply.
pub async fn refresh_move_source(
    manager: &SessionManagerControl,
    id: &str,
) -> Result<Option<mj_core::state::ManagedSessionSnapshot>> {
    let handle = manager
        .wait_for_session(id, std::time::Duration::from_secs(5))
        .await?;
    let result = async {
        let mut lease = handle.lease_connection().await?;
        let snapshot = lease.connection_mut().sync().await?;
        lease.release();
        Ok(snapshot)
    }
    .await;
    match result {
        Ok(snapshot) => Ok(Some(snapshot)),
        Err(error) if crate::worker_client::RelayTransportDead::marks(&error) => {
            tracing::warn!(session_id = id, error = %error, "Move will recover the unavailable source without its harness");
            Ok(None)
        }
        Err(error) => Err(error),
    }
}

fn digest(value: &impl serde::Serialize) -> Result<String> {
    Ok(lower_hex(Sha256::digest(serde_json::to_vec(value)?)))
}

struct MovePhaseTimer<'a> {
    session_id: &'a str,
    phase: &'static str,
    started: std::time::Instant,
}

impl<'a> MovePhaseTimer<'a> {
    fn new(session_id: &'a str, phase: &'static str) -> Self {
        Self {
            session_id,
            phase,
            started: std::time::Instant::now(),
        }
    }
}

impl Drop for MovePhaseTimer<'_> {
    fn drop(&mut self) {
        tracing::info!(
            session_id = self.session_id,
            phase = self.phase,
            elapsed_ms = self.started.elapsed().as_millis() as u64,
            "move phase finished"
        );
    }
}

/// Confirmation is an inspector, not transport for attachment bytes: every
/// surface that shows a move preparation sees a placeholder for each queued
/// image. Replay always reads the verified archive after destination readiness.
fn replace_queued_images_with_placeholders(
    queued_commands: &mut [mj_core::state::MaterializedQueuedPrompt],
) {
    for block in queued_commands
        .iter_mut()
        .flat_map(|command| command.content.iter_mut())
    {
        if block.get("type").and_then(serde_json::Value::as_str) != Some("image") {
            continue;
        }
        let mime = block
            .get("mimeType")
            .or_else(|| block.get("mime_type"))
            .and_then(serde_json::Value::as_str)
            .unwrap_or("image");
        *block = serde_json::json!({"type": "text", "text": format!("[Image attachment: {mime}]")});
    }
}

impl Controller {
    /// Returns the planned conversion when this move turns a local checkout
    /// into an isolated workspace, so the caller can describe it without
    /// reading Git a second time.
    fn validate_move_destination_paths(
        &self,
        source: &mj_core::state::SessionRecord,
        target_id: &str,
        executor: &(impl CommandExecutor + Sync),
    ) -> Result<Option<super::worktree::RawToWorkspaceConversion>> {
        use super::worktree::ResumePlan;
        match super::worktree::resume_compatibility(source, &self.config, target_id)
            .map_err(anyhow::Error::msg)?
        {
            ResumePlan::RawToWorkspace => {
                return Ok(Some(super::worktree::plan_raw_to_workspace(
                    source,
                    &self.config,
                    executor,
                )?));
            }
            ResumePlan::WorkspaceToRaw => {
                self.plan_workspace_to_raw(source, target_id, executor)?;
            }
            ResumePlan::InPlace if source.managed_worktree.is_none() => {
                if let Some(path) = &source.project_directory {
                    self.validate_project_directory(target_id, path, executor)?;
                }
            }
            ResumePlan::InPlace => {}
        }
        Ok(None)
    }
    fn move_confirmation(
        &self,
        selection: &MoveSelection,
        conversion: Option<&mj_core::state::RawConversionPreview>,
    ) -> Result<(bool, Vec<mj_core::state::MaterializedQueuedPrompt>, String)> {
        let source = self
            .state
            .sessions
            .get(&selection.session_id)
            .context("unknown move session")?;
        let (mut active, mut queued) = crate::database::move_pending_work(&source.id)?;
        if let Some(operation) = crate::database::load_move_operation(&source.id)?
            && operation.queue_admission_started
            && !operation.queue_admission_finished
        {
            ensure!(
                operation.selection == *selection,
                "queue admission is incomplete on the live destination; retry that move before selecting another destination"
            );
            let checkpoint = operation
                .checkpoint
                .as_ref()
                .context("retained queue checkpoint is missing")?;
            let verified = verify_archive_streaming(&checkpoint.archive_path)?;
            ensure!(
                verified.archive_sha256 == checkpoint.sha256
                    && verified.manifest.session.id == source.id,
                "retained move checkpoint verification failed"
            );
            queued = verified
                .canonical_session
                .queued_prompts
                .into_iter()
                .map(|entry| mj_core::state::MaterializedQueuedPrompt {
                    accepted_ordinal: None,
                    command_id: entry.command_id,
                    kind: match entry.kind {
                        CanonicalQueuedCommandKind::Prompt => {
                            mj_core::state::QueuedCommandKind::Prompt
                        }
                        CanonicalQueuedCommandKind::SetConfig { key, value } => {
                            mj_core::state::QueuedCommandKind::SetConfig { key, value }
                        }
                    },
                    content: entry.content,
                    queued_at_ms: entry.queued_at_ms,
                })
                .collect();
            active = false;
        }
        let fingerprint = digest(&(
            &source.last_profile,
            &source.target_template_id,
            &source.target,
            &source.target_runtime,
            &source.native_session_id,
            &source.resource_allocation,
            &source.additional_mounts,
            &source.container_cpus,
            &source.container_memory,
            selection,
            self.move_configuration_fingerprint(selection)?,
            &queued,
            // Only what the destination is built from. The dirty counts move
            // with every keystroke of a live agent, and hashing them would
            // invalidate the confirmation the person is reading.
            conversion.map(|preview| {
                (
                    &preview.fetch_url,
                    &preview.push_urls,
                    &preview.branch,
                    &preview.destination,
                )
            }),
        ))?;
        Ok((active, queued, fingerprint))
    }
    pub(super) fn move_configuration_fingerprint(
        &self,
        selection: &MoveSelection,
    ) -> Result<String> {
        let profile = self
            .config
            .profiles
            .get(
                selection
                    .profile_id
                    .as_deref()
                    .context("move profile is unresolved")?,
            )
            .context("move profile no longer exists")?;
        let target = self
            .config
            .targets
            .get(
                selection
                    .target_template_id
                    .as_deref()
                    .context("move target is unresolved")?,
            )
            .context("move target no longer exists")?;
        // Only a digest crosses IPC or enters the move record. Configuration
        // may contain credential-bearing values and must never be copied there.
        let source = self
            .state
            .sessions
            .get(&selection.session_id)
            .context("unknown move session")?;
        digest(&(
            profile,
            target,
            &self.config.bundles,
            self.config.targets.get(&source.target_template_id),
            self.config.profiles.get(&source.last_profile),
        ))
    }

    async fn validate_move_destination_configuration(
        &self,
        selection: &MoveSelection,
        source_harness: mj_core::config::HarnessKind,
        operational: &mj_core::relay::RelayOperationalState,
    ) -> Result<()> {
        let profile_id = selection
            .profile_id
            .as_deref()
            .context("move profile is unresolved")?;
        let profile = self
            .config
            .profiles
            .get(profile_id)
            .context("move profile no longer exists")?;
        let source = self
            .state
            .sessions
            .get(&selection.session_id)
            .context("unknown move session")?;
        if profile.kind != source_harness || profile_id == source.last_profile {
            return Ok(());
        }
        let accepted = mj_core::acp::AcceptedSessionConfig::from_configuration(
            &operational.config,
            &operational.config_options,
        );
        if accepted.model.is_none() && accepted.effort.is_none() {
            return Ok(());
        }
        // A fresh probe prevents a stale local catalogue from approving a
        // move that the destination profile will immediately reset.
        let choices =
            super::profile_config::discover(profile_id.to_owned(), accepted.model.clone(), true)
                .await
                .with_context(|| {
                    format!("discover destination profile {profile_id:?} configuration")
                })?;
        validate_preserved_configuration(profile_id, &accepted, &choices)
    }

    pub async fn prepare_move_session_controlled(
        &self,
        mut selection: MoveSelection,
        executor: &(impl CommandExecutor + Sync),
    ) -> Result<MovePreparation> {
        ensure!(
            selection.profile_id.is_some() || selection.target_template_id.is_some(),
            "move requires a target or profile selection"
        );
        let source = self
            .state
            .sessions
            .get(&selection.session_id)
            .context("unknown session")?;
        ensure!(
            !self.state.subagents.contains_key(&source.id),
            "sub-agent sessions cannot move independently of their parent"
        );
        ensure!(
            !self.state.subagents.values().any(|child| {
                child.parent_session_id == source.id
                    && self
                        .state
                        .sessions
                        .get(&child.child_session_id)
                        .is_some_and(|session| session.state.is_active())
            }),
            "stop active sub-agents before moving their parent session"
        );
        let previous = crate::database::load_move_operation(&source.id)?;
        let retry = previous.as_ref().is_some_and(|op| {
            !matches!(op.phase, MovePhase::Completed) && source.checkpoint.is_some()
        });
        ensure!(
            matches!(
                source.state,
                SessionState::Running | SessionState::Disconnected
            ) || retry,
            "only active sessions can move; run `mj resume` (or POST /api/v1/sessions/{}/resume) for a stopped or lost session",
            source.id
        );
        selection
            .profile_id
            .get_or_insert_with(|| source.last_profile.clone());
        selection
            .target_template_id
            .get_or_insert_with(|| source.target_template_id.clone());
        selection
            .additional_mounts
            .get_or_insert_with(|| source.additional_mounts.clone());
        ensure!(
            !selection.clear_resource_allocation || selection.resource_allocation.is_none(),
            "select resource allocation or explicitly clear it, not both"
        );
        if !selection.clear_resource_allocation {
            selection.resource_allocation = selection
                .resource_allocation
                .or_else(|| source.resource_allocation.clone());
        }
        let profile_id = selection.profile_id.as_deref().unwrap();
        let target_id = selection.target_template_id.as_deref().unwrap();
        let profile = self
            .config
            .profiles
            .get(profile_id)
            .context("unknown destination profile")?;
        ensure!(
            profile.enabled,
            "destination profile {profile_id:?} is disabled"
        );
        let target = self
            .config
            .targets
            .get(target_id)
            .context("unknown destination target")?;
        self.validate_muse_resume_destination(source, profile.kind, target_id)?;
        super::worktree::resume_compatibility(source, &self.config, target_id)
            .map_err(anyhow::Error::msg)?;
        super::backend::validate_resource_allocation(
            target,
            selection.resource_allocation.as_ref(),
        )?;
        let mounts = selection.additional_mounts.as_deref().unwrap_or_default();
        ensure!(
            profile.kind != mj_core::config::HarnessKind::Muse || mounts.is_empty(),
            "Muse Code ACP supports one workspace root; attached directories are unsupported"
        );
        ensure!(
            mounts.is_empty() || mj_core::config::mount_history_host(target).is_some(),
            "attached resources are unsupported for this target; select compatible resources explicitly"
        );
        crate::targets::validate_additional_mounts(mounts)?;
        for mount in mounts {
            self.validate_mount_source(target_id, &mount.source, executor)?;
        }
        let planned_conversion =
            self.validate_move_destination_paths(source, target_id, executor)?;
        ensure!(
            profile.home.is_dir(),
            "destination profile home is unavailable; configure the profile before moving"
        );
        super::worker_binary::preflight_worker_binary(target)?;
        super::backend::preflight_target(target, executor, super::backend::TargetCheck::Launch)?;
        let source_harness = previous
            .as_ref()
            .filter(|operation| {
                !operation.queue_admission_started && operation.phase != MovePhase::Completed
            })
            .and_then(|operation| operation.recovery_session.as_ref())
            .map_or(source.harness_kind, |record| record.harness_kind);
        let cross_harness = profile.kind != source_harness;
        if cross_harness {
            let cancel = tokio_util::sync::CancellationToken::new();
            let resolve =
                crate::utility_llm::UtilityLlmRuntime::shared().resolve(&self.config, &cancel);
            tokio::pin!(resolve);
            loop {
                tokio::select! {
                    result = &mut resolve => { result.context("cross-harness move needs an available utility model")?; break; }
                    _ = tokio::time::sleep(std::time::Duration::from_millis(50)) => {
                        if executor.cancellation_requested() { cancel.cancel(); bail!("move preparation cancelled"); }
                    }
                }
            }
        }
        // What moving a local checkout into a target really does, computed
        // before anything is stopped so a person can confirm it.
        let conversion = planned_conversion
            .map(|conversion| {
                super::worktree::raw_conversion_preview(source, &conversion, executor)
                    .context("describe the move of this checkout into the target")
            })
            .transpose()?
            .map(Box::new);
        let (active, mut queued_commands, fingerprint) =
            self.move_confirmation(&selection, conversion.as_deref())?;
        replace_queued_images_with_placeholders(&mut queued_commands);
        let operation_id = previous
            .as_ref()
            .filter(|operation| {
                operation.selection == selection
                    && operation.phase != MovePhase::Completed
                    && operation.checkpoint.is_some()
            })
            .map(|operation| operation.operation_id.clone())
            .unwrap_or(new_command_id("move")?);
        Ok(MovePreparation {
            source_unavailable: false,
            in_place: in_place_move_eligible(
                source,
                &selection,
                self.state.subagents.contains_key(&source.id),
                retry,
            ),
            conversion,
            selection,
            source_profile_id: source.last_profile.clone(),
            source_target_template_id: source.target_template_id.clone(),
            cross_harness,
            active,
            queued_commands,
            fingerprint,
            operation_id,
        })
    }

    /// Called with one daemon lifecycle and recovery reservation already held.
    pub async fn move_session_managed_controlled(
        &mut self,
        request: MoveSessionRequest,
        executor: &(impl CommandExecutor + Sync),
        manager: &SessionManagerControl,
    ) -> Result<MoveOutcome> {
        let prepared = &request.preparation;
        let id = prepared.selection.session_id.clone();
        let started = std::time::Instant::now();
        executor.notify_notice("Checking destination");
        let checked = {
            let _checking_destination =
                ProvisionStageGuard::new(executor, ProvisionStage::Verifying);
            let mut checked = self
                .prepare_move_session_controlled(prepared.selection.clone(), executor)
                .await?;
            // Destination checks can outlast a turn. Refresh confirmation from the
            // relay immediately before interruption, while new submissions are held.
            if matches!(
                self.state.sessions[&id].state,
                SessionState::Running | SessionState::Disconnected
            ) {
                let source_harness = self.state.sessions[&id].harness_kind;
                let snapshot = refresh_move_source(manager, &id).await?;
                let (active, queue, fingerprint) =
                    self.move_confirmation(&checked.selection, checked.conversion.as_deref())?;
                checked.source_unavailable = snapshot
                    .as_ref()
                    .is_none_or(|snapshot| !snapshot.operational.native_session_is_ready());
                checked.active = active
                    || checked.source_unavailable
                    || snapshot.as_ref().is_some_and(|snapshot| {
                        let mut operational = snapshot.operational.clone();
                        operational.queued_prompts.clear();
                        operational.checkpoint_barrier = None;
                        !operational.safe_to_replace(source_harness)
                    });
                if let Some(snapshot) = &snapshot {
                    self.validate_move_destination_configuration(
                        &checked.selection,
                        source_harness,
                        &snapshot.operational,
                    )
                    .await?;
                }
                checked.queued_commands = queue;
                checked.fingerprint = fingerprint;
            }
            checked
        };
        ensure!(
            checked.fingerprint == prepared.fingerprint,
            "session, pending work, or destination configuration changed; prepare and confirm Move again"
        );
        let queue = request.queue.unwrap_or(ResumeQueueDisposition::Discard);
        let source = self.state.sessions[&id].clone();
        let old_operation = crate::database::load_move_operation(&id)?;
        let retry = old_operation.filter(|op| {
            op.selection == prepared.selection
                && op.phase != MovePhase::Completed
                && op.checkpoint.is_some()
        });
        if retry.is_none()
            && source.state == SessionState::Running
            && source.last_profile == checked.selection.profile_id.as_deref().unwrap()
            && source.target_template_id == checked.selection.target_template_id.as_deref().unwrap()
            && Some(&source.additional_mounts) == checked.selection.additional_mounts.as_ref()
            && source.resource_allocation == checked.selection.resource_allocation
            && (!checked.selection.clear_resource_allocation
                || (source.container_cpus.is_none() && source.container_memory.is_none()))
        {
            return Ok(outcome(
                &prepared.operation_id,
                &prepared.selection,
                "unchanged",
                None,
                None,
            ));
        }
        ensure!(
            !checked.active || request.acknowledge_interruption,
            "active work will be interrupted; confirm Move again with interruption acknowledgement"
        );
        ensure!(
            checked.queued_commands.is_empty() || request.queue.is_some(),
            "pending work requires an explicit queue choice: discard or start"
        );
        let timestamp = now();
        let mut operation = match retry {
            Some(mut op) => {
                ensure!(
                    !op.queue_admission_started || op.queue == queue,
                    "queued work may already have run; retry with the original queue choice on the same destination"
                );
                crate::database::clear_move_cancellation_for_retry(&id)?;
                op.configuration_fingerprint =
                    self.move_configuration_fingerprint(&checked.selection)?;
                op.queue = queue;
                op.cancellation_requested = false;
                op.error = None;
                op
            }
            None => MoveOperation {
                source_checkpoint_only: false,
                in_place: in_place_move_eligible(
                    &source,
                    &checked.selection,
                    self.state.subagents.contains_key(&id),
                    false,
                ),
                operation_id: prepared.operation_id.clone(),
                selection: checked.selection.clone(),
                source_profile_id: source.last_profile.clone(),
                source_target_template_id: source.target_template_id.clone(),
                source_target: source.target.clone(),
                source_native_session_id: source.native_session_id.clone(),
                source_additional_mounts: source.additional_mounts.clone(),
                source_resource_allocation: source.resource_allocation.clone(),
                destination_target: None,
                destination_native_session_id: None,
                destination_store_id: None,
                configuration_fingerprint: self
                    .move_configuration_fingerprint(&checked.selection)?,
                checkpoint: None,
                recovery_session: None,
                queue,
                phase: MovePhase::Preparing,
                queue_admission_started: false,
                queue_admission_finished: false,
                cancellation_requested: false,
                created_at: timestamp.clone(),
                updated_at: timestamp,
                error: None,
            },
        };
        crate::database::save_move_operation(&operation)?;
        tracing::info!(
            session_id = id,
            phase = "preflight",
            elapsed_ms = started.elapsed().as_millis() as u64,
            "move phase completed"
        );
        let result = self
            .execute_move(&mut operation, Some(&checked), executor, manager)
            .await;
        self.finish_move_result(&mut operation, result, executor)
    }

    fn finish_move_result(
        &self,
        operation: &mut MoveOperation,
        result: Result<()>,
        executor: &impl CommandExecutor,
    ) -> Result<MoveOutcome> {
        let (status, error, recovery) = match result {
            Ok(()) => {
                operation.phase = MovePhase::Completed;
                ("completed", None, None)
            }
            Err(error) => {
                let cancelled =
                    executor.cancellation_requested() || operation.cancellation_requested;
                operation.phase = if cancelled {
                    MovePhase::Cancelled
                } else {
                    MovePhase::Failed
                };
                operation.cancellation_requested = cancelled;
                let recovery = failed_move_recovery(
                    operation,
                    self.state.sessions.get(&operation.selection.session_id),
                );
                let error = format!("{error:#}");
                operation.error = Some(error.clone());
                (
                    if cancelled { "cancelled" } else { "failed" },
                    Some(error),
                    Some(recovery),
                )
            }
        };
        operation.updated_at = now();
        crate::database::save_move_operation(operation)?;
        Ok(outcome(
            &operation.operation_id,
            &operation.selection,
            status,
            error,
            recovery,
        ))
    }

    pub async fn recover_move_managed_controlled(
        &mut self,
        mut operation: MoveOperation,
        executor: &(impl CommandExecutor + Sync),
        manager: &SessionManagerControl,
    ) -> Result<MoveOutcome> {
        let id = operation.selection.session_id.clone();
        let result = async {
            let session = self.state.sessions.get(&id).context("move session is missing")?.clone();
            if operation.queue_admission_started {
                ensure!(!operation.cancellation_requested, "Move was cancelled; destination retained without further queue admission");
                return self.admit_move_queue(&mut operation, executor).await;
            }
            if matches!(session.state, SessionState::Closing | SessionState::Destroying) {
                let cleanup = crate::targets::CancellableProcessExecutor::with_timeout(std::time::Duration::from_secs(15));
                self.recover_move_source_stop(&mut operation, &cleanup, manager).await?;
                operation.checkpoint = self.state.sessions[&id].checkpoint.clone();
                if self.state.sessions[&id].state == SessionState::Stopped && self.state.sessions[&id].target.is_some() {
                    self.cleanup_stopped_target(&id, &cleanup)?;
                }
                bail!("{}", interrupted_source_stop_message(
                    "Move source stop recovered; no destination work was started. Retry Move or Resume with previous settings",
                    operation.in_place,
                ));
            }
            match operation.phase {
                MovePhase::Preparing => bail!("Move preparation was interrupted; source retained. Prepare Move again."),
                MovePhase::ResumingDestination if session.state == SessionState::Running => {
                    // Running is installed only after native readiness and the
                    // handoff. A crash before the next intent write is safe to
                    // advance, since restore started with an empty queue.
                    ensure!(Some(&session.last_profile) == operation.selection.profile_id.as_ref()
                        && Some(&session.target_template_id) == operation.selection.target_template_id.as_ref(),
                        "ready destination does not match the move intent");
                    operation.destination_target = session.target.clone();
                    operation.destination_native_session_id = session.native_session_id.clone();
                    operation.queue_admission_started = true;
                    operation.phase = MovePhase::StartingQueue;
                    crate::database::save_move_operation(&operation)?;
                    restore_move_queue_hold(&operation);
                    ensure!(!operation.cancellation_requested, "Move was cancelled; ready destination retained");
                    self.admit_move_queue(&mut operation, executor).await
                }
                MovePhase::ResumingDestination => {
                    let previous = operation.recovery_session.as_ref().context("move lacks its stopped recovery identity; retain resources for inspection")?;
                    // An in-place swap still owns the checkout the source was
                    // using, so the rollback retires it exactly as a resume
                    // that recreated one.
                    let error = self.rollback_failed_resume(&id, previous, operation.in_place,
                        anyhow::anyhow!("destination restoration was interrupted; checkpoint retained for an explicit retry"), executor)?;
                    Err(error)
                }
                MovePhase::ClosingSource => {
                    if matches!(session.state, SessionState::Closing | SessionState::Destroying) {
                        self.recover_move_source_stop(&mut operation, executor, manager).await?;
                    }
                    operation.checkpoint = self.state.sessions[&id].checkpoint.clone();
                    if self.state.sessions[&id].state == SessionState::Stopped && self.state.sessions[&id].target.is_some() {
                        self.cleanup_stopped_target(&id, executor)?;
                    }
                    bail!("{}", interrupted_source_stop_message(
                        "source stop was recovered; verified checkpoint retained. Retry move or Resume with previous settings",
                        operation.in_place,
                    ))
                }
                _ => bail!("Move requires an explicit retry after the daemon restarted"),
            }
        }.await;
        self.finish_move_result(&mut operation, result, executor)
    }

    async fn recover_move_source_stop(
        &mut self,
        operation: &mut MoveOperation,
        executor: &(impl CommandExecutor + Sync),
        manager: &SessionManagerControl,
    ) -> Result<()> {
        let id = operation.selection.session_id.clone();
        if self.state.sessions[&id].state == SessionState::Closing {
            self.prepare_move_source_checkpoint(&id, executor, manager, operation)
                .await?;
            let handle = manager
                .wait_for_session(&id, std::time::Duration::from_secs(5))
                .await?;
            let mut lease = handle.lease_connection().await?;
            let execution = lease.connection_mut().sync().await?.operational.execution;
            lease.release();
            if matches!(
                execution,
                mj_core::relay::RelayExecutionState::Idle
                    | mj_core::relay::RelayExecutionState::Running
            ) {
                if operation.cancellation_requested {
                    let record = self.state.sessions.get_mut(&id).unwrap();
                    record.state = SessionState::Running;
                    record.updated_at = now();
                    record.last_error =
                        Some("Move was cancelled before the source was sealed".into());
                    crate::database::save_lifecycle_session(record)?;
                } else {
                    // A recovered source stop always tears its target down: an
                    // interrupted in-place swap falls back to the fresh path.
                    self.suspend_session_for_move(
                        &id,
                        executor,
                        manager,
                        operation,
                        None,
                        SourceTargetDisposition::Destroy,
                    )
                    .await?;
                }
                return Ok(());
            }
        }
        // A move's source stop was admitted by the move itself.
        self.recover_interrupted_close_managed(&id, executor, manager, true, None)
            .await?;
        Ok(())
    }

    async fn execute_move(
        &mut self,
        operation: &mut MoveOperation,
        preparation: Option<&MovePreparation>,
        executor: &(impl CommandExecutor + Sync),
        manager: &SessionManagerControl,
    ) -> Result<()> {
        let id = operation.selection.session_id.clone();
        ensure!(
            !executor.cancellation_requested(),
            "move cancelled before source interruption"
        );
        if !operation.queue_admission_started {
            if self.state.sessions[&id].state == SessionState::Error
                && let Some(previous) = operation.recovery_session.as_ref()
            {
                // A prior failed teardown retains its exact partial checkout.
                // Restore source identity only after that owner is stopped.
                let failure = self.rollback_failed_resume(
                    &id,
                    previous,
                    false,
                    anyhow::anyhow!("clean up the partial Move destination before retry"),
                    executor,
                )?;
                ensure!(
                    self.state.sessions[&id].state == SessionState::Stopped,
                    "{failure:#}"
                );
            }
            let state = self.state.sessions[&id].state;
            if matches!(state, SessionState::Closing | SessionState::Destroying) {
                self.recover_move_source_stop(operation, executor, manager)
                    .await?;
                operation.checkpoint = self.state.sessions[&id].checkpoint.clone();
            } else if matches!(state, SessionState::Running | SessionState::Disconnected)
                && operation.destination_target.is_none()
            {
                executor.notify_notice("Stopping source");
                let _timing = MovePhaseTimer::new(&id, "checkpoint and source stop");
                operation.phase = MovePhase::ClosingSource;
                operation.updated_at = now();
                crate::database::save_move_operation(operation)?;
                // An eligible move keeps its environment: the close stops at
                // the sealed relay and the record keeps its target for
                // `restore_session_in_place`.
                let disposition = if operation.in_place {
                    SourceTargetDisposition::RetainForInPlaceSwap
                } else {
                    SourceTargetDisposition::Destroy
                };
                self.suspend_session_for_move(
                    &id,
                    executor,
                    manager,
                    operation,
                    preparation,
                    disposition,
                )
                .await?;
            }
            // An in-place move never reaches `Stopped` with a target: its
            // source stays `Closing` in the environment the destination reuses.
            if !operation.in_place
                && self.state.sessions[&id].state == SessionState::Stopped
                && self.state.sessions[&id].target.is_some()
            {
                executor.notify_notice("Cleaning up source");
                let _timing = MovePhaseTimer::new(&id, "source storage cleanup");
                self.cleanup_stopped_target(&id, executor)?;
            }
            operation.checkpoint = operation
                .checkpoint
                .clone()
                .or_else(|| self.state.sessions[&id].checkpoint.clone());
            ensure!(
                operation.checkpoint.is_some(),
                "move has no verified checkpoint"
            );
            ensure!(
                !executor.cancellation_requested(),
                "move cancelled after source teardown; session is stopped"
            );
            operation.phase = MovePhase::ResumingDestination;
            operation.recovery_session = Some(self.state.sessions[&id].clone());
            operation.updated_at = now();
            crate::database::save_move_operation(operation)?;
            executor.notify_notice("Preparing destination");
            if operation.in_place {
                // The environment is kept, so there is nothing to provision and
                // no allocation to clear: eligibility already required the
                // allocation to be unchanged.
                self.restore_session_in_place(
                    &id,
                    operation.selection.profile_id.as_deref().unwrap(),
                    executor,
                )
                .await?;
            } else {
                if operation.selection.clear_resource_allocation {
                    let session = self.state.sessions.get_mut(&id).unwrap();
                    session.resource_allocation = None;
                    session.container_cpus = None;
                    session.container_memory = None;
                    crate::database::save_session(session)?;
                }
                self.resume_session_controlled(
                    &id,
                    operation.selection.profile_id.as_deref().unwrap(),
                    operation.selection.target_template_id.as_deref().unwrap(),
                    SessionResumeOptions {
                        additional_mounts: operation.selection.additional_mounts.clone(),
                        resource_allocation: operation.selection.resource_allocation.clone(),
                        discard_queue: true,
                    },
                    executor,
                )
                .await?;
            }
            let destination = &self.state.sessions[&id];
            operation.destination_target = destination.target.clone();
            operation.destination_native_session_id = destination.native_session_id.clone();
            // Persist readiness before submitting even the first queued command.
            operation.phase = MovePhase::StartingQueue;
            operation.queue_admission_started = true;
            operation.updated_at = now();
            crate::database::save_move_operation(operation)?;
        }
        restore_move_queue_hold(operation);
        self.admit_move_queue(operation, executor).await
    }

    async fn admit_move_queue(
        &self,
        operation: &mut MoveOperation,
        executor: &(impl CommandExecutor + Sync),
    ) -> Result<()> {
        let timing_id = operation.selection.session_id.clone();
        let _timing = MovePhaseTimer::new(&timing_id, "queue admission");
        let id = &operation.selection.session_id;
        let mut relay = {
            let _checking_destination =
                ProvisionStageGuard::new(executor, ProvisionStage::Verifying);
            let destination = &self.state.sessions[id];
            ensure!(
                destination.state == SessionState::Running
                    && destination.target == operation.destination_target
                    && destination.native_session_id == operation.destination_native_session_id,
                "cannot prove the same ready destination; refusing to replay potentially executed work"
            );
            let spec = self.reconnect_command(id)?;
            let relay = StandaloneSession::connect_command(&spec, id).await?;
            let store_id = relay.snapshot().operational.store_id.context("destination worker does not expose its durable store identity; upgrade the worker before admitting queued work")?;
            if let Some(expected) = &operation.destination_store_id {
                ensure!(
                    *expected == store_id,
                    "destination relay storage was replaced; refusing to replay potentially executed work"
                );
            } else {
                // No command can be admitted until this identity is durable.
                operation.destination_store_id = Some(store_id);
                crate::database::save_move_operation(operation)?;
            }
            ensure!(
                relay.snapshot().operational.native_session_id
                    == operation.destination_native_session_id,
                "destination relay native identity changed; refusing queue replay"
            );
            relay
        };
        if operation.queue == ResumeQueueDisposition::Start && !operation.queue_admission_finished {
            let _starting_queue = ProvisionStageGuard::new(executor, ProvisionStage::Starting);
            executor.notify_notice("Starting queued work");
            let checkpoint = operation
                .checkpoint
                .as_ref()
                .context("move queue archive is missing")?;
            let verified = verify_archive_streaming(&checkpoint.archive_path)?;
            ensure!(
                verified.archive_sha256 == checkpoint.sha256 && verified.manifest.session.id == *id,
                "move queue checkpoint verification failed"
            );
            for queued in verified.canonical_session.queued_prompts {
                ensure!(
                    !executor.cancellation_requested(),
                    "move cancelled during queue admission; destination retained"
                );
                let command = match queued.kind {
                    CanonicalQueuedCommandKind::Prompt => RelayCommand::Prompt {
                        prompt: queued
                            .content
                            .into_iter()
                            .map(serde_json::from_value)
                            .collect::<serde_json::Result<_>>()?,
                    },
                    CanonicalQueuedCommandKind::SetConfig { key, value } => {
                        RelayCommand::SetConfig { key, value }
                    }
                };
                relay.submit(queued.command_id, command).await?;
            }
        }
        operation.queue_admission_finished = true;
        crate::database::save_move_operation(operation)?;
        restore_move_queue_hold(operation);
        let queue_sentence = if operation.queue == ResumeQueueDisposition::Discard {
            "Queued work was discarded; ready and idle."
        } else {
            "Queued work was accepted."
        };
        let source_profile = &operation.source_profile_id;
        let source_target = &operation.source_target_template_id;
        let destination_profile = operation.selection.profile_id.as_deref().unwrap();
        let destination_target = operation.selection.target_template_id.as_deref().unwrap();
        // The two moves are different events for the person reading the
        // conversation: one rebuilt the environment, the other kept it.
        let text = if operation.in_place {
            format!(
                "Switched from {source_profile} / {source_target} to {destination_profile} / {destination_target} in place; the workspace and environment were kept. {queue_sentence} The interrupted prompt was not replayed."
            )
        } else {
            format!(
                "Moved from {source_profile} / {source_target} to {destination_profile} / {destination_target} in a fresh environment. {queue_sentence} The interrupted prompt was not replayed."
            )
        };
        relay
            .submit(
                format!("{}-notice", operation.operation_id),
                RelayCommand::RecordNotice { text },
            )
            .await?;
        Ok(())
    }

    pub(super) fn validate_move_checkpoint(
        &self,
        operation: &MoveOperation,
        preparation: Option<&MovePreparation>,
        executor: &(impl CommandExecutor + Sync),
    ) -> Result<()> {
        let _verifying = ProvisionStageGuard::new(executor, ProvisionStage::Verifying);
        let current = Controller {
            config: mj_core::config::Config::load()?,
            state: self.state.clone(),
        };
        ensure!(
            current.move_configuration_fingerprint(&operation.selection)?
                == operation.configuration_fingerprint,
            "destination configuration changed during move"
        );
        let id = &operation.selection.session_id;
        current.validate_move_destination_paths(
            &self.state.sessions[id],
            operation.selection.target_template_id.as_deref().unwrap(),
            executor,
        )?;
        if let super::ResumeRepositorySourcePreflight::RepositoryMoved(mismatch) = self
            .preflight_resume_repository_sources(
                id,
                operation.selection.target_template_id.as_deref().unwrap(),
                executor,
            )?
        {
            bail!(
                "destination repository source is missing checkpoint commit {}; source retained",
                mismatch.missing_commit
            );
        }
        if let Some(prepared) = preparation {
            let checkpoint = self.state.sessions[id]
                .checkpoint
                .as_ref()
                .context("no move checkpoint")?;
            let verified = verify_archive_streaming(&checkpoint.archive_path)?;
            let actual: Vec<_> = verified
                .canonical_session
                .queued_prompts
                .iter()
                .map(|p| p.command_id.as_str())
                .collect();
            let expected: Vec<_> = prepared
                .queued_commands
                .iter()
                .map(|p| p.command_id.as_str())
                .collect();
            ensure!(
                actual == expected,
                "pending queue changed before checkpoint capture; source retained, confirm Move again"
            );
        }
        Ok(())
    }
}

fn validate_preserved_configuration(
    profile_id: &str,
    accepted: &mj_core::acp::AcceptedSessionConfig,
    choices: &mj_core::worker_launch::ProfileConfig,
) -> Result<()> {
    for (key, value, offered) in [
        ("model", accepted.model.as_deref(), &choices.models),
        ("effort", accepted.effort.as_deref(), &choices.efforts),
    ] {
        let Some(value) = value else { continue };
        ensure!(
            offered.iter().any(|choice| choice.value == value),
            "destination profile {profile_id:?} does not offer the session's accepted {key} {value:?}; choices: {}",
            offered
                .iter()
                .map(|choice| choice.value.as_str())
                .collect::<Vec<_>>()
                .join(", ")
        );
    }
    Ok(())
}

/// Whether this move can replace only the harness inside the source target.
///
/// The environment is kept only when nothing about it changes: the same target
/// template, the same attached mounts, and the same resource allocation. A
/// retry starts from a torn-down or unknown source, and a sub-agent never owns
/// its own target, so both take the full fresh-environment path.
pub(super) fn in_place_move_eligible(
    source: &mj_core::state::SessionRecord,
    selection: &MoveSelection,
    is_subagent: bool,
    retry: bool,
) -> bool {
    !retry
        && !is_subagent
        && source.target.is_some()
        && matches!(
            source.state,
            SessionState::Running | SessionState::Disconnected
        )
        && Some(&source.target_template_id) == selection.target_template_id.as_ref()
        && Some(&source.additional_mounts) == selection.additional_mounts.as_ref()
        && source.resource_allocation == selection.resource_allocation
        && !selection.clear_resource_allocation
}

fn outcome(
    operation_id: &str,
    selection: &MoveSelection,
    status: &str,
    error: Option<String>,
    recovery: Option<String>,
) -> MoveOutcome {
    MoveOutcome {
        operation_id: operation_id.into(),
        session_id: selection.session_id.clone(),
        profile_id: selection.profile_id.clone().unwrap_or_default(),
        target_template_id: selection.target_template_id.clone().unwrap_or_default(),
        outcome: status.into(),
        error,
        recovery,
    }
}