mj_controller/controller/worker_binary/

launch.rs

use super::*;

fn disable_mbx_cache_shims(
    session_id: &str,
    backend: &targets::TargetLocator,
    worker_root: &str,
    executor: &impl CommandExecutor,
    reason: &str,
) {
    let cleanup = remove_generated_mbx_shims(executor, backend, worker_root);
    if let Err(error) = &cleanup {
        tracing::warn!(
            session_id,
            "could not remove marked shared-mbx launchers: {error:#}"
        );
    }
    let cleanup_note = cleanup
        .err()
        .map(|error| format!(" Mjolnir could not remove its marked launchers: {error:#}."))
        .unwrap_or_default();
    tracing::warn!(
        session_id,
        "shared mbx is unavailable in this container: {reason}"
    );
    executor.notify_notice(&format!(
        "The Rust build cache is unavailable in this container: {reason}.{cleanup_note} The session will start without it."
    ));
}

fn build_cache_config_roots(launch: &WorkerLaunchConfig) -> Vec<PathBuf> {
    [&launch.target_environment, &launch.environment]
        .into_iter()
        .filter_map(|environment| environment.get("XDG_CONFIG_HOME").map(PathBuf::from))
        .collect::<std::collections::BTreeSet<_>>()
        .into_iter()
        .collect()
}

impl Controller {
    /// Where this session's worker lives. This is decided from the session
    /// record and configuration alone, so a caller can name the worker root
    /// before anything is installed into it.
    pub(in crate::controller) fn worker_placement(
        &self,
        session_id: &str,
    ) -> Result<(targets::TargetLocator, String)> {
        let session = self
            .state
            .sessions
            .get(session_id)
            .with_context(|| format!("unknown session {session_id}"))?;
        let locator = session
            .target
            .as_ref()
            .context("session target is missing")?;
        if let Some(owner) = crate::worker_lifecycle::current(session_id) {
            owner.verify_target(locator)?;
        }
        let backend = backend_locator(locator, session, &self.config)?;
        let worker_root = targets::worker_root(&backend, session_id)?;
        Ok((backend, worker_root))
    }

    pub(in crate::controller) fn prepare_worker_files(
        &self,
        session_id: &str,
        backend: &targets::TargetLocator,
        worker_root: &str,
        executor: &impl CommandExecutor,
    ) -> Result<()> {
        let owner = crate::worker_lifecycle::require(session_id)?;
        let session = self
            .state
            .sessions
            .get(session_id)
            .with_context(|| format!("unknown session {session_id}"))?;
        if let Some(target) = session.target.as_ref() {
            owner.verify_target(target)?;
        }
        let profile = self
            .config
            .profiles
            .get(&session.last_profile)
            .context("session profile is missing")?;
        profile.ensure_ready(&session.last_profile)?;
        let (mut launch, project_memory, target_profile_home) =
            self.session_launch_config(session_id, backend)?;

        if session.native_session_id.is_some()
            && profile.kind == mj_core::config::HarnessKind::Codex
        {
            launch.goal_resume_request = Some(mj_core::state::new_session_id()?);
        }
        let staging = tempfile::tempdir().context("create worker staging directory")?;
        let launch_path = staging.path().join("launch.json");
        launch.write(&launch_path)?;
        let ownership_path = staging.path().join("ownership.json");
        WorkerOwnership {
            version: WorkerOwnership::VERSION,
            workspace_id: session.workspace_id.clone(),
            session_id: session_id.to_string(),
            profile_id: session.last_profile.clone(),
            bundle_id: session.bundle_id.clone(),
            target_template_id: session.target_template_id.clone(),
            instance_id: Some(mj_core::config::instance_identity()),
        }
        .write(&ownership_path)?;
        // Every session runs from a staged copy of its profile, on every target,
        // so `target_profile_home` is always a home the session owns and the
        // stage is always installed there.
        let profile_stage = staging.path().join("profile");
        let started = Instant::now();
        let result = stage_profile(profile, &profile_stage);
        tracing::debug!(
            session_id,
            elapsed_ms = started.elapsed().as_millis(),
            "profile staging completed"
        );
        result?;
        stage_managed_skills(
            profile.kind,
            &profile_stage,
            session
                .target
                .as_ref()
                .context("session target is missing")?
                .skills_scope(),
        )?;
        stage_codex_catalog(
            &session.last_profile,
            profile,
            &profile_stage,
            &fetch_catalog_over_https,
            &SharedCatalogCache,
        )?;
        append_hel_target_environment(profile.kind, &profile_stage, backend)?;
        append_container_storage_guidance(
            profile.kind,
            &profile_stage,
            backend,
            session.container_workspace.as_deref(),
            targets::has_managed_temporary_volume(backend, executor)?,
        )?;
        append_subagent_policy(
            profile.kind,
            &profile_stage,
            &launch.subagents,
            self.config.subagents.max_concurrent,
        )?;
        apply_staged_execution_setting(profile.kind, launch.execution_policy, &profile_stage)?;
        if profile.kind == mj_core::config::HarnessKind::Claude {
            configure_claude_mailbox_hook(
                &profile_stage,
                worker_root,
                launch.agent_mailboxes_enabled,
            )?;
            configure_claude_subagent_mcp(
                &profile_stage,
                worker_root,
                launch.subagent_mcp_role(),
                launch.agent_mailboxes_enabled,
            )?;
        }
        // A session without project memory gets no replica, no baseline and
        // no history server: nothing of the workspace's memory reaches it.
        if let Some(project_memory) = &project_memory {
            stage_memory_replica(
                project_memory,
                Path::new(&target_profile_home),
                &profile_stage,
            )?;
            if project_memory.mcp_delivery == ProjectMemoryMcpDelivery::HarnessProfile {
                configure_kimi_history_mcp(
                    &profile_stage,
                    worker_root,
                    project_memory.history_socket.as_deref(),
                )?;
            }
        }
        let worker_binary = worker_binary_for(backend, executor)?;

        install_worker_files(
            executor,
            backend,
            session_id,
            worker_root,
            &target_profile_home,
            &worker_binary,
            &launch_path,
            &ownership_path,
            &profile_stage,
            shared_profile_login(profile, backend).as_ref(),
        )?;
        if session.build_cache.is_some() {
            self.install_build_cache_shim(session, backend, &launch, executor)
                .context("install shared machine build cache configuration")?;
        }
        prepare_installed_managed_harness(executor, backend, worker_root, &launch)
    }

