feat(desktop): add disable_local_spawn flag to prevent duplicate agent spawns

desktop/src-tauri/src/commands/agent_config_tests.rs

@@ -85,6 +85,7 @@ fn agent_record() -> ManagedAgentRecord {
         model: None,
         env_vars: Default::default(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: BackendKind::Local,

desktop/src-tauri/src/commands/agent_settings.rs

@@ -61,6 +61,50 @@ pub async fn set_managed_agent_start_on_app_launch(
     .map_err(|e| format!("spawn_blocking failed: {e}"))?
 }
 
+#[tauri::command]
+pub async fn set_managed_agent_disable_local_spawn(
+    pubkey: String,
+    disable_local_spawn: bool,
+    app: AppHandle,
+) -> Result<ManagedAgentSummary, String> {
+    tokio::task::spawn_blocking(move || {
+        let state = app.state::<AppState>();
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|error| error.to_string())?;
+        let mut records = load_managed_agents(&app)?;
+        let mut runtimes = state
+            .managed_agent_processes
+            .lock()
+            .map_err(|error| error.to_string())?;
+
+        let (sync_changed, exited_pubkeys) =
+            sync_managed_agent_processes(&mut records, &mut runtimes, &current_instance_id(&app));
+        if sync_changed {
+            save_managed_agents(&app, &records)?;
+        }
+        for pubkey in &exited_pubkeys {
+            state.clear_agent_session_caches(pubkey);
+        }
+
+        {
+            let record = find_managed_agent_mut(&mut records, &pubkey)?;
+            record.disable_local_spawn = disable_local_spawn;
+            record.updated_at = now_iso();
+        }
+
+        save_managed_agents(&app, &records)?;
+        let record = records
+            .iter()
+            .find(|record| record.pubkey == pubkey)
+            .ok_or_else(|| format!("agent {pubkey} not found"))?;
+        super::agents::summarize_from_disk(&app, record, &runtimes)
+    })
+    .await
+    .map_err(|e| format!("spawn_blocking failed: {e}"))?
+}
+
 #[tauri::command]
 pub async fn set_managed_agent_auto_restart(
     pubkey: String,

desktop/src-tauri/src/commands/agents.rs

@@ -685,6 +685,7 @@ pub async fn create_managed_agent(
             } else {
                 input.start_on_app_launch
             },
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: input.backend.clone(),

desktop/src-tauri/src/commands/agents_tests.rs

@@ -31,6 +31,7 @@ fn bare_agent_record(
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         runtime_pid: None,
         backend: BackendKind::Local,
         backend_agent_id: None,

desktop/src-tauri/src/commands/personas/delete_cascade_tests.rs

@@ -39,6 +39,7 @@ fn make_agent(
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         runtime_pid,
         backend: BackendKind::Local,
         backend_agent_id: None,

desktop/src-tauri/src/commands/personas/inbound/inbound_tests.rs

@@ -181,6 +181,7 @@ fn local_agent() -> ManagedAgentRecord {
         persona_source_version: Some("local-hash".to_string()),
         env_vars: BTreeMap::from([("API_KEY".to_string(), "localsecret".to_string())]),
         start_on_app_launch: true,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: Some(1234),
         backend: crate::managed_agents::BackendKind::Provider {

desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs

@@ -35,6 +35,7 @@ fn make_definition(slug: &str) -> ManagedAgentRecord {
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: false,
         runtime_pid: None,
         backend: BackendKind::Local,

desktop/src-tauri/src/commands/personas/snapshot/import.rs

@@ -622,6 +622,7 @@ pub async fn confirm_agent_snapshot_import(
             persona_source_version: None,
             env_vars: std::collections::BTreeMap::new(),
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: crate::managed_agents::BackendKind::Local,

desktop/src-tauri/src/commands/personas/snapshot/tests.rs

@@ -44,6 +44,7 @@ fn make_definition(slug: &str) -> ManagedAgentRecord {
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: false,
         runtime_pid: None,
         backend: BackendKind::Local,

desktop/src-tauri/src/commands/personas/update/name_propagation_tests.rs

@@ -27,6 +27,7 @@ fn agent(persona_id: &str, name: &str, display_name: Option<&str>) -> ManagedAge
         persona_source_version: None,
         env_vars: std::collections::BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: Default::default(),

desktop/src-tauri/src/commands/team_snapshot.rs

@@ -575,6 +575,7 @@ pub async fn confirm_team_snapshot_import(
             persona_source_version: None,
             env_vars: std::collections::BTreeMap::new(),
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: crate::managed_agents::BackendKind::Local,

desktop/src-tauri/src/commands/team_snapshot/tests.rs

@@ -202,6 +202,7 @@ fn team_export_with_instance_and_memory_level_uses_supplied_entries() {
         persona_source_version: None,
         env_vars: Default::default(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: crate::managed_agents::BackendKind::Local,

desktop/src-tauri/src/lib.rs

@@ -701,6 +701,7 @@ pub fn run() {
             stop_managed_agent,
             set_agent_managed_profiles,
             set_managed_agent_start_on_app_launch,
+            set_managed_agent_disable_local_spawn,
             set_managed_agent_auto_restart,
             delete_managed_agent,
             get_managed_agent_log,

desktop/src-tauri/src/managed_agents/agent_events.rs

@@ -186,6 +186,7 @@ mod tests {
             persona_source_version: Some("abc123".to_string()),
             env_vars: BTreeMap::from([("OPENAI_API_KEY".to_string(), "sk-secret".to_string())]),
             start_on_app_launch: true,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: Some(4242),
             backend: super::super::BackendKind::Provider {

desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs

@@ -385,6 +385,7 @@ mod tests {
             model: None,
             env_vars: std::collections::BTreeMap::new(),
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: crate::managed_agents::types::BackendKind::Local,

desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs

@@ -39,6 +39,7 @@ fn minimal_record() -> ManagedAgentRecord {
             m
         },
         start_on_app_launch: true,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: Some(12345), // MUST NOT appear
         backend: BackendKind::Provider {

desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs

@@ -84,6 +84,7 @@ fn test_record() -> ManagedAgentRecord {
         model: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: crate::managed_agents::types::BackendKind::Local,

desktop/src-tauri/src/managed_agents/discovery/tests.rs

@@ -232,6 +232,7 @@ fn record_with(
         provider: None,
         persona_source_version: None,
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: Default::default(),

desktop/src-tauri/src/managed_agents/effective_config/tests.rs

@@ -61,6 +61,7 @@ fn record(
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         runtime_pid: None,
         backend: BackendKind::Local,
         backend_agent_id: None,

desktop/src-tauri/src/managed_agents/global_config/tests.rs

@@ -321,6 +321,7 @@ fn bare_record() -> ManagedAgentRecord {
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         runtime_pid: None,
         backend: BackendKind::Local,
         backend_agent_id: None,

desktop/src-tauri/src/managed_agents/nest/render_tests.rs

@@ -57,6 +57,7 @@ fn make_agent(name: &str, persona_id: Option<&str>) -> ManagedAgentRecord {
         provider: None,
         persona_source_version: None,
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: BackendKind::default(),

desktop/src-tauri/src/managed_agents/parallelism.rs

@@ -85,6 +85,7 @@ mod tests {
             provider: None,
             persona_source_version: None,
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: Default::default(),

desktop/src-tauri/src/managed_agents/persona_events/tests.rs

@@ -27,6 +27,7 @@ pub(super) fn sample_record() -> ManagedAgentRecord {
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: BackendKind::Local,

desktop/src-tauri/src/managed_agents/readiness.rs

@@ -1498,6 +1498,7 @@ mod tests {
             persona_source_version: None,
             env_vars,
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: Default::default(),

desktop/src-tauri/src/managed_agents/restore.rs

@@ -167,7 +167,11 @@ pub async fn restore_managed_agents_on_launch(
 
         let candidates: Vec<String> = records
             .iter()
-            .filter(|record| record.start_on_app_launch && record.backend == BackendKind::Local)
+            .filter(|record| {
+                record.start_on_app_launch
+                    && record.backend == BackendKind::Local
+                    && !record.disable_local_spawn
+            })
             .map(|record| record.pubkey.clone())
             .collect();
 

desktop/src-tauri/src/managed_agents/runtime.rs

@@ -336,6 +336,7 @@ pub fn build_managed_agent_summary(
         last_error: record.last_error.clone(),
         last_error_code: record.last_error_code,
         start_on_app_launch: record.start_on_app_launch,
+        disable_local_spawn: record.disable_local_spawn,
         auto_restart_on_config_change: record.auto_restart_on_config_change,
         log_path,
         respond_to: record.respond_to,

desktop/src-tauri/src/managed_agents/runtime/test_fixtures.rs

@@ -58,6 +58,7 @@ pub(super) fn fixture(
         persona_source_version: None,
         env_vars: std::collections::BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: Default::default(),

desktop/src-tauri/src/managed_agents/runtime_commands.rs

@@ -260,6 +260,9 @@ fn start_pair(
     if record.backend != BackendKind::Local {
         return Err("managed runtime pairs require a local agent".into());
     }
+    if record.disable_local_spawn {
+        return Err("local spawn disabled — runtime is externally managed".into());
+    }
     if expected_updated_at.is_some_and(|expected| record.updated_at != expected) {
         return Err("managed agent changed while runtime reconciliation was in flight".into());
     }
@@ -468,7 +471,11 @@ pub async fn reconcile_managed_agent_runtimes(
     for community in communities {
         for record in records
             .iter()
-            .filter(|record| record.start_on_app_launch && record.backend == BackendKind::Local)
+            .filter(|record| {
+                record.start_on_app_launch
+                    && record.backend == BackendKind::Local
+                    && !record.disable_local_spawn
+            })
         // The legacy per-record relay pin is deliberately ignored here — see
         // `effective_agent_relay_url`. Every local auto-start agent fans out
         // to every configured community.

desktop/src-tauri/src/managed_agents/spawn_snapshot/tests.rs

@@ -64,6 +64,7 @@ fn record() -> ManagedAgentRecord {
         persona_source_version: None,
         env_vars: BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: true,
         runtime_pid: None,
         backend: Default::default(),

desktop/src-tauri/src/managed_agents/team_snapshot.rs

@@ -279,6 +279,7 @@ mod tests {
                 m
             },
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: BackendKind::Local,

desktop/src-tauri/src/managed_agents/teams_tests.rs

@@ -186,6 +186,7 @@ fn managed_agent(name: &str) -> ManagedAgentRecord {
         persona_source_version: None,
         env_vars: std::collections::BTreeMap::new(),
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: false,
         runtime_pid: None,
         backend: crate::managed_agents::BackendKind::Local,

desktop/src-tauri/src/managed_agents/types.rs

@@ -121,6 +121,7 @@ impl AgentDefinition {
             persona_source_version: None,
             env_vars: self.env_vars,
             start_on_app_launch: false,
+            disable_local_spawn: false,
             auto_restart_on_config_change: true,
             runtime_pid: None,
             backend: BackendKind::default(),
@@ -309,6 +310,13 @@ pub struct ManagedAgentRecord {
     pub env_vars: BTreeMap<String, String>,
     #[serde(default = "default_start_on_app_launch")]
     pub start_on_app_launch: bool,
+    /// When `true`, Desktop never spawns a local process for this agent — neither
+    /// at boot-time reconciliation nor on reactive triggers (channel open, @mention).
+    /// The persona and key remain in the store so the agent can be re-activated at
+    /// any time by flipping this back to `false`. Intended for agents whose canonical
+    /// runtime is an external host (e.g. a VPS systemd unit).
+    #[serde(default)]
+    pub disable_local_spawn: bool,
     /// Auto-restart this agent when its effective spawn config drifts from
     /// the running process (Chunk F). Default ON; the policy loop in the
     /// frontend only fires when the agent is idle, connected, and local.
@@ -550,6 +558,7 @@ pub struct ManagedAgentSummary {
     pub last_error: Option<String>,
     pub last_error_code: Option<i64>,
     pub start_on_app_launch: bool,
+    pub disable_local_spawn: bool,
     pub auto_restart_on_config_change: bool,
     pub log_path: String,
     pub respond_to: RespondTo,

desktop/src-tauri/src/managed_agents/types/tests.rs

@@ -755,6 +755,7 @@ fn summary_fixture(
         last_error: None,
         last_error_code: None,
         start_on_app_launch: false,
+        disable_local_spawn: false,
         auto_restart_on_config_change: false,
         log_path: String::new(),
         respond_to: RespondTo::OwnerOnly,

desktop/src/features/agents/hooks.ts

@@ -45,6 +45,7 @@ import type { HarnessDefinitionInput } from "@/shared/api/tauri";
 import { discoverAcpRuntimes } from "@/shared/api/tauriAcpDiscovery";
 import {
   setManagedAgentAutoRestart,
+  setManagedAgentDisableLocalSpawn,
   setManagedAgentStartOnAppLaunch,
   startManagedAgent,
   stopManagedAgent,
@@ -648,6 +649,24 @@ export function useSetManagedAgentStartOnAppLaunchMutation() {
   });
 }
 
+export function useSetManagedAgentDisableLocalSpawnMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      pubkey,
+      disableLocalSpawn,
+    }: {
+      pubkey: string;
+      disableLocalSpawn: boolean;
+    }) => setManagedAgentDisableLocalSpawn(pubkey, disableLocalSpawn),
+    onSettled: async () => {
+      await queryClient.invalidateQueries({ queryKey: managedAgentsQueryKey });
+      await queryClient.invalidateQueries({ queryKey: relayAgentsQueryKey });
+    },
+  });
+}
+
 export function useDeleteManagedAgentMutation() {
   const queryClient = useQueryClient();
 

desktop/src/features/agents/ui/ManagedAgentRow.tsx

@@ -261,7 +261,11 @@ function AgentSummary({
             <PubKey pubkey={agent.pubkey} />
             {agent.backend.type === "local" ? (
               <span>
-                {agent.startOnAppLaunch ? "Auto-start" : "Manual start"}
+                {agent.disableLocalSpawn
+                  ? "Remote runtime"
+                  : agent.startOnAppLaunch
+                    ? "Auto-start"
+                    : "Manual start"}
               </span>
             ) : (
               <span>Remote deployment</span>