    /// Refresh and verify the shared-cache copy, then install marked launchers
    /// in the session's `bin` directory on the worker PATH.
    pub(in crate::controller) fn install_build_cache_shim(
        &self,
        session: &mj_core::state::SessionRecord,
        backend: &targets::TargetLocator,
        launch: &WorkerLaunchConfig,
        executor: &impl CommandExecutor,
    ) -> Result<()> {
        let Some(cache) = session.build_cache.as_ref() else {
            return Ok(());
        };
        let worker_root = targets::worker_root(backend, &session.id)?;
        let config_roots = build_cache_config_roots(launch);
        let configuration = mj_core::config::build_cache_configuration_directory(&cache.directory);
        if link_legacy_mbx_configuration(
            executor,
            backend,
            &worker_root,
            &configuration,
            &config_roots,
        )? {
            return Ok(());
        }
        let binary = match crate::controller::mbx::sync_mbx_binary_for_container(
            backend,
            &cache.directory,
            executor,
        ) {
            Ok(crate::controller::mbx::CachedMbxSync::Ready(binary)) => binary,
            Ok(crate::controller::mbx::CachedMbxSync::Unavailable(reason)) => {
                disable_mbx_cache_shims(&session.id, backend, &worker_root, executor, &reason);
                return Ok(());
            }
            Err(error) => {
                disable_mbx_cache_shims(
                    &session.id,
                    backend,
                    &worker_root,
                    executor,
                    &format!("{error:#}"),
                );
                return Ok(());
            }
        };
        if let Err(error) = verify_mbx_binary(executor, backend, &binary.path, &binary.version) {
            disable_mbx_cache_shims(
                &session.id,
                backend,
                &worker_root,
                executor,
                &format!("{error:#}"),
            );
            return Ok(());
        }
        let (configuration, config_roots) =
            self.build_cache_configuration(session, backend, launch, executor)?;
        install_mbx_shims(
            executor,
            backend,
            &worker_root,
            &binary.path,
            &configuration,
            &config_roots,
        )
    }

    pub(in crate::controller) fn prepare_build_cache_links(
        &self,
        session: &mj_core::state::SessionRecord,
        backend: &targets::TargetLocator,
        launch: &WorkerLaunchConfig,
        executor: &impl CommandExecutor,
    ) -> Result<()> {
        self.install_build_cache_shim(session, backend, launch, executor)
    }

    fn build_cache_configuration(
        &self,
        session: &mj_core::state::SessionRecord,
        backend: &targets::TargetLocator,
        launch: &WorkerLaunchConfig,
        executor: &impl CommandExecutor,
    ) -> Result<(PathBuf, Vec<PathBuf>)> {
        let configuration = crate::controller::mbx::prepare_session_configuration(
            &self.config,
            backend,
            session
                .build_cache
                .as_ref()
                .context("session has no build cache")?,
            executor,
        )?;
        let config_roots = build_cache_config_roots(launch);
        Ok((configuration, config_roots))
    }

    /// Probe the installed binary and the worker's recorded state after a
    /// session becomes unreachable. Returns `None` only when the session has
    /// no target to probe; a probe that fails says why.
    pub fn diagnose_worker(&self, session_id: &str) -> Option<String> {
        self.diagnose_worker_controlled(session_id, &crate::targets::ProcessExecutor)
    }

    pub fn diagnose_worker_controlled(
        &self,
        session_id: &str,
        executor: &impl CommandExecutor,
    ) -> Option<String> {
        let session = self.state.sessions.get(session_id)?;
        let locator = session.target.as_ref()?;
        let backend = match backend_locator(locator, session, &self.config) {
            Ok(backend) => backend,
            Err(error) => {
                tracing::debug!(
                    session_id,
                    error = format!("{error:#}"),
                    "could not construct a worker diagnostic probe"
                );
                return None;
            }
        };
        let worker_root = match targets::worker_root(&backend, session_id) {
            Ok(root) => root,
            Err(error) => {
                tracing::debug!(
                    session_id,
                    error = format!("{error:#}"),
                    "could not derive the worker diagnostic root"
                );
                return None;
            }
        };
        let binary_failure = worker_binary_probe_failure(executor, &backend, &worker_root);
        let probe = match probe_worker(executor, &backend, &worker_root) {
            Ok(probe) => probe.to_string(),
            Err(error) => format!("the worker could not be probed: {error:#}"),
        };
        Some(match binary_failure {
            Some(binary_failure) => format!("{binary_failure}; {probe}"),
            None => probe,
        })
    }

    /// A non-destructive liveness probe plus commands that replace a confirmed
    /// dead session worker without touching its durable relay files. The
    /// session manager runs both off its async actor.
    pub fn worker_recovery_plan(
        &self,
        session_id: &str,
        operation: Option<&mj_core::state::MoveOperation>,
    ) -> Result<WorkerRecoveryPlan> {
        let (backend, worker_root) = self.worker_placement(session_id)?;
        let launch = self.worker_launch_config_for_move(session_id, &backend, operation)?;
        let workspace = worker_workspace_for_recovery(&backend, &launch.cwd);
        Ok(WorkerRecoveryPlan {
            source_target: self.state.sessions[session_id]
                .target
                .clone()
                .context("session target is missing")?,
            target: targets::target_recovery_plan(&backend, session_id)?,
            workspace,
            liveness_probe: worker_liveness_command(&backend, &worker_root),
            exit_record: Some(worker_exit_record_command(&backend, &worker_root)),
            binary_refresh: worker_binary_refresh_plan(&backend, session_id)?,
            launch_refresh: Some(worker_launch_refresh_plan(&backend, session_id, &launch)?),
            restart: CommandPlan {
                description: format!("restart Mjolnir worker for session {session_id}"),
                commands: vec![
                    stop_worker_command(&backend, &worker_root),
                    start_worker_command(&backend, &worker_root),
                ],
            },
        })
    }

    /// The launch config for a session, including what depends on its
    /// sub-agent role. The first launch and every relaunch use this, so a
    /// relaunched worker keeps its delegation tools and a relaunched child
    /// keeps its parent's workspace.
    fn session_launch_config(
        &self,
        session_id: &str,
        backend: &targets::TargetLocator,
    ) -> Result<(
        WorkerLaunchConfig,
        Option<ProjectMemoryLaunchConfig>,
        String,
    )> {
        let session = self
            .state
            .sessions
            .get(session_id)
            .with_context(|| format!("unknown session {session_id}"))?;
        session.validate_configuration(&self.config)?;
        let profile = self
            .config
            .profiles
            .get(&session.last_profile)
            .context("session profile is missing")?;
        let checkout = self.state.checkout(session_id)?;
        let bundle = checkout
            .project_directory()
            .is_none()
            .then(|| session.project_bundle(&self.config))
            .flatten();
        let target = session.target_runtime_settings(&self.config)?;
        let subagent = self.state.subagents.get(session_id);
        // A sub-agent child shares its parent's container, so it works in the
        // parent's workspace. The parent record is authoritative for that path.
        let (workspace_session_id, workspace_container) = match subagent.as_ref() {
            Some(child) => {
                let parent = self
                    .state
                    .sessions
                    .get(&child.parent_session_id)
                    .context("sub-agent parent session is missing")?;
                (parent.id.clone(), parent.container_workspace.clone())
            }
            None => (session_id.to_owned(), session.container_workspace.clone()),
        };
        let (mut launch, project_memory, target_profile_home) = worker_launch_config_with_checkout(
            session,
            &checkout,
            profile,
            bundle,
            backend,
            LaunchWorkspace {
                session_id: &workspace_session_id,
                container: workspace_container.as_deref(),
                parent_worktree: self.subagent_parent_worktree(session_id),
            },
            &target,
        )?;
        if subagent.is_some() {
            launch.environment.insert(
                mj_core::worker_launch::SESSION_MANAGED_SUBAGENT_ENV.into(),
                "1".into(),
            );
            launch
                .environment
                .remove(mj_core::worker_launch::SESSION_MESSAGE_MCP_ENV);
        } else {
            launch
                .environment
                .remove(mj_core::worker_launch::SESSION_MANAGED_SUBAGENT_ENV);
            // This controller stages the message-only registration for every
            // top-level session; the worker trusts only this marker.
            launch.environment.insert(
                mj_core::worker_launch::SESSION_MESSAGE_MCP_ENV.into(),
                "1".into(),
            );
        }
        apply_jev_switch(&mut launch, self.config.jev.enabled);
        apply_continuation_switch(&mut launch, self.config.automatic_continuation_enabled());
        launch.agent_mailboxes_enabled = self.config.agent_mailboxes_enabled_for(session);
        launch.subagents = session
            .subagents
            .clone()
            .unwrap_or_default()
            .for_launch(profile.kind, subagent.is_some());
        // Registration decided whether this child can be given the tool.
        launch.handback_tool = subagent.as_ref().is_some_and(|child| child.handback_tool);
        // The child's harness opens on its spawn model instead of switching
        // to it from the profile default before the first turn (issue 1217).
        launch.initial_model = subagent.as_ref().and_then(|child| child.model.clone());
        // Capturing the working tree is only ever useful to a turn review, so
        // it is spent only on a session a review can run for: one whose
        // configuration has an eligible reviewer, and that is not a child. A child
        // works in its parent's tree, and reviewing it would report the
        // parent's work as the child's.
        launch.review_capture =
            mj_core::review::settings::can_review(&self.config) && subagent.is_none();
        if let Some(subagent) = &subagent {
            let parent = self
                .state
                .sessions
                .get(&subagent.parent_session_id)
                .context("sub-agent parent session is missing")?;
            let parent_profile = self
                .config
                .profiles
                .get(&parent.last_profile)
                .context("sub-agent parent profile is missing")?;
            let parent_target = parent.target_runtime_settings(&self.config)?;
            let parent_locator = parent
                .target
                .as_ref()
                .context("sub-agent parent has no live target")?;
            let parent_backend = backend_locator(parent_locator, parent, &self.config)?;
            let parent_checkout = self.state.checkout(&parent.id)?;
            let parent_bundle = parent_checkout
                .project_directory()
                .is_none()
                .then(|| parent.project_bundle(&self.config))
                .flatten();
            let (parent_launch, _, _) = worker_launch_config_with_checkout(
                parent,
                &parent_checkout,
                parent_profile,
                parent_bundle,
                &parent_backend,
                LaunchWorkspace {
                    session_id: &parent.id,
                    container: parent.container_workspace.as_deref(),
                    parent_worktree: None,
                },
                &parent_target,
            )?;
            launch.cwd = if subagent.working_directory.as_os_str().is_empty() {
                parent_launch.cwd
            } else {
                parent_launch.cwd.join(&subagent.working_directory)
            };
            launch.additional_directories = parent_launch.additional_directories;
        }
        Ok((launch, project_memory, target_profile_home))
    }

    pub(in crate::controller) fn current_worker_launch_config(
        &self,
        session_id: &str,
        backend: &targets::TargetLocator,
    ) -> Result<WorkerLaunchConfig> {
        let operation = crate::database::load_move_operation(session_id)?;
        self.worker_launch_config_for_move(session_id, backend, operation.as_ref())
    }

    fn worker_launch_config_for_move(
        &self,
        session_id: &str,
        backend: &targets::TargetLocator,
        operation: Option<&mj_core::state::MoveOperation>,
    ) -> Result<WorkerLaunchConfig> {
        let session = self
            .state
            .sessions
            .get(session_id)
            .with_context(|| format!("unknown session {session_id}"))?;
        let (mut launch, _, _) = self.session_launch_config(session_id, backend)?;
        if operation.is_some_and(|operation| {
            operation.source_checkpoint_only
                && operation.destination_target.is_none()
                && matches!(
                    operation.phase,
                    mj_core::state::MovePhase::Preparing
                        | mj_core::state::MovePhase::ClosingSource
                        | mj_core::state::MovePhase::Failed
                        | mj_core::state::MovePhase::Cancelled
                )
                && session.last_profile == operation.source_profile_id
                && session.target == operation.source_target
                && matches!(
                    session.state,
                    mj_core::state::SessionState::Running
                        | mj_core::state::SessionState::Disconnected
                        | mj_core::state::SessionState::Closing
                )
        }) {
            launch.run_mode = mj_core::worker_launch::WorkerRunMode::CheckpointOnly;
        }
        Ok(launch)
    }

    /// Where the session's project memory is synchronized, or `None` for a
    /// session that has none.
    pub fn project_memory_sync_target(
        &self,
        session_id: &str,
    ) -> Result<Option<ProjectMemorySyncTarget>> {
        let session = self
            .state
            .sessions
            .get(session_id)
            .with_context(|| format!("unknown session {session_id}"))?;
        if session.no_project_memory {
            return Ok(None);
        }
        session.validate_configuration(&self.config)?;
        let locator = session
            .target
            .as_ref()
            .context("session target is missing")?;
        let backend = backend_locator(locator, session, &self.config)?;
        let profile = self
            .config
            .profiles
            .get(&session.last_profile)
            .context("session profile is missing")?;
        let checkout = self.state.checkout(session_id)?;
        let bundle = checkout
            .project_directory()
            .is_none()
            .then(|| session.project_bundle(&self.config))
            .flatten();
        let workspace = if let Some(project_directory) = checkout.project_directory() {
            (project_directory.to_string_lossy().into_owned(), Vec::new())
        } else {
            workspace_paths(
                &backend,
                bundle.context("session bundle is missing")?,
                session_id,
                session.container_workspace.as_deref(),
            )?
        };
        let target_home = target_profile_home(&backend, session_id, profile);
        let launch = project_memory_launch(
            session,
            bundle,
            &workspace,
            &target_home,
            self.subagent_parent_worktree(session_id),
        )?;
        Ok(Some(ProjectMemorySyncTarget {
            canonical_root: canonical_memory_root(&launch.project_key),
        }))
    }
}

/// Carries `[jev] enabled = false` to the worker, which reads it from its
/// launch environment, and keeps the Jev key out of the worker and the
/// harness so nothing can reach the service.
pub(super) fn apply_jev_switch(launch: &mut WorkerLaunchConfig, enabled: bool) {
    if enabled {
        return;
    }
    for environment in [&mut launch.target_environment, &mut launch.environment] {
        environment.remove("TYPESAFE_API_KEY");
        environment.insert(
            mj_core::jev::DISABLED_ENVIRONMENT.to_owned(),
            "1".to_owned(),
        );
    }
}

/// Tell the worker when nobody will act on a `Continue` verdict, so it does
/// not park the assessment as deferred. Travels like the Jev switch.
pub(super) fn apply_continuation_switch(launch: &mut WorkerLaunchConfig, enabled: bool) {
    if enabled {
        return;
    }
    for environment in [&mut launch.target_environment, &mut launch.environment] {
        environment.insert(
            mj_core::jev::CONTINUATION_DISABLED_ENVIRONMENT.to_owned(),
            "1".to_owned(),
        );
    }
}

/// Whether this session gets Mjolnir's delegation tools in place of its
/// harness's own. The session's stored choice governs; `None` means native
/// sub-agents, so a session created before the per-session choice existed (or
/// through `mj new` with neither flag given) gets its harness's own
/// sub-agents. A child never gets them, and only Claude and Codex can receive
/// them at all.
#[cfg(test)]
pub(super) fn subagent_tools_enabled(
    session: &mj_core::state::SessionRecord,
    is_child: bool,
) -> bool {
    session
        .subagents
        .clone()
        .unwrap_or_default()
        .for_launch(session.harness_kind, is_child)
        .uses_mjolnir()
}

pub(super) fn worker_workspace_for_recovery(
    backend: &targets::TargetLocator,
    directory: &Path,
) -> Option<WorkerWorkspace> {
    let target = match backend {
        targets::TargetLocator::LocalBare { .. } => mj_core::state::ManagedWorktreeTarget::Local,
        targets::TargetLocator::SshBare { ssh, .. } => mj_core::state::ManagedWorktreeTarget::Ssh {
            destination: ssh.destination.clone(),
            ssh_args: ssh.ssh_args.clone(),
        },
        targets::TargetLocator::LocalPodman { .. }
        | targets::TargetLocator::LocalDocker { .. }
        | targets::TargetLocator::AppleContainer { .. }
        | targets::TargetLocator::AwsEc2 { .. }
        | targets::TargetLocator::SshPodman { .. }
        | targets::TargetLocator::SshDocker { .. } => return None,
    };
    Some(WorkerWorkspace {
        target,
        directory: directory.to_path_buf(),
    })
}

pub(super) struct LaunchWorkspace<'a> {
    pub session_id: &'a str,
    pub container: Option<&'a Path>,
    pub parent_worktree: Option<&'a mj_core::state::ManagedWorktree>,
}

#[cfg(test)]
pub(super) fn worker_launch_config(
    session: &mj_core::state::SessionRecord,
    profile: &mj_core::config::HarnessProfile,
    bundle: Option<&ProjectBundle>,
    backend: &targets::TargetLocator,
    worker_workspace: LaunchWorkspace<'_>,
    target: &mj_core::state::TargetRuntimeSettings,
) -> Result<(
    WorkerLaunchConfig,
    Option<ProjectMemoryLaunchConfig>,
    String,
)> {
    worker_launch_config_with_checkout(
        session,
        &session.checkout(),
        profile,
        bundle,
        backend,
        worker_workspace,
        target,
    )
}

pub(super) fn worker_launch_config_with_checkout(
    session: &mj_core::state::SessionRecord,
    checkout: &mj_core::state::Checkout<'_>,
    profile: &mj_core::config::HarnessProfile,
    bundle: Option<&ProjectBundle>,
    backend: &targets::TargetLocator,
    worker_workspace: LaunchWorkspace<'_>,
    target: &mj_core::state::TargetRuntimeSettings,
) -> Result<(
    WorkerLaunchConfig,
    Option<ProjectMemoryLaunchConfig>,
    String,
)> {
    let session_id = session.id.as_str();
    let execution_policy = target.execution_policy;
    let target_profile_home = target_profile_home(backend, session_id, profile);
    let workspace = if let Some(project_directory) = checkout.project_directory() {
        (project_directory.to_string_lossy().into_owned(), Vec::new())
    } else {
        workspace_paths(
            backend,
            bundle.context("session bundle is missing")?,
            worker_workspace.session_id,
            worker_workspace.container,
        )?
    };
    let mut additional_directories = workspace.1.iter().map(PathBuf::from).collect::<Vec<_>>();
    additional_directories.extend(
        session
            .additional_mounts
            .iter()
            .map(|resource| resource.destination.clone()),
    );
    if profile.kind == mj_core::config::HarnessKind::Muse && !additional_directories.is_empty() {
        bail!(
            "{} ACP does not support multiple workspace roots; use a single-repository bundle",
            profile.kind.display_name()
        );
    }
    let (bridge_command, bridge_args) = bridge_launch(profile.kind, execution_policy);
    let mut target_environment = target.environment.clone();
    let podman_container = backend.container_engine() == Some("podman");
    if podman_container {
        // Provisioning writes inherited settings to this file under the
        // container's configured home. A root Podman worker can have
        // HOME=/root, so the session Git config includes the file by path.
        target_environment.insert(
            mj_core::worker_launch::SESSION_GIT_CONFIG_INCLUDE_PATH.into(),
            "/home/hel/.gitconfig".into(),
        );
    }
    // The turn bounds are read by the worker process, which re-execs with a
    // cleared environment, so a value set for the daemon cannot reach it by
    // inheritance. Carry the two knobs explicitly when the daemon was started
    // with them, so shortening a timeout for a test works on every target and
    // not only on the container targets that can set it in configuration.
    // `RUST_LOG` travels the same way and for the same reason: a worker that
    // has gone quiet is diagnosed from its own log, and the log level cannot
    // be raised after the fact on a worker that re-execs with a cleared
    // environment.
    for name in [
        "MJ_TURN_STALL_TIMEOUT_MS",
        "MJ_TURN_TOOL_STALL_TIMEOUT_MS",
        "RUST_LOG",
    ] {
        if let Ok(value) = std::env::var(name) {
            target_environment.insert(name.to_owned(), value);
        }
    }
    // Resolve the daemon's local key before launching remote or container
    // workers, whose home directories do not contain its secrets file.
    if let Some(key) = mj_core::activity::verdict::api_key() {
        target_environment.insert("TYPESAFE_API_KEY".to_owned(), key);
    }
    // The build cache reaches the harness, its terminals, and the reviewer
    // sidecar, all of which run Cargo through the mbx shim.
    if let Some(build_cache) = &session.build_cache {
        target_environment.insert(
            "MBX_CACHE_DIR".into(),
            build_cache.directory.to_string_lossy().into_owned(),
        );
        target_environment.insert(
            "MJ_MBX_CONFIG_DIR".into(),
            mj_core::config::build_cache_configuration_directory(&build_cache.directory)
                .to_string_lossy()
                .into_owned(),
        );
        // Compiler symlinks name this worker's private executable. Sharing
        // them lets another container replace them with an unreachable path.
        target_environment.insert(
            "MBX_SHIMS_DIR".into(),
            Path::new(&targets::worker_root(backend, session_id)?)
                .join("mbx-shims")
                .to_string_lossy()
                .into_owned(),
        );
        // The per-build summary and savings lines are for a human at a
        // terminal; in a harness session they only add noise to Cargo output.
        target_environment.insert("MBX_SUMMARY".into(), "off".into());
        target_environment.insert("MBX_SAVINGS".into(), "off".into());
    }
    let mut environment = target_environment.clone();
    environment.extend(profile.environment.resolved().clone());
    // This ownership fact is generated by the controller, so a profile cannot
    // impersonate another session or turn a child into a top-level sender.
    environment.insert("MJ_SESSION_ID".into(), session_id.to_owned());
    if session
        .target
        .as_ref()
        .is_some_and(|target| target.skills_scope() == mj_core::skills::SkillsScope::Localhost)
    {
        // Harnesses clear their environment. Host CLI commands must still
        // address the daemon that created this session, including named instances.
        environment.insert(
            "MJ_CONFIG_DIR".into(),
            std::path::absolute(mj_core::config::config_dir())
                .context("resolve host Mjolnir configuration directory")?
                .to_string_lossy()
                .into_owned(),
        );
        environment.insert(
            "MJ_DATA_DIR".into(),
            std::path::absolute(data_dir())
                .context("resolve host Mjolnir data directory")?
                .to_string_lossy()
                .into_owned(),
        );
        if let Some(instance) = mj_core::config::instance_name() {
            environment.insert("MJ_INSTANCE".into(), instance);
        } else {
            environment.remove("MJ_INSTANCE");
        }
    }
    profile
        .kind
        .configure_home_environment(Path::new(&target_profile_home), &mut environment);
    profile
        .kind
        .configure_execution_environment(execution_policy, &mut environment)?;
    // The project's identity also keys the shared tool cache and names the
    // Claude project directory, so it is worked out for every session. Only
    // the memory launch config below depends on the session's choice.
    let mut project_memory = project_memory_launch(
        session,
        bundle,
        &workspace,
        &target_profile_home,
        worker_workspace.parent_worktree,
    )?;
    project_memory.mcp_delivery = project_memory_mcp_delivery(profile.kind, backend);
    project_memory.history_socket =
        Some(Path::new(&targets::worker_root(backend, &session.id)?).join("control.sock"));
    if let Some(cache) = &target.tool_cache {
        let private = Path::new(&targets::worker_root(backend, session_id)?).join("tool-cache");
        for (name, value) in [
            (
                "MJ_TOOL_CACHE_DIR",
                cache.directory.to_string_lossy().into_owned(),
            ),
            ("MJ_TOOL_CACHE_PROJECT", project_memory.project_key.clone()),
            ("MJ_TOOL_CACHE_HOME", private.to_string_lossy().into_owned()),
            (
                "MJ_NX_HOME_DIR",
                cache.nx_home.to_string_lossy().into_owned(),
            ),
        ] {
            target_environment.insert(name.into(), value.clone());
            environment.insert(name.into(), value);
        }
    }
    if profile.kind == mj_core::config::HarnessKind::Claude {
        environment.insert(
            "CLAUDE_CODE_PROJECT_DIR_NAME".into(),
            project_memory_replica_slug(&project_memory.project_key, session_id),
        );
        if session.no_project_memory {
            // Claude Code reads and offers its auto-memory directory unless
            // told not to. Set after the profile's own environment so the
            // session's choice wins.
            environment.insert(CLAUDE_DISABLE_AUTO_MEMORY_ENV.into(), "1".into());
        }
    }
    let project_memory = (!session.no_project_memory).then_some(project_memory);
    apply_claude_setup_token(
        &mut environment,
        profile.kind,
        &mj_core::credentials::claude_oauth_token_path(&session.last_profile),
    );
    let excluded_environment =
        exclude_harness_environment(&session.last_profile, profile, &mut environment);
    if podman_container && profile.kind == mj_core::config::HarnessKind::Claude {
        // Claude Code rejects bypassPermissions under uid 0 unless it is
        // told the process is already running in an isolated sandbox.
        // Podman container exec inherits HOME and the configured user from
        // the container, preserving both for stopped legacy sessions.
        environment.insert("IS_SANDBOX".into(), "1".into());
    }
    Ok((
        WorkerLaunchConfig {
            goal_resume_request: None,
            target_environment,
            seed_image_environment: backend.container_engine().is_some(),
            run_mode: Default::default(),
            session_id: session_id.to_string(),
            subagents: mj_core::subagent::SubagentPolicy::Native,
            handback_tool: false,
            agent_mailboxes_enabled: true,
            initial_model: None,
            review_capture: false,
            harness: profile.kind,
            harness_home: PathBuf::from(&target_profile_home),
            // The staged home mirrors the profile home, so the marker's path
            // within the profile home is the one the worker must check and
            // the credential sync must write. Kimi's is nested
            // (`credentials/kimi-code.json`); its file name alone named a file
            // at the top of the staged home that Kimi never reads.
            authentication_marker: profile
                .authentication_marker()
                .strip_prefix(&profile.home)
                .ok()
                .map(|name| name.to_string_lossy().into_owned()),
            bridge_command: PathBuf::from(bridge_command),
            bridge_args,
            harness_runtime: harness_runtime_policy(backend),
            environment,
            excluded_environment,
            cwd: PathBuf::from(&workspace.0),
            additional_directories,
            native_session_id: session.native_session_id.clone(),
            project_memory: project_memory.clone(),
            execution_policy,
        },
        project_memory,
        target_profile_home,
    ))
}

/// Leave out of a launch every variable the profile's harness must never see,
/// and name them for the worker, which removes them again once it has added
/// the target's own login environment.
///
/// Saying so once per profile is enough: the launch config is rebuilt for
/// every recovery check, and the variables do not change between them.
pub(super) fn exclude_harness_environment(
    profile_id: &str,
    profile: &mj_core::config::HarnessProfile,
    environment: &mut std::collections::BTreeMap<String, String>,
) -> Vec<String> {
    static REPORTED: std::sync::Mutex<std::collections::BTreeSet<String>> =
        std::sync::Mutex::new(std::collections::BTreeSet::new());
    let before = environment.clone();
    let excluded = profile.exclude_harness_environment(environment);
    let removed = excluded
        .iter()
        .filter(|name| before.contains_key(*name))
        .cloned()
        .collect::<Vec<_>>();
    if !removed.is_empty()
        && REPORTED
            .lock()
            .map(|mut reported| reported.insert(profile_id.to_owned()))
            .unwrap_or(true)
    {
        tracing::info!(
            profile_id,
            removed = removed.join(", "),
            "left API key settings out of the harness environment: this Codex profile must not use an OpenAI API key"
        );
    }
    excluded
}

pub(super) fn harness_runtime_policy(backend: &targets::TargetLocator) -> HarnessRuntimePolicy {
    match backend {
        targets::TargetLocator::LocalBare { .. }
        | targets::TargetLocator::AwsEc2 { .. }
        | targets::TargetLocator::SshBare { .. } => HarnessRuntimePolicy::Managed,
        _ => HarnessRuntimePolicy::Ambient,
    }
